@c FIXME: the following need documentation
@c * [: (coreutils)[ invocation. File/string tests.
@c * pinky: (coreutils)pinky invocation. FIXME.
-@c * mktemp: (coreutils)mktemp invocation. FIXME.
@dircategory Individual utilities
@direntry
* df: (coreutils)df invocation. Report file system disk usage.
* dir: (coreutils)dir invocation. List directories briefly.
* dircolors: (coreutils)dircolors invocation. Color setup for ls.
-* dirname: (coreutils)dirname invocation. Strip non-directory suffix.
+* dirname: (coreutils)dirname invocation. Strip last file name component.
* du: (coreutils)du invocation. Report on disk usage.
* echo: (coreutils)echo invocation. Print a line of text.
* env: (coreutils)env invocation. Modify the environment.
* mkdir: (coreutils)mkdir invocation. Create directories.
* mkfifo: (coreutils)mkfifo invocation. Create FIFOs (named pipes).
* mknod: (coreutils)mknod invocation. Create special files.
+* mktemp: (coreutils)mktemp invocation. Create temporary files.
* mv: (coreutils)mv invocation. Rename files.
* nice: (coreutils)nice invocation. Modify niceness.
* nl: (coreutils)nl invocation. Number lines and write files.
* nohup: (coreutils)nohup invocation. Immunize to hangups.
+* nproc: (coreutils)nproc invocation. Print the number of processors.
* od: (coreutils)od invocation. Dump files in octal, etc.
* paste: (coreutils)paste invocation. Merge lines of files.
* pathchk: (coreutils)pathchk invocation. Check file name portability.
* shuf: (coreutils)shuf invocation. Shuffling text files.
* sleep: (coreutils)sleep invocation. Delay for a specified time.
* sort: (coreutils)sort invocation. Sort text files.
-* split: (coreutils)split invocation. Split into fixed-size pieces.
+* split: (coreutils)split invocation. Split into pieces.
* stat: (coreutils)stat invocation. Report file(system) status.
* stdbuf: (coreutils)stdbuf invocation. Modify stdio buffering.
* stty: (coreutils)stty invocation. Print/change terminal settings.
This manual documents version @value{VERSION} of the @sc{gnu} core
utilities, including the standard programs for text and file manipulation.
-Copyright @copyright{} 1994-1996, 2000-2009 Free Software Foundation, Inc.
+Copyright @copyright{} 1994-1996, 2000-2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@cindex file utilities
@menu
-* Introduction:: Caveats, overview, and authors.
-* Common options:: Common options.
-* Output of entire files:: cat tac nl od
-* Formatting file contents:: fmt pr fold
-* Output of parts of files:: head tail split csplit
-* Summarizing files:: wc sum cksum md5sum sha1sum sha2
-* Operating on sorted files:: sort shuf uniq comm ptx tsort
-* Operating on fields within a line:: cut paste join
-* Operating on characters:: tr expand unexpand
-* Directory listing:: ls dir vdir dircolors
-* Basic operations:: cp dd install mv rm shred
-* Special file types:: ln mkdir rmdir mkfifo mknod
-* Changing file attributes:: chgrp chmod chown touch
-* Disk usage:: df du stat sync truncate
-* Printing text:: echo printf yes
-* Conditions:: false true test expr
-* Redirection:: tee
-* File name manipulation:: dirname basename pathchk
-* Working context:: pwd stty printenv tty
-* User information:: id logname whoami groups users who
-* System context:: date uname hostname hostid uptime
-* SELinux context:: chcon runcon
-* Modified command invocation:: chroot env nice nohup stdbuf su timeout
-* Process control:: kill
-* Delaying:: sleep
-* Numeric operations:: factor seq
-* File permissions:: Access modes.
-* Date input formats:: Specifying date strings.
-* Opening the software toolbox:: The software tools philosophy.
-* GNU Free Documentation License:: Copying and sharing this manual.
-* Concept index:: General index.
+* Introduction:: Caveats, overview, and authors
+* Common options:: Common options
+* Output of entire files:: cat tac nl od base64
+* Formatting file contents:: fmt pr fold
+* Output of parts of files:: head tail split csplit
+* Summarizing files:: wc sum cksum md5sum sha1sum sha2
+* Operating on sorted files:: sort shuf uniq comm ptx tsort
+* Operating on fields:: cut paste join
+* Operating on characters:: tr expand unexpand
+* Directory listing:: ls dir vdir dircolors
+* Basic operations:: cp dd install mv rm shred
+* Special file types:: mkdir rmdir unlink mkfifo mknod ln link readlink
+* Changing file attributes:: chgrp chmod chown touch
+* Disk usage:: df du stat sync truncate
+* Printing text:: echo printf yes
+* Conditions:: false true test expr
+* Redirection:: tee
+* File name manipulation:: dirname basename pathchk mktemp
+* Working context:: pwd stty printenv tty
+* User information:: id logname whoami groups users who
+* System context:: date arch nproc uname hostname hostid uptime
+* SELinux context:: chcon runcon
+* Modified command invocation:: chroot env nice nohup stdbuf su timeout
+* Process control:: kill
+* Delaying:: sleep
+* Numeric operations:: factor seq
+* File permissions:: Access modes
+* Date input formats:: Specifying date strings
+* Opening the software toolbox:: The software tools philosophy
+* GNU Free Documentation License:: Copying and sharing this manual
+* Concept index:: General index
@detailmenu
--- The Detailed Node Listing ---
Common Options
-* Exit status:: Indicating program success or failure.
-* Backup options:: Backup options
-* Block size:: Block size
-* Signal specifications:: Specifying signals
+* Exit status:: Indicating program success or failure
+* Backup options:: Backup options
+* Block size:: Block size
+* Floating point:: Floating point number representation
+* Signal specifications:: Specifying signals
* Disambiguating names and IDs:: chgrp and chown owner and group syntax
-* Random sources:: Sources of random data
-* Target directory:: Target directory
-* Trailing slashes:: Trailing slashes
-* Traversing symlinks:: Traversing symlinks to directories
-* Treating / specially:: Treating / specially
-* Standards conformance:: Standards conformance
+* Random sources:: Sources of random data
+* Target directory:: Target directory
+* Trailing slashes:: Trailing slashes
+* Traversing symlinks:: Traversing symlinks to directories
+* Treating / specially:: Treating / specially
+* Standards conformance:: Standards conformance
Output of entire files
-* cat invocation:: Concatenate and write files.
-* tac invocation:: Concatenate and write files in reverse.
-* nl invocation:: Number lines and write files.
-* od invocation:: Write files in octal or other formats.
-* base64 invocation:: Transform data into printable data.
+* cat invocation:: Concatenate and write files
+* tac invocation:: Concatenate and write files in reverse
+* nl invocation:: Number lines and write files
+* od invocation:: Write files in octal or other formats
+* base64 invocation:: Transform data into printable data
Formatting file contents
-* fmt invocation:: Reformat paragraph text.
-* pr invocation:: Paginate or columnate files for printing.
-* fold invocation:: Wrap input lines to fit in specified width.
+* fmt invocation:: Reformat paragraph text
+* pr invocation:: Paginate or columnate files for printing
+* fold invocation:: Wrap input lines to fit in specified width
Output of parts of files
-* head invocation:: Output the first part of files.
-* tail invocation:: Output the last part of files.
-* split invocation:: Split a file into fixed-size pieces.
-* csplit invocation:: Split a file into context-determined pieces.
+* head invocation:: Output the first part of files
+* tail invocation:: Output the last part of files
+* split invocation:: Split a file into fixed-size pieces
+* csplit invocation:: Split a file into context-determined pieces
Summarizing files
-* wc invocation:: Print newline, word, and byte counts.
-* sum invocation:: Print checksum and block counts.
-* cksum invocation:: Print CRC checksum and byte counts.
-* md5sum invocation:: Print or check MD5 digests.
-* sha1sum invocation:: Print or check SHA-1 digests.
-* sha2 utilities:: Print or check SHA-2 digests.
+* wc invocation:: Print newline, word, and byte counts
+* sum invocation:: Print checksum and block counts
+* cksum invocation:: Print CRC checksum and byte counts
+* md5sum invocation:: Print or check MD5 digests
+* sha1sum invocation:: Print or check SHA-1 digests
+* sha2 utilities:: Print or check SHA-2 digests
Operating on sorted files
-* sort invocation:: Sort text files.
-* shuf invocation:: Shuffle text files.
-* uniq invocation:: Uniquify files.
-* comm invocation:: Compare two sorted files line by line.
-* ptx invocation:: Produce a permuted index of file contents.
-* tsort invocation:: Topological sort.
+* sort invocation:: Sort text files
+* shuf invocation:: Shuffle text files
+* uniq invocation:: Uniquify files
+* comm invocation:: Compare two sorted files line by line
+* ptx invocation:: Produce a permuted index of file contents
+* tsort invocation:: Topological sort
@command{ptx}: Produce permuted indexes
-* General options in ptx:: Options which affect general program behavior.
-* Charset selection in ptx:: Underlying character set considerations.
-* Input processing in ptx:: Input fields, contexts, and keyword selection.
-* Output formatting in ptx:: Types of output format, and sizing the fields.
-* Compatibility in ptx:: The @acronym{GNU} extensions to @command{ptx}
+* General options in ptx:: Options which affect general program behavior
+* Charset selection in ptx:: Underlying character set considerations
+* Input processing in ptx:: Input fields, contexts, and keyword selection
+* Output formatting in ptx:: Types of output format, and sizing the fields
+* Compatibility in ptx:: The @acronym{GNU} extensions to @command{ptx}
-Operating on fields within a line
+Operating on fields
-* cut invocation:: Print selected parts of lines.
-* paste invocation:: Merge lines of files.
-* join invocation:: Join lines on a common field.
+* cut invocation:: Print selected parts of lines
+* paste invocation:: Merge lines of files
+* join invocation:: Join lines on a common field
Operating on characters
-* tr invocation:: Translate, squeeze, and/or delete characters.
-* expand invocation:: Convert tabs to spaces.
-* unexpand invocation:: Convert spaces to tabs.
+* tr invocation:: Translate, squeeze, and/or delete characters
+* expand invocation:: Convert tabs to spaces
+* unexpand invocation:: Convert spaces to tabs
@command{tr}: Translate, squeeze, and/or delete characters
-* Character sets:: Specifying sets of characters.
-* Translating:: Changing one set of characters to another.
-* Squeezing:: Squeezing repeats and deleting.
+* Character sets:: Specifying sets of characters
+* Translating:: Changing one set of characters to another
+* Squeezing:: Squeezing repeats and deleting
Directory listing
-* ls invocation:: List directory contents
-* dir invocation:: Briefly list directory contents
-* vdir invocation:: Verbosely list directory contents
-* dircolors invocation:: Color setup for @command{ls}
+* ls invocation:: List directory contents
+* dir invocation:: Briefly list directory contents
+* vdir invocation:: Verbosely list directory contents
+* dircolors invocation:: Color setup for @command{ls}
@command{ls}: List directory contents
-* Which files are listed:: Which files are listed
-* What information is listed:: What information is listed
-* Sorting the output:: Sorting the output
-* More details about version sort:: More details about version sort
-* General output formatting:: General output formatting
-* Formatting the file names:: Formatting the file names
+* Which files are listed:: Which files are listed
+* What information is listed:: What information is listed
+* Sorting the output:: Sorting the output
+* Details about version sort:: More details about version sort
+* General output formatting:: General output formatting
+* Formatting the file names:: Formatting the file names
Basic operations
-* cp invocation:: Copy files and directories
-* dd invocation:: Convert and copy a file
-* install invocation:: Copy files and set attributes
-* mv invocation:: Move (rename) files
-* rm invocation:: Remove files or directories
-* shred invocation:: Remove files more securely
+* cp invocation:: Copy files and directories
+* dd invocation:: Convert and copy a file
+* install invocation:: Copy files and set attributes
+* mv invocation:: Move (rename) files
+* rm invocation:: Remove files or directories
+* shred invocation:: Remove files more securely
Special file types
-* link invocation:: Make a hard link via the link syscall
-* ln invocation:: Make links between files
-* mkdir invocation:: Make directories
-* mkfifo invocation:: Make FIFOs (named pipes)
-* mknod invocation:: Make block or character special files
-* readlink invocation:: Print value of a symlink or canonical file name
-* rmdir invocation:: Remove empty directories
-* unlink invocation:: Remove files via unlink syscall
+* link invocation:: Make a hard link via the link syscall
+* ln invocation:: Make links between files
+* mkdir invocation:: Make directories
+* mkfifo invocation:: Make FIFOs (named pipes)
+* mknod invocation:: Make block or character special files
+* readlink invocation:: Print value of a symlink or canonical file name
+* rmdir invocation:: Remove empty directories
+* unlink invocation:: Remove files via unlink syscall
Changing file attributes
-* chown invocation:: Change file owner and group
-* chgrp invocation:: Change group ownership
-* chmod invocation:: Change access permissions
-* touch invocation:: Change file timestamps
+* chown invocation:: Change file owner and group
+* chgrp invocation:: Change group ownership
+* chmod invocation:: Change access permissions
+* touch invocation:: Change file timestamps
Disk usage
-* df invocation:: Report file system disk space usage
-* du invocation:: Estimate file space usage
-* stat invocation:: Report file or file system status
-* sync invocation:: Synchronize data on disk with memory
-* truncate invocation:: Shrink or extend the size of a file
+* df invocation:: Report file system disk space usage
+* du invocation:: Estimate file space usage
+* stat invocation:: Report file or file system status
+* sync invocation:: Synchronize data on disk with memory
+* truncate invocation:: Shrink or extend the size of a file
Printing text
-* echo invocation:: Print a line of text
-* printf invocation:: Format and print data
-* yes invocation:: Print a string until interrupted
+* echo invocation:: Print a line of text
+* printf invocation:: Format and print data
+* yes invocation:: Print a string until interrupted
Conditions
-* false invocation:: Do nothing, unsuccessfully
-* true invocation:: Do nothing, successfully
-* test invocation:: Check file types and compare values
-* expr invocation:: Evaluate expressions
+* false invocation:: Do nothing, unsuccessfully
+* true invocation:: Do nothing, successfully
+* test invocation:: Check file types and compare values
+* expr invocation:: Evaluate expressions
@command{test}: Check file types and compare values
-* File type tests:: File type tests
-* Access permission tests:: Access permission tests
-* File characteristic tests:: File characteristic tests
-* String tests:: String tests
-* Numeric tests:: Numeric tests
+* File type tests:: File type tests
+* Access permission tests:: Access permission tests
+* File characteristic tests:: File characteristic tests
+* String tests:: String tests
+* Numeric tests:: Numeric tests
@command{expr}: Evaluate expression
-* String expressions:: + : match substr index length
-* Numeric expressions:: + - * / %
-* Relations for expr:: | & < <= = == != >= >
-* Examples of expr:: Examples of using @command{expr}
+* String expressions:: + : match substr index length
+* Numeric expressions:: + - * / %
+* Relations for expr:: | & < <= = == != >= >
+* Examples of expr:: Examples of using @command{expr}
Redirection
File name manipulation
* basename invocation:: Strip directory and suffix from a file name
-* dirname invocation:: Strip non-directory suffix from a file name
+* dirname invocation:: Strip last file name component
* pathchk invocation:: Check file name validity and portability
+* mktemp invocation:: Create temporary file or directory
Working context
@command{stty}: Print or change terminal characteristics
-* Control:: Control settings
-* Input:: Input settings
-* Output:: Output settings
-* Local:: Local settings
-* Combination:: Combination settings
-* Characters:: Special characters
-* Special:: Special settings
+* Control:: Control settings
+* Input:: Input settings
+* Output:: Output settings
+* Local:: Local settings
+* Combination:: Combination settings
+* Characters:: Special characters
+* Special:: Special settings
User information
* arch invocation:: Print machine hardware name
* date invocation:: Print or set system date and time
+* nproc invocation:: Print the number of processors
* uname invocation:: Print system information
* hostname invocation:: Print or set system name
* hostid invocation:: Print numeric host identifier
* Date conversion specifiers:: %[aAbBcCdDeFgGhjmuUVwWxyY]
* Literal conversion specifiers:: %[%nt]
* Padding and other flags:: Pad with zeros, spaces, etc.
-* Setting the time:: Changing the system clock.
-* Options for date:: Instead of the current time.
-* Date input formats:: Specifying date strings.
-* Examples of date:: Examples.
+* Setting the time:: Changing the system clock
+* Options for date:: Instead of the current time
+* Date input formats:: Specifying date strings
+* Examples of date:: Examples
SELinux context
File permissions
-* Mode Structure:: Structure of file mode bits.
-* Symbolic Modes:: Mnemonic representation of file mode bits.
-* Numeric Modes:: File mode bits as octal numbers.
-* Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories.
+* Mode Structure:: Structure of file mode bits
+* Symbolic Modes:: Mnemonic representation of file mode bits
+* Numeric Modes:: File mode bits as octal numbers
+* Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories
Date input formats
-* General date syntax:: Common rules.
-* Calendar date items:: 19 Dec 1994.
-* Time of day items:: 9:20pm.
-* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
-* Day of week items:: Monday and others.
-* Relative items in date strings:: next tuesday, 2 years ago.
-* Pure numbers in date strings:: 19931219, 1440.
-* Seconds since the Epoch:: @@1078100502.
-* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
-* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
+* General date syntax:: Common rules
+* Calendar date items:: 19 Dec 1994
+* Time of day items:: 9:20pm
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}
+* Day of week items:: Monday and others
+* Relative items in date strings:: next tuesday, 2 years ago
+* Pure numbers in date strings:: 19931219, 1440
+* Seconds since the Epoch:: @@1078100502
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0"
+* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al
Opening the software toolbox
Copying This Manual
-* GNU Free Documentation License:: Copying and sharing this manual.
+* GNU Free Documentation License:: Copying and sharing this manual
@end detailmenu
@end menu
symbolic link to a directory. @xref{Target directory}.
@end macro
+@macro optNull{cmd}
+@item -0
+@opindex -0
+@itemx --null
+@opindex --null
+@cindex output @sc{nul}-byte-terminated lines
+Output a zero byte (@acronym{ASCII} @sc{nul}) at the end of each line,
+rather than a newline. This option enables other programs to parse the
+output of @command{\cmd\} even when that output would contain data
+with embedded newlines.
+@end macro
+
@macro optSi
@itemx --si
@opindex --si
@macro mayConflictWithShellBuiltIn{cmd}
@cindex conflicts with shell built-ins
@cindex built-in shell commands, conflicts with
-Due to shell aliases and built-in @command{\cmd\} command, using an
+Due to shell aliases and built-in @command{\cmd\} functions, using an
unadorned @command{\cmd\} interactively or in a script may get you
different functionality than that described here. Invoke it via
@command{env} (i.e., @code{env \cmd\ @dots{}}) to avoid interference
@end macro
@macro multiplierSuffixes{varName}
-@ignore
-Appending @samp{b} multiplies @var{\varName\} by 512,
-@samp{kB} by 1000, @samp{K} by 1024,
-@samp{MB} by 1000*1000, @samp{M} by 1024*1024,
-@samp{GB} by 1000*1000*1000, @samp{G} by 1024*1024*1024,
-and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
-@end ignore
-@var{\varName\} is a number which may have one of the following
-multiplicative suffixes:
+@var{\varName\} may be, or may be an integer optionally followed by,
+one of the following multiplicative suffixes:
@example
@samp{b} => 512 ("blocks")
@samp{KB} => 1000 (KiloBytes)
@c FIXME: same as above, but no ``blocks'' line.
@macro multiplierSuffixesNoBlocks{varName}
-@var{\varName\} is a number which may have one of the following
-multiplicative suffixes:
+@var{\varName\} may be, or may be an integer optionally followed by,
+one of the following multiplicative suffixes:
@example
@samp{KB} => 1000 (KiloBytes)
@samp{K} => 1024 (KibiBytes)
* Exit status:: Indicating program success or failure.
* Backup options:: -b -S, in some programs.
* Block size:: BLOCK_SIZE and --block-size, in some programs.
+* Floating point:: Floating point number representation.
* Signal specifications:: Specifying signals using the --signal option.
* Disambiguating names and IDs:: chgrp and chown owner and group syntax
* Random sources:: --random-source, in some programs.
* Trailing slashes:: --strip-trailing-slashes, in some programs.
* Traversing symlinks:: -H, -L, or -P, in some programs.
* Treating / specially:: --preserve-root and --no-preserve-root.
-* Special built-in utilities:: @command{break}, @command{:}, @command{eval}, @dots{}
+* Special built-in utilities:: @command{break}, @command{:}, @dots{}
* Standards conformance:: Conformance to the @acronym{POSIX} standard.
@end menu
other exit status values and a few associate different
meanings with the values @samp{0} and @samp{1}.
Here are some of the exceptions:
-@command{chroot}, @command{env}, @command{expr},
-@command{nice}, @command{nohup}, @command{printenv}, @command{sort},
+@command{chroot}, @command{env}, @command{expr}, @command{nice},
+@command{nohup}, @command{printenv}, @command{sort}, @command{stdbuf},
@command{su}, @command{test}, @command{timeout}, @command{tty}.
@option{--block-size=human-readable}. The @option{--si} option is
equivalent to @option{--block-size=si}.
+@node Floating point
+@section Floating point numbers
+@cindex floating point
+@cindex IEEE floating point
+
+Commands that accept or produce floating point numbers employ the
+floating point representation of the underlying system, and suffer
+from rounding error, overflow, and similar floating-point issues.
+Almost all modern systems use IEEE-754 floating point, and it is
+typically portable to assume IEEE-754 behavior these days. IEEE-754
+has positive and negative infinity, distinguishes positive from
+negative zero, and uses special values called NaNs to represent
+invalid computations such as dividing zero by itself. For more
+information, please see David Goldberg's paper
+@uref{http://@/www.validlab.com/@/goldberg/@/paper.pdf, What Every
+Computer Scientist Should Know About Floating-Point Arithmetic}.
+
+@vindex LC_NUMERIC
+Commands that accept floating point numbers as options, operands or
+input use the standard C functions @code{strtod} and @code{strtold} to
+convert from text to floating point numbers. These floating point
+numbers therefore can use scientific notation like @code{1.0e-34} and
+@code{-10e100}. Modern C implementations also accept hexadecimal
+floating point numbers such as @code{-0x.ep-3}, which stands for
+@minus{}14/16 times @math{2^-3}, which equals @minus{}0.109375. The
+@env{LC_NUMERIC} locale determines the decimal-point character.
+@xref{Parsing of Floats,,, libc, The GNU C Library Reference Manual}.
+
@node Signal specifications
@section Signal specifications
@cindex signals, specifying
@macro choptH
@item -H
@opindex -H
-@cindex symbolic link to directory, traverse each that is specified on the command line
+@cindex symbolic link to directory, traverse if on the command line
If @option{--recursive} (@option{-R}) is specified and
a command line argument is a symbolic link to a directory, traverse it.
@end macro
that is standard for your system. To cause them to conform to a
different version of @acronym{POSIX}, define the @env{_POSIX2_VERSION}
environment variable to a value of the form @var{yyyymm} specifying
-the year and month the standard was adopted. Two values are currently
+the year and month the standard was adopted. Three values are currently
supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
-@acronym{POSIX} 1003.2-1992, and @samp{200112} stands for @acronym{POSIX}
-1003.1-2001. For example, if you have a newer system but are running software
+@acronym{POSIX} 1003.2-1992, @samp{200112} stands for @acronym{POSIX}
+1003.1-2001, and @samp{200809} stands for @acronym{POSIX} 1003.1-2008.
+For example, if you have a newer system but are running software
that assumes an older version of @acronym{POSIX} and uses @samp{sort +1}
or @samp{tail +10}, you can work around any compatibility problems by setting
@samp{_POSIX2_VERSION=199209} in your environment.
@itemx --number
@opindex -n
@opindex --number
-Number all output lines, starting with 1.
+Number all output lines, starting with 1. This option is ignored
+if @option{-b} is in effect.
@item -s
@itemx --squeeze-blank
Analogous to @option{--body-numbering}.
@item -i @var{number}
-@itemx --page-increment=@var{number}
+@itemx --line-increment=@var{number}
@opindex -i
-@opindex --page-increment
+@opindex --line-increment
Increment line numbers by @var{number} (default 1).
@item -l @var{number}
@smallexample
od [@var{option}]@dots{} [@var{file}]@dots{}
od [-abcdfilosx]@dots{} [@var{file}] [[+]@var{offset}[.][b]]
-od [@var{option}]@dots{} --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
+od [@var{option}]@dots{} --traditional [@var{file}]@c
+ [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
@end smallexample
Each line of output consists of the offset in the input, followed by
Instead of the normal output, output only @dfn{string constants}: at
least @var{bytes} consecutive @acronym{ASCII} graphic characters,
followed by a zero byte (@acronym{ASCII} @sc{nul}).
-Prefixes and suffixes on @code{bytes} are interpreted as for the
+Prefixes and suffixes on @var{bytes} are interpreted as for the
@option{-j} option.
If @var{n} is omitted with @option{--strings}, the default is 3.
@item d
signed decimal
@item f
-floating point
+floating point (@pxref{Floating point})
@item o
octal
@item u
@table @samp
-@item -C
-@itemx --compare
-@opindex -C
-@opindex --compare
-Compare each pair of source and destination files, and if the destination has
-identical content and any specified owner, group, permissions, and possibly
-SELinux context, then do not modify the destination at all.
-
@item -c
@itemx --crown-margin
@opindex -c
@menu
* head invocation:: Output the first part of files.
* tail invocation:: Output the last part of files.
-* split invocation:: Split a file into fixed-size pieces.
+* split invocation:: Split a file into pieces.
* csplit invocation:: Split a file into context-determined pieces.
@end menu
it has been unlinked, use @option{--follow=descriptor}. This is the default
behavior, but it is not useful if you're tracking a log file that may be
rotated (removed or renamed, then reopened). In that case, use
-@option{--follow=name} to track the named file by reopening it periodically
-to see if it has been removed and recreated by some other program.
+@option{--follow=name} to track the named file, perhaps by reopening it
+periodically to see if it has been removed and recreated by some other program.
+Note that the inotify-based implementation handles this case without
+the need for any periodic reopening.
No matter which method you use, if the tracked file is determined to have
shrunk, @command{tail} prints a message saying the file has been truncated
The option values @samp{descriptor} and @samp{name} may be specified only
with the long form of the option, not with @option{-f}.
-@vindex POSIXLY_CORRECT
-If @env{POSIXLY_CORRECT} is set, the @option{-f} option is ignored if
+The @option{-f} option is ignored if
no @var{file} operand is specified and standard input is a FIFO or a pipe.
+Likewise, the @option{-f} option has no effect for any
+operand specified as @samp{-}, when standard input is a FIFO or a pipe.
+
+With kernel inotify support, output is asynchronous and generally very prompt.
+Otherwise, @command{tail} sleeps for one second between checks---
+use @option{--sleep-interval=@var{N}} to change that default---which can
+make the output appear slightly less responsive or bursty.
@item -F
@opindex -F
changed size.
Historical implementations of @command{tail} have required that
@var{number} be an integer. However, GNU @command{tail} accepts
-an arbitrary floating point number (using a period before any
-fractional digits).
+an arbitrary floating point number. @xref{Floating point}.
+When @command{tail} uses inotify, this polling-related option
+is usually ignored. However, if you also specify @option{--pid=@var{p}},
+@command{tail} checks whether process @var{p} is alive at least
+every @var{number} seconds.
@itemx --pid=@var{pid}
@opindex --pid
When following a log file that is rotated, this is approximately the
number of seconds between when tail prints the last pre-rotation lines
and when it prints the lines that have accumulated in the new log file.
-This option is meaningful only when following by name.
+This option is meaningful only when polling (i.e., without inotify)
+and when following by name.
@itemx -n @var{k}
@itemx --lines=@var{k}
@node split invocation
-@section @command{split}: Split a file into fixed-size pieces
+@section @command{split}: Split a file into pieces.
@pindex split
@cindex splitting a file into pieces
@cindex pieces, splitting a file into
-@command{split} creates output files containing consecutive sections of
-@var{input} (standard input if none is given or @var{input} is
-@samp{-}). Synopsis:
+@command{split} creates output files containing consecutive or interleaved
+sections of @var{input} (standard input if none is given or @var{input}
+is @samp{-}). Synopsis:
@example
split [@var{option}] [@var{input} [@var{prefix}]]
The output files' names consist of @var{prefix} (@samp{x} by default)
followed by a group of characters (@samp{aa}, @samp{ab}, @dots{} by
default), such that concatenating the output files in traditional
-sorted order by file name produces
-the original input file. If the output file names are exhausted,
-@command{split} reports an error without deleting the output files
-that it did create.
+sorted order by file name produces the original input file (except
+@option{-r}). If the output file names are exhausted, @command{split}
+reports an error without deleting the output files that it did create.
The program accepts the following options. Also see @ref{Common options}.
Put @var{lines} lines of @var{input} into each output file.
For compatibility @command{split} also supports an obsolete
-option syntax @option{-@var{lines}}. New scripts should use @option{-l
-@var{lines}} instead.
+option syntax @option{-@var{lines}}. New scripts should use
+@option{-l @var{lines}} instead.
@item -b @var{size}
@itemx --bytes=@var{size}
@var{size} bytes are broken into multiple files.
@var{size} has the same format as for the @option{--bytes} option.
+@itemx --filter=@var{command}
+@opindex --filter
+With this option, rather than simply writing to each output file,
+write through a pipe to the specified shell @var{command} for each output file.
+@var{command} should use the $FILE environment variable, which is set
+to a different output file name for each invocation of the command.
+For example, imagine that you have a 1TiB compressed file
+that, if uncompressed, would be too large to reside on disk,
+yet you must split it into individually-compressed pieces
+of a more manageable size.
+To do that, you might run this command:
+
+@example
+xz -dc BIG.xz | split -b200G --filter='xz > $FILE.xz' - big-
+@end example
+
+Assuming a 10:1 compression ratio, that would create about fifty 20GiB files
+with names @file{big-xaa.xz}, @file{big-xab.xz}, @file{big-xac.xz}, etc.
+
+@item -n @var{chunks}
+@itemx --number=@var{chunks}
+@opindex -n
+@opindex --number
+
+Split @var{input} to @var{chunks} output files where @var{chunks} may be:
+
+@example
+@var{n} generate @var{n} files based on current size of @var{input}
+@var{k}/@var{n} only output @var{k}th of @var{n} to stdout
+l/@var{n} generate @var{n} files without splitting lines
+l/@var{k}/@var{n} likewise but only output @var{k}th of @var{n} to stdout
+r/@var{n} like @samp{l} but use round robin distribution
+r/@var{k}/@var{n} likewise but only output @var{k}th of @var{n} to stdout
+@end example
+
+Any excess bytes remaining after dividing the @var{input}
+into @var{n} chunks, are assigned to the last chunk.
+Any excess bytes appearing after the initial calculation are discarded
+(except when using @samp{r} mode).
+
+All @var{n} files are created even if there are fewer than @var{n} lines,
+or the @var{input} is truncated.
+
+For @samp{l} mode, chunks are approximately @var{input} size / @var{n}.
+The @var{input} is partitioned into @var{n} equal sized portions, with
+the last assigned any excess. If a line @emph{starts} within a partition
+it is written completely to the corresponding file. Since lines
+are not split even if they overlap a partition, the files written
+can be larger or smaller than the partition size, and even empty
+if a line is so long as to completely overlap the partition.
+
+For @samp{r} mode, the size of @var{input} is irrelevant,
+and so can be a pipe for example.
+
@item -a @var{length}
@itemx --suffix-length=@var{length}
@opindex -a
@opindex --numeric-suffixes
Use digits in suffixes rather than lower-case letters.
+@item -e
+@itemx --elide-empty-files
+@opindex -e
+@opindex --elide-empty-files
+Suppress the generation of zero-length output files. This can happen
+with the @option{--number} option if a file is (truncated to be) shorter
+than the number requested, or if a line is so long as to completely
+span a chunk. The output file sequence numbers, always run consecutively
+even when this option is specified.
+
+@item -u
+@itemx --unbuffered
+@opindex -u
+@opindex --unbuffered
+Immediately copy input to output in @option{--number r/...} mode,
+which is a much slower mode of operation.
+
@itemx --verbose
@opindex --verbose
Write a diagnostic just before each output file is opened.
@exitstatus
+Here are a few examples to illustrate how the
+@option{--number} (@option{-n}) option works:
+
+Notice how, by default, one line may be split onto two or more:
+
+@example
+$ seq -w 6 10 > k; split -n3 k; head xa?
+==> xaa <==
+06
+07
+==> xab <==
+
+08
+0
+==> xac <==
+9
+10
+@end example
+
+Use the "l/" modifier to suppress that:
+
+@example
+$ seq -w 6 10 > k; split -nl/3 k; head xa?
+==> xaa <==
+06
+07
+
+==> xab <==
+08
+09
+
+==> xac <==
+10
+@end example
+
+Use the "r/" modifier to distribute lines in a round-robin fashion:
+
+@example
+$ seq -w 6 10 > k; split -nr/3 k; head xa?
+==> xaa <==
+06
+09
+
+==> xab <==
+07
+10
+
+==> xac <==
+08
+@end example
+
+You can also extract just the Kth chunk.
+This extracts and prints just the 7th "chunk" of 33:
+
+@example
+$ seq 100 > k; split -nl/7/33 k
+20
+21
+22
+@end example
+
@node csplit invocation
@section @command{csplit}: Split a file into context-determined pieces
@code{printf(3)}-style conversion specification, possibly including
format specification flags, a field width, a precision specifications,
or all of these kinds of modifiers. The format letter must convert a
-binary integer argument to readable form; thus, only @samp{d}, @samp{i},
+binary unsigned integer argument to readable form. The format letters
+@samp{d} and @samp{i} are aliases for @samp{u}, and the
@samp{u}, @samp{o}, @samp{x}, and @samp{X} conversions are allowed. The
entire @var{suffix} is given (with the current output file number) to
@code{sprintf(3)} to form the file name suffixes for each of the
In such cases, running @command{\cmd\} via @command{xargs} is undesirable
because it splits the list into pieces and makes @command{\cmd\} print
\subListOutput\ for each sublist rather than for the entire list.
-One way to produce a list of @acronym{ASCII} @sc{nul} terminated file names is with @sc{gnu}
+One way to produce a list of @acronym{ASCII} @sc{nul} terminated file
+names is with @sc{gnu}
@command{find}, using its @option{-print0} predicate.
-If @var{file} is @samp{-} then the @acronym{ASCII} @sc{nul} terminated file names
-are read from standard input.
+If @var{file} is @samp{-} then the @acronym{ASCII} @sc{nul} terminated
+file names are read from standard input.
@end macro
@filesZeroFromOption{wc,,a total}
Note: The MD5 digest is more reliable than a simple CRC (provided by
the @command{cksum} command) for detecting accidental file corruption,
as the chances of accidentally having two files with identical MD5
-are vanishingly small. However, it should not be considered truly
-secure against malicious tampering: although finding a file with a
-given MD5 fingerprint, or modifying a file so as to retain its MD5 are
-considered infeasible at the moment, it is known how to produce
-different files with identical MD5 (a ``collision''), something which
-can be a security issue in certain contexts. For more secure hashes,
-consider using SHA-1 or SHA-2. @xref{sha1sum invocation}, and
-@ref{sha2 utilities}.
+are vanishingly small. However, it should not be considered secure
+against malicious tampering: although finding a file with a given MD5
+fingerprint is considered infeasible at the moment, it is known how
+to modify certain files, including digital certificates, so that they
+appear valid when signed with an MD5 digest.
+For more secure hashes, consider using SHA-2. @xref{sha2 utilities}.
If a @var{file} is specified as @samp{-} or if no files are given
@command{md5sum} computes the checksum for the standard input.
@opindex --sort
@cindex general numeric sort
@vindex LC_NUMERIC
-Sort numerically, using the standard C function @code{strtod} to convert
-a prefix of each line to a double-precision floating point number.
-This allows floating point numbers to be specified in scientific notation,
-like @code{1.0e-34} and @code{10e100}.
-The @env{LC_NUMERIC} locale determines the decimal-point character.
+Sort numerically, converting a prefix of each line to a long
+double-precision floating point number. @xref{Floating point}.
Do not report overflow, underflow, or conversion errors.
Use the following collating sequence:
@opindex --sort
@cindex human numeric sort
@vindex LC_NUMERIC
-Sort numerically, as per the @option{--numeric-sort} option below, and in
-addition handle IEC or SI suffixes like MiB, MB etc (@ref{Block size}).
-Note a mixture of IEC and SI suffixes is not supported and will
-be flagged as an error. Also the numbers must be abbreviated uniformly.
-I.E. values with different precisions like 6000K and 5M will be sorted
-incorrectly.
+Sort numerically, first by numeric sign (negative, zero, or positive);
+then by @acronym{SI} suffix (either empty, or @samp{k} or @samp{K}, or
+one of @samp{MGTPEZY}, in that order; @pxref{Block size}); and finally
+by numeric value. For example, @samp{1023M} sorts before @samp{1G}
+because @samp{M} (mega) precedes @samp{G} (giga) as an @acronym{SI}
+suffix. This option sorts values that are consistently scaled to the
+nearest suffix, regardless of whether suffixes denote powers of 1000
+or 1024, and it therefore sorts the output of any single invocation of
+the @command{df}, @command{du}, or @command{ls} commands that are
+invoked with their @option{--human-readable} or @option{--si} options.
+The syntax for numbers is the same as for the @option{--numeric-sort}
+option; the @acronym{SI} suffix must immediately follow the number.
@item -i
@itemx --ignore-nonprinting
@opindex -V
@opindex --version-sort
@cindex version number sort
-@vindex LC_NUMERIC
-Sort per @code{strverscmp(3)}. This is a normal string comparison, except
-that embedded decimal numbers are sorted by numeric value
-(see @option{--numeric-sort} above).
+Sort by version name and number. It behaves like a standard sort,
+except that each sequence of decimal digits is treated numerically
+as an index/version number. (@xref{Details about version sort}.)
@item -r
@itemx --reverse
Example: To sort on the second field, use @option{--key=2,2}
(@option{-k 2,2}). See below for more notes on keys and more examples.
+See also the @option{--debug} option to help determine the part
+of the line being used in the sort.
+
+@item --debug
+Highlight the portion of each line used for sorting.
+Also issue warnings about questionable usage to stderr.
@item --batch-size=@var{nmerge}
@opindex --batch-size
performance by using this option to specify directories on different
disks and controllers.
+@item --parallel=@var{n}
+@opindex --parallel
+@cindex multithreaded sort
+Set the number of sorts run in parallel to @var{n}. By default,
+@var{n} is set to the number of available processors, but limited
+to 8, as there are diminishing performance gains after that.
+Note also that using @var{n} threads increases the memory usage by
+a factor of log @var{n}. Also see @ref{nproc invocation}.
+
@item -u
@itemx --unique
@opindex -u
Historical (BSD and System V) implementations of @command{sort} have
differed in their interpretation of some options, particularly
-@option{-b}, @option{-f}, and @option{-n}. @sc{gnu} sort follows the @acronym{POSIX}
+@option{-b}, @option{-f}, and @option{-n}.
+@sc{gnu} sort follows the @acronym{POSIX}
behavior, which is usually (but not always!) like the System V behavior.
According to @acronym{POSIX}, @option{-n} no longer implies @option{-b}. For
consistency, @option{-M} has been changed in the same way. This may
inherited from the global options it will be attached to both.
If input lines can contain leading or adjacent blanks and @option{-t}
is not used, then @option{-k} is typically combined with @option{-b} or
-an option that implicitly ignores leading blanks (@samp{MghnV}) as otherwise
+an option that implicitly ignores leading blanks (@samp{Mghn}) as otherwise
the varying numbers of leading blanks in fields can cause confusing results.
If the start position in a sort field specifier falls after the end of
@vindex POSIXLY_CORRECT
On older systems, @command{sort} supports an obsolete origin-zero
syntax @samp{+@var{pos1} [-@var{pos2}]} for specifying sort keys.
+The obsolete sequence @samp{sort +@var{a}.@var{x} -@var{b}.@var{y}}
+is equivalent to @samp{sort -k @var{a+1}.@var{x+1},@var{b}} if @var{y}
+is @samp{0} or absent, otherwise it is equivalent to @samp{sort -k
+@var{a+1}.@var{x+1},@var{b+1}.@var{y}}.
+
This obsolete behavior can be enabled or disabled with the
@env{_POSIX2_VERSION} environment variable (@pxref{Standards
conformance}); it can also be enabled when @env{POSIXLY_CORRECT} is
@end example
@item
+Run no more that 4 sorts concurrently, using a buffer size of 10M.
+
+@example
+sort --parallel=4 -S 10M
+@end example
+
+@item
Sort alphabetically, omitting the first and second fields
and the blanks at the start of the third field.
This uses a single key composed of the characters beginning
@c and converting each @samp{\0} back to the original record delimiter.
@c
@c @example
-@c printf 'c\n\nb\n\na\n'|perl -0pe 's/\n\n/\n\0/g'|sort -z|perl -0pe 's/\0/\n/g'
+@c printf 'c\n\nb\n\na\n' |
+@c perl -0pe 's/\n\n/\n\0/g' |
+@c sort -z |
+@c perl -0pe 's/\0/\n/g'
@c @end example
@item
@macro checkOrderOption{cmd}
If the @option{--check-order} option is given, unsorted inputs will
cause a fatal error message. If the option @option{--nocheck-order}
-is given, unsorted inputs will never cause an error message. If
-neither of these options is given, wrongly sorted inputs are diagnosed
-only if an input file is found to contain unpairable lines. If an
-input file is diagnosed as being unsorted, the @command{\cmd\} command
-will exit with a nonzero status (and the output should not be used).
+is given, unsorted inputs will never cause an error message. If neither
+of these options is given, wrongly sorted inputs are diagnosed
+only if an input file is found to contain unpairable
+@ifset JOIN_COMMAND
+lines, and when both input files are non empty.
+@end ifset
+@ifclear JOIN_COMMAND
+lines.
+@end ifclear
+If an input file is diagnosed as being unsorted, the @command{\cmd\}
+command will exit with a nonzero status (and the output should not be used).
Forcing @command{\cmd\} to process wrongly sorted input files
containing unpairable lines by specifying @option{--nocheck-order} is
processing. Each output line will look like:
@smallexample
-.xx "@var{tail}" "@var{before}" "@var{keyword_and_after}" "@var{head}" "@var{ref}"
+.xx "@var{tail}" "@var{before}" "@var{keyword_and_after}"@c
+ "@var{head}" "@var{ref}"
@end smallexample
so it will be possible to write a @samp{.xx} roff macro to take care of
line will look like:
@smallexample
-\xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@{@var{after}@}@{@var{head}@}@{@var{ref}@}
+\xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@c
+@{@var{after}@}@{@var{head}@}@{@var{ref}@}
@end smallexample
@noindent
in different ways.
-@node Operating on fields within a line
-@chapter Operating on fields within a line
+@node Operating on fields
+@chapter Operating on fields
@menu
* cut invocation:: Print selected parts of lines.
Select for printing only the fields listed in @var{field-list}.
Fields are separated by a TAB character by default. Also print any
line that contains no delimiter character, unless the
-@option{--only-delimited} (@option{-s}) option is specified
+@option{--only-delimited} (@option{-s}) option is specified.
+
+Note @command{awk} supports more sophisticated field processing,
+and by default will use (and discard) runs of blank characters to
+separate fields, and ignore leading and trailing blanks.
+@example
+@verbatim
+awk '{print $2}' # print the second field
+awk '{print $NF-1}' # print the penultimate field
+awk '{print $2,$1}' # reorder the first two fields
+@end verbatim
+@end example
+
+In the unlikely event that @command{awk} is unavailable,
+one can use the @command{join} command, to process blank
+characters as @command{awk} does above.
+@example
+@verbatim
+join -a1 -o 1.2 - /dev/null # print the second field
+join -a1 -o 1.2,1.1 - /dev/null # reorder the first two fields
+@end verbatim
+@end example
@item -d @var{input_delim_byte}
@itemx --delimiter=@var{input_delim_byte}
sort a file on its default join field, but if you select a non-default
locale, join field, separator, or comparison options, then you should
do so consistently between @command{join} and @command{sort}.
+If @samp{join -t ''} is specified then the whole line is considered which
+matches the default operation of sort.
If the input has no unpairable lines, a @acronym{GNU} extension is
available; the sort order can be any order that considers two fields
b b1 b2
@end example
+@set JOIN_COMMAND
@checkOrderOption{join}
+@clear JOIN_COMMAND
The defaults are:
@itemize
@item -e @var{string}
@opindex -e
-Replace those output fields that are missing in the input with
-@var{string}.
+Replace those output fields that are missing in the input with @var{string}.
+I.E. missing fields specified with the @option{-12jo} options.
+
+@item --header
+@opindex --header
+Treat the first line of each input file as a header line. The header lines will
+be joined and printed as the first output line. If @option{-o} is used to
+specify output format, the header line will be printed according to the
+specified format. The header lines will not be checked for ordering even if
+@option{--check-order} is specified. Also if the header lines from each file
+do not match, the heading fields from the first file will be used.
@item -i
@itemx --ignore-case
Equivalent to @option{-1 @var{field} -2 @var{field}}.
@item -o @var{field-list}
-Construct each output line according to the format in @var{field-list}.
-Each element in @var{field-list} is either the single character @samp{0} or
-has the form @var{m.n} where the file number, @var{m}, is @samp{1} or
-@samp{2} and @var{n} is a positive field number.
+@itemx -o auto
+If the keyword @samp{auto} is specified, infer the output format from
+the first line in each file. This is the same as the default output format
+but also ensures the same number of fields are output for each line.
+Missing fields are replaced with the @option{-e} option and extra fields
+are discarded.
+
+Otherwise, construct each output line according to the format in
+@var{field-list}. Each element in @var{field-list} is either the single
+character @samp{0} or has the form @var{m.n} where the file number, @var{m},
+is @samp{1} or @samp{2} and @var{n} is a positive field number.
A field specification of @samp{0} denotes the join field.
In most cases, the functionality of the @samp{0} field spec
Use character @var{char} as the input and output field separator.
Treat as significant each occurrence of @var{char} in the input file.
Use @samp{sort -t @var{char}}, without the @option{-b} option of
-@samp{sort}, to produce this ordering.
+@samp{sort}, to produce this ordering. If @samp{join -t ''} is specified,
+the whole line is considered, matching the default operation of sort.
+If @samp{-t '\0'} is specified then the @acronym{ASCII} @sc{nul}
+character is used to delimit the fields.
@item -v @var{file-number}
Print a line for each unpairable line in file @var{file-number}
@item \v
Control-K.
@item \@var{ooo}
-The character with the value given by @var{ooo}, which is 1 to 3
-octal digits,
+The 8-bit character with the value given by @var{ooo}, which is 1 to 3
+octal digits. Note that @samp{\400} is interpreted as the two-byte
+sequence, @samp{\040} @samp{0}.
@item \\
A backslash.
@end table
@noindent
By the way, the above idiom is not portable because it uses ranges, and
it assumes that the octal code for newline is 012.
-Assuming a @acronym{POSIX} compliant @command{tr}, here is a better way to write it:
+Assuming a @acronym{POSIX} compliant @command{tr}, here is a better
+way to write it:
@example
tr -cs '[:alnum:]' '[\n*]'
1 minor problems (e.g., failure to access a file or directory not
specified as a command line argument. This happens when listing a
directory in which entries are actively being removed or renamed.)
-2 serious trouble (e.g., memory exhausted, invalid option or failure
- to access file or directory specified as a command line argument)
+2 serious trouble (e.g., memory exhausted, invalid option, failure
+ to access a file or directory specified as a command line argument
+ or a directory loop)
@end display
Also see @ref{Common options}.
* Which files are listed::
* What information is listed::
* Sorting the output::
-* More details about version sort::
+* Details about version sort::
* General output formatting::
* Formatting file timestamps::
* Formatting the file names::
@opindex version@r{, sorting option for @command{ls}}
Sort by version name and number, lowest first. It behaves like a default
sort, except that each sequence of decimal digits is treated numerically
-as an index/version number. (@xref{More details about version sort}.)
+as an index/version number. (@xref{Details about version sort}.)
@item -X
@itemx --sort=extension
@end table
-@node More details about version sort
-@subsection More details about version sort
+@node Details about version sort
+@subsection Details about version sort
-The version sort takes into account the fact that file names frequently include
-indices or version numbers. Standard sorting functions usually do not produce
-the ordering that people expect because comparisons are made on a
-character-by-character basis. The version
-sort addresses this problem, and is especially useful when browsing
-directories that contain many files with indices/version numbers in their
-names:
+Version sorting handles the fact that file names frequently include indices or
+version numbers. Standard sorting usually does not produce the order that one
+expects because comparisons are made on a character-by-character basis.
+Version sorting is especially useful when browsing directories that contain
+many files with indices/version numbers in their names:
@example
$ ls -1 $ ls -1v
-foo.zml-1.gz foo.zml-1.gz
-foo.zml-100.gz foo.zml-2.gz
-foo.zml-12.gz foo.zml-6.gz
-foo.zml-13.gz foo.zml-12.gz
-foo.zml-2.gz foo.zml-13.gz
-foo.zml-25.gz foo.zml-25.gz
-foo.zml-6.gz foo.zml-100.gz
+abc.zml-1.gz abc.zml-1.gz
+abc.zml-12.gz abc.zml-2.gz
+abc.zml-2.gz abc.zml-12.gz
@end example
Version-sorted strings are compared such that if @var{ver1} and @var{ver2}
abc-1.01a.tgz abc-1.012b.tgz
@end example
-This functionality is implemented using gnulib's @code{filevercmp} function.
-One result of that implementation decision is that @samp{ls -v}
-and @samp{sort -V} do not use the locale category, @env{LC_COLLATE},
-which means non-numeric prefixes are sorted as if @env{LC_COLLATE} were set
-to @samp{C}.
+This functionality is implemented using gnulib's @code{filevercmp} function,
+which has some caveats worth noting.
+
+@itemize @bullet
+@item @env{LC_COLLATE} is ignored, which means @samp{ls -v} and @samp{sort -V}
+will sort non-numeric prefixes as if the @env{LC_COLLATE} locale category
+was set to @samp{C}.
+@item Some suffixes will not be matched by the regular
+expression mentioned above. Consequently these examples may
+not sort as you expect:
+
+@example
+abc-1.2.3.4.7z
+abc-1.2.3.7z
+@end example
+
+@example
+abc-1.2.3.4.x86_64.rpm
+abc-1.2.3.x86_64.rpm
+@end example
+@end itemize
@node General output formatting
@subsection General output formatting
@command{less} usually produces unreadable results. However, using
@code{more -f} does seem to work.
+@vindex LS_COLORS
+@vindex SHELL @r{environment variable, and color}
+Note that using the @option{--color} option may incur a noticeable
+performance penalty when run in a directory with very many entries,
+because the default settings require that @command{ls} @code{stat} every
+single file it lists.
+However, if you would like most of the file-type coloring
+but can live without the other coloring options (e.g.,
+executable, orphan, sticky, other-writable, capability), use
+@command{dircolors} to set the @env{LS_COLORS} environment variable like this,
+@example
+eval $(dircolors -p | perl -pe \
+ 's/^((CAP|S[ET]|O[TR]|M|E)\w+).*/$1 00/' | dircolors -)
+@end example
+and on a @code{dirent.d_type}-capable file system, @command{ls}
+will perform only one @code{stat} call per command line argument.
+
@item -F
@itemx --classify
@itemx --indicator-style=classify
@node Formatting file timestamps
@subsection Formatting file timestamps
-By default, file timestamps are listed in abbreviated form. Most
-locales use a timestamp like @samp{2002-03-30 23:45}. However, the
-default @acronym{POSIX} locale uses a date like @samp{Mar 30@ @ 2002}
-for non-recent timestamps, and a date-without-year and time like
-@samp{Mar 30 23:45} for recent timestamps.
+By default, file timestamps are listed in abbreviated form, using
+a date like @samp{Mar 30@ @ 2002} for non-recent timestamps, and a
+date-without-year and time like @samp{Mar 30 23:45} for recent timestamps.
+This format can change depending on the current locale as detailed below.
A timestamp is considered to be @dfn{recent} if it is less than six
months old, and is not dated in the future. If a timestamp dated
but ignore any failure to do that and print no corresponding diagnostic.
Equivalent to @option{-dR --preserve=all} with the reduced diagnostics.
+@itemx --attributes-only
+@opindex --attributes-only
+Preserve the specified attributes of the original files in the copy,
+but do not copy any data. See the @option{--preserve} option for
+controlling which attributes to copy.
+
@item -b
@itemx @w{@kbd{--backup}[=@var{method}]}
@opindex -b
a member of the desired group.
@itemx timestamps
Preserve the times of last access and last modification, when possible.
-In general, it is not possible to preserve these attributes
+On older systems, it is not possible to preserve these attributes
when the affected file is a symbolic link.
-However, FreeBSD now provides the @code{lutimes} function, which makes
-it possible even for symbolic links. However, this implementation does
-not yet take advantage of that.
-@c FIXME: once we provide lutimes support, update the above.
+However, many systems now provide the @code{utimensat} function,
+which makes it possible even for symbolic links.
@itemx links
Preserve in the destination files
any links between corresponding source files.
@end smallexample
@itemx context
-Preserve SELinux security context of the file. @command{cp} will fail
-if the preserving of SELinux security context is not succesful.
+Preserve SELinux security context of the file, or fail with full diagnostics.
@itemx xattr
-Preserve extended attributes if @command{cp} is built with xattr support,
-and xattrs are supported and enabled on your file system.
-If SELinux context and/or ACLs are implemented using xattrs,
+Preserve extended attributes of the file, or fail with full diagnostics.
+If @command{cp} is built without xattr support, ignore this option.
+If SELinux context, ACLs or Capabilities are implemented using xattrs,
they are preserved by this option as well.
@itemx all
Preserve all file attributes.
Equivalent to specifying all of the above, but with the difference
that failure to preserve SELinux security context or extended attributes
-does not change @command{cp}'s exit status.
-@command{cp} does diagnose such failures.
+does not change @command{cp}'s exit status. In contrast to @option{-a},
+all but @samp{Operation not supported} warnings are output.
@end table
Using @option{--preserve} with no @var{attribute_list} is equivalent
unless you also specify @option{-P}, as @acronym{POSIX} allows
implementations that dereference symbolic links by default.
+@item --reflink[=@var{when}]
+@opindex --reflink[=@var{when}]
+@cindex COW
+@cindex clone
+@cindex copy on write
+Perform a lightweight, copy-on-write (COW) copy, if supported by the
+file system. Once it has succeeded, beware that the source and destination
+files share the same disk data blocks as long as they remain unmodified.
+Thus, if a disk I/O error affects data blocks of one of the files,
+the other suffers the same fate.
+
+The @var{when} value can be one of the following:
+
+@table @samp
+@item always
+The default behavior: if the copy-on-write operation is not supported
+then report the failure for each file and exit with a failure status.
+
+@item auto
+If the copy-on-write operation is not supported then fall back
+to the standard copy behaviour.
+@end table
+
+This option is overridden by the @option{--link}, @option{--symbolic-link}
+and @option{--attributes-only} options, thus allowing it to be used
+to configure the default data copying behavior for @command{cp}.
+For example, with the following alias, @command{cp} will use the
+minimum amount of space supported by the file system.
+
+@example
+alias cp='cp --reflink=auto --sparse=always'
+@end example
+
@item --remove-destination
@opindex --remove-destination
Remove each existing destination file before attempting to open it
This makes @command{dd} read and write @var{bytes} per block,
overriding any @samp{ibs} and @samp{obs} settings.
In addition, if no data-transforming @option{conv} option is specified,
-each input block is copied to the output as a single block,
-without aggregating short reads.
+input is copied to the output as soon as it's read,
+even if it is smaller than the block size.
@item cbs=@var{bytes}
@opindex cbs
@item unblock
@opindex unblock
-Replace trailing spaces in each @samp{cbs}-sized input block with a
-newline.
+Remove any trailing spaces in each @samp{cbs}-sized input block,
+and append a newline.
The @samp{block} and @samp{unblock} conversions are mutually exclusive.
when an odd number of bytes are read---the last byte is simply copied
(since there is nothing to swap it with).
-@item noerror
-@opindex noerror
-@cindex read errors, ignoring
-Continue after read errors.
+@item sync
+@opindex sync @r{(padding with @acronym{ASCII} @sc{nul}s)}
+Pad every input block to size of @samp{ibs} with trailing zero bytes.
+When used with @samp{block} or @samp{unblock}, pad with spaces instead of
+zero bytes.
-@item nocreat
-@opindex nocreat
-@cindex creating output file, avoiding
-Do not create the output file; the output file must already exist.
+@end table
+The following ``conversions'' are really file flags
+and don't affect internal processing:
+
+@table @samp
@item excl
@opindex excl
@cindex creating output file, requiring
Fail if the output file already exists; @command{dd} must create the
output file itself.
+@item nocreat
+@opindex nocreat
+@cindex creating output file, avoiding
+Do not create the output file; the output file must already exist.
+
The @samp{excl} and @samp{nocreat} conversions are mutually exclusive.
@item notrunc
@cindex truncating output file, avoiding
Do not truncate the output file.
-@item sync
-@opindex sync @r{(padding with @acronym{ASCII} @sc{nul}s)}
-Pad every input block to size of @samp{ibs} with trailing zero bytes.
-When used with @samp{block} or @samp{unblock}, pad with spaces instead of
-zero bytes.
+@item noerror
+@opindex noerror
+@cindex read errors, ignoring
+Continue after read errors.
@item fdatasync
@opindex fdatasync
@cindex synchronized data and metadata I/O
Use synchronized I/O for both data and metadata.
+@item nocache
+@opindex nocache
+@cindex discarding file cache
+Discard the data cache for a file.
+When count=0 all cache is discarded,
+otherwise the cache is dropped for the processed
+portion of the file. Also when count=0
+failure to discard the cache is diagnosed
+and reflected in the exit status.
+Here as some usage examples:
+
+@example
+# Advise to drop cache for whole file
+dd if=ifile iflag=nocache count=0
+
+# Ensure drop cache for the whole file
+dd of=ofile oflag=nocache conv=notrunc,fdatasync count=0
+
+# Drop cache for part of file
+dd if=ifile iflag=nocache skip=10 count=10 of=/dev/null
+
+# Stream data using just the read-ahead cache
+dd if=ifile of=ofile iflag=nocache oflag=nocache
+@end example
+
@item nonblock
@opindex nonblock
@cindex nonblocking I/O
@samp{w}=2, @samp{x@var{m}}=@var{m}, or any of the
standard block size suffixes like @samp{k}=1024 (@pxref{Block size}).
+Any block size you specify via @samp{bs=}, @samp{ibs=}, @samp{obs=}, @samp{cbs=}
+should not be too large---values larger than a few megabytes
+are generally wasteful or (as in the gigabyte..exabyte case) downright
+counterproductive or error-inducing.
+
Use different @command{dd} invocations to use different block sizes for
skipping and I/O@. For example, the following shell commands copy data
in 512 KiB blocks between a disk and a tape, but do not save or restore a
@optBackup
+@item -C
+@itemx --compare
+@opindex -C
+@opindex --compare
+Compare each pair of source and destination files, and if the destination has
+identical content and any specified owner, group, permissions, and possibly
+SELinux context, then do not modify the destination at all.
+
@item -c
@opindex -c
Ignored; for compatibility with old Unix versions of @command{install}.
original partition.
@cindex extended attributes, xattr
-@command{mv} always tries to copy extended attributes (xattr).
+@command{mv} always tries to copy extended attributes (xattr), which may
+include SELinux context, ACLs or Capabilities.
+Upon failure all but @samp{Operation not supported} warnings are output.
@cindex prompting, and @command{mv}
If a destination file exists but is normally unwritable, standard input
when it might be a symlink to a directory.
Otherwise, @command{mv} may do something very surprising, since
its behavior depends on the underlying rename system call.
-On a system with a modern Linux-based kernel, it fails with @code{errno=ENOTDIR}.
+On a system with a modern Linux-based kernel, it fails with
+@code{errno=ENOTDIR}.
However, on other systems (at least FreeBSD 6.1 and Solaris 10) it silently
renames not the symlink but rather the directory referenced by the symlink.
@xref{Trailing slashes}.
When removing a hierarchy recursively, skip any directory that is on a
file system different from that of the corresponding command line argument.
+@cindex bind mount
This option is useful when removing a build ``chroot'' hierarchy,
which normally contains no valuable data. However, it is not uncommon
to bind-mount @file{/home} into such a hierarchy, to make it easier to
@opindex -x
@opindex --exact
By default, @command{shred} rounds the size of a regular file up to the next
-multiple of the file system block size to fully erase the last block of the file.
+multiple of the file system block size to fully erase the last block
+of the file.
Use @option{--exact} to suppress that behavior.
Thus, by default if you shred a 10-byte regular file on a system with 512-byte
blocks, the resulting file will be 512 bytes long. With this option,
shred --verbose /dev/sda5
@end example
+On modern disks, a single pass should be adequate,
+and it will take one third the time of the default three-pass approach.
+
+@example
+# 1 pass, write pseudo-random data; 3x faster than the default
+shred --verbose -n1 /dev/sda5
+@end example
+
+To be on the safe side, use at least one pass that overwrites using
+pseudo-random data. I.e., don't be tempted to use @samp{-n0 --zero},
+in case some disk controller optimizes the process of writing blocks
+of all zeros, and thereby does not clear all bytes in a block.
+Some SSDs may do just that.
+
A @var{file} of @samp{-} denotes standard output.
The intended use of this is to shred a removed temporary file.
For example:
@example
-i=`tempfile -m 0600`
+i=`mktemp`
exec 3<>"$i"
rm -- "$i"
echo "Hello, world" >&3
not specified by @acronym{POSIX}, and the @command{link} command is
more portable in practice.
+If @var{filename} is a symbolic link, it is unspecified whether
+@var{linkname} will be a hard link to the symbolic link or to the
+target of the symbolic link. Use @command{ln -P} or @command{ln -L}
+to specify which behavior is desired.
+
@exitstatus
original are indistinguishable. Technically speaking, they share the
same inode, and the inode contains all the information about a
file---indeed, it is not incorrect to say that the inode @emph{is} the
-file. On all existing implementations, you cannot make a hard link to
-a directory, and hard links cannot cross file system boundaries. (These
+file. Most systems prohibit making a hard link to
+a directory; on those where it is allowed, only the super-user can do
+so (and with caution, since creating a cycle will cause problems to many
+other utilities). Hard links cannot cross file system boundaries. (These
restrictions are not mandated by @acronym{POSIX}, however.)
@cindex dereferencing symbolic links
reading, writing, and so on) are passed the symbolic link file, the
kernel automatically @dfn{dereferences} the link and operates on the
target of the link. But some operations (e.g., removing) work on the
-link file itself, rather than on its target. The owner, group, and
-mode of a symlink are not significant to file access performed through
-the link. @xref{Symbolic Links,,,
+link file itself, rather than on its target. The owner and group of a
+symlink are not significant to file access performed through
+the link, but do have implications on deleting a symbolic link from a
+directory with the restricted deletion bit set. On the GNU system,
+the mode of a symlink has no significance and cannot be changed, but
+on some BSD systems, the mode can be changed and will affect whether
+the symlink will be traversed in file name resolution. @xref{Symbolic Links,,,
libc, The GNU C Library Reference Manual}.
Symbolic links can contain arbitrary strings; a @dfn{dangling symlink}
@cindex prompting, and @command{ln}
Prompt whether to remove existing destination files.
+@item -L
+@itemx --logical
+@opindex -L
+@opindex --logical
+If @option{-s} is not in effect, and the source file is a symbolic
+link, create the hard link to the file referred to by the symbolic
+link, rather than the symbolic link itself.
+
@item -n
@itemx --no-dereference
@opindex -n
This option is weaker than the @option{--no-target-directory}
(@option{-T}) option, so it has no effect if both options are given.
+@item -P
+@itemx --physical
+@opindex -P
+@opindex --physical
+If @option{-s} is not in effect, and the source file is a symbolic
+link, create the hard link to the symbolic link itself. On platforms
+where this is not supported by the kernel, this option creates a
+symbolic link with identical contents; since symbolic link contents
+cannot be edited, any file name resolution performed through either
+link will be the same as if a hard link had been created.
+
@item -s
@itemx --symbolic
@opindex -s
@end table
+@cindex hard links to symbolic links
+@cindex symbolic links and @command{ln}
+If @option{-L} and @option{-P} are both given, the last one takes
+precedence. If @option{-s} is also given, @option{-L} and @option{-P}
+are silently ignored. If neither option is given, then this
+implementation defaults to @option{-P} if the system @code{link} supports
+hard links to symbolic links (such as the GNU system), and @option{-L}
+if @code{link} follows symbolic links (such as on BSD).
+
@exitstatus
Examples:
@opindex --canonicalize
Activate canonicalize mode.
If any component of the file name except the last one is missing or unavailable,
-@command{readlink} produces no output and exits with a nonzero exit code.
+@command{readlink} produces no output and exits with a nonzero exit
+code. A trailing slash is ignored.
@item -e
@itemx --canonicalize-existing
@opindex --canonicalize-existing
Activate canonicalize mode.
If any component is missing or unavailable, @command{readlink} produces
-no output and exits with a nonzero exit code.
+no output and exits with a nonzero exit code. A trailing slash
+requires that the name resolve to a directory.
@item -m
@itemx --canonicalize-missing
Synopsis:
@example
-chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@} @var{file}@dots{}
+chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@}@c
+ @var{file}@dots{}
@end example
If used, @var{new-owner} specifies the new owner and/or group as follows
or to the group of an existing reference file. Synopsis:
@example
-chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@} @var{file}@dots{}
+chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@}@c
+ @var{file}@dots{}
@end example
If @var{group} is intended to represent a
@command{chmod} changes the access permissions of the named files. Synopsis:
@example
-chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{ref_file}@} @var{file}@dots{}
+chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{ref_file}@}@c
+ @var{file}@dots{}
@end example
@cindex symbolic links, permissions of
@end example
@cindex empty files, creating
-Any @var{file} argument that does not exist is created empty.
+Any @var{file} argument that does not exist is created empty, unless
+option @option{--no-create} (@option{-c}) or @option{--no-dereference}
+(@option{-h}) was in effect.
A @var{file} argument string of @samp{-} is handled specially and
causes @command{touch} to change the times of the file associated with
Although @command{touch} provides options for changing two of the times---the
times of last access and modification---of a file, there is actually
-a third one as well: the inode change time. This is often referred to
-as a file's @code{ctime}.
+a standard third one as well: the inode change time. This is often
+referred to as a file's @code{ctime}.
The inode change time represents the time when the file's meta-information
last changed. One common example of this is when the permissions of a
file change. Changing the permissions doesn't access the file, so
Another operation that modifies a file's ctime without affecting
the others is renaming. In any case, it is not possible, in normal
operations, for a user to change the ctime field to a user-specified value.
+Some operating systems and file systems support a fourth time: the
+birth time, when the file was first created; by definition, this
+timestamp never changes.
@vindex TZ
Time stamps assume the time zone rules specified by the @env{TZ}
@itemx --no-create
@opindex -c
@opindex --no-create
-Do not create files that do not exist.
+Do not warn about or create files that do not exist.
@item -d
@itemx --date=@var{time}
@cindex BSD @command{touch} compatibility
Ignored; for compatibility with BSD versions of @command{touch}.
+@item -h
+@itemx --no-dereference
+@opindex -h
+@opindex --no-dereference
+@cindex symbolic links, changing time
+@findex lutimes
+Attempt to change the timestamps of a symbolic link, rather than what
+the link refers to. When using this option, empty files are not
+created, but option @option{-c} must also be used to avoid warning
+about files that do not exist. Not all systems support changing the
+timestamps of symlinks, since underlying system support for this
+action was not required until @acronym{POSIX} 2008. Also, on some
+systems, the mere act of examining a symbolic link changes the access
+time, such that only changes to the modification time will persist
+long enough to be observable. When coupled with option @option{-r}, a
+reference timestamp is taken from a symbolic link rather than the file
+it refers to.
+
@item -m
@itemx --time=mtime
@itemx --time=modify
the origin for any relative @var{time}s given, but is otherwise ignored.
For example, @samp{-r foo -d '-5 seconds'} specifies a time stamp
equal to five seconds before the corresponding time stamp for @file{foo}.
+If @var{file} is a symbolic link, the reference timestamp is taken
+from the target of the symlink, unless @option{-h} was also in effect.
@item -t [[@var{cc}]@var{yy}]@var{mmddhhmm}[.@var{ss}]
Use the argument (optional four-digit or two-digit years, months,
is 20 for years in the range 0 @dots{} 68, and 19 for years in
69 @dots{} 99. If no digits of the year are specified,
the argument is interpreted as a date in the current year.
+Note that @var{ss} may be @samp{60}, to accommodate leap seconds.
@end table
If an argument @var{file} is a disk device file containing a mounted
file system, @command{df} shows the space available on that file system
rather than on the file system containing the device node (i.e., the root
-file system). @sc{gnu} @command{df} does not attempt to determine the disk usage
+file system). @sc{gnu} @command{df} does not attempt to determine the
+disk usage
on unmounted file systems, because on most kinds of systems doing so
requires extremely nonportable intimate knowledge of file system
structures.
For each symbolic links encountered by @command{du},
consider the disk space used by the symbolic link.
+@item -d @var{depth}
@item --max-depth=@var{depth}
+@opindex -d @var{depth}
@opindex --max-depth=@var{depth}
@cindex limiting output of @command{du}
Show the total for each directory (and file if --all) that is at
most MAX_DEPTH levels down from the root of the hierarchy. The root
is at level 0, so @code{du --max-depth=0} is equivalent to @code{du -s}.
-@item -0
-@opindex -0
-@itemx --null
-@opindex --null
-@cindex output null-byte-terminated lines
-Output a zero byte (@acronym{ASCII} @sc{nul}) at the end of each line,
-rather than a newline. This option enables other programs to parse the
-output of @command{du} even when that output would contain file names
-with embedded newlines.
+@optNull{du}
@optSi
@cindex file systems
Report information about the file systems where the given files are located
instead of information about the files themselves.
+This option implies the @option{-L} option.
@item -c
@itemx --format=@var{format}
@item %A - Access rights in human readable form
@item %b - Number of blocks allocated (see @samp{%B})
@item %B - The size in bytes of each block reported by @samp{%b}
+@item %C - The SELinux security context of a file, if available
@item %d - Device number in decimal
@item %D - Device number in hex
@item %f - Raw mode in hex
@item %G - Group name of owner
@item %h - Number of hard links
@item %i - Inode number
+@item %m - Mount point (See note below)
@item %n - File name
@item %N - Quoted file name with dereference if symbolic link
@item %o - I/O block size
@item %T - Minor device type in hex
@item %u - User ID of owner
@item %U - User name of owner
+@item %w - Time of file birth, or @samp{-} if unknown
+@item %W - Time of file birth as seconds since Epoch, or @samp{0}
@item %x - Time of last access
@item %X - Time of last access as seconds since Epoch
@item %y - Time of last modification
@item %Z - Time of last change as seconds since Epoch
@end itemize
+The @samp{%W}, @samp{%X}, @samp{%Y}, and @samp{%Z} formats accept a
+precision preceded by a period to specify the number of digits to
+print after the decimal point. For example, @samp{%.3X} outputs the
+last access time to millisecond precision. If a period is given but no
+precision, @command{stat} uses 9 digits, so @samp{%.X} is equivalent to
+@samp{%.9X}. When discarding excess precision, time stamps are truncated
+toward minus infinity.
+
+@example
+zero pad:
+ $ stat -c '[%015Y]' /usr
+ [000001288929712]
+space align:
+ $ stat -c '[%15Y]' /usr
+ [ 1288929712]
+ $ stat -c '[%-15Y]' /usr
+ [1288929712 ]
+precision:
+ $ stat -c '[%.3Y]' /usr
+ [1288929712.114]
+ $ stat -c '[%.Y]' /usr
+ [1288929712.114951834]
+@end example
+
+The mount point printed by @samp{%m} is similar to that output
+by @command{df}, except that:
+@itemize @bullet
+@item
+stat does not dereference symlinks by default
+(unless @option{-L} is specified)
+@item
+stat does not search for specified device nodes in the
+file system list, instead operating on them directly
+@item
+@cindex bind mount
+stat outputs the alias for a bind mounted file, rather than
+the initial mount point of its backing device.
+One can recursively call stat until there is no change in output,
+to get the current base mount point
+@end itemize
+
When listing file system information (@option{--file-system} (@option{-f})),
you must use a different set of @var{format} directives:
@itemx --reference=@var{rfile}
@opindex -r
@opindex --reference
-Set the size of each @var{file} to the same size as @var{rfile}.
+Base the size of each @var{file} on the size of @var{rfile}.
@item -s @var{size}
@itemx --size=@var{size}
@opindex -s
@opindex --size
-Set the size of each @var{file} to this @var{size}.
+Set or adjust the size of each @var{file} according to @var{size}.
@multiplierSuffixesNoBlocks{size}
@var{size} may also be prefixed by one of the following to adjust
backspace
@item \c
produce no further output
+@item \e
+escape
@item \f
form feed
@item \n
backslash
@item \0@var{nnn}
the eight-bit value that is the octal number @var{nnn}
-(zero to three octal digits)
+(zero to three octal digits), if @var{nnn} is
+a nine-bit value, the ninth bit is ignored
@item \@var{nnn}
the eight-bit value that is the octal number @var{nnn}
-(one to three octal digits)
+(one to three octal digits), if @var{nnn} is
+a nine-bit value, the ninth bit is ignored
@item \x@var{hh}
the eight-bit value that is the hexadecimal number @var{hh}
(one or two hexadecimal digits)
@command{printf} has an additional directive, @samp{%b}, which prints its
argument string with @samp{\} escapes interpreted in the same way as in
the @var{format} string, except that octal escapes are of the form
-@samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits.
+@samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits. If
+@samp{\@var{ooo}} is nine-bit value, ignore the ninth bit.
If a precision is also given, it limits the number of bytes printed
from the converted string.
current locale. For example, in a locale whose radix character is a
comma, the command @samp{printf %g 3.14} outputs @samp{3,14} whereas
the command @samp{printf %g 3,14} is an error.
+@xref{Floating point}.
@kindex \@var{ooo}
@kindex \x@var{hh}
@command{printf} interprets @samp{\@var{ooo}} in @var{format} as an octal number
-(if @var{ooo} is 1 to 3 octal digits) specifying a character to print,
+(if @var{ooo} is 1 to 3 octal digits) specifying a byte to print,
and @samp{\x@var{hh}} as a hexadecimal number (if @var{hh} is 1 to 2 hex
digits) specifying a character to print.
+Note however that when @samp{\@var{ooo}} specifies a number larger than 255,
+@command{printf} ignores the ninth bit.
+For example, @samp{printf '\400'} is equivalent to @samp{printf '\0'}.
@kindex \uhhhh
@kindex \Uhhhhhhhh
If @var{expression} is omitted, @command{test} returns false.
If @var{expression} is a single argument,
-@command{test} returns false if the argument is null and true otherwise. The argument
+@command{test} returns false if the argument is null and true
+otherwise. The argument
can be any string, including strings like @samp{-d}, @samp{-1},
@samp{--}, @samp{--help}, and @samp{--version} that most other
programs would treat as options. To get help and version information,
* File type tests:: -[bcdfhLpSt]
* Access permission tests:: -[gkruwxOG]
* File characteristic tests:: -e -s -nt -ot -ef
-* String tests:: -z -n = !=
+* String tests:: -z -n = == !=
* Numeric tests:: -eq -ne -lt -le -gt -ge
* Connectives for test:: ! -a -o
@end menu
@cindex equal string check
True if the strings are equal.
+@item @var{string1} == @var{string2}
+@opindex ==
+@cindex equal string check
+True if the strings are equal (synonym for =).
+
@item @var{string1} != @var{string2}
@opindex !=
@cindex not-equal string check
@menu
* basename invocation:: Strip directory and suffix from a file name.
-* dirname invocation:: Strip non-directory suffix from a file name.
+* dirname invocation:: Strip last file name component.
* pathchk invocation:: Check file name validity and portability.
+* mktemp invocation:: Create temporary file or directory.
@end menu
@node dirname invocation
-@section @command{dirname}: Strip non-directory suffix from a file name
+@section @command{dirname}: Strip last file name component
@pindex dirname
@cindex directory components, printing
@cindex non-directory suffix, stripping
@command{dirname} prints all but the final slash-delimited component of
-a string (presumably a file name). Synopsis:
+@var{name}. Slashes on either side of the final component are also
+removed. If the string contains no slash, @command{dirname} prints
+@samp{.} (meaning the current directory). Synopsis:
@example
dirname @var{name}
@end example
-If @var{name} is a single component, @command{dirname} prints @samp{.}
-(meaning the current directory).
+@var{name} need not be a file name, but if it is, this operation
+effectively lists the directory that contains the final component,
+including the case when the final component is itself a directory.
@basenameAndDirname
@smallexample
# Output "/usr/bin".
dirname /usr/bin/sort
+dirname /usr/bin//.//
# Output ".".
dirname stdio.h
1 otherwise.
@end display
+@node mktemp invocation
+@section @command{mktemp}: Create temporary file or directory
+
+@pindex mktemp
+@cindex file names, creating temporary
+@cindex directory, creating temporary
+@cindex temporary files and directories
+
+@command{mktemp} manages the creation of temporary files and
+directories. Synopsis:
+
+@example
+mktemp [@var{option}]@dots{} [@var{template}]
+@end example
+
+Safely create a temporary file or directory based on @var{template},
+and print its name. If given, @var{template} must include at least
+three consecutive @samp{X}s in the last component. If omitted, the template
+@samp{tmp.XXXXXXXXXX} is used, and option @option{--tmpdir} is
+implied. The final run of @samp{X}s in the @var{template} will be replaced
+by alpha-numeric characters; thus, on a case-sensitive file system,
+and with a @var{template} including a run of @var{n} instances of @samp{X},
+there are @samp{62**@var{n}} potential file names.
+
+Older scripts used to create temporary files by simply joining the
+name of the program with the process id (@samp{$$}) as a suffix.
+However, that naming scheme is easily predictable, and suffers from a
+race condition where the attacker can create an appropriately named
+symbolic link, such that when the script then opens a handle to what
+it thought was an unused file, it is instead modifying an existing
+file. Using the same scheme to create a directory is slightly safer,
+since the @command{mkdir} will fail if the target already exists, but
+it is still inferior because it allows for denial of service attacks.
+Therefore, modern scripts should use the @command{mktemp} command to
+guarantee that the generated name will be unpredictable, and that
+knowledge of the temporary file name implies that the file was created
+by the current script and cannot be modified by other users.
+
+When creating a file, the resulting file has read and write
+permissions for the current user, but no permissions for the group or
+others; these permissions are reduced if the current umask is more
+restrictive.
+
+Here are some examples (although note that if you repeat them, you
+will most likely get different file names):
+
+@itemize @bullet
+
+@item
+Create a temporary file in the current directory.
+@example
+$ mktemp file.XXXX
+file.H47c
+@end example
+
+@item
+Create a temporary file with a known suffix.
+@example
+$ mktemp --suffix=.txt file-XXXX
+file-H08W.txt
+$ mktemp file-XXXX-XXXX.txt
+file-XXXX-eI9L.txt
+@end example
+
+@item
+Create a secure fifo relative to the user's choice of @env{TMPDIR},
+but falling back to the current directory rather than @file{/tmp}.
+Note that @command{mktemp} does not create fifos, but can create a
+secure directory in which the fifo can live. Exit the shell if the
+directory or fifo could not be created.
+@example
+$ dir=$(mktemp -p "$@{TMPDIR:-.@}" -d dir-XXXX) || exit 1
+$ fifo=$dir/fifo
+$ mkfifo "$fifo" || @{ rmdir "$dir"; exit 1; @}
+@end example
+
+@item
+Create and use a temporary file if possible, but ignore failure. The
+file will reside in the directory named by @env{TMPDIR}, if specified,
+or else in @file{/tmp}.
+@example
+$ file=$(mktemp -q) && @{
+> # Safe to use $file only within this block. Use quotes,
+> # since $TMPDIR, and thus $file, may contain whitespace.
+> echo ... > "$file"
+> rm "$file"
+> @}
+@end example
+
+@item
+Act as a semi-random character generator (it is not fully random,
+since it is impacted by the contents of the current directory). To
+avoid security holes, do not use the resulting names to create a file.
+@example
+$ mktemp -u XXX
+Gb9
+$ mktemp -u XXX
+nzC
+@end example
+
+@end itemize
+
+The program accepts the following options. Also see @ref{Common options}.
+
+@table @samp
+
+@item -d
+@itemx --directory
+@opindex -d
+@opindex --directory
+Create a directory rather than a file. The directory will have read,
+write, and search permissions for the current user, but no permissions
+for the group or others; these permissions are reduced if the current
+umask is more restrictive.
+
+@item -q
+@itemx --quiet
+@opindex -q
+@opindex --quiet
+Suppress diagnostics about failure to create a file or directory. The
+exit status will still reflect whether a file was created.
+
+@item -u
+@itemx --dry-run
+@opindex -u
+@opindex --dry-run
+Generate a temporary name that does not name an existing file, without
+changing the file system contents. Using the output of this command
+to create a new file is inherently unsafe, as there is a window of
+time between generating the name and using it where another process
+can create an object by the same name.
+
+@item -p @var{dir}
+@itemx --tmpdir[=@var{dir}]
+@opindex -p
+@opindex --tmpdir
+Treat @var{template} relative to the directory @var{dir}. If
+@var{dir} is not specified (only possible with the long option
+@option{--tmpdir}) or is the empty string, use the value of
+@env{TMPDIR} if available, otherwise use @samp{/tmp}. If this is
+specified, @var{template} must not be absolute. However,
+@var{template} can still contain slashes, although intermediate
+directories must already exist.
+
+@item --suffix=@var{suffix}
+@opindex --suffix
+Append @var{suffix} to the @var{template}. @var{suffix} must not
+contain slash. If @option{--suffix} is specified, @var{template} must
+end in @samp{X}; if it is not specified, then an appropriate
+@option{--suffix} is inferred by finding the last @samp{X} in
+@var{template}. This option exists for use with the default
+@var{template} and for the creation of a @var{suffix} that starts with
+@samp{X}.
+
+@item -t
+@opindex -t
+Treat @var{template} as a single file relative to the value of
+@env{TMPDIR} if available, or to the directory specified by
+@option{-p}, otherwise to @samp{/tmp}. @var{template} must not
+contain slashes. This option is deprecated; the use of @option{-p}
+without @option{-t} offers better defaults (by favoring the command
+line over @env{TMPDIR}) and more flexibility (by allowing intermediate
+directories).
+
+@end table
+
+@cindex exit status of @command{mktemp}
+Exit status:
+
+@display
+0 if the file was created,
+1 otherwise.
+@end display
+
@node Working context
@chapter Working context
@opindex --file
Set the line opened by the file name specified in @var{device} instead of
the tty line connected to standard input. This option is necessary
-because opening a @acronym{POSIX} tty requires use of the @code{O_NONDELAY} flag to
-prevent a @acronym{POSIX} tty from blocking until the carrier detect line is high if
+because opening a @acronym{POSIX} tty requires use of the
+@code{O_NONDELAY} flag to prevent a @acronym{POSIX} tty from blocking
+until the carrier detect line is high if
the @code{clocal} flag is not set. Hence, it is not always possible
to allow the shell to open the device in the traditional manner.
of course).
Some settings are not available on all @acronym{POSIX} systems, since they use
-extensions. Such arguments are marked below with ``Non-@acronym{POSIX}'' in their
-description. On non-@acronym{POSIX} systems, those or other settings also may not
+extensions. Such arguments are marked below with
+``Non-@acronym{POSIX}'' in their description. On non-@acronym{POSIX}
+systems, those or other settings also may not
be available, but it's not feasible to document all the variations: just
try it and see.
@item ofill
@opindex ofill
@cindex pad instead of timing for delaying
-Use fill (padding) characters instead of timing for delays. Non-@acronym{POSIX}.
+Use fill (padding) characters instead of timing for delays.
+Non-@acronym{POSIX}.
May be negated.
@item ofdel
@opindex crtkill
Echo the @code{kill} special character by erasing each character on
the line as indicated by the @code{echoprt} and @code{echoe} settings,
-instead of by the @code{echoctl} and @code{echok} settings. Non-@acronym{POSIX}.
+instead of by the @code{echoctl} and @code{echok} settings.
+Non-@acronym{POSIX}.
May be negated.
@end table
@item rows @var{n}
@opindex rows
-Tell the tty kernel driver that the terminal has @var{n} rows. Non-@acronym{POSIX}.
+Tell the tty kernel driver that the terminal has @var{n} rows.
+Non-@acronym{POSIX}.
@item cols @var{n}
@itemx columns @var{n}
every environment variable. Otherwise, it prints the value of each
@var{variable} that is set, and nothing for those that are not set.
-The only options are a lone @option{--help} or @option{--version}.
-@xref{Common options}.
+The program accepts the following option. Also see @ref{Common options}.
+
+@table @samp
+
+@optNull{printenv}
+
+@end table
@cindex exit status of @command{printenv}
Exit status:
id [@var{option}]@dots{} [@var{username}]
@end example
+@vindex POSIXLY_CORRECT
By default, it prints the real user ID, real group ID, effective user ID
if different from the real user ID, effective group ID if different from
the real group ID, and supplemental group IDs.
+In addition, if SELinux
+is enabled and the @env{POSIXLY_CORRECT} environment variable is not set,
+then print @samp{context=@var{c}}, where @var{c} is the security context.
Each of these numeric values is preceded by an identifying string and
followed by the corresponding user or group name in parentheses.
@menu
* date invocation:: Print or set system date and time.
* arch invocation:: Print machine hardware name.
+* nproc invocation:: Print the number of processors.
* uname invocation:: Print system information.
* hostname invocation:: Print or set system name.
* hostid invocation:: Print numeric host identifier.
@exitstatus
+@node nproc invocation
+@section @command{nproc}: Print the number of available processors
+
+@pindex nproc
+@cindex Print the number of processors
+@cindex system information, printing
+
+Print the number of processing units available to the current process,
+which may be less than the number of online processors.
+If this information is not accessible, then print the number of
+processors installed. If the @env{OMP_NUM_THREADS} environment variable is
+set, then it will determine the returned value. The result is guaranteed to be
+greater than zero. Synopsis:
+
+@example
+nproc [@var{option}]
+@end example
+
+The program accepts the following options. Also see @ref{Common options}.
+
+@table @samp
+
+@item --all
+@opindex --all
+Print the number of installed processors on the system, which may
+be greater than the number online or available to the current process.
+The @env{OMP_NUM_THREADS} environment variable is not honored in this case.
+
+@item --ignore=@var{number}
+@opindex --ignore
+If possible, exclude this @var{number} of processing units.
+
+@end table
+
+@exitstatus
+
+
@node uname invocation
@section @command{uname}: Print system information
@smallexample
uname -a
-@result{} Linux dum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 i686 unknown unknown GNU/Linux
+@result{} Linux dum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 i686@c
+ unknown unknown GNU/Linux
@end smallexample
@smallexample
chcon [@var{option}]@dots{} @var{context} @var{file}@dots{}
-chcon [@var{option}]@dots{} [-u @var{user}] [-r @var{role}] [-l @var{range}] [-t @var{type}] @var{file}@dots{}
+chcon [@var{option}]@dots{} [-u @var{user}] [-r @var{role}] [-l @var{range}]@c
+ [-t @var{type}] @var{file}@dots{}
chcon [@var{option}]@dots{} --reference=@var{rfile} @var{file}@dots{}
@end smallexample
Synopses:
@smallexample
runcon @var{context} @var{command} [@var{args}]
-runcon [ -c ] [-u @var{user}] [-r @var{role}] [-t @var{type}] [-l @var{range}] @var{command} [@var{args}]
+runcon [ -c ] [-u @var{user}] [-r @var{role}] [-t @var{type}]@c
+ [-l @var{range}] @var{command} [@var{args}]
@end smallexample
Run @var{command} with completely-specified @var{context}, or with
Any additional arguments after @var{command}
are interpreted as arguments to the command.
-With neither @var{context} nor @var{command}, print the current security context.
+With neither @var{context} nor @var{command}, print the current
+security context.
The program accepts the following options. Also see @ref{Common options}.
Exit status:
@display
-1 if @command{chroot} itself fails
+125 if @command{chroot} itself fails
126 if @var{command} is found but cannot be invoked
127 if @var{command} cannot be found
the exit status of @var{command} otherwise
The program should not be a special built-in utility
(@pxref{Special built-in utilities}).
+Modifications to @env{PATH} take effect prior to searching for
+@var{command}. Use caution when reducing @env{PATH}; behavior is
+not portable when @env{PATH} is undefined or omits key directories
+such as @file{/bin}.
+
+In the rare case that a utility contains a @samp{=} in the name, the
+only way to disambiguate it from a variable assignment is to use an
+intermediate command for @var{command}, and pass the problematic
+program name via @var{args}. For example, if @file{./prog=} is an
+executable in the current @env{PATH}:
+
+@example
+env prog= true # runs 'true', with prog= in environment
+env ./prog= true # runs 'true', with ./prog= in environment
+env -- prog= true # runs 'true', with prog= in environment
+env sh -c '\prog= true' # runs 'prog=' with argument 'true'
+env sh -c 'exec "$@@"' sh prog= true # also runs 'prog='
+@end example
+
@cindex environment, printing
If no command name is specified following the environment
specifications, the resulting environment is printed. This is like
specifying the @command{printenv} program.
+For some examples, suppose the environment passed to @command{env}
+contains @samp{LOGNAME=rms}, @samp{EDITOR=emacs}, and
+@samp{PATH=.:/gnubin:/hacks}:
+
+@itemize @bullet
+
+@item
+Output the current environment.
+@example
+$ env | LC_ALL=C sort
+EDITOR=emacs
+LOGNAME=rms
+PATH=.:/gnubin:/hacks
+@end example
+
+@item
+Run @command{foo} with a reduced environment, preserving only the
+original @env{PATH} to avoid problems in locating @command{foo}.
+@example
+env - PATH="$PATH" foo
+@end example
+
+@item
+Run @command{foo} with the environment containing @samp{LOGNAME=rms},
+@samp{EDITOR=emacs}, and @samp{PATH=.:/gnubin:/hacks}, and guarantees
+that @command{foo} was found in the file system rather than as a shell
+built-in.
+@example
+env foo
+@end example
+
+@item
+Run @command{nemacs} with the environment containing @samp{LOGNAME=foo},
+@samp{EDITOR=emacs}, @samp{PATH=.:/gnubin:/hacks}, and
+@samp{DISPLAY=gnu:0}.
+@example
+env DISPLAY=gnu:0 LOGNAME=foo nemacs
+@end example
+
+@item
+Attempt to run the program @command{/energy/--} (as that is the only
+possible path search result); if the command exists, the environment
+will contain @samp{LOGNAME=rms} and @samp{PATH=/energy}, and the
+arguments will be @samp{e=mc2}, @samp{bar}, and @samp{baz}.
+@example
+env -u EDITOR PATH=/energy -- e=mc2 bar baz
+@end example
+
+@end itemize
+
+
The program accepts the following options. Also see @ref{Common options}.
Options must precede operands.
@table @samp
+@optNull{env}
+
@item -u @var{name}
@itemx --unset=@var{name}
@opindex -u
@display
0 if no @var{command} is specified and the environment is output
-1 if @command{env} itself fails
+125 if @command{env} itself fails
126 if @var{command} is found but cannot be invoked
127 if @var{command} cannot be found
the exit status of @var{command} otherwise
@display
0 if no @var{command} is specified and the niceness is output
-1 if @command{nice} itself fails
+125 if @command{nice} itself fails
126 if @var{command} is found but cannot be invoked
127 if @var{command} cannot be found
the exit status of @var{command} otherwise
Exit status:
@display
+125 if @command{nohup} itself fails, and @env{POSIXLY_CORRECT} is not set
126 if @var{command} is found but cannot be invoked
-127 if @command{nohup} itself fails or if @var{command} cannot be found
+127 if @var{command} cannot be found
the exit status of @var{command} otherwise
@end display
+If @env{POSIXLY_CORRECT} is set, internal failures give status 127
+instead of 125.
+
@node stdbuf invocation
@section @command{stdbuf}: Run a command with modified I/O stream buffering
Exit status:
@display
-1 if @command{su} itself fails
+125 if @command{su} itself fails
126 if subshell is found but cannot be invoked
127 if subshell cannot be found
the exit status of the subshell otherwise
still running after the specified time interval. Synopsis:
@example
-timeout [@var{option}] @var{number}[smhd] @var{command} [@var{arg}]@dots{}
+timeout [@var{option}] @var{duration} @var{command} [@var{arg}]@dots{}
@end example
-@cindex time units
-@var{number} is an integer followed by an optional unit; the default
-is seconds. The units are:
-
-@table @samp
-@item s
-seconds
-@item m
-minutes
-@item h
-hours
-@item d
-days
-@end table
-
@var{command} must not be a special built-in utility (@pxref{Special
built-in utilities}).
-The program accepts the following option. Also see @ref{Common options}.
+The program accepts the following options. Also see @ref{Common options}.
Options must precede operands.
@table @samp
+@item -k @var{duration}
+@itemx --kill-after=@var{duration}
+@opindex -k
+@opindex --kill-after
+Ensure the monitored @var{command} is killed by also sending a @samp{KILL}
+signal, after the specified @var{duration}. Without this option, if the
+selected signal proves not to be fatal, @command{timeout} does not kill
+the @var{command}.
+
@item -s @var{signal}
@itemx --signal=@var{signal}
@opindex -s
Send this @var{signal} to @var{command} on timeout, rather than the
default @samp{TERM} signal. @var{signal} may be a name like @samp{HUP}
or a number. Also see @xref{Signal specifications}.
-
@end table
+@cindex time units
+@var{duration} is an integer followed by an optional unit:
+@display
+@samp{s} for seconds (the default)
+@samp{m} for minutes
+@samp{h} for hours
+@samp{d} for days
+@end display
+A duration of 0 disables the associated timeout.
+
@cindex exit status of @command{timeout}
Exit status:
Historical implementations of @command{sleep} have required that
@var{number} be an integer, and only accepted a single argument
without a suffix. However, GNU @command{sleep} accepts
-arbitrary floating point numbers (using a period before any fractional
-digits).
+arbitrary floating point numbers. @xref{Floating point}.
The only options are @option{--help} and @option{--version}. @xref{Common
options}.
Similarly, factoring the eighth Fermat number @math{2^{256}+1} takes
about 20 seconds on the same machine.
-Factoring large prime numbers is, in general, hard. The Pollard Rho
+Factoring large numbers is, in general, hard. The Pollard Rho
algorithm used by @command{factor} is particularly effective for
numbers with relatively small factors. If you wish to factor large
numbers which do not have small factors (for example, numbers which
even when @var{first} is larger than @var{last}.
@var{first} also defaults to @samp{1}. So @code{seq 1} prints
@samp{1}, but @code{seq 0} and @code{seq 10 5} produce no output.
-Floating-point numbers
-may be specified (using a period before any fractional digits).
+Floating-point numbers may be specified. @xref{Floating point}.
The program accepts the following options. Also see @ref{Common options}.
Options must precede operands.
On most systems, seq can produce whole-number output for values up to
at least @math{2^{53}}. Larger integers are approximated. The details
-differ depending on your floating-point implementation, but a common
+differ depending on your floating-point implementation.
+@xref{Floating point}. A common
case is that @command{seq} works with integers through @math{2^{64}},
and larger integers may not be numerically correct:
@chapter File permissions
@include perm.texi
-@include getdate.texi
+@include parse-datetime.texi
@c What's GNU?
@c Arnold Robbins
@unnumberedsec Toolbox Introduction
This month's column is only peripherally related to the GNU Project, in
-that it describes a number of the GNU tools on your GNU/Linux system and how they
+that it describes a number of the GNU tools on your GNU/Linux system
+and how they
might be used. What it's really about is the ``Software Tools'' philosophy
of program development and usage.
@unnumberedsec Putting the Tools Together
Now, let's suppose this is a large ISP server system with dozens of users
-logged in. The management wants the system administrator to write a program that will
+logged in. The management wants the system administrator to write a
+program that will
generate a sorted list of logged in users. Furthermore, even if a user
is logged in multiple times, his or her name should only show up in the
output once.
@command{uniq} does. However, @command{uniq} has other uses for which one
cannot substitute @samp{sort -u}.
-The administrator puts this pipeline into a shell script, and makes it available for
+The administrator puts this pipeline into a shell script, and makes it
+available for
all the users on the system (@samp{#} is the system administrator,
or @code{root}, prompt):
projects / platform / upstream / coreutils.git / blobdiff