1: \input texinfo
    2: @c %**start of header
    3: @setfilename coreutils.info
    4: @settitle @sc{gnu} Coreutils
    5: 
    6: @c %**end of header
    7: 
    8: @include version.texi
    9: @include constants.texi
   10: 
   11: @c Define new indices.
   12: @defcodeindex op
   13: @defcodeindex fl
   14: 
   15: @c Put everything in one index (arbitrarily chosen to be the concept index).
   16: @syncodeindex fl cp
   17: @syncodeindex fn cp
   18: @syncodeindex ky cp
   19: @syncodeindex op cp
   20: @syncodeindex pg cp
   21: @syncodeindex vr cp
   22: 
   23: @dircategory Basics
   24: @direntry
   25: * Coreutils: (coreutils).       Core GNU (file, text, shell) utilities.
   26: * Common options: (coreutils)Common options.      Common options.
   27: * File permissions: (coreutils)File permissions.  Access modes.
   28: * Date input formats: (coreutils)Date input formats.
   29: @end direntry
   30: 
   31: @c FIXME: the following need documentation
   32: @c * [: (coreutils)[ invocation.                   File/string tests.
   33: @c * pinky: (coreutils)pinky invocation.           FIXME.
   34: @c * uptime: (coreutils)uptime invocation.         FIXME.
   35: 
   36: @dircategory Individual utilities
   37: @direntry
   38: * base64: (coreutils)base64 invocation.         Base64 encode/decode data.
   39: * basename: (coreutils)basename invocation.     Strip directory and suffix.
   40: * cat: (coreutils)cat invocation.               Concatenate and write files.
   41: * chgrp: (coreutils)chgrp invocation.           Change file groups.
   42: * chmod: (coreutils)chmod invocation.           Change file permissions.
   43: * chown: (coreutils)chown invocation.           Change file owners/groups.
   44: * chroot: (coreutils)chroot invocation.         Specify the root directory.
   45: * cksum: (coreutils)cksum invocation.           Print POSIX CRC checksum.
   46: * comm: (coreutils)comm invocation.             Compare sorted files by line.
   47: * cp: (coreutils)cp invocation.                 Copy files.
   48: * csplit: (coreutils)csplit invocation.         Split by context.
   49: * cut: (coreutils)cut invocation.               Print selected parts of lines.
   50: * date: (coreutils)date invocation.             Print/set system date and time.
   51: * dd: (coreutils)dd invocation.                 Copy and convert a file.
   52: * df: (coreutils)df invocation.                 Report file system disk usage.
   53: * dir: (coreutils)dir invocation.               List directories briefly.
   54: * dircolors: (coreutils)dircolors invocation.   Color setup for ls.
   55: * dirname: (coreutils)dirname invocation.       Strip non-directory suffix.
   56: * du: (coreutils)du invocation.                 Report on disk usage.
   57: * echo: (coreutils)echo invocation.             Print a line of text.
   58: * env: (coreutils)env invocation.               Modify the environment.
   59: * expand: (coreutils)expand invocation.         Convert tabs to spaces.
   60: * expr: (coreutils)expr invocation.             Evaluate expressions.
   61: * factor: (coreutils)factor invocation.         Print prime factors
   62: * false: (coreutils)false invocation.           Do nothing, unsuccessfully.
   63: * fmt: (coreutils)fmt invocation.               Reformat paragraph text.
   64: * fold: (coreutils)fold invocation.             Wrap long input lines.
   65: * groups: (coreutils)groups invocation.         Print group names a user is in.
   66: * head: (coreutils)head invocation.             Output the first part of files.
   67: * hostid: (coreutils)hostid invocation.         Print numeric host identifier.
   68: * hostname: (coreutils)hostname invocation.     Print or set system name.
   69: * id: (coreutils)id invocation.                 Print user identity.
   70: * install: (coreutils)install invocation.       Copy and change attributes.
   71: * join: (coreutils)join invocation.             Join lines on a common field.
   72: * kill: (coreutils)kill invocation.             Send a signal to processes.
   73: * link: (coreutils)link invocation.             Make hard links between files.
   74: * ln: (coreutils)ln invocation.                 Make links between files.
   75: * logname: (coreutils)logname invocation.       Print current login name.
   76: * ls: (coreutils)ls invocation.                 List directory contents.
   77: * md5sum: (coreutils)md5sum invocation.         Print or check MD5 digests.
   78: * mkdir: (coreutils)mkdir invocation.           Create directories.
   79: * mkfifo: (coreutils)mkfifo invocation.         Create FIFOs (named pipes).
   80: * mknod: (coreutils)mknod invocation.           Create special files.
   81: * mv: (coreutils)mv invocation.                 Rename files.
   82: * nice: (coreutils)nice invocation.             Modify niceness.
   83: * nl: (coreutils)nl invocation.                 Number lines and write files.
   84: * nohup: (coreutils)nohup invocation.           Immunize to hangups.
   85: * od: (coreutils)od invocation.                 Dump files in octal, etc.
   86: * paste: (coreutils)paste invocation.           Merge lines of files.
   87: * pathchk: (coreutils)pathchk invocation.       Check file name portability.
   88: * pr: (coreutils)pr invocation.                 Paginate or columnate files.
   89: * printenv: (coreutils)printenv invocation.     Print environment variables.
   90: * printf: (coreutils)printf invocation.         Format and print data.
   91: * ptx: (coreutils)ptx invocation.               Produce permuted indexes.
   92: * pwd: (coreutils)pwd invocation.               Print working directory.
   93: * readlink: (coreutils)readlink invocation.     Print referent of a symlink.
   94: * rm: (coreutils)rm invocation.                 Remove files.
   95: * rmdir: (coreutils)rmdir invocation.           Remove empty directories.
   96: * seq: (coreutils)seq invocation.               Print numeric sequences
   97: * sha1sum: (coreutils)sha1sum invocation.       Print or check SHA-1 digests.
   98: * sha2: (coreutils)sha2 utilities.              Print or check SHA-2 digests.
   99: * shred: (coreutils)shred invocation.           Remove files more securely.
  100: * shuf: (coreutils)shuf invocation.             Shuffling text files.
  101: * sleep: (coreutils)sleep invocation.           Delay for a specified time.
  102: * sort: (coreutils)sort invocation.             Sort text files.
  103: * split: (coreutils)split invocation.           Split into fixed-size pieces.
  104: * stat: (coreutils)stat invocation.             Report file(system) status.
  105: * stty: (coreutils)stty invocation.             Print/change terminal settings.
  106: * su: (coreutils)su invocation.                 Modify user and group ID.
  107: * sum: (coreutils)sum invocation.               Print traditional checksum.
  108: * sync: (coreutils)sync invocation.             Synchronize memory and disk.
  109: * tac: (coreutils)tac invocation.               Reverse files.
  110: * tail: (coreutils)tail invocation.             Output the last part of files.
  111: * tee: (coreutils)tee invocation.               Redirect to multiple files.
  112: * test: (coreutils)test invocation.             File/string tests.
  113: * touch: (coreutils)touch invocation.           Change file timestamps.
  114: * tr: (coreutils)tr invocation.                 Translate characters.
  115: * true: (coreutils)true invocation.             Do nothing, successfully.
  116: * tsort: (coreutils)tsort invocation.           Topological sort.
  117: * tty: (coreutils)tty invocation.               Print terminal name.
  118: * uname: (coreutils)uname invocation.           Print system information.
  119: * unexpand: (coreutils)unexpand invocation.     Convert spaces to tabs.
  120: * uniq: (coreutils)uniq invocation.             Uniquify files.
  121: * unlink: (coreutils)unlink invocation.         Removal via unlink(2).
  122: * users: (coreutils)users invocation.           Print current user names.
  123: * vdir: (coreutils)vdir invocation.             List directories verbosely.
  124: * wc: (coreutils)wc invocation.                 Line, word, and byte counts.
  125: * who: (coreutils)who invocation.               Print who is logged in.
  126: * whoami: (coreutils)whoami invocation.         Print effective user ID.
  127: * yes: (coreutils)yes invocation.               Print a string indefinitely.
  128: @end direntry
  129: 
  130: @copying
  131: This manual documents version @value{VERSION} of the @sc{gnu} core
  132: utilities, including the standard programs for text and file manipulation.
  133: 
  134: Copyright @copyright{} 1994, 1995, 1996, 2000, 2001, 2002, 2003, 2004,
  135: 2005, 2006 Free Software Foundation, Inc.
  136: 
  137: @quotation
  138: Permission is granted to copy, distribute and/or modify this document
  139: under the terms of the GNU Free Documentation License, Version 1.2 or
  140: any later version published by the Free Software Foundation; with no
  141: Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  142: Texts.  A copy of the license is included in the section entitled ``GNU
  143: Free Documentation License''.
  144: @end quotation
  145: @end copying
  146: 
  147: @titlepage
  148: @title @sc{gnu} @code{Coreutils}
  149: @subtitle Core GNU utilities
  150: @subtitle for version @value{VERSION}, @value{UPDATED}
  151: @author David MacKenzie et al.
  152: 
  153: @page
  154: @vskip 0pt plus 1filll
  155: @insertcopying
  156: @end titlepage
  157: 
  158: 
  159: @ifnottex
  160: @node Top
  161: @top GNU Coreutils
  162: 
  163: @insertcopying
  164: @end ifnottex
  165: 
  166: @cindex core utilities
  167: @cindex text utilities
  168: @cindex shell utilities
  169: @cindex file utilities
  170: 
  171: @menu
  172: * Introduction::                       Caveats, overview, and authors.
  173: * Common options::                     Common options.
  174: * Output of entire files::             cat tac nl od
  175: * Formatting file contents::           fmt pr fold
  176: * Output of parts of files::           head tail split csplit
  177: * Summarizing files::                  wc sum cksum md5sum sha1sum sha2
  178: * Operating on sorted files::          sort shuf uniq comm ptx tsort
  179: * Operating on fields within a line::  cut paste join
  180: * Operating on characters::            tr expand unexpand
  181: * Directory listing::                  ls dir vdir dircolors
  182: * Basic operations::                   cp dd install mv rm shred
  183: * Special file types::                 ln mkdir rmdir mkfifo mknod
  184: * Changing file attributes::           chgrp chmod chown touch
  185: * Disk usage::                         df du stat sync
  186: * Printing text::                      echo printf yes
  187: * Conditions::                         false true test expr
  188: * Redirection::                        tee
  189: * File name manipulation::             dirname basename pathchk
  190: * Working context::                    pwd stty printenv tty
  191: * User information::                   id logname whoami groups users who
  192: * System context::                     date uname hostname hostid
  193: * Modified command invocation::        chroot env nice nohup su
  194: * Process control::                    kill
  195: * Delaying::                           sleep
  196: * Numeric operations::                 factor seq
  197: * File permissions::                   Access modes.
  198: * Date input formats::                 Specifying date strings.
  199: * Opening the software toolbox::       The software tools philosophy.
  200: * Copying This Manual::                License for copying this manual.
  201: * Index::                              General index.
  202: 
  203: @detailmenu
  204:  --- The Detailed Node Listing ---
  205: 
  206: Common Options
  207: 
  208: * Exit status::                 Indicating program success or failure.
  209: * Backup options::              Backup options
  210: * Block size::                  Block size
  211: * Disambiguating names and IDs:: chgrp and chown owner and group syntax
  212: * Random sources::              Sources of random data
  213: * Target directory::            Target directory
  214: * Trailing slashes::            Trailing slashes
  215: * Traversing symlinks::         Traversing symlinks to directories
  216: * Treating / specially::        Treating / specially
  217: * Standards conformance::       Standards conformance
  218: 
  219: Output of entire files
  220: 
  221: * cat invocation::              Concatenate and write files.
  222: * tac invocation::              Concatenate and write files in reverse.
  223: * nl invocation::               Number lines and write files.
  224: * od invocation::               Write files in octal or other formats.
  225: * base64 invocation::           Transform data into printable data.
  226: 
  227: Formatting file contents
  228: 
  229: * fmt invocation::              Reformat paragraph text.
  230: * pr invocation::               Paginate or columnate files for printing.
  231: * fold invocation::             Wrap input lines to fit in specified width.
  232: 
  233: Output of parts of files
  234: 
  235: * head invocation::             Output the first part of files.
  236: * tail invocation::             Output the last part of files.
  237: * split invocation::            Split a file into fixed-size pieces.
  238: * csplit invocation::           Split a file into context-determined pieces.
  239: 
  240: Summarizing files
  241: 
  242: * wc invocation::               Print newline, word, and byte counts.
  243: * sum invocation::              Print checksum and block counts.
  244: * cksum invocation::            Print CRC checksum and byte counts.
  245: * md5sum invocation::           Print or check MD5 digests.
  246: * sha1sum invocation::          Print or check SHA-1 digests.
  247: * sha2 utilities::              Print or check SHA-2 digests.
  248: 
  249: Operating on sorted files
  250: 
  251: * sort invocation::             Sort text files.
  252: * shuf invocation::             Shuffle text files.
  253: * uniq invocation::             Uniquify files.
  254: * comm invocation::             Compare two sorted files line by line.
  255: * ptx invocation::              Produce a permuted index of file contents.
  256: * tsort invocation::            Topological sort.
  257: 
  258: @command{ptx}: Produce permuted indexes
  259: 
  260: * General options in ptx::      Options which affect general program behavior.
  261: * Charset selection in ptx::    Underlying character set considerations.
  262: * Input processing in ptx::     Input fields, contexts, and keyword selection.
  263: * Output formatting in ptx::    Types of output format, and sizing the fields.
  264: * Compatibility in ptx::        The @acronym{GNU} extensions to @command{ptx}
  265: 
  266: Operating on fields within a line
  267: 
  268: * cut invocation::              Print selected parts of lines.
  269: * paste invocation::            Merge lines of files.
  270: * join invocation::             Join lines on a common field.
  271: 
  272: Operating on characters
  273: 
  274: * tr invocation::               Translate, squeeze, and/or delete characters.
  275: * expand invocation::           Convert tabs to spaces.
  276: * unexpand invocation::         Convert spaces to tabs.
  277: 
  278: @command{tr}: Translate, squeeze, and/or delete characters
  279: 
  280: * Character sets::              Specifying sets of characters.
  281: * Translating::                 Changing one set of characters to another.
  282: * Squeezing::                   Squeezing repeats and deleting.
  283: 
  284: Directory listing
  285: 
  286: * ls invocation::               List directory contents
  287: * dir invocation::              Briefly list directory contents
  288: * vdir invocation::             Verbosely list directory contents
  289: * dircolors invocation::        Color setup for @command{ls}
  290: 
  291: @command{ls}:  List directory contents
  292: 
  293: * Which files are listed::      Which files are listed
  294: * What information is listed::  What information is listed
  295: * Sorting the output::          Sorting the output
  296: * More details about version sort::  More details about version sort
  297: * General output formatting::   General output formatting
  298: * Formatting the file names::   Formatting the file names
  299: 
  300: Basic operations
  301: 
  302: * cp invocation::               Copy files and directories
  303: * dd invocation::               Convert and copy a file
  304: * install invocation::          Copy files and set attributes
  305: * mv invocation::               Move (rename) files
  306: * rm invocation::               Remove files or directories
  307: * shred invocation::            Remove files more securely
  308: 
  309: Special file types
  310: 
  311: * link invocation::             Make a hard link via the link syscall
  312: * ln invocation::               Make links between files
  313: * mkdir invocation::            Make directories
  314: * mkfifo invocation::           Make FIFOs (named pipes)
  315: * mknod invocation::            Make block or character special files
  316: * readlink invocation::         Print the referent of a symbolic link
  317: * rmdir invocation::            Remove empty directories
  318: * unlink invocation::           Remove files via unlink syscall
  319: 
  320: Changing file attributes
  321: 
  322: * chown invocation::            Change file owner and group
  323: * chgrp invocation::            Change group ownership
  324: * chmod invocation::            Change access permissions
  325: * touch invocation::            Change file timestamps
  326: 
  327: Disk usage
  328: 
  329: * df invocation::               Report file system disk space usage
  330: * du invocation::               Estimate file space usage
  331: * stat invocation::             Report file or file system status
  332: * sync invocation::             Synchronize data on disk with memory
  333: 
  334: Printing text
  335: 
  336: * echo invocation::             Print a line of text
  337: * printf invocation::           Format and print data
  338: * yes invocation::              Print a string until interrupted
  339: 
  340: Conditions
  341: 
  342: * false invocation::              Do nothing, unsuccessfully
  343: * true invocation::               Do nothing, successfully
  344: * test invocation::               Check file types and compare values
  345: * expr invocation::               Evaluate expressions
  346: 
  347: @command{test}: Check file types and compare values
  348: 
  349: * File type tests::               File type tests
  350: * Access permission tests::       Access permission tests
  351: * File characteristic tests::     File characteristic tests
  352: * String tests::                  String tests
  353: * Numeric tests::                 Numeric tests
  354: 
  355: @command{expr}: Evaluate expression
  356: 
  357: * String expressions::         + : match substr index length
  358: * Numeric expressions::        + - * / %
  359: * Relations for expr::         | & < <= = == != >= >
  360: * Examples of expr::           Examples of using @command{expr}
  361: 
  362: Redirection
  363: 
  364: * tee invocation::               Redirect output to multiple files
  365: 
  366: File name manipulation
  367: 
  368: * basename invocation::          Strip directory and suffix from a file name
  369: * dirname invocation::           Strip non-directory suffix from a file name
  370: * pathchk invocation::           Check file name portability
  371: 
  372: Working context
  373: 
  374: * pwd invocation::               Print working directory
  375: * stty invocation::              Print or change terminal characteristics
  376: * printenv invocation::          Print all or some environment variables
  377: * tty invocation::               Print file name of terminal on standard input
  378: 
  379: @command{stty}: Print or change terminal characteristics
  380: 
  381: * Control::                     Control settings
  382: * Input::                       Input settings
  383: * Output::                      Output settings
  384: * Local::                       Local settings
  385: * Combination::                 Combination settings
  386: * Characters::                  Special characters
  387: * Special::                     Special settings
  388: 
  389: User information
  390: 
  391: * id invocation::                Print user identity
  392: * logname invocation::           Print current login name
  393: * whoami invocation::            Print effective user ID
  394: * groups invocation::            Print group names a user is in
  395: * users invocation::             Print login names of users currently logged in
  396: * who invocation::               Print who is currently logged in
  397: 
  398: System context
  399: 
  400: * date invocation::              Print or set system date and time
  401: * uname invocation::             Print system information
  402: * hostname invocation::          Print or set system name
  403: * hostid invocation::            Print numeric host identifier.
  404: 
  405: @command{date}: Print or set system date and time
  406: 
  407: * Time conversion specifiers::   %[HIklMNpPrRsSTXzZ]
  408: * Date conversion specifiers::   %[aAbBcCdDeFgGhjmuUVwWxyY]
  409: * Literal conversion specifiers:: %[%nt]
  410: * Padding and other flags::      Pad with zeros, spaces, etc.
  411: * Setting the time::             Changing the system clock.
  412: * Options for date::             Instead of the current time.
  413: * Examples of date::             Examples.
  414: 
  415: Modified command invocation
  416: 
  417: * chroot invocation::            Run a command with a different root directory
  418: * env invocation::               Run a command in a modified environment
  419: * nice invocation::              Run a command with modified niceness
  420: * nohup invocation::             Run a command immune to hangups
  421: * su invocation::                Run a command with substitute user and group ID
  422: 
  423: Process control
  424: 
  425: * kill invocation::              Sending a signal to processes.
  426: 
  427: Delaying
  428: 
  429: * sleep invocation::             Delay for a specified time
  430: 
  431: Numeric operations
  432: 
  433: * factor invocation::            Print prime factors
  434: * seq invocation::               Print numeric sequences
  435: 
  436: File permissions
  437: 
  438: * Mode Structure::               Structure of file mode bits.
  439: * Symbolic Modes::               Mnemonic representation of file mode bits.
  440: * Numeric Modes::                File mode bits as octal numbers.
  441: * Directory Setuid and Setgid::  Set-user-ID and set-group-ID on directories.
  442: 
  443: Date input formats
  444: 
  445: * General date syntax::          Common rules.
  446: * Calendar date items::          19 Dec 1994.
  447: * Time of day items::            9:20pm.
  448: * Time zone items::              @sc{est}, @sc{pdt}, @sc{gmt}.
  449: * Day of week items::            Monday and others.
  450: * Relative items in date strings:: next tuesday, 2 years ago.
  451: * Pure numbers in date strings:: 19931219, 1440.
  452: * Seconds since the Epoch::      @@1078100502.
  453: * Specifying time zone rules::   TZ="America/New_York", TZ="UTC0".
  454: * Authors of get_date::          Bellovin, Eggert, Salz, Berets, et al.
  455: 
  456: Opening the software toolbox
  457: 
  458: * Toolbox introduction::         Toolbox introduction
  459: * I/O redirection::              I/O redirection
  460: * The who command::              The @command{who} command
  461: * The cut command::              The @command{cut} command
  462: * The sort command::             The @command{sort} command
  463: * The uniq command::             The @command{uniq} command
  464: * Putting the tools together::   Putting the tools together
  465: 
  466: Copying This Manual
  467: 
  468: * GNU Free Documentation License::  License for copying this manual.
  469: 
  470: @end detailmenu
  471: @end menu
  472: 
  473: 
  474: @node Introduction
  475: @chapter Introduction
  476: 
  477: This manual is a work in progress: many sections make no attempt to explain
  478: basic concepts in a way suitable for novices.  Thus, if you are interested,
  479: please get involved in improving this manual.  The entire @sc{gnu} community
  480: will benefit.
  481: 
  482: @cindex @acronym{POSIX}
  483: The @sc{gnu} utilities documented here are mostly compatible with the
  484: @acronym{POSIX} standard.
  485: @cindex bugs, reporting
  486: Please report bugs to @email{bug-coreutils@@gnu.org}.  Remember
  487: to include the version number, machine architecture, input files, and
  488: any other information needed to reproduce the bug: your input, what you
  489: expected, what you got, and why it is wrong.  Diffs are welcome, but
  490: please include a description of the problem as well, since this is
  491: sometimes difficult to infer.  @xref{Bugs, , , gcc, Using and Porting GNU CC}.
  492: 
  493: @cindex Berry, K.
  494: @cindex Paterson, R.
  495: @cindex Stallman, R.
  496: @cindex Pinard, F.
  497: @cindex MacKenzie, D.
  498: @cindex Meyering, J.
  499: @cindex Youmans, B.
  500: This manual was originally derived from the Unix man pages in the
  501: distributions, which were written by David MacKenzie and updated by Jim
  502: Meyering.  What you are reading now is the authoritative documentation
  503: for these utilities; the man pages are no longer being maintained.  The
  504: original @command{fmt} man page was written by Ross Paterson.  Fran@,{c}ois
  505: Pinard did the initial conversion to Texinfo format.  Karl Berry did the
  506: indexing, some reorganization, and editing of the results.  Brian
  507: Youmans of the Free Software Foundation office staff combined the
  508: manuals for textutils, fileutils, and sh-utils to produce the present
  509: omnibus manual.  Richard Stallman contributed his usual invaluable
  510: insights to the overall process.
  511: 
  512: @node Common options
  513: @chapter Common options
  514: 
  515: @macro optBackup
  516: @item -b
  517: @itemx @w{@kbd{--backup}[=@var{method}]}
  518: @opindex -b
  519: @opindex --backup
  520: @vindex VERSION_CONTROL
  521: @cindex backups, making
  522: @xref{Backup options}.
  523: Make a backup of each file that would otherwise be overwritten or removed.
  524: @end macro
  525: 
  526: @macro optBackupSuffix
  527: @item -S @var{suffix}
  528: @itemx --suffix=@var{suffix}
  529: @opindex -S
  530: @opindex --suffix
  531: Append @var{suffix} to each backup file made with @option{-b}.
  532: @xref{Backup options}.
  533: @end macro
  534: 
  535: @macro optTargetDirectory
  536: @item -t @var{directory}
  537: @itemx @w{@kbd{--target-directory}=@var{directory}}
  538: @opindex -t
  539: @opindex --target-directory
  540: @cindex target directory
  541: @cindex destination directory
  542: Specify the destination @var{directory}.
  543: @xref{Target directory}.
  544: @end macro
  545: 
  546: @macro optNoTargetDirectory
  547: @item -T
  548: @itemx --no-target-directory
  549: @opindex -T
  550: @opindex --no-target-directory
  551: @cindex target directory
  552: @cindex destination directory
  553: Do not treat the last operand specially when it is a directory or a
  554: symbolic link to a directory.  @xref{Target directory}.
  555: @end macro
  556: 
  557: @macro optSi
  558: @itemx --si
  559: @opindex --si
  560: @cindex SI output
  561: Append an SI-style abbreviation to each size, such as @samp{M} for
  562: megabytes.  Powers of 1000 are used, not 1024; @samp{M} stands for
  563: 1,000,000 bytes.  This option is equivalent to
  564: @option{--block-size=si}.  Use the @option{-h} or
  565: @option{--human-readable} option if
  566: you prefer powers of 1024.
  567: @end macro
  568: 
  569: @macro optHumanReadable
  570: @item -h
  571: @itemx --human-readable
  572: @opindex -h
  573: @opindex --human-readable
  574: @cindex human-readable output
  575: Append a size letter to each size, such as @samp{M} for mebibytes.
  576: Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes.
  577: Use the @option{--si} option if you prefer powers of 1000.
  578: @end macro
  579: 
  580: @macro optStripTrailingSlashes
  581: @itemx @w{@kbd{--strip-trailing-slashes}}
  582: @opindex --strip-trailing-slashes
  583: @cindex stripping trailing slashes
  584: Remove any trailing slashes from each @var{source} argument.
  585: @xref{Trailing slashes}.
  586: @end macro
  587: 
  588: @cindex common options
  589: 
  590: Certain options are available in all of these programs.  Rather than
  591: writing identical descriptions for each of the programs, they are
  592: described here.  (In fact, every @sc{gnu} program accepts (or should accept)
  593: these options.)
  594: 
  595: @vindex POSIXLY_CORRECT
  596: Normally options and operands can appear in any order, and programs act
  597: as if all the options appear before any operands.  For example,
  598: @samp{sort -r passwd -t :} acts like @samp{sort -r -t : passwd}, since
  599: @samp{:} is an option-argument of @option{-t}.  However, if the
  600: @env{POSIXLY_CORRECT} environment variable is set, options must appear
  601: before operands, unless otherwise specified for a particular command.
  602: 
  603: A few programs can usefully have trailing operands with leading
  604: @samp{-}.  With such a program, options must precede operands even if
  605: @env{POSIXLY_CORRECT} is not set, and this fact is noted in the
  606: program description.  For example, the @command{env} command's options
  607: must appear before its operands, since in some cases the operands
  608: specify a command that itself contains options.
  609: 
  610: Some of these programs recognize the @option{--help} and @option{--version}
  611: options only when one of them is the sole command line argument.
  612: 
  613: @table @samp
  614: 
  615: @item --help
  616: @opindex --help
  617: @cindex help, online
  618: Print a usage message listing all available options, then exit successfully.
  619: 
  620: @item --version
  621: @opindex --version
  622: @cindex version number, finding
  623: Print the version number, then exit successfully.
  624: 
  625: @item --
  626: @opindex --
  627: @cindex option delimiter
  628: Delimit the option list.  Later arguments, if any, are treated as
  629: operands even if they begin with @samp{-}.  For example, @samp{sort --
  630: -r} reads from the file named @file{-r}.
  631: 
  632: @end table
  633: 
  634: @cindex standard input
  635: @cindex standard output
  636: A single @samp{-} operand is not really an option, though it looks like one.  It
  637: stands for standard input, or for standard output if that is clear from
  638: the context.  For example, @samp{sort -} reads from standard input,
  639: and is equivalent to plain @samp{sort}, and @samp{tee -} writes an
  640: extra copy of its input to standard output.  Unless otherwise
  641: specified, @samp{-} can appear as any operand that requires a file
  642: name.
  643: 
  644: @menu
  645: * Exit status::                 Indicating program success or failure.
  646: * Backup options::              -b -S, in some programs.
  647: * Block size::                  BLOCK_SIZE and --block-size, in some programs.
  648: * Disambiguating names and IDs:: chgrp and chown owner and group syntax
  649: * Random sources::              --random-source, in some programs.
  650: * Target directory::            Specifying a target directory, in some programs.
  651: * Trailing slashes::            --strip-trailing-slashes, in some programs.
  652: * Traversing symlinks::         -H, -L, or -P, in some programs.
  653: * Treating / specially::        --preserve-root and --no-preserve-root.
  654: * Special built-in utilities::  @command{break}, @command{:}, @command{eval}, @dots{}
  655: * Standards conformance::       Conformance to the @acronym{POSIX} standard.
  656: @end menu
  657: 
  658: 
  659: @node Exit status
  660: @section Exit status
  661: 
  662: @macro exitstatus
  663: An exit status of zero indicates success,
  664: and a nonzero value indicates failure.
  665: @end macro
  666: 
  667: Nearly every command invocation yields an integral @dfn{exit status}
  668: that can be used to change how other commands work.
  669: For the vast majority of commands, an exit status of zero indicates
  670: success.  Failure is indicated by a nonzero value---typically
  671: @samp{1}, though it may differ on unusual platforms as @acronym{POSIX}
  672: requires only that it be nonzero.
  673: 
  674: However, some of the programs documented here do produce
  675: other exit status values and a few associate different
  676: meanings with the values @samp{0} and @samp{1}.
  677: Here are some of the exceptions:
  678: @command{chroot}, @command{env}, @command{expr},
  679: @command{nice}, @command{nohup}, @command{printenv},
  680: @command{sort}, @command{su}, @command{test}, @command{tty}.
  681: 
  682: 
  683: @node Backup options
  684: @section Backup options
  685: 
  686: @cindex backup options
  687: 
  688: Some @sc{gnu} programs (at least @command{cp}, @command{install},
  689: @command{ln}, and @command{mv}) optionally make backups of files
  690: before writing new versions.
  691: These options control the details of these backups.  The options are also
  692: briefly mentioned in the descriptions of the particular programs.
  693: 
  694: @table @samp
  695: 
  696: @item -b
  697: @itemx @w{@kbd{--backup}[=@var{method}]}
  698: @opindex -b
  699: @opindex --backup
  700: @vindex VERSION_CONTROL
  701: @cindex backups, making
  702: Make a backup of each file that would otherwise be overwritten or removed.
  703: Without this option, the original versions are destroyed.
  704: Use @var{method} to determine the type of backups to make.
  705: When this option is used but @var{method} is not specified,
  706: then the value of the @env{VERSION_CONTROL}
  707: environment variable is used.  And if @env{VERSION_CONTROL} is not set,
  708: the default backup type is @samp{existing}.
  709: 
  710: Note that the short form of this option, @option{-b} does not accept any
  711: argument.  Using @option{-b} is equivalent to using @option{--backup=existing}.
  712: 
  713: @vindex version-control @r{Emacs variable}
  714: This option corresponds to the Emacs variable @samp{version-control};
  715: the values for @var{method} are the same as those used in Emacs.
  716: This option also accepts more descriptive names.
  717: The valid @var{method}s are (unique abbreviations are accepted):
  718: 
  719: @table @samp
  720: @item none
  721: @itemx off
  722: @opindex none @r{backup method}
  723: Never make backups.
  724: 
  725: @item numbered
  726: