diff options
| author | Lorry Tar Creator <lorry-tar-importer@lorry> | 2007-03-22 21:23:21 +0000 |
|---|---|---|
| committer | Lorry Tar Creator <lorry-tar-importer@lorry> | 2007-03-22 21:23:21 +0000 |
| commit | cbf5993c43f49281173f185863577d86bfac6eae (patch) | |
| tree | 90737c96cf15b97273a2bdc5950b3cf09f1d94ca /doc | |
| download | coreutils-tarball-cbf5993c43f49281173f185863577d86bfac6eae.tar.gz | |
coreutils-6.9coreutils-6.9
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 1971 | ||||
| -rw-r--r-- | doc/Makefile.am | 74 | ||||
| -rw-r--r-- | doc/Makefile.in | 976 | ||||
| -rw-r--r-- | doc/constants.texi | 1 | ||||
| -rw-r--r-- | doc/coreutils.info | 15863 | ||||
| -rw-r--r-- | doc/coreutils.texi | 14638 | ||||
| -rw-r--r-- | doc/fdl.texi | 452 | ||||
| -rw-r--r-- | doc/getdate.texi | 553 | ||||
| -rw-r--r-- | doc/perm.texi | 604 | ||||
| -rw-r--r-- | doc/stamp-vti | 4 | ||||
| -rw-r--r-- | doc/version.texi | 4 |
11 files changed, 35140 insertions, 0 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog new file mode 100644 index 0000000..38b5f9d --- /dev/null +++ b/doc/ChangeLog @@ -0,0 +1,1971 @@ +2007-03-21 Eric Blake <ebb9@byu.net> + + * coreutils.texi (md5sum invocation): Document escapes in output + format. Reported by Armijn Hemel. + +2007-03-15 Paul Eggert <eggert@cs.ucla.edu> + + Fix manual in response to bug reports by Dan Jacobson. + * coreutils.texi (sort invocation): Explain numeric sorts better. + Compress self-congratulation into a simple "comparison is exact" + notice; the --general-numeric-sort option already explains the + tradeoffs. + (seq invocation): Add example of -f. + +2007-03-12 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cp invocation): Mention that --preserve=timestamps + doesn't preserve time stamps on symbolic links. + Reported by Polo Talnir in <https://bugzilla.redhat.com/230866>. + +2007-02-27 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (df invocation): With -P, the default block size + and output format is not affected by DF_BLOCK_SIZE, BLOCK_SIZE, or + BLOCKSIZE. + +2007-01-30 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi + (Input processing in ptx, mkdir invocation, rmdir invocation): + @item -> @itemx to fix some typos. + +2007-01-30 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (mkdir invocation): Say how to set the file + permission bits of a parent directory with mkdir -p. + +2007-01-29 Jim Meyering <jim@meyering.net> + + Document new syntax: "chown +0:+287 file", "chgrp +99 file" + * coreutils.texi (Disambiguating names and IDs): New section. + (chown invocation, chgrp invocation): Mention the new syntax + with an xref to the new section. + +2007-01-19 Jim Meyering <jim@meyering.net> + + * coreutils.texi (ls: General output formatting): Mention the + workarounds to accommodate the Apple Terminal bug. + +2007-01-04 Jim Meyering <jim@meyering.net> + + * coreutils.texi (base64 invocation): When decoding, newlines + are always accepted. + +2007-01-03 Jim Meyering <jim@meyering.net> + + Document what the ".0" in e.g., "-k 2,3.0" means, and... + * coreutils.texi (sort invocation): ... that it can be applied to the + field-end spec, but not the field-start one. Patch from Evan Hunt. + +2006-12-21 Jim Meyering <jim@meyering.net> + + * coreutils.texi (dd invocation): Improve the documentation + for bs, ibs, obs, and cbs. Suggestion from Dan Jacobson. + Patch by Olivier Delhomme. + (dd invocation): Add to the description of cbs. + (dd invocation): Specify that bs=N overrides only any + _preceding_ ibs and obs settings. Spotted by Andreas Schwab. + +2006-12-14 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Remove two doubled words. + (Treating / specially): With --preserve-root, chgrp and chown + will not modify "/", even through a symlink. + +2006-11-28 Jim Meyering <jim@meyering.net> + + * perm.texi (Mode Structure): Fix typo: s/setgid/setuid/. + Reported by Georg Neis as Debian bug 400778. + +2006-10-27 Jim Meyering <jim@meyering.net> + + * coreutils.texi (wc invocation): When giving the order in which + the various "counts" are listed, also mention "maximum line length". + Prompted by a report from Vincent LeFevre. + +2006-10-23 Jim Meyering <jim@meyering.net> + + * coreutils.texi (rm invocation): Describe --one-file-system. + +2006-09-26 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (groups invocation): "groups" no longer prefixes + the output with "user :" unless more than one user is specified. + +2006-09-19 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (cp invocation): Say that -i and -f are + independent. Clarify -i's behavior. + (Disk usage): Clarify intro. Problem reported by Van Ly. + +2006-09-08 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (tail invocation): Ignore -f when standard input + is a FIFO, too. + +2006-09-02 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (Treating / specially): --preserve-root is + now the default for rm. + (rm invocation): Likewise. Also, document that you can't + remove `.' or `..'. Use the POSIX term "root directory" + rather than the more-ambiguous "file system root". + +2006-08-22 Paul Eggert <eggert@cs.ucla.edu> + + * .cvsignore: Add Makefile.in, coreutils.html, coreutils.pdf, + coreutils.ps, coreutils.tps. Remove coreutils.cm (dunno what it + is, but the makefile doesn't mention it). Remove coreutils.info + as it is subsumed by coreutils.info*. + +2006-08-22 Jim Meyering <jim@meyering.net> + + * .cvsignore: Add files that are now generated by ../bootstrap. + +2006-08-20 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.in, fdl.texi, getdate.texi: + Remove from CVS, since ../bootstrap generates them automatically. + +2006-08-17 Jim Meyering <jim@meyering.net> + + * Makefile.am (EXTRA_DIST): Reflect doclicense.texi->fdl.texi renaming. + +2006-08-17 Paul Eggert <eggert@cs.ucla.edu> + + * ChangeLog: Add copyright notice. + * Makefile.am: Likewise. + * getdate.texi: Likewise. + * perm.texi: Likewise. + * getdate.texi: Update to version 1.2 of the GNU FDL. + * coreutils.texi: Likewise. + (Copying This Manual): Renamed from GNU Free Documentation License. + Now an appendix. Include fdl.texi rather than doclicense.texi. + * fdl.tex: Renamed from doclicense.texi. Latest version from FSF. + * perm.texi: Add copyright notice. + +2006-08-15 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (df invocation): df exits nonzero if it outputs + nothing. + +2006-08-09 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (dd invocation): Warn about oflag=append without + conv=notrunc. See Debian bug 373736. + +2006-08-08 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (shuf invocation, Random sources): New sections. + (Operating on sorted files): Add shuf. + (sort invocation, shred invocation): New option --random-source. + (sort invocation): Fix typo: -R -> -r. + +2006-07-28 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (install invocation, mkdir invocation): + Add cross-references to Directory Setuid and Setgid. + (install-invocation): The default mode is no longer equivalent to 755. + * perm.texi (Changing Special Mode Bits): Clarify u+s versus + a+s versus +s, and likewise for g+s. + (Numeric Modes): Bring back example of 0055 == 55. 4755 no + longer clears setgid bit on directories. + (Directory Setuid and Setgid): Numeric modes now affect setuid + and setgid on directories only if they set these bits. This + is so that leading 0 has no effect on numeric modes. + +2006-07-26 Jim Meyering <jim@meyering.net> + + * coreutils.texi (What information is listed): Mention that missing + pieces of information are marked with "?". From Paul Eggert. + +2006-07-25 Paul Eggert <eggert@cs.ucla.edu> + + * perm.texi (Directory Setuid and Setgid): Explain that this is a + GNU extension, and that other systems behave differently here. + +2006-07-22 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (What information is listed): Clarify that the + restricted deletion flag is another name for the sticky bit. + * perm.texi (Mode Structure): The restricted deletion flag + restricts only unprivileged users. + (Mode Structure, Symbolic Modes, Numeric Modes): Be more careful + about distinguishing file mode bits from permissions bits, + and about execute versus search permission. The FreeBSD command + is chflags, not chrflags. + +2006-07-16 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi: Change GNU to @acronym{GNU} in a few places. + Use "set-user-ID" and "set-group-ID" a bit more consistently. + Use "appropriate privileges" rather than "super-user" a bit + more consistently. + (install invocation): Parent directories are now 755 without uid + or gid changing. The default mode is now 0755, not 755. + (mkdir invocation): Rewrite the top-level usage description, since + I couldn't easily follow the old one. It's now 3 lines not 8. + For -m, describe file permission bits versus other bits, and note + that mkdir is atomic if you don't mention special bits. + (chmod invocation): Mention what chmod does to setgid and setuid bits. + * perm.texi (Mode Structure): Modernize the explanation of the + setuid and setgid bits on directories. + (Changing Special Mode Bits): Mention that a implies both u and g + for s. Cross reference to new node. + (Numeric Modes): Don't claim that 0055 is the same as 55; this isn't + true any more. Mention new node. + 4755 is now like u=rwxs,go=rx,g-s, not like u=rwxs,go=rx. + (Directory Setuid and Setgid): New node. + +2006-07-08 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Squeezing): Separate doubled "the", so typo-checkers + don't complain. + + * Makefile.am (check-texinfo): Enforce the zeros vs. zeroes consistency. + +2006-07-08 Ralf Wildenhues <Ralf.Wildenhues@gmx.de> + + * coreutils.texi: Fix some typos. Use `zeros' consistently (both + `zeros' and `zeroes' are correct). + +2006-07-01 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (tail invocation): With no operand, 'tail -f' now + silently ignores the '-f' only if standard input is a FIFO or pipe + and POSIXLY_CORRECT is set. + +2006-06-30 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (seq invocation): seq now uses long double + internally rather than double. It now defaults to a minimal fixed + point format if possible. It lets you use %a, %A, %E, %F, %G. + Don't assume printf doesn't work for numbers that fit in 64 but + not 32 bits; typically they work these days. Improve discussion + of large integers and update the rounding-error numbers. + +2006-06-28 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (sort invocation): 'sort +1 -2' is now supported + even when conforming to POSIX 1003.1-2001, since this is a pure + extension to POSIX. + +2006-06-27 Jim Meyering <jim@meyering.net> + + * coreutils.texi (wc invocation): Remove ./ prefix from example. + From Padraig Brady. + +2006-06-26 Jim Meyering <jim@meyering.net> + + * coreutils.texi (wc invocation): Spell out `--files0-from' in + the example. Suggestion from Bob Proulx. + + * coreutils.texi (wc invocation): Document new --files0-from option. + +2006-06-20 Eric Blake <ebb9@byu.net> + + * coreutils.texi (sleep invocation): Document that accepting + multiple arguments and suffixes are extensions. + Reported by Dan Jacobson. + +2006-06-12 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.am (check-texinfo): Use $(_W) and $(W_) instead of + assuming grep -w (which is not portable). + +2006-05-27 Ralf Wildenhues <Ralf.Wildenhues@gmx.de> + + * Makefile.am: Use `AM_MAKEINFOFLAGS' rather than + overwriting `MAKEINFO', so that `missing' can do its job. + + * Makefile.am (check-texinfo): Use `$(EGREP)' instead of `grep -E'. + (check-texinfo): Use literal `{' only in brackets, i.e., [{] or [}], + to avoid triggering an error from Solaris 2.6's grep. + +2006-05-25 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (sort invocation): Remove mention of --seed, since + it's going away. + +2006-05-04 Eric Blake <ebb9@byu.net> + + * coreutils.texi (Examples of date): Give example of @seconds. + +2006-05-03 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (head invocation, tail invocation, sort invocation): + Give advice about porting to hosts that support only obsolete syntax. + Problem reported by Zack Weinberg. + +2006-04-23 Francesco Montorsi <fr_m@hotmail.com> + + * coreutils.texi (Which files are listed): Describe new option: + --group-directories-first. + +2006-04-17 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (What information is listed): Add P for Solaris + 10 ports. Add commented-out entries for other types that POSIX + says are possible, or that I observed in FreeBSD documentation. + +2006-04-18 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Input processing in ptx): Remove mention of the + default --ignore file, /usr/local/lib/eign. That file has never + been used. Reported by Eric Blake. + +2006-04-12 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (expr invocation): expr exit status is 3 only for + internal errors now; 2 is also for invalid values in expressions. + + (What information is listed): Document 'ls' type letters. + Problem reported by Lincoln Martin. + +2006-04-09 Ori Avtalion <oavtal@bezeqint.net> + + * coreutils.texi (Top): Add 'hostid' to System context menu line. + (trivial change) + +2006-03-22 Eric Blake <ebb9@byu.net> + + * coreutils.texi (General options in ptx): Undocument --copyright. + +2006-03-27 Eric Blake <ebb9@byu.net> + + * coreutils.texi (dirname invocation): Macro in previous patch + was too broad. + +2006-03-11 Eric Blake <ebb9@byu.net> + + * coreutils.texi (basename invocation, dirname invocation): + Improve documentation to match recent // patches. + +2006-03-23 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (nohup invocation): nohup now redirects stderr to + nohup.out if stdout is closed and stderr is a tty. + +2006-03-05 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (dd invocation): New flags directory, nolinks. + Alphabetize nofollow. + +2006-02-17 Simon Josefsson <jas@extundo.com> + + * coreutils.texi: Add base64 section. + +2006-02-20 Eric Blake <ebb9@byu.net> + + * coreutils.texi (rm invocation): Fix typo in last patch. + (paste invocation): Fix whitespace. + +2006-02-18 Eric Blake <ebb9@byu.net> + + * coreutils.texi (rm invocation): Document new -I option, and new + --interactive behavior. + +2006-02-12 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Character sets): Don't say that an unknown + backslash-escape causes an error message -- it doesn't. + Mention that `\' also removes any special significance, so + is useful for [, ], *, -. Prompted by Richard Neill in + http://savannah.gnu.org/bugs/index.php?func=detailitem&item_id=14937 + +2006-02-01 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (od invocation): Warn that -t a ignores the high + order bit. + +2006-01-30 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (tail invocation): In the obsolete usage, the + count is optional, so put square brackets around it. + +2006-01-02 Paul Eggert <eggert@cs.ucla.edu> + + * getdate.texi (General date syntax): Invalid dates are rejected. + (Time of day items): Mention the possibility of leap seconds. + Problem reported by Dr. David Alan Gilbert. + + * coreutils.texi: Use @acronym around "ISO" uniformly. + (Date conversion specifiers): Explain %g, %G, and %V a bit better. + +2006-01-02 Jim Meyering <jim@meyering.net> + + * coreutils.texi (tail invocation): Say that --retry + is useful `mainly' (not `only') when following by name. + +2006-01-01 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi, perm.texi: Clarify file mode bits versus + file permission bits. + * coreutils.texi (mkfifo invocation, mknod invocation): -m + affects only file permission bits. + +2005-12-29 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (sort invocation): Clarify that a blank is a space + or a tab. + +2005-12-15 Jim Meyering <jim@meyering.net> + + * coreutils.texi (stat invocation) [--printf]: Describe new option. + [--format]: Add example. Distinguish from --printf. + Sort option descriptions. + +2005-12-05 Andreas Gruenbacher <agruen@suse.de> + + * coreutils.texi (ls): Clarify the Alternate Access Method description. + (cp): Clarify that --preserve=mode also preserves acls. + +2005-12-12 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (sort invocation): Clarify explanation of + --random-sort, and use a simpler example. + +2005-12-10 Frederik Eaton <frederik@ofb.net> + + * coreutils.texi (sort invocation): Add --random-sort (-R) and --seed. + +2005-12-07 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (dd invocation): New noatime flag. + +2005-11-25 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (df invocation): Document treatment of dummy file + systems better. + +2005-11-16 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (ln invocation): ln -v now outputs lines only for + successful links. + (tail invocation): Say that the obsolete form uses exactly one + option and at most one file. + +2005-11-13 Jim Meyering <jim@meyering.net> + + * perm.texi (Mode Structure): Capitalize two sentences in an + enumerated list and fix a typo. From Aaron Hawley. + +2005-11-08 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (Formatting file timestamps): ls now defaults to + --time-style='locale', which in turn acts like + --time-style='posix-long-iso' if the locale settings are messed up. + +2005-11-02 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (rm invocation): Don't mention --directory (-d). + +2005-11-01 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (tail invocation): Describe obsolete usages + like "tail -2" more precisely. + (touch invocation): The old usage works only for 1969-1999 now. + +2005-08-28 David Madore <david.madore@ens.fr> + + * coreutils.texi: Document SHA-1 and SHA-2 utilities. + +2005-10-15 Paul Eggert <eggert@cs.ucla.edu> + + * doc/coreutils.texi (Top, General output formatting, dir invocation): + (vdir invocation): Don't document the old v and d commands. + +2005-10-15 Jim Meyering <jim@meyering.net> + + * coreutils.texi (du invocation): Document du's -m option, + now that we've decided to keep it. + (who invocation): Remove documentation for deprecated --idle (-i). + +2005-10-13 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Avoid a few overfull/underfull hboxes. + +2005-09-24 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (touch invocation): + "touch -" now touches standard output. + +2005-09-17 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (who invocation): Remove a stray '+'. + +2005-09-15 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (uname invocation): uname -a no longer generates + the -p and -i outputs if they are unknown. + +2005-09-13 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (Time conversion specifiers, Options for date): + Document date --rfc-3339 and new specifiers %:z, %::z, %:::z. Use + "date and time" consistently; the old version sometimes said "time + and date". Fix a minor bug in the documentation for --rfc-2822: + it claimed day-of-month < 10 had leading space, not leading zero. + Use a consistent format for terms like "RFC". + (uname invocation): Mention that Linux outputs "unknown" for + -i and -p. + +2005-09-08 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (nice invocation): Document "niceness" versus + "nice value" versus "scheduling priority". + +2005-09-07 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (nice invocation): Use "niceness", not "nice value" + to talk about nice values offset by -20. Don't use the word + "priority" when niceness is intended. + +2005-08-15 Jim Meyering <jim@meyering.net> + + * coreutils.texi (join invocation): Itemize the defaults. + From Karl Berry. + +2005-08-12 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cp invocation, mv invocation): Remove square + brackets in --reply=[HOW]. Reported by Oscar Liljeblad. + +2005-07-19 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (md5sum invocation): --check now allows multiple + FILE inputs. + +2005-07-18 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (false invocation): + Mention that false is often built-in, and that it exits + with status >1 on some hosts. + (true invocation): Remove now-incorrect "non-POSIX mode" reference. + +2005-07-15 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (nohup invocation): POSIXLY_CORRECT no longer + affects nohup's behavior. Input is redirected from /dev/null. + +2005-07-11 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (cat invocation): Remove -B or --binary option + (available on MS-DOS-like platforms only). Explain when text and + binary mode are used now. + (md5sum invocation): -b actually does have an effect on Unix: it + causes "*" to be output. Explain when text and binary mode are + used now. + +2005-07-03 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cp invocation): Mark --reply as deprecated. + (mv invocation): Likewise. + +2005-06-24 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cp invocation): Clarify how --reply=no works. + +2005-06-14 William Brendling <wbrendling@gmail.com> + + * coreutils.texi (du invocation): New options --last-time and + --time-style. + +2005-06-19 Jim Meyering <jim@meyering.net> + + * coreutils.texi (ln invocation): Change a few `paths' to `file names'. + * Makefile.am (check-texinfo): Also catch uses of path, pathname. + +2005-06-17 Jim Meyering <jim@meyering.net> + + * coreutils.texi (shred invocation): Clarify that shred + works on ext3 as long as it's not in data=journal mode. + Patch from Mark Melahn. + +2005-06-16 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Backup options): Undocument --version-control=S (-V). + +2005-06-07 Jim Meyering <jim@meyering.net> + + * coreutils.texi (ln invocation): Examples, from Bob Proulx. + +2005-06-01 Paul Eggert <eggert@cs.ucla.edu> + + Use "file name" when talking about file names, instead of "filename" + or "path", as per the GNU coding standards. + * coreutils.texi (readlink invocation): "path component" -> + "component", since we don't use the POSIX "path" nomenclature. + +2005-05-11 Paul Eggert <eggert@cs.ucla.edu> + + * getdate.texi (General date syntax): Don't say that date + date --iso-8601=ns generates acceptable dates; it doesn't yet. + Problem reported by Nic Ferrier. + +2005-05-06 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (dd invocation): New flags "binary" and "text". + +2005-05-04 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (chmod invocation): chmod -w complains if its + behavior differs from what chmod a-w would do. + +2005-05-02 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (ls invocation): ls --indicator-style=directory + renamed to ls --indicator-style=slash, to avoid confusion with ls + --directory. + +2005-04-28 Paul Eggert <eggert@cs.ucla.edu> + + * perm.texi (Mode Structure, Changing Special Permissions): + (Conditional Executability, Numeric Modes): + These days the sticky bit is more often uses as the restricted + deletion flag, so modernize the discussion about this. + (Mode Structure): Linux/GNU -> GNU/Linux. + (Symbolic Modes): Don't imply that "+ur" or "u" is valid. + (Setting Permissions): Don't imply that "+t" is invalid. + Use "rwx" rather than the less-common "rxw" in an example. + (Copying Permissions): Say that ugo is a replacement for + a string of the other letters. Add spaces around examples. + Use "set-user-ID" rather than "set user ID" to avoid ambiguity. + Use "+t" rather than "o+t", since POSIX doesn't specify the latter. + Mention which combinations are portable and which are GNU. + (Numeric Modes): Don't imply they aren't portable; they are + nowadays. + +2005-04-26 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (Standards conformance): Do not mention head -10, + since it now works the same regardless of POSIX version. + (od invocation): -w N -> -w[N]. + (pr invocation): -S STRING -> -SSTRING. + (fold invocation): -WIDTH works even when conforming to POSIX + 1003.1-2001. + (head invocation, tail invocation): Likewise for -NUM. + (split invocation): Likewise for -LINES. + (uniq invocation): Likewise for -N. + (expand invocation, unexpand invocation): Likewise for -TAB. + (nice invocation): Likewise for -ADJUSTMENT. + (sort invocation): Clarify explanation of +N option. + (uniq invocation): Likewise. + (join invocation): Remove special case for --help, --version. + (touch invocation): Clarify explanation of date options. + (Options for date): -I timespec -> -I[timespec]. + +2005-04-23 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (install invocation): Use a= instead of 0 for + the point of departure for -m, and explain what it meeams. + (mkdir invocation, mkfifo invocation, mknod invocation): + The umask does not affect the point of departure. + Problem reported by Mike Stone. + +2005-04-11 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi: For consistency, standardize on "user ID" rather + than "uid" or "UID" or "user id". Similarly for "group ID". + +2005-04-09 Jim Meyering <jim@meyering.net> + + * coreutils.texi (rm invocation): Say that --recursive removes + listed directories too, not just their contents. + +2005-04-08 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (dd invocation): Document the distinction between + INFO and USR1 for dd, and the effect of POSIXLY_CORRECT here. + +2005-04-05 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (cat invocation, chown invocation) + (chgrp invocation, basename invocation, dirname invocation): + Add examples, which are copies of the examples newly added + to the usage messages. + (ln invocation): Use same format as other examples above, + for consistency. + +2005-03-26 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi: Clarify NUL vs null byte vs null character. + +2005-03-18 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (nohup invocation): Clarify nohup.out creation. + +2005-03-11 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (Formatting file timestamps): Very long timestamps + may be treated as errors. + +2005-03-08 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (date invocation): Use an example that makes it + clear tha the default date use space-padded day of month. + Replace "directive" with "conversion specifier" to be consistent + with POSIX. All uses changed. + Fix menu RHS to match actual directive lists. + (Time conversion specifiers): Renamed from Time directives. + Use @samp consistently, sometimes instead of @code. + Consistently ention which specifiers are GNU extensions. + Give more examples (in some cases, instead of ranges). + Say why %F is preferred for dates. + (Date conversion specifiers): Renamed from Date directives. + Likewise for other changes. + (Padding and other flags): Correct the description. + Document #. Give an example for %9B. + +2005-02-23 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi: Adjust to match current strftime.c. + (Time directives): Say that %k, %l, and %P are GNU extensions. + For %p and %P, mention handling of noon and midnight. + For %s, use ISO 8601, and mention handling of leap seconds. + For %S, clarify mention of leap seconds. + For %T, say that it's the same as %H:%M:%S. + For %X, don't say that it must be the same as %H:%M:%S. + For %z and %Z, clarify which time zones are used. These options + are now affected by --date, so don't claim that they're not. + (Date directives): %C is now all but the last two chars of %Y. + For %D, say that it's equivalent to %m/%d/%y. + For %e, use blank in example. + For %h, use @code for %b. + For %Y, mention what happens with outlandish years. + (Padding and other flags): Renamed from Padding. + Mention that the flags are GNU extensions. + Mention the 0 and ^ flags. + Mention field widths an modifiers. + (Examples of date): - is a flag, not a modifier. + +2005-01-07 Jim Meyering <jim@meyering.net> + + * coreutils.texi (sort invocation): Specify that a string + of zero digits is interpreted as 0. Reported by Ulrich Hermisson. + +2005-01-04 Jim Meyering <jim@meyering.net> + + * coreutils.texi (shred invocation): Clarify that shred works fine + with journaled file systems that are configured not to journal + file system data. Also mention BFS and NTFS. + +2004-12-15 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (ls invocation): Change minor problem to be + "subdirectory not found", since top-level trouble is now serious. + (dircolors invocation): Quote argument to eval. Problem reported + by Stephane Chazelas. + +2004-12-11 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (join invocation): Mention that blank separators + in the -o option need to be quoted. Problem reported by Phil Clayton. + +2004-12-10 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (id invocation): -G also prints main group. + Problem reported by Tim Waugh. + +2004-12-09 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (ls invocation): Document new "ls" exit status. + +2004-12-08 Paul Eggert <eggert@cs.ucla.edu> + + * getdate.texi (Time of day items, Time zone items): + Describe new formats +00:00, UTC+00:00. + +2004-12-04 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cut invocation): Say when --complement is useful. + +2004-10-01 Paolo Bonzini <bonzini@gnu.org> + + * coreutils.texi (cut invocation): Document --complement and + adjust the documentation of -b, -c, -f. + +2004-11-27 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (du invocation): Use if=/dev/null rather + than :|. Problem reported by Dan Jacobson. + Use "seek=2GiB" rather than the wordier "seek=`echo '2^31'|bc`". + Say "KiB" not the (inaccurate) "kilobytes". + Similarly for "GiB" and "gigabytes". + +2004-11-16 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi: Changes inspired by Debian coreutils 5.2.1-2. + (General output formatting): -x doesn't have an operand. + (Formatting the file names): Warn that even with -N unprintable + chars are still printed as '?' some times. + (rm invocation): Reword rm -d to note that it's sometimes useful + on non-directories. + (logname invocation, users invocation, who invocation): + The utmp and wtmp file names vary from system to system. + + * getdate.texi (General date syntax): "next" is 1, not 2. + Document that "second" isn't allowed as an ordinal number. + +2004-11-15 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (dd invocation): Reword the new dd message. + +2004-11-14 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (dd invocation): dd now outputs total bytes, + seconds, and bytes per second. + +2004-11-03 Paul Eggert <eggert@cs.ucla.edu> + + * Makefile.am (_W, W_): New macros. + (check-texinfo): Use them instead of assuming grep -w (which is not + portable). + +2004-10-29 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi: Document TZ better, and adjust to new getdate.texi. + (Top): Update menu. + (pr invocation, Formatting file timestamps, touch invocation, + stat invocation, who invocation, date invocation, Options for date): + Mention TZ. + * getdate.texi: Sync from gnulib. + +2004-10-28 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (Standards conformance): Use "head -10" rather + than "head -1" as example of obsolete usage, since the POSIX + consensus is that "head -1" could be supported even if we don't + yet have clear consensus on "head -10". See today's revision to + the SUS FAQ + <http://www.opengroup.org/austin/papers/single_unix_faq.html>. + +2004-10-24 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (pathchk invocation): Options must precede operands. + +2004-10-17 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (pathchk invocation): Overall lengths are + OS limits, not file system limits. Component length checks + apply to all components, not merely to existing ones. Say + that nonexistent names are not errors. For -p, omit all + checks based on the underlying file system, not merely length + checks. Explain what the portable file name character set is. + +2004-10-15 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (printf invocation): Mention ISO/IEC 10646 as + well as Unicode. Various minor formatting cleanups. + +2004-10-13 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (sort invocation): Move LC_ALL, LC_COLLATE + index entries to proper paragraph. + +2004-10-12 Jim Meyering <jim@meyering.net> + + * Makefile.am (check-texinfo): Add `builtin' and `builtins' to + the list of words to avoid. + +2004-10-11 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (Special built-in utilities): New node. + (printf invocation): builtin -> built-in, for consistency + with POSIX terminology. + (test invocation, pwd invocation): + Use specific rather than generic language to warn about + built-in commands. + (chroot invocation, env invocation, nice invocation, nohup invocation): + Warn that command must not be a special built-in. + (env invocation): Warn about environment variables with unusual + spellings, or duplicates. + +2004-09-26 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (ls invocation): Document "ls --hide". + +2004-09-24 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (chmod invocation): Warn about "chmod -w file". + +2004-09-23 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (tail invocation): Fix bugs in the description of + the obsolete syntax (e.g., it does not support -k or -m). Warn + about usages like "tail -" and "tail -c 4" that are ambigous on + older systems. + +2004-09-20 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (mv invocation, rm invocation): Say "the response + is affirmative" rather than "the response begins with y or Y", + so that the documentation is accurate in non-English locales. + Problem reported by Munzir Taha. + +2004-09-18 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (dd invocation): Distinguish between options + (e.g., --help) and operands (e.g., if=file). Move miscellaneous + stuff after the operand descriptions, for clarity. + +2004-09-09 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (sort invocation): -u disables the last-resort + comparison, too. Revamp its description. + (test invocation): Document -r, -w, -x more carefully. + +2004-09-08 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (Common options): Some programs don't reorder + options. + (tr invocation, echo invocation, printf invocation, test invocation, + expr invocation, basename invocation, chroot invocation, + nice invocation, nohup invocation, seq invocation): + This program doesn't reorder options. + (tr invocation): Mention --help, --version, --. + (echo invocation): Mention that -- isn't special. + (test invocation): Mention that the expression is optional, + and that test ! EXPR is like ! test EXPR. + Mention that -h and -L don't dereference symlinks. + (expr invocation): Mention --help, --version. + + * coreutils.texi (sort invocation): Add remarks about sort -u + versus sort | uniq. Prompted by a question from Andrew Noymer. + +2004-09-06 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (od invocation): Several changes for POSIX + and FreeBSD compatibility. Add support for XSI syntax + (POSIX 1003.1-2004). Rename -s[N] to -S N. Remove documentation + for -h. -i is now -t dI (not d2) and -l is now -t dL (not d4). + +2004-09-05 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (String tests): Improve quality of warning about + quoting strings for the shell. + +2004-09-03 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (dd invocation): Specify which conversion options + are mutually exclusive. Give a bit more detail about ascii, + ebcdic, and ibm conversions. + +2004-08-24 Paul Eggert <eggert@cs.ucla.edu> + + POSIX-conformance fixes for "expand" and "unexpand". + * coreutils.texi: Standardize on "tab stop" (the POSIX usage) + rather than "tabstop". + (unexpand invocation): Use "blank" rather than "space" when + POSIX requires "blank". Define "blank". Initial blanks are + converted even if there's just one. For -a, convert two or + more blanks only if they occur just before a tab stop. + +2004-08-19 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (chown invocation): Fix synopsis: + group must always be preceded by separator. + "chown : file" and "chown '' file" don't change the owner or group. + Update the explanation of what happens to the set-user-ID or + set-group-ID bits, e.g., they sometimes are not cleared if they + denote mandatory locking. Change "find"-oriented examples to use + chown -h. + +2004-08-18 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (printf invocation): Clarify how "printf" is + supposed to work with extra arguments, missing arguments, etc. + +2004-08-10 Paul Eggert <eggert@cs.ucla.edu> + + POSIX-conformance fixes for "-" used as an operand. + * coreutils.texi (Common options): Clarify that "-" means + stdin/stdout only when it is an operand, not when it is an + option-argument. + (shred invocation): "shred -- -" is equivalent to "shred -", + not to "shred ./-". + (tee invocation): "tee -" means to copy (again) to stdout. + +2004-07-25 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (nice invocation): Document the "nice value", and + how it affects the scheduling priority. (The old documentation + implied that the nice value equaled the scheduling priority, which + isn't accurate.) Document that the range of nice values might + exceed -20..19. Specify what happens when you give a nice value + that is out of range, or when you don't have permissions to lower + the nice value. Bash doesn't have a builtin 'nice', so don't say + "most shells" have one. + +2004-04-03 Dmitry V. Levin <ldv@altlinux.org> + + * coreutils.texi (readlink invocation): Document new + "readlink -f" behaviour and new canonicalize options, -e and -m. + +2004-07-02 Jim Meyering <jim@meyering.net> + + * Makefile.am (check-texinfo): Disallow `filename' in .texi files. + Spell it like `file name' instead, to be consistent. + Fail if a @footnote directive follows non-punctuation. + Fail upon use of @url. Use @uref instead. + +2004-07-01 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (Common options, Target directory, cp invocation, + install invocation, mv invocation, ln invocation): Add -t as a + short option for --target-directory, and -T as a short option for + --no-target-directory. Clean up relevant synopses a bit, so that + the language is similar for all. + +2004-06-30 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi: Put the right amount of space at sentence ends. + Make sure "i.e." and "e.g." are followed by commas (the GNU style). + Put blank lines before and after every @example, prefer the + previous line to end in ":" (when not a sentence end, for consistency), + and prepend @noindent to the following line when appropriate. + In examples, use "--" arguments when needed to prevent undesired + interpretation of operands as options. + Use "file name" rather than "filename", as per the GNU coding standards. + Remove unwanted spaces before @footnote. + Use "---" when appropriate, instead of " -- ". + Use "name" (or something like that) rather than "path" or "pathname", + since the GNU coding standards don't allow "path". + Use @acronym, @command, @minus{}, @samp in a few places, + where appropriate. + (Target directory): Clarify description of example. + (fmt invocation): Give issue number for reference, and reword + for clarity. + (sort invocation): Note that xargs without -0 also mishandles + file names containing some special characters other than newline. + (Translating): Mention that \012 is not universally portable. + Use '\0' rather than '\000'. + (Squeezing): bourne -> Bourne. + Fix unportable usage of '\n' by replacing it with '[\n*]'. + (More details about version sort): Remove unnecessary indent + in examples. + (dd invocation): Use 'kill -s USR1', not 'kill -USR1', as POSIX + indicates that the former is more portable (the latter is an XSI + extension). + (shred invocation): Use @uref rather than @url, and use a more-typical + style for the date. + (kill invocation): Clarify usage; for example, "kill -s TERM -1" + isn't allowed. + (seq invocation): Reword to avoid implying that printf necessarily + fails for numbers outside the 32-bit range. Prefer separating + options from their operands. + (Opening the software toolbox): Give an online reference to + Robbins's article, and give a date. Don't imply that the + current documentation is unchanged from his article. + (Putting the tools together): Rework examples so that they don't + assume the C locale; nowadays many users now operate outside the C + locale by default. While we're at it, don't assume ASCII either. + Indent example to match actual output from GNU uniq. Remove some + unnecessary and confusing brackets from 'tr' operands. "Software + Tools in Pascal" is back in print, according to Amazon anyway. + Add references to Kernighan's online copies of examples. + +2004-06-30 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi, perm.texi: Standardize on "file system" rather + than "filesystem", as POSIX prefers it with a space. + +2004-06-29 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (Common options, Target directory, cp + invocation, install invocation, mv invocation, ln invocation): + Likewise. + (link invocation): Explain how to rewrite link using ln now + that we have --no-target-directory. + (ln invocation): Explain that --no-target-directory subsumes + --no-dereference. + (unlink invocation): Modify wording to match new wording in + link invocation. + +2004-06-25 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (install invocation): Document + --target-directory in synopsis, too. + +2004-06-15 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (yes invocation): "--" is now supported. + (false invocation, true invocation): --help and --version now + work unconditionally. + +2004-06-07 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Remove menu references to just-removed subsection. + +2004-06-06 Jim Meyering <jim@meyering.net> + + * coreutils.texi (tr invocation): Remove the section describing + how POSIXLY_CORRECT changes tr's behavior. + +2004-06-02 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cut invocation): Clarify what --output-delimiter=STR + does with byte/character ranges. + +2004-06-01 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (tr invocation): Mention -C. + +2004-05-13 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (echo invocation): Document today's changes. + +2004-05-17 Jim Meyering <jim@meyering.net> + + chgrp and chown now dereference symlinks by default, per POSIX. + * coreutils.texi (chgrp invocation, chown invocation): Document it. + +2004-05-13 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (sort invocation): Document that "sort -m -o F" + might write F before reading all the input. + +2004-05-09 Jim Meyering <jim@meyering.net> + + * coreutils.texi (stat invocation): Change IO to I/O. + * Makefile.am (check-texinfo): Check for the above. + +2004-04-25 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (sort invocation): Mention -k earlier, so + that the options are in alphabetical order. Describe how -b works + more-accurately; this involves fixing some examples, too. Mention + what happens if the start field falls after an end field or after + a line end. Warn about using -k without -b, -g, -M, -n, or -t. + Add an example of how to sort IPv4 addresses and Apache Common + Log Format dates. Remove a duplicate example. + (Putting the tools together): Use separate options rather + than agglomerating them. + +2004-03-27 Paul Eggert <eggert@twinsun.com> + + cp -pu and mv -u (when copying) now take the destination + file system time stamp resolution into account. + + * coreutils.texi (mv invocation): Document this. + (cp invocation): Document -u (it was missing!) with new behavior. + +2004-04-08 Paul Eggert <eggert@cs.ucla.edu> + + * coreutils.texi (dd invocation): Remove noctty flag from dd. + +2004-04-07 Paul Eggert <eggert@twinsun.com> + + New dd conv= symbols nocreat, excl, fdatasync, fsync, + and new dd options iflag= and oflag=. + + * coreutils.texi (dd invocation): Document them. + +2004-04-07 Jim Meyering <jim@meyering.net> + + * coreutils.texi (stty invocation - Input): Document new iutf8 option. + +2004-04-04 Jim Meyering <jim@meyering.net> + + * coreutils.texi (stat invocation): Correct --format description. + +2004-02-25 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (Block size): Document new envvar BLOCKSIZE. + +2004-03-24 Jim Meyering <jim@meyering.net> + + * Makefile.am (check-texinfo): Add a check to ensure future + consistency in using @sc{nul}, not `NUL'. + +2004-03-23 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi: Use @sc{nul} consistently for NUL. + (du invocation): FILE0 -> FILE. + +2004-03-23 Jim Meyering <jim@meyering.net> + + * coreutils.texi (du invocation): --files0-from is useful with + --total (-c), not with --summarize. + +2004-03-22 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Tweak a few lines that resulted in + `overfull hbox' warnings. + +2004-03-03 Jim Meyering <jim@meyering.net> + + * coreutils.texi (du invocation): Document new option: --file0-from=F. + +2004-02-29 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (touch invocation): + Describe use of fractional seconds. + (date invocation, Options for date): Likewise. + * getdate.texi (General date syntax, Time of day items): Likewise. + * coreutils.texi (date invocation): Mention effect of LC_TIME. + (Options for date): Describe new --iso-8601=ns option. + + * getdate.texi: Add copyright notice. Change getdate to + get_date when talking about the function name. + (Seconds since the Epoch): New section, containing the time_t + info moved from Date input formats section, along with new + info about the @ syntax. Mention negative time stamps, + fractional time stamps, and leap seconds. + (General date syntax): Modernize examples a bit to reflect new + features. + (General date syntax, Relative items in date strings): + Use ' rather than " to quote formats. + (Time of day items): Add an example with fractional seconds. + Describe fractional-second syntax. + +2004-03-15 Jim Meyering <jim@meyering.net> + + * coreutils.texi (date invocation): Add missing `C' to %[...] range + in the `Date directives:: ...' menu entry. From Bob Proulx. + + * coreutils.texi: Add FIXME comment: + The following don't have `invocation' nodes: [, pinky, shasum, uptime. + +2004-03-10 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Sorting the output): Remove description of + ls's --sort=directory option. ls doesn't accept that option, yet. + Reported by Arvind Autar. + + * coreutils.texi (cp invocation): Improve description of + cp's --sparse=WHEN option. + + * coreutils.texi (nl invocation): Specify that these are _basic_ + regular expressions (BRE), and add a link to grep's documentation. + Suggestion from Dan Jacobson. + +2004-02-23 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (chown invocation): Document that chown now falls + back on USER.GROUP parsing regardless of POSIX version, as POSIX + 1003.1-2001 allows that behavior as a compatible extension. + +2004-02-22 Jim Meyering <jim@meyering.net> + + * coreutils.texi (du invocation): Mention that using du's -H option + currently evokes a warning. + +2004-02-15 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (expr invocation): + Document what forms integers may take, and say "integer" + consistently instead of "number". Warn about operands + that "expr" can misinterpret, and how to work around the + problem. + +2004-02-17 Jim Meyering <jim@meyering.net> + + * coreutils.texi (csplit invocation): Correct typo (s/LINE/N/) + in description of `N' pattern. From Reuben Thomas <rrt@sc3d.org> + +2004-02-11 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Time directives): The %s value *is* changed by the + --date=DATE option; don't say otherwise. Patch from Padraig Brady. + +2004-02-10 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (Formatting the file names): + Improve wording for --quoting-style documentation. + Suggestions by Bruno Haible. + +2004-02-02 Jim Meyering <jim@meyering.net> + + * coreutils.texi (nice invocation): Add examples. + Prompted by a suggestion from Dan Jacobson. + (factor invocation): Add an example. + Update timing numbers for a more modern CPU. + +2004-01-27 Jim Meyering <jim@meyering.net> + + * coreutils.texi (seq invocation): Remove `@dots{}' at end of synopsis. + Separate `Synopses' section into three examples. + Clarify first paragraph. @w{}-protect an expression.1 + Use @option{--option}, rather than @code{--option}. + +2004-01-19 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (Exit status): Document that ordinary failure + might not exit with status 1 on unusual platforms. + Mention chroot, env, nice, and su as having unusual exit + status patterns. Don't bother to mention true and false + since their exit status patterns are actually normal. + (sort invocation, su invocation): Mention its unusual exit + status pattern. + (chroot invocation): Simplify description of exit status 1. + Remove duplicate description of status 127. + (env invocation): Use consistent tenses; simplifiy description + of status 1. + (nice invocation): Likewise. + +2003-12-15 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (touch invocation): touch -r and -d can now + both be specified, with -r specifying the origin for -d. + +2004-01-15 Alfred M. Szmidt <ams@kemisten.nu> + + Factor out some common options. + * coreutils.texi (Common options): Define macros here. + (What information is listed, cp invocation): Use the macro(s). + (install invocation, mv invocation, ln invocation): Likewise. + (df invocation, du invocation): Likewise. + +2004-01-09 Jim Meyering <jim@meyering.net> + + Document the exit status of each and every program. + * coreutils.texi (yes invocation): Document that a write error + makes `yes' exit unsuccessfully. + (chroot invocation): Enumerate the meaning of exit status values. + (nice invocation): Likewise. + (Exit status) [@macro exitstatus]: New macro. + Use @exitstatus to describe the exit status of most programs. + +2004-01-02 Jim Meyering <jim@meyering.net> + + * coreutils.texi (du invocation): Mention that -H will eventually + mean not --si, but --dereference-args (-D). + +2003-12-20 Jim Meyering <jim@meyering.net> + + * coreutils.texi (du invocation): Describe new option: -0, --null. + +2003-12-03 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (What information is listed, chroot invocation): + Adjust example 'ls' output to match new behavior with narrower + output columns. + (The cut command): Remove example that cut the output of + 'ls -l'. The output was incorrect even with the old 'ls', and + the whole idea of using 'cut' on 'ls -l' output is bogus anyway. + +2003-11-24 Paul Eggert <eggert@twinsun.com> + + Parse floating-point operands and options in the C locale. + POSIX requires this for printf, and we might as well be + consistent elsewhere (tail, sleep, seq). + + * coreutils.texi (tail invocation, printf invocation, + sleep invocation, seq invocation): Document this. + +2003-11-24 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Traversing symlinks, Treating / specially): + New sections. + (rm invocation, chown invocation, chmod invocation, chgrp invocation): + Describe new options, --preserve-root and --no-preserve-root. + +2003-11-11 Jim Meyering <jim@meyering.net> + + * coreutils.texi (chown invocation) [chownchgrpoptions]: New macro + describing -H, -L, -P options. Use it here. + (chgrp invocation): And here. + +2003-11-09 Jim Meyering <jim@meyering.net> + + * coreutils.texi (dd invocation): Fix typo in example. + +2003-10-15 Jim Meyering <jim@meyering.net> + + * coreutils.texi (ln invocation): Note that --directory, -d, -F + probably won't work even for superuser. Suggestion from Dan Jacobson. + +2003-09-29 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (csplit invocation): + The regexp offset need not have a sign; POSIX requires support + for signless offets. + +2003-10-03 Jim Meyering <jim@meyering.net> + + * coreutils.texi (du invocation): Describe -P, --no-dereference. + +2003-09-28 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Translating): Correct typo in menu description. + From A Costa. + +2003-09-02 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (sort invocation): -d now overrides -i. + "whitespace" -> "blanks"; "whitespace" isn't correct. + -t '\0' now specifies a NUL tab. + +2003-08-17 Jim Meyering <jim@meyering.net> + + * coreutils.texi (who invocation): Add an entry for -l, --login. + Remove `-l' from the entry for --lookup. + (who invocation): Begin adding missing option documentation. + +2003-08-07 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (split invocation): + Add -d or --numeric-suffixes option to 'split'. + +2003-07-31 Paul Eggert <eggert@twinsun.com> + + * getdate.texi (General date syntax): Add --rfc-2822 option to GNU date. + * coreutils.texi (Options for date): Fix a typo in format: + it's now %d not %_d. Add URLs. + +2003-07-31 Paul Eggert <eggert@twinsun.com> + + * getdate.texi (Relative items in date strings): Warn about + fuzz in relative units. + +2003-07-29 Jim Meyering <jim@meyering.net> + + * coreutils.texi (tail invocation): Restore two end-of-sentence words + that were mistakenly removed on 2002-09-13. Reported by Paul Worrall. + +2003-07-28 Jim Meyering <jim@meyering.net> + + * coreutils.texi (dd invocation): Explain that a SIGUSR1 signal + makes dd give a progress report to stderr. + +2003-07-24 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi: Document changes of 2003-07-24. + +2003-07-24 Jim Meyering <jim@meyering.net> + + * coreutils.texi (su invocation): Use `@subsection', not invalid + `@heading'. + +2003-07-17 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (expr invocation): Exit status is 2 if the + expression is syntactically invalid, 3 if there is some other error. + This change is for conformance to POSIX. + +2003-07-14 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (uname invocation): Explain the POSIX + terminology behind uname -m and uname -s. + +2003-07-13 Jim Meyering <jim@meyering.net> + + * coreutils.texi (chown invocation): Warn that chown + now clears set-user-ID and set-group-ID bits on some systems. + From Bob Proulx. + (nohup invocation): Tell what happens when stdout is not a terminal. + Based on a suggestion from Steven Mocking. + +2003-07-10 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Standards conformance): Mention that uses like + `tail -1' and `head -1', like `sort +1', are non conforming. + (chown invocation): Say that using `.' as a separator may not work. + +2003-06-25 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Time directives) [%s]: Add a cross reference + to the related examples. + (Examples of date): Add an @anchor here, along with a few more examples. + Suggestion from Dan Jacobson. + +2003-06-12 Jim Meyering <jim@meyering.net> + + * coreutils.texi (wc invocation): Tweak wording: wc prints counts in + the order `newline, word, byte'. Suggestion from Keith M. Briggs. + Also change `lines' to `newlines'. + +2003-05-14 Jim Meyering <jim@meyering.net> + + * coreutils.texi (head invocation): Document --bytes=-N and --lines=-N. + +2003-05-13 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (uniq invocation, squeezing, The uniq command): + Use "repeated" rather than "duplicate" to describe adjacent + duplicates; this simplifies the description and makes it more + consistent with POSIX. + (uniq invocation): Make it clear that -d and -u suppress the + output of lines, rather than cause some lines to be output. + Mention what happens if a line lacks enough fields or characters. + +2003-05-13 Jim Meyering <jim@meyering.net> + + * coreutils.texi (true invocation): Mention that it is possible to + make true --help or true --version (in non-POSIX mode) exit nonzero. + Suggestion from Paul Eggert. + +2003-05-10 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Exit status): Remove `uniq' from the list. + It uses standard exit codes. + (More details about version sort): Note that strverscmp, and hence + `ls -v', does not use LC_COLLATE. Reported by From: Andrey Borzenkov. + +2003-04-21 Jim Meyering <jim@meyering.net> + + Fix printf POSIX compatibility bug reported by Ben Harris in + <http://mail.gnu.org/archive/html/bug-coreutils/2003-04/msg00070.html>. + * coreutils.texi (printf invocation): It's \NNN in the format, + \0NNN in the %b operand. + +2003-04-10 Jim Meyering <jim@meyering.net> + + * Makefile.am (check-texinfo): Check for uses of non-zero. + I prefer to spell it `nonzero'. + + * coreutils.texi (readlink invocation): Tweak description a little. + +2003-04-04 Jim Meyering <jim@meyering.net> + + * Makefile.am (constants.texi): Rename target (thus enabling it), + now that fileutils, textutils, and sh-utils have been merged. + (MAINTAINERCLEANFILES): Define. + +2003-04-02 Jim Meyering <jim@meyering.net> + + * coreutils.texi (false invocation): Note that false exits + unsuccessfully even with --help and --version. + + * Makefile.am (check-texinfo): Don't fail if perl is missing. + Reported by Nelson Beebe. + +2003-03-27 Jim Meyering <jim@meyering.net> + + * coreutils.texi (printf invocation): Fix formatting bugs. + From Paul Eggert. + (sort invocation): Describe sort's --stable (-s) option. + +2003-03-13 Jim Meyering <jim@meyering.net> + + * coreutils.texi (shred invocation): Mention that --exact + is now the default for non-regular files. + +2003-03-02 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Exit status): New section. + Suggestion from Michael Stone. + +2003-02-21 Jim Meyering <jim@meyering.net> + + * coreutils.texi (du invocation): Document --apparent-size. + Adjust documentation of --bytes (-b). + (stat invocation): Describe %B. + +2003-02-07 Richard Dawe <rich@phekda.freeserve.co.uk> + + * coreutils.texi: Use @command instead of @code for program names. + + * perm.texi (Mode Structure): Mention filesystem-specific + permissions and that mounting a filesystem as read-only may + override actual file permissions. Use @command instead + of @code for program names. + +2003-02-06 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Adjust alignment and mention `file, text, shell' + on the `* Coreutils:...' dirently line. From Karl Berry. + +2003-02-05 Jim Meyering <jim@meyering.net> + + * Makefile.am (check-texinfo): Allow bare `POSIX' to be used on + direntry lines. + + * coreutils.texi: Use new form of @direntry. + Put unlink in its proper place. Adjust wording in some + dir entry descriptions, mainly so they fit in 80 columns. + Don't use mark-up like @acronym{POSIX} in direntries. + Mostly from Karl Berry. + +2003-01-25 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cut invocation): Describe new functionality of + --output-delimiter=STR. + +2003-01-24 Jim Meyering <jim@meyering.net> + + * coreutils.texi (The cut command): Give an example of using cut -c + with an output delimiter. From Jan Nieuwenhuizen. + + * coreutils.texi (The cut command): Extend the new example a little. + (Formatting file timestamps): Fix typo: s/%M:S/%M:%S/. + + * coreutils.texi: Change each use of `Core-utils' to `Coreutils'. + From Karl Berry. + +2003-01-19 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Which files are listed): Document new option: + --dereference-command-line-symlink-to-dir. + +2003-01-15 Paul Eggert <eggert@twinsun.com> + + Change ls -H back to the way it was yesterday, since this is + compatible with FreeBSD and the POSIX spec is confusing + and somewhat contradictory. + + * coreutils.texi (Which files are listed, General output + formatting): Undo last change. + +2003-01-15 Jim Meyering <jim@meyering.net> + + * coreutils.texi (General output formatting): Reflect option name change: + s/--dereference-command-line/--dereference-command-line-symlink-to-dir/. + Say that this option changes how ls treats only symlinks to directories + specified on the command line. + +2002-08-27 Dmitry V. Levin <ldv@altlinux.org> + + * coreutils.texi: Document readlink. + +2002-12-14 Jim Meyering <jim@meyering.net> + + * coreutils.texi (mknod invocation): Specify how major and minor mode + numbers are interpreted. Report forwarded by Kristin E Thomas. + +2002-11-13 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Examples of expr): Remove bogus `^'s. + Reported by Thomas Goerlich. + +2002-11-09 Jim Meyering <jim@meyering.net> + + * coreutils.texi (What information is listed) [--dired]: + Correct parts of --dired description. Reported by Andre Spiegel. + Include a lot more description, with examples. + +2002-11-06 Jim Meyering <jim@meyering.net> + + * coreutils.texi (printf invocation): Fix typo in index: + change \0x prefix to \x. + Change \xhhh to \xhh. + +2002-10-07 Paul Eggert <eggert@twinsun.com> + + Add support for locale-specific size indications (e.g., + thousands-separators) and for explicit size suffixes on output. + + * coreutils.texi (Block size): Say that: + This affects display format as well as block size. + Fractional block counts are rounded up. + ls file size blocksize defaults to 1. + A block size spec preceded by ' generates thousands separators. + A suffix without a preceding integer generates suffixes. + (tail invocation): 32k -> 32 KiB. + (What information is listed): ls -h is now equivalent to + ls --block-size=human, and ls -H is now equivalent to + ls --block-size=si. Displayed file size is now always affected by + --block-size. + +2002-09-13 Jim Meyering <jim@meyering.net> + + * coreutils.texi (tail invocation): In --sleep-interval=NUMBER, + NUMBER may now be a floating point number. + (stat invocation): Remove references to now-removed %S and %C. + (Time directives) [%S]: Explain why the range is [0..60]. + +2002-08-30 Jim Meyering <jim@meyering.net> + + * coreutils.texi [START-INFO-DIR-ENTRY]: Don't use sc{} on LHS. + Fix typo: s/permission/permissions/. From Michail Litvak. + +2002-08-02 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (uniq invocation): uniq now obeys LC_COLLATE. + +2002-07-29 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (nohup invocation): Change behavior to conform to + POSIX 1003.1-2001: + - Do not adjust scheduling priority. + - Redirects stderr to stdout, if stderr is not a terminal. + - Exit status is now 126 if command was found but not invoked, + 127 if nohup failed or if command was not found. + +2002-07-24 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Time directives): Document %P, %R, %e, %F, + %g, %G, and %V + +2002-07-22 Martin Michlmayr <tbm@cyrius.com> + + * coreutils.texi (Formatting the file names): Document + that -N/--literal are equivalent to --quoting-style=literal. + Reported by Oskar Liljeblad as Debian bug#103612. + +2002-07-10 Jim Meyering <jim@meyering.net> + + * coreutils.texi (du invocation): s/PAT/PATTERN/. + From Martin Michlmayr. + +2002-07-08 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cp invocation): Remove unnecessary "$@" in example; + Texinfo would render the @" as an umlaut over the following character. + From Paul Eggert. + * Makefile.am (check-texinfo): Check for the above. + +2002-07-06 Jim Meyering <jim@meyering.net> + + * coreutils.texi (stat invocation): Remove description of --secure. + +2002-07-03 Jim Meyering <jim@meyering.net> + + * coreutils.texi (stat invocation): Rename --link/-l + to --dereference/-L. Rewrite description of --dereference. + +2002-06-26 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (Putting the tools together): Don't mention egrep, + since it's not part of POSIX 1003.1-2001. + +2002-06-21 Jim Meyering <jim@meyering.net> + + * coreutils.texi (stat invocation): New section. From Michael Meskes. + +2002-05-19 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (ls invocation): Document new option: --author. + +2002-06-03 Jim Meyering <jim@meyering.net> + + * coreutils.texi (rm invocation): Add the warning (also in the --help + output) that the contents of a removed file are often recoverable. + +2002-05-27 Jim Meyering <jim@meyering.net> + + * Makefile.am (check-texinfo): Adapt to reflect that now we use + @acronym{POSIX}. + +2002-05-26 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Use @acronym in place of most uses of @sc. + * getdate.texi (Date input formats): Likewise. + +2002-04-28 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Change `@code{PROG}' to `@command{PROG}'. + +2002-04-28 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (kill invocation): Document the above. + Document POSIX signals better. + +2002-04-15 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Document kill. + Written by Marcus Brinkmann. + +2002-04-13 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Document link and unlink. + +2002-04-08 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Use new directives, @copying and @insertcopying, + thus now requiring texinfo-4.2 to create the .info file. + +2002-02-26 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (File characteristic tests): Document the + behavior of test -nt and -ot when one of the files does not exist, + using the same behavior that is documented in ksh93. + +2002-03-05 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (cut invocation): Say that selected input is + written in the same order that it is read, and is written + exactly once. + +2002-03-03 Paul Eggert <eggert@twinsun.com> + + Make cp -r equivalent to cp -R. Add a new cp option --copy-contents + for people who want to emulate the traditional (and rarely desirable) + cp -r behavior. + + * coreutils.texi (cp invocation): Document this. + Fix some related minor bugs: --no-dereference is no longer + equivalent to -d, and --archive (-a) can override the other + symlink options. Warn that cp -R is not portable on symbolic + links unless you also specify -P. + +2002-03-02 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cp invocation): Document that cp -r + preserves symlinks. Emphasize non-portability of cp -r. + +2002-02-27 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (Time directives): Add %N for nanoseconds. + This documents the recent change to 'ls'. + +2002-02-28 Jim Meyering <jim@meyering.net> + + * coreutils.texi (pr invocation): Reword to avoid using `:' + in an @opindex entry -- info doesn't permit it. + +2002-02-27 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (Formatting file timestamps): Document new + time-formatting method: --time-style=+FORMAT. + +2002-02-18 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (seq invocation): In the example, use "tail + -n 3", not "tail -3", to conform to POSIX 1003.1-2001. + +2002-02-17 Jim Meyering <jim@meyering.net> + + * coreutils.texi (tsort background): New section. + From Ian Lance Taylor. + (tsort invocation): Add a more realistic example. + +2002-02-15 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi: Document _POSIX2_VERSION. + (Standards Conformance): New section. + +2002-01-24 Jim Meyering <jim@meyering.net> + + * coreutils.texi (START-INFO-DIR-ENTRY): Remove a few entries + and clean up a few others based on suggestions from Bob Proulx. + +2002-02-14 Paul Eggert <eggert@twinsun.com> + + Add support for POSIX 1003.1-2001, which requires removal for + support of obsolete "+" option syntax in sort, tail, and uniq. + * coreutils.texi: Document this. (Also, document a similar + change to "touch", for fileutils). + +2002-01-12 Jim Meyering <jim@meyering.net> + + * coreutils.texi (shred invocation): List some journaled filesystems. + +2001-11-10 Jim Meyering <jim@meyering.net> + + * coreutils.texi (Date directives): Document %u. + +2001-11-07 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (paste invocation): Give examples. + Thanks to Dan Jacobson for suggesting the examples. + +2001-11-05 Jim Meyering <jim@meyering.net> + + * coreutils.texi (sort invocation): Recommend setting LC_ALL=C, + not LC_COLLATE=C. Explain how the latter can cause problems. + Based on a message from Paul Eggert. + (ls invocation): Recommend setting LC_ALL=C, not LC_COLLATE=C. + +2001-10-21 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cp invocation): Describe --reply=... + +2001-10-17 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cp invocation): `cp --no-dereference' is + no longer equivalent to `cp -d'. + `cp -d' is equivalent to `--no-dereference --preserve=links'. + cp's -P option means --no-dereference, not --parents. + Describe new optional argument to --preserve. + Describe new option: --no-preserve=ATTRIBUTE_LIST. + +2001-09-23 Jim Meyering <jim@meyering.net> + + * Makefile.am (check-texinfo): Redirect stderr of `grep -w' to + /dev/null, so people with old versions of grep don't see the failure. + +2001-09-16 Jim Meyering <jim@meyering.net> + + * coreutils.texi (mv invocation): Describe new option: + --reply={yes,no,query}. Fix a few typos. + +2001-09-15 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (uniq invocation): The input need not + be sorted. Try to clarify -d versus -D versus -u. + +2001-09-12 Jim Meyering <jim@meyering.net> + + * coreutils.texi (tail invocation): Document new option: -F. + From Herbert Xu. + +2001-09-04 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi (join invocation): Describe the GNU + extension to join, which does not require sorted input when + the input contains no unpairable lines. + +2001-09-03 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi: + New 'uname' options -i or --hardware-platform, + and -o or --operating-system. + 'uname -a' now outputs -i and -o information at the end. + New uname option --kernel-version is an alias for -v. + Uname option --release has been renamed to --kernel-release, + and --sysname has been renamed to --kernel-name; + the old options will work for a while, but are no longer documented. + +2001-08-24 Herbert Xu <herbert@gondor.apana.org.au> + + * coreutils.texi (cut invocation): Document how cut treats lines + with no separators. + +2001-06-19 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi: expr now uses LC_COLLATE for string comparison, + as per POSIX. + +2001-08-25 Jim Meyering <jim@meyering.net> + + * coreutils.texi: Use @option, rather than @samp everywhere. + +2001-06-21 Paul Eggert <eggert@twinsun.com> + + * coreutils.texi: 'expr' now requires '+' rather than 'quote' + to quote tokens. + +2001-07-14 Jim Meyering <jim@meyering.net> + + * coreutils.texi (cp invocation): Reflect 2001-07-08 change to + cp (via copy.c). + +2001-06-16 Jim Meyering <jim@meyering.net> + + * Makefile.am (info_TEXINFOS): Reflect renaming: s/omni-/core/. + * coreutils.texi: Likewise. + + * coreutils.texi: New, renamed from omni-utils.texi. + * omni-utils.texi: Removed, renamed to coreutils.texi. + + * omni-utils.texi (ls invocation): Mention the effect of locale. + Reported by Keith Thompson. + +2001-05-24 Jim Meyering <jim@meyering.net> + + * texinfo.tex: Update from master source. + + * omni-utils.texi (ls invocation): Document more clearly what ls + does when given no arguments. + +2001-05-21 Jim Meyering <jim@meyering.net> + + * textutils.texi: Remove file. + + * Makefile.am ($(DVIS), $(INFO_DEPS)): Depend on $(EXTRA_DIST). + (DISABLED_constants.texi): New rule -- disabled for now. + + This directory is now shared by fileutils, textutils, and sh-utils. + + + ----- + + Copyright (C) 2001, 2003, 2004, 2005, 2006 Free Software + Foundation, Inc. + + Copying and distribution of this file, with or without + modification, are permitted provided the copyright notice + and this notice are preserved. diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..e0e2ee5 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,74 @@ +# Make coreutils documentation. -*-Makefile-*- + +# Copyright (C) 1995, 1996, 1997, 1998, 2001, 2002, 2003, 2004, 2005, +# 2006 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +# 02110-1301, USA. + +info_TEXINFOS = coreutils.texi + +EXTRA_DIST = perm.texi getdate.texi constants.texi fdl.texi + +# The following is necessary if the package name is 8 characters or longer. +# If the info documentation would be split into 10 or more separate files, +# then this is necessary even if the package name is 7 characters long. +# +# Tell makeinfo to put everything in a single info file: <package>.info. +# Otherwise, it would also generate files with names like <package>.info-[123], +# and those names all map to one 14-byte name (<package>.info-) on some crufty +# old systems. +AM_MAKEINFOFLAGS = --no-split + +constants.texi: $(top_srcdir)/src/tail.c + LC_ALL=C \ + sed -n -e 's/^#define \(DEFAULT_MAX[_A-Z]*\) \(.*\)/@set \1 \2/p' \ + $(top_srcdir)/src/tail.c > t-$@ + mv t-$@ $@ + +MAINTAINERCLEANFILES = constants.texi + +$(DVIS): $(EXTRA_DIST) +$(INFO_DEPS): $(EXTRA_DIST) + +# Extended regular expressions to match word starts and ends. +_W = (^|[^A-Za-z0-9_]) +W_ = ([^A-Za-z0-9_]|$$) + +# List words/regexps here that should not appear in the texinfo documentation. +# E.g., use @sc{nul}, not `NUL' +# Use `time zone', not `timezone'. +# Use `zeros', not `zeroes' (nothing wrong with `zeroes'. just be consistent). +check-texinfo: + fail=0; \ + grep timezone $(srcdir)/*.texi && fail=1; \ + $(EGREP) '$(_W)IO$(W_)' $(srcdir)/*.texi && fail=1; \ + grep non-zero $(srcdir)/*.texi && fail=1; \ + grep '@url{' $(srcdir)/*.texi && fail=1; \ + $(EGREP) '$(_W)NUL$(W_)' $(srcdir)/*.texi && fail=1; \ + grep '\$$@"' $(srcdir)/*.texi && fail=1; \ + grep -n '[^[:punct:]]@footnote' $(srcdir)/*.texi && fail=1; \ + grep -n filename $(srcdir)/*.texi|$(EGREP) -v 'setfilename|[{]filename[}]' \ + && fail=1; \ + $(PERL) -e 1 2> /dev/null && { $(PERL) -ne \ + '/\bPOSIX\b/ && !/\@acronym{POSIX}/ && !/^\* / || /{posix}/ and print,exit 1' \ + $(srcdir)/*.texi 2> /dev/null || fail=1; }; \ + $(EGREP) -i '$(_W)zeroes$(W_)' $(srcdir)/*.texi && fail=1; \ + $(EGREP) -i '$(_W)builtins?$(W_)' $(srcdir)/*.texi && fail=1; \ + $(EGREP) -i '$(_W)path(name)?s?$(W_)' $(srcdir)/*.texi \ + | $(EGREP) -v '@vindex PATH$$|@env[{]PATH[}]' && fail=1; \ + exit $$fail + +check: check-texinfo diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..ca84e92 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,976 @@ +# Makefile.in generated by automake 1.10 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# Make coreutils documentation. -*-Makefile-*- + +# Copyright (C) 1995, 1996, 1997, 1998, 2001, 2002, 2003, 2004, 2005, +# 2006 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +# 02110-1301, USA. +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = doc +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in \ + $(srcdir)/stamp-vti $(srcdir)/version.texi ChangeLog +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/absolute-header.m4 \ + $(top_srcdir)/m4/acl.m4 $(top_srcdir)/m4/alloca.m4 \ + $(top_srcdir)/m4/allocsa.m4 $(top_srcdir)/m4/argmatch.m4 \ + $(top_srcdir)/m4/arpa_inet_h.m4 $(top_srcdir)/m4/assert.m4 \ + $(top_srcdir)/m4/atexit.m4 $(top_srcdir)/m4/autobuild.m4 \ + $(top_srcdir)/m4/backupfile.m4 $(top_srcdir)/m4/base64.m4 \ + $(top_srcdir)/m4/bison.m4 $(top_srcdir)/m4/boottime.m4 \ + $(top_srcdir)/m4/c-strtod.m4 $(top_srcdir)/m4/calloc.m4 \ + $(top_srcdir)/m4/canon-host.m4 \ + $(top_srcdir)/m4/canonicalize.m4 \ + $(top_srcdir)/m4/chdir-long.m4 $(top_srcdir)/m4/check-decl.m4 \ + $(top_srcdir)/m4/chown.m4 $(top_srcdir)/m4/clock_time.m4 \ + $(top_srcdir)/m4/cloexec.m4 $(top_srcdir)/m4/close-stream.m4 \ + $(top_srcdir)/m4/closeout.m4 $(top_srcdir)/m4/codeset.m4 \ + $(top_srcdir)/m4/config-h.m4 $(top_srcdir)/m4/cycle-check.m4 \ + $(top_srcdir)/m4/d-ino.m4 $(top_srcdir)/m4/d-type.m4 \ + $(top_srcdir)/m4/dirfd.m4 $(top_srcdir)/m4/dirname.m4 \ + $(top_srcdir)/m4/dos.m4 $(top_srcdir)/m4/double-slash-root.m4 \ + $(top_srcdir)/m4/dup2.m4 $(top_srcdir)/m4/eealloc.m4 \ + $(top_srcdir)/m4/eoverflow.m4 $(top_srcdir)/m4/error.m4 \ + $(top_srcdir)/m4/euidaccess-stat.m4 \ + $(top_srcdir)/m4/euidaccess.m4 $(top_srcdir)/m4/exclude.m4 \ + $(top_srcdir)/m4/exitfail.m4 $(top_srcdir)/m4/extensions.m4 \ + $(top_srcdir)/m4/fchdir.m4 $(top_srcdir)/m4/fcntl-safer.m4 \ + $(top_srcdir)/m4/fcntl_h.m4 $(top_srcdir)/m4/fd-reopen.m4 \ + $(top_srcdir)/m4/file-type.m4 $(top_srcdir)/m4/fileblocks.m4 \ + $(top_srcdir)/m4/filemode.m4 $(top_srcdir)/m4/filenamecat.m4 \ + $(top_srcdir)/m4/flexmember.m4 $(top_srcdir)/m4/fnmatch.m4 \ + $(top_srcdir)/m4/fpending.m4 $(top_srcdir)/m4/fprintftime.m4 \ + $(top_srcdir)/m4/free.m4 $(top_srcdir)/m4/fstypename.m4 \ + $(top_srcdir)/m4/fsusage.m4 $(top_srcdir)/m4/ftruncate.m4 \ + $(top_srcdir)/m4/fts.m4 $(top_srcdir)/m4/getaddrinfo.m4 \ + $(top_srcdir)/m4/getcwd-abort-bug.m4 \ + $(top_srcdir)/m4/getcwd-path-max.m4 $(top_srcdir)/m4/getcwd.m4 \ + $(top_srcdir)/m4/getdate.m4 $(top_srcdir)/m4/getdelim.m4 \ + $(top_srcdir)/m4/getgroups.m4 $(top_srcdir)/m4/gethostname.m4 \ + $(top_srcdir)/m4/gethrxtime.m4 $(top_srcdir)/m4/getline.m4 \ + $(top_srcdir)/m4/getloadavg.m4 $(top_srcdir)/m4/getndelim2.m4 \ + $(top_srcdir)/m4/getopt.m4 $(top_srcdir)/m4/getpagesize.m4 \ + $(top_srcdir)/m4/getpass.m4 $(top_srcdir)/m4/gettext.m4 \ + $(top_srcdir)/m4/gettime.m4 $(top_srcdir)/m4/gettimeofday.m4 \ + $(top_srcdir)/m4/getugroups.m4 \ + $(top_srcdir)/m4/getusershell.m4 $(top_srcdir)/m4/glibc21.m4 \ + $(top_srcdir)/m4/gnulib-common.m4 \ + $(top_srcdir)/m4/gnulib-comp.m4 \ + $(top_srcdir)/m4/group-member.m4 \ + $(top_srcdir)/m4/hard-locale.m4 $(top_srcdir)/m4/hash.m4 \ + $(top_srcdir)/m4/host-os.m4 $(top_srcdir)/m4/human.m4 \ + $(top_srcdir)/m4/i-ring.m4 $(top_srcdir)/m4/iconv.m4 \ + $(top_srcdir)/m4/idcache.m4 $(top_srcdir)/m4/inet_ntop.m4 \ + $(top_srcdir)/m4/inline.m4 $(top_srcdir)/m4/intmax_t.m4 \ + $(top_srcdir)/m4/inttostr.m4 $(top_srcdir)/m4/inttypes-pri.m4 \ + $(top_srcdir)/m4/inttypes.m4 $(top_srcdir)/m4/inttypes_h.m4 \ + $(top_srcdir)/m4/isapipe.m4 $(top_srcdir)/m4/jm-macros.m4 \ + $(top_srcdir)/m4/jm-winsz1.m4 $(top_srcdir)/m4/jm-winsz2.m4 \ + $(top_srcdir)/m4/lchmod.m4 $(top_srcdir)/m4/lchown.m4 \ + $(top_srcdir)/m4/lib-check.m4 $(top_srcdir)/m4/lib-ignore.m4 \ + $(top_srcdir)/m4/lib-ld.m4 $(top_srcdir)/m4/lib-link.m4 \ + $(top_srcdir)/m4/lib-prefix.m4 $(top_srcdir)/m4/link-follow.m4 \ + $(top_srcdir)/m4/localcharset.m4 \ + $(top_srcdir)/m4/long-options.m4 \ + $(top_srcdir)/m4/longdouble.m4 $(top_srcdir)/m4/longlong.m4 \ + $(top_srcdir)/m4/ls-mntd-fs.m4 $(top_srcdir)/m4/lstat.m4 \ + $(top_srcdir)/m4/mbchar.m4 $(top_srcdir)/m4/mbiter.m4 \ + $(top_srcdir)/m4/mbrtowc.m4 $(top_srcdir)/m4/mbscasecmp.m4 \ + $(top_srcdir)/m4/mbstate_t.m4 $(top_srcdir)/m4/mbswidth.m4 \ + $(top_srcdir)/m4/md5.m4 $(top_srcdir)/m4/memcasecmp.m4 \ + $(top_srcdir)/m4/memchr.m4 $(top_srcdir)/m4/memcmp.m4 \ + $(top_srcdir)/m4/memcoll.m4 $(top_srcdir)/m4/memcpy.m4 \ + $(top_srcdir)/m4/memmove.m4 $(top_srcdir)/m4/mempcpy.m4 \ + $(top_srcdir)/m4/memrchr.m4 $(top_srcdir)/m4/memset.m4 \ + $(top_srcdir)/m4/memxfrm.m4 $(top_srcdir)/m4/mkancesdirs.m4 \ + $(top_srcdir)/m4/mkdir-p.m4 $(top_srcdir)/m4/mkdir-slash.m4 \ + $(top_srcdir)/m4/mkstemp.m4 $(top_srcdir)/m4/mktime.m4 \ + $(top_srcdir)/m4/modechange.m4 $(top_srcdir)/m4/mountlist.m4 \ + $(top_srcdir)/m4/mpsort.m4 $(top_srcdir)/m4/nanosleep.m4 \ + $(top_srcdir)/m4/netinet_in_h.m4 $(top_srcdir)/m4/nls.m4 \ + $(top_srcdir)/m4/openat.m4 $(top_srcdir)/m4/pathmax.m4 \ + $(top_srcdir)/m4/perl.m4 $(top_srcdir)/m4/physmem.m4 \ + $(top_srcdir)/m4/po.m4 $(top_srcdir)/m4/posixtm.m4 \ + $(top_srcdir)/m4/posixver.m4 $(top_srcdir)/m4/prereq.m4 \ + $(top_srcdir)/m4/progtest.m4 $(top_srcdir)/m4/putenv.m4 \ + $(top_srcdir)/m4/quote.m4 $(top_srcdir)/m4/quotearg.m4 \ + $(top_srcdir)/m4/randint.m4 $(top_srcdir)/m4/randperm.m4 \ + $(top_srcdir)/m4/randread.m4 $(top_srcdir)/m4/readlink.m4 \ + $(top_srcdir)/m4/readtokens.m4 $(top_srcdir)/m4/readutmp.m4 \ + $(top_srcdir)/m4/regex.m4 \ + $(top_srcdir)/m4/rename-dest-slash.m4 \ + $(top_srcdir)/m4/rename.m4 $(top_srcdir)/m4/rmdir-errno.m4 \ + $(top_srcdir)/m4/rmdir.m4 $(top_srcdir)/m4/root-dev-ino.m4 \ + $(top_srcdir)/m4/rpmatch.m4 $(top_srcdir)/m4/safe-read.m4 \ + $(top_srcdir)/m4/safe-write.m4 $(top_srcdir)/m4/same.m4 \ + $(top_srcdir)/m4/save-cwd.m4 $(top_srcdir)/m4/savedir.m4 \ + $(top_srcdir)/m4/savewd.m4 $(top_srcdir)/m4/setenv.m4 \ + $(top_srcdir)/m4/settime.m4 $(top_srcdir)/m4/sha1.m4 \ + $(top_srcdir)/m4/sha256.m4 $(top_srcdir)/m4/sha512.m4 \ + $(top_srcdir)/m4/sig2str.m4 $(top_srcdir)/m4/snprintf.m4 \ + $(top_srcdir)/m4/socklen.m4 $(top_srcdir)/m4/sockpfaf.m4 \ + $(top_srcdir)/m4/ssize_t.m4 $(top_srcdir)/m4/st_dm_mode.m4 \ + $(top_srcdir)/m4/stat-prog.m4 $(top_srcdir)/m4/stat-time.m4 \ + $(top_srcdir)/m4/stdarg.m4 $(top_srcdir)/m4/stdbool.m4 \ + $(top_srcdir)/m4/stdint.m4 $(top_srcdir)/m4/stdint_h.m4 \ + $(top_srcdir)/m4/stdio-safer.m4 $(top_srcdir)/m4/stdio_h.m4 \ + $(top_srcdir)/m4/stdlib-safer.m4 $(top_srcdir)/m4/stdlib_h.m4 \ + $(top_srcdir)/m4/stpcpy.m4 $(top_srcdir)/m4/strcspn.m4 \ + $(top_srcdir)/m4/strdup.m4 $(top_srcdir)/m4/strftime.m4 \ + $(top_srcdir)/m4/string_h.m4 $(top_srcdir)/m4/strndup.m4 \ + $(top_srcdir)/m4/strnlen.m4 $(top_srcdir)/m4/strnumcmp.m4 \ + $(top_srcdir)/m4/strpbrk.m4 $(top_srcdir)/m4/strtod.m4 \ + $(top_srcdir)/m4/strtoimax.m4 $(top_srcdir)/m4/strtol.m4 \ + $(top_srcdir)/m4/strtoll.m4 $(top_srcdir)/m4/strtoul.m4 \ + $(top_srcdir)/m4/strtoull.m4 $(top_srcdir)/m4/strtoumax.m4 \ + $(top_srcdir)/m4/strverscmp.m4 \ + $(top_srcdir)/m4/sys_socket_h.m4 \ + $(top_srcdir)/m4/sys_stat_h.m4 $(top_srcdir)/m4/sys_time_h.m4 \ + $(top_srcdir)/m4/tempname.m4 $(top_srcdir)/m4/time_h.m4 \ + $(top_srcdir)/m4/time_r.m4 $(top_srcdir)/m4/timespec.m4 \ + $(top_srcdir)/m4/tm_gmtoff.m4 $(top_srcdir)/m4/tzset.m4 \ + $(top_srcdir)/m4/unicodeio.m4 $(top_srcdir)/m4/unistd-safer.m4 \ + $(top_srcdir)/m4/unistd_h.m4 $(top_srcdir)/m4/unlink-busy.m4 \ + $(top_srcdir)/m4/unlinkdir.m4 $(top_srcdir)/m4/unlocked-io.m4 \ + $(top_srcdir)/m4/uptime.m4 $(top_srcdir)/m4/userspec.m4 \ + $(top_srcdir)/m4/utimbuf.m4 $(top_srcdir)/m4/utime.m4 \ + $(top_srcdir)/m4/utimecmp.m4 $(top_srcdir)/m4/utimens.m4 \ + $(top_srcdir)/m4/utimes-null.m4 $(top_srcdir)/m4/utimes.m4 \ + $(top_srcdir)/m4/vasnprintf.m4 $(top_srcdir)/m4/vasprintf.m4 \ + $(top_srcdir)/m4/wchar.m4 $(top_srcdir)/m4/wchar_t.m4 \ + $(top_srcdir)/m4/wctype.m4 $(top_srcdir)/m4/wcwidth.m4 \ + $(top_srcdir)/m4/wint_t.m4 $(top_srcdir)/m4/xalloc.m4 \ + $(top_srcdir)/m4/xfts.m4 $(top_srcdir)/m4/xgetcwd.m4 \ + $(top_srcdir)/m4/xnanosleep.m4 $(top_srcdir)/m4/xstrndup.m4 \ + $(top_srcdir)/m4/xstrtod.m4 $(top_srcdir)/m4/xstrtol.m4 \ + $(top_srcdir)/m4/yesno.m4 $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/lib/config.h +CONFIG_CLEAN_FILES = +SOURCES = +DIST_SOURCES = +INFO_DEPS = $(srcdir)/coreutils.info +TEXINFO_TEX = $(top_srcdir)/build-aux/texinfo.tex +am__TEXINFO_TEX_DIR = $(top_srcdir)/build-aux +DVIS = coreutils.dvi +PDFS = coreutils.pdf +PSS = coreutils.ps +HTMLS = coreutils.html +TEXINFOS = coreutils.texi +TEXI2DVI = texi2dvi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +am__installdirs = "$(DESTDIR)$(infodir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = `echo $$p | sed -e 's|^.*/||'`; +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ABSOLUTE_DIRENT_H = @ABSOLUTE_DIRENT_H@ +ABSOLUTE_FCNTL_H = @ABSOLUTE_FCNTL_H@ +ABSOLUTE_INTTYPES_H = @ABSOLUTE_INTTYPES_H@ +ABSOLUTE_NETINET_IN_H = @ABSOLUTE_NETINET_IN_H@ +ABSOLUTE_STDINT_H = @ABSOLUTE_STDINT_H@ +ABSOLUTE_STDIO_H = @ABSOLUTE_STDIO_H@ +ABSOLUTE_STDLIB_H = @ABSOLUTE_STDLIB_H@ +ABSOLUTE_STRING_H = @ABSOLUTE_STRING_H@ +ABSOLUTE_SYS_SOCKET_H = @ABSOLUTE_SYS_SOCKET_H@ +ABSOLUTE_SYS_STAT_H = @ABSOLUTE_SYS_STAT_H@ +ABSOLUTE_SYS_TIME_H = @ABSOLUTE_SYS_TIME_H@ +ABSOLUTE_TIME_H = @ABSOLUTE_TIME_H@ +ABSOLUTE_UNISTD_H = @ABSOLUTE_UNISTD_H@ +ABSOLUTE_WCHAR_H = @ABSOLUTE_WCHAR_H@ +ABSOLUTE_WCTYPE_H = @ABSOLUTE_WCTYPE_H@ +ACLOCAL = @ACLOCAL@ +ALLOCA = @ALLOCA@ +ALLOCA_H = @ALLOCA_H@ +AMTAR = @AMTAR@ +ARPA_INET_H = @ARPA_INET_H@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BITSIZEOF_PTRDIFF_T = @BITSIZEOF_PTRDIFF_T@ +BITSIZEOF_SIG_ATOMIC_T = @BITSIZEOF_SIG_ATOMIC_T@ +BITSIZEOF_SIZE_T = @BITSIZEOF_SIZE_T@ +BITSIZEOF_WCHAR_T = @BITSIZEOF_WCHAR_T@ +BITSIZEOF_WINT_T = @BITSIZEOF_WINT_T@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFAULT_POSIX2_VERSION = @DEFAULT_POSIX2_VERSION@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DF_PROG = @DF_PROG@ +DIRENT_H = @DIRENT_H@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EOVERFLOW = @EOVERFLOW@ +EXEEXT = @EXEEXT@ +FCNTL_H = @FCNTL_H@ +FNMATCH_H = @FNMATCH_H@ +GETLOADAVG_LIBS = @GETLOADAVG_LIBS@ +GETOPT_H = @GETOPT_H@ +GLIBC21 = @GLIBC21@ +GMSGFMT = @GMSGFMT@ +GMSGFMT_015 = @GMSGFMT_015@ +GNULIB_CHOWN = @GNULIB_CHOWN@ +GNULIB_DUP2 = @GNULIB_DUP2@ +GNULIB_FCHDIR = @GNULIB_FCHDIR@ +GNULIB_FPRINTF_POSIX = @GNULIB_FPRINTF_POSIX@ +GNULIB_FTRUNCATE = @GNULIB_FTRUNCATE@ +GNULIB_GETCWD = @GNULIB_GETCWD@ +GNULIB_GETLOGIN_R = @GNULIB_GETLOGIN_R@ +GNULIB_GETSUBOPT = @GNULIB_GETSUBOPT@ +GNULIB_IMAXABS = @GNULIB_IMAXABS@ +GNULIB_IMAXDIV = @GNULIB_IMAXDIV@ +GNULIB_MBSCASECMP = @GNULIB_MBSCASECMP@ +GNULIB_MBSCASESTR = @GNULIB_MBSCASESTR@ +GNULIB_MBSCHR = @GNULIB_MBSCHR@ +GNULIB_MBSCSPN = @GNULIB_MBSCSPN@ +GNULIB_MBSLEN = @GNULIB_MBSLEN@ +GNULIB_MBSNCASECMP = @GNULIB_MBSNCASECMP@ +GNULIB_MBSPBRK = @GNULIB_MBSPBRK@ +GNULIB_MBSPCASECMP = @GNULIB_MBSPCASECMP@ +GNULIB_MBSRCHR = @GNULIB_MBSRCHR@ +GNULIB_MBSSEP = @GNULIB_MBSSEP@ +GNULIB_MBSSPN = @GNULIB_MBSSPN@ +GNULIB_MBSSTR = @GNULIB_MBSSTR@ +GNULIB_MBSTOK_R = @GNULIB_MBSTOK_R@ +GNULIB_MEMMEM = @GNULIB_MEMMEM@ +GNULIB_MEMPCPY = @GNULIB_MEMPCPY@ +GNULIB_MEMRCHR = @GNULIB_MEMRCHR@ +GNULIB_MKDTEMP = @GNULIB_MKDTEMP@ +GNULIB_MKSTEMP = @GNULIB_MKSTEMP@ +GNULIB_PRINTF_POSIX = @GNULIB_PRINTF_POSIX@ +GNULIB_READLINK = @GNULIB_READLINK@ +GNULIB_SNPRINTF = @GNULIB_SNPRINTF@ +GNULIB_SPRINTF_POSIX = @GNULIB_SPRINTF_POSIX@ +GNULIB_STPCPY = @GNULIB_STPCPY@ +GNULIB_STPNCPY = @GNULIB_STPNCPY@ +GNULIB_STRCASESTR = @GNULIB_STRCASESTR@ +GNULIB_STRCHRNUL = @GNULIB_STRCHRNUL@ +GNULIB_STRDUP = @GNULIB_STRDUP@ +GNULIB_STRNDUP = @GNULIB_STRNDUP@ +GNULIB_STRNLEN = @GNULIB_STRNLEN@ +GNULIB_STRPBRK = @GNULIB_STRPBRK@ +GNULIB_STRSEP = @GNULIB_STRSEP@ +GNULIB_STRTOIMAX = @GNULIB_STRTOIMAX@ +GNULIB_STRTOK_R = @GNULIB_STRTOK_R@ +GNULIB_STRTOUMAX = @GNULIB_STRTOUMAX@ +GNULIB_VFPRINTF_POSIX = @GNULIB_VFPRINTF_POSIX@ +GNULIB_VPRINTF_POSIX = @GNULIB_VPRINTF_POSIX@ +GNULIB_VSNPRINTF = @GNULIB_VSNPRINTF@ +GNULIB_VSPRINTF_POSIX = @GNULIB_VSPRINTF_POSIX@ +GNU_PACKAGE = @GNU_PACKAGE@ +GREP = @GREP@ +HAVE_DECL_GETLOGIN_R = @HAVE_DECL_GETLOGIN_R@ +HAVE_DECL_IMAXABS = @HAVE_DECL_IMAXABS@ +HAVE_DECL_IMAXDIV = @HAVE_DECL_IMAXDIV@ +HAVE_DECL_MEMMEM = @HAVE_DECL_MEMMEM@ +HAVE_DECL_MEMRCHR = @HAVE_DECL_MEMRCHR@ +HAVE_DECL_SNPRINTF = @HAVE_DECL_SNPRINTF@ +HAVE_DECL_STRDUP = @HAVE_DECL_STRDUP@ +HAVE_DECL_STRNCASECMP = @HAVE_DECL_STRNCASECMP@ +HAVE_DECL_STRNDUP = @HAVE_DECL_STRNDUP@ +HAVE_DECL_STRNLEN = @HAVE_DECL_STRNLEN@ +HAVE_DECL_STRTOIMAX = @HAVE_DECL_STRTOIMAX@ +HAVE_DECL_STRTOK_R = @HAVE_DECL_STRTOK_R@ +HAVE_DECL_STRTOUMAX = @HAVE_DECL_STRTOUMAX@ +HAVE_DECL_VSNPRINTF = @HAVE_DECL_VSNPRINTF@ +HAVE_DUP2 = @HAVE_DUP2@ +HAVE_FTRUNCATE = @HAVE_FTRUNCATE@ +HAVE_GETSUBOPT = @HAVE_GETSUBOPT@ +HAVE_INTTYPES_H = @HAVE_INTTYPES_H@ +HAVE_LONG_LONG_INT = @HAVE_LONG_LONG_INT@ +HAVE_MEMPCPY = @HAVE_MEMPCPY@ +HAVE_MKDTEMP = @HAVE_MKDTEMP@ +HAVE_NETINET_IN_H = @HAVE_NETINET_IN_H@ +HAVE_READLINK = @HAVE_READLINK@ +HAVE_SIGNED_SIG_ATOMIC_T = @HAVE_SIGNED_SIG_ATOMIC_T@ +HAVE_SIGNED_WCHAR_T = @HAVE_SIGNED_WCHAR_T@ +HAVE_SIGNED_WINT_T = @HAVE_SIGNED_WINT_T@ +HAVE_STDINT_H = @HAVE_STDINT_H@ +HAVE_STPCPY = @HAVE_STPCPY@ +HAVE_STPNCPY = @HAVE_STPNCPY@ +HAVE_STRCASECMP = @HAVE_STRCASECMP@ +HAVE_STRCASESTR = @HAVE_STRCASESTR@ +HAVE_STRCHRNUL = @HAVE_STRCHRNUL@ +HAVE_STRNDUP = @HAVE_STRNDUP@ +HAVE_STRPBRK = @HAVE_STRPBRK@ +HAVE_STRSEP = @HAVE_STRSEP@ +HAVE_STRUCT_TIMEVAL = @HAVE_STRUCT_TIMEVAL@ +HAVE_SYS_BITYPES_H = @HAVE_SYS_BITYPES_H@ +HAVE_SYS_INTTYPES_H = @HAVE_SYS_INTTYPES_H@ +HAVE_SYS_SOCKET_H = @HAVE_SYS_SOCKET_H@ +HAVE_SYS_TIME_H = @HAVE_SYS_TIME_H@ +HAVE_SYS_TYPES_H = @HAVE_SYS_TYPES_H@ +HAVE_UNISTD_H = @HAVE_UNISTD_H@ +HAVE_UNSIGNED_LONG_LONG_INT = @HAVE_UNSIGNED_LONG_LONG_INT@ +HAVE_WCTYPE_H = @HAVE_WCTYPE_H@ +HAVE_WINSOCK2_H = @HAVE_WINSOCK2_H@ +HAVE_WINT_T = @HAVE_WINT_T@ +HAVE_WS2TCPIP_H = @HAVE_WS2TCPIP_H@ +HAVE__BOOL = @HAVE__BOOL@ +HELP2MAN = @HELP2MAN@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +INTLLIBS = @INTLLIBS@ +INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@ +INTTYPES_H = @INTTYPES_H@ +KMEM_GROUP = @KMEM_GROUP@ +LDFLAGS = @LDFLAGS@ +LIBCOREUTILS_LIBDEPS = @LIBCOREUTILS_LIBDEPS@ +LIBCOREUTILS_LTLIBDEPS = @LIBCOREUTILS_LTLIBDEPS@ +LIBICONV = @LIBICONV@ +LIBINTL = @LIBINTL@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIB_ACL = @LIB_ACL@ +LIB_ACL_TRIVIAL = @LIB_ACL_TRIVIAL@ +LIB_CLOCK_GETTIME = @LIB_CLOCK_GETTIME@ +LIB_CRYPT = @LIB_CRYPT@ +LIB_EACCESS = @LIB_EACCESS@ +LIB_FDATASYNC = @LIB_FDATASYNC@ +LIB_GETHRXTIME = @LIB_GETHRXTIME@ +LIB_NANOSLEEP = @LIB_NANOSLEEP@ +LN_S = @LN_S@ +LTLIBICONV = @LTLIBICONV@ +LTLIBINTL = @LTLIBINTL@ +LTLIBOBJS = @LTLIBOBJS@ +MAKEINFO = @MAKEINFO@ +MAN = @MAN@ +MKDIR_P = @MKDIR_P@ +MSGFMT = @MSGFMT@ +MSGFMT_015 = @MSGFMT_015@ +MSGMERGE = @MSGMERGE@ +NEED_SETGID = @NEED_SETGID@ +NETINET_IN_H = @NETINET_IN_H@ +OBJEXT = @OBJEXT@ +OPTIONAL_BIN_PROGS = @OPTIONAL_BIN_PROGS@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +POSUB = @POSUB@ +POW_LIB = @POW_LIB@ +PRIPTR_PREFIX = @PRIPTR_PREFIX@ +PRI_MACROS_BROKEN = @PRI_MACROS_BROKEN@ +PTRDIFF_T_SUFFIX = @PTRDIFF_T_SUFFIX@ +RANLIB = @RANLIB@ +REPLACE_CHOWN = @REPLACE_CHOWN@ +REPLACE_FCHDIR = @REPLACE_FCHDIR@ +REPLACE_FPRINTF = @REPLACE_FPRINTF@ +REPLACE_GETCWD = @REPLACE_GETCWD@ +REPLACE_GETTIMEOFDAY = @REPLACE_GETTIMEOFDAY@ +REPLACE_LOCALTIME_R = @REPLACE_LOCALTIME_R@ +REPLACE_MKSTEMP = @REPLACE_MKSTEMP@ +REPLACE_NANOSLEEP = @REPLACE_NANOSLEEP@ +REPLACE_PRINTF = @REPLACE_PRINTF@ +REPLACE_SNPRINTF = @REPLACE_SNPRINTF@ +REPLACE_SPRINTF = @REPLACE_SPRINTF@ +REPLACE_STRPTIME = @REPLACE_STRPTIME@ +REPLACE_TIMEGM = @REPLACE_TIMEGM@ +REPLACE_VFPRINTF = @REPLACE_VFPRINTF@ +REPLACE_VPRINTF = @REPLACE_VPRINTF@ +REPLACE_VSNPRINTF = @REPLACE_VSNPRINTF@ +REPLACE_VSPRINTF = @REPLACE_VSPRINTF@ +SEQ_LIBM = @SEQ_LIBM@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +SIG_ATOMIC_T_SUFFIX = @SIG_ATOMIC_T_SUFFIX@ +SIZE_T_SUFFIX = @SIZE_T_SUFFIX@ +STDBOOL_H = @STDBOOL_H@ +STDINT_H = @STDINT_H@ +STRIP = @STRIP@ +SYS_SOCKET_H = @SYS_SOCKET_H@ +SYS_STAT_H = @SYS_STAT_H@ +SYS_TIME_H = @SYS_TIME_H@ +SYS_TIME_H_DEFINES_STRUCT_TIMESPEC = @SYS_TIME_H_DEFINES_STRUCT_TIMESPEC@ +TIME_H_DEFINES_STRUCT_TIMESPEC = @TIME_H_DEFINES_STRUCT_TIMESPEC@ +U = @U@ +USE_NLS = @USE_NLS@ +VERSION = @VERSION@ +WCHAR_H = @WCHAR_H@ +WCHAR_T_SUFFIX = @WCHAR_T_SUFFIX@ +WCTYPE_H = @WCTYPE_H@ +WINT_T_SUFFIX = @WINT_T_SUFFIX@ +XGETTEXT = @XGETTEXT@ +XGETTEXT_015 = @XGETTEXT_015@ +YACC = @YACC@ +YFLAGS = @YFLAGS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +gl_LIBOBJS = @gl_LIBOBJS@ +gl_LTLIBOBJS = @gl_LTLIBOBJS@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +info_TEXINFOS = coreutils.texi +EXTRA_DIST = perm.texi getdate.texi constants.texi fdl.texi + +# The following is necessary if the package name is 8 characters or longer. +# If the info documentation would be split into 10 or more separate files, +# then this is necessary even if the package name is 7 characters long. +# +# Tell makeinfo to put everything in a single info file: <package>.info. +# Otherwise, it would also generate files with names like <package>.info-[123], +# and those names all map to one 14-byte name (<package>.info-) on some crufty +# old systems. +AM_MAKEINFOFLAGS = --no-split +MAINTAINERCLEANFILES = constants.texi + +# Extended regular expressions to match word starts and ends. +_W = (^|[^A-Za-z0-9_]) +W_ = ([^A-Za-z0-9_]|$$) +all: all-am + +.SUFFIXES: +.SUFFIXES: .dvi .html .info .pdf .ps .texi +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +.texi.info: + restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && cd $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + cd $(srcdir); \ + else \ + rc=$$?; \ + cd $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texi.dvi: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $< + +.texi.pdf: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $< + +.texi.html: + rm -rf $(@:.html=.htp) + if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@; \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ + else \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ + exit 1; \ + fi +$(srcdir)/coreutils.info: coreutils.texi $(srcdir)/version.texi +coreutils.dvi: coreutils.texi $(srcdir)/version.texi +coreutils.pdf: coreutils.texi $(srcdir)/version.texi +coreutils.html: coreutils.texi $(srcdir)/version.texi +$(srcdir)/version.texi: $(srcdir)/stamp-vti +$(srcdir)/stamp-vti: coreutils.texi $(top_srcdir)/configure + @(dir=.; test -f ./coreutils.texi || dir=$(srcdir); \ + set `$(SHELL) $(top_srcdir)/build-aux/mdate-sh $$dir/coreutils.texi`; \ + echo "@set UPDATED $$1 $$2 $$3"; \ + echo "@set UPDATED-MONTH $$2 $$3"; \ + echo "@set EDITION $(VERSION)"; \ + echo "@set VERSION $(VERSION)") > vti.tmp + @cmp -s vti.tmp $(srcdir)/version.texi \ + || (echo "Updating $(srcdir)/version.texi"; \ + cp vti.tmp $(srcdir)/version.texi) + -@rm -f vti.tmp + @cp $(srcdir)/version.texi $@ + +mostlyclean-vti: + -rm -f vti.tmp + +maintainer-clean-vti: + -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi +.dvi.ps: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && \ + (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f $(distdir)/$$relfile || \ + cp -p $$file $(distdir)/$$relfile; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf coreutils.aux coreutils.cp coreutils.cps coreutils.fl coreutils.fn \ + coreutils.ky coreutils.log coreutils.op coreutils.pg \ + coreutils.tmp coreutils.toc coreutils.tp coreutils.tps \ + coreutils.vr coreutils.dvi coreutils.pdf coreutils.ps \ + coreutils.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info +check-am: all-am +check: check-am +all-am: Makefile $(INFO_DEPS) +installdirs: + for dir in "$(DESTDIR)$(infodir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." + -test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES) +clean: clean-am + +clean-am: clean-generic mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: $(DVIS) + +html: html-am + +html-am: $(HTMLS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am + +install-dvi: install-dvi-am + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)" + @list='$(DVIS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/$$f"; \ + done +install-exec-am: + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" + @list='$(HTMLS)'; for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + if test -d "$$d$$p"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \ + else \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \ + fi; \ + done +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)" + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ + echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \ + $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)" + @list='$(PDFS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \ + done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)" + @list='$(PSS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(psdir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(psdir)/$$f"; \ + done +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic maintainer-clean-vti + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic mostlyclean-vti + +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic dist-info \ + distclean distclean-generic distdir dvi dvi-am html html-am \ + info info-am install install-am install-data install-data-am \ + install-dvi install-dvi-am install-exec install-exec-am \ + install-html install-html-am install-info install-info-am \ + install-man install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs maintainer-clean maintainer-clean-aminfo \ + maintainer-clean-generic maintainer-clean-vti mostlyclean \ + mostlyclean-aminfo mostlyclean-generic mostlyclean-vti pdf \ + pdf-am ps ps-am uninstall uninstall-am uninstall-dvi-am \ + uninstall-html-am uninstall-info-am uninstall-pdf-am \ + uninstall-ps-am + + +constants.texi: $(top_srcdir)/src/tail.c + LC_ALL=C \ + sed -n -e 's/^#define \(DEFAULT_MAX[_A-Z]*\) \(.*\)/@set \1 \2/p' \ + $(top_srcdir)/src/tail.c > t-$@ + mv t-$@ $@ + +$(DVIS): $(EXTRA_DIST) +$(INFO_DEPS): $(EXTRA_DIST) + +# List words/regexps here that should not appear in the texinfo documentation. +# E.g., use @sc{nul}, not `NUL' +# Use `time zone', not `timezone'. +# Use `zeros', not `zeroes' (nothing wrong with `zeroes'. just be consistent). +check-texinfo: + fail=0; \ + grep timezone $(srcdir)/*.texi && fail=1; \ + $(EGREP) '$(_W)IO$(W_)' $(srcdir)/*.texi && fail=1; \ + grep non-zero $(srcdir)/*.texi && fail=1; \ + grep '@url{' $(srcdir)/*.texi && fail=1; \ + $(EGREP) '$(_W)NUL$(W_)' $(srcdir)/*.texi && fail=1; \ + grep '\$$@"' $(srcdir)/*.texi && fail=1; \ + grep -n '[^[:punct:]]@footnote' $(srcdir)/*.texi && fail=1; \ + grep -n filename $(srcdir)/*.texi|$(EGREP) -v 'setfilename|[{]filename[}]' \ + && fail=1; \ + $(PERL) -e 1 2> /dev/null && { $(PERL) -ne \ + '/\bPOSIX\b/ && !/\@acronym{POSIX}/ && !/^\* / || /{posix}/ and print,exit 1' \ + $(srcdir)/*.texi 2> /dev/null || fail=1; }; \ + $(EGREP) -i '$(_W)zeroes$(W_)' $(srcdir)/*.texi && fail=1; \ + $(EGREP) -i '$(_W)builtins?$(W_)' $(srcdir)/*.texi && fail=1; \ + $(EGREP) -i '$(_W)path(name)?s?$(W_)' $(srcdir)/*.texi \ + | $(EGREP) -v '@vindex PATH$$|@env[{]PATH[}]' && fail=1; \ + exit $$fail + +check: check-texinfo +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/constants.texi b/doc/constants.texi new file mode 100644 index 0000000..f6bffca --- /dev/null +++ b/doc/constants.texi @@ -0,0 +1 @@ +@set DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS 5 diff --git a/doc/coreutils.info b/doc/coreutils.info new file mode 100644 index 0000000..4589ca2 --- /dev/null +++ b/doc/coreutils.info @@ -0,0 +1,15863 @@ +This is coreutils.info, produced by makeinfo version 4.8 from +coreutils.texi. + +INFO-DIR-SECTION Basics +START-INFO-DIR-ENTRY +* Coreutils: (coreutils). Core GNU (file, text, shell) utilities. +* Common options: (coreutils)Common options. Common options. +* File permissions: (coreutils)File permissions. Access modes. +* Date input formats: (coreutils)Date input formats. +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* base64: (coreutils)base64 invocation. Base64 encode/decode data. +* basename: (coreutils)basename invocation. Strip directory and suffix. +* cat: (coreutils)cat invocation. Concatenate and write files. +* chgrp: (coreutils)chgrp invocation. Change file groups. +* chmod: (coreutils)chmod invocation. Change file permissions. +* chown: (coreutils)chown invocation. Change file owners/groups. +* chroot: (coreutils)chroot invocation. Specify the root directory. +* cksum: (coreutils)cksum invocation. Print POSIX CRC checksum. +* comm: (coreutils)comm invocation. Compare sorted files by line. +* cp: (coreutils)cp invocation. Copy files. +* csplit: (coreutils)csplit invocation. Split by context. +* cut: (coreutils)cut invocation. Print selected parts of lines. +* date: (coreutils)date invocation. Print/set system date and time. +* dd: (coreutils)dd invocation. Copy and convert a file. +* 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. +* du: (coreutils)du invocation. Report on disk usage. +* echo: (coreutils)echo invocation. Print a line of text. +* env: (coreutils)env invocation. Modify the environment. +* expand: (coreutils)expand invocation. Convert tabs to spaces. +* expr: (coreutils)expr invocation. Evaluate expressions. +* factor: (coreutils)factor invocation. Print prime factors +* false: (coreutils)false invocation. Do nothing, unsuccessfully. +* fmt: (coreutils)fmt invocation. Reformat paragraph text. +* fold: (coreutils)fold invocation. Wrap long input lines. +* groups: (coreutils)groups invocation. Print group names a user is in. +* head: (coreutils)head invocation. Output the first part of files. +* hostid: (coreutils)hostid invocation. Print numeric host identifier. +* hostname: (coreutils)hostname invocation. Print or set system name. +* id: (coreutils)id invocation. Print user identity. +* install: (coreutils)install invocation. Copy and change attributes. +* join: (coreutils)join invocation. Join lines on a common field. +* kill: (coreutils)kill invocation. Send a signal to processes. +* link: (coreutils)link invocation. Make hard links between files. +* ln: (coreutils)ln invocation. Make links between files. +* logname: (coreutils)logname invocation. Print current login name. +* ls: (coreutils)ls invocation. List directory contents. +* md5sum: (coreutils)md5sum invocation. Print or check MD5 digests. +* mkdir: (coreutils)mkdir invocation. Create directories. +* mkfifo: (coreutils)mkfifo invocation. Create FIFOs (named pipes). +* mknod: (coreutils)mknod invocation. Create special 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. +* 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. +* pr: (coreutils)pr invocation. Paginate or columnate files. +* printenv: (coreutils)printenv invocation. Print environment variables. +* printf: (coreutils)printf invocation. Format and print data. +* ptx: (coreutils)ptx invocation. Produce permuted indexes. +* pwd: (coreutils)pwd invocation. Print working directory. +* readlink: (coreutils)readlink invocation. Print referent of a symlink. +* rm: (coreutils)rm invocation. Remove files. +* rmdir: (coreutils)rmdir invocation. Remove empty directories. +* seq: (coreutils)seq invocation. Print numeric sequences +* sha1sum: (coreutils)sha1sum invocation. Print or check SHA-1 digests. +* sha2: (coreutils)sha2 utilities. Print or check SHA-2 digests. +* shred: (coreutils)shred invocation. Remove files more securely. +* 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. +* stat: (coreutils)stat invocation. Report file(system) status. +* stty: (coreutils)stty invocation. Print/change terminal settings. +* su: (coreutils)su invocation. Modify user and group ID. +* sum: (coreutils)sum invocation. Print traditional checksum. +* sync: (coreutils)sync invocation. Synchronize memory and disk. +* tac: (coreutils)tac invocation. Reverse files. +* tail: (coreutils)tail invocation. Output the last part of files. +* tee: (coreutils)tee invocation. Redirect to multiple files. +* test: (coreutils)test invocation. File/string tests. +* touch: (coreutils)touch invocation. Change file timestamps. +* tr: (coreutils)tr invocation. Translate characters. +* true: (coreutils)true invocation. Do nothing, successfully. +* tsort: (coreutils)tsort invocation. Topological sort. +* tty: (coreutils)tty invocation. Print terminal name. +* uname: (coreutils)uname invocation. Print system information. +* unexpand: (coreutils)unexpand invocation. Convert spaces to tabs. +* uniq: (coreutils)uniq invocation. Uniquify files. +* unlink: (coreutils)unlink invocation. Removal via unlink(2). +* users: (coreutils)users invocation. Print current user names. +* vdir: (coreutils)vdir invocation. List directories verbosely. +* wc: (coreutils)wc invocation. Line, word, and byte counts. +* who: (coreutils)who invocation. Print who is logged in. +* whoami: (coreutils)whoami invocation. Print effective user ID. +* yes: (coreutils)yes invocation. Print a string indefinitely. +END-INFO-DIR-ENTRY + + This manual documents version 6.9 of the GNU core utilities, +including the standard programs for text and file manipulation. + + Copyright (C) 1994, 1995, 1996, 2000, 2001, 2002, 2003, 2004, 2005, +2006 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with no Front-Cover Texts, + and with no Back-Cover Texts. A copy of the license is included + in the section entitled "GNU Free Documentation License". + + +File: coreutils.info, Node: Top, Next: Introduction, Up: (dir) + +GNU Coreutils +************* + +This manual documents version 6.9 of the GNU core utilities, including +the standard programs for text and file manipulation. + + Copyright (C) 1994, 1995, 1996, 2000, 2001, 2002, 2003, 2004, 2005, +2006 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, with no Front-Cover Texts, + and with no Back-Cover Texts. A copy of the license is included + in the section entitled "GNU Free Documentation License". + +* 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 +* 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 +* Modified command invocation:: chroot env nice nohup su +* 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. +* Copying This Manual:: License for copying this manual. +* Index:: General index. + + --- The Detailed Node Listing --- + +Common Options + +* Exit status:: Indicating program success or failure. +* Backup options:: Backup options +* Block size:: Block size +* 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 + +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. + +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. + +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. + +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. + +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. + +`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 GNU extensions to `ptx' + +Operating on fields within a line + +* 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': 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. + +Directory listing + +* ls invocation:: List directory contents +* dir invocation:: Briefly list directory contents +* vdir invocation:: Verbosely list directory contents +* dircolors invocation:: Color setup for `ls' + +`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 + +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 + +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 the referent of a symbolic link +* 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 + +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 + +Printing text + +* 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 + +`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 + +`expr': Evaluate expression + +* String expressions:: + : match substr index length +* Numeric expressions:: + - * / % +* Relations for expr:: | & < <= = == != >= > +* Examples of expr:: Examples of using `expr' + +Redirection + +* tee invocation:: Redirect output to multiple files + +File name manipulation + +* basename invocation:: Strip directory and suffix from a file name +* dirname invocation:: Strip non-directory suffix from a file name +* pathchk invocation:: Check file name portability + +Working context + +* pwd invocation:: Print working directory +* stty invocation:: Print or change terminal characteristics +* printenv invocation:: Print all or some environment variables +* tty invocation:: Print file name of terminal on standard input + +`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 + +User information + +* id invocation:: Print user identity +* logname invocation:: Print current login name +* whoami invocation:: Print effective user ID +* groups invocation:: Print group names a user is in +* users invocation:: Print login names of users currently logged in +* who invocation:: Print who is currently logged in + +System context + +* date invocation:: Print or set system date and time +* uname invocation:: Print system information +* hostname invocation:: Print or set system name +* hostid invocation:: Print numeric host identifier. + +`date': Print or set system date and time + +* Time conversion specifiers:: %[HIklMNpPrRsSTXzZ] +* 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. +* Examples of date:: Examples. + +Modified command invocation + +* chroot invocation:: Run a command with a different root directory +* env invocation:: Run a command in a modified environment +* nice invocation:: Run a command with modified niceness +* nohup invocation:: Run a command immune to hangups +* su invocation:: Run a command with substitute user and group ID + +Process control + +* kill invocation:: Sending a signal to processes. + +Delaying + +* sleep invocation:: Delay for a specified time + +Numeric operations + +* factor invocation:: Print prime factors +* seq invocation:: Print numeric sequences + +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. + +Date input formats + +* General date syntax:: Common rules. +* Calendar date items:: 19 Dec 1994. +* Time of day items:: 9:20pm. +* Time zone items:: EST, PDT, 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. + +Opening the software toolbox + +* Toolbox introduction:: Toolbox introduction +* I/O redirection:: I/O redirection +* The who command:: The `who' command +* The cut command:: The `cut' command +* The sort command:: The `sort' command +* The uniq command:: The `uniq' command +* Putting the tools together:: Putting the tools together + +Copying This Manual + +* GNU Free Documentation License:: License for copying this manual. + + +File: coreutils.info, Node: Introduction, Next: Common options, Prev: Top, Up: Top + +1 Introduction +************** + +This manual is a work in progress: many sections make no attempt to +explain basic concepts in a way suitable for novices. Thus, if you are +interested, please get involved in improving this manual. The entire +GNU community will benefit. + + The GNU utilities documented here are mostly compatible with the +POSIX standard. Please report bugs to <bug-coreutils@gnu.org>. +Remember to include the version number, machine architecture, input +files, and any other information needed to reproduce the bug: your +input, what you expected, what you got, and why it is wrong. Diffs are +welcome, but please include a description of the problem as well, since +this is sometimes difficult to infer. *Note Bugs: (gcc)Bugs. + + This manual was originally derived from the Unix man pages in the +distributions, which were written by David MacKenzie and updated by Jim +Meyering. What you are reading now is the authoritative documentation +for these utilities; the man pages are no longer being maintained. The +original `fmt' man page was written by Ross Paterson. Franc,ois Pinard +did the initial conversion to Texinfo format. Karl Berry did the +indexing, some reorganization, and editing of the results. Brian +Youmans of the Free Software Foundation office staff combined the +manuals for textutils, fileutils, and sh-utils to produce the present +omnibus manual. Richard Stallman contributed his usual invaluable +insights to the overall process. + + +File: coreutils.info, Node: Common options, Next: Output of entire files, Prev: Introduction, Up: Top + +2 Common options +**************** + +Certain options are available in all of these programs. Rather than +writing identical descriptions for each of the programs, they are +described here. (In fact, every GNU program accepts (or should accept) +these options.) + + Normally options and operands can appear in any order, and programs +act as if all the options appear before any operands. For example, +`sort -r passwd -t :' acts like `sort -r -t : passwd', since `:' is an +option-argument of `-t'. However, if the `POSIXLY_CORRECT' environment +variable is set, options must appear before operands, unless otherwise +specified for a particular command. + + A few programs can usefully have trailing operands with leading `-'. +With such a program, options must precede operands even if +`POSIXLY_CORRECT' is not set, and this fact is noted in the program +description. For example, the `env' command's options must appear +before its operands, since in some cases the operands specify a command +that itself contains options. + + Some of these programs recognize the `--help' and `--version' +options only when one of them is the sole command line argument. + +`--help' + Print a usage message listing all available options, then exit + successfully. + +`--version' + Print the version number, then exit successfully. + +`--' + Delimit the option list. Later arguments, if any, are treated as + operands even if they begin with `-'. For example, `sort -- -r' + reads from the file named `-r'. + + + A single `-' operand is not really an option, though it looks like +one. It stands for standard input, or for standard output if that is +clear from the context. For example, `sort -' reads from standard +input, and is equivalent to plain `sort', and `tee -' writes an extra +copy of its input to standard output. Unless otherwise specified, `-' +can appear as any operand that requires a file name. + +* Menu: + +* Exit status:: Indicating program success or failure. +* Backup options:: -b -S, in some programs. +* Block size:: BLOCK_SIZE and --block-size, in some programs. +* Disambiguating names and IDs:: chgrp and chown owner and group syntax +* Random sources:: --random-source, in some programs. +* Target directory:: Specifying a target directory, 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:: `break', `:', `eval', ... +* Standards conformance:: Conformance to the POSIX standard. + + +File: coreutils.info, Node: Exit status, Next: Backup options, Up: Common options + +2.1 Exit status +=============== + +Nearly every command invocation yields an integral "exit status" that +can be used to change how other commands work. For the vast majority +of commands, an exit status of zero indicates success. Failure is +indicated by a nonzero value--typically `1', though it may differ on +unusual platforms as POSIX requires only that it be nonzero. + + However, some of the programs documented here do produce other exit +status values and a few associate different meanings with the values +`0' and `1'. Here are some of the exceptions: `chroot', `env', `expr', +`nice', `nohup', `printenv', `sort', `su', `test', `tty'. + + +File: coreutils.info, Node: Backup options, Next: Block size, Prev: Exit status, Up: Common options + +2.2 Backup options +================== + +Some GNU programs (at least `cp', `install', `ln', and `mv') optionally +make backups of files before writing new versions. These options +control the details of these backups. The options are also briefly +mentioned in the descriptions of the particular programs. + +`-b' +`--backup[=METHOD]' + Make a backup of each file that would otherwise be overwritten or + removed. Without this option, the original versions are destroyed. + Use METHOD to determine the type of backups to make. When this + option is used but METHOD is not specified, then the value of the + `VERSION_CONTROL' environment variable is used. And if + `VERSION_CONTROL' is not set, the default backup type is + `existing'. + + Note that the short form of this option, `-b' does not accept any + argument. Using `-b' is equivalent to using `--backup=existing'. + + This option corresponds to the Emacs variable `version-control'; + the values for METHOD are the same as those used in Emacs. This + option also accepts more descriptive names. The valid METHODs are + (unique abbreviations are accepted): + + `none' + `off' + Never make backups. + + `numbered' + `t' + Always make numbered backups. + + `existing' + `nil' + Make numbered backups of files that already have them, simple + backups of the others. + + `simple' + `never' + Always make simple backups. Please note `never' is not to be + confused with `none'. + + +`-S SUFFIX' +`--suffix=SUFFIX' + Append SUFFIX to each backup file made with `-b'. If this option + is not specified, the value of the `SIMPLE_BACKUP_SUFFIX' + environment variable is used. And if `SIMPLE_BACKUP_SUFFIX' is not + set, the default is `~', just as in Emacs. + + + +File: coreutils.info, Node: Block size, Next: Disambiguating names and IDs, Prev: Backup options, Up: Common options + +2.3 Block size +============== + +Some GNU programs (at least `df', `du', and `ls') display sizes in +"blocks". You can adjust the block size and method of display to make +sizes easier to read. The block size used for display is independent +of any file system block size. Fractional block counts are rounded up +to the nearest integer. + + The default block size is chosen by examining the following +environment variables in turn; the first one that is set determines the +block size. + +`DF_BLOCK_SIZE' + This specifies the default block size for the `df' command. + Similarly, `DU_BLOCK_SIZE' specifies the default for `du' and + `LS_BLOCK_SIZE' for `ls'. + +`BLOCK_SIZE' + This specifies the default block size for all three commands, if + the above command-specific environment variables are not set. + +`BLOCKSIZE' + This specifies the default block size for all values that are + normally printed as blocks, if neither `BLOCK_SIZE' nor the above + command-specific environment variables are set. Unlike the other + environment variables, `BLOCKSIZE' does not affect values that are + normally printed as byte counts, e.g., the file sizes contained in + `ls -l' output. + +`POSIXLY_CORRECT' + If neither `COMMAND_BLOCK_SIZE', nor `BLOCK_SIZE', nor `BLOCKSIZE' + is set, but this variable is set, the block size defaults to 512. + + + If none of the above environment variables are set, the block size +currently defaults to 1024 bytes in most contexts, but this number may +change in the future. For `ls' file sizes, the block size defaults to +1 byte. + + A block size specification can be a positive integer specifying the +number of bytes per block, or it can be `human-readable' or `si' to +select a human-readable format. Integers may be followed by suffixes +that are upward compatible with the SI prefixes +(http://www.bipm.fr/enus/3_SI/si-prefixes.html) for decimal multiples +and with the IEC 60027-2 prefixes for binary multiples +(http://physics.nist.gov/cuu/Units/binary.html). + + With human-readable formats, output sizes are followed by a size +letter such as `M' for megabytes. `BLOCK_SIZE=human-readable' uses +powers of 1024; `M' stands for 1,048,576 bytes. `BLOCK_SIZE=si' is +similar, but uses powers of 1000 and appends `B'; `MB' stands for +1,000,000 bytes. + + A block size specification preceded by `'' causes output sizes to be +displayed with thousands separators. The `LC_NUMERIC' locale specifies +the thousands separator and grouping. For example, in an American +English locale, `--block-size="'1kB"' would cause a size of 1234000 +bytes to be displayed as `1,234'. In the default C locale, there is no +thousands separator so a leading `'' has no effect. + + An integer block size can be followed by a suffix to specify a +multiple of that size. A bare size letter, or one followed by `iB', +specifies a multiple using powers of 1024. A size letter followed by +`B' specifies powers of 1000 instead. For example, `1M' and `1MiB' are +equivalent to `1048576', whereas `1MB' is equivalent to `1000000'. + + A plain suffix without a preceding integer acts as if `1' were +prepended, except that it causes a size indication to be appended to +the output. For example, `--block-size="kB"' displays 3000 as `3kB'. + + The following suffixes are defined. Large sizes like `1Y' may be +rejected by your computer due to limitations of its arithmetic. + +`kB' + kilobyte: 10^3 = 1000. + +`k' +`K' +`KiB' + kibibyte: 2^10 = 1024. `K' is special: the SI prefix is `k' and + the IEC 60027-2 prefix is `Ki', but tradition and POSIX use `k' to + mean `KiB'. + +`MB' + megabyte: 10^6 = 1,000,000. + +`M' +`MiB' + mebibyte: 2^20 = 1,048,576. + +`GB' + gigabyte: 10^9 = 1,000,000,000. + +`G' +`GiB' + gibibyte: 2^30 = 1,073,741,824. + +`TB' + terabyte: 10^12 = 1,000,000,000,000. + +`T' +`TiB' + tebibyte: 2^40 = 1,099,511,627,776. + +`PB' + petabyte: 10^15 = 1,000,000,000,000,000. + +`P' +`PiB' + pebibyte: 2^50 = 1,125,899,906,842,624. + +`EB' + exabyte: 10^18 = 1,000,000,000,000,000,000. + +`E' +`EiB' + exbibyte: 2^60 = 1,152,921,504,606,846,976. + +`ZB' + zettabyte: 10^21 = 1,000,000,000,000,000,000,000 + +`Z' +`ZiB' + 2^70 = 1,180,591,620,717,411,303,424. (`Zi' is a GNU extension to + IEC 60027-2.) + +`YB' + yottabyte: 10^24 = 1,000,000,000,000,000,000,000,000. + +`Y' +`YiB' + 2^80 = 1,208,925,819,614,629,174,706,176. (`Yi' is a GNU + extension to IEC 60027-2.) + + Block size defaults can be overridden by an explicit +`--block-size=SIZE' option. The `-k' option is equivalent to +`--block-size=1K', which is the default unless the `POSIXLY_CORRECT' +environment variable is set. The `-h' or `--human-readable' option is +equivalent to `--block-size=human-readable'. The `--si' option is +equivalent to `--block-size=si'. + + +File: coreutils.info, Node: Disambiguating names and IDs, Next: Random sources, Prev: Block size, Up: Common options + +2.4 chown and chgrp: Disambiguating user names and IDs +====================================================== + +Since the OWNER and GROUP arguments to `chown' and `chgrp' may be +specified as names or numeric IDs, there is an apparent ambiguity. +What if a user or group _name_ is a string of digits? (1) Should the +command interpret it as a user name or as an ID? POSIX requires that +`chown' and `chgrp' first attempt to resolve the specified string as a +name, and only once that fails, then try to interpret it as an ID. +This is troublesome when you want to specify a numeric ID, say 42, and +it must work even in a pathological situation where `42' is a user name +that maps to some other user ID, say 1000. Simply invoking `chown 42 +F', will set `F's owner ID to 1000--not what you intended. + + GNU `chown' and `chgrp' provide a way to work around this, that at +the same time may result in a significant performance improvement by +eliminating a database look-up. Simply precede each numeric user ID +and/or group ID with a `+', in order to force its interpretation as an +integer: + + chown +42 F + chgrp +$numeric_group_id another-file + chown +0:+0 / + + GNU `chown' and `chgrp' skip the name look-up process for each +`+'-prefixed string, because a string containing `+' is never a valid +user or group name. This syntax is accepted on most common Unix +systems, but not on Solaris 10. + + ---------- Footnotes ---------- + + (1) Using a number as a user name is common in some environments. + + +File: coreutils.info, Node: Random sources, Next: Target directory, Prev: Disambiguating names and IDs, Up: Common options + +2.5 Sources of random data +========================== + +The `shuf', `shred', and `sort' commands sometimes need random data to +do their work. For example, `sort -R' must choose a hash function at +random, and it needs random data to make this selection. + + Normally these commands use the device file `/dev/urandom' as the +source of random data. Typically, this device gathers environmental +noise from device drivers and other sources into an entropy pool, and +uses the pool to generate random bits. If the pool is short of data, +the device reuses the internal pool to produce more bits, using a +cryptographically secure pseudorandom number generator. + + `/dev/urandom' suffices for most practical uses, but applications +requiring high-value or long-term protection of private data may +require an alternate data source like `/dev/random' or `/dev/arandom'. +The set of available sources depends on your operating system. + + To use such a source, specify the `--random-source=FILE' option, +e.g., `shuf --random-source=/dev/random'. The contents of FILE should +be as random as possible. An error is reported if FILE does not +contain enough bytes to randomize the input adequately. + + To reproduce the results of an earlier invocation of a command, you +can save some random data into a file and then use that file as the +random source in earlier and later invocations of the command. + + Some old-fashioned or stripped-down operating systems lack support +for `/dev/urandom'. On these systems commands like `shuf' by default +fall back on an internal pseudorandom generator initialized by a small +amount of entropy. + + +File: coreutils.info, Node: Target directory, Next: Trailing slashes, Prev: Random sources, Up: Common options + +2.6 Target directory +==================== + +The `cp', `install', `ln', and `mv' commands normally treat the last +operand specially when it is a directory or a symbolic link to a +directory. For example, `cp source dest' is equivalent to `cp source +dest/source' if `dest' is a directory. Sometimes this behavior is not +exactly what is wanted, so these commands support the following options +to allow more fine-grained control: + +`-T' +`--no-target-directory' + Do not treat the last operand specially when it is a directory or a + symbolic link to a directory. This can help avoid race conditions + in programs that operate in a shared area. For example, when the + command `mv /tmp/source /tmp/dest' succeeds, there is no guarantee + that `/tmp/source' was renamed to `/tmp/dest': it could have been + renamed to `/tmp/dest/source' instead, if some other process + created `/tmp/dest' as a directory. However, if `mv -T + /tmp/source /tmp/dest' succeeds, there is no question that + `/tmp/source' was renamed to `/tmp/dest'. + + In the opposite situation, where you want the last operand to be + treated as a directory and want a diagnostic otherwise, you can use + the `--target-directory' (`-t') option. + +`-t DIRECTORY' +`--target-directory=DIRECTORY' + Use DIRECTORY as the directory component of each destination file + name. + + The interface for most programs is that after processing options + and a finite (possibly zero) number of fixed-position arguments, + the remaining argument list is either expected to be empty, or is + a list of items (usually files) that will all be handled + identically. The `xargs' program is designed to work well with + this convention. + + The commands in the `mv'-family are unusual in that they take a + variable number of arguments with a special case at the _end_ + (namely, the target directory). This makes it nontrivial to + perform some operations, e.g., "move all files from here to + ../d/", because `mv * ../d/' might exhaust the argument space, and + `ls | xargs ...' doesn't have a clean way to specify an extra + final argument for each invocation of the subject command. (It + can be done by going through a shell command, but that requires + more human labor and brain power than it should.) + + The `--target-directory' (`-t') option allows the `cp', `install', + `ln', and `mv' programs to be used conveniently with `xargs'. For + example, you can move the files from the current directory to a + sibling directory, `d' like this: + + ls | xargs mv -t ../d -- + + However, this doesn't move files whose names begin with `.'. If + you use the GNU `find' program, you can move those files too, with + this command: + + find . -mindepth 1 -maxdepth 1 \ + | xargs mv -t ../d + + But both of the above approaches fail if there are no files in the + current directory, or if any file has a name containing a blank or + some other special characters. The following example removes + those limitations and requires both GNU `find' and GNU `xargs': + + find . -mindepth 1 -maxdepth 1 -print0 \ + | xargs --null --no-run-if-empty \ + mv -t ../d + + +The `--target-directory' (`-t') and `--no-target-directory' (`-T') +options cannot be combined. + + +File: coreutils.info, Node: Trailing slashes, Next: Traversing symlinks, Prev: Target directory, Up: Common options + +2.7 Trailing slashes +==================== + +Some GNU programs (at least `cp' and `mv') allow you to remove any +trailing slashes from each SOURCE argument before operating on it. The +`--strip-trailing-slashes' option enables this behavior. + + This is useful when a SOURCE argument may have a trailing slash and +specify a symbolic link to a directory. This scenario is in fact rather +common because some shells can automatically append a trailing slash +when performing file name completion on such symbolic links. Without +this option, `mv', for example, (via the system's rename function) must +interpret a trailing slash as a request to dereference the symbolic link +and so must rename the indirectly referenced _directory_ and not the +symbolic link. Although it may seem surprising that such behavior be +the default, it is required by POSIX and is consistent with other parts +of that standard. + + +File: coreutils.info, Node: Traversing symlinks, Next: Treating / specially, Prev: Trailing slashes, Up: Common options + +2.8 Traversing symlinks +======================= + +The following options modify how `chown' and `chgrp' traverse a +hierarchy when the `--recursive' (`-R') option is also specified. If +more than one of the following options is specified, only the final one +takes effect. These options specify whether processing a symbolic link +to a directory entails operating on just the symbolic link or on all +files in the hierarchy rooted at that directory. + + These options are independent of `--dereference' and +`--no-dereference' (`-h'), which control whether to modify a symlink or +its referent. + +`-H' + If `--recursive' (`-R') is specified and a command line argument + is a symbolic link to a directory, traverse it. + +`-L' + In a recursive traversal, traverse every symbolic link to a + directory that is encountered. + +`-P' + Do not traverse any symbolic links. This is the default if none + of `-H', `-L', or `-P' is specified. + + + +File: coreutils.info, Node: Treating / specially, Next: Special built-in utilities, Prev: Traversing symlinks, Up: Common options + +2.9 Treating / specially +======================== + +Certain commands can operate destructively on entire hierarchies. For +example, if a user with appropriate privileges mistakenly runs `rm -rf +/ tmp/junk', that may remove all files on the entire system. Since +there are so few legitimate uses for such a command, GNU `rm' normally +declines to operate on any directory that resolves to `/'. If you +really want to try to remove all the files on your system, you can use +the `--no-preserve-root' option, but the default behavior, specified by +the `--preserve-option', is safer for most purposes. + + The commands `chgrp', `chmod' and `chown' can also operate +destructively on entire hierarchies, so they too support these options. +Although, unlike `rm', they don't actually unlink files, these +commands are arguably more dangerous when operating recursively on `/', +since they often work much more quickly, and hence damage more files +before an alert user can interrupt them. Tradition and POSIX require +these commands to operate recursively on `/', so they default to +`--no-preserve-root', but using the `--preserve-root' option makes them +safer for most purposes. For convenience you can specify +`--preserve-root' in an alias or in a shell function. + + Note that the `--preserve-root' option also ensures that `chgrp' and +`chown' do not modify `/' even when dereferencing a symlink pointing to +`/'. + + +File: coreutils.info, Node: Special built-in utilities, Next: Standards conformance, Prev: Treating / specially, Up: Common options + +2.10 Special built-in utilities +=============================== + +Some programs like `nice' can invoke other programs; for example, the +command `nice cat file' invokes the program `cat' by executing the +command `cat file'. However, "special built-in utilities" like `exit' +cannot be invoked this way. For example, the command `nice exit' does +not have a well-defined behavior: it may generate an error message +instead of exiting. + + Here is a list of the special built-in utilities that are +standardized by POSIX 1003.1-2004. + + . : break continue eval exec exit export readonly return set shift + times trap unset + + For example, because `.', `:', and `exec' are special, the commands +`nice . foo.sh', `nice :', and `nice exec pwd' do not work as you might +expect. + + Many shells extend this list. For example, Bash has several extra +special built-in utilities like `history', and `suspend', and with Bash +the command `nice suspend' generates an error message instead of +suspending. + + +File: coreutils.info, Node: Standards conformance, Prev: Special built-in utilities, Up: Common options + +2.11 Standards conformance +========================== + +In a few cases, the GNU utilities' default behavior is incompatible +with the POSIX standard. To suppress these incompatibilities, define +the `POSIXLY_CORRECT' environment variable. Unless you are checking +for POSIX conformance, you probably do not need to define +`POSIXLY_CORRECT'. + + Newer versions of POSIX are occasionally incompatible with older +versions. For example, older versions of POSIX required the command +`sort +1' to sort based on the second and succeeding fields in each +input line, but starting with POSIX 1003.1-2001 the same command is +required to sort the file named `+1', and you must instead use the +command `sort -k 2' to get the field-based sort. + + The GNU utilities normally conform to the version of POSIX that is +standard for your system. To cause them to conform to a different +version of POSIX, define the `_POSIX2_VERSION' environment variable to +a value of the form YYYYMM specifying the year and month the standard +was adopted. Two values are currently supported for `_POSIX2_VERSION': +`199209' stands for POSIX 1003.2-1992, and `200112' stands for POSIX +1003.1-2001. For example, if you have a newer system but are running +software that assumes an older version of POSIX and uses `sort +1' or +`tail +10', you can work around any compatibility problems by setting +`_POSIX2_VERSION=199209' in your environment. + + +File: coreutils.info, Node: Output of entire files, Next: Formatting file contents, Prev: Common options, Up: Top + +3 Output of entire files +************************ + +These commands read and write entire files, possibly transforming them +in some way. + +* Menu: + +* 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. + + +File: coreutils.info, Node: cat invocation, Next: tac invocation, Up: Output of entire files + +3.1 `cat': Concatenate and write files +====================================== + +`cat' copies each FILE (`-' means standard input), or standard input if +none are given, to standard output. Synopsis: + + cat [OPTION] [FILE]... + + The program accepts the following options. Also see *Note Common +options::. + +`-A' +`--show-all' + Equivalent to `-vET'. + +`-b' +`--number-nonblank' + Number all nonblank output lines, starting with 1. + +`-e' + Equivalent to `-vE'. + +`-E' +`--show-ends' + Display a `$' after the end of each line. + +`-n' +`--number' + Number all output lines, starting with 1. + +`-s' +`--squeeze-blank' + Replace multiple adjacent blank lines with a single blank line. + +`-t' + Equivalent to `-vT'. + +`-T' +`--show-tabs' + Display TAB characters as `^I'. + +`-u' + Ignored; for POSIX compatibility. + +`-v' +`--show-nonprinting' + Display control characters except for LFD and TAB using `^' + notation and precede characters that have the high bit set with + `M-'. + + + On systems like MS-DOS that distinguish between text and binary +files, `cat' normally reads and writes in binary mode. However, `cat' +reads in text mode if one of the options `-bensAE' is used or if `cat' +is reading from standard input and standard input is a terminal. +Similarly, `cat' writes in text mode if one of the options `-bensAE' is +used or if standard output is a terminal. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + Examples: + + # Output f's contents, then standard input, then g's contents. + cat f - g + + # Copy standard input to standard output. + cat + + +File: coreutils.info, Node: tac invocation, Next: nl invocation, Prev: cat invocation, Up: Output of entire files + +3.2 `tac': Concatenate and write files in reverse +================================================= + +`tac' copies each FILE (`-' means standard input), or standard input if +none are given, to standard output, reversing the records (lines by +default) in each separately. Synopsis: + + tac [OPTION]... [FILE]... + + "Records" are separated by instances of a string (newline by +default). By default, this separator string is attached to the end of +the record that it follows in the file. + + The program accepts the following options. Also see *Note Common +options::. + +`-b' +`--before' + The separator is attached to the beginning of the record that it + precedes in the file. + +`-r' +`--regex' + Treat the separator string as a regular expression. Users of `tac' + on MS-DOS/MS-Windows should note that, since `tac' reads files in + binary mode, each line of a text file might end with a CR/LF pair + instead of the Unix-style LF. + +`-s SEPARATOR' +`--separator=SEPARATOR' + Use SEPARATOR as the record separator, instead of newline. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: nl invocation, Next: od invocation, Prev: tac invocation, Up: Output of entire files + +3.3 `nl': Number lines and write files +====================================== + +`nl' writes each FILE (`-' means standard input), or standard input if +none are given, to standard output, with line numbers added to some or +all of the lines. Synopsis: + + nl [OPTION]... [FILE]... + + `nl' decomposes its input into (logical) pages; by default, the line +number is reset to 1 at the top of each logical page. `nl' treats all +of the input files as a single document; it does not reset line numbers +or logical pages between files. + + A logical page consists of three sections: header, body, and footer. +Any of the sections can be empty. Each can be numbered in a different +style from the others. + + The beginnings of the sections of logical pages are indicated in the +input file by a line containing exactly one of these delimiter strings: + +`\:\:\:' + start of header; + +`\:\:' + start of body; + +`\:' + start of footer. + + The two characters from which these strings are made can be changed +from `\' and `:' via options (see below), but the pattern and length of +each string cannot be changed. + + A section delimiter is replaced by an empty line on output. Any text +that comes before the first section delimiter string in the input file +is considered to be part of a body section, so `nl' treats a file that +contains no section delimiters as a single body section. + + The program accepts the following options. Also see *Note Common +options::. + +`-b STYLE' +`--body-numbering=STYLE' + Select the numbering style for lines in the body section of each + logical page. When a line is not numbered, the current line number + is not incremented, but the line number separator character is + still prepended to the line. The styles are: + + `a' + number all lines, + + `t' + number only nonempty lines (default for body), + + `n' + do not number lines (default for header and footer), + + `pBRE' + number only lines that contain a match for the basic regular + expression BRE. *Note Regular Expressions: (grep)Regular + Expressions. + +`-d CD' +`--section-delimiter=CD' + Set the section delimiter characters to CD; default is `\:'. If + only C is given, the second remains `:'. (Remember to protect `\' + or other metacharacters from shell expansion with quotes or extra + backslashes.) + +`-f STYLE' +`--footer-numbering=STYLE' + Analogous to `--body-numbering'. + +`-h STYLE' +`--header-numbering=STYLE' + Analogous to `--body-numbering'. + +`-i NUMBER' +`--page-increment=NUMBER' + Increment line numbers by NUMBER (default 1). + +`-l NUMBER' +`--join-blank-lines=NUMBER' + Consider NUMBER (default 1) consecutive empty lines to be one + logical line for numbering, and only number the last one. Where + fewer than NUMBER consecutive empty lines occur, do not number + them. An empty line is one that contains no characters, not even + spaces or tabs. + +`-n FORMAT' +`--number-format=FORMAT' + Select the line numbering format (default is `rn'): + + `ln' + left justified, no leading zeros; + + `rn' + right justified, no leading zeros; + + `rz' + right justified, leading zeros. + +`-p' +`--no-renumber' + Do not reset the line number at the start of a logical page. + +`-s STRING' +`--number-separator=STRING' + Separate the line number from the text line in the output with + STRING (default is the TAB character). + +`-v NUMBER' +`--starting-line-number=NUMBER' + Set the initial line number on each logical page to NUMBER + (default 1). + +`-w NUMBER' +`--number-width=NUMBER' + Use NUMBER characters for line numbers (default 6). + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: od invocation, Next: base64 invocation, Prev: nl invocation, Up: Output of entire files + +3.4 `od': Write files in octal or other formats +=============================================== + +`od' writes an unambiguous representation of each FILE (`-' means +standard input), or standard input if none are given. Synopses: + + od [OPTION]... [FILE]... + od [-abcdfilosx]... [FILE] [[+]OFFSET[.][b]] + od [OPTION]... --traditional [FILE] [[+]OFFSET[.][b] [[+]LABEL[.][b]]] + + Each line of output consists of the offset in the input, followed by +groups of data from the file. By default, `od' prints the offset in +octal, and each group of file data is a C `short int''s worth of input +printed as a single octal number. + + If OFFSET is given, it specifies how many input bytes to skip before +formatting and writing. By default, it is interpreted as an octal +number, but the optional trailing decimal point causes it to be +interpreted as decimal. If no decimal is specified and the offset +begins with `0x' or `0X' it is interpreted as a hexadecimal number. If +there is a trailing `b', the number of bytes skipped will be OFFSET +multiplied by 512. + + If a command is of both the first and second forms, the second form +is assumed if the last operand begins with `+' or (if there are two +operands) a digit. For example, in `od foo 10' and `od +10' the `10' +is an offset, whereas in `od 10' the `10' is a file name. + + The program accepts the following options. Also see *Note Common +options::. + +`-A RADIX' +`--address-radix=RADIX' + Select the base in which file offsets are printed. RADIX can be + one of the following: + + `d' + decimal; + + `o' + octal; + + `x' + hexadecimal; + + `n' + none (do not print offsets). + + The default is octal. + +`-j BYTES' +`--skip-bytes=BYTES' + Skip BYTES input bytes before formatting and writing. If BYTES + begins with `0x' or `0X', it is interpreted in hexadecimal; + otherwise, if it begins with `0', in octal; otherwise, in decimal. + Appending `b' multiplies BYTES by 512, `k' by 1024, and `m' by + 1048576. + +`-N BYTES' +`--read-bytes=BYTES' + Output at most BYTES bytes of the input. Prefixes and suffixes on + `bytes' are interpreted as for the `-j' option. + +`-S N' +`--strings[=N]' + Instead of the normal output, output only "string constants": at + least N consecutive ASCII graphic characters, followed by a null + (zero) byte. + + If N is omitted with `--strings', the default is 3. + +`-t TYPE' +`--format=TYPE' + Select the format in which to output the file data. TYPE is a + string of one or more of the below type indicator characters. If + you include more than one type indicator character in a single TYPE + string, or use this option more than once, `od' writes one copy of + each output line using each of the data types that you specified, + in the order that you specified. + + Adding a trailing "z" to any type specification appends a display + of the ASCII character representation of the printable characters + to the output line generated by the type specification. + + `a' + named character, ignoring high-order bit + + `c' + ASCII character or backslash escape, + + `d' + signed decimal + + `f' + floating point + + `o' + octal + + `u' + unsigned decimal + + `x' + hexadecimal + + The type `a' outputs things like `sp' for space, `nl' for newline, + and `nul' for a null (zero) byte. Only the least significant + seven bits of each byte is used; the high-order bit is ignored. + Type `c' outputs ` ', `\n', and `\0', respectively. + + Except for types `a' and `c', you can specify the number of bytes + to use in interpreting each number in the given data type by + following the type indicator character with a decimal integer. + Alternately, you can specify the size of one of the C compiler's + built-in data types by following the type indicator character with + one of the following characters. For integers (`d', `o', `u', + `x'): + + `C' + char + + `S' + short + + `I' + int + + `L' + long + + For floating point (`f'): + + F + float + + D + double + + L + long double + +`-v' +`--output-duplicates' + Output consecutive lines that are identical. By default, when two + or more consecutive output lines would be identical, `od' outputs + only the first line, and puts just an asterisk on the following + line to indicate the elision. + +`-w[N]' +`--width[=N]' + Dump `n' input bytes per output line. This must be a multiple of + the least common multiple of the sizes associated with the + specified output types. + + If this option is not given at all, the default is 16. If N is + omitted, the default is 32. + + + The next several options are shorthands for format specifications. +GNU `od' accepts any combination of shorthands and format specification +options. These options accumulate. + +`-a' + Output as named characters. Equivalent to `-t a'. + +`-b' + Output as octal bytes. Equivalent to `-t o1'. + +`-c' + Output as ASCII characters or backslash escapes. Equivalent to + `-t c'. + +`-d' + Output as unsigned decimal two-byte units. Equivalent to `-t u2'. + +`-f' + Output as floats. Equivalent to `-t fF'. + +`-i' + Output as decimal ints. Equivalent to `-t dI'. + +`-l' + Output as decimal long ints. Equivalent to `-t dL'. + +`-o' + Output as octal two-byte units. Equivalent to `-t o2'. + +`-s' + Output as decimal two-byte units. Equivalent to `-t d2'. + +`-x' + Output as hexadecimal two-byte units. Equivalent to `-t x2'. + +`--traditional' + Recognize the non-option label argument that traditional `od' + accepted. The following syntax: + + od --traditional [FILE] [[+]OFFSET[.][b] [[+]LABEL[.][b]]] + + can be used to specify at most one file and optional arguments + specifying an offset and a pseudo-start address, LABEL. The LABEL + argument is interpreted just like OFFSET, but it specifies an + initial pseudo-address. The pseudo-addresses are displayed in + parentheses following any normal address. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: base64 invocation, Prev: od invocation, Up: Output of entire files + +3.5 `base64': Transform data into printable data. +================================================= + +`base64' transforms data read from a file, or standard input, into (or +from) base64 encoded form. The base64 encoded form uses printable +ASCII characters to represent binary data, see RFC 3548 +(ftp://ftp.rfc-editor.org/in-notes/rfc3548.txt). Synopses: + + base64 [OPTION]... [FILE] + base64 --decode [OPTION]... [FILE] + + The base64 encoding expands data to roughly 133% of the original. + + The program accepts the following options. Also see *Note Common +options::. + +`-w COLS' +`--wrap=COLS' + During encoding, wrap lines after COLS characters. This must be a + positive number. + + The default is to wrap after 76 characters. Use the value 0 to + disable line wrapping altogether. + +`-d' +`--decode' + Change the mode of operation, from the default of encoding data, to + decoding data. Input is expected to be base64 encoded data, and + the output will be the original data. + +`-i' +`--ignore-garbage' + When decoding, newlines are always accepted. During decoding, + ignore unrecognized bytes, to permit distorted data to be decoded. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Formatting file contents, Next: Output of parts of files, Prev: Output of entire files, Up: Top + +4 Formatting file contents +************************** + +These commands reformat the contents of files. + +* Menu: + +* fmt invocation:: Reformat paragraph text. +* pr invocation:: Paginate or columnate files for printing. +* fold invocation:: Wrap input lines to fit in specified width. + + +File: coreutils.info, Node: fmt invocation, Next: pr invocation, Up: Formatting file contents + +4.1 `fmt': Reformat paragraph text +================================== + +`fmt' fills and joins lines to produce output lines of (at most) a +given number of characters (75 by default). Synopsis: + + fmt [OPTION]... [FILE]... + + `fmt' reads from the specified FILE arguments (or standard input if +none are given), and writes to standard output. + + By default, blank lines, spaces between words, and indentation are +preserved in the output; successive input lines with different +indentation are not joined; tabs are expanded on input and introduced on +output. + + `fmt' prefers breaking lines at the end of a sentence, and tries to +avoid line breaks after the first word of a sentence or before the last +word of a sentence. A "sentence break" is defined as either the end of +a paragraph or a word ending in any of `.?!', followed by two spaces or +end of line, ignoring any intervening parentheses or quotes. Like TeX, +`fmt' reads entire "paragraphs" before choosing line breaks; the +algorithm is a variant of that given by Donald E. Knuth and Michael F. +Plass in "Breaking Paragraphs Into Lines", `Software--Practice & +Experience' 11, 11 (November 1981), 1119-1184. + + The program accepts the following options. Also see *Note Common +options::. + +`-c' +`--crown-margin' + "Crown margin" mode: preserve the indentation of the first two + lines within a paragraph, and align the left margin of each + subsequent line with that of the second line. + +`-t' +`--tagged-paragraph' + "Tagged paragraph" mode: like crown margin mode, except that if + indentation of the first line of a paragraph is the same as the + indentation of the second, the first line is treated as a one-line + paragraph. + +`-s' +`--split-only' + Split lines only. Do not join short lines to form longer ones. + This prevents sample lines of code, and other such "formatted" + text from being unduly combined. + +`-u' +`--uniform-spacing' + Uniform spacing. Reduce spacing between words to one space, and + spacing between sentences to two spaces. + +`-WIDTH' +`-w WIDTH' +`--width=WIDTH' + Fill output lines up to WIDTH characters (default 75). `fmt' + initially tries to make lines about 7% shorter than this, to give + it room to balance line lengths. + +`-p PREFIX' +`--prefix=PREFIX' + Only lines beginning with PREFIX (possibly preceded by whitespace) + are subject to formatting. The prefix and any preceding + whitespace are stripped for the formatting and then re-attached to + each formatted output line. One use is to format certain kinds of + program comments, while leaving the code unchanged. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: pr invocation, Next: fold invocation, Prev: fmt invocation, Up: Formatting file contents + +4.2 `pr': Paginate or columnate files for printing +================================================== + +`pr' writes each FILE (`-' means standard input), or standard input if +none are given, to standard output, paginating and optionally +outputting in multicolumn format; optionally merges all FILEs, printing +all in parallel, one per column. Synopsis: + + pr [OPTION]... [FILE]... + + By default, a 5-line header is printed at each page: two blank lines; +a line with the date, the file name, and the page count; and two more +blank lines. A footer of five blank lines is also printed. With the +`-F' option, a 3-line header is printed: the leading two blank lines are +omitted; no footer is used. The default PAGE_LENGTH in both cases is 66 +lines. The default number of text lines changes from 56 (without `-F') +to 63 (with `-F'). The text line of the header takes the form `DATE +STRING PAGE', with spaces inserted around STRING so that the line takes +up the full PAGE_WIDTH. Here, DATE is the date (see the `-D' or +`--date-format' option for details), STRING is the centered header +string, and PAGE identifies the page number. The `LC_MESSAGES' locale +category affects the spelling of PAGE; in the default C locale, it is +`Page NUMBER' where NUMBER is the decimal page number. + + Form feeds in the input cause page breaks in the output. Multiple +form feeds produce empty pages. + + Columns are of equal width, separated by an optional string (default +is `space'). For multicolumn output, lines will always be truncated to +PAGE_WIDTH (default 72), unless you use the `-J' option. For single +column output no line truncation occurs by default. Use `-W' option to +truncate lines in that case. + + The following changes were made in version 1.22i and apply to later +versions of `pr': - Brian + * Some small LETTER OPTIONS (`-s', `-w') have been redefined for + better POSIX compliance. The output of some further cases has + been adapted to other Unix systems. These changes are not + compatible with earlier versions of the program. + + * Some NEW CAPITAL LETTER options (`-J', `-S', `-W') have been + introduced to turn off unexpected interferences of small letter + options. The `-N' option and the second argument LAST_PAGE of + `+FIRST_PAGE' offer more flexibility. The detailed handling of + form feeds set in the input files requires the `-T' option. + + * Capital letter options override small letter ones. + + * Some of the option-arguments (compare `-s', `-e', `-i', `-n') + cannot be specified as separate arguments from the preceding + option letter (already stated in the POSIX specification). + + The program accepts the following options. Also see *Note Common +options::. + +`+FIRST_PAGE[:LAST_PAGE]' +`--pages=FIRST_PAGE[:LAST_PAGE]' + Begin printing with page FIRST_PAGE and stop with LAST_PAGE. + Missing `:LAST_PAGE' implies end of file. While estimating the + number of skipped pages each form feed in the input file results + in a new page. Page counting with and without `+FIRST_PAGE' is + identical. By default, counting starts with the first page of + input file (not first page printed). Line numbering may be + altered by `-N' option. + +`-COLUMN' +`--columns=COLUMN' + With each single FILE, produce COLUMN columns of output (default + is 1) and print columns down, unless `-a' is used. The column + width is automatically decreased as COLUMN increases; unless you + use the `-W/-w' option to increase PAGE_WIDTH as well. This + option might well cause some lines to be truncated. The number of + lines in the columns on each page are balanced. The options `-e' + and `-i' are on for multiple text-column output. Together with + `-J' option column alignment and line truncation is turned off. + Lines of full length are joined in a free field format and `-S' + option may set field separators. `-COLUMN' may not be used with + `-m' option. + +`-a' +`--across' + With each single FILE, print columns across rather than down. The + `-COLUMN' option must be given with COLUMN greater than one. If a + line is too long to fit in a column, it is truncated. + +`-c' +`--show-control-chars' + Print control characters using hat notation (e.g., `^G'); print + other nonprinting characters in octal backslash notation. By + default, nonprinting characters are not changed. + +`-d' +`--double-space' + Double space the output. + +`-D FORMAT' +`--date-format=FORMAT' + Format header dates using FORMAT, using the same conventions as + for the command `date +FORMAT'; *Note date invocation::. Except + for directives, which start with `%', characters in FORMAT are + printed unchanged. You can use this option to specify an + arbitrary string in place of the header date, e.g., + `--date-format="Monday morning"'. + + Normally the date format defaults to `%Y-%m-%d %H:%M' (for + example, `2001-12-04 23:59'); but if the `POSIXLY_CORRECT' + environment variable is set and the `LC_TIME' locale category + specifies the POSIX locale, the default is `%b %e %H:%M %Y' (for + example, `Dec 4 23:59 2001'. + + Time stamps are listed according to the time zone rules specified + by the `TZ' environment variable, or by the system default rules if + `TZ' is not set. *Note Specifying the Time Zone with `TZ': + (libc)TZ Variable. + +`-e[IN-TABCHAR[IN-TABWIDTH]]' +`--expand-tabs[=IN-TABCHAR[IN-TABWIDTH]]' + Expand TABs to spaces on input. Optional argument IN-TABCHAR is + the input tab character (default is the TAB character). Second + optional argument IN-TABWIDTH is the input tab character's width + (default is 8). + +`-f' +`-F' +`--form-feed' + Use a form feed instead of newlines to separate output pages. The + default page length of 66 lines is not altered. But the number of + lines of text per page changes from default 56 to 63 lines. + +`-h HEADER' +`--header=HEADER' + Replace the file name in the header with the centered string + HEADER. When using the shell, HEADER should be quoted and should + be separated from `-h' by a space. + +`-i[OUT-TABCHAR[OUT-TABWIDTH]]' +`--output-tabs[=OUT-TABCHAR[OUT-TABWIDTH]]' + Replace spaces with TABs on output. Optional argument OUT-TABCHAR + is the output tab character (default is the TAB character). + Second optional argument OUT-TABWIDTH is the output tab + character's width (default is 8). + +`-J' +`--join-lines' + Merge lines of full length. Used together with the column options + `-COLUMN', `-a -COLUMN' or `-m'. Turns off `-W/-w' line + truncation; no column alignment used; may be used with + `--sep-string[=STRING]'. `-J' has been introduced (together with + `-W' and `--sep-string') to disentangle the old (POSIX-compliant) + options `-w' and `-s' along with the three column options. + +`-l PAGE_LENGTH' +`--length=PAGE_LENGTH' + Set the page length to PAGE_LENGTH (default 66) lines, including + the lines of the header [and the footer]. If PAGE_LENGTH is less + than or equal to 10 (or <= 3 with `-F'), the header and footer are + omitted, and all form feeds set in input files are eliminated, as + if the `-T' option had been given. + +`-m' +`--merge' + Merge and print all FILEs in parallel, one in each column. If a + line is too long to fit in a column, it is truncated, unless the + `-J' option is used. `--sep-string[=STRING]' may be used. Empty + pages in some FILEs (form feeds set) produce empty columns, still + marked by STRING. The result is a continuous line numbering and + column marking throughout the whole merged file. Completely empty + merged pages show no separators or line numbers. The default + header becomes `DATE PAGE' with spaces inserted in the middle; this + may be used with the `-h' or `--header' option to fill up the + middle blank part. + +`-n[NUMBER-SEPARATOR[DIGITS]]' +`--number-lines[=NUMBER-SEPARATOR[DIGITS]]' + Provide DIGITS digit line numbering (default for DIGITS is 5). + With multicolumn output the number occupies the first DIGITS + column positions of each text column or only each line of `-m' + output. With single column output the number precedes each line + just as `-m' does. Default counting of the line numbers starts + with the first line of the input file (not the first line printed, + compare the `--page' option and `-N' option). Optional argument + NUMBER-SEPARATOR is the character appended to the line number to + separate it from the text followed. The default separator is the + TAB character. In a strict sense a TAB is always printed with + single column output only. The TAB-width varies with the + TAB-position, e.g., with the left MARGIN specified by `-o' option. + With multicolumn output priority is given to `equal width of + output columns' (a POSIX specification). The TAB-width is fixed + to the value of the first column and does not change with + different values of left MARGIN. That means a fixed number of + spaces is always printed in the place of the NUMBER-SEPARATOR TAB. + The tabification depends upon the output position. + +`-N LINE_NUMBER' +`--first-line-number=LINE_NUMBER' + Start line counting with the number LINE_NUMBER at first line of + first page printed (in most cases not the first line of the input + file). + +`-o MARGIN' +`--indent=MARGIN' + Indent each line with a margin MARGIN spaces wide (default is + zero). The total page width is the size of the margin plus the + PAGE_WIDTH set with the `-W/-w' option. A limited overflow may + occur with numbered single column output (compare `-n' option). + +`-r' +`--no-file-warnings' + Do not print a warning message when an argument FILE cannot be + opened. (The exit status will still be nonzero, however.) + +`-s[CHAR]' +`--separator[=CHAR]' + Separate columns by a single character CHAR. The default for CHAR + is the TAB character without `-w' and `no character' with `-w'. + Without `-s' the default separator `space' is set. `-s[char]' + turns off line truncation of all three column options + (`-COLUMN'|`-a -COLUMN'|`-m') unless `-w' is set. This is a + POSIX-compliant formulation. + +`-SSTRING' +`--sep-string[=STRING]' + Use STRING to separate output columns. The `-S' option doesn't + affect the `-W/-w' option, unlike the `-s' option which does. It + does not affect line truncation or column alignment. Without + `-S', and with `-J', `pr' uses the default output separator, TAB. + Without `-S' or `-J', `pr' uses a `space' (same as `-S" "'). + `--sep-string' with no `=STRING' is equivalent to + `--sep-string=""'. + +`-t' +`--omit-header' + Do not print the usual header [and footer] on each page, and do + not fill out the bottom of pages (with blank lines or a form + feed). No page structure is produced, but form feeds set in the + input files are retained. The predefined pagination is not + changed. `-t' or `-T' may be useful together with other options; + e.g.: `-t -e4', expand TAB characters in the input file to 4 + spaces but don't make any other changes. Use of `-t' overrides + `-h'. + +`-T' +`--omit-pagination' + Do not print header [and footer]. In addition eliminate all form + feeds set in the input files. + +`-v' +`--show-nonprinting' + Print nonprinting characters in octal backslash notation. + +`-w PAGE_WIDTH' +`--width=PAGE_WIDTH' + Set page width to PAGE_WIDTH characters for multiple text-column + output only (default for PAGE_WIDTH is 72). `-s[CHAR]' turns off + the default page width and any line truncation and column + alignment. Lines of full length are merged, regardless of the + column options set. No PAGE_WIDTH setting is possible with single + column output. A POSIX-compliant formulation. + +`-W PAGE_WIDTH' +`--page_width=PAGE_WIDTH' + Set the page width to PAGE_WIDTH characters. That's valid with and + without a column option. Text lines are truncated, unless `-J' is + used. Together with one of the three column options (`-COLUMN', + `-a -COLUMN' or `-m') column alignment is always used. The + separator options `-S' or `-s' don't affect the `-W' option. + Default is 72 characters. Without `-W PAGE_WIDTH' and without any + of the column options NO line truncation is used (defined to keep + downward compatibility and to meet most frequent tasks). That's + equivalent to `-W 72 -J'. The header line is never truncated. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: fold invocation, Prev: pr invocation, Up: Formatting file contents + +4.3 `fold': Wrap input lines to fit in specified width +====================================================== + +`fold' writes each FILE (`-' means standard input), or standard input +if none are given, to standard output, breaking long lines. Synopsis: + + fold [OPTION]... [FILE]... + + By default, `fold' breaks lines wider than 80 columns. The output +is split into as many lines as necessary. + + `fold' counts screen columns by default; thus, a tab may count more +than one column, backspace decreases the column count, and carriage +return sets the column to zero. + + The program accepts the following options. Also see *Note Common +options::. + +`-b' +`--bytes' + Count bytes rather than columns, so that tabs, backspaces, and + carriage returns are each counted as taking up one column, just + like other characters. + +`-s' +`--spaces' + Break at word boundaries: the line is broken after the last blank + before the maximum line length. If the line contains no such + blanks, the line is broken at the maximum line length as usual. + +`-w WIDTH' +`--width=WIDTH' + Use a maximum line length of WIDTH columns instead of 80. + + For compatibility `fold' supports an obsolete option syntax + `-WIDTH'. New scripts should use `-w WIDTH' instead. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Output of parts of files, Next: Summarizing files, Prev: Formatting file contents, Up: Top + +5 Output of parts of files +************************** + +These commands output pieces of the input. + +* 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. +* csplit invocation:: Split a file into context-determined pieces. + + +File: coreutils.info, Node: head invocation, Next: tail invocation, Up: Output of parts of files + +5.1 `head': Output the first part of files +========================================== + +`head' prints the first part (10 lines by default) of each FILE; it +reads from standard input if no files are given or when given a FILE of +`-'. Synopsis: + + head [OPTION]... [FILE]... + + If more than one FILE is specified, `head' prints a one-line header +consisting of: + + ==> FILE NAME <== + +before the output for each FILE. + + The program accepts the following options. Also see *Note Common +options::. + +`-c N' +`--bytes=N' + Print the first N bytes, instead of initial lines. Appending `b' + multiplies N by 512, `k' by 1024, and `m' by 1048576. However, if + N starts with a `-', print all but the last N bytes of each file. + +`-n N' +`--lines=N' + Output the first N lines. However, if N starts with a `-', print + all but the last N lines of each file. + +`-q' +`--quiet' +`--silent' + Never print file name headers. + +`-v' +`--verbose' + Always print file name headers. + + + For compatibility `head' also supports an obsolete option syntax +`-COUNTOPTIONS', which is recognized only if it is specified first. +COUNT is a decimal number optionally followed by a size letter (`b', +`k', `m') as in `-c', or `l' to mean count by lines, or other option +letters (`cqv'). Scripts intended for standard hosts should use `-c +COUNT' or `-n COUNT' instead. If your script must also run on hosts +that support only the obsolete syntax, it is usually simpler to avoid +`head', e.g., by using `sed 5q' instead of `head -5'. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: tail invocation, Next: split invocation, Prev: head invocation, Up: Output of parts of files + +5.2 `tail': Output the last part of files +========================================= + +`tail' prints the last part (10 lines by default) of each FILE; it +reads from standard input if no files are given or when given a FILE of +`-'. Synopsis: + + tail [OPTION]... [FILE]... + + If more than one FILE is specified, `tail' prints a one-line header +consisting of: + + ==> FILE NAME <== + +before the output for each FILE. + + GNU `tail' can output any amount of data (some other versions of +`tail' cannot). It also has no `-r' option (print in reverse), since +reversing a file is really a different job from printing the end of a +file; BSD `tail' (which is the one with `-r') can only reverse files +that are at most as large as its buffer, which is typically 32 KiB. A +more reliable and versatile way to reverse files is the GNU `tac' +command. + + If any option-argument is a number N starting with a `+', `tail' +begins printing with the Nth item from the start of each file, instead +of from the end. + + The program accepts the following options. Also see *Note Common +options::. + +`-c BYTES' +`--bytes=BYTES' + Output the last BYTES bytes, instead of final lines. Appending + `b' multiplies BYTES by 512, `k' by 1024, and `m' by 1048576. + +`-f' +`--follow[=HOW]' + Loop forever trying to read more characters at the end of the file, + presumably because the file is growing. If more than one file is + given, `tail' prints a header whenever it gets output from a + different file, to indicate which file that output is from. + + There are two ways to specify how you'd like to track files with + this option, but that difference is noticeable only when a + followed file is removed or renamed. If you'd like to continue to + track the end of a growing file even after it has been unlinked, + use `--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 + `--follow=name' to track the named file by reopening it + periodically to see if it has been removed and recreated by some + other program. + + No matter which method you use, if the tracked file is determined + to have shrunk, `tail' prints a message saying the file has been + truncated and resumes tracking the end of the file from the + newly-determined endpoint. + + When a file is removed, `tail''s behavior depends on whether it is + following the name or the descriptor. When following by name, + tail can detect that a file has been removed and gives a message + to that effect, and if `--retry' has been specified it will + continue checking periodically to see if the file reappears. When + following a descriptor, tail does not detect that the file has + been unlinked or renamed and issues no message; even though the + file may no longer be accessible via its original name, it may + still be growing. + + The option values `descriptor' and `name' may be specified only + with the long form of the option, not with `-f'. + + If `POSIXLY_CORRECT' is set, the `-f' option is ignored if no FILE + operand is specified and standard input is a FIFO or a pipe. + +`-F' + This option is the same as `--follow=name --retry'. That is, tail + will attempt to reopen a file when it is removed. Should this + fail, tail will keep trying until it becomes accessible again. + +`--retry' + This option is useful mainly when following by name (i.e., with + `--follow=name'). Without this option, when tail encounters a + file that doesn't exist or is otherwise inaccessible, it reports + that fact and never checks it again. + +`--sleep-interval=NUMBER' + Change the number of seconds to wait between iterations (the + default is 1.0). During one iteration, every specified file is + checked to see if it has changed size. Historical implementations + of `tail' have required that NUMBER be an integer. However, GNU + `tail' accepts an arbitrary floating point number (using a period + before any fractional digits). + +`--pid=PID' + When following by name or by descriptor, you may specify the + process ID, PID, of the sole writer of all FILE arguments. Then, + shortly after that process terminates, tail will also terminate. + This will work properly only if the writer and the tailing process + are running on the same machine. For example, to save the output + of a build in a file and to watch the file grow, if you invoke + `make' and `tail' like this then the tail process will stop when + your build completes. Without this option, you would have had to + kill the `tail -f' process yourself. + + $ make >& makerr & tail --pid=$! -f makerr + + If you specify a PID that is not in use or that does not correspond + to the process that is writing to the tailed files, then `tail' + may terminate long before any FILEs stop growing or it may not + terminate until long after the real writer has terminated. Note + that `--pid' cannot be supported on some systems; `tail' will + print a warning if this is the case. + +`--max-unchanged-stats=N' + When tailing a file by name, if there have been N (default + n=5) consecutive iterations for which the file has not changed, + then `open'/`fstat' the file to determine if that file name is + still associated with the same device/inode-number pair as before. + 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. + +`-n N' +`--lines=N' + Output the last N lines. + +`-q' +`--quiet' +`--silent' + Never print file name headers. + +`-v' +`--verbose' + Always print file name headers. + + + For compatibility `tail' also supports an obsolete usage `tail +-[COUNT][bcl][f] [FILE]', which is recognized only if it does not +conflict with the usage described above. This obsolete form uses +exactly one option and at most one file. In the option, COUNT is an +optional decimal number optionally followed by a size letter (`b', `c', +`l') to mean count by 512-byte blocks, bytes, or lines, optionally +followed by `f' which has the same meaning as `-f'. + + On older systems, the leading `-' can be replaced by `+' in the +obsolete option syntax with the same meaning as in counts, and obsolete +usage overrides normal usage when the two conflict. This obsolete +behavior can be enabled or disabled with the `_POSIX2_VERSION' +environment variable (*note Standards conformance::). + + Scripts intended for use on standard hosts should avoid obsolete +syntax and should use `-c COUNT[b]', `-n COUNT', and/or `-f' instead. +If your script must also run on hosts that support only the obsolete +syntax, you can often rewrite it to avoid problematic usages, e.g., by +using `sed -n '$p'' rather than `tail -1'. If that's not possible, the +script can use a test like `if tail -c +1 </dev/null >/dev/null 2>&1; +then ...' to decide which syntax to use. + + Even if your script assumes the standard behavior, you should still +beware usages whose behaviors differ depending on the POSIX version. +For example, avoid `tail - main.c', since it might be interpreted as +either `tail main.c' or as `tail -- - main.c'; avoid `tail -c 4', since +it might mean either `tail -c4' or `tail -c 10 4'; and avoid `tail +4', +since it might mean either `tail ./+4' or `tail -n +4'. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: split invocation, Next: csplit invocation, Prev: tail invocation, Up: Output of parts of files + +5.3 `split': Split a file into fixed-size pieces +================================================ + +`split' creates output files containing consecutive sections of INPUT +(standard input if none is given or INPUT is `-'). Synopsis: + + split [OPTION] [INPUT [PREFIX]] + + By default, `split' puts 1000 lines of INPUT (or whatever is left +over for the last section), into each output file. + + The output files' names consist of PREFIX (`x' by default) followed +by a group of characters (`aa', `ab', ... 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, `split' reports an error without deleting the output files +that it did create. + + The program accepts the following options. Also see *Note Common +options::. + +`-a LENGTH' +`--suffix-length=LENGTH' + Use suffixes of length LENGTH. The default LENGTH is 2. + +`-l LINES' +`--lines=LINES' + Put LINES lines of INPUT into each output file. + + For compatibility `split' also supports an obsolete option syntax + `-LINES'. New scripts should use `-l LINES' instead. + +`-b BYTES' +`--bytes=BYTES' + Put the first BYTES bytes of INPUT into each output file. + Appending `b' multiplies BYTES by 512, `k' by 1024, and `m' by + 1048576. + +`-C BYTES' +`--line-bytes=BYTES' + Put into each output file as many complete lines of INPUT as + possible without exceeding BYTES bytes. For lines longer than + BYTES bytes, put BYTES bytes into each output file until less than + BYTES bytes of the line are left, then continue normally. BYTES + has the same format as for the `--bytes' option. + +`-d' +`--numeric-suffixes' + Use digits in suffixes rather than lower-case letters. + +`--verbose' + Write a diagnostic to standard error just before each output file + is opened. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: csplit invocation, Prev: split invocation, Up: Output of parts of files + +5.4 `csplit': Split a file into context-determined pieces +========================================================= + +`csplit' creates zero or more output files containing sections of INPUT +(standard input if INPUT is `-'). Synopsis: + + csplit [OPTION]... INPUT PATTERN... + + The contents of the output files are determined by the PATTERN +arguments, as detailed below. An error occurs if a PATTERN argument +refers to a nonexistent line of the input file (e.g., if no remaining +line matches a given regular expression). After every PATTERN has been +matched, any remaining input is copied into one last output file. + + By default, `csplit' prints the number of bytes written to each +output file after it has been created. + + The types of pattern arguments are: + +`N' + Create an output file containing the input up to but not including + line N (a positive integer). If followed by a repeat count, also + create an output file containing the next N lines of the input + file once for each repeat. + +`/REGEXP/[OFFSET]' + Create an output file containing the current line up to (but not + including) the next line of the input file that contains a match + for REGEXP. The optional OFFSET is an integer. If it is given, + the input up to (but not including) the matching line plus or + minus OFFSET is put into the output file, and the line after that + begins the next section of input. + +`%REGEXP%[OFFSET]' + Like the previous type, except that it does not create an output + file, so that section of the input file is effectively ignored. + +`{REPEAT-COUNT}' + Repeat the previous pattern REPEAT-COUNT additional times. The + REPEAT-COUNT can either be a positive integer or an asterisk, + meaning repeat as many times as necessary until the input is + exhausted. + + + The output files' names consist of a prefix (`xx' by default) +followed by a suffix. By default, the suffix is an ascending sequence +of two-digit decimal numbers from `00' to `99'. In any case, +concatenating the output files in sorted order by file name produces the +original input file. + + By default, if `csplit' encounters an error or receives a hangup, +interrupt, quit, or terminate signal, it removes any output files that +it has created so far before it exits. + + The program accepts the following options. Also see *Note Common +options::. + +`-f PREFIX' +`--prefix=PREFIX' + Use PREFIX as the output file name prefix. + +`-b SUFFIX' +`--suffix=SUFFIX' + Use SUFFIX as the output file name suffix. When this option is + specified, the suffix string must include exactly one + `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 `d', `i', `u', `o', `x', and `X' conversions are + allowed. The entire SUFFIX is given (with the current output file + number) to `sprintf(3)' to form the file name suffixes for each of + the individual output files in turn. If this option is used, the + `--digits' option is ignored. + +`-n DIGITS' +`--digits=DIGITS' + Use output file names containing numbers that are DIGITS digits + long instead of the default 2. + +`-k' +`--keep-files' + Do not remove output files when errors are encountered. + +`-z' +`--elide-empty-files' + Suppress the generation of zero-length output files. (In cases + where the section delimiters of the input file are supposed to + mark the first lines of each of the sections, the first output + file will generally be a zero-length file unless you use this + option.) The output file sequence numbers always run + consecutively starting from 0, even when this option is specified. + +`-s' +`-q' +`--silent' +`--quiet' + Do not print counts of output file sizes. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Summarizing files, Next: Operating on sorted files, Prev: Output of parts of files, Up: Top + +6 Summarizing files +******************* + +These commands generate just a few numbers representing entire contents +of files. + +* Menu: + +* 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. + + +File: coreutils.info, Node: wc invocation, Next: sum invocation, Up: Summarizing files + +6.1 `wc': Print newline, word, and byte counts +============================================== + +`wc' counts the number of bytes, characters, whitespace-separated +words, and newlines in each given FILE, or standard input if none are +given or for a FILE of `-'. Synopsis: + + wc [OPTION]... [FILE]... + + `wc' prints one line of counts for each file, and if the file was +given as an argument, it prints the file name following the counts. If +more than one FILE is given, `wc' prints a final line containing the +cumulative counts, with the file name `total'. The counts are printed +in this order: newlines, words, characters, bytes, maximum line length. +Each count is printed right-justified in a field with at least one +space between fields so that the numbers and file names normally line +up nicely in columns. The width of the count fields varies depending +on the inputs, so you should not depend on a particular field width. +However, as a GNU extension, if only one count is printed, it is +guaranteed to be printed without leading spaces. + + By default, `wc' prints three counts: the newline, words, and byte +counts. Options can specify that only certain counts be printed. +Options do not undo others previously given, so + + wc --bytes --words + +prints both the byte counts and the word counts. + + With the `--max-line-length' option, `wc' prints the length of the +longest line per file, and if there is more than one file it prints the +maximum (not the sum) of those lengths. + + The program accepts the following options. Also see *Note Common +options::. + +`-c' +`--bytes' + Print only the byte counts. + +`-m' +`--chars' + Print only the character counts. + +`-w' +`--words' + Print only the word counts. + +`-l' +`--lines' + Print only the newline counts. + +`-L' +`--max-line-length' + Print only the maximum line lengths. + +`--files0-from=FILE' + Rather than processing files named on the command line, process + those named in file FILE; each name is terminated by a null byte. + This is useful when the list of file names is so long that it may + exceed a command line length limitation. In such cases, running + `wc' via `xargs' is undesirable because it splits the list into + pieces and makes `wc' print a total for each sublist rather than + for the entire list. One way to produce a list of + null-byte-terminated file names is with GNU `find', using its + `-print0' predicate. For example, to find the length of the + longest line in any `.c' or `.h' file in the current hierarchy, do + this: + + find . -name '*.[ch]' -print0 | wc -L --files0-from=- | tail -n1 + + Do not specify any FILE on the command line when using this option. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: sum invocation, Next: cksum invocation, Prev: wc invocation, Up: Summarizing files + +6.2 `sum': Print checksum and block counts +========================================== + +`sum' computes a 16-bit checksum for each given FILE, or standard input +if none are given or for a FILE of `-'. Synopsis: + + sum [OPTION]... [FILE]... + + `sum' prints the checksum for each FILE followed by the number of +blocks in the file (rounded up). If more than one FILE is given, file +names are also printed (by default). (With the `--sysv' option, +corresponding file names are printed when there is at least one file +argument.) + + By default, GNU `sum' computes checksums using an algorithm +compatible with BSD `sum' and prints file sizes in units of 1024-byte +blocks. + + The program accepts the following options. Also see *Note Common +options::. + +`-r' + Use the default (BSD compatible) algorithm. This option is + included for compatibility with the System V `sum'. Unless `-s' + was also given, it has no effect. + +`-s' +`--sysv' + Compute checksums using an algorithm compatible with System V + `sum''s default, and print file sizes in units of 512-byte blocks. + + + `sum' is provided for compatibility; the `cksum' program (see next +section) is preferable in new applications. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: cksum invocation, Next: md5sum invocation, Prev: sum invocation, Up: Summarizing files + +6.3 `cksum': Print CRC checksum and byte counts +=============================================== + +`cksum' computes a cyclic redundancy check (CRC) checksum for each +given FILE, or standard input if none are given or for a FILE of `-'. +Synopsis: + + cksum [OPTION]... [FILE]... + + `cksum' prints the CRC checksum for each file along with the number +of bytes in the file, and the file name unless no arguments were given. + + `cksum' is typically used to ensure that files transferred by +unreliable means (e.g., netnews) have not been corrupted, by comparing +the `cksum' output for the received files with the `cksum' output for +the original files (typically given in the distribution). + + The CRC algorithm is specified by the POSIX standard. It is not +compatible with the BSD or System V `sum' algorithms (see the previous +section); it is more robust. + + The only options are `--help' and `--version'. *Note Common +options::. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: md5sum invocation, Next: sha1sum invocation, Prev: cksum invocation, Up: Summarizing files + +6.4 `md5sum': Print or check MD5 digests +======================================== + +`md5sum' computes a 128-bit checksum (or "fingerprint" or +"message-digest") for each specified FILE. + + Note: The MD5 digest is more reliable than a simple CRC (provided by +the `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. *Note sha1sum invocation::, and *Note sha2 utilities::. + + If a FILE is specified as `-' or if no files are given `md5sum' +computes the checksum for the standard input. `md5sum' can also +determine whether a file and checksum are consistent. Synopsis: + + md5sum [OPTION]... [FILE]... + + For each FILE, `md5sum' outputs the MD5 checksum, a flag indicating +a binary or text input file, and the file name. If FILE contains a +backslash or newline, the line is started with a backslash, and each +problematic character in the file name is escaped with a backslash, +making the output unambiguous even in the presence of arbitrary file +names. If FILE is omitted or specified as `-', standard input is read. + + The program accepts the following options. Also see *Note Common +options::. + +`-b' +`--binary' + Treat each input file as binary, by reading it in binary mode and + outputting a `*' flag. This is the inverse of `--text'. On + systems like GNU that do not distinguish between binary and text + files, this option merely flags each input file as binary: the MD5 + checksum is unaffected. This option is the default on systems + like MS-DOS that distinguish between binary and text files, except + for reading standard input when standard input is a terminal. + +`-c' +`--check' + Read file names and checksum information (not data) from each FILE + (or from stdin if no FILE was specified) and report whether the + checksums match the contents of the named files. The input to + this mode of `md5sum' is usually the output of a prior, + checksum-generating run of `md5sum'. Each valid line of input + consists of an MD5 checksum, a binary/text flag, and then a file + name. Binary files are marked with `*', text with ` '. For each + such line, `md5sum' reads the named file and computes its MD5 + checksum. Then, if the computed message digest does not match the + one on the line with the file name, the file is noted as having + failed the test. Otherwise, the file passes the test. By + default, for each valid line, one line is written to standard + output indicating whether the named file passed the test. After + all checks have been performed, if there were any failures, a + warning is issued to standard error. Use the `--status' option to + inhibit that output. If any listed file cannot be opened or read, + if any valid line has an MD5 checksum inconsistent with the + associated file, or if no valid line is found, `md5sum' exits with + nonzero status. Otherwise, it exits successfully. + +`--status' + This option is useful only when verifying checksums. When + verifying checksums, don't generate the default one-line-per-file + diagnostic and don't output the warning summarizing any failures. + Failures to open or read a file still evoke individual diagnostics + to standard error. If all listed files are readable and are + consistent with the associated MD5 checksums, exit successfully. + Otherwise exit with a status code indicating there was a failure. + +`-t' +`--text' + Treat each input file as text, by reading it in text mode and + outputting a ` ' flag. This is the inverse of `--binary'. This + option is the default on systems like GNU that do not distinguish + between binary and text files. On other systems, it is the + default for reading standard input when standard input is a + terminal. + +`-w' +`--warn' + When verifying checksums, warn about improperly formatted MD5 + checksum lines. This option is useful only if all but a few lines + in the checked input are valid. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: sha1sum invocation, Next: sha2 utilities, Prev: md5sum invocation, Up: Summarizing files + +6.5 `sha1sum': Print or check SHA-1 digests +=========================================== + +`sha1sum' computes a 160-bit checksum for each specified FILE. The +usage and options of this command are precisely the same as for +`md5sum'. *Note md5sum invocation::. + + Note: The SHA-1 digest is more secure than MD5, and no collisions of +it are known (different files having the same fingerprint). However, +it is known that they can be produced with considerable, but not +unreasonable, resources. For this reason, it is generally considered +that SHA-1 should be gradually phased out in favor of the more secure +SHA-2 hash algorithms. *Note sha2 utilities::. + + +File: coreutils.info, Node: sha2 utilities, Prev: sha1sum invocation, Up: Summarizing files + +6.6 sha2 utilities: Print or check SHA-2 digests +================================================ + +The commands `sha224sum', `sha256sum', `sha384sum' and `sha512sum' +compute checksums of various lengths (respectively 224, 256, 384 and +512 bits), collectively known as the SHA-2 hashes. The usage and +options of these commands are precisely the same as for `md5sum'. +*Note md5sum invocation::. + + Note: The SHA384 and SHA512 digests are considerably slower to +compute, especially on 32-bit computers, than SHA224 or SHA256. + + +File: coreutils.info, Node: Operating on sorted files, Next: Operating on fields within a line, Prev: Summarizing files, Up: Top + +7 Operating on sorted files +*************************** + +These commands work with (or produce) sorted files. + +* Menu: + +* 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. +* tsort background:: Where tsort came from. + + +File: coreutils.info, Node: sort invocation, Next: shuf invocation, Up: Operating on sorted files + +7.1 `sort': Sort text files +=========================== + +`sort' sorts, merges, or compares all the lines from the given files, +or standard input if none are given or for a FILE of `-'. By default, +`sort' writes the results to standard output. Synopsis: + + sort [OPTION]... [FILE]... + + `sort' has three modes of operation: sort (the default), merge, and +check for sortedness. The following options change the operation mode: + +`-c' +`--check' +`--check=diagnose-first' + Check whether the given file is already sorted: if it is not all + sorted, print a diagnostic containing the first out-of-order line + and exit with a status of 1. Otherwise, exit successfully. At + most one input file can be given. + +`-C' +`--check=quiet' +`--check=silent' + Exit successfully if the given file is already sorted, and exit + with status 1 otherwise. At most one input file can be given. + This is like `-c', except it does not print a diagnostic. + +`-m' +`--merge' + Merge the given files by sorting them as a group. Each input file + must always be individually sorted. It always works to sort + instead of merge; merging is provided because it is faster, in the + case where it works. + + + A pair of lines is compared as follows: `sort' compares each pair of +fields, in the order specified on the command line, according to the +associated ordering options, until a difference is found or no fields +are left. If no key fields are specified, `sort' uses a default key of +the entire line. Finally, as a last resort when all keys compare +equal, `sort' compares entire lines as if no ordering options other +than `--reverse' (`-r') were specified. The `--stable' (`-s') option +disables this "last-resort comparison" so that lines in which all +fields compare equal are left in their original relative order. The +`--unique' (`-u') option also disables the last-resort comparison. + + Unless otherwise specified, all comparisons use the character +collating sequence specified by the `LC_COLLATE' locale.(1) + + GNU `sort' (as specified for all GNU utilities) has no limit on +input line length or restrictions on bytes allowed within lines. In +addition, if the final byte of an input file is not a newline, GNU +`sort' silently supplies one. A line's trailing newline is not part of +the line for comparison purposes. + + Exit status: + + 0 if no error occurred + 1 if invoked with `-c' or `-C' and the input is not sorted + 2 if an error occurred + + If the environment variable `TMPDIR' is set, `sort' uses its value +as the directory for temporary files instead of `/tmp'. The +`--temporary-directory' (`-T') option in turn overrides the environment +variable. + + The following options affect the ordering of output lines. They may +be specified globally or as part of a specific key field. If no key +fields are specified, global options apply to comparison of entire +lines; otherwise the global options are inherited by key fields that do +not specify any special options of their own. In pre-POSIX versions of +`sort', global options affect only later key fields, so portable shell +scripts should specify global options first. + +`-b' +`--ignore-leading-blanks' + Ignore leading blanks when finding sort keys in each line. By + default a blank is a space or a tab, but the `LC_CTYPE' locale can + change this. + +`-d' +`--dictionary-order' + Sort in "phone directory" order: ignore all characters except + letters, digits and blanks when sorting. By default letters and + digits are those of ASCII and a blank is a space or a tab, but the + `LC_CTYPE' locale can change this. + +`-f' +`--ignore-case' + Fold lowercase characters into the equivalent uppercase characters + when comparing so that, for example, `b' and `B' sort as equal. + The `LC_CTYPE' locale determines character types. + +`-g' +`--general-numeric-sort' + Sort numerically, using the standard C function `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 `1.0e-34' and `10e100'. The `LC_NUMERIC' locale + determines the decimal-point character. Do not report overflow, + underflow, or conversion errors. Use the following collating + sequence: + + * Lines that do not start with numbers (all considered to be + equal). + + * NaNs ("Not a Number" values, in IEEE floating point + arithmetic) in a consistent but machine-dependent order. + + * Minus infinity. + + * Finite numbers in ascending numeric order (with -0 and +0 + equal). + + * Plus infinity. + + Use this option only if there is no alternative; it is much slower + than `--numeric-sort' (`-n') and it can lose information when + converting to floating point. + +`-i' +`--ignore-nonprinting' + Ignore nonprinting characters. The `LC_CTYPE' locale determines + character types. This option has no effect if the stronger + `--dictionary-order' (`-d') option is also given. + +`-M' +`--month-sort' + An initial string, consisting of any amount of blanks, followed by + a month name abbreviation, is folded to UPPER case and compared in + the order `JAN' < `FEB' < ... < `DEC'. Invalid names compare low + to valid names. The `LC_TIME' locale category determines the + month spellings. By default a blank is a space or a tab, but the + `LC_CTYPE' locale can change this. + +`-n' +`--numeric-sort' + Sort numerically. The number begins each line and consists of + optional blanks, an optional `-' sign, and zero or more digits + possibly separated by thousands separators, optionally followed by + a decimal-point character and zero or more digits. An empty + number is treated as `0'. The `LC_NUMERIC' locale specifies the + decimal-point character and thousands separator. By default a + blank is a space or a tab, but the `LC_CTYPE' locale can change + this. + + Comparison is exact; there is no rounding error. + + Neither a leading `+' nor exponential notation is recognized. To + compare such strings numerically, use the `--general-numeric-sort' + (`-g') option. + +`-r' +`--reverse' + Reverse the result of comparison, so that lines with greater key + values appear earlier in the output instead of later. + +`-R' +`--random-sort' + Sort by hashing the input keys and then sorting the hash values. + Choose the hash function at random, ensuring that it is free of + collisions so that differing keys have differing hash values. + This is like a random permutation of the inputs (*note shuf + invocation::), except that keys with the same value sort together. + + If multiple random sort fields are specified, the same random hash + function is used for all fields. To use different random hash + functions for different fields, you can invoke `sort' more than + once. + + The choice of hash function is affected by the `--random-source' + option. + + + Other options are: + +`--compress-program=PROG' + Compress any temporary files with the program PROG. + + With no arguments, PROG must compress standard input to standard + output, and when given the `-d' option it must decompress standard + input to standard output. + + Terminate with an error if PROG exits with nonzero status. + + Whitespace and the backslash character should not appear in PROG; + they are reserved for future use. + +`-k POS1[,POS2]' +`--key=POS1[,POS2]' + Specify a sort field that consists of the part of the line between + POS1 and POS2 (or the end of the line, if POS2 is omitted), + _inclusive_. + + Each POS has the form `F[.C][OPTS]', where F is the number of the + field to use, and C is the number of the first character from the + beginning of the field. Fields and character positions are + numbered starting with 1; a character position of zero in POS2 + indicates the field's last character. If `.C' is omitted from + POS1, it defaults to 1 (the beginning of the field); if omitted + from POS2, it defaults to 0 (the end of the field). OPTS are + ordering options, allowing individual keys to be sorted according + to different rules; see below for details. Keys can span multiple + fields. + + Example: To sort on the second field, use `--key=2,2' (`-k 2,2'). + See below for more examples. + +`-o OUTPUT-FILE' +`--output=OUTPUT-FILE' + Write output to OUTPUT-FILE instead of standard output. Normally, + `sort' reads all input before opening OUTPUT-FILE, so you can + safely sort a file in place by using commands like `sort -o F F' + and `cat F | sort -o F'. However, `sort' with `--merge' (`-m') + can open the output file before reading all input, so a command + like `cat F | sort -m -o F - G' is not safe as `sort' might start + writing `F' before `cat' is done reading it. + + On newer systems, `-o' cannot appear after an input file if + `POSIXLY_CORRECT' is set, e.g., `sort F -o F'. Portable scripts + should specify `-o OUTPUT-FILE' before any input files. + +`--random-source=FILE' + Use FILE as a source of random data used to determine which random + hash function to use with the `-R' option. *Note Random sources::. + +`-s' +`--stable' + Make `sort' stable by disabling its last-resort comparison. This + option has no effect if no fields or global ordering options other + than `--reverse' (`-r') are specified. + +`-S SIZE' +`--buffer-size=SIZE' + Use a main-memory sort buffer of the given SIZE. By default, SIZE + is in units of 1024 bytes. Appending `%' causes SIZE to be + interpreted as a percentage of physical memory. Appending `K' + multiplies SIZE by 1024 (the default), `M' by 1,048,576, `G' by + 1,073,741,824, and so on for `T', `P', `E', `Z', and `Y'. + Appending `b' causes SIZE to be interpreted as a byte count, with + no multiplication. + + This option can improve the performance of `sort' by causing it to + start with a larger or smaller sort buffer than the default. + However, this option affects only the initial buffer size. The + buffer grows beyond SIZE if `sort' encounters input lines larger + than SIZE. + +`-t SEPARATOR' +`--field-separator=SEPARATOR' + Use character SEPARATOR as the field separator when finding the + sort keys in each line. By default, fields are separated by the + empty string between a non-blank character and a blank character. + By default a blank is a space or a tab, but the `LC_CTYPE' locale + can change this. + + That is, given the input line ` foo bar', `sort' breaks it into + fields ` foo' and ` bar'. The field separator is not considered + to be part of either the field preceding or the field following, + so with `sort -t " "' the same input line has three fields: an + empty field, `foo', and `bar'. However, fields that extend to the + end of the line, as `-k 2', or fields consisting of a range, as + `-k 2,3', retain the field separators present between the + endpoints of the range. + + To specify a null character (ASCII NUL) as the field separator, + use the two-character string `\0', e.g., `sort -t '\0''. + +`-T TEMPDIR' +`--temporary-directory=TEMPDIR' + Use directory TEMPDIR to store temporary files, overriding the + `TMPDIR' environment variable. If this option is given more than + once, temporary files are stored in all the directories given. If + you have a large sort or merge that is I/O-bound, you can often + improve performance by using this option to specify directories on + different disks and controllers. + +`-u' +`--unique' + Normally, output only the first of a sequence of lines that compare + equal. For the `--check' (`-c' or `-C') option, check that no + pair of consecutive lines compares equal. + + This option also disables the default last-resort comparison. + + The commands `sort -u' and `sort | uniq' are equivalent, but this + equivalence does not extend to arbitrary `sort' options. For + example, `sort -n -u' inspects only the value of the initial + numeric string when checking for uniqueness, whereas `sort -n | + uniq' inspects the entire line. *Note uniq invocation::. + +`-z' +`--zero-terminated' + Treat the input as a set of lines, each terminated by a null + character (ASCII NUL) instead of a line feed (ASCII LF). This + option can be useful in conjunction with `perl -0' or `find + -print0' and `xargs -0' which do the same in order to reliably + handle arbitrary file names (even those containing blanks or other + special characters). + + + Historical (BSD and System V) implementations of `sort' have +differed in their interpretation of some options, particularly `-b', +`-f', and `-n'. GNU sort follows the POSIX behavior, which is usually +(but not always!) like the System V behavior. According to POSIX, `-n' +no longer implies `-b'. For consistency, `-M' has been changed in the +same way. This may affect the meaning of character positions in field +specifications in obscure cases. The only fix is to add an explicit +`-b'. + + A position in a sort field specified with `-k' may have any of the +option letters `Mbdfinr' appended to it, in which case the global +ordering options are not used for that particular field. The `-b' +option may be independently attached to either or both of the start and +end positions of a field specification, and if it is inherited from the +global options it will be attached to both. If input lines can contain +leading or adjacent blanks and `-t' is not used, then `-k' is typically +combined with `-b', `-g', `-M', or `-n'; 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 the line or after the end field, the field is empty. If the `-b' +option was specified, the `.C' part of a field specification is counted +from the first nonblank character of the field. + + On older systems, `sort' supports an obsolete origin-zero syntax +`+POS1 [-POS2]' for specifying sort keys. This obsolete behavior can +be enabled or disabled with the `_POSIX2_VERSION' environment variable +(*note Standards conformance::); it can also be enabled when +`POSIXLY_CORRECT' is not set by using the obsolete syntax with `-POS2' +present. + + Scripts intended for use on standard hosts should avoid obsolete +syntax and should use `-k' instead. For example, avoid `sort +2', +since it might be interpreted as either `sort ./+2' or `sort -k 3'. If +your script must also run on hosts that support only the obsolete +syntax, it can use a test like `if sort -k 1 </dev/null >/dev/null +2>&1; then ...' to decide which syntax to use. + + Here are some examples to illustrate various combinations of options. + + * Sort in descending (reverse) numeric order. + + sort -n -r + + * 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 at the start of the first + nonblank character in field three and extending to the end of each + line. + + sort -k 3b + + * Sort numerically on the second field and resolve ties by sorting + alphabetically on the third and fourth characters of field five. + Use `:' as the field delimiter. + + sort -t : -k 2,2n -k 5.3,5.4 + + Note that if you had written `-k 2n' instead of `-k 2,2n' `sort' + would have used all characters beginning in the second field and + extending to the end of the line as the primary _numeric_ key. + For the large majority of applications, treating keys spanning + more than one field as numeric will not do what you expect. + + Also note that the `n' modifier was applied to the field-end + specifier for the first key. It would have been equivalent to + specify `-k 2n,2' or `-k 2n,2n'. All modifiers except `b' apply + to the associated _field_, regardless of whether the modifier + character is attached to the field-start and/or the field-end part + of the key specifier. + + * Sort the password file on the fifth field and ignore any leading + blanks. Sort lines with equal values in field five on the numeric + user ID in field three. Fields are separated by `:'. + + sort -t : -k 5b,5 -k 3,3n /etc/passwd + sort -t : -n -k 5b,5 -k 3,3 /etc/passwd + sort -t : -b -k 5,5 -k 3,3n /etc/passwd + + These three commands have equivalent effect. The first specifies + that the first key's start position ignores leading blanks and the + second key is sorted numerically. The other two commands rely on + global options being inherited by sort keys that lack modifiers. + The inheritance works in this case because `-k 5b,5b' and `-k + 5b,5' are equivalent, as the location of a field-end lacking a `.C' + character position is not affected by whether initial blanks are + skipped. + + * Sort a set of log files, primarily by IPv4 address and secondarily + by time stamp. If two lines' primary and secondary keys are + identical, output the lines in the same order that they were + input. The log files contain lines that look like this: + + 4.150.156.3 - - [01/Apr/2004:06:31:51 +0000] message 1 + 211.24.3.231 - - [24/Apr/2004:20:17:39 +0000] message 2 + + Fields are separated by exactly one space. Sort IPv4 addresses + lexicographically, e.g., 212.61.52.2 sorts before 212.129.233.201 + because 61 is less than 129. + + sort -s -t ' ' -k 4.9n -k 4.5M -k 4.2n -k 4.14,4.21 file*.log | + sort -s -t '.' -k 1,1n -k 2,2n -k 3,3n -k 4,4n + + This example cannot be done with a single `sort' invocation, since + IPv4 address components are separated by `.' while dates come just + after a space. So it is broken down into two invocations of + `sort': the first sorts by time stamp and the second by IPv4 + address. The time stamp is sorted by year, then month, then day, + and finally by hour-minute-second field, using `-k' to isolate each + field. Except for hour-minute-second there's no need to specify + the end of each key field, since the `n' and `M' modifiers sort + based on leading prefixes that cannot cross field boundaries. The + IPv4 addresses are sorted lexicographically. The second sort uses + `-s' so that ties in the primary key are broken by the secondary + key; the first sort uses `-s' so that the combination of the two + sorts is stable. + + * Generate a tags file in case-insensitive sorted order. + + find src -type f -print0 | sort -z -f | xargs -0 etags --append + + The use of `-print0', `-z', and `-0' in this case means that file + names that contain blanks or other special characters are not + broken up by the sort operation. + + * Shuffle a list of directories, but preserve the order of files + within each directory. For instance, one could use this to + generate a music playlist in which albums are shuffled but the + songs of each album are played in order. + + ls */* | sort -t / -k 1,1R -k 2,2 + + + ---------- Footnotes ---------- + + (1) If you use a non-POSIX locale (e.g., by setting `LC_ALL' to +`en_US'), then `sort' may produce output that is sorted differently +than you're accustomed to. In that case, set the `LC_ALL' environment +variable to `C'. Note that setting only `LC_COLLATE' has two problems. +First, it is ineffective if `LC_ALL' is also set. Second, it has +undefined behavior if `LC_CTYPE' (or `LANG', if `LC_CTYPE' is unset) is +set to an incompatible value. For example, you get undefined behavior +if `LC_CTYPE' is `ja_JP.PCK' but `LC_COLLATE' is `en_US.UTF-8'. + + +File: coreutils.info, Node: shuf invocation, Next: uniq invocation, Prev: sort invocation, Up: Operating on sorted files + +7.2 `shuf': Shuffling text +========================== + +`shuf' shuffles its input by outputting a random permutation of its +input lines. Each output permutation is equally likely. Synopses: + + shuf [OPTION]... [FILE] + shuf -e [OPTION]... [ARG]... + shuf -i LO-HI [OPTION]... + + `shuf' has three modes of operation that affect where it obtains its +input lines. By default, it reads lines from standard input. The +following options change the operation mode: + +`-e' +`--echo' + Treat each command-line operand as an input line. + +`-i LO-HI' +`--input-range=LO-HI' + Act as if input came from a file containing the range of unsigned + decimal integers LO...HI, one per line. + + + `shuf''s other options can affect its behavior in all operation +modes: + +`-n LINES' +`--head-lines=LINES' + Output at most LINES lines. By default, all input lines are + output. + +`-o OUTPUT-FILE' +`--output=OUTPUT-FILE' + Write output to OUTPUT-FILE instead of standard output. `shuf' + reads all input before opening OUTPUT-FILE, so you can safely + shuffle a file in place by using commands like `shuf -o F <F' and + `cat F | shuf -o F'. + +`--random-source=FILE' + Use FILE as a source of random data used to determine which + permutation to generate. *Note Random sources::. + +`-z' +`--zero-terminated' + Treat the input and output as a set of lines, each terminated by a + zero byte (ASCII NUL (Null) character) instead of an ASCII LF + (Line Feed). This option can be useful in conjunction with `perl + -0' or `find -print0' and `xargs -0' which do the same in order to + reliably handle arbitrary file names (even those containing blanks + or other special characters). + + + For example: + + shuf <<EOF + A man, + a plan, + a canal: + Panama! + EOF + +might produce the output + + Panama! + A man, + a canal: + a plan, + +Similarly, the command: + + shuf -e clubs hearts diamonds spades + +might output: + + clubs + diamonds + spades + hearts + +and the command `shuf -i 1-4' might output: + + 4 + 2 + 1 + 3 + +These examples all have four input lines, so `shuf' might produce any +of the twenty-four possible permutations of the input. In general, if +there are N input lines, there are N! (i.e., N factorial, or N * (N - +1) * ... * 1) possible output permutations. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: uniq invocation, Next: comm invocation, Prev: shuf invocation, Up: Operating on sorted files + +7.3 `uniq': Uniquify files +========================== + +`uniq' writes the unique lines in the given `input', or standard input +if nothing is given or for an INPUT name of `-'. Synopsis: + + uniq [OPTION]... [INPUT [OUTPUT]] + + By default, `uniq' prints its input lines, except that it discards +all but the first of adjacent repeated lines, so that no output lines +are repeated. Optionally, it can instead discard lines that are not +repeated, or all repeated lines. + + The input need not be sorted, but repeated input lines are detected +only if they are adjacent. If you want to discard non-adjacent +duplicate lines, perhaps you want to use `sort -u'. *Note sort +invocation::. + + Comparisons use the character collating sequence specified by the +`LC_COLLATE' locale category. + + If no OUTPUT file is specified, `uniq' writes to standard output. + + The program accepts the following options. Also see *Note Common +options::. + +`-f N' +`--skip-fields=N' + Skip N fields on each line before checking for uniqueness. Use a + null string for comparison if a line has fewer than N fields. + Fields are sequences of non-space non-tab characters that are + separated from each other by at least one space or tab. + + For compatibility `uniq' supports an obsolete option syntax `-N'. + New scripts should use `-f N' instead. + +`-s N' +`--skip-chars=N' + Skip N characters before checking for uniqueness. Use a null + string for comparison if a line has fewer than N characters. If + you use both the field and character skipping options, fields are + skipped over first. + + On older systems, `uniq' supports an obsolete option syntax `+N'. + This obsolete behavior can be enabled or disabled with the + `_POSIX2_VERSION' environment variable (*note Standards + conformance::), but portable scripts should avoid commands whose + behavior depends on this variable. For example, use `uniq ./+10' + or `uniq -s 10' rather than the ambiguous `uniq +10'. + +`-c' +`--count' + Print the number of times each line occurred along with the line. + +`-i' +`--ignore-case' + Ignore differences in case when comparing lines. + +`-d' +`--repeated' + Discard lines that are not repeated. When used by itself, this + option causes `uniq' to print the first copy of each repeated line, + and nothing else. + +`-D' +`--all-repeated[=DELIMIT-METHOD]' + Do not discard the second and subsequent repeated input lines, but + discard lines that are not repeated. This option is useful mainly + in conjunction with other options e.g., to ignore case or to + compare only selected fields. The optional DELIMIT-METHOD tells + how to delimit groups of repeated lines, and must be one of the + following: + + `none' + Do not delimit groups of repeated lines. This is equivalent + to `--all-repeated' (`-D'). + + `prepend' + Output a newline before each group of repeated lines. + + `separate' + Separate groups of repeated lines with a single newline. + This is the same as using `prepend', except that there is no + newline before the first group, and hence may be better + suited for output direct to users. + + Note that when groups are delimited and the input stream contains + two or more consecutive blank lines, then the output is ambiguous. + To avoid that, filter the input through `tr -s '\n'' to replace + each sequence of consecutive newlines with a single newline. + + This is a GNU extension. + +`-u' +`--unique' + Discard the first repeated line. When used by itself, this option + causes `uniq' to print unique lines, and nothing else. + +`-w N' +`--check-chars=N' + Compare at most N characters on each line (after skipping any + specified fields and characters). By default the entire rest of + the lines are compared. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: comm invocation, Next: ptx invocation, Prev: uniq invocation, Up: Operating on sorted files + +7.4 `comm': Compare two sorted files line by line +================================================= + +`comm' writes to standard output lines that are common, and lines that +are unique, to two input files; a file name of `-' means standard +input. Synopsis: + + comm [OPTION]... FILE1 FILE2 + + Before `comm' can be used, the input files must be sorted using the +collating sequence specified by the `LC_COLLATE' locale. If an input +file ends in a non-newline character, a newline is silently appended. +The `sort' command with no options always outputs a file that is +suitable input to `comm'. + + With no options, `comm' produces three-column output. Column one +contains lines unique to FILE1, column two contains lines unique to +FILE2, and column three contains lines common to both files. Columns +are separated by a single TAB character. + + The options `-1', `-2', and `-3' suppress printing of the +corresponding columns. Also see *Note Common options::. + + Unlike some other comparison utilities, `comm' has an exit status +that does not depend on the result of the comparison. Upon normal +completion `comm' produces an exit code of zero. If there is an error +it exits with nonzero status. + + +File: coreutils.info, Node: tsort invocation, Next: tsort background, Prev: ptx invocation, Up: Operating on sorted files + +7.5 `tsort': Topological sort +============================= + +`tsort' performs a topological sort on the given FILE, or standard +input if no input file is given or for a FILE of `-'. For more details +and some history, see *Note tsort background::. Synopsis: + + tsort [OPTION] [FILE] + + `tsort' reads its input as pairs of strings, separated by blanks, +indicating a partial ordering. The output is a total ordering that +corresponds to the given partial ordering. + + For example + + tsort <<EOF + a b c + d + e f + b c d e + EOF + +will produce the output + + a + b + c + d + e + f + + Consider a more realistic example. You have a large set of +functions all in one file, and they may all be declared static except +one. Currently that one (say `main') is the first function defined in +the file, and the ones it calls directly follow it, followed by those +they call, etc. Let's say that you are determined to take advantage of +prototypes, so you have to choose between declaring all of those +functions (which means duplicating a lot of information from the +definitions) and rearranging the functions so that as many as possible +are defined before they are used. One way to automate the latter +process is to get a list for each function of the functions it calls +directly. Many programs can generate such lists. They describe a call +graph. Consider the following list, in which a given line indicates +that the function on the left calls the one on the right directly. + + main parse_options + main tail_file + main tail_forever + tail_file pretty_name + tail_file write_header + tail_file tail + tail_forever recheck + tail_forever pretty_name + tail_forever write_header + tail_forever dump_remainder + tail tail_lines + tail tail_bytes + tail_lines start_lines + tail_lines dump_remainder + tail_lines file_lines + tail_lines pipe_lines + tail_bytes xlseek + tail_bytes start_bytes + tail_bytes dump_remainder + tail_bytes pipe_bytes + file_lines dump_remainder + recheck pretty_name + + then you can use `tsort' to produce an ordering of those functions +that satisfies your requirement. + + example$ tsort call-graph | tac + dump_remainder + start_lines + file_lines + pipe_lines + xlseek + start_bytes + pipe_bytes + tail_lines + tail_bytes + pretty_name + write_header + tail + recheck + parse_options + tail_file + tail_forever + main + + `tsort' detects any cycles in the input and writes the first cycle +encountered to standard error. + + Note that for a given partial ordering, generally there is no unique +total ordering. In the context of the call graph above, the function +`parse_options' may be placed anywhere in the list as long as it +precedes `main'. + + The only options are `--help' and `--version'. *Note Common +options::. + + +File: coreutils.info, Node: tsort background, Prev: tsort invocation, Up: Operating on sorted files + +7.6 `tsort': Background +======================= + +`tsort' exists because very early versions of the Unix linker processed +an archive file exactly once, and in order. As `ld' read each object +in the archive, it decided whether it was needed in the program based on +whether it defined any symbols which were undefined at that point in +the link. + + This meant that dependencies within the archive had to be handled +specially. For example, `scanf' probably calls `read'. That means +that in a single pass through an archive, it was important for `scanf.o' +to appear before read.o, because otherwise a program which calls +`scanf' but not `read' might end up with an unexpected unresolved +reference to `read'. + + The way to address this problem was to first generate a set of +dependencies of one object file on another. This was done by a shell +script called `lorder'. The GNU tools don't provide a version of +lorder, as far as I know, but you can still find it in BSD +distributions. + + Then you ran `tsort' over the `lorder' output, and you used the +resulting sort to define the order in which you added objects to the +archive. + + This whole procedure has been obsolete since about 1980, because +Unix archives now contain a symbol table (traditionally built by +`ranlib', now generally built by `ar' itself), and the Unix linker uses +the symbol table to effectively make multiple passes over an archive +file. + + Anyhow, that's where tsort came from. To solve an old problem with +the way the linker handled archive files, which has since been solved +in different ways. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: ptx invocation, Next: tsort invocation, Prev: comm invocation, Up: Operating on sorted files + +7.7 `ptx': Produce permuted indexes +=================================== + +`ptx' reads a text file and essentially produces a permuted index, with +each keyword in its context. The calling sketch is either one of: + + ptx [OPTION ...] [FILE ...] + ptx -G [OPTION ...] [INPUT [OUTPUT]] + + The `-G' (or its equivalent: `--traditional') option disables all +GNU extensions and reverts to traditional mode, thus introducing some +limitations and changing several of the program's default option values. +When `-G' is not specified, GNU extensions are always enabled. GNU +extensions to `ptx' are documented wherever appropriate in this +document. For the full list, see *Note Compatibility in ptx::. + + Individual options are explained in the following sections. + + When GNU extensions are enabled, there may be zero, one or several +FILEs after the options. If there is no FILE, the program reads the +standard input. If there is one or several FILEs, they give the name +of input files which are all read in turn, as if all the input files +were concatenated. However, there is a full contextual break between +each file and, when automatic referencing is requested, file names and +line numbers refer to individual text input files. In all cases, the +program outputs the permuted index to the standard output. + + When GNU extensions are _not_ enabled, that is, when the program +operates in traditional mode, there may be zero, one or two parameters +besides the options. If there are no parameters, the program reads the +standard input and outputs the permuted index to the standard output. +If there is only one parameter, it names the text INPUT to be read +instead of the standard input. If two parameters are given, they give +respectively the name of the INPUT file to read and the name of the +OUTPUT file to produce. _Be very careful_ to note that, in this case, +the contents of file given by the second parameter is destroyed. This +behavior is dictated by System V `ptx' compatibility; GNU Standards +normally discourage output parameters not introduced by an option. + + Note that for _any_ file named as the value of an option or as an +input text file, a single dash `-' may be used, in which case standard +input is assumed. However, it would not make sense to use this +convention more than once per program invocation. + +* Menu: + +* 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:: + + +File: coreutils.info, Node: General options in ptx, Next: Charset selection in ptx, Up: ptx invocation + +7.7.1 General options +--------------------- + +`-G' +`--traditional' + As already explained, this option disables all GNU extensions to + `ptx' and switches to traditional mode. + +`--help' + Print a short help on standard output, then exit without further + processing. + +`--version' + Print the program version on standard output, then exit without + further processing. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Charset selection in ptx, Next: Input processing in ptx, Prev: General options in ptx, Up: ptx invocation + +7.7.2 Charset selection +----------------------- + +As it is set up now, the program assumes that the input file is coded +using 8-bit ISO 8859-1 code, also known as Latin-1 character set, +_unless_ it is compiled for MS-DOS, in which case it uses the character +set of the IBM-PC. (GNU `ptx' is not known to work on smaller MS-DOS +machines anymore.) Compared to 7-bit ASCII, the set of characters +which are letters is different; this alters the behavior of regular +expression matching. Thus, the default regular expression for a +keyword allows foreign or diacriticized letters. Keyword sorting, +however, is still crude; it obeys the underlying character set ordering +quite blindly. + +`-f' +`--ignore-case' + Fold lower case letters to upper case for sorting. + + + +File: coreutils.info, Node: Input processing in ptx, Next: Output formatting in ptx, Prev: Charset selection in ptx, Up: ptx invocation + +7.7.3 Word selection and input processing +----------------------------------------- + +`-b FILE' +`--break-file=FILE' + This option provides an alternative (to `-W') method of describing + which characters make up words. It introduces the name of a file + which contains a list of characters which can_not_ be part of one + word; this file is called the "Break file". Any character which + is not part of the Break file is a word constituent. If both + options `-b' and `-W' are specified, then `-W' has precedence and + `-b' is ignored. + + When GNU extensions are enabled, the only way to avoid newline as a + break character is to write all the break characters in the file + with no newline at all, not even at the end of the file. When GNU + extensions are disabled, spaces, tabs and newlines are always + considered as break characters even if not included in the Break + file. + +`-i FILE' +`--ignore-file=FILE' + The file associated with this option contains a list of words + which will never be taken as keywords in concordance output. It + is called the "Ignore file". The file contains exactly one word + in each line; the end of line separation of words is not subject + to the value of the `-S' option. + +`-o FILE' +`--only-file=FILE' + The file associated with this option contains a list of words + which will be retained in concordance output; any word not + mentioned in this file is ignored. The file is called the "Only + file". The file contains exactly one word in each line; the end + of line separation of words is not subject to the value of the + `-S' option. + + There is no default for the Only file. When both an Only file and + an Ignore file are specified, a word is considered a keyword only + if it is listed in the Only file and not in the Ignore file. + +`-r' +`--references' + On each input line, the leading sequence of non-white space + characters will be taken to be a reference that has the purpose of + identifying this input line in the resulting permuted index. For + more information about reference production, see *Note Output + formatting in ptx::. Using this option changes the default value + for option `-S'. + + Using this option, the program does not try very hard to remove + references from contexts in output, but it succeeds in doing so + _when_ the context ends exactly at the newline. If option `-r' is + used with `-S' default value, or when GNU extensions are disabled, + this condition is always met and references are completely + excluded from the output contexts. + +`-S REGEXP' +`--sentence-regexp=REGEXP' + This option selects which regular expression will describe the end + of a line or the end of a sentence. In fact, this regular + expression is not the only distinction between end of lines or end + of sentences, and input line boundaries have no special + significance outside this option. By default, when GNU extensions + are enabled and if `-r' option is not used, end of sentences are + used. In this case, this REGEX is imported from GNU Emacs: + + [.?!][]\"')}]*\\($\\|\t\\| \\)[ \t\n]* + + Whenever GNU extensions are disabled or if `-r' option is used, end + of lines are used; in this case, the default REGEXP is just: + + \n + + Using an empty REGEXP is equivalent to completely disabling end of + line or end of sentence recognition. In this case, the whole file + is considered to be a single big line or sentence. The user might + want to disallow all truncation flag generation as well, through + option `-F ""'. *Note Syntax of Regular Expressions: + (emacs)Regexps. + + When the keywords happen to be near the beginning of the input + line or sentence, this often creates an unused area at the + beginning of the output context line; when the keywords happen to + be near the end of the input line or sentence, this often creates + an unused area at the end of the output context line. The program + tries to fill those unused areas by wrapping around context in + them; the tail of the input line or sentence is used to fill the + unused area on the left of the output line; the head of the input + line or sentence is used to fill the unused area on the right of + the output line. + + As a matter of convenience to the user, many usual backslashed + escape sequences from the C language are recognized and converted + to the corresponding characters by `ptx' itself. + +`-W REGEXP' +`--word-regexp=REGEXP' + This option selects which regular expression will describe each + keyword. By default, if GNU extensions are enabled, a word is a + sequence of letters; the REGEXP used is `\w+'. When GNU + extensions are disabled, a word is by default anything which ends + with a space, a tab or a newline; the REGEXP used is `[^ \t\n]+'. + + An empty REGEXP is equivalent to not using this option. *Note + Syntax of Regular Expressions: (emacs)Regexps. + + As a matter of convenience to the user, many usual backslashed + escape sequences, as found in the C language, are recognized and + converted to the corresponding characters by `ptx' itself. + + + +File: coreutils.info, Node: Output formatting in ptx, Next: Compatibility in ptx, Prev: Input processing in ptx, Up: ptx invocation + +7.7.4 Output formatting +----------------------- + +Output format is mainly controlled by the `-O' and `-T' options +described in the table below. When neither `-O' nor `-T' are selected, +and if GNU extensions are enabled, the program chooses an output format +suitable for a dumb terminal. Each keyword occurrence is output to the +center of one line, surrounded by its left and right contexts. Each +field is properly justified, so the concordance output can be readily +observed. As a special feature, if automatic references are selected +by option `-A' and are output before the left context, that is, if +option `-R' is _not_ selected, then a colon is added after the +reference; this nicely interfaces with GNU Emacs `next-error' +processing. In this default output format, each white space character, +like newline and tab, is merely changed to exactly one space, with no +special attempt to compress consecutive spaces. This might change in +the future. Except for those white space characters, every other +character of the underlying set of 256 characters is transmitted +verbatim. + + Output format is further controlled by the following options. + +`-g NUMBER' +`--gap-size=NUMBER' + Select the size of the minimum white space gap between the fields + on the output line. + +`-w NUMBER' +`--width=NUMBER' + Select the maximum output width of each final line. If references + are used, they are included or excluded from the maximum output + width depending on the value of option `-R'. If this option is not + selected, that is, when references are output before the left + context, the maximum output width takes into account the maximum + length of all references. If this option is selected, that is, + when references are output after the right context, the maximum + output width does not take into account the space taken by + references, nor the gap that precedes them. + +`-A' +`--auto-reference' + Select automatic references. Each input line will have an + automatic reference made up of the file name and the line ordinal, + with a single colon between them. However, the file name will be + empty when standard input is being read. If both `-A' and `-r' + are selected, then the input reference is still read and skipped, + but the automatic reference is used at output time, overriding the + input reference. + +`-R' +`--right-side-refs' + In the default output format, when option `-R' is not used, any + references produced by the effect of options `-r' or `-A' are + placed to the far right of output lines, after the right context. + With default output format, when the `-R' option is specified, + references are rather placed at the beginning of each output line, + before the left context. For any other output format, option `-R' + is ignored, with one exception: with `-R' the width of references + is _not_ taken into account in total output width given by `-w'. + + This option is automatically selected whenever GNU extensions are + disabled. + +`-F STRING' +`--flac-truncation=STRING' + This option will request that any truncation in the output be + reported using the string STRING. Most output fields + theoretically extend towards the beginning or the end of the + current line, or current sentence, as selected with option `-S'. + But there is a maximum allowed output line width, changeable + through option `-w', which is further divided into space for + various output fields. When a field has to be truncated because + it cannot extend beyond the beginning or the end of the current + line to fit in, then a truncation occurs. By default, the string + used is a single slash, as in `-F /'. + + STRING may have more than one character, as in `-F ...'. Also, in + the particular case when STRING is empty (`-F ""'), truncation + flagging is disabled, and no truncation marks are appended in this + case. + + As a matter of convenience to the user, many usual backslashed + escape sequences, as found in the C language, are recognized and + converted to the corresponding characters by `ptx' itself. + +`-M STRING' +`--macro-name=STRING' + Select another STRING to be used instead of `xx', while generating + output suitable for `nroff', `troff' or TeX. + +`-O' +`--format=roff' + Choose an output format suitable for `nroff' or `troff' + processing. Each output line will look like: + + .xx "TAIL" "BEFORE" "KEYWORD_AND_AFTER" "HEAD" "REF" + + so it will be possible to write a `.xx' roff macro to take care of + the output typesetting. This is the default output format when GNU + extensions are disabled. Option `-M' can be used to change `xx' + to another macro name. + + In this output format, each non-graphical character, like newline + and tab, is merely changed to exactly one space, with no special + attempt to compress consecutive spaces. Each quote character: `"' + is doubled so it will be correctly processed by `nroff' or `troff'. + +`-T' +`--format=tex' + Choose an output format suitable for TeX processing. Each output + line will look like: + + \xx {TAIL}{BEFORE}{KEYWORD}{AFTER}{HEAD}{REF} + + so it will be possible to write a `\xx' definition to take care of + the output typesetting. Note that when references are not being + produced, that is, neither option `-A' nor option `-r' is + selected, the last parameter of each `\xx' call is inhibited. + Option `-M' can be used to change `xx' to another macro name. + + In this output format, some special characters, like `$', `%', + `&', `#' and `_' are automatically protected with a backslash. + Curly brackets `{', `}' are protected with a backslash and a pair + of dollar signs (to force mathematical mode). The backslash + itself produces the sequence `\backslash{}'. Circumflex and tilde + diacritical marks produce the sequence `^\{ }' and `~\{ }' + respectively. Other diacriticized characters of the underlying + character set produce an appropriate TeX sequence as far as + possible. The other non-graphical characters, like newline and + tab, and all other characters which are not part of ASCII, are + merely changed to exactly one space, with no special attempt to + compress consecutive spaces. Let me know how to improve this + special character processing for TeX. + + + +File: coreutils.info, Node: Compatibility in ptx, Prev: Output formatting in ptx, Up: ptx invocation + +7.7.5 The GNU extensions to `ptx' +--------------------------------- + +This version of `ptx' contains a few features which do not exist in +System V `ptx'. These extra features are suppressed by using the `-G' +command line option, unless overridden by other command line options. +Some GNU extensions cannot be recovered by overriding, so the simple +rule is to avoid `-G' if you care about GNU extensions. Here are the +differences between this program and System V `ptx'. + + * This program can read many input files at once, it always writes + the resulting concordance on standard output. On the other hand, + System V `ptx' reads only one file and sends the result to + standard output or, if a second FILE parameter is given on the + command, to that FILE. + + Having output parameters not introduced by options is a dangerous + practice which GNU avoids as far as possible. So, for using `ptx' + portably between GNU and System V, you should always use it with a + single input file, and always expect the result on standard + output. You might also want to automatically configure in a `-G' + option to `ptx' calls in products using `ptx', if the configurator + finds that the installed `ptx' accepts `-G'. + + * The only options available in System V `ptx' are options `-b', + `-f', `-g', `-i', `-o', `-r', `-t' and `-w'. All other options + are GNU extensions and are not repeated in this enumeration. + Moreover, some options have a slightly different meaning when GNU + extensions are enabled, as explained below. + + * By default, concordance output is not formatted for `troff' or + `nroff'. It is rather formatted for a dumb terminal. `troff' or + `nroff' output may still be selected through option `-O'. + + * Unless `-R' option is used, the maximum reference width is + subtracted from the total output line width. With GNU extensions + disabled, width of references is not taken into account in the + output line width computations. + + * All 256 bytes, even null bytes, are always read and processed from + input file with no adverse effect, even if GNU extensions are + disabled. However, System V `ptx' does not accept 8-bit + characters, a few control characters are rejected, and the tilde + `~' is also rejected. + + * Input line length is only limited by available memory, even if GNU + extensions are disabled. However, System V `ptx' processes only + the first 200 characters in each line. + + * The break (non-word) characters default to be every character + except all letters of the underlying character set, diacriticized + or not. When GNU extensions are disabled, the break characters + default to space, tab and newline only. + + * The program makes better use of output line width. If GNU + extensions are disabled, the program rather tries to imitate + System V `ptx', but still, there are some slight disposition + glitches this program does not completely reproduce. + + * The user can specify both an Ignore file and an Only file. This + is not allowed with System V `ptx'. + + + +File: coreutils.info, Node: Operating on fields within a line, Next: Operating on characters, Prev: Operating on sorted files, Up: Top + +8 Operating on fields within a line +*********************************** + +* Menu: + +* cut invocation:: Print selected parts of lines. +* paste invocation:: Merge lines of files. +* join invocation:: Join lines on a common field. + + +File: coreutils.info, Node: cut invocation, Next: paste invocation, Up: Operating on fields within a line + +8.1 `cut': Print selected parts of lines +======================================== + +`cut' writes to standard output selected parts of each line of each +input file, or standard input if no files are given or for a file name +of `-'. Synopsis: + + cut [OPTION]... [FILE]... + + In the table which follows, the BYTE-LIST, CHARACTER-LIST, and +FIELD-LIST are one or more numbers or ranges (two numbers separated by +a dash) separated by commas. Bytes, characters, and fields are +numbered starting at 1. Incomplete ranges may be given: `-M' means +`1-M'; `N-' means `N' through end of line or last field. The list +elements can be repeated, can overlap, and can be specified in any +order; but the selected input is written in the same order that it is +read, and is written exactly once. + + The program accepts the following options. Also see *Note Common +options::. + +`-b BYTE-LIST' +`--bytes=BYTE-LIST' + Select for printing only the bytes in positions listed in + BYTE-LIST. Tabs and backspaces are treated like any other + character; they take up 1 byte. If an output delimiter is + specified, (see the description of `--output-delimiter'), then + output that string between ranges of selected bytes. + +`-c CHARACTER-LIST' +`--characters=CHARACTER-LIST' + Select for printing only the characters in positions listed in + CHARACTER-LIST. The same as `-b' for now, but + internationalization will change that. Tabs and backspaces are + treated like any other character; they take up 1 character. If an + output delimiter is specified, (see the description of + `--output-delimiter'), then output that string between ranges of + selected bytes. + +`-f FIELD-LIST' +`--fields=FIELD-LIST' + Select for printing only the fields listed in FIELD-LIST. Fields + are separated by a TAB character by default. Also print any line + that contains no delimiter character, unless the + `--only-delimited' (`-s') option is specified + +`-d INPUT_DELIM_BYTE' +`--delimiter=INPUT_DELIM_BYTE' + With `-f', use the first byte of INPUT_DELIM_BYTE as the input + fields separator (default is TAB). + +`-n' + Do not split multi-byte characters (no-op for now). + +`-s' +`--only-delimited' + For `-f', do not print lines that do not contain the field + separator character. Normally, any line without a field separator + is printed verbatim. + +`--output-delimiter=OUTPUT_DELIM_STRING' + With `-f', output fields are separated by OUTPUT_DELIM_STRING. + The default with `-f' is to use the input delimiter. When using + `-b' or `-c' to select ranges of byte or character offsets (as + opposed to ranges of fields), output OUTPUT_DELIM_STRING between + non-overlapping ranges of selected bytes. + +`--complement' + This option is a GNU extension. Select for printing the + complement of the bytes, characters or fields selected with the + `-b', `-c' or `-f' options. In other words, do _not_ print the + bytes, characters or fields specified via those options. This + option is useful when you have many fields and want to print all + but a few of them. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: paste invocation, Next: join invocation, Prev: cut invocation, Up: Operating on fields within a line + +8.2 `paste': Merge lines of files +================================= + +`paste' writes to standard output lines consisting of sequentially +corresponding lines of each given file, separated by a TAB character. +Standard input is used for a file name of `-' or if no input files are +given. + + For example: + + $ cat num2 + 1 + 2 + $ cat let3 + a + b + c + $ paste num2 let3 + 1 a + 2 b + c + + Synopsis: + + paste [OPTION]... [FILE]... + + The program accepts the following options. Also see *Note Common +options::. + +`-s' +`--serial' + Paste the lines of one file at a time rather than one line from + each file. Using the above example data: + + $ paste -s num2 let3 + 1 2 + a b c + +`-d DELIM-LIST' +`--delimiters=DELIM-LIST' + Consecutively use the characters in DELIM-LIST instead of TAB to + separate merged lines. When DELIM-LIST is exhausted, start again + at its beginning. Using the above example data: + + $ paste -d '%_' num2 let3 num2 + 1%a_1 + 2%b_2 + %c_ + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: join invocation, Prev: paste invocation, Up: Operating on fields within a line + +8.3 `join': Join lines on a common field +======================================== + +`join' writes to standard output a line for each pair of input lines +that have identical join fields. Synopsis: + + join [OPTION]... FILE1 FILE2 + + Either FILE1 or FILE2 (but not both) can be `-', meaning standard +input. FILE1 and FILE2 should be sorted on the join fields. + + Normally, the sort order is that of the collating sequence specified +by the `LC_COLLATE' locale. Unless the `-t' option is given, the sort +comparison ignores blanks at the start of the join field, as in `sort +-b'. If the `--ignore-case' option is given, the sort comparison +ignores the case of characters in the join field, as in `sort -f'. + + The `sort' and `join' commands should use consistent locales and +options if the output of `sort' is fed to `join'. You can use a +command like `sort -k 1b,1' to 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 `join' +and `sort'. + + As a GNU extension, if the input has no unpairable lines the sort +order can be any order that considers two fields to be equal if and +only if the sort comparison described above considers them to be equal. +For example: + + $ cat file1 + a a1 + c c1 + b b1 + $ cat file2 + a a2 + c c2 + b b2 + $ join file1 file2 + a a1 a2 + c c1 c2 + b b1 b2 + + The defaults are: + * the join field is the first field in each line; + + * fields in the input are separated by one or more blanks, with + leading blanks on the line ignored; + + * fields in the output are separated by a space; + + * each output line consists of the join field, the remaining fields + from FILE1, then the remaining fields from FILE2. + + The program accepts the following options. Also see *Note Common +options::. + +`-a FILE-NUMBER' + Print a line for each unpairable line in file FILE-NUMBER (either + `1' or `2'), in addition to the normal output. + +`-e STRING' + Replace those output fields that are missing in the input with + STRING. + +`-i' +`--ignore-case' + Ignore differences in case when comparing keys. With this option, + the lines of the input files must be ordered in the same way. Use + `sort -f' to produce this ordering. + +`-1 FIELD' + Join on field FIELD (a positive integer) of file 1. + +`-2 FIELD' + Join on field FIELD (a positive integer) of file 2. + +`-j FIELD' + Equivalent to `-1 FIELD -2 FIELD'. + +`-o FIELD-LIST' + Construct each output line according to the format in FIELD-LIST. + Each element in FIELD-LIST is either the single character `0' or + has the form M.N where the file number, M, is `1' or `2' and N is + a positive field number. + + A field specification of `0' denotes the join field. In most + cases, the functionality of the `0' field spec may be reproduced + using the explicit M.N that corresponds to the join field. + However, when printing unpairable lines (using either of the `-a' + or `-v' options), there is no way to specify the join field using + M.N in FIELD-LIST if there are unpairable lines in both files. To + give `join' that functionality, POSIX invented the `0' field + specification notation. + + The elements in FIELD-LIST are separated by commas or blanks. + Blank separators typically need to be quoted for the shell. For + example, the commands `join -o 1.2,2.2' and `join -o '1.2 2.2'' + are equivalent. + + All output lines--including those printed because of any -a or -v + option--are subject to the specified FIELD-LIST. + +`-t CHAR' + Use character CHAR as the input and output field separator. Treat + as significant each occurrence of CHAR in the input file. Use + `sort -t CHAR', without the `-b' option of `sort', to produce this + ordering. + +`-v FILE-NUMBER' + Print a line for each unpairable line in file FILE-NUMBER (either + `1' or `2'), instead of the normal output. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Operating on characters, Next: Directory listing, Prev: Operating on fields within a line, Up: Top + +9 Operating on characters +************************* + +This commands operate on individual characters. + +* Menu: + +* tr invocation:: Translate, squeeze, and/or delete characters. +* expand invocation:: Convert tabs to spaces. +* unexpand invocation:: Convert spaces to tabs. + + +File: coreutils.info, Node: tr invocation, Next: expand invocation, Up: Operating on characters + +9.1 `tr': Translate, squeeze, and/or delete characters +====================================================== + +Synopsis: + + tr [OPTION]... SET1 [SET2] + + `tr' copies standard input to standard output, performing one of the +following operations: + + * translate, and optionally squeeze repeated characters in the + result, + + * squeeze repeated characters, + + * delete characters, + + * delete characters, then squeeze repeated characters from the + result. + + The SET1 and (if given) SET2 arguments define ordered sets of +characters, referred to below as SET1 and SET2. These sets are the +characters of the input that `tr' operates on. The `--complement' +(`-c', `-C') option replaces SET1 with its complement (all of the +characters that are not in SET1). + + Currently `tr' fully supports only single-byte characters. +Eventually it will support multibyte characters; when it does, the `-C' +option will cause it to complement the set of characters, whereas `-c' +will cause it to complement the set of values. This distinction will +matter only when some values are not characters, and this is possible +only in locales using multibyte encodings when the input contains +encoding errors. + + The program accepts the `--help' and `--version' options. *Note +Common options::. Options must precede operands. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + +* Menu: + +* Character sets:: Specifying sets of characters. +* Translating:: Changing one set of characters to another. +* Squeezing:: Squeezing repeats and deleting. + + +File: coreutils.info, Node: Character sets, Next: Translating, Up: tr invocation + +9.1.1 Specifying sets of characters +----------------------------------- + +The format of the SET1 and SET2 arguments resembles the format of +regular expressions; however, they are not regular expressions, only +lists of characters. Most characters simply represent themselves in +these strings, but the strings can contain the shorthands listed below, +for convenience. Some of them can be used only in SET1 or SET2, as +noted below. + +Backslash escapes + The following backslash escape sequences are recognized: + + `\a' + Control-G. + + `\b' + Control-H. + + `\f' + Control-L. + + `\n' + Control-J. + + `\r' + Control-M. + + `\t' + Control-I. + + `\v' + Control-K. + + `\OOO' + The character with the value given by OOO, which is 1 to 3 + octal digits, + + `\\' + A backslash. + + While a backslash followed by a character not listed above is + interpreted as that character, the backslash also effectively + removes any special significance, so it is useful to escape `[', + `]', `*', and `-'. + +Ranges + The notation `M-N' expands to all of the characters from M through + N, in ascending order. M should collate before N; if it doesn't, + an error results. As an example, `0-9' is the same as + `0123456789'. + + GNU `tr' does not support the System V syntax that uses square + brackets to enclose ranges. Translations specified in that format + sometimes work as expected, since the brackets are often + transliterated to themselves. However, they should be avoided + because they sometimes behave unexpectedly. For example, `tr -d + '[0-9]'' deletes brackets as well as digits. + + Many historically common and even accepted uses of ranges are not + portable. For example, on EBCDIC hosts using the `A-Z' range will + not do what most would expect because `A' through `Z' are not + contiguous as they are in ASCII. If you can rely on a POSIX + compliant version of `tr', then the best way to work around this + is to use character classes (see below). Otherwise, it is most + portable (and most ugly) to enumerate the members of the ranges. + +Repeated characters + The notation `[C*N]' in SET2 expands to N copies of character C. + Thus, `[y*6]' is the same as `yyyyyy'. The notation `[C*]' in + STRING2 expands to as many copies of C as are needed to make SET2 + as long as SET1. If N begins with `0', it is interpreted in + octal, otherwise in decimal. + +Character classes + The notation `[:CLASS:]' expands to all of the characters in the + (predefined) class CLASS. The characters expand in no particular + order, except for the `upper' and `lower' classes, which expand in + ascending order. When the `--delete' (`-d') and + `--squeeze-repeats' (`-s') options are both given, any character + class can be used in SET2. Otherwise, only the character classes + `lower' and `upper' are accepted in SET2, and then only if the + corresponding character class (`upper' and `lower', respectively) + is specified in the same relative position in SET1. Doing this + specifies case conversion. The class names are given below; an + error results when an invalid class name is given. + + `alnum' + Letters and digits. + + `alpha' + Letters. + + `blank' + Horizontal whitespace. + + `cntrl' + Control characters. + + `digit' + Digits. + + `graph' + Printable characters, not including space. + + `lower' + Lowercase letters. + + `print' + Printable characters, including space. + + `punct' + Punctuation characters. + + `space' + Horizontal or vertical whitespace. + + `upper' + Uppercase letters. + + `xdigit' + Hexadecimal digits. + +Equivalence classes + The syntax `[=C=]' expands to all of the characters that are + equivalent to C, in no particular order. Equivalence classes are + a relatively recent invention intended to support non-English + alphabets. But there seems to be no standard way to define them + or determine their contents. Therefore, they are not fully + implemented in GNU `tr'; each character's equivalence class + consists only of that character, which is of no particular use. + + + +File: coreutils.info, Node: Translating, Next: Squeezing, Prev: Character sets, Up: tr invocation + +9.1.2 Translating +----------------- + +`tr' performs translation when SET1 and SET2 are both given and the +`--delete' (`-d') option is not given. `tr' translates each character +of its input that is in SET1 to the corresponding character in SET2. +Characters not in SET1 are passed through unchanged. When a character +appears more than once in SET1 and the corresponding characters in SET2 +are not all the same, only the final one is used. For example, these +two commands are equivalent: + + tr aaa xyz + tr a z + + A common use of `tr' is to convert lowercase characters to +uppercase. This can be done in many ways. Here are three of them: + + tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ + tr a-z A-Z + tr '[:lower:]' '[:upper:]' + +But note that using ranges like `a-z' above is not portable. + + When `tr' is performing translation, SET1 and SET2 typically have +the same length. If SET1 is shorter than SET2, the extra characters at +the end of SET2 are ignored. + + On the other hand, making SET1 longer than SET2 is not portable; +POSIX says that the result is undefined. In this situation, BSD `tr' +pads SET2 to the length of SET1 by repeating the last character of SET2 +as many times as necessary. System V `tr' truncates SET1 to the length +of SET2. + + By default, GNU `tr' handles this case like BSD `tr'. When the +`--truncate-set1' (`-t') option is given, GNU `tr' handles this case +like the System V `tr' instead. This option is ignored for operations +other than translation. + + Acting like System V `tr' in this case breaks the relatively common +BSD idiom: + + tr -cs A-Za-z0-9 '\012' + +because it converts only zero bytes (the first element in the +complement of SET1), rather than all non-alphanumerics, to newlines. + +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 POSIX +compliant `tr', here is a better way to write it: + + tr -cs '[:alnum:]' '[\n*]' + + +File: coreutils.info, Node: Squeezing, Prev: Translating, Up: tr invocation + +9.1.3 Squeezing repeats and deleting +------------------------------------ + +When given just the `--delete' (`-d') option, `tr' removes any input +characters that are in SET1. + + When given just the `--squeeze-repeats' (`-s') option, `tr' replaces +each input sequence of a repeated character that is in SET1 with a +single occurrence of that character. + + When given both `--delete' and `--squeeze-repeats', `tr' first +performs any deletions using SET1, then squeezes repeats from any +remaining characters using SET2. + + The `--squeeze-repeats' option may also be used when translating, in +which case `tr' first performs translation, then squeezes repeats from +any remaining characters using SET2. + + Here are some examples to illustrate various combinations of options: + + * Remove all zero bytes: + + tr -d '\0' + + * Put all words on lines by themselves. This converts all + non-alphanumeric characters to newlines, then squeezes each string + of repeated newlines into a single newline: + + tr -cs '[:alnum:]' '[\n*]' + + * Convert each sequence of repeated newlines to a single newline: + + tr -s '\n' + + * Find doubled occurrences of words in a document. For example, + people often write "the the" with the repeated words separated by + a newline. The Bourne shell script below works first by + converting each sequence of punctuation and blank characters to a + single newline. That puts each "word" on a line by itself. Next + it maps all uppercase characters to lower case, and finally it + runs `uniq' with the `-d' option to print out only the words that + were repeated. + + #!/bin/sh + cat -- "$@" \ + | tr -s '[:punct:][:blank:]' '[\n*]' \ + | tr '[:upper:]' '[:lower:]' \ + | uniq -d + + * Deleting a small set of characters is usually straightforward. + For example, to remove all `a's, `x's, and `M's you would do this: + + tr -d axM + + However, when `-' is one of those characters, it can be tricky + because `-' has special meanings. Performing the same task as + above but also removing all `-' characters, we might try `tr -d + -axM', but that would fail because `tr' would try to interpret + `-a' as a command-line option. Alternatively, we could try + putting the hyphen inside the string, `tr -d a-xM', but that + wouldn't work either because it would make `tr' interpret `a-x' as + the range of characters `a'...`x' rather than the three. One way + to solve the problem is to put the hyphen at the end of the list + of characters: + + tr -d axM- + + Or you can use `--' to terminate option processing: + + tr -d -- -axM + + More generally, use the character class notation `[=c=]' with `-' + (or any other character) in place of the `c': + + tr -d '[=-=]axM' + + Note how single quotes are used in the above example to protect the + square brackets from interpretation by a shell. + + + +File: coreutils.info, Node: expand invocation, Next: unexpand invocation, Prev: tr invocation, Up: Operating on characters + +9.2 `expand': Convert tabs to spaces +==================================== + +`expand' writes the contents of each given FILE, or standard input if +none are given or for a FILE of `-', to standard output, with tab +characters converted to the appropriate number of spaces. Synopsis: + + expand [OPTION]... [FILE]... + + By default, `expand' converts all tabs to spaces. It preserves +backspace characters in the output; they decrement the column count for +tab calculations. The default action is equivalent to `-t 8' (set tabs +every 8 columns). + + The program accepts the following options. Also see *Note Common +options::. + +`-t TAB1[,TAB2]...' +`--tabs=TAB1[,TAB2]...' + If only one tab stop is given, set the tabs TAB1 spaces apart + (default is 8). Otherwise, set the tabs at columns TAB1, TAB2, + ... (numbered from 0), and replace any tabs beyond the last tab + stop given with single spaces. Tab stops can be separated by + blanks as well as by commas. + + For compatibility, GNU `expand' also accepts the obsolete option + syntax, `-T1[,T2]...'. New scripts should use `-t T1[,T2]...' + instead. + +`-i' +`--initial' + Only convert initial tabs (those that precede all non-space or + non-tab characters) on each line to spaces. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: unexpand invocation, Prev: expand invocation, Up: Operating on characters + +9.3 `unexpand': Convert spaces to tabs +====================================== + +`unexpand' writes the contents of each given FILE, or standard input if +none are given or for a FILE of `-', to standard output, converting +blanks at the beginning of each line into as many tab characters as +needed. In the default POSIX locale, a "blank" is a space or a tab; +other locales may specify additional blank characters. Synopsis: + + unexpand [OPTION]... [FILE]... + + By default, `unexpand' converts only initial blanks (those that +precede all non-blank characters) on each line. It preserves backspace +characters in the output; they decrement the column count for tab +calculations. By default, tabs are set at every 8th column. + + The program accepts the following options. Also see *Note Common +options::. + +`-t TAB1[,TAB2]...' +`--tabs=TAB1[,TAB2]...' + If only one tab stop is given, set the tabs TAB1 columns apart + instead of the default 8. Otherwise, set the tabs at columns + TAB1, TAB2, ... (numbered from 0), and leave blanks beyond the tab + stops given unchanged. Tab stops can be separated by blanks as + well as by commas. This option implies the `-a' option. + + For compatibility, GNU `unexpand' supports the obsolete option + syntax, `-TAB1[,TAB2]...', where tab stops must be separated by + commas. (Unlike `-t', this obsolete option does not imply `-a'.) + New scripts should use `--first-only -t TAB1[,TAB2]...' instead. + +`-a' +`--all' + Also convert all sequences of two or more blanks just before a tab + stop, even if they occur after non-blank characters in a line. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Directory listing, Next: Basic operations, Prev: Operating on characters, Up: Top + +10 Directory listing +******************** + +This chapter describes the `ls' command and its variants `dir' and +`vdir', which list information about files. + +* Menu: + +* ls invocation:: List directory contents. +* dir invocation:: Briefly ls. +* vdir invocation:: Verbosely ls. +* dircolors invocation:: Color setup for ls, etc. + + +File: coreutils.info, Node: ls invocation, Next: dir invocation, Up: Directory listing + +10.1 `ls': List directory contents +================================== + +The `ls' program lists information about files (of any type, including +directories). Options and file arguments can be intermixed +arbitrarily, as usual. + + For non-option command-line arguments that are directories, by +default `ls' lists the contents of directories, not recursively, and +omitting files with names beginning with `.'. For other non-option +arguments, by default `ls' lists just the file name. If no non-option +argument is specified, `ls' operates on the current directory, acting +as if it had been invoked with a single argument of `.'. + + By default, the output is sorted alphabetically, according to the +locale settings in effect.(1) If standard output is a terminal, the +output is in columns (sorted vertically) and control characters are +output as question marks; otherwise, the output is listed one per line +and control characters are output as-is. + + Because `ls' is such a fundamental program, it has accumulated many +options over the years. They are described in the subsections below; +within each section, options are listed alphabetically (ignoring case). +The division of options into the subsections is not absolute, since some +options affect more than one aspect of `ls''s operation. + + Exit status: + + 0 success + 1 minor problems (e.g., a subdirectory was not found) + 2 serious trouble (e.g., memory exhausted) + + Also see *Note Common options::. + +* Menu: + +* Which files are listed:: +* What information is listed:: +* Sorting the output:: +* More details about version sort:: +* General output formatting:: +* Formatting file timestamps:: +* Formatting the file names:: + + ---------- Footnotes ---------- + + (1) If you use a non-POSIX locale (e.g., by setting `LC_ALL' to +`en_US'), then `ls' may produce output that is sorted differently than +you're accustomed to. In that case, set the `LC_ALL' environment +variable to `C'. + + +File: coreutils.info, Node: Which files are listed, Next: What information is listed, Up: ls invocation + +10.1.1 Which files are listed +----------------------------- + +These options determine which files `ls' lists information for. By +default, `ls' lists files and the contents of any directories on the +command line, except that in directories it ignores files whose names +start with `.'. + +`-a' +`--all' + In directories, do not ignore file names that start with `.'. + +`-A' +`--almost-all' + In directories, do not ignore all file names that start with `.'; + ignore only `.' and `..'. The `--all' (`-a') option overrides + this option. + +`-B' +`--ignore-backups' + In directories, ignore files that end with `~'. This option is + equivalent to `--ignore='*~' --ignore='.*~''. + +`-d' +`--directory' + List just the names of directories, as with other types of files, + rather than listing their contents. Do not follow symbolic links + listed on the command line unless the `--dereference-command-line' + (`-H'), `--dereference' (`-L'), or + `--dereference-command-line-symlink-to-dir' options are specified. + +`-H' +`--dereference-command-line' + If a command line argument specifies a symbolic link, show + information for the file the link references rather than for the + link itself. + +`--dereference-command-line-symlink-to-dir' + Do not dereference symbolic links, with one exception: if a + command line argument specifies a symbolic link that refers to a + directory, show information for that directory rather than for the + link itself. This is the default behavior when no other + dereferencing-related option has been specified (`--classify' + (`-F'), `--directory' (`-d'), (`-l'), `--dereference' (`-L'), or + `--dereference-command-line' (`-H')). + +`--group-directories-first' + Group all the directories before the files and then sort the + directories and the files separately using the selected sort key + (see -sort option). That is, this option specifies a primary sort + key, and the -sort option specifies a secondary key. + +`--hide=PATTERN' + In directories, ignore files whose names match the shell pattern + PATTERN, unless the `--all' (`-a') or `--almost-all' (`-A') is + also given. This option acts like `--ignore=PATTERN' except that + it has no effect if `--all' (`-a') or `--almost-all' (`-A') is + also given. + + This option can be useful in shell aliases. For example, if `lx' + is an alias for `ls --hide='*~'' and `ly' is an alias for `ls + --ignore='*~'', then the command `lx -A' lists the file `README~' + even though `ly -A' would not. + +`-I PATTERN' +`--ignore=PATTERN' + In directories, ignore files whose names match the shell pattern + (not regular expression) PATTERN. As in the shell, an initial `.' + in a file name does not match a wildcard at the start of PATTERN. + Sometimes it is useful to give this option several times. For + example, + + $ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*' + + The first option ignores names of length 3 or more that start with + `.', the second ignores all two-character names that start with `.' + except `..', and the third ignores names that start with `#'. + +`-L' +`--dereference' + When showing file information for a symbolic link, show information + for the file the link references rather than the link itself. + However, even with this option, `ls' still prints the name of the + link itself, not the name of the file that the link points to. + +`-R' +`--recursive' + List the contents of all directories recursively. + + + +File: coreutils.info, Node: What information is listed, Next: Sorting the output, Prev: Which files are listed, Up: ls invocation + +10.1.2 What information is listed +--------------------------------- + +These options affect the information that `ls' displays. By default, +only file names are shown. + +`--author' + List each file's author when producing long format directory + listings. In GNU/Hurd, file authors can differ from their owners, + but in other operating systems the two are the same. + +`-D' +`--dired' + With the long listing (`-l') format, print an additional line after + the main output: + + //DIRED// BEG1 END1 BEG2 END2 ... + + The BEGN and ENDN are unsigned integers that record the byte + position of the beginning and end of each file name in the output. + This makes it easy for Emacs to find the names, even when they + contain unusual characters such as space or newline, without fancy + searching. + + If directories are being listed recursively (`-R'), output a + similar line with offsets for each subdirectory name: + + //SUBDIRED// BEG1 END1 ... + + Finally, output a line of the form: + + //DIRED-OPTIONS// --quoting-style=WORD + + where WORD is the quoting style (*note Formatting the file + names::). + + Here is an actual example: + + $ mkdir -p a/sub/deeper a/sub2 + $ touch a/f1 a/f2 + $ touch a/sub/deeper/file + $ ls -gloRF --dired a + a: + total 8 + -rw-r--r-- 1 0 Jun 10 12:27 f1 + -rw-r--r-- 1 0 Jun 10 12:27 f2 + drwxr-xr-x 3 4096 Jun 10 12:27 sub/ + drwxr-xr-x 2 4096 Jun 10 12:27 sub2/ + + a/sub: + total 4 + drwxr-xr-x 2 4096 Jun 10 12:27 deeper/ + + a/sub/deeper: + total 0 + -rw-r--r-- 1 0 Jun 10 12:27 file + + a/sub2: + total 0 + //DIRED// 48 50 84 86 120 123 158 162 217 223 282 286 + //SUBDIRED// 2 3 167 172 228 240 290 296 + //DIRED-OPTIONS// --quoting-style=literal + + Note that the pairs of offsets on the `//DIRED//' line above + delimit these names: `f1', `f2', `sub', `sub2', `deeper', `file'. + The offsets on the `//SUBDIRED//' line delimit the following + directory names: `a', `a/sub', `a/sub/deeper', `a/sub2'. + + Here is an example of how to extract the fifth entry name, + `deeper', corresponding to the pair of offsets, 222 and 228: + + $ ls -gloRF --dired a > out + $ dd bs=1 skip=222 count=6 < out 2>/dev/null; echo + deeper + + Note that although the listing above includes a trailing slash for + the `deeper' entry, the offsets select the name without the + trailing slash. However, if you invoke `ls' with `--dired' along + with an option like `--escape' (aka `-b') and operate on a file + whose name contains special characters, notice that the backslash + _is_ included: + + $ touch 'a b' + $ ls -blog --dired 'a b' + -rw-r--r-- 1 0 Jun 10 12:28 a\ b + //DIRED// 30 34 + //DIRED-OPTIONS// --quoting-style=escape + + If you use a quoting style that adds quote marks (e.g., + `--quoting-style=c'), then the offsets include the quote marks. + So beware that the user may select the quoting style via the + environment variable `QUOTING_STYLE'. Hence, applications using + `--dired' should either specify an explicit + `--quoting-style=literal' option (aka `-N' or `--literal') on the + command line, or else be prepared to parse the escaped names. + +`--full-time' + Produce long format directory listings, and list times in full. + It is equivalent to using `--format=long' with + `--time-style=full-iso' (*note Formatting file timestamps::). + +`-g' + Produce long format directory listings, but don't display owner + information. + +`-G' +`--no-group' + Inhibit display of group information in a long format directory + listing. (This is the default in some non-GNU versions of `ls', + so we provide this option for compatibility.) + +`-h' +`--human-readable' + Append a size letter to each size, such as `M' for mebibytes. + Powers of 1024 are used, not 1000; `M' stands for 1,048,576 bytes. + Use the `--si' option if you prefer powers of 1000. + +`-i' +`--inode' + Print the inode number (also called the file serial number and + index number) of each file to the left of the file name. (This + number uniquely identifies each file within a particular file + system.) + +`-l' +`--format=long' +`--format=verbose' + In addition to the name of each file, print the file type, file + mode bits, number of hard links, owner name, group name, size, and + timestamp (*note Formatting file timestamps::), normally the + modification time. Print question marks for information that + cannot be determined. + + Normally the size is printed as a byte count without punctuation, + but this can be overridden (*note Block size::). For example, `-h' + prints an abbreviated, human-readable count, and + `--block-size="'1"' prints a byte count with the thousands + separator of the current locale. + + For each directory that is listed, preface the files with a line + `total BLOCKS', where BLOCKS is the total disk allocation for all + files in that directory. The block size currently defaults to 1024 + bytes, but this can be overridden (*note Block size::). The + BLOCKS computed counts each hard link separately; this is arguably + a deficiency. + + The file type is one of the following characters: + + `-' + regular file + + `b' + block special file + + `c' + character special file + + `C' + high performance ("contiguous data") file + + `d' + directory + + `D' + door (Solaris 2.5 and up) + + `l' + symbolic link + + `M' + off-line ("migrated") file (Cray DMF) + + `n' + network special file (HP-UX) + + `p' + FIFO (named pipe) + + `P' + port (Solaris 10 and up) + + `s' + socket + + `?' + some other file type + + The file mode bits listed are similar to symbolic mode + specifications (*note Symbolic Modes::). But `ls' combines + multiple bits into the third character of each set of permissions + as follows: + + `s' + If the set-user-ID or set-group-ID bit and the corresponding + executable bit are both set. + + `S' + If the set-user-ID or set-group-ID bit is set but the + corresponding executable bit is not set. + + `t' + If the restricted deletion flag or sticky bit, and the + other-executable bit, are both set. The restricted deletion + flag is another name for the sticky bit. *Note Mode + Structure::. + + `T' + If the restricted deletion flag or sticky bit is set but the + other-executable bit is not set. + + `x' + If the executable bit is set and none of the above apply. + + `-' + Otherwise. + + Following the file mode bits is a single character that specifies + whether an alternate access method such as an access control list + applies to the file. When the character following the file mode + bits is a space, there is no alternate access method. When it is + a printing character, then there is such a method. + + For a file with an extended access control list, a `+' character is + listed. Basic access control lists are equivalent to the + permissions listed, and are not considered an alternate access + method. + +`-n' +`--numeric-uid-gid' + Produce long format directory listings, but display numeric user + and group IDs instead of the owner and group names. + +`-o' + Produce long format directory listings, but don't display group + information. It is equivalent to using `--format=long' with + `--no-group' . + +`-s' +`--size' + Print the disk allocation of each file to the left of the file + name. This is the amount of disk space used by the file, which is + usually a bit more than the file's size, but it can be less if the + file has holes. + + Normally the disk allocation is printed in units of 1024 bytes, + but this can be overridden (*note Block size::). + + For files that are NFS-mounted from an HP-UX system to a BSD + system, this option reports sizes that are half the correct + values. On HP-UX systems, it reports sizes that are twice the + correct values for files that are NFS-mounted from BSD systems. + This is due to a flaw in HP-UX; it also affects the HP-UX `ls' + program. + +`--si' + Append an SI-style abbreviation to each size, such as `M' for + megabytes. Powers of 1000 are used, not 1024; `M' stands for + 1,000,000 bytes. This option is equivalent to `--block-size=si'. + Use the `-h' or `--human-readable' option if you prefer powers of + 1024. + + + +File: coreutils.info, Node: Sorting the output, Next: More details about version sort, Prev: What information is listed, Up: ls invocation + +10.1.3 Sorting the output +------------------------- + +These options change the order in which `ls' sorts the information it +outputs. By default, sorting is done by character code (e.g., ASCII +order). + +`-c' +`--time=ctime' +`--time=status' + If the long listing format (e.g., `-l', `-o') is being used, print + the status change time (the `ctime' in the inode) instead of the + modification time. When explicitly sorting by time (`--sort=time' + or `-t') or when not using a long listing format, sort according + to the status change time. + +`-f' + Primarily, like `-U'--do not sort; list the files in whatever + order they are stored in the directory. But also enable `-a' (list + all files) and disable `-l', `--color', and `-s' (if they were + specified before the `-f'). + +`-r' +`--reverse' + Reverse whatever the sorting method is--e.g., list files in reverse + alphabetical order, youngest first, smallest first, or whatever. + +`-S' +`--sort=size' + Sort by file size, largest first. + +`-t' +`--sort=time' + Sort by modification time (the `mtime' in the inode), newest first. + +`-u' +`--time=atime' +`--time=access' +`--time=use' + If the long listing format (e.g., `--format=long') is being used, + print the last access time (the `atime' in the inode). When + explicitly sorting by time (`--sort=time' or `-t') or when not + using a long listing format, sort according to the access time. + +`-U' +`--sort=none' + Do not sort; list the files in whatever order they are stored in + the directory. (Do not do any of the other unrelated things that + `-f' does.) This is especially useful when listing very large + directories, since not doing any sorting can be noticeably faster. + +`-v' +`--sort=version' + 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. (*Note More + details about version sort::.) + +`-X' +`--sort=extension' + Sort directory contents alphabetically by file extension + (characters after the last `.'); files with no extension are + sorted first. + + + +File: coreutils.info, Node: More details about version sort, Next: General output formatting, Prev: Sorting the output, Up: ls invocation + +10.1.4 More 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: + + $ 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 + + Note also that numeric parts with leading zeros are considered as +fractional one: + + $ ls -1 $ ls -1v + abc-1.007.tgz abc-1.007.tgz + abc-1.012b.tgz abc-1.01a.tgz + abc-1.01a.tgz abc-1.012b.tgz + + This functionality is implemented using the `strverscmp' function. +*Note String/Array Comparison: (libc)String/Array Comparison. One +result of that implementation decision is that `ls -v' does not use the +locale category, `LC_COLLATE'. As a result, non-numeric prefixes are +sorted as if `LC_COLLATE' were set to `C'. + + +File: coreutils.info, Node: General output formatting, Next: Formatting file timestamps, Prev: More details about version sort, Up: ls invocation + +10.1.5 General output formatting +-------------------------------- + +These options affect the appearance of the overall output. + +`-1' +`--format=single-column' + List one file per line. This is the default for `ls' when standard + output is not a terminal. + +`-C' +`--format=vertical' + List files in columns, sorted vertically. This is the default for + `ls' if standard output is a terminal. It is always the default + for the `dir' program. GNU `ls' uses variable width columns to + display as many files as possible in the fewest lines. + +`--color [=WHEN]' + Specify whether to use color for distinguishing file types. WHEN + may be omitted, or one of: + * none - Do not use color at all. This is the default. + + * auto - Only use color if standard output is a terminal. + + * always - Always use color. + Specifying `--color' and no WHEN is equivalent to `--color=always'. + Piping a colorized listing through a pager like `more' or `less' + usually produces unreadable results. However, using `more -f' + does seem to work. + +`-F' +`--classify' +`--indicator-style=classify' + Append a character to each file name indicating the file type. + Also, for regular files that are executable, append `*'. The file + type indicators are `/' for directories, `@' for symbolic links, + `|' for FIFOs, `=' for sockets, `>' for doors, and nothing for + regular files. Do not follow symbolic links listed on the command + line unless the `--dereference-command-line' (`-H'), + `--dereference' (`-L'), or + `--dereference-command-line-symlink-to-dir' options are specified. + +`--file-type' +`--indicator-style=file-type' + Append a character to each file name indicating the file type. + This is like `-F', except that executables are not marked. + +`--indicator-style=WORD' + Append a character indicator with style WORD to entry names, as + follows: + + `none' + Do not append any character indicator; this is the default. + + `slash' + Append `/' for directories. This is the same as the `-p' + option. + + `file-type' + Append `/' for directories, `@' for symbolic links, `|' for + FIFOs, `=' for sockets, and nothing for regular files. This + is the same as the `--file-type' option. + + `classify' + Append `*' for executable regular files, otherwise behave as + for `file-type'. This is the same as the `-F' or + `--classify' option. + +`-k' + Print file sizes in 1024-byte blocks, overriding the default block + size (*note Block size::). This option is equivalent to + `--block-size=1K'. + +`-m' +`--format=commas' + List files horizontally, with as many as will fit on each line, + separated by `, ' (a comma and a space). + +`-p' +`--indicator-style=slash' + Append a `/' to directory names. + +`-x' +`--format=across' +`--format=horizontal' + List the files in columns, sorted horizontally. + +`-T COLS' +`--tabsize=COLS' + Assume that each tab stop is COLS columns wide. The default is 8. + `ls' uses tabs where possible in the output, for efficiency. If + COLS is zero, do not use tabs at all. + + Some terminal emulators (at least Apple Terminal 1.5 (133) from + Mac OS X 10.4.8) do not properly align columns to the right of a + TAB following a non-ASCII byte. If you use such a terminal + emulator, use the `-T0' option or put `TABSIZE=0' in your + environment to tell `ls' to align using spaces, not tabs. + +`-w' +`--width=COLS' + Assume the screen is COLS columns wide. The default is taken from + the terminal settings if possible; otherwise the environment + variable `COLUMNS' is used if it is set; otherwise the default is + 80. + + + +File: coreutils.info, Node: Formatting file timestamps, Next: Formatting the file names, Prev: General output formatting, Up: ls invocation + +10.1.6 Formatting file timestamps +--------------------------------- + +By default, file timestamps are listed in abbreviated form. Most +locales use a timestamp like `2002-03-30 23:45'. However, the default +POSIX locale uses a date like `Mar 30 2002' for non-recent timestamps, +and a date-without-year and time like `Mar 30 23:45' for recent +timestamps. + + A timestamp is considered to be "recent" if it is less than six +months old, and is not dated in the future. If a timestamp dated today +is not listed in recent form, the timestamp is in the future, which +means you probably have clock skew problems which may break programs +like `make' that rely on file timestamps. + + Time stamps are listed according to the time zone rules specified by +the `TZ' environment variable, or by the system default rules if `TZ' +is not set. *Note Specifying the Time Zone with `TZ': (libc)TZ +Variable. + + The following option changes how file timestamps are printed. + +`--time-style=STYLE' + List timestamps in style STYLE. The STYLE should be one of the + following: + + `+FORMAT' + List timestamps using FORMAT, where FORMAT is interpreted + like the format argument of `date' (*note date invocation::). + For example, `--time-style="+%Y-%m-%d %H:%M:%S"' causes `ls' + to list timestamps like `2002-03-30 23:45:56'. As with + `date', FORMAT's interpretation is affected by the `LC_TIME' + locale category. + + If FORMAT contains two format strings separated by a newline, + the former is used for non-recent files and the latter for + recent files; if you want output columns to line up, you may + need to insert spaces in one of the two formats. + + `full-iso' + List timestamps in full using ISO 8601 date, time, and time + zone format with nanosecond precision, e.g., `2002-03-30 + 23:45:56.477817180 -0700'. This style is equivalent to + `+%Y-%m-%d %H:%M:%S.%N %z'. + + This is useful because the time output includes all the + information that is available from the operating system. For + example, this can help explain `make''s behavior, since GNU + `make' uses the full timestamp to determine whether a file is + out of date. + + `long-iso' + List ISO 8601 date and time in minutes, e.g., `2002-03-30 + 23:45'. These timestamps are shorter than `full-iso' + timestamps, and are usually good enough for everyday work. + This style is equivalent to `+%Y-%m-%d %H:%M'. + + `iso' + List ISO 8601 dates for non-recent timestamps (e.g., + `2002-03-30 '), and ISO 8601 month, day, hour, and minute for + recent timestamps (e.g., `03-30 23:45'). These timestamps + are uglier than `long-iso' timestamps, but they carry nearly + the same information in a smaller space and their brevity + helps `ls' output fit within traditional 80-column output + lines. The following two `ls' invocations are equivalent: + + newline=' + ' + ls -l --time-style="+%Y-%m-%d $newline%m-%d %H:%M" + ls -l --time-style="iso" + + `locale' + List timestamps in a locale-dependent form. For example, a + Finnish locale might list non-recent timestamps like `maalis + 30 2002' and recent timestamps like `maalis 30 23:45'. + Locale-dependent timestamps typically consume more space than + `iso' timestamps and are harder for programs to parse because + locale conventions vary so widely, but they are easier for + many people to read. + + The `LC_TIME' locale category specifies the timestamp format. + The default POSIX locale uses timestamps like `Mar 30 2002' + and `Mar 30 23:45'; in this locale, the following two `ls' + invocations are equivalent: + + newline=' + ' + ls -l --time-style="+%b %e %Y$newline%b %e %H:%M" + ls -l --time-style="locale" + + Other locales behave differently. For example, in a German + locale, `--time-style="locale"' might be equivalent to + `--time-style="+%e. %b %Y $newline%e. %b %H:%M"' and might + generate timestamps like `30. Ma"r 2002 ' and `30. Ma"r + 23:45'. + + `posix-STYLE' + List POSIX-locale timestamps if the `LC_TIME' locale category + is POSIX, STYLE timestamps otherwise. For example, the + `posix-long-iso' style lists timestamps like `Mar 30 2002' + and `Mar 30 23:45' when in the POSIX locale, and like + `2002-03-30 23:45' otherwise. + + You can specify the default value of the `--time-style' option with +the environment variable `TIME_STYLE'; if `TIME_STYLE' is not set the +default style is `locale'. GNU Emacs 21.3 and later use the `--dired' +option and therefore can parse any date format, but if you are using +Emacs 21.1 or 21.2 and specify a non-POSIX locale you may need to set +`TIME_STYLE="posix-long-iso"'. + + To avoid certain denial-of-service attacks, timestamps that would be +longer than 1000 bytes may be treated as errors. + + +File: coreutils.info, Node: Formatting the file names, Prev: Formatting file timestamps, Up: ls invocation + +10.1.7 Formatting the file names +-------------------------------- + +These options change how file names themselves are printed. + +`-b' +`--escape' +`--quoting-style=escape' + Quote nongraphic characters in file names using alphabetic and + octal backslash sequences like those used in C. + +`-N' +`--literal' +`--quoting-style=literal' + Do not quote file names. However, with `ls' nongraphic characters + are still printed as question marks if the output is a terminal + and you do not specify the `--show-control-chars' option. + +`-q' +`--hide-control-chars' + Print question marks instead of nongraphic characters in file + names. This is the default if the output is a terminal and the + program is `ls'. + +`-Q' +`--quote-name' +`--quoting-style=c' + Enclose file names in double quotes and quote nongraphic + characters as in C. + +`--quoting-style=WORD' + Use style WORD to quote file names and other strings that may + contain arbitrary characters. The WORD should be one of the + following: + + `literal' + Output strings as-is; this is the same as the `-N' or + `--literal' option. + + `shell' + Quote strings for the shell if they contain shell + metacharacters or would cause ambiguous output. The quoting + is suitable for POSIX-compatible shells like `bash', but it + does not always work for incompatible shells like `csh'. + + `shell-always' + Quote strings for the shell, even if they would normally not + require quoting. + + `c' + Quote strings as for C character string literals, including + the surrounding double-quote characters; this is the same as + the `-Q' or `--quote-name' option. + + `escape' + Quote strings as for C character string literals, except omit + the surrounding double-quote characters; this is the same as + the `-b' or `--escape' option. + + `clocale' + Quote strings as for C character string literals, except use + surrounding quotation marks appropriate for the locale. + + `locale' + Quote strings as for C character string literals, except use + surrounding quotation marks appropriate for the locale, and + quote `like this' instead of "like this" in the default C + locale. This looks nicer on many displays. + + You can specify the default value of the `--quoting-style' option + with the environment variable `QUOTING_STYLE'. If that environment + variable is not set, the default value is `literal', but this + default may change to `shell' in a future version of this package. + +`--show-control-chars' + Print nongraphic characters as-is in file names. This is the + default unless the output is a terminal and the program is `ls'. + + + +File: coreutils.info, Node: dir invocation, Next: vdir invocation, Prev: ls invocation, Up: Directory listing + +10.2 `dir': Briefly list directory contents +=========================================== + +`dir' is equivalent to `ls -C -b'; that is, by default files are listed +in columns, sorted vertically, and special characters are represented +by backslash escape sequences. + + *Note `ls': ls invocation. + + +File: coreutils.info, Node: vdir invocation, Next: dircolors invocation, Prev: dir invocation, Up: Directory listing + +10.3 `vdir': Verbosely list directory contents +============================================== + +`vdir' is equivalent to `ls -l -b'; that is, by default files are +listed in long format and special characters are represented by +backslash escape sequences. + + +File: coreutils.info, Node: dircolors invocation, Prev: vdir invocation, Up: Directory listing + +10.4 `dircolors': Color setup for `ls' +====================================== + +`dircolors' outputs a sequence of shell commands to set up the terminal +for color output from `ls' (and `dir', etc.). Typical usage: + + eval "`dircolors [OPTION]... [FILE]`" + + If FILE is specified, `dircolors' reads it to determine which colors +to use for which file types and extensions. Otherwise, a precompiled +database is used. For details on the format of these files, run +`dircolors --print-database'. + + The output is a shell command to set the `LS_COLORS' environment +variable. You can specify the shell syntax to use on the command line, +or `dircolors' will guess it from the value of the `SHELL' environment +variable. + + The program accepts the following options. Also see *Note Common +options::. + +`-b' +`--sh' +`--bourne-shell' + Output Bourne shell commands. This is the default if the `SHELL' + environment variable is set and does not end with `csh' or `tcsh'. + +`-c' +`--csh' +`--c-shell' + Output C shell commands. This is the default if `SHELL' ends with + `csh' or `tcsh'. + +`-p' +`--print-database' + Print the (compiled-in) default color configuration database. This + output is itself a valid configuration file, and is fairly + descriptive of the possibilities. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Basic operations, Next: Special file types, Prev: Directory listing, Up: Top + +11 Basic operations +******************* + +This chapter describes the commands for basic file manipulation: +copying, moving (renaming), and deleting (removing). + +* Menu: + +* cp invocation:: Copy files. +* 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. + + +File: coreutils.info, Node: cp invocation, Next: dd invocation, Up: Basic operations + +11.1 `cp': Copy files and directories +===================================== + +`cp' copies files (or, optionally, directories). The copy is +completely independent of the original. You can either copy one file to +another, or copy arbitrarily many files to a destination directory. +Synopses: + + cp [OPTION]... [-T] SOURCE DEST + cp [OPTION]... SOURCE... DIRECTORY + cp [OPTION]... -t DIRECTORY SOURCE... + + * If two file names are given, `cp' copies the first file to the + second. + + * If the `--target-directory' (`-t') option is given, or failing + that if the last file is a directory and the + `--no-target-directory' (`-T') option is not given, `cp' copies + each SOURCE file to the specified directory, using the SOURCEs' + names. + + Generally, files are written just as they are read. For exceptions, +see the `--sparse' option below. + + By default, `cp' does not copy directories. However, the `-R', +`-a', and `-r' options cause `cp' to copy recursively by descending +into source directories and copying files to corresponding destination +directories. + + By default, `cp' follows symbolic links only when not copying +recursively. This default can be overridden with the `--archive' +(`-a'), `-d', `--dereference' (`-L'), `--no-dereference' (`-P'), and +`-H' options. If more than one of these options is specified, the last +one silently overrides the others. + + By default, `cp' copies the contents of special files only when not +copying recursively. This default can be overridden with the +`--copy-contents' option. + + `cp' generally refuses to copy a file onto itself, with the +following exception: if `--force --backup' is specified with SOURCE and +DEST identical, and referring to a regular file, `cp' will make a +backup file, either regular or numbered, as specified in the usual ways +(*note Backup options::). This is useful when you simply want to make +a backup of an existing file before changing it. + + The program accepts the following options. Also see *Note Common +options::. + +`-a' +`--archive' + Preserve as much as possible of the structure and attributes of the + original files in the copy (but do not attempt to preserve internal + directory structure; i.e., `ls -U' may list the entries in a copied + directory in a different order). Equivalent to `-dpPR'. + +`-b' +`--backup[=METHOD]' + *Note Backup options::. Make a backup of each file that would + otherwise be overwritten or removed. As a special case, `cp' + makes a backup of SOURCE when the force and backup options are + given and SOURCE and DEST are the same name for an existing, + regular file. One useful application of this combination of + options is this tiny Bourne shell script: + + #!/bin/sh + # Usage: backup FILE... + # Create a GNU-style backup of each listed FILE. + for i; do + cp --backup --force -- "$i" "$i" + done + +`--copy-contents' + If copying recursively, copy the contents of any special files + (e.g., FIFOs and device files) as if they were regular files. + This means trying to read the data in each source file and writing + it to the destination. It is usually a mistake to use this + option, as it normally has undesirable effects on special files + like FIFOs and the ones typically found in the `/dev' directory. + In most cases, `cp -R --copy-contents' will hang indefinitely + trying to read from FIFOs and special files like `/dev/console', + and it will fill up your destination disk if you use it to copy + `/dev/zero'. This option has no effect unless copying + recursively, and it does not affect the copying of symbolic links. + +`-d' + Copy symbolic links as symbolic links rather than copying the + files that they point to, and preserve hard links between source + files in the copies. Equivalent to `--no-dereference + --preserve=links'. + +`-f' +`--force' + When copying without this option and an existing destination file + cannot be opened for writing, the copy fails. However, with + `--force'), when a destination file cannot be opened, `cp' then + unlinks it and tries to open it again. Contrast this behavior + with that enabled by `--link' and `--symbolic-link', whereby the + destination file is never opened but rather is unlinked + unconditionally. Also see the description of + `--remove-destination'. + + This option is independent of the `--interactive' or `-i' option: + neither cancels the effect of the other. + +`-H' + If a command line argument specifies a symbolic link, then copy the + file it points to rather than the symbolic link itself. However, + copy (preserving its nature) any symbolic link that is encountered + via recursive traversal. + +`-i' +`--interactive' + When copying a file other than a directory, prompt whether to + overwrite an existing destination file. + +`-l' +`--link' + Make hard links instead of copies of non-directories. + +`-L' +`--dereference' + Always follow symbolic links. + +`-P' +`--no-dereference' + Copy symbolic links as symbolic links rather than copying the + files that they point to. + +`-p' +`--preserve[=ATTRIBUTE_LIST]' + Preserve the specified attributes of the original files. If + specified, the ATTRIBUTE_LIST must be a comma-separated list of + one or more of the following strings: + + `mode' + Preserve the file mode bits and access control lists. + + `ownership' + Preserve the owner and group. On most modern systems, only + users with appropriate privileges may change the owner of a + file, and ordinary users may preserve the group ownership of + a file only if they happen to be a member of the desired + group. + + `timestamps' + Preserve the times of last access and last modification, when + possible. In general, it is not possible to preserve these + attributes when the affected file is a symbolic link. + However, FreeBSD now provides the `lutimes' function, which + makes it possibile even for symbolic links. However, this + implementation does not yet take advantage of that. + + `links' + Preserve in the destination files any links between + corresponding source files. + + `all' + Preserve all file attributes. Equivalent to specifying all + of the above. + + Using `--preserve' with no ATTRIBUTE_LIST is equivalent to + `--preserve=mode,ownership,timestamps'. + + In the absence of this option, each destination file is created + with the mode bits of the corresponding source file, minus the + bits set in the umask and minus the set-user-ID and set-group-ID + bits. *Note File permissions::. + +`--no-preserve=ATTRIBUTE_LIST' + Do not preserve the specified attributes. The ATTRIBUTE_LIST has + the same form as for `--preserve'. + +`--parents' + Form the name of each destination file by appending to the target + directory a slash and the specified name of the source file. The + last argument given to `cp' must be the name of an existing + directory. For example, the command: + + cp --parents a/b/c existing_dir + + copies the file `a/b/c' to `existing_dir/a/b/c', creating any + missing intermediate directories. + +`--reply=HOW' + *Deprecated: to be removed in 2008.* + Using `--reply=yes' makes `cp' act as if `yes' were given as a + response to every prompt about a destination file. That + effectively cancels any preceding `--interactive' or `-i' option. + Specify `--reply=no' to make `cp' act as if `no' were given as a + response to every prompt about a destination file. Specify + `--reply=query' to make `cp' prompt the user about each existing + destination file. + +`-R' +`-r' +`--recursive' + Copy directories recursively. Symbolic links are not followed by + default; see the `--archive' (`-a'), `-d', `--dereference' (`-L'), + `--no-dereference' (`-P'), and `-H' options. Special files are + copied by creating a destination file of the same type as the + source; see the `--copy-contents' option. It is not portable to + use `-r' to copy symbolic links or special files. On some non-GNU + systems, `-r' implies the equivalent of `-L' and `--copy-contents' + for historical reasons. Also, it is not portable to use `-R' to + copy symbolic links unless you also specify `-P', as POSIX allows + implementations that dereference symbolic links by default. + +`--remove-destination' + Remove each existing destination file before attempting to open it + (contrast with `-f' above). + +`--sparse=WHEN' + A "sparse file" contains "holes"--a sequence of zero bytes that + does not occupy any physical disk blocks; the `read' system call + reads these as zeros. This can both save considerable disk space + and increase speed, since many binary files contain lots of + consecutive zero bytes. By default, `cp' detects holes in input + source files via a crude heuristic and makes the corresponding + output file sparse as well. Only regular files may be sparse. + + The WHEN value can be one of the following: + + `auto' + The default behavior: if the input file is sparse, attempt to + make the output file sparse, too. However, if an output file + exists but refers to a non-regular file, then do not attempt + to make it sparse. + + `always' + For each sufficiently long sequence of zero bytes in the + input file, attempt to create a corresponding hole in the + output file, even if the input file does not appear to be + sparse. This is useful when the input file resides on a file + system that does not support sparse files (for example, + `efs' file systems in SGI IRIX 5.3 and earlier), but the + output file is on a type of file system that does support + them. Holes may be created only in regular files, so if the + destination file is of some other type, `cp' does not even + try to make it sparse. + + `never' + Never make the output file sparse. This is useful in + creating a file for use with the `mkswap' command, since such + a file must not have any holes. + +`--strip-trailing-slashes' + Remove any trailing slashes from each SOURCE argument. *Note + Trailing slashes::. + +`-s' +`--symbolic-link' + Make symbolic links instead of copies of non-directories. All + source file names must be absolute (starting with `/') unless the + destination files are in the current directory. This option merely + results in an error message on systems that do not support + symbolic links. + +`-S SUFFIX' +`--suffix=SUFFIX' + Append SUFFIX to each backup file made with `-b'. *Note Backup + options::. + +`-t DIRECTORY' +`--target-directory=DIRECTORY' + Specify the destination DIRECTORY. *Note Target directory::. + +`-T' +`--no-target-directory' + Do not treat the last operand specially when it is a directory or a + symbolic link to a directory. *Note Target directory::. + +`-u' +`--update' + Do not copy a non-directory that has an existing destination with + the same or newer modification time. If time stamps are being + preserved, the comparison is to the source time stamp truncated to + the resolutions of the destination file system and of the system + calls used to update time stamps; this avoids duplicate work if + several `cp -pu' commands are executed with the same source and + destination. + +`-v' +`--verbose' + Print the name of each file before copying it. + +`-x' +`--one-file-system' + Skip subdirectories that are on different file systems from the + one that the copy started on. However, mount point directories + _are_ copied. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: dd invocation, Next: install invocation, Prev: cp invocation, Up: Basic operations + +11.2 `dd': Convert and copy a file +================================== + +`dd' copies a file (from standard input to standard output, by default) +with a changeable I/O block size, while optionally performing +conversions on it. Synopses: + + dd [OPERAND]... + dd OPTION + + The only options are `--help' and `--version'. *Note Common +options::. `dd' accepts the following operands. + +`if=FILE' + Read from FILE instead of standard input. + +`of=FILE' + Write to FILE instead of standard output. Unless `conv=notrunc' + is given, `dd' truncates FILE to zero bytes (or the size specified + with `seek='). + +`ibs=BYTES' + Set the input block size to BYTES. This makes `dd' read BYTES per + block. + +`obs=BYTES' + Set the output block size to BYTES. This makes `dd' write BYTES + per block. + +`bs=BYTES' + Set both input and output block sizes to BYTES. This makes `dd' + read and write BYTES per block, overriding any `ibs' and `obs' + settings. + +`cbs=BYTES' + Set the conversion block size to BYTES. When converting + variable-length records to fixed-length ones (`conv=block') or the + reverse (`conv=unblock'), use BYTES as the fixed record length. + +`skip=BLOCKS' + Skip BLOCKS `ibs'-byte blocks in the input file before copying. + +`seek=BLOCKS' + Skip BLOCKS `obs'-byte blocks in the output file before copying. + +`count=BLOCKS' + Copy BLOCKS `ibs'-byte blocks from the input file, instead of + everything until the end of the file. + +`conv=CONVERSION[,CONVERSION]...' + Convert the file as specified by the CONVERSION argument(s). (No + spaces around any comma(s).) + + Conversions: + + `ascii' + Convert EBCDIC to ASCII, using the conversion table specified + by POSIX. This provides a 1:1 translation for all 256 bytes. + + `ebcdic' + Convert ASCII to EBCDIC. This is the inverse of the `ascii' + conversion. + + `ibm' + Convert ASCII to alternate EBCDIC, using the alternate + conversion table specified by POSIX. This is not a 1:1 + translation, but reflects common historical practice for `~', + `[', and `]'. + + The `ascii', `ebcdic', and `ibm' conversions are mutually + exclusive. + + `block' + For each line in the input, output `cbs' bytes, replacing the + input newline with a space and padding with spaces as + necessary. + + `unblock' + Replace trailing spaces in each `cbs'-sized input block with a + newline. + + The `block' and `unblock' conversions are mutually exclusive. + + `lcase' + Change uppercase letters to lowercase. + + `ucase' + Change lowercase letters to uppercase. + + The `lcase' and `ucase' conversions are mutually exclusive. + + `swab' + Swap every pair of input bytes. GNU `dd', unlike others, + works when an odd number of bytes are read--the last byte is + simply copied (since there is nothing to swap it with). + + `noerror' + Continue after read errors. + + `nocreat' + Do not create the output file; the output file must already + exist. + + `excl' + Fail if the output file already exists; `dd' must create the + output file itself. + + The `excl' and `nocreat' conversions are mutually exclusive. + + `notrunc' + Do not truncate the output file. + + `sync' + Pad every input block to size of `ibs' with trailing zero + bytes. When used with `block' or `unblock', pad with spaces + instead of zero bytes. + + `fdatasync' + Synchronize output data just before finishing. This forces a + physical write of output data. + + `fsync' + Synchronize output data and metadata just before finishing. + This forces a physical write of output data and metadata. + + +`iflag=FLAG[,FLAG]...' + Access the input file using the flags specified by the FLAG + argument(s). (No spaces around any comma(s).) + +`oflag=FLAG[,FLAG]...' + Access the output file using the flags specified by the FLAG + argument(s). (No spaces around any comma(s).) + + Here are the flags. Not every flag is supported on every operating + system. + + `append' + Write in append mode, so that even if some other process is + writing to this file, every `dd' write will append to the + current contents of the file. This flag makes sense only for + output. If you combine this flag with the `of=FILE' operand, + you should also specify `conv=notrunc' unless you want the + output file to be truncated before being appended to. + + `direct' + Use direct I/O for data, avoiding the buffer cache. + + `directory' + Fail unless the file is a directory. Most operating systems + do not allow I/O to a directory, so this flag has limited + utility. + + `dsync' + Use synchronized I/O for data. For the output file, this + forces a physical write of output data on each write. For + the input file, this flag can matter when reading from a + remote file that has been written to synchronously by some + other process. Metadata (e.g., last-access and last-modified + time) is not necessarily synchronized. + + `sync' + Use synchronized I/O for both data and metadata. + + `nonblock' + Use non-blocking I/O. + + `noatime' + Do not update the file's access time. Some older file + systems silently ignore this flag, so it is a good idea to + test it on your files before relying on it. + + `noctty' + Do not assign the file to be a controlling terminal for `dd'. + This has no effect when the file is not a terminal. On many + hosts (e.g., GNU/Linux hosts), this option has no effect at + all. + + `nofollow' + Do not follow symbolic links. + + `nolinks' + Fail if the file has multiple hard links. + + `binary' + Use binary I/O. This option has an effect only on nonstandard + platforms that distinguish binary from text I/O. + + `text' + Use text I/O. Like `binary', this option has no effect on + standard platforms. + + + These flags are not supported on all systems, and `dd' rejects + attempts to use them when they are not supported. When reading + from standard input or writing to standard output, the `nofollow' + and `noctty' flags should not be specified, and the other flags + (e.g., `nonblock') can affect how other processes behave with the + affected file descriptors, even after `dd' exits. + + + The numeric-valued strings above (BYTES and BLOCKS) can be followed +by a multiplier: `b'=512, `c'=1, `w'=2, `xM'=M, or any of the standard +block size suffixes like `k'=1024 (*note Block size::). + + Use different `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 4 KiB label at the start of the disk: + + disk=/dev/rdsk/c0t1d0s2 + tape=/dev/rmt/0 + + # Copy all but the label from disk to tape. + (dd bs=4k skip=1 count=0 && dd bs=512k) <$disk >$tape + + # Copy from tape back to disk, but leave the disk label alone. + (dd bs=4k seek=1 count=0 && dd bs=512k) <$tape >$disk + + Sending an `INFO' signal to a running `dd' process makes it print +I/O statistics to standard error and then resume copying. In the +example below, `dd' is run in the background to copy 10 million blocks. +The `kill' command makes it output intermediate I/O statistics, and +when `dd' completes, it outputs the final statistics. + + $ dd if=/dev/zero of=/dev/null count=10MB & pid=$! + $ kill -s INFO $pid; wait $pid + 3385223+0 records in + 3385223+0 records out + 1733234176 bytes (1.7 GB) copied, 6.42173 seconds, 270 MB/s + 10000000+0 records in + 10000000+0 records out + 5120000000 bytes (5.1 GB) copied, 18.913 seconds, 271 MB/s + + On systems lacking the `INFO' signal `dd' responds to the `USR1' +signal instead, unless the `POSIXLY_CORRECT' environment variable is +set. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: install invocation, Next: mv invocation, Prev: dd invocation, Up: Basic operations + +11.3 `install': Copy files and set attributes +============================================= + +`install' copies files while setting their file mode bits and, if +possible, their owner and group. Synopses: + + install [OPTION]... [-T] SOURCE DEST + install [OPTION]... SOURCE... DIRECTORY + install [OPTION]... -t DIRECTORY SOURCE... + install [OPTION]... -d DIRECTORY... + + * If two file names are given, `install' copies the first file to the + second. + + * If the `--target-directory' (`-t') option is given, or failing + that if the last file is a directory and the + `--no-target-directory' (`-T') option is not given, `install' + copies each SOURCE file to the specified directory, using the + SOURCEs' names. + + * If the `--directory' (`-d') option is given, `install' creates + each DIRECTORY and any missing parent directories. Parent + directories are created with mode `u=rwx,go=rx' (755), regardless + of the `-m' option or the current umask. *Note Directory Setuid + and Setgid::, for how the set-user-ID and set-group-ID bits of + parent directories are inherited. + + `install' is similar to `cp', but allows you to control the +attributes of destination files. It is typically used in Makefiles to +copy programs into their destination directories. It refuses to copy +files onto themselves. + + The program accepts the following options. Also see *Note Common +options::. + +`-b' +`--backup[=METHOD]' + *Note Backup options::. Make a backup of each file that would + otherwise be overwritten or removed. + +`-c' + Ignored; for compatibility with old Unix versions of `install'. + +`-d' +`--directory' + Create any missing parent directories, giving them the default + attributes. Then create each given directory, setting their owner, + group and mode as given on the command line or to the defaults. + +`-g GROUP' +`--group=GROUP' + Set the group ownership of installed files or directories to + GROUP. The default is the process's current group. GROUP may be + either a group name or a numeric group ID. + +`-m MODE' +`--mode=MODE' + Set the file mode bits for the installed file or directory to MODE, + which can be either an octal number, or a symbolic mode as in + `chmod', with `a=' (no access allowed to anyone) as the point of + departure (*note File permissions::). The default mode is + `u=rwx,go=rx,a-s'--read, write, and execute for the owner, read + and execute for group and other, and with set-user-ID and + set-group-ID disabled. This default is not quite the same as + `755', since it disables instead of preserving set-user-ID and + set-group-ID on directories. *Note Directory Setuid and Setgid::. + +`-o OWNER' +`--owner=OWNER' + If `install' has appropriate privileges (is run as root), set the + ownership of installed files or directories to OWNER. The default + is `root'. OWNER may be either a user name or a numeric user ID. + +`-p' +`--preserve-timestamps' + Set the time of last access and the time of last modification of + each installed file to match those of each corresponding original + file. When a file is installed without this option, its last + access and last modification times are both set to the time of + installation. This option is useful if you want to use the last + modification times of installed files to keep track of when they + were last built as opposed to when they were last installed. + +`-s' +`--strip' + Strip the symbol tables from installed binary executables. + +`-S SUFFIX' +`--suffix=SUFFIX' + Append SUFFIX to each backup file made with `-b'. *Note Backup + options::. + +`-t DIRECTORY' +`--target-directory=DIRECTORY' + Specify the destination DIRECTORY. *Note Target directory::. + +`-T' +`--no-target-directory' + Do not treat the last operand specially when it is a directory or a + symbolic link to a directory. *Note Target directory::. + +`-v' +`--verbose' + Print the name of each file before copying it. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: mv invocation, Next: rm invocation, Prev: install invocation, Up: Basic operations + +11.4 `mv': Move (rename) files +============================== + +`mv' moves or renames files (or directories). Synopses: + + mv [OPTION]... [-T] SOURCE DEST + mv [OPTION]... SOURCE... DIRECTORY + mv [OPTION]... -t DIRECTORY SOURCE... + + * If two file names are given, `mv' moves the first file to the + second. + + * If the `--target-directory' (`-t') option is given, or failing + that if the last file is a directory and the + `--no-target-directory' (`-T') option is not given, `mv' moves + each SOURCE file to the specified directory, using the SOURCEs' + names. + + `mv' can move any type of file from one file system to another. +Prior to version `4.0' of the fileutils, `mv' could move only regular +files between file systems. For example, now `mv' can move an entire +directory hierarchy including special device files from one partition +to another. It first uses some of the same code that's used by `cp -a' +to copy the requested directories and files, then (assuming the copy +succeeded) it removes the originals. If the copy fails, then the part +that was copied to the destination partition is removed. If you were +to copy three directories from one partition to another and the copy of +the first directory succeeded, but the second didn't, the first would +be left on the destination partition and the second and third would be +left on the original partition. + + If a destination file exists but is normally unwritable, standard +input is a terminal, and the `-f' or `--force' option is not given, +`mv' prompts the user for whether to replace the file. (You might own +the file, or have write permission on its directory.) If the response +is not affirmative, the file is skipped. + + _Warning_: If you try to move a symlink that points to a directory, +and you specify the symlink with a trailing slash, then `mv' doesn't +move the symlink but instead moves the directory referenced by the +symlink. *Note Trailing slashes::. + + The program accepts the following options. Also see *Note Common +options::. + +`-b' +`--backup[=METHOD]' + *Note Backup options::. Make a backup of each file that would + otherwise be overwritten or removed. + +`-f' +`--force' + Do not prompt the user before removing a destination file. + +`-i' +`--interactive' + Prompt whether to overwrite each existing destination file, + regardless of its permissions. If the response is not + affirmative, the file is skipped. + +`--reply=HOW' + *Deprecated: to be removed in 2008.* + Specifying `--reply=yes' is equivalent to using `--force'. + Specify `--reply=no' to make `mv' act as if `no' were given as a + response to every prompt about a destination file. Specify + `--reply=query' to make `mv' prompt the user about each existing + destination file. Note that `--reply=no' has an effect only when + `mv' would prompt without `-i' or equivalent, i.e., when a + destination file exists and is not writable, standard input is a + terminal, and no `-f' (or equivalent) option is specified. + +`-u' +`--update' + Do not move a non-directory that has an existing destination with + the same or newer modification time. If the move is across file + system boundaries, the comparison is to the source time stamp + truncated to the resolutions of the destination file system and of + the system calls used to update time stamps; this avoids duplicate + work if several `mv -u' commands are executed with the same source + and destination. + +`-v' +`--verbose' + Print the name of each file before moving it. + +`--strip-trailing-slashes' + Remove any trailing slashes from each SOURCE argument. *Note + Trailing slashes::. + +`-S SUFFIX' +`--suffix=SUFFIX' + Append SUFFIX to each backup file made with `-b'. *Note Backup + options::. + +`-t DIRECTORY' +`--target-directory=DIRECTORY' + Specify the destination DIRECTORY. *Note Target directory::. + +`-T' +`--no-target-directory' + Do not treat the last operand specially when it is a directory or a + symbolic link to a directory. *Note Target directory::. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: rm invocation, Next: shred invocation, Prev: mv invocation, Up: Basic operations + +11.5 `rm': Remove files or directories +====================================== + +`rm' removes each given FILE. By default, it does not remove +directories. Synopsis: + + rm [OPTION]... [FILE]... + + If the `-I' or `--interactive=once' option is given, and there are +more than three files or the `-r', `-R', or `--recursive' are given, +then `rm' prompts the user for whether to proceed with the entire +operation. If the response is not affirmative, the entire command is +aborted. + + Otherwise, if a file is unwritable, standard input is a terminal, and +the `-f' or `--force' option is not given, or the `-i' or +`--interactive=always' option _is_ given, `rm' prompts the user for +whether to remove the file. If the response is not affirmative, the +file is skipped. + + Any attempt to remove a file whose last file name component is `.' +or `..' is rejected without any prompting. + + _Warning_: If you use `rm' to remove a file, it is usually possible +to recover the contents of that file. If you want more assurance that +the contents are truly unrecoverable, consider using `shred'. + + The program accepts the following options. Also see *Note Common +options::. + +`-f' +`--force' + Ignore nonexistent files and never prompt the user. Ignore any + previous `--interactive' (`-i') option. + +`-i' + Prompt whether to remove each file. If the response is not + affirmative, the file is skipped. Ignore any previous `--force' + (`-f') option. Equivalent to `--interactive=always'. + +`-I' + Prompt once whether to proceed with the command, if more than three + files are named or if a recursive removal is requested. Ignore any + previous `--force' (`-f') option. Equivalent to + `--interactive=once'. + +`--interactive [=WHEN]' + Specify when to issue an interactive prompt. WHEN may be omitted, + or one of: + * never - Do not prompt at all. + + * once - Prompt once if more than three files are named or if a + recursive removal is requested. Equivalent to `-I'. + + * always - Prompt for every file being removed. Equivalent to + `-i'. + Specifying `--interactive' and no WHEN is equivalent to + `--interactive=always'. + +`--one-file-system' + When removing a hierarchy recursively, skip any directory that is + on a file system different from that of the corresponding command + line argument. + + This option is useful when removing a build "chroot" hierarchy, + which normally contains no valuable data. However, it is not + uncommon to bind-mount `/home' into such a hierarchy, to make it + easier to use one's start-up file. The catch is that it's easy to + forget to unmount `/home'. Then, when you use `rm -rf' to remove + your normally throw-away chroot, that command will remove + everything under `/home', too. Use the `--one-file-system' + option, and it will warn about and skip directories on other file + systems. Of course, this will not save your `/home' if it and your + chroot happen to be on the same file system. + +`--preserve-root' + Fail upon any attempt to remove the root directory, `/', when used + with the `--recursive' option. This is the default behavior. + *Note Treating / specially::. + +`--no-preserve-root' + Do not treat `/' specially when removing recursively. This option + is not recommended unless you really want to remove all the files + on your computer. *Note Treating / specially::. + +`-r' +`-R' +`--recursive' + Remove the listed directories and their contents recursively. + +`-v' +`--verbose' + Print the name of each file before removing it. + + + One common question is how to remove files whose names begin with a +`-'. GNU `rm', like every program that uses the `getopt' function to +parse its arguments, lets you use the `--' option to indicate that all +following arguments are non-options. To remove a file called `-f' in +the current directory, you could type either: + + rm -- -f + +or: + + rm ./-f + + The Unix `rm' program's use of a single `-' for this purpose +predates the development of the getopt standard syntax. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: shred invocation, Prev: rm invocation, Up: Basic operations + +11.6 `shred': Remove files more securely +======================================== + +`shred' overwrites devices or files, to help prevent even very +expensive hardware from recovering the data. + + Ordinarily when you remove a file (*note rm invocation::), the data +is not actually destroyed. Only the index listing where the file is +stored is destroyed, and the storage is made available for reuse. +There are undelete utilities that will attempt to reconstruct the index +and can bring the file back if the parts were not reused. + + On a busy system with a nearly-full drive, space can get reused in a +few seconds. But there is no way to know for sure. If you have +sensitive data, you may want to be sure that recovery is not possible +by actually overwriting the file with non-sensitive data. + + However, even after doing that, it is possible to take the disk back +to a laboratory and use a lot of sensitive (and expensive) equipment to +look for the faint "echoes" of the original data underneath the +overwritten data. If the data has only been overwritten once, it's not +even that hard. + + The best way to remove something irretrievably is to destroy the +media it's on with acid, melt it down, or the like. For cheap +removable media like floppy disks, this is the preferred method. +However, hard drives are expensive and hard to melt, so the `shred' +utility tries to achieve a similar effect non-destructively. + + This uses many overwrite passes, with the data patterns chosen to +maximize the damage they do to the old data. While this will work on +floppies, the patterns are designed for best effect on hard drives. +For more details, see the source code and Peter Gutmann's paper `Secure +Deletion of Data from Magnetic and Solid-State Memory' +(http://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html), from the +proceedings of the Sixth USENIX Security Symposium (San Jose, +California, July 22-25, 1996). + + *Please note* that `shred' relies on a very important assumption: +that the file system overwrites data in place. This is the traditional +way to do things, but many modern file system designs do not satisfy +this assumption. Exceptions include: + + * Log-structured or journaled file systems, such as those supplied + with AIX and Solaris, and JFS, ReiserFS, XFS, Ext3 (in + `data=journal' mode), BFS, NTFS, etc. when they are configured to + journal _data_. + + * File systems that write redundant data and carry on even if some + writes fail, such as RAID-based file systems. + + * File systems that make snapshots, such as Network Appliance's NFS + server. + + * File systems that cache in temporary locations, such as NFS + version 3 clients. + + * Compressed file systems. + + In the particular case of ext3 file systems, the above disclaimer +applies (and `shred' is thus of limited effectiveness) only in +`data=journal' mode, which journals file data in addition to just +metadata. In both the `data=ordered' (default) and `data=writeback' +modes, `shred' works as usual. Ext3 journaling modes can be changed by +adding the `data=something' option to the mount options for a +particular file system in the `/etc/fstab' file, as documented in the +mount man page (man mount). + + If you are not sure how your file system operates, then you should +assume that it does not overwrite data in place, which means that shred +cannot reliably operate on regular files in your file system. + + Generally speaking, it is more reliable to shred a device than a +file, since this bypasses the problem of file system design mentioned +above. However, even shredding devices is not always completely +reliable. For example, most disks map out bad sectors invisibly to the +application; if the bad sectors contain sensitive data, `shred' won't +be able to destroy it. + + `shred' makes no attempt to detect or report this problem, just as +it makes no attempt to do anything about backups. However, since it is +more reliable to shred devices than files, `shred' by default does not +truncate or remove the output file. This default is more suitable for +devices, which typically cannot be truncated and should not be removed. + + Finally, consider the risk of backups and mirrors. File system +backups and remote mirrors may contain copies of the file that cannot +be removed, and that will allow a shredded file to be recovered later. +So if you keep any data you may later want to destroy using `shred', be +sure that it is not backed up or mirrored. + + shred [OPTION]... FILE[...] + + The program accepts the following options. Also see *Note Common +options::. + +`-f' +`--force' + Override file permissions if necessary to allow overwriting. + +`-NUMBER' +`-n NUMBER' +`--iterations=NUMBER' + By default, `shred' uses 25 passes of overwrite. This is enough + for all of the useful overwrite patterns to be used at least once. + You can reduce this to save time, or increase it if you have a lot + of time to waste. + +`--random-source=FILE' + Use FILE as a source of random data used to overwrite and to + choose pass ordering. *Note Random sources::. + +`-s BYTES' +`--size=BYTES' + Shred the first BYTES bytes of the file. The default is to shred + the whole file. BYTES can be followed by a size specification like + `K', `M', or `G' to specify a multiple. *Note Block size::. + +`-u' +`--remove' + After shredding a file, truncate it (if possible) and then remove + it. If a file has multiple links, only the named links will be + removed. + +`-v' +`--verbose' + Display status updates as sterilization proceeds. + +`-x' +`--exact' + By default, `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. Use `--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 does not increase the apparent size of the + file. + +`-z' +`--zero' + Normally, the last pass that `shred' writes is made up of random + data. If this would be conspicuous on your hard drive (for + example, because it looks like encrypted data), or you just think + it's tidier, the `--zero' option adds an additional overwrite pass + with all zero bits. This is in addition to the number of passes + specified by the `--iterations' option. + + + You might use the following command to erase all trace of the file +system you'd created on the floppy disk in your first drive. That +command takes about 20 minutes to erase a "1.44MB" (actually 1440 KiB) +floppy. + + shred --verbose /dev/fd0 + + Similarly, to erase all data on a selected partition of your hard +disk, you could give a command like this: + + shred --verbose /dev/sda5 + + A FILE of `-' denotes standard output. The intended use of this is +to shred a removed temporary file. For example: + + i=`tempfile -m 0600` + exec 3<>"$i" + rm -- "$i" + echo "Hello, world" >&3 + shred - >&3 + exec 3>- + + However, the command `shred - >file' does not shred the contents of +FILE, since the shell truncates FILE before invoking `shred'. Use the +command `shred file' or (if using a Bourne-compatible shell) the +command `shred - 1<>file' instead. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Special file types, Next: Changing file attributes, Prev: Basic operations, Up: Top + +12 Special file types +********************* + +This chapter describes commands which create special types of files (and +`rmdir', which removes directories, one special file type). + + Although Unix-like operating systems have markedly fewer special file +types than others, not _everything_ can be treated only as the +undifferentiated byte stream of "normal files". For example, when a +file is created or removed, the system must record this information, +which it does in a "directory"--a special type of file. Although you +can read directories as normal files, if you're curious, in order for +the system to do its job it must impose a structure, a certain order, +on the bytes of the file. Thus it is a "special" type of file. + + Besides directories, other special file types include named pipes +(FIFOs), symbolic links, sockets, and so-called "special files". + +* Menu: + +* 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 the referent of a symbolic link. +* rmdir invocation:: Remove empty directories. +* unlink invocation:: Remove files via the unlink syscall + + +File: coreutils.info, Node: link invocation, Next: ln invocation, Up: Special file types + +12.1 `link': Make a hard link via the link syscall +================================================== + +`link' creates a single hard link at a time. It is a minimalist +interface to the system-provided `link' function. *Note Hard Links: +(libc)Hard Links. It avoids the bells and whistles of the more +commonly-used `ln' command (*note ln invocation::). Synopsis: + + link FILENAME LINKNAME + + FILENAME must specify an existing file, and LINKNAME must specify a +nonexistent entry in an existing directory. `link' simply calls `link +(FILENAME, LINKNAME)' to create the link. + + On a GNU system, this command acts like `ln --directory +--no-target-directory FILENAME LINKNAME'. However, the `--directory' +and `--no-target-directory' options are not specified by POSIX, and the +`link' command is more portable in practice. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: ln invocation, Next: mkdir invocation, Prev: link invocation, Up: Special file types + +12.2 `ln': Make links between files +=================================== + +`ln' makes links between files. By default, it makes hard links; with +the `-s' option, it makes symbolic (or "soft") links. Synopses: + + ln [OPTION]... [-T] TARGET LINKNAME + ln [OPTION]... TARGET + ln [OPTION]... TARGET... DIRECTORY + ln [OPTION]... -t DIRECTORY TARGET... + + * If two file names are given, `ln' creates a link to the first file + from the second. + + * If one TARGET is given, `ln' creates a link to that file in the + current directory. + + * If the `--target-directory' (`-t') option is given, or failing + that if the last file is a directory and the + `--no-target-directory' (`-T') option is not given, `ln' creates a + link to each TARGET file in the specified directory, using the + TARGETs' names. + + + Normally `ln' does not remove existing files. Use the `--force' +(`-f') option to remove them unconditionally, the `--interactive' +(`-i') option to remove them conditionally, and the `--backup' (`-b') +option to rename them. + + A "hard link" is another name for an existing file; the link and the +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 _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 +restrictions are not mandated by POSIX, however.) + + "Symbolic links" ("symlinks" for short), on the other hand, are a +special file type (which not all kernels support: System V release 3 +(and older) systems lack symlinks) in which the link file actually +refers to a different file, by name. When most operations (opening, +reading, writing, and so on) are passed the symbolic link file, the +kernel automatically "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. *Note Symbolic Links: +(libc)Symbolic Links. + + The program accepts the following options. Also see *Note Common +options::. + +`-b' +`--backup[=METHOD]' + *Note Backup options::. Make a backup of each file that would + otherwise be overwritten or removed. + +`-d' +`-F' +`--directory' + Allow users with appropriate privileges to attempt to make hard + links to directories. However, note that this will probably fail + due to system restrictions, even for the super-user. + +`-f' +`--force' + Remove existing destination files. + +`-i' +`--interactive' + Prompt whether to remove existing destination files. + +`-n' +`--no-dereference' + Do not treat the last operand specially when it is a symbolic link + to a directory. Instead, treat it as if it were a normal file. + + When the destination is an actual directory (not a symlink to one), + there is no ambiguity. The link is created in that directory. + But when the specified destination is a symlink to a directory, + there are two ways to treat the user's request. `ln' can treat + the destination just as it would a normal directory and create the + link in it. On the other hand, the destination can be viewed as a + non-directory--as the symlink itself. In that case, `ln' must + delete or backup that symlink before creating the new link. The + default is to treat a destination that is a symlink to a directory + just like a directory. + + This option is weaker than the `--no-target-directory' (`-T') + option, so it has no effect if both options are given. + +`-s' +`--symbolic' + Make symbolic links instead of hard links. This option merely + produces an error message on systems that do not support symbolic + links. + +`-S SUFFIX' +`--suffix=SUFFIX' + Append SUFFIX to each backup file made with `-b'. *Note Backup + options::. + +`-t DIRECTORY' +`--target-directory=DIRECTORY' + Specify the destination DIRECTORY. *Note Target directory::. + +`-T' +`--no-target-directory' + Do not treat the last operand specially when it is a directory or a + symbolic link to a directory. *Note Target directory::. + +`-v' +`--verbose' + Print the name of each file after linking it successfully. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + Examples: + + Bad Example: + + # Create link ../a pointing to a in that directory. + # Not really useful because it points to itself. + ln -s a .. + + Better Example: + + # Change to the target before creating symlinks to avoid being confused. + cd .. + ln -s adir/a . + + Bad Example: + + # Hard coded file names don't move well. + ln -s $(pwd)/a /some/dir/ + + Better Example: + + # Relative file names survive directory moves and also + # work across networked file systems. + ln -s afile anotherfile + ln -s ../adir/afile yetanotherfile + + +File: coreutils.info, Node: mkdir invocation, Next: mkfifo invocation, Prev: ln invocation, Up: Special file types + +12.3 `mkdir': Make directories +============================== + +`mkdir' creates directories with the specified names. Synopsis: + + mkdir [OPTION]... NAME... + + `mkdir' creates each directory NAME in the order given. It reports +an error if NAME already exists, unless the `-p' option is given and +NAME is a directory. + + The program accepts the following options. Also see *Note Common +options::. + +`-m MODE' +`--mode=MODE' + Set the file permission bits of created directories to MODE, which + uses the same syntax as in `chmod' and uses `a=rwx' (read, write + and execute allowed for everyone) for the point of the departure. + *Note File permissions::. + + Normally the directory has the desired file mode bits at the + moment it is created. As a GNU extension, MODE may also mention + special mode bits, but in this case there may be a temporary window + during which the directory exists but its special mode bits are + incorrect. *Note Directory Setuid and Setgid::, for how the + set-user-ID and set-group-ID bits of directories are inherited + unless overridden in this way. + +`-p' +`--parents' + Make any missing parent directories for each argument, setting + their file permission bits to the umask modified by `u+wx'. Ignore + existing parent directories, and do not change their file + permission bits. + + To set the file permission bits of any newly-created parent + directories to a value that includes `u+wx', you can set the umask + before invoking `mkdir'. For example, if the shell command + `(umask u=rwx,go=rx; mkdir -p P/Q)' creates the parent `P' it sets + the parent's permission bits to `u=rwx,go=rx'. To set a parent's + special mode bits as well, you can invoke `chmod' after `mkdir'. + *Note Directory Setuid and Setgid::, for how the set-user-ID and + set-group-ID bits of newly-created parent directories are + inherited. + +`-v' +`--verbose' + Print a message for each created directory. This is most useful + with `--parents'. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: mkfifo invocation, Next: mknod invocation, Prev: mkdir invocation, Up: Special file types + +12.4 `mkfifo': Make FIFOs (named pipes) +======================================= + +`mkfifo' creates FIFOs (also called "named pipes") with the specified +names. Synopsis: + + mkfifo [OPTION] NAME... + + A "FIFO" is a special file type that permits independent processes +to communicate. One process opens the FIFO file for writing, and +another for reading, after which data can flow as with the usual +anonymous pipe in shells or elsewhere. + + The program accepts the following option. Also see *Note Common +options::. + +`-m MODE' +`--mode=MODE' + Set the mode of created FIFOs to MODE, which is symbolic as in + `chmod' and uses `a=rw' (read and write allowed for everyone) for + the point of departure. MODE should specify only file permission + bits. *Note File permissions::. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: mknod invocation, Next: readlink invocation, Prev: mkfifo invocation, Up: Special file types + +12.5 `mknod': Make block or character special files +=================================================== + +`mknod' creates a FIFO, character special file, or block special file +with the specified name. Synopsis: + + mknod [OPTION]... NAME TYPE [MAJOR MINOR] + + Unlike the phrase "special file type" above, the term "special file" +has a technical meaning on Unix: something that can generate or receive +data. Usually this corresponds to a physical piece of hardware, e.g., +a printer or a disk. (These files are typically created at +system-configuration time.) The `mknod' command is what creates files +of this type. Such devices can be read either a character at a time or +a "block" (many characters) at a time, hence we say there are "block +special" files and "character special" files. + + The arguments after NAME specify the type of file to make: + +`p' + for a FIFO + +`b' + for a block special file + +`c' + for a character special file + + + When making a block or character special file, the major and minor +device numbers must be given after the file type. If a major or minor +device number begins with `0x' or `0X', it is interpreted as +hexadecimal; otherwise, if it begins with `0', as octal; otherwise, as +decimal. + + The program accepts the following option. Also see *Note Common +options::. + +`-m MODE' +`--mode=MODE' + Set the mode of created files to MODE, which is symbolic as in + `chmod' and uses `a=rw' as the point of departure. MODE should + specify only file permission bits. *Note File permissions::. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: readlink invocation, Next: rmdir invocation, Prev: mknod invocation, Up: Special file types + +12.6 `readlink': Print the referent of a symbolic link +====================================================== + +`readlink' may work in one of two supported modes: + +`Readlink mode' + `readlink' outputs the value of the given symbolic link. If + `readlink' is invoked with an argument other than the name of a + symbolic link, it produces no output and exits with a nonzero exit + code. + +`Canonicalize mode' + `readlink' outputs the absolute name of the given file which + contains no `.', `..' components nor any repeated separators (`/') + or symbolic links. + + + readlink [OPTION] FILE + + By default, `readlink' operates in readlink mode. + + The program accepts the following options. Also see *Note Common +options::. + +`-f' +`--canonicalize' + Activate canonicalize mode. If any component of the file name + except the last one is missing or unavailable, `readlink' produces + no output and exits with a nonzero exit code. + +`-e' +`--canonicalize-existing' + Activate canonicalize mode. If any component is missing or + unavailable, `readlink' produces no output and exits with a + nonzero exit code. + +`-m' +`--canonicalize-missing' + Activate canonicalize mode. If any component is missing or + unavailable, `readlink' treats it as a directory. + +`-n' +`--no-newline' + Do not output the trailing newline. + +`-s' +`-q' +`--silent' +`--quiet' + Suppress most error messages. + +`-v' +`--verbose' + Report error messages. + + + The `readlink' utility first appeared in OpenBSD 2.1. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: rmdir invocation, Next: unlink invocation, Prev: readlink invocation, Up: Special file types + +12.7 `rmdir': Remove empty directories +====================================== + +`rmdir' removes empty directories. Synopsis: + + rmdir [OPTION]... DIRECTORY... + + If any DIRECTORY argument does not refer to an existing empty +directory, it is an error. + + The program accepts the following option. Also see *Note Common +options::. + +`--ignore-fail-on-non-empty' + Ignore each failure to remove a directory that is solely because + the directory is non-empty. + +`-p' +`--parents' + Remove DIRECTORY, then try to remove each component of DIRECTORY. + So, for example, `rmdir -p a/b/c' is similar to `rmdir a/b/c a/b + a'. As such, it fails if any of those directories turns out not + to be empty. Use the `--ignore-fail-on-non-empty' option to make + it so such a failure does not evoke a diagnostic and does not + cause `rmdir' to exit unsuccessfully. + +`-v' +`--verbose' + Give a diagnostic for each successful removal. DIRECTORY is + removed. + + + *Note rm invocation::, for how to remove non-empty directories +(recursively). + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: unlink invocation, Prev: rmdir invocation, Up: Special file types + +12.8 `unlink': Remove files via the unlink syscall +================================================== + +`unlink' deletes a single specified file name. It is a minimalist +interface to the system-provided `unlink' function. *Note Deleting +Files: (libc)Deleting Files. Synopsis: It avoids the bells and +whistles of the more commonly-used `rm' command (*note rm invocation::). + + unlink FILENAME + + On some systems `unlink' can be used to delete the name of a +directory. On others, it can be used that way only by a privileged +user. In the GNU system `unlink' can never delete the name of a +directory. + + The `unlink' command honors the `--help' and `--version' options. +To remove a file whose name begins with `-', prefix the name with `./', +e.g., `unlink ./--help'. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Changing file attributes, Next: Disk usage, Prev: Special file types, Up: Top + +13 Changing file attributes +*************************** + +A file is not merely its contents, a name, and a file type (*note +Special file types::). A file also has an owner (a user ID), a group +(a group ID), permissions (what the owner can do with the file, what +people in the group can do, and what everyone else can do), various +timestamps, and other information. Collectively, we call these a file's +"attributes". + + These commands change file attributes. + +* Menu: + +* chgrp invocation:: Change file groups. +* chmod invocation:: Change access permissions. +* chown invocation:: Change file owners and groups. +* touch invocation:: Change file timestamps. + + +File: coreutils.info, Node: chown invocation, Next: touch invocation, Prev: chmod invocation, Up: Changing file attributes + +13.1 `chown': Change file owner and group +========================================= + +`chown' changes the user and/or group ownership of each given FILE to +NEW-OWNER or to the user and group of an existing reference file. +Synopsis: + + chown [OPTION]... {NEW-OWNER | --reference=REF_FILE} FILE... + + If used, NEW-OWNER specifies the new owner and/or group as follows +(with no embedded white space): + + [OWNER] [ : [GROUP] ] + + Specifically: + +OWNER + If only an OWNER (a user name or numeric user ID) is given, that + user is made the owner of each given file, and the files' group is + not changed. + +OWNER`:'GROUP + If the OWNER is followed by a colon and a GROUP (a group name or + numeric group ID), with no spaces between them, the group + ownership of the files is changed as well (to GROUP). + +OWNER`:' + If a colon but no group name follows OWNER, that user is made the + owner of the files and the group of the files is changed to + OWNER's login group. + +`:'GROUP + If the colon and following GROUP are given, but the owner is + omitted, only the group of the files is changed; in this case, + `chown' performs the same function as `chgrp'. + +`:' + If only a colon is given, or if NEW-OWNER is empty, neither the + owner nor the group is changed. + + + If OWNER or GROUP is intended to represent a numeric user or group +ID, then you may specify it with a leading `+'. *Note Disambiguating +names and IDs::. + + Some older scripts may still use `.' in place of the `:' separator. +POSIX 1003.1-2001 (*note Standards conformance::) does not require +support for that, but for backward compatibility GNU `chown' supports +`.' so long as no ambiguity results. New scripts should avoid the use +of `.' because it is not portable, and because it has undesirable +results if the entire OWNER`.'GROUP happens to identify a user whose +name contains `.'. + + The `chown' command sometimes clears the set-user-ID or set-group-ID +permission bits. This behavior depends on the policy and functionality +of the underlying `chown' system call, which may make system-dependent +file mode modifications outside the control of the `chown' command. +For example, the `chown' command might not affect those bits when +invoked by a user with appropriate privileges, or when the bits signify +some function other than executable permission (e.g., mandatory +locking). When in doubt, check the underlying system behavior. + + The program accepts the following options. Also see *Note Common +options::. + +`-c' +`--changes' + Verbosely describe the action for each FILE whose ownership + actually changes. + +`-f' +`--silent' +`--quiet' + Do not print error messages about files whose ownership cannot be + changed. + +`--from=OLD-OWNER' + Change a FILE's ownership only if it has current attributes + specified by OLD-OWNER. OLD-OWNER has the same form as NEW-OWNER + described above. This option is useful primarily from a security + standpoint in that it narrows considerably the window of potential + abuse. For example, to reflect a user ID numbering change for one + user's files without an option like this, `root' might run + + find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER + + But that is dangerous because the interval between when the `find' + tests the existing file's owner and when the `chown' is actually + run may be quite large. One way to narrow the gap would be to + invoke chown for each file as it is found: + + find / -owner OLDUSER -exec chown -h NEWUSER {} \; + + But that is very slow if there are many affected files. With this + option, it is safer (the gap is narrower still) though still not + perfect: + + chown -h -R --from=OLDUSER NEWUSER / + +`--dereference' + Do not act on symbolic links themselves but rather on what they + point to. This is the default. + +`-h' +`--no-dereference' + Act on symbolic links themselves instead of what they point to. + This mode relies on the `lchown' system call. On systems that do + not provide the `lchown' system call, `chown' fails when a file + specified on the command line is a symbolic link. By default, no + diagnostic is issued for symbolic links encountered during a + recursive traversal, but see `--verbose'. + +`--preserve-root' + Fail upon any attempt to recursively change the root directory, + `/'. Without `--recursive', this option has no effect. *Note + Treating / specially::. + +`--no-preserve-root' + Cancel the effect of any preceding `--preserve-root' option. + *Note Treating / specially::. + +`--reference=REF_FILE' + Change the user and group of each FILE to be the same as those of + REF_FILE. If REF_FILE is a symbolic link, do not use the user and + group of the symbolic link, but rather those of the file it refers + to. + +`-v' +`--verbose' + Output a diagnostic for every file processed. If a symbolic link + is encountered during a recursive traversal on a system without + the `lchown' system call, and `--no-dereference' is in effect, + then issue a diagnostic saying neither the symbolic link nor its + referent is being changed. + +`-R' +`--recursive' + Recursively change ownership of directories and their contents. + +`-H' + If `--recursive' (`-R') is specified and a command line argument + is a symbolic link to a directory, traverse it. *Note Traversing + symlinks::. + +`-L' + In a recursive traversal, traverse every symbolic link to a + directory that is encountered. *Note Traversing symlinks::. + +`-P' + Do not traverse any symbolic links. This is the default if none + of `-H', `-L', or `-P' is specified. *Note Traversing symlinks::. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + Examples: + + # Change the owner of /u to "root". + chown root /u + + # Likewise, but also change its group to "staff". + chown root:staff /u + + # Change the owner of /u and subfiles to "root". + chown -hR root /u + + +File: coreutils.info, Node: chgrp invocation, Next: chmod invocation, Up: Changing file attributes + +13.2 `chgrp': Change group ownership +==================================== + +`chgrp' changes the group ownership of each given FILE to GROUP (which +can be either a group name or a numeric group ID) or to the group of an +existing reference file. Synopsis: + + chgrp [OPTION]... {GROUP | --reference=REF_FILE} FILE... + + If GROUP is intended to represent a numeric group ID, then you may +specify it with a leading `+'. *Note Disambiguating names and IDs::. + + The program accepts the following options. Also see *Note Common +options::. + +`-c' +`--changes' + Verbosely describe the action for each FILE whose group actually + changes. + +`-f' +`--silent' +`--quiet' + Do not print error messages about files whose group cannot be + changed. + +`--dereference' + Do not act on symbolic links themselves but rather on what they + point to. This is the default. + +`-h' +`--no-dereference' + Act on symbolic links themselves instead of what they point to. + This mode relies on the `lchown' system call. On systems that do + not provide the `lchown' system call, `chgrp' fails when a file + specified on the command line is a symbolic link. By default, no + diagnostic is issued for symbolic links encountered during a + recursive traversal, but see `--verbose'. + +`--preserve-root' + Fail upon any attempt to recursively change the root directory, + `/'. Without `--recursive', this option has no effect. *Note + Treating / specially::. + +`--no-preserve-root' + Cancel the effect of any preceding `--preserve-root' option. + *Note Treating / specially::. + +`--reference=REF_FILE' + Change the group of each FILE to be the same as that of REF_FILE. + If REF_FILE is a symbolic link, do not use the group of the + symbolic link, but rather that of the file it refers to. + +`-v' +`--verbose' + Output a diagnostic for every file processed. If a symbolic link + is encountered during a recursive traversal on a system without + the `lchown' system call, and `--no-dereference' is in effect, + then issue a diagnostic saying neither the symbolic link nor its + referent is being changed. + +`-R' +`--recursive' + Recursively change the group ownership of directories and their + contents. + +`-H' + If `--recursive' (`-R') is specified and a command line argument + is a symbolic link to a directory, traverse it. *Note Traversing + symlinks::. + +`-L' + In a recursive traversal, traverse every symbolic link to a + directory that is encountered. *Note Traversing symlinks::. + +`-P' + Do not traverse any symbolic links. This is the default if none + of `-H', `-L', or `-P' is specified. *Note Traversing symlinks::. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + Examples: + + # Change the group of /u to "staff". + chgrp staff /u + + # Change the group of /u and subfiles to "staff". + chgrp -hR staff /u + + +File: coreutils.info, Node: chmod invocation, Next: chown invocation, Prev: chgrp invocation, Up: Changing file attributes + +13.3 `chmod': Change access permissions +======================================= + +`chmod' changes the access permissions of the named files. Synopsis: + + chmod [OPTION]... {MODE | --reference=REF_FILE} FILE... + + `chmod' never changes the permissions of symbolic links, since the +`chmod' system call cannot change their permissions. This is not a +problem since the permissions of symbolic links are never used. +However, for each symbolic link listed on the command line, `chmod' +changes the permissions of the pointed-to file. In contrast, `chmod' +ignores symbolic links encountered during recursive directory +traversals. + + A successful use of `chmod' clears the set-group-ID bit of a regular +file if the file's group ID does not match the user's effective group +ID or one of the user's supplementary group IDs, unless the user has +appropriate privileges. Additional restrictions may cause the +set-user-ID and set-group-ID bits of MODE or REF_FILE to be ignored. +This behavior depends on the policy and functionality of the underlying +`chmod' system call. When in doubt, check the underlying system +behavior. + + If used, MODE specifies the new file mode bits. For details, see +the section on *Note File permissions::. If you really want MODE to +have a leading `-', you should use `--' first, e.g., `chmod -- -w +file'. Typically, though, `chmod a-w file' is preferable, and `chmod -w +file' (without the `--') complains if it behaves differently from what +`chmod a-w file' would do. + + The program accepts the following options. Also see *Note Common +options::. + +`-c' +`--changes' + Verbosely describe the action for each FILE whose permissions + actually changes. + +`-f' +`--silent' +`--quiet' + Do not print error messages about files whose permissions cannot be + changed. + +`--preserve-root' + Fail upon any attempt to recursively change the root directory, + `/'. Without `--recursive', this option has no effect. *Note + Treating / specially::. + +`--no-preserve-root' + Cancel the effect of any preceding `--preserve-root' option. + *Note Treating / specially::. + +`-v' +`--verbose' + Verbosely describe the action or non-action taken for every FILE. + +`--reference=REF_FILE' + Change the mode of each FILE to be the same as that of REF_FILE. + *Note File permissions::. If REF_FILE is a symbolic link, do not + use the mode of the symbolic link, but rather that of the file it + refers to. + +`-R' +`--recursive' + Recursively change permissions of directories and their contents. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: touch invocation, Prev: chown invocation, Up: Changing file attributes + +13.4 `touch': Change file timestamps +==================================== + +`touch' changes the access and/or modification times of the specified +files. Synopsis: + + touch [OPTION]... FILE... + + Any FILE that does not exist is created empty. + + A FILE of `-' causes `touch' to change the times of the file +associated with standard output. + + If changing both the access and modification times to the current +time, `touch' can change the timestamps for files that the user running +it does not own but has write permission for. Otherwise, the user must +own the files. + + Although `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 `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 the atime doesn't change, nor does it +modify the file, so the mtime doesn't change. Yet, something about the +file itself has changed, and this must be noted somewhere. This is the +job of the ctime field. This is necessary, so that, for example, a +backup program can make a fresh copy of the file, including the new +permissions value. 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. + + Time stamps assume the time zone rules specified by the `TZ' +environment variable, or by the system default rules if `TZ' is not +set. *Note Specifying the Time Zone with `TZ': (libc)TZ Variable. You +can avoid ambiguities during daylight saving transitions by using UTC +time stamps. + + The program accepts the following options. Also see *Note Common +options::. + +`-a' +`--time=atime' +`--time=access' +`--time=use' + Change the access time only. + +`-c' +`--no-create' + Do not create files that do not exist. + +`-d' +`--date=TIME' + Use TIME instead of the current time. It can contain month names, + time zones, `am' and `pm', `yesterday', etc. For example, + `--date="2004-02-27 14:19:13.489392193 +0530"' specifies the + instant of time that is 489,392,193 nanoseconds after February 27, + 2004 at 2:19:13 PM in a time zone that is 5 hours and 30 minutes + east of UTC. *Note Date input formats::. File systems that do + not support high-resolution time stamps silently ignore any excess + precision here. + +`-f' + Ignored; for compatibility with BSD versions of `touch'. + +`-m' +`--time=mtime' +`--time=modify' + Change the modification time only. + +`-r FILE' +`--reference=FILE' + Use the times of the reference FILE instead of the current time. + If this option is combined with the `--date=TIME' (`-d TIME') + option, the reference FILE's time is the origin for any relative + TIMEs given, but is otherwise ignored. For example, `-r foo -d + '-5 seconds'' specifies a time stamp equal to five seconds before + the corresponding time stamp for `foo'. + +`-t [[CC]YY]MMDDHHMM[.SS]' + Use the argument (optional four-digit or two-digit years, months, + days, hours, minutes, optional seconds) instead of the current + time. If the year is specified with only two digits, then CC is + 20 for years in the range 0 ... 68, and 19 for years in 69 ... 99. + If no digits of the year are specified, the argument is + interpreted as a date in the current year. + + + On older systems, `touch' supports an obsolete syntax, as follows. +If no timestamp is given with any of the `-d', `-r', or `-t' options, +and if there are two or more FILEs and the first FILE is of the form +`MMDDHHMM[YY]' and this would be a valid argument to the `-t' option +(if the YY, if any, were moved to the front), and if the represented +year is in the range 1969-1999, that argument is interpreted as the time +for the other files instead of as a file name. This obsolete behavior +can be enabled or disabled with the `_POSIX2_VERSION' environment +variable (*note Standards conformance::), but portable scripts should +avoid commands whose behavior depends on this variable. For example, +use `touch ./12312359 main.c' or `touch -t 12312359 main.c' rather than +the ambiguous `touch 12312359 main.c'. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Disk usage, Next: Printing text, Prev: Changing file attributes, Up: Top + +14 Disk usage +************* + +No disk can hold an infinite amount of data. These commands report how +much disk storage is in use or available, report other file and file +status information, and write buffers to disk. + +* Menu: + +* 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 memory and disk. + + +File: coreutils.info, Node: df invocation, Next: du invocation, Up: Disk usage + +14.1 `df': Report file system disk space usage +============================================== + +`df' reports the amount of disk space used and available on file +systems. Synopsis: + + df [OPTION]... [FILE]... + + With no arguments, `df' reports the space used and available on all +currently mounted file systems (of all types). Otherwise, `df' reports +on the file system containing each argument FILE. + + Normally the disk space is printed in units of 1024 bytes, but this +can be overridden (*note Block size::). Non-integer quantities are +rounded up to the next higher unit. + + If an argument FILE is a disk device file containing a mounted file +system, `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). GNU `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. + + The program accepts the following options. Also see *Note Common +options::. + +`-a' +`--all' + Include in the listing dummy file systems, which are omitted by + default. Such file systems are typically special-purpose + pseudo-file-systems, such as automounter entries. + +`-B SIZE' +`--block-size=SIZE' + Scale sizes by SIZE before printing them (*note Block size::). + For example, `-BG' prints sizes in units of 1,073,741,824 bytes. + +`-h' +`--human-readable' + Append a size letter to each size, such as `M' for mebibytes. + Powers of 1024 are used, not 1000; `M' stands for 1,048,576 bytes. + Use the `--si' option if you prefer powers of 1000. + +`-H' + Equivalent to `--si'. + +`-i' +`--inodes' + List inode usage information instead of block usage. An inode + (short for index node) contains information about a file such as + its owner, permissions, timestamps, and location on the disk. + +`-k' + Print sizes in 1024-byte blocks, overriding the default block size + (*note Block size::). This option is equivalent to + `--block-size=1K'. + +`-l' +`--local' + Limit the listing to local file systems. By default, remote file + systems are also listed. + +`--no-sync' + Do not invoke the `sync' system call before getting any usage data. + This may make `df' run significantly faster on systems with many + disks, but on some systems (notably SunOS) the results may be + slightly out of date. This is the default. + +`-P' +`--portability' + Use the POSIX output format. This is like the default format + except for the following: + + 1. The information about each file system is always printed on + exactly one line; a mount device is never put on a line by + itself. This means that if the mount device name is more + than 20 characters long (e.g., for some network mounts), the + columns are misaligned. + + 2. The labels in the header output line are changed to conform + to POSIX. + + 3. The default block size and output format are unaffected by the + `DF_BLOCK_SIZE', `BLOCK_SIZE' and `BLOCKSIZE' environment + variables. However, the default block size is still affected + by `POSIXLY_CORRECT': it is 512 if `POSIXLY_CORRECT' is set, + 1024 otherwise. *Note Block size::. + +`--si' + Append an SI-style abbreviation to each size, such as `M' for + megabytes. Powers of 1000 are used, not 1024; `M' stands for + 1,000,000 bytes. This option is equivalent to `--block-size=si'. + Use the `-h' or `--human-readable' option if you prefer powers of + 1024. + +`--sync' + Invoke the `sync' system call before getting any usage data. On + some systems (notably SunOS), doing this yields more up to date + results, but in general this option makes `df' much slower, + especially when there are many or very busy file systems. + +`-t FSTYPE' +`--type=FSTYPE' + Limit the listing to file systems of type FSTYPE. Multiple file + system types can be specified by giving multiple `-t' options. By + default, nothing is omitted. + +`-T' +`--print-type' + Print each file system's type. The types printed here are the + same ones you can include or exclude with `-t' and `-x'. The + particular types printed are whatever is supported by the system. + Here are some of the common names (this list is certainly not + exhaustive): + + `nfs' + An NFS file system, i.e., one mounted over a network from + another machine. This is the one type name which seems to be + used uniformly by all systems. + + `4.2, ufs, efs...' + A file system on a locally-mounted hard disk. (The system + might even support more than one type here; Linux does.) + + `hsfs, cdfs' + A file system on a CD-ROM drive. HP-UX uses `cdfs', most + other systems use `hsfs' (`hs' for "High Sierra"). + + `pcfs' + An MS-DOS file system, usually on a diskette. + + +`-x FSTYPE' +`--exclude-type=FSTYPE' + Limit the listing to file systems not of type FSTYPE. Multiple + file system types can be eliminated by giving multiple `-x' + options. By default, no file system types are omitted. + +`-v' + Ignored; for compatibility with System V versions of `df'. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. Failure includes the case where no output is +generated, so you can inspect the exit status of a command like `df -t +ext3 -t reiserfs DIR' to test whether DIR is on a file system of type +`ext3' or `reiserfs'. + + +File: coreutils.info, Node: du invocation, Next: stat invocation, Prev: df invocation, Up: Disk usage + +14.2 `du': Estimate file space usage +==================================== + +`du' reports the amount of disk space used by the specified files and +for each subdirectory (of directory arguments). Synopsis: + + du [OPTION]... [FILE]... + + With no arguments, `du' reports the disk space for the current +directory. Normally the disk space is printed in units of 1024 bytes, +but this can be overridden (*note Block size::). Non-integer +quantities are rounded up to the next higher unit. + + The program accepts the following options. Also see *Note Common +options::. + +`-a' +`--all' + Show counts for all files, not just directories. + +`--apparent-size' + Print apparent sizes, rather than disk usage. The apparent size + of a file is the number of bytes reported by `wc -c' on regular + files, or more generally, `ls -l --block-size=1' or `stat + --format=%s'. For example, a file containing the word `zoo' with + no newline would, of course, have an apparent size of 3. Such a + small file may require anywhere from 0 to 16 KiB or more of disk + space, depending on the type and configuration of the file system + on which the file resides. However, a sparse file created with + this command: + + dd bs=1 seek=2GiB if=/dev/null of=big + + has an apparent size of 2 GiB, yet on most modern systems, it + actually uses almost no disk space. + +`-b' +`--bytes' + Equivalent to `--apparent-size --block-size=1'. + +`-B SIZE' +`--block-size=SIZE' + Scale sizes by SIZE before printing them (*note Block size::). + For example, `-BG' prints sizes in units of 1,073,741,824 bytes. + +`-c' +`--total' + Print a grand total of all arguments after all arguments have been + processed. This can be used to find out the total disk usage of a + given set of files or directories. + +`-D' +`--dereference-args' + Dereference symbolic links that are command line arguments. Does + not affect other symbolic links. This is helpful for finding out + the disk usage of directories, such as `/usr/tmp', which are often + symbolic links. + +`--files0-from=FILE' + Rather than processing files named on the command line, process + those named in file FILE; each name is terminated by a null byte. + This is useful with the `--total' (`-c') option when the list of + file names is so long that it may exceed a command line length + limitation. In such cases, running `du' via `xargs' is undesirable + because it splits the list into pieces and makes `du' print a + total for each sublist rather than for the entire list. One way + to produce a list of null-byte-terminated file names is with GNU + `find', using its `-print0' predicate. Do not specify any FILE on + the command line when using this option. + +`-h' +`--human-readable' + Append a size letter to each size, such as `M' for mebibytes. + Powers of 1024 are used, not 1000; `M' stands for 1,048,576 bytes. + Use the `--si' option if you prefer powers of 1000. + +`-H' + Currently, `-H' is the same as `--si', except that `-H' evokes a + warning. This option will be changed to be equivalent to + `--dereference-args' (`-D'). + +`-k' + Print sizes in 1024-byte blocks, overriding the default block size + (*note Block size::). This option is equivalent to + `--block-size=1K'. + +`-l' +`--count-links' + Count the size of all files, even if they have appeared already + (as a hard link). + +`-L' +`--dereference' + Dereference symbolic links (show the disk space used by the file + or directory that the link points to instead of the space used by + the link). + +`-m' + Print sizes in 1,048,576-byte blocks, overriding the default block + size (*note Block size::). This option is equivalent to + `--block-size=1M'. + +`-P' +`--no-dereference' + For each symbolic links encountered by `du', consider the disk + space used by the symbolic link. + +`--max-depth=DEPTH' + 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 `du --max-depth=0' is equivalent to `du -s'. + +`-0' +`--null' + Output a null byte at the end of each line, rather than a newline. + This option enables other programs to parse the output of `du' + even when that output would contain file names with embedded + newlines. + +`--si' + Append an SI-style abbreviation to each size, such as `MB' for + megabytes. Powers of 1000 are used, not 1024; `MB' stands for + 1,000,000 bytes. Use the `-h' or `--human-readable' option if you + prefer powers of 1024. + +`-s' +`--summarize' + Display only a total for each argument. + +`-S' +`--separate-dirs' + Report the size of each directory separately, not including the + sizes of subdirectories. + +`--time' + Show time of the most recent modification of any file in the + directory, or any of its subdirectories. + +`--time=ctime' +`--time=status' +`--time=use' + Show the most recent status change time (the `ctime' in the inode) + of any file in the directory, instead of the modification time. + +`--time=atime' +`--time=access' + Show the most recent access time (the `atime' in the inode) of any + file in the directory, instead of the modification time. + +`--time-style=STYLE' + List timestamps in style STYLE. This option has an effect only if + the `--time' option is also specified. The STYLE should be one of + the following: + + `+FORMAT' + List timestamps using FORMAT, where FORMAT is interpreted + like the format argument of `date' (*note date invocation::). + For example, `--time-style="+%Y-%m-%d %H:%M:%S"' causes `du' + to list timestamps like `2002-03-30 23:45:56'. As with + `date', FORMAT's interpretation is affected by the `LC_TIME' + locale category. + + `full-iso' + List timestamps in full using ISO 8601 date, time, and time + zone format with nanosecond precision, e.g., `2002-03-30 + 23:45:56.477817180 -0700'. This style is equivalent to + `+%Y-%m-%d %H:%M:%S.%N %z'. + + `long-iso' + List ISO 8601 date and time in minutes, e.g., `2002-03-30 + 23:45'. These timestamps are shorter than `full-iso' + timestamps, and are usually good enough for everyday work. + This style is equivalent to `+%Y-%m-%d %H:%M'. + + `iso' + List ISO 8601 dates for timestamps, e.g., `2002-03-30'. This + style is equivalent to `+%Y-%m-%d'. + + You can specify the default value of the `--time-style' option + with the environment variable `TIME_STYLE'; if `TIME_STYLE' is not + set the default style is `long-iso'. For compatibility with `ls', + if `TIME_STYLE' begins with `+' and contains a newline, the + newline and any later characters are ignored; if `TIME_STYLE' + begins with `posix-' the `posix-' is ignored; and if `TIME_STYLE' + is `locale' it is ignored. + +`-x' +`--one-file-system' + Skip directories that are on different file systems from the one + that the argument being processed is on. + +`--exclude=PATTERN' + When recursing, skip subdirectories or files matching PATTERN. + For example, `du --exclude='*.o'' excludes files whose names end + in `.o'. + +`-X FILE' +`--exclude-from=FILE' + Like `--exclude', except take the patterns to exclude from FILE, + one per line. If FILE is `-', take the patterns from standard + input. + + + On BSD systems, `du' reports sizes that are half the correct values +for files that are NFS-mounted from HP-UX systems. On HP-UX systems, +it reports sizes that are twice the correct values for files that are +NFS-mounted from BSD systems. This is due to a flaw in HP-UX; it also +affects the HP-UX `du' program. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: stat invocation, Next: sync invocation, Prev: du invocation, Up: Disk usage + +14.3 `stat': Report file or file system status +============================================== + +`stat' displays information about the specified file(s). Synopsis: + + stat [OPTION]... [FILE]... + + With no option, `stat' reports all information about the given files. +But it also can be used to report the information of the file systems +the given files are located on. If the files are links, `stat' can +also give information about the files the links point to. + +`-L' +`--dereference' + Change how `stat' treats symbolic links. With this option, `stat' + acts on the file referenced by each symbolic link argument. + Without it, `stat' acts on any symbolic link argument directly. + +`-f' +`--file-system' + Report information about the file systems where the given files + are located instead of information about the files themselves. + +`-c' +`--format=FORMAT' + Use FORMAT rather than the default format. FORMAT is + automatically newline-terminated, so running a command like the + following with two or more FILE operands produces a line of output + for each operand: + $ stat --format=%d:%i / /usr + 2050:2 + 2057:2 + +`--printf=FORMAT' + Use FORMAT rather than the default format. Like `--format', but + interpret backslash escapes, and do not output a mandatory + trailing newline. If you want a newline, include `\n' in the + FORMAT. Here's how you would use `--printf' to print the device + and inode numbers of `/' and `/usr': + $ stat --printf='%d:%i\n' / /usr + 2050:2 + 2057:2 + +`-t' +`--terse' + Print the information in terse form, suitable for parsing by other + programs. + + The valid format sequences for files are: + + * %a - Access rights in octal + + * %A - Access rights in human readable form + + * %b - Number of blocks allocated (see `%B') + + * %B - The size in bytes of each block reported by `%b' + + * %d - Device number in decimal + + * %D - Device number in hex + + * %f - Raw mode in hex + + * %F - File type + + * %g - Group ID of owner + + * %G - Group name of owner + + * %h - Number of hard links + + * %i - Inode number + + * %n - File name + + * %N - Quoted file name with dereference if symbolic link + + * %o - I/O block size + + * %s - Total size, in bytes + + * %t - Major device type in hex + + * %T - Minor device type in hex + + * %u - User ID of owner + + * %U - User name of owner + + * %x - Time of last access + + * %X - Time of last access as seconds since Epoch + + * %y - Time of last modification + + * %Y - Time of last modification as seconds since Epoch + + * %z - Time of last change + + * %Z - Time of last change as seconds since Epoch + + The valid format sequences for file systems are: + + * %a - Free blocks available to non-super-user + + * %b - Total data blocks in file system + + * %c - Total file nodes in file system + + * %d - Free file nodes in file system + + * %f - Free blocks in file system + + * %i - File System ID in hex + + * %l - Maximum length of file names + + * %n - File name + + * %s - Block size (for faster transfers) + + * %S - Fundamental block size (for block counts) + + * %t - Type in hex + + * %T - Type in human readable form + + Time stamps are listed according to the time zone rules specified + by the `TZ' environment variable, or by the system default rules if + `TZ' is not set. *Note Specifying the Time Zone with `TZ': + (libc)TZ Variable. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: sync invocation, Prev: stat invocation, Up: Disk usage + +14.4 `sync': Synchronize data on disk with memory +================================================= + +`sync' writes any data buffered in memory out to disk. This can +include (but is not limited to) modified superblocks, modified inodes, +and delayed reads and writes. This must be implemented by the kernel; +The `sync' program does nothing but exercise the `sync' system call. + + The kernel keeps data in memory to avoid doing (relatively slow) disk +reads and writes. This improves performance, but if the computer +crashes, data may be lost or the file system corrupted as a result. +The `sync' command ensures everything in memory is written to disk. + + Any arguments are ignored, except for a lone `--help' or `--version' +(*note Common options::). + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Printing text, Next: Conditions, Prev: Disk usage, Up: Top + +15 Printing text +**************** + +This section describes commands that display text strings. + +* Menu: + +* echo invocation:: Print a line of text. +* printf invocation:: Format and print data. +* yes invocation:: Print a string until interrupted. + + +File: coreutils.info, Node: echo invocation, Next: printf invocation, Up: Printing text + +15.1 `echo': Print a line of text +================================= + +`echo' writes each given STRING to standard output, with a space +between each and a newline after the last one. Synopsis: + + echo [OPTION]... [STRING]... + + The program accepts the following options. Also see *Note Common +options::. Options must precede operands, and the normally-special +argument `--' has no special meaning and is treated like any other +STRING. + +`-n' + Do not output the trailing newline. + +`-e' + Enable interpretation of the following backslash-escaped + characters in each STRING: + + `\a' + alert (bell) + + `\b' + backspace + + `\c' + suppress trailing newline + + `\f' + form feed + + `\n' + new line + + `\r' + carriage return + + `\t' + horizontal tab + + `\v' + vertical tab + + `\\' + backslash + + `\0NNN' + the eight-bit value that is the octal number NNN (zero to + three octal digits) + + `\NNN' + the eight-bit value that is the octal number NNN (one to + three octal digits) + + `\xHH' + the eight-bit value that is the hexadecimal number HH (one or + two hexadecimal digits) + +`-E' + Disable interpretation of backslash escapes in each STRING. This + is the default. If `-e' and `-E' are both specified, the last one + given takes effect. + + + If the `POSIXLY_CORRECT' environment variable is set, then when +`echo''s first argument is not `-n' it outputs option-like arguments +instead of treating them as options. For example, `echo -ne hello' +outputs `-ne hello' instead of plain `hello'. + + POSIX does not require support for any options, and says that the +behavior of `echo' is implementation-defined if any STRING contains a +backslash or if the first argument is `-n'. Portable programs can use +the `printf' command if they need to omit trailing newlines or output +control characters or backslashes. *Note printf invocation::. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: printf invocation, Next: yes invocation, Prev: echo invocation, Up: Printing text + +15.2 `printf': Format and print data +==================================== + +`printf' does formatted printing of text. Synopsis: + + printf FORMAT [ARGUMENT]... + + `printf' prints the FORMAT string, interpreting `%' directives and +`\' escapes to format numeric and string arguments in a way that is +mostly similar to the C `printf' function. The differences are as +follows: + + * The FORMAT argument is reused as necessary to convert all the + given ARGUMENTs. For example, the command `printf %s a b' outputs + `ab'. + + * Missing ARGUMENTs are treated as null strings or as zeros, + depending on whether the context expects a string or a number. For + example, the command `printf %sx%d' prints `x0'. + + * An additional escape, `\c', causes `printf' to produce no further + output. For example, the command `printf 'A%sC\cD%sF' B E' prints + `ABC'. + + * The hexadecimal escape sequence `\xHH' has at most two digits, as + opposed to C where it can have an unlimited number of digits. For + example, the command `printf '\x07e'' prints two bytes, whereas + the C statement `printf ("\x07e")' prints just one. + + * `printf' has an additional directive, `%b', which prints its + argument string with `\' escapes interpreted in the same way as in + the FORMAT string, except that octal escapes are of the form + `\0OOO' where OOO is 0 to 3 octal digits. If a precision is also + given, it limits the number of bytes printed from the converted + string. + + * Numeric arguments must be single C constants, possibly with leading + `+' or `-'. For example, `printf %.4d -3' outputs `-0003'. + + * If the leading character of a numeric argument is `"' or `'' then + its value is the numeric value of the immediately following + character. Any remaining characters are silently ignored if the + `POSIXLY_CORRECT' environment variable is set; otherwise, a + warning is printed. For example, `printf "%d" "'a"' outputs `97' + on hosts that use the ASCII character set, since `a' has the + numeric value 97 in ASCII. + + + A floating-point argument must use a period before any fractional +digits, but is printed according to the `LC_NUMERIC' category of the +current locale. For example, in a locale whose radix character is a +comma, the command `printf %g 3.14' outputs `3,14' whereas the command +`printf %g 3,14' is an error. + + `printf' interprets `\OOO' in FORMAT as an octal number (if OOO is 1 +to 3 octal digits) specifying a character to print, and `\xHH' as a +hexadecimal number (if HH is 1 to 2 hex digits) specifying a character +to print. + + `printf' interprets two character syntaxes introduced in ISO C 99: +`\u' for 16-bit Unicode (ISO/IEC 10646) characters, specified as four +hexadecimal digits HHHH, and `\U' for 32-bit Unicode characters, +specified as eight hexadecimal digits HHHHHHHH. `printf' outputs the +Unicode characters according to the `LC_CTYPE' locale. + + The processing of `\u' and `\U' requires a full-featured `iconv' +facility. It is activated on systems with glibc 2.2 (or newer), or +when `libiconv' is installed prior to this package. Otherwise `\u' and +`\U' will print as-is. + + The only options are a lone `--help' or `--version'. *Note Common +options::. Options must precede operands. + + The Unicode character syntaxes are useful for writing strings in a +locale independent way. For example, a string containing the Euro +currency symbol + + $ /usr/local/bin/printf '\u20AC 14.95' + +will be output correctly in all locales supporting the Euro symbol +(ISO-8859-15, UTF-8, and others). Similarly, a Chinese string + + $ /usr/local/bin/printf '\u4e2d\u6587' + +will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8, +etc). + + Note that in these examples, the full name of `printf' has been +given, to distinguish it from the GNU `bash' built-in function `printf'. + + For larger strings, you don't need to look up the hexadecimal code +values of each character one by one. ASCII characters mixed with \u +escape sequences is also known as the JAVA source file encoding. You +can use GNU recode 3.5c (or newer) to convert strings to this encoding. +Here is how to convert a piece of text into a shell script which will +output this text in a locale-independent way: + + $ LC_CTYPE=zh_CN.big5 /usr/local/bin/printf \ + '\u4e2d\u6587\n' > sample.txt + $ recode BIG5..JAVA < sample.txt \ + | sed -e "s|^|/usr/local/bin/printf '|" -e "s|$|\\\\n'|" \ + > sample.sh + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: yes invocation, Prev: printf invocation, Up: Printing text + +15.3 `yes': Print a string until interrupted +============================================ + +`yes' prints the command line arguments, separated by spaces and +followed by a newline, forever until it is killed. If no arguments are +given, it prints `y' followed by a newline forever until killed. + + Upon a write error, `yes' exits with status `1'. + + The only options are a lone `--help' or `--version'. To output an +argument that begins with `-', precede it with `--', e.g., `yes -- +--help'. *Note Common options::. + + +File: coreutils.info, Node: Conditions, Next: Redirection, Prev: Printing text, Up: Top + +16 Conditions +************* + +This section describes commands that are primarily useful for their exit +status, rather than their output. Thus, they are often used as the +condition of shell `if' statements, or as the last command in a +pipeline. + +* Menu: + +* false invocation:: Do nothing, unsuccessfully. +* true invocation:: Do nothing, successfully. +* test invocation:: Check file types and compare values. +* expr invocation:: Evaluate expressions. + + +File: coreutils.info, Node: false invocation, Next: true invocation, Up: Conditions + +16.1 `false': Do nothing, unsuccessfully +======================================== + +`false' does nothing except return an exit status of 1, meaning +"failure". It can be used as a place holder in shell scripts where an +unsuccessful command is needed. In most modern shells, `false' is a +built-in command, so when you use `false' in a script, you're probably +using the built-in command, not the one documented here. + + `false' honors the `--help' and `--version' options. + + This version of `false' is implemented as a C program, and is thus +more secure and faster than a shell script implementation, and may +safely be used as a dummy shell for the purpose of disabling accounts. + + Note that `false' (unlike all other programs documented herein) +exits unsuccessfully, even when invoked with `--help' or `--version'. + + Portable programs should not assume that the exit status of `false' +is 1, as it is greater than 1 on some non-GNU hosts. + + +File: coreutils.info, Node: true invocation, Next: test invocation, Prev: false invocation, Up: Conditions + +16.2 `true': Do nothing, successfully +===================================== + +`true' does nothing except return an exit status of 0, meaning +"success". It can be used as a place holder in shell scripts where a +successful command is needed, although the shell built-in command `:' +(colon) may do the same thing faster. In most modern shells, `true' is +a built-in command, so when you use `true' in a script, you're probably +using the built-in command, not the one documented here. + + `true' honors the `--help' and `--version' options. + + Note, however, that it is possible to cause `true' to exit with +nonzero status: with the `--help' or `--version' option, and with +standard output already closed or redirected to a file that evokes an +I/O error. For example, using a Bourne-compatible shell: + + $ ./true --version >&- + ./true: write error: Bad file number + $ ./true --version > /dev/full + ./true: write error: No space left on device + + This version of `true' is implemented as a C program, and is thus +more secure and faster than a shell script implementation, and may +safely be used as a dummy shell for the purpose of disabling accounts. + + +File: coreutils.info, Node: test invocation, Next: expr invocation, Prev: true invocation, Up: Conditions + +16.3 `test': Check file types and compare values +================================================ + +`test' returns a status of 0 (true) or 1 (false) depending on the +evaluation of the conditional expression EXPR. Each part of the +expression must be a separate argument. + + `test' has file status checks, string operators, and numeric +comparison operators. + + `test' has an alternate form that uses opening and closing square +brackets instead a leading `test'. For example, instead of `test -d +/', you can write `[ -d / ]'. The square brackets must be separate +arguments; for example, `[-d /]' does not have the desired effect. +Since `test EXPR' and `[ EXPR ]' have the same meaning, only the former +form is discussed below. + + Synopses: + + test EXPRESSION + test + [ EXPRESSION ] + [ ] + [ OPTION + + Because most shells have a built-in `test' command, using an +unadorned `test' in a script or interactively may get you different +functionality than that described here. + + If EXPRESSION is omitted, `test' returns false. If EXPRESSION is a +single argument, `test' returns false if the argument is null and true +otherwise. The argument can be any string, including strings like +`-d', `-1', `--', `--help', and `--version' that most other programs +would treat as options. To get help and version information, invoke +the commands `[ --help' and `[ --version', without the usual closing +brackets. *Note Common options::. + + Exit status: + + 0 if the expression is true, + 1 if the expression is false, + 2 if an error occurred. + +* Menu: + +* File type tests:: -[bcdfhLpSt] +* Access permission tests:: -[gkruwxOG] +* File characteristic tests:: -e -s -nt -ot -ef +* String tests:: -z -n = != +* Numeric tests:: -eq -ne -lt -le -gt -ge +* Connectives for test:: ! -a -o + + +File: coreutils.info, Node: File type tests, Next: Access permission tests, Up: test invocation + +16.3.1 File type tests +---------------------- + +These options test for particular types of files. (Everything's a file, +but not all files are the same!) + +`-b FILE' + True if FILE exists and is a block special device. + +`-c FILE' + True if FILE exists and is a character special device. + +`-d FILE' + True if FILE exists and is a directory. + +`-f FILE' + True if FILE exists and is a regular file. + +`-h FILE' +`-L FILE' + True if FILE exists and is a symbolic link. Unlike all other + file-related tests, this test does not dereference FILE if it is a + symbolic link. + +`-p FILE' + True if FILE exists and is a named pipe. + +`-S FILE' + True if FILE exists and is a socket. + +`-t FD' + True if FD is a file descriptor that is associated with a terminal. + + + +File: coreutils.info, Node: Access permission tests, Next: File characteristic tests, Prev: File type tests, Up: test invocation + +16.3.2 Access permission tests +------------------------------ + +These options test for particular access permissions. + +`-g FILE' + True if FILE exists and has its set-group-ID bit set. + +`-k FILE' + True if FILE exists and has its "sticky" bit set. + +`-r FILE' + True if FILE exists and read permission is granted. + +`-u FILE' + True if FILE exists and has its set-user-ID bit set. + +`-w FILE' + True if FILE exists and write permission is granted. + +`-x FILE' + True if FILE exists and execute permission is granted (or search + permission, if it is a directory). + +`-O FILE' + True if FILE exists and is owned by the current effective user ID. + +`-G FILE' + True if FILE exists and is owned by the current effective group ID. + + + +File: coreutils.info, Node: File characteristic tests, Next: String tests, Prev: Access permission tests, Up: test invocation + +16.3.3 File characteristic tests +-------------------------------- + +These options test other file characteristics. + +`-e FILE' + True if FILE exists. + +`-s FILE' + True if FILE exists and has a size greater than zero. + +`FILE1 -nt FILE2' + True if FILE1 is newer (according to modification date) than + FILE2, or if FILE1 exists and FILE2 does not. + +`FILE1 -ot FILE2' + True if FILE1 is older (according to modification date) than + FILE2, or if FILE2 exists and FILE1 does not. + +`FILE1 -ef FILE2' + True if FILE1 and FILE2 have the same device and inode numbers, + i.e., if they are hard links to each other. + + + +File: coreutils.info, Node: String tests, Next: Numeric tests, Prev: File characteristic tests, Up: test invocation + +16.3.4 String tests +------------------- + +These options test string characteristics. You may need to quote +STRING arguments for the shell. For example: + + test -n "$V" + + The quotes here prevent the wrong arguments from being passed to +`test' if `$V' is empty or contains special characters. + +`-z STRING' + True if the length of STRING is zero. + +`-n STRING' +`STRING' + True if the length of STRING is nonzero. + +`STRING1 = STRING2' + True if the strings are equal. + +`STRING1 != STRING2' + True if the strings are not equal. + + + +File: coreutils.info, Node: Numeric tests, Next: Connectives for test, Prev: String tests, Up: test invocation + +16.3.5 Numeric tests +-------------------- + +Numeric relationals. The arguments must be entirely numeric (possibly +negative), or the special expression `-l STRING', which evaluates to +the length of STRING. + +`ARG1 -eq ARG2' +`ARG1 -ne ARG2' +`ARG1 -lt ARG2' +`ARG1 -le ARG2' +`ARG1 -gt ARG2' +`ARG1 -ge ARG2' + These arithmetic binary operators return true if ARG1 is equal, + not-equal, less-than, less-than-or-equal, greater-than, or + greater-than-or-equal than ARG2, respectively. + + + For example: + + test -1 -gt -2 && echo yes + => yes + test -l abc -gt 1 && echo yes + => yes + test 0x100 -eq 1 + error--> test: integer expression expected before -eq + + +File: coreutils.info, Node: Connectives for test, Prev: Numeric tests, Up: test invocation + +16.3.6 Connectives for `test' +----------------------------- + +The usual logical connectives. + +`! EXPR' + True if EXPR is false. + +`EXPR1 -a EXPR2' + True if both EXPR1 and EXPR2 are true. + +`EXPR1 -o EXPR2' + True if either EXPR1 or EXPR2 is true. + + + +File: coreutils.info, Node: expr invocation, Prev: test invocation, Up: Conditions + +16.4 `expr': Evaluate expressions +================================= + +`expr' evaluates an expression and writes the result on standard +output. Each token of the expression must be a separate argument. + + Operands are either integers or strings. Integers consist of one or +more decimal digits, with an optional leading `-'. `expr' converts +anything appearing in an operand position to an integer or a string +depending on the operation being applied to it. + + Strings are not quoted for `expr' itself, though you may need to +quote them to protect characters with special meaning to the shell, +e.g., spaces. However, regardless of whether it is quoted, a string +operand should not be a parenthesis or any of `expr''s operators like +`+', so you cannot safely pass an arbitrary string `$str' to expr +merely by quoting it to the shell. One way to work around this is to +use the GNU extension `+', (e.g., `+ "$str" = foo'); a more portable +way is to use `" $str"' and to adjust the rest of the expression to take +the leading space into account (e.g., `" $str" = " foo"'). + + You should not pass a negative integer or a string with leading `-' +as `expr''s first argument, as it might be misinterpreted as an option; +this can be avoided by parenthesization. Also, portable scripts should +not use a string operand that happens to take the form of an integer; +this can be worked around by inserting leading spaces as mentioned +above. + + Operators may be given as infix symbols or prefix keywords. +Parentheses may be used for grouping in the usual manner. You must +quote parentheses and many operators to avoid the shell evaluating them, +however. + + The only options are `--help' and `--version'. *Note Common +options::. Options must precede operands. + + Exit status: + + 0 if the expression is neither null nor 0, + 1 if the expression is null or 0, + 2 if the expression is invalid, + 3 if an internal error occurred (e.g., arithmetic overflow). + +* Menu: + +* String expressions:: + : match substr index length +* Numeric expressions:: + - * / % +* Relations for expr:: | & < <= = == != >= > +* Examples of expr:: Examples. + + +File: coreutils.info, Node: String expressions, Next: Numeric expressions, Up: expr invocation + +16.4.1 String expressions +------------------------- + +`expr' supports pattern matching and other string operators. These +have lower precedence than both the numeric and relational operators (in +the next sections). + +`STRING : REGEX' + Perform pattern matching. The arguments are converted to strings + and the second is considered to be a (basic, a la GNU `grep') + regular expression, with a `^' implicitly prepended. The first + argument is then matched against this regular expression. + + If the match succeeds and REGEX uses `\(' and `\)', the `:' + expression returns the part of STRING that matched the + subexpression; otherwise, it returns the number of characters + matched. + + If the match fails, the `:' operator returns the null string if + `\(' and `\)' are used in REGEX, otherwise 0. + + Only the first `\( ... \)' pair is relevant to the return value; + additional pairs are meaningful only for grouping the regular + expression operators. + + In the regular expression, `\+', `\?', and `\|' are operators + which respectively match one or more, zero or one, or separate + alternatives. SunOS and other `expr''s treat these as regular + characters. (POSIX allows either behavior.) *Note Regular + Expression Library: (regex)Top, for details of regular expression + syntax. Some examples are in *Note Examples of expr::. + +`match STRING REGEX' + An alternative way to do pattern matching. This is the same as + `STRING : REGEX'. + +`substr STRING POSITION LENGTH' + Returns the substring of STRING beginning at POSITION with length + at most LENGTH. If either POSITION or LENGTH is negative, zero, + or non-numeric, returns the null string. + +`index STRING CHARSET' + Returns the first position in STRING where the first character in + CHARSET was found. If no character in CHARSET is found in STRING, + return 0. + +`length STRING' + Returns the length of STRING. + +`+ TOKEN' + Interpret TOKEN as a string, even if it is a keyword like MATCH or + an operator like `/'. This makes it possible to test `expr length + + "$x"' or `expr + "$x" : '.*/\(.\)'' and have it do the right + thing even if the value of $X happens to be (for example) `/' or + `index'. This operator is a GNU extension. Portable shell + scripts should use `" $token" : ' \(.*\)'' instead of `+ "$token"'. + + + To make `expr' interpret keywords as strings, you must use the +`quote' operator. + + +File: coreutils.info, Node: Numeric expressions, Next: Relations for expr, Prev: String expressions, Up: expr invocation + +16.4.2 Numeric expressions +-------------------------- + +`expr' supports the usual numeric operators, in order of increasing +precedence. The string operators (previous section) have lower +precedence, the connectives (next section) have higher. + +`+ -' + Addition and subtraction. Both arguments are converted to + integers; an error occurs if this cannot be done. + +`* / %' + Multiplication, division, remainder. Both arguments are converted + to integers; an error occurs if this cannot be done. + + + +File: coreutils.info, Node: Relations for expr, Next: Examples of expr, Prev: Numeric expressions, Up: expr invocation + +16.4.3 Relations for `expr' +--------------------------- + +`expr' supports the usual logical connectives and relations. These are +higher precedence than either the string or numeric operators (previous +sections). Here is the list, lowest-precedence operator first. + +`|' + Returns its first argument if that is neither null nor zero, + otherwise its second argument if it is neither null nor zero, + otherwise 0. It does not evaluate its second argument if its + first argument is neither null nor zero. + +`&' + Return its first argument if neither argument is null or zero, + otherwise 0. It does not evaluate its second argument if its + first argument is null or zero. + +`< <= = == != >= >' + Compare the arguments and return 1 if the relation is true, 0 + otherwise. `==' is a synonym for `='. `expr' first tries to + convert both arguments to integers and do a numeric comparison; if + either conversion fails, it does a lexicographic comparison using + the character collating sequence specified by the `LC_COLLATE' + locale. + + + +File: coreutils.info, Node: Examples of expr, Prev: Relations for expr, Up: expr invocation + +16.4.4 Examples of using `expr' +------------------------------- + +Here are a few examples, including quoting for shell metacharacters. + + To add 1 to the shell variable `foo', in Bourne-compatible shells: + + foo=`expr $foo + 1` + + To print the non-directory part of the file name stored in `$fname', +which need not contain a `/': + + expr $fname : '.*/\(.*\)' '|' $fname + + An example showing that `\+' is an operator: + + expr aaa : 'a\+' + => 3 + + expr abc : 'a\(.\)c' + => b + expr index abcdef cz + => 3 + expr index index a + error--> expr: syntax error + expr index quote index a + => 0 + + +File: coreutils.info, Node: Redirection, Next: File name manipulation, Prev: Conditions, Up: Top + +17 Redirection +************** + +Unix shells commonly provide several forms of "redirection"--ways to +change the input source or output destination of a command. But one +useful redirection is performed by a separate command, not by the shell; +it's described here. + +* Menu: + +* tee invocation:: Redirect output to multiple files. + + +File: coreutils.info, Node: tee invocation, Up: Redirection + +17.1 `tee': Redirect output to multiple files +============================================= + +The `tee' command copies standard input to standard output and also to +any files given as arguments. This is useful when you want not only to +send some data down a pipe, but also to save a copy. Synopsis: + + tee [OPTION]... [FILE]... + + If a file being written to does not already exist, it is created. +If a file being written to already exists, the data it previously +contained is overwritten unless the `-a' option is used. + + A FILE of `-' causes `tee' to send another copy of input to standard +output, but this is typically not that useful as the copies are +interleaved. + + The program accepts the following options. Also see *Note Common +options::. + +`-a' +`--append' + Append standard input to the given files rather than overwriting + them. + +`-i' +`--ignore-interrupts' + Ignore interrupt signals. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: File name manipulation, Next: Working context, Prev: Redirection, Up: Top + +18 File name manipulation +************************* + +This section describes commands that manipulate file names. + +* Menu: + +* basename invocation:: Strip directory and suffix from a file name. +* dirname invocation:: Strip non-directory suffix from a file name. +* pathchk invocation:: Check file name portability. + + +File: coreutils.info, Node: basename invocation, Next: dirname invocation, Up: File name manipulation + +18.1 `basename': Strip directory and suffix from a file name +============================================================ + +`basename' removes any leading directory components from NAME. +Synopsis: + + basename NAME [SUFFIX] + + If SUFFIX is specified and is identical to the end of NAME, it is +removed from NAME as well. Note that since trailing slashes are +removed prior to suffix matching, SUFFIX will do nothing if it contains +slashes. `basename' prints the result on standard output. + + Together, `basename' and `dirname' are designed such that if `ls +"$name"' succeeds, then the command sequence `cd "$(dirname "$name")"; +ls "$(basename "$name")"' will, too. This works for everything except +file names containing a trailing newline. + + POSIX allows the implementation to define the results if NAME is +empty or `//'. In the former case, GNU `basename' returns the empty +string. In the latter case, the result is `//' on platforms where // +is distinct from /, and `/' on platforms where there is no difference. + + The only options are `--help' and `--version'. *Note Common +options::. Options must precede operands. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + Examples: + + # Output "sort". + basename /usr/bin/sort + + # Output "stdio". + basename include/stdio.h .h + + +File: coreutils.info, Node: dirname invocation, Next: pathchk invocation, Prev: basename invocation, Up: File name manipulation + +18.2 `dirname': Strip non-directory suffix from a file name +=========================================================== + +`dirname' prints all but the final slash-delimited component of a +string (presumably a file name). Synopsis: + + dirname NAME + + If NAME is a single component, `dirname' prints `.' (meaning the +current directory). + + Together, `basename' and `dirname' are designed such that if `ls +"$name"' succeeds, then the command sequence `cd "$(dirname "$name")"; +ls "$(basename "$name")"' will, too. This works for everything except +file names containing a trailing newline. + + POSIX allows the implementation to define the results if NAME is +`//'. With GNU `dirname', the result is `//' on platforms where // is +distinct from /, and `/' on platforms where there is no difference. + + The only options are `--help' and `--version'. *Note Common +options::. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + Examples: + + # Output "/usr/bin". + dirname /usr/bin/sort + + # Output ".". + dirname stdio.h + + +File: coreutils.info, Node: pathchk invocation, Prev: dirname invocation, Up: File name manipulation + +18.3 `pathchk': Check file name portability +=========================================== + +`pathchk' checks portability of file names. Synopsis: + + pathchk [OPTION]... NAME... + + For each NAME, `pathchk' prints a message if any of these conditions +is true: + + 1. One of the existing directories in NAME does not have search + (execute) permission, + + 2. The length of NAME is larger than the maximum supported by the + operating system. + + 3. The length of one component of NAME is longer than its file + system's maximum. + + A nonexistent NAME is not an error, so long a file with that name +could be created under the above conditions. + + The program accepts the following options. Also see *Note Common +options::. Options must precede operands. + +`-p' + Instead of performing checks based on the underlying file system, + print a message if any of these conditions is true: + + 1. A file name is empty. + + 2. The length of a file name or one of its components exceeds the + POSIX minimum limits for portability. + + 3. A file name contains a character outside the portable file + name character set, namely, the ASCII letters and digits, `-', + `.', `/', and `_'. + +`-P' + Print a message if a file name is empty, or if it contains a + component that begins with `-'. + +`--portability' + Print a message if a file name is not portable to all POSIX hosts. + This option is equivalent to `-p -P'. + + + Exit status: + + 0 if all specified file names passed all checks, + 1 otherwise. + + +File: coreutils.info, Node: Working context, Next: User information, Prev: File name manipulation, Up: Top + +19 Working context +****************** + +This section describes commands that display or alter the context in +which you are working: the current directory, the terminal settings, and +so forth. See also the user-related commands in the next section. + +* Menu: + +* pwd invocation:: Print working directory. +* stty invocation:: Print or change terminal characteristics. +* printenv invocation:: Print environment variables. +* tty invocation:: Print file name of terminal on standard input. + + +File: coreutils.info, Node: pwd invocation, Next: stty invocation, Up: Working context + +19.1 `pwd': Print working directory +=================================== + +`pwd' prints the fully resolved name of the current directory. That +is, all components of the printed name will be actual directory +names--none will be symbolic links. + + Because most shells have a built-in `pwd' command, using an +unadorned `pwd' in a script or interactively may get you different +functionality than that described here. + + The only options are a lone `--help' or `--version'. *Note Common +options::. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: stty invocation, Next: printenv invocation, Prev: pwd invocation, Up: Working context + +19.2 `stty': Print or change terminal characteristics +===================================================== + +`stty' prints or changes terminal characteristics, such as baud rate. +Synopses: + + stty [OPTION] [SETTING]... + stty [OPTION] + + If given no line settings, `stty' prints the baud rate, line +discipline number (on systems that support it), and line settings that +have been changed from the values set by `stty sane'. By default, mode +reading and setting are performed on the tty line connected to standard +input, although this can be modified by the `--file' option. + + `stty' accepts many non-option arguments that change aspects of the +terminal line operation, as described below. + + The program accepts the following options. Also see *Note Common +options::. + +`-a' +`--all' + Print all current settings in human-readable form. This option + may not be used in combination with any line settings. + +`-F DEVICE' +`--file=DEVICE' + Set the line opened by the file name specified in DEVICE instead of + the tty line connected to standard input. This option is necessary + because opening a POSIX tty requires use of the `O_NONDELAY' flag + to prevent a POSIX tty from blocking until the carrier detect line + is high if the `clocal' flag is not set. Hence, it is not always + possible to allow the shell to open the device in the traditional + manner. + +`-g' +`--save' + Print all current settings in a form that can be used as an + argument to another `stty' command to restore the current + settings. This option may not be used in combination with any + line settings. + + + Many settings can be turned off by preceding them with a `-'. Such +arguments are marked below with "May be negated" in their description. +The descriptions themselves refer to the positive case, that is, when +_not_ negated (unless stated otherwise, of course). + + Some settings are not available on all POSIX systems, since they use +extensions. Such arguments are marked below with "Non-POSIX" in their +description. On non-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. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + +* Menu: + +* Control:: Control settings +* Input:: Input settings +* Output:: Output settings +* Local:: Local settings +* Combination:: Combination settings +* Characters:: Special characters +* Special:: Special settings + + +File: coreutils.info, Node: Control, Next: Input, Up: stty invocation + +19.2.1 Control settings +----------------------- + +Control settings: + +`parenb' + Generate parity bit in output and expect parity bit in input. May + be negated. + +`parodd' + Set odd parity (even if negated). May be negated. + +`cs5' +`cs6' +`cs7' +`cs8' + Set character size to 5, 6, 7, or 8 bits. + +`hup' +`hupcl' + Send a hangup signal when the last process closes the tty. May be + negated. + +`cstopb' + Use two stop bits per character (one if negated). May be negated. + +`cread' + Allow input to be received. May be negated. + +`clocal' + Disable modem control signals. May be negated. + +`crtscts' + Enable RTS/CTS flow control. Non-POSIX. May be negated. + + +File: coreutils.info, Node: Input, Next: Output, Prev: Control, Up: stty invocation + +19.2.2 Input settings +--------------------- + +`ignbrk' + Ignore break characters. May be negated. + +`brkint' + Make breaks cause an interrupt signal. May be negated. + +`ignpar' + Ignore characters with parity errors. May be negated. + +`parmrk' + Mark parity errors (with a 255-0-character sequence). May be + negated. + +`inpck' + Enable input parity checking. May be negated. + +`istrip' + Clear high (8th) bit of input characters. May be negated. + +`inlcr' + Translate newline to carriage return. May be negated. + +`igncr' + Ignore carriage return. May be negated. + +`icrnl' + Translate carriage return to newline. May be negated. + +`iutf8' + Assume input characters are UTF-8 encoded. May be negated. + +`ixon' + Enable XON/XOFF flow control (that is, `CTRL-S'/`CTRL-Q'). May be + negated. + +`ixoff' +`tandem' + Enable sending of `stop' character when the system input buffer is + almost full, and `start' character when it becomes almost empty + again. May be negated. + +`iuclc' + Translate uppercase characters to lowercase. Non-POSIX. May be + negated. + +`ixany' + Allow any character to restart output (only the start character if + negated). Non-POSIX. May be negated. + +`imaxbel' + Enable beeping and not flushing input buffer if a character arrives + when the input buffer is full. Non-POSIX. May be negated. + + +File: coreutils.info, Node: Output, Next: Local, Prev: Input, Up: stty invocation + +19.2.3 Output settings +---------------------- + +These arguments specify output-related operations. + +`opost' + Postprocess output. May be negated. + +`olcuc' + Translate lowercase characters to uppercase. Non-POSIX. May be + negated. + +`ocrnl' + Translate carriage return to newline. Non-POSIX. May be negated. + +`onlcr' + Translate newline to carriage return-newline. Non-POSIX. May be + negated. + +`onocr' + Do not print carriage returns in the first column. Non-POSIX. + May be negated. + +`onlret' + Newline performs a carriage return. Non-POSIX. May be negated. + +`ofill' + Use fill (padding) characters instead of timing for delays. + Non-POSIX. May be negated. + +`ofdel' + Use delete characters for fill instead of null characters. + Non-POSIX. May be negated. + +`nl1' +`nl0' + Newline delay style. Non-POSIX. + +`cr3' +`cr2' +`cr1' +`cr0' + Carriage return delay style. Non-POSIX. + +`tab3' +`tab2' +`tab1' +`tab0' + Horizontal tab delay style. Non-POSIX. + +`bs1' +`bs0' + Backspace delay style. Non-POSIX. + +`vt1' +`vt0' + Vertical tab delay style. Non-POSIX. + +`ff1' +`ff0' + Form feed delay style. Non-POSIX. + + +File: coreutils.info, Node: Local, Next: Combination, Prev: Output, Up: stty invocation + +19.2.4 Local settings +--------------------- + +`isig' + Enable `interrupt', `quit', and `suspend' special characters. May + be negated. + +`icanon' + Enable `erase', `kill', `werase', and `rprnt' special characters. + May be negated. + +`iexten' + Enable non-POSIX special characters. May be negated. + +`echo' + Echo input characters. May be negated. + +`echoe' +`crterase' + Echo `erase' characters as backspace-space-backspace. May be + negated. + +`echok' + Echo a newline after a `kill' character. May be negated. + +`echonl' + Echo newline even if not echoing other characters. May be negated. + +`noflsh' + Disable flushing after `interrupt' and `quit' special characters. + May be negated. + +`xcase' + Enable input and output of uppercase characters by preceding their + lowercase equivalents with `\', when `icanon' is set. Non-POSIX. + May be negated. + +`tostop' + Stop background jobs that try to write to the terminal. Non-POSIX. + May be negated. + +`echoprt' +`prterase' + Echo erased characters backward, between `\' and `/'. Non-POSIX. + May be negated. + +`echoctl' +`ctlecho' + Echo control characters in hat notation (`^C') instead of + literally. Non-POSIX. May be negated. + +`echoke' +`crtkill' + Echo the `kill' special character by erasing each character on the + line as indicated by the `echoprt' and `echoe' settings, instead + of by the `echoctl' and `echok' settings. Non-POSIX. May be + negated. + + +File: coreutils.info, Node: Combination, Next: Characters, Prev: Local, Up: stty invocation + +19.2.5 Combination settings +--------------------------- + +Combination settings: + +`evenp' +`parity' + Same as `parenb -parodd cs7'. May be negated. If negated, same + as `-parenb cs8'. + +`oddp' + Same as `parenb parodd cs7'. May be negated. If negated, same as + `-parenb cs8'. + +`nl' + Same as `-icrnl -onlcr'. May be negated. If negated, same as + `icrnl -inlcr -igncr onlcr -ocrnl -onlret'. + +`ek' + Reset the `erase' and `kill' special characters to their default + values. + +`sane' + Same as: + + cread -ignbrk brkint -inlcr -igncr icrnl -ixoff + -iuclc -ixany imaxbel opost -olcuc -ocrnl onlcr + -onocr -onlret -ofill -ofdel nl0 cr0 tab0 bs0 vt0 + ff0 isig icanon iexten echo echoe echok -echonl + -noflsh -xcase -tostop -echoprt echoctl echoke + + and also sets all special characters to their default values. + +`cooked' + Same as `brkint ignpar istrip icrnl ixon opost isig icanon', plus + sets the `eof' and `eol' characters to their default values if + they are the same as the `min' and `time' characters. May be + negated. If negated, same as `raw'. + +`raw' + Same as: + + -ignbrk -brkint -ignpar -parmrk -inpck -istrip + -inlcr -igncr -icrnl -ixon -ixoff -iuclc -ixany + -imaxbel -opost -isig -icanon -xcase min 1 time 0 + + May be negated. If negated, same as `cooked'. + +`cbreak' + Same as `-icanon'. May be negated. If negated, same as `icanon'. + +`pass8' + Same as `-parenb -istrip cs8'. May be negated. If negated, same + as `parenb istrip cs7'. + +`litout' + Same as `-parenb -istrip -opost cs8'. May be negated. If + negated, same as `parenb istrip opost cs7'. + +`decctlq' + Same as `-ixany'. Non-POSIX. May be negated. + +`tabs' + Same as `tab0'. Non-POSIX. May be negated. If negated, same as + `tab3'. + +`lcase' +`LCASE' + Same as `xcase iuclc olcuc'. Non-POSIX. May be negated. + +`crt' + Same as `echoe echoctl echoke'. + +`dec' + Same as `echoe echoctl echoke -ixany intr ^C erase ^? kill C-u'. + + +File: coreutils.info, Node: Characters, Next: Special, Prev: Combination, Up: stty invocation + +19.2.6 Special characters +------------------------- + +The special characters' default values vary from system to system. +They are set with the syntax `name value', where the names are listed +below and the value can be given either literally, in hat notation +(`^C'), or as an integer which may start with `0x' to indicate +hexadecimal, `0' to indicate octal, or any other digit to indicate +decimal. + + For GNU stty, giving a value of `^-' or `undef' disables that +special character. (This is incompatible with Ultrix `stty', which +uses a value of `u' to disable a special character. GNU `stty' treats +a value `u' like any other, namely to set that special character to +<U>.) + +`intr' + Send an interrupt signal. + +`quit' + Send a quit signal. + +`erase' + Erase the last character typed. + +`kill' + Erase the current line. + +`eof' + Send an end of file (terminate the input). + +`eol' + End the line. + +`eol2' + Alternate character to end the line. Non-POSIX. + +`swtch' + Switch to a different shell layer. Non-POSIX. + +`start' + Restart the output after stopping it. + +`stop' + Stop the output. + +`susp' + Send a terminal stop signal. + +`dsusp' + Send a terminal stop signal after flushing the input. Non-POSIX. + +`rprnt' + Redraw the current line. Non-POSIX. + +`werase' + Erase the last word typed. Non-POSIX. + +`lnext' + Enter the next character typed literally, even if it is a special + character. Non-POSIX. + + +File: coreutils.info, Node: Special, Prev: Characters, Up: stty invocation + +19.2.7 Special settings +----------------------- + +`min N' + Set the minimum number of characters that will satisfy a read until + the time value has expired, when `-icanon' is set. + +`time N' + Set the number of tenths of a second before reads time out if the + minimum number of characters have not been read, when `-icanon' is + set. + +`ispeed N' + Set the input speed to N. + +`ospeed N' + Set the output speed to N. + +`rows N' + Tell the tty kernel driver that the terminal has N rows. + Non-POSIX. + +`cols N' +`columns N' + Tell the kernel that the terminal has N columns. Non-POSIX. + +`size' + Print the number of rows and columns that the kernel thinks the + terminal has. (Systems that don't support rows and columns in the + kernel typically use the environment variables `LINES' and + `COLUMNS' instead; however, GNU `stty' does not know anything + about them.) Non-POSIX. + +`line N' + Use line discipline N. Non-POSIX. + +`speed' + Print the terminal speed. + +`N' + Set the input and output speeds to N. N can be one of: 0 50 75 + 110 134 134.5 150 200 300 600 1200 1800 2400 4800 9600 19200 38400 + `exta' `extb'. `exta' is the same as 19200; `extb' is the same as + 38400. 0 hangs up the line if `-clocal' is set. + + +File: coreutils.info, Node: printenv invocation, Next: tty invocation, Prev: stty invocation, Up: Working context + +19.3 `printenv': Print all or some environment variables +======================================================== + +`printenv' prints environment variable values. Synopsis: + + printenv [OPTION] [VARIABLE]... + + If no VARIABLEs are specified, `printenv' prints the value of every +environment variable. Otherwise, it prints the value of each VARIABLE +that is set, and nothing for those that are not set. + + The only options are a lone `--help' or `--version'. *Note Common +options::. + + Exit status: + + 0 if all variables specified were found + 1 if at least one specified variable was not found + 2 if a write error occurred + + +File: coreutils.info, Node: tty invocation, Prev: printenv invocation, Up: Working context + +19.4 `tty': Print file name of terminal on standard input +========================================================= + +`tty' prints the file name of the terminal connected to its standard +input. It prints `not a tty' if standard input is not a terminal. +Synopsis: + + tty [OPTION]... + + The program accepts the following option. Also see *Note Common +options::. + +`-s' +`--silent' +`--quiet' + Print nothing; only return an exit status. + + + Exit status: + + 0 if standard input is a terminal + 1 if standard input is not a terminal + 2 if given incorrect arguments + 3 if a write error occurs + + +File: coreutils.info, Node: User information, Next: System context, Prev: Working context, Up: Top + +20 User information +******************* + +This section describes commands that print user-related information: +logins, groups, and so forth. + +* Menu: + +* id invocation:: Print user identity. +* logname invocation:: Print current login name. +* whoami invocation:: Print effective user ID. +* groups invocation:: Print group names a user is in. +* users invocation:: Print login names of users currently logged in. +* who invocation:: Print who is currently logged in. + + +File: coreutils.info, Node: id invocation, Next: logname invocation, Up: User information + +20.1 `id': Print user identity +============================== + +`id' prints information about the given user, or the process running it +if no user is specified. Synopsis: + + id [OPTION]... [USERNAME] + + 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. + + Each of these numeric values is preceded by an identifying string and +followed by the corresponding user or group name in parentheses. + + The options cause `id' to print only part of the above information. +Also see *Note Common options::. + +`-g' +`--group' + Print only the group ID. + +`-G' +`--groups' + Print only the group ID and the supplementary groups. + +`-n' +`--name' + Print the user or group name instead of the ID number. Requires + `-u', `-g', or `-G'. + +`-r' +`--real' + Print the real, instead of effective, user or group ID. Requires + `-u', `-g', or `-G'. + +`-u' +`--user' + Print only the user ID. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: logname invocation, Next: whoami invocation, Prev: id invocation, Up: User information + +20.2 `logname': Print current login name +======================================== + +`logname' prints the calling user's name, as found in a +system-maintained file (often `/var/run/utmp' or `/etc/utmp'), and +exits with a status of 0. If there is no entry for the calling +process, `logname' prints an error message and exits with a status of 1. + + The only options are `--help' and `--version'. *Note Common +options::. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: whoami invocation, Next: groups invocation, Prev: logname invocation, Up: User information + +20.3 `whoami': Print effective user ID +====================================== + +`whoami' prints the user name associated with the current effective +user ID. It is equivalent to the command `id -un'. + + The only options are `--help' and `--version'. *Note Common +options::. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: groups invocation, Next: users invocation, Prev: whoami invocation, Up: User information + +20.4 `groups': Print group names a user is in +============================================= + +`groups' prints the names of the primary and any supplementary groups +for each given USERNAME, or the current process if no names are given. +If more than one name is given, the name of each user is printed before +the list of that user's groups. Synopsis: + + groups [USERNAME]... + + The group lists are equivalent to the output of the command `id -Gn'. + + The only options are `--help' and `--version'. *Note Common +options::. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: users invocation, Next: who invocation, Prev: groups invocation, Up: User information + +20.5 `users': Print login names of users currently logged in +============================================================ + +`users' prints on a single line a blank-separated list of user names of +users currently logged in to the current host. Each user name +corresponds to a login session, so if a user has more than one login +session, that user's name will appear the same number of times in the +output. Synopsis: + + users [FILE] + + With no FILE argument, `users' extracts its information from a +system-maintained file (often `/var/run/utmp' or `/etc/utmp'). If a +file argument is given, `users' uses that file instead. A common +choice is `/var/log/wtmp'. + + The only options are `--help' and `--version'. *Note Common +options::. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: who invocation, Prev: users invocation, Up: User information + +20.6 `who': Print who is currently logged in +============================================ + +`who' prints information about users who are currently logged on. +Synopsis: + + `who' [OPTION] [FILE] [am i] + + If given no non-option arguments, `who' prints the following +information for each user currently logged on: login name, terminal +line, login time, and remote hostname or X display. + + If given one non-option argument, `who' uses that instead of a +default system-maintained file (often `/var/run/utmp' or `/etc/utmp') +as the name of the file containing the record of users logged on. +`/var/log/wtmp' is commonly given as an argument to `who' to look at +who has previously logged on. + + If given two non-option arguments, `who' prints only the entry for +the user running it (determined from its standard input), preceded by +the hostname. Traditionally, the two arguments given are `am i', as in +`who am i'. + + Time stamps are listed according to the time zone rules specified by +the `TZ' environment variable, or by the system default rules if `TZ' +is not set. *Note Specifying the Time Zone with `TZ': (libc)TZ +Variable. + + The program accepts the following options. Also see *Note Common +options::. + +`-a' +`--all' + Same as `-b -d --login -p -r -t -T -u'. + +`-b' +`--boot' + Print the date and time of last system boot. + +`-d' +`--dead' + Print information corresponding to dead processes. + +`-H' +`--heading' + Print column headings. + +`-m' + Same as `who am i'. + +`-q' +`--count' + Print only the login names and the number of users logged on. + Overrides all other options. + +`-s' + Ignored; for compatibility with other versions of `who'. + +`-u' + After the login time, print the number of hours and minutes that + the user has been idle. `.' means the user was active in the last + minute. `old' means the user has been idle for more than 24 hours. + +`-l' +`--login' + List only the entries that correspond to processes via which the + system is waiting for a user to login. The user name is always + `LOGIN'. + +`--lookup' + Attempt to canonicalize hostnames found in utmp through a DNS + lookup. This is not the default because it can cause significant + delays on systems with automatic dial-up internet access. + +`-H' +`--heading' + Print a line of column headings. + +`-w' +`-T' +`--mesg' +`--message' +`--writable' + After each login name print a character indicating the user's + message status: + + `+' allowing `write' messages + `-' disallowing `write' messages + `?' cannot find terminal device + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: System context, Next: Modified command invocation, Prev: User information, Up: Top + +21 System context +***************** + +This section describes commands that print or change system-wide +information. + +* Menu: + +* date invocation:: Print or set system date and time. +* uname invocation:: Print system information. +* hostname invocation:: Print or set system name. +* hostid invocation:: Print numeric host identifier. + + +File: coreutils.info, Node: date invocation, Next: uname invocation, Up: System context + +21.1 `date': Print or set system date and time +============================================== + +Synopses: + + date [OPTION]... [+FORMAT] + date [-u|--utc|--universal] [ MMDDhhmm[[CC]YY][.ss] ] + + Invoking `date' with no FORMAT argument is equivalent to invoking it +with a default format that depends on the `LC_TIME' locale category. +In the default C locale, this format is `'+%a %b %e %H:%M:%S %Z %Y'', +so the output looks like `Thu Mar 3 13:47:51 PST 2005'. + + Normally, `date' uses the time zone rules indicated by the `TZ' +environment variable, or the system default rules if `TZ' is not set. +*Note Specifying the Time Zone with `TZ': (libc)TZ Variable. + + If given an argument that starts with a `+', `date' prints the +current date and time (or the date and time specified by the `--date' +option, see below) in the format defined by that argument, which is +similar to that of the `strftime' function. Except for conversion +specifiers, which start with `%', characters in the format string are +printed unchanged. The conversion specifiers are described below. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + +* Menu: + +* Time conversion specifiers:: %[HIklMNpPrRsSTXzZ] +* 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. +* Examples of date:: Examples. + + +File: coreutils.info, Node: Time conversion specifiers, Next: Date conversion specifiers, Up: date invocation + +21.1.1 Time conversion specifiers +--------------------------------- + +`date' conversion specifiers related to times. + +`%H' + hour (`00'...`23') + +`%I' + hour (`01'...`12') + +`%k' + hour (` 0'...`23'). This is a GNU extension. + +`%l' + hour (` 1'...`12'). This is a GNU extension. + +`%M' + minute (`00'...`59') + +`%N' + nanoseconds (`000000000'...`999999999'). This is a GNU extension. + +`%p' + locale's equivalent of either `AM' or `PM'; blank in many locales. + Noon is treated as `PM' and midnight as `AM'. + +`%P' + like `%p', except lower case. This is a GNU extension. + +`%r' + locale's 12-hour clock time (e.g., `11:11:04 PM') + +`%R' + 24-hour hour and minute. Same as `%H:%M'. This is a GNU + extension. + +`%s' + seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. + Leap seconds are not counted unless leap second support is + available. *Note %s-examples::, for examples. This is a GNU + extension. + +`%S' + second (`00'...`60'). This may be `60' if leap seconds are + supported. + +`%T' + 24-hour hour, minute, and second. Same as `%H:%M:%S'. + +`%X' + locale's time representation (e.g., `23:13:48') + +`%z' + RFC 2822/ISO 8601 style numeric time zone (e.g., `-0600' or + `+0530'), or nothing if no time zone is determinable. This value + reflects the numeric time zone appropriate for the current time, + using the time zone rules specified by the `TZ' environment + variable. The time (and optionally, the time zone rules) can be + overridden by the `--date' option. This is a GNU extension. + +`%:z' + RFC 3339/ISO 8601 style numeric time zone with `:' (e.g., `-06:00' + or `+05:30'), or nothing if no time zone is determinable. This is + a GNU extension. + +`%::z' + Numeric time zone to the nearest second with `:' (e.g., + `-06:00:00' or `+05:30:00'), or nothing if no time zone is + determinable. This is a GNU extension. + +`%:::z' + Numeric time zone with `:' using the minimum necessary precision + (e.g., `-06', `+05:30', or `-04:56:02'), or nothing if no time + zone is determinable. This is a GNU extension. + +`%Z' + alphabetic time zone abbreviation (e.g., `EDT'), or nothing if no + time zone is determinable. See `%z' for how it is determined. + + +File: coreutils.info, Node: Date conversion specifiers, Next: Literal conversion specifiers, Prev: Time conversion specifiers, Up: date invocation + +21.1.2 Date conversion specifiers +--------------------------------- + +`date' conversion specifiers related to dates. + +`%a' + locale's abbreviated weekday name (e.g., `Sun') + +`%A' + locale's full weekday name, variable length (e.g., `Sunday') + +`%b' + locale's abbreviated month name (e.g., `Jan') + +`%B' + locale's full month name, variable length (e.g., `January') + +`%c' + locale's date and time (e.g., `Thu Mar 3 23:05:25 2005') + +`%C' + century. This is like `%Y', except the last two digits are + omitted. For example, it is `20' if `%Y' is `2000', and is `-0' + if `%Y' is `-001'. It is normally at least two characters, but it + may be more. + +`%d' + day of month (e.g., `01') + +`%D' + date; same as `%m/%d/%y' + +`%e' + day of month, space padded; same as `%_d' + +`%F' + full date in ISO 8601 format; same as `%Y-%m-%d'. This is a good + choice for a date format, as it is standard and is easy to sort in + the usual case where years are in the range 0000...9999. This is + a GNU extension. + +`%g' + year corresponding to the ISO week number, but without the century + (range `00' through `99'). This has the same format and value as + `%y', except that if the ISO week number (see `%V') belongs to the + previous or next year, that year is used instead. This is a GNU + extension. + +`%G' + year corresponding to the ISO week number. This has the same + format and value as `%Y', except that if the ISO week number (see + `%V') belongs to the previous or next year, that year is used + instead. It is normally useful only if `%V' is also used; for + example, the format `%G-%m-%d' is probably a mistake, since it + combines the ISO week number year with the conventional month and + day. This is a GNU extension. + +`%h' + same as `%b' + +`%j' + day of year (`001'...`366') + +`%m' + month (`01'...`12') + +`%u' + day of week (`1'...`7') with `1' corresponding to Monday + +`%U' + week number of year, with Sunday as the first day of the week + (`00'...`53'). Days in a new year preceding the first Sunday are + in week zero. + +`%V' + ISO week number, that is, the week number of year, with Monday as + the first day of the week (`01'...`53'). If the week containing + January 1 has four or more days in the new year, then it is + considered week 1; otherwise, it is week 53 of the previous year, + and the next week is week 1. (See the ISO 8601 standard.) + +`%w' + day of week (`0'...`6') with 0 corresponding to Sunday + +`%W' + week number of year, with Monday as first day of week + (`00'...`53'). Days in a new year preceding the first Monday are + in week zero. + +`%x' + locale's date representation (e.g., `12/31/99') + +`%y' + last two digits of year (`00'...`99') + +`%Y' + year. This is normally at least four characters, but it may be + more. Year `0000' precedes year `0001', and year `-001' precedes + year `0000'. + + +File: coreutils.info, Node: Literal conversion specifiers, Next: Padding and other flags, Prev: Date conversion specifiers, Up: date invocation + +21.1.3 Literal conversion specifiers +------------------------------------ + +`date' conversion specifiers that produce literal strings. + +`%%' + a literal % + +`%n' + a newline + +`%t' + a horizontal tab + + +File: coreutils.info, Node: Padding and other flags, Next: Setting the time, Prev: Literal conversion specifiers, Up: date invocation + +21.1.4 Padding and other flags +------------------------------ + +Unless otherwise specified, `date' normally pads numeric fields with +zeros, so that, for example, numeric months are always output as two +digits. Seconds since the epoch are not padded, though, since there is +no natural width for them. + + As a GNU extension, `date' recognizes any of the following optional +flags after the `%': + +`-' + (hyphen) Do not pad the field; useful if the output is intended for + human consumption. + +`_' + (underscore) Pad with spaces; useful if you need a fixed number of + characters in the output, but zeros are too distracting. + +`0' + (zero) Pad with zeros even if the conversion specifier would + normally pad with spaces. + +`^' + Use upper case characters if possible. + +`#' + Use opposite case characters if possible. A field that is + normally upper case becomes lower case, and vice versa. + +Here are some examples of padding: + + date +%d/%m -d "Feb 1" + => 01/02 + date +%-d/%-m -d "Feb 1" + => 1/2 + date +%_d/%_m -d "Feb 1" + => 1/ 2 + + As a GNU extension, you can specify the field width (after any flag, +if present) as a decimal number. If the natural size of the output is +of the field has less than the specified number of characters, the +result is written right adjusted and padded to the given size. For +example, `%9B' prints the right adjusted month name in a field of width +9. + + An optional modifier can follow the optional flag and width +specification. The modifiers are: + +`E' + Use the locale's alternate representation for date and time. This + modifier applies to the `%c', `%C', `%x', `%X', `%y' and `%Y' + conversion specifiers. In a Japanese locale, for example, `%Ex' + might yield a date format based on the Japanese Emperors' reigns. + +`O' + Use the locale's alternate numeric symbols for numbers. This + modifier applies only to numeric conversion specifiers. + + If the format supports the modifier but no alternate representation +is available, it is ignored. + + +File: coreutils.info, Node: Setting the time, Next: Options for date, Prev: Padding and other flags, Up: date invocation + +21.1.5 Setting the time +----------------------- + +If given an argument that does not start with `+', `date' sets the +system clock to the date and time specified by that argument (as +described below). You must have appropriate privileges to set the +system clock. The `--date' and `--set' options may not be used with +such an argument. The `--universal' option may be used with such an +argument to indicate that the specified date and time are relative to +Coordinated Universal Time rather than to the local time zone. + + The argument must consist entirely of digits, which have the +following meaning: + +`MM' + month + +`DD' + day within month + +`hh' + hour + +`mm' + minute + +`CC' + first two digits of year (optional) + +`YY' + last two digits of year (optional) + +`ss' + second (optional) + + The `--set' option also sets the system clock; see the next section. + + +File: coreutils.info, Node: Options for date, Next: Examples of date, Prev: Setting the time, Up: date invocation + +21.1.6 Options for `date' +------------------------- + +The program accepts the following options. Also see *Note Common +options::. + +`-d DATESTR' +`--date=DATESTR' + Display the date and time specified in DATESTR instead of the + current date and time. DATESTR can be in almost any common + format. It can contain month names, time zones, `am' and `pm', + `yesterday', etc. For example, `--date="2004-02-27 + 14:19:13.489392193 +0530"' specifies the instant of time that is + 489,392,193 nanoseconds after February 27, 2004 at 2:19:13 PM in a + time zone that is 5 hours and 30 minutes east of UTC. *Note Date + input formats::. + +`-f DATEFILE' +`--file=DATEFILE' + Parse each line in DATEFILE as with `-d' and display the resulting + date and time. If DATEFILE is `-', use standard input. This is + useful when you have many dates to process, because the system + overhead of starting up the `date' executable many times can be + considerable. + +`-r FILE' +`--reference=FILE' + Display the date and time of the last modification of FILE, + instead of the current date and time. + +`-R' +`--rfc-822' +`--rfc-2822' + Display the date and time using the format `%a, %d %b %Y %H:%M:%S + %z', evaluated in the C locale so abbreviations are always in + English. For example: + + Fri, 09 Sep 2005 13:51:39 -0700 + + This format conforms to Internet RFCs 2822 + (ftp://ftp.rfc-editor.org/in-notes/rfc2822.txt) and 822 + (ftp://ftp.rfc-editor.org/in-notes/rfc822.txt), the current and + previous standards for Internet email. + +`--rfc-3339=TIMESPEC' + Display the date using a format specified by Internet RFC 3339 + (ftp://ftp.rfc-editor.org/in-notes/rfc3339.txt). This is a subset + of the ISO 8601 format, except that it also permits applications + to use a space rather than a `T' to separate dates from times. + Unlike the other standard formats, RFC 3339 format is always + suitable as input for the `--date' (`-d') and `--file' (`-f') + options, regardless of the current locale. + + The argument TIMESPEC specifies how much of the time to include. + It can be one of the following: + + `date' + Print just the full-date, e.g., `2005-09-14'. This is + equivalent to the format `%Y-%m-%d'. + + `seconds' + Print the full-date and full-time separated by a space, e.g., + `2005-09-14 00:56:06+05:30'. The output ends with a numeric + time-offset; here the `+05:30' means that local time is five + hours and thirty minutes east of UTC. This is equivalent to + the format `%Y-%m-%d %H:%M:%S%:z'. + + `ns' + Like `seconds', but also print nanoseconds, e.g., `2005-09-14 + 00:56:06.998458565+05:30'. This is equivalent to the format + `%Y-%m-%d %H:%M:%S.%N%:z'. + + +`-s DATESTR' +`--set=DATESTR' + Set the date and time to DATESTR. See `-d' above. + +`-u' +`--utc' +`--universal' + Use Coordinated Universal Time (UTC) by operating as if the `TZ' + environment variable were set to the string `UTC0'. Coordinated + Universal Time is often called "Greenwich Mean Time" (GMT) for + historical reasons. + + +File: coreutils.info, Node: Examples of date, Prev: Options for date, Up: date invocation + +21.1.7 Examples of `date' +------------------------- + +Here are a few examples. Also see the documentation for the `-d' +option in the previous section. + + * To print the date of the day before yesterday: + + date --date='2 days ago' + + * To print the date of the day three months and one day hence: + + date --date='3 months 1 day' + + * To print the day of year of Christmas in the current year: + + date --date='25 Dec' +%j + + * To print the current full month name and the day of the month: + + date '+%B %d' + + But this may not be what you want because for the first nine days + of the month, the `%d' expands to a zero-padded two-digit field, + for example `date -d 1may '+%B %d'' will print `May 01'. + + * To print a date without the leading zero for one-digit days of the + month, you can use the (GNU extension) `-' flag to suppress the + padding altogether: + + date -d 1may '+%B %-d + + * To print the current date and time in the format required by many + non-GNU versions of `date' when setting the system clock: + + date +%m%d%H%M%Y.%S + + * To set the system clock forward by two minutes: + + date --set='+2 minutes' + + * To print the date in RFC 2822 format, use `date --rfc-2822'. Here + is some example output: + + Fri, 09 Sep 2005 13:51:39 -0700 + + * To convert a date string to the number of seconds since the epoch + (which is 1970-01-01 00:00:00 UTC), use the `--date' option with + the `%s' format. That can be useful in sorting and/or graphing + and/or comparing data by date. The following command outputs the + number of the seconds since the epoch for the time two minutes + after the epoch: + + date --date='1970-01-01 00:02:00 +0000' +%s + 120 + + If you do not specify time zone information in the date string, + `date' uses your computer's idea of the time zone when + interpreting the string. For example, if your computer's time + zone is that of Cambridge, Massachusetts, which was then 5 hours + (i.e., 18,000 seconds) behind UTC: + + # local time zone used + date --date='1970-01-01 00:02:00' +%s + 18120 + + * If you're sorting or graphing dated data, your raw date values may + be represented as seconds since the epoch. But few people can + look at the date `946684800' and casually note "Oh, that's the + first second of the year 2000 in Greenwich, England." + + date --date='2000-01-01 UTC' +%s + 946684800 + + An alternative is to use the `--utc' (`-u') option. Then you may + omit `UTC' from the date string. Although this produces the same + result for `%s' and many other format sequences, with a time zone + offset different from zero, it would give a different result for + zone-dependent formats like `%z'. + + date -u --date=2000-01-01 +%s + 946684800 + + To convert such an unwieldy number of seconds back to a more + readable form, use a command like this: + + # local time zone used + date -d '1970-01-01 UTC 946684800 seconds' +"%Y-%m-%d %T %z" + 1999-12-31 19:00:00 -0500 + + Or if you do not mind depending on the `@' feature present since + coreutils 5.3.0, you could shorten this to: + + date -d @946684800 +"%F %T %z" + 1999-12-31 19:00:00 -0500 + + Often it is better to output UTC-relative date and time: + + date -u -d '1970-01-01 946684800 seconds' +"%Y-%m-%d %T %z" + 2000-01-01 00:00:00 +0000 + + + +File: coreutils.info, Node: uname invocation, Next: hostname invocation, Prev: date invocation, Up: System context + +21.2 `uname': Print system information +====================================== + +`uname' prints information about the machine and operating system it is +run on. If no options are given, `uname' acts as if the `-s' option +were given. Synopsis: + + uname [OPTION]... + + If multiple options or `-a' are given, the selected information is +printed in this order: + + KERNEL-NAME NODENAME KERNEL-RELEASE KERNEL-VERSION + MACHINE PROCESSOR HARDWARE-PLATFORM OPERATING-SYSTEM + + The information may contain internal spaces, so such output cannot be +parsed reliably. In the following example, RELEASE is +`2.2.18ss.e820-bda652a #4 SMP Tue Jun 5 11:24:08 PDT 2001': + + uname -a + => Linux dum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 i686 unknown unknown GNU/Linux + + The program accepts the following options. Also see *Note Common +options::. + +`-a' +`--all' + Print all of the below information, except omit the processor type + and the hardware platform name if they are unknown. + +`-i' +`--hardware-platform' + Print the hardware platform name (sometimes called the hardware + implementation). Print `unknown' if the kernel does not make this + information easily available, as is the case with Linux kernels. + +`-m' +`--machine' + Print the machine hardware name (sometimes called the hardware + class or hardware type). + +`-n' +`--nodename' + Print the network node hostname. + +`-p' +`--processor' + Print the processor type (sometimes called the instruction set + architecture or ISA). Print `unknown' if the kernel does not make + this information easily available, as is the case with Linux + kernels. + +`-o' +`--operating-system' + Print the name of the operating system. + +`-r' +`--kernel-release' + Print the kernel release. + +`-s' +`--kernel-name' + Print the kernel name. POSIX 1003.1-2001 (*note Standards + conformance::) calls this "the implementation of the operating + system", because the POSIX specification itself has no notion of + "kernel". The kernel name might be the same as the operating + system name printed by the `-o' or `--operating-system' option, + but it might differ. Some operating systems (e.g., FreeBSD, + HP-UX) have the same name as their underlying kernels; others + (e.g., GNU/Linux, Solaris) do not. + +`-v' +`--kernel-version' + Print the kernel version. + + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: hostname invocation, Next: hostid invocation, Prev: uname invocation, Up: System context + +21.3 `hostname': Print or set system name +========================================= + +With no arguments, `hostname' prints the name of the current host +system. With one argument, it sets the current host name to the +specified string. You must have appropriate privileges to set the host +name. Synopsis: + + hostname [NAME] + + The only options are `--help' and `--version'. *Note Common +options::. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: hostid invocation, Prev: hostname invocation, Up: System context + +21.4 `hostid': Print numeric host identifier. +============================================= + +`hostid' prints the numeric identifier of the current host in +hexadecimal. This command accepts no arguments. The only options are +`--help' and `--version'. *Note Common options::. + + For example, here's what it prints on one system I use: + + $ hostid + 1bac013d + + On that system, the 32-bit quantity happens to be closely related to +the system's Internet address, but that isn't always the case. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Modified command invocation, Next: Process control, Prev: System context, Up: Top + +22 Modified command invocation +****************************** + +This section describes commands that run other commands in some context +different than the current one: a modified environment, as a different +user, etc. + +* Menu: + +* chroot invocation:: Modify the root directory. +* env invocation:: Modify environment variables. +* nice invocation:: Modify niceness. +* nohup invocation:: Immunize to hangups. +* su invocation:: Modify user and group ID. + + +File: coreutils.info, Node: chroot invocation, Next: env invocation, Up: Modified command invocation + +22.1 `chroot': Run a command with a different root directory +============================================================ + +`chroot' runs a command with a specified root directory. On many +systems, only the super-user can do this. Synopses: + + chroot NEWROOT [COMMAND [ARGS]...] + chroot OPTION + + Ordinarily, file names are looked up starting at the root of the +directory structure, i.e., `/'. `chroot' changes the root to the +directory NEWROOT (which must exist) and then runs COMMAND with +optional ARGS. If COMMAND is not specified, the default is the value +of the `SHELL' environment variable or `/bin/sh' if not set, invoked +with the `-i' option. COMMAND must not be a special built-in utility +(*note Special built-in utilities::). + + The only options are `--help' and `--version'. *Note Common +options::. Options must precede operands. + + Here are a few tips to help avoid common problems in using chroot. +To start with a simple example, make COMMAND refer to a statically +linked binary. If you were to use a dynamically linked executable, then +you'd have to arrange to have the shared libraries in the right place +under your new root directory. + + For example, if you create a statically linked `ls' executable, and +put it in `/tmp/empty', you can run this command as root: + + $ chroot /tmp/empty /ls -Rl / + + Then you'll see output like this: + + /: + total 1023 + -rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls + + If you want to use a dynamically linked executable, say `bash', then +first run `ldd bash' to see what shared objects it needs. Then, in +addition to copying the actual binary, also copy the listed files to +the required positions under your intended new root directory. +Finally, if the executable requires any other files (e.g., data, state, +device files), copy them into place, too. + + Exit status: + + 1 if `chroot' itself fails + 126 if COMMAND is found but cannot be invoked + 127 if COMMAND cannot be found + the exit status of COMMAND otherwise + + +File: coreutils.info, Node: env invocation, Next: nice invocation, Prev: chroot invocation, Up: Modified command invocation + +22.2 `env': Run a command in a modified environment +=================================================== + +`env' runs a command with a modified environment. Synopses: + + env [OPTION]... [NAME=VALUE]... [COMMAND [ARGS]...] + env + + Operands of the form `VARIABLE=VALUE' set the environment variable +VARIABLE to value VALUE. VALUE may be empty (`VARIABLE='). Setting a +variable to an empty value is different from unsetting it. These +operands are evaluated left-to-right, so if two operands mention the +same variable the earlier is ignored. + + Environment variable names can be empty, and can contain any +characters other than `=' and the null character (ASCII NUL). However, +it is wise to limit yourself to names that consist solely of +underscores, digits, and ASCII letters, and that begin with a +non-digit, as applications like the shell do not work well with other +names. + + The first operand that does not contain the character `=' specifies +the program to invoke; it is searched for according to the `PATH' +environment variable. Any remaining arguments are passed as arguments +to that program. The program should not be a special built-in utility +(*note Special built-in utilities::). + + If no command name is specified following the environment +specifications, the resulting environment is printed. This is like +specifying the `printenv' program. + + The program accepts the following options. Also see *Note Common +options::. Options must precede operands. + +`-u NAME' +`--unset=NAME' + Remove variable NAME from the environment, if it was in the + environment. + +`-' +`-i' +`--ignore-environment' + Start with an empty environment, ignoring the inherited + environment. + + + Exit status: + + 0 if no COMMAND is specified and the environment is output + 1 if `env' itself fails + 126 if COMMAND is found but cannot be invoked + 127 if COMMAND cannot be found + the exit status of COMMAND otherwise + + +File: coreutils.info, Node: nice invocation, Next: nohup invocation, Prev: env invocation, Up: Modified command invocation + +22.3 `nice': Run a command with modified niceness +================================================= + +`nice' prints or modifies a process's "niceness", a parameter that +affects whether the process is scheduled favorably. Synopsis: + + nice [OPTION]... [COMMAND [ARG]...] + + If no arguments are given, `nice' prints the current niceness. +Otherwise, `nice' runs the given COMMAND with its niceness adjusted. +By default, its niceness is incremented by 10. + + Nicenesses range at least from -20 (resulting in the most favorable +scheduling) through 19 (the least favorable). Some systems may have a +wider range of nicenesses; conversely, other systems may enforce more +restrictive limits. An attempt to set the niceness outside the +supported range is treated as an attempt to use the minimum or maximum +supported value. + + A niceness should not be confused with a scheduling priority, which +lets applications determine the order in which threads are scheduled to +run. Unlike a priority, a niceness is merely advice to the scheduler, +which the scheduler is free to ignore. Also, as a point of +terminology, POSIX defines the behavior of `nice' in terms of a "nice +value", which is the nonnegative difference between a niceness and the +minimum niceness. Though `nice' conforms to POSIX, its documentation +and diagnostics use the term "niceness" for compatibility with +historical practice. + + COMMAND must not be a special built-in utility (*note Special +built-in utilities::). + + Because many shells have a built-in `nice' command, using an +unadorned `nice' in a script or interactively may get you different +functionality than that described here. + + The program accepts the following option. Also see *Note Common +options::. Options must precede operands. + +`-n ADJUSTMENT' +`--adjustment=ADJUSTMENT' + Add ADJUSTMENT instead of 10 to the command's niceness. If + ADJUSTMENT is negative and you lack appropriate privileges, `nice' + issues a warning but otherwise acts as if you specified a zero + adjustment. + + For compatibility `nice' also supports an obsolete option syntax + `-ADJUSTMENT'. New scripts should use `-n ADJUSTMENT' instead. + + + Exit status: + + 0 if no COMMAND is specified and the niceness is output + 1 if `nice' itself fails + 126 if COMMAND is found but cannot be invoked + 127 if COMMAND cannot be found + the exit status of COMMAND otherwise + + It is sometimes useful to run a non-interactive program with reduced +niceness. + + $ nice factor 4611686018427387903 + + Since `nice' prints the current niceness, you can invoke it through +itself to demonstrate how it works. + + The default behavior is to increase the niceness by `10': + + $ nice + 0 + $ nice nice + 10 + $ nice -n 10 nice + 10 + + The ADJUSTMENT is relative to the current niceness. In the next +example, the first `nice' invocation runs the second one with niceness +10, and it in turn runs the final one with a niceness that is 3 more: + + $ nice nice -n 3 nice + 13 + + Specifying a niceness larger than the supported range is the same as +specifying the maximum supported value: + + $ nice -n 10000000000 nice + 19 + + Only a privileged user may run a process with lower niceness: + + $ nice -n -1 nice + nice: cannot set niceness: Permission denied + 0 + $ sudo nice -n -1 nice + -1 + + +File: coreutils.info, Node: nohup invocation, Next: su invocation, Prev: nice invocation, Up: Modified command invocation + +22.4 `nohup': Run a command immune to hangups +============================================= + +`nohup' runs the given COMMAND with hangup signals ignored, so that the +command can continue running in the background after you log out. +Synopsis: + + nohup COMMAND [ARG]... + + If standard input is a terminal, it is redirected from `/dev/null' +so that terminal sessions do not mistakenly consider the terminal to be +used by the command. This is a GNU extension; programs intended to be +portable to non-GNU hosts should use `nohup COMMAND [ARG]... </dev/null' +instead. + + If standard output is a terminal, the command's standard output is +appended to the file `nohup.out'; if that cannot be written to, it is +appended to the file `$HOME/nohup.out'; and if that cannot be written +to, the command is not run. Any `nohup.out' or `$HOME/nohup.out' file +created by `nohup' is made readable and writable only to the user, +regardless of the current umask settings. + + If standard error is a terminal, it is normally redirected to the +same file descriptor as the (possibly-redirected) standard output. +However, if standard output is closed, standard error terminal output +is instead appended to the file `nohup.out' or `$HOME/nohup.out' as +above. + + `nohup' does not automatically put the command it runs in the +background; you must do that explicitly, by ending the command line +with an `&'. Also, `nohup' does not alter the niceness of COMMAND; use +`nice' for that, e.g., `nohup nice COMMAND'. + + COMMAND must not be a special built-in utility (*note Special +built-in utilities::). + + The only options are `--help' and `--version'. *Note Common +options::. Options must precede operands. + + Exit status: + + 126 if COMMAND is found but cannot be invoked + 127 if `nohup' itself fails or if COMMAND cannot be found + the exit status of COMMAND otherwise + + +File: coreutils.info, Node: su invocation, Prev: nohup invocation, Up: Modified command invocation + +22.5 `su': Run a command with substitute user and group ID +========================================================== + +`su' allows one user to temporarily become another user. It runs a +command (often an interactive shell) with the real and effective user +ID, group ID, and supplemental groups of a given USER. Synopsis: + + su [OPTION]... [USER [ARG]...] + + If no USER is given, the default is `root', the super-user. The +shell to use is taken from USER's `passwd' entry, or `/bin/sh' if none +is specified there. If USER has a password, `su' prompts for the +password unless run by a user with effective user ID of zero (the +super-user). + + By default, `su' does not change the current directory. It sets the +environment variables `HOME' and `SHELL' from the password entry for +USER, and if USER is not the super-user, sets `USER' and `LOGNAME' to +USER. By default, the shell is not a login shell. + + Any additional ARGs are passed as additional arguments to the shell. + + GNU `su' does not treat `/bin/sh' or any other shells specially +(e.g., by setting `argv[0]' to `-su', passing `-c' only to certain +shells, etc.). + + `su' can optionally be compiled to use `syslog' to report failed, +and optionally successful, `su' attempts. (If the system supports +`syslog'.) However, GNU `su' does not check if the user is a member of +the `wheel' group; see below. + + The program accepts the following options. Also see *Note Common +options::. + +`-c COMMAND' +`--command=COMMAND' + Pass COMMAND, a single command line to run, to the shell with a + `-c' option instead of starting an interactive shell. + +`-f' +`--fast' + Pass the `-f' option to the shell. This probably only makes sense + if the shell run is `csh' or `tcsh', for which the `-f' option + prevents reading the startup file (`.cshrc'). With Bourne-like + shells, the `-f' option disables file name pattern expansion + (globbing), which is not likely to be useful. + +`-' +`-l' +`--login' + Make the shell a login shell. This means the following. Unset all + environment variables except `TERM', `HOME', and `SHELL' (which + are set as described above), and `USER' and `LOGNAME' (which are + set, even for the super-user, as described above), and set `PATH' + to a compiled-in default value. Change to USER's home directory. + Prepend `-' to the shell's name, intended to make it read its + login startup file(s). + +`-m' +`-p' +`--preserve-environment' + Do not change the environment variables `HOME', `USER', `LOGNAME', + or `SHELL'. Run the shell given in the environment variable + `SHELL' instead of the shell from USER's passwd entry, unless the + user running `su' is not the super-user and USER's shell is + restricted. A "restricted shell" is one that is not listed in the + file `/etc/shells', or in a compiled-in list if that file does not + exist. Parts of what this option does can be overridden by + `--login' and `--shell'. + +`-s SHELL' +`--shell=SHELL' + Run SHELL instead of the shell from USER's passwd entry, unless + the user running `su' is not the super-user and USER's shell is + restricted (see `-m' just above). + + + Exit status: + + 1 if `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 + +22.5.1 Why GNU `su' does not support the `wheel' group +------------------------------------------------------ + +(This section is by Richard Stallman.) + + Sometimes a few of the users try to hold total power over all the +rest. For example, in 1984, a few users at the MIT AI lab decided to +seize power by changing the operator password on the Twenex system and +keeping it secret from everyone else. (I was able to thwart this coup +and give power back to the users by patching the kernel, but I wouldn't +know how to do that in Unix.) + + However, occasionally the rulers do tell someone. Under the usual +`su' mechanism, once someone learns the root password who sympathizes +with the ordinary users, he or she can tell the rest. The "wheel +group" feature would make this impossible, and thus cement the power of +the rulers. + + I'm on the side of the masses, not that of the rulers. If you are +used to supporting the bosses and sysadmins in whatever they do, you +might find this idea strange at first. + + +File: coreutils.info, Node: Process control, Next: Delaying, Prev: Modified command invocation, Up: Top + +23 Process control +****************** + +* Menu: + +* kill invocation:: Sending a signal to processes. + + +File: coreutils.info, Node: kill invocation, Up: Process control + +23.1 `kill': Send a signal to processes +======================================= + +The `kill' command sends a signal to processes, causing them to +terminate or otherwise act upon receiving the signal in some way. +Alternatively, it lists information about signals. Synopses: + + kill [-s SIGNAL | --signal SIGNAL | -SIGNAL] PID... + kill [-l | --list | -t | --table] [SIGNAL]... + + The first form of the `kill' command sends a signal to all PID +arguments. The default signal to send if none is specified is `TERM'. +The special signal number `0' does not denote a valid signal, but can +be used to test whether the PID arguments specify processes to which a +signal could be sent. + + If PID is positive, the signal is sent to the process with the +process ID PID. If PID is zero, the signal is sent to all processes in +the process group of the current process. If PID is -1, the signal is +sent to all processes for which the user has permission to send a +signal. If PID is less than -1, the signal is sent to all processes in +the process group that equals the absolute value of PID. + + If PID is not positive, a system-dependent set of system processes +is excluded from the list of processes to which the signal is sent. + + If a negative PID argument is desired as the first one, it should be +preceded by `--'. However, as a common extension to POSIX, `--' is not +required with `kill -SIGNAL -PID'. The following commands are +equivalent: + + kill -15 -1 + kill -TERM -1 + kill -s TERM -- -1 + kill -- -1 + + The first form of the `kill' command succeeds if every PID argument +specifies at least one process that the signal was sent to. + + The second form of the `kill' command lists signal information. +Either the `-l' or `--list' option, or the `-t' or `--table' option +must be specified. Without any SIGNAL argument, all supported signals +are listed. The output of `-l' or `--list' is a list of the signal +names, one per line; if SIGNAL is already a name, the signal number is +printed instead. The output of `-t' or `--table' is a table of signal +numbers, names, and descriptions. This form of the `kill' command +succeeds if all SIGNAL arguments are valid and if there is no output +error. + + The `kill' command also supports the `--help' and `--version' +options. *Note Common options::. + + A SIGNAL may be a signal name like `HUP', or a signal number like +`1', or an exit status of a process terminated by the signal. A signal +name can be given in canonical form or prefixed by `SIG'. The case of +the letters is ignored, except for the `-SIGNAL' option which must use +upper case to avoid ambiguity with lower case option letters. The +following signal names and numbers are supported on all POSIX compliant +systems: + +`HUP' + 1. Hangup. + +`INT' + 2. Terminal interrupt. + +`QUIT' + 3. Terminal quit. + +`ABRT' + 6. Process abort. + +`KILL' + 9. Kill (cannot be caught or ignored). + +`ALRM' + 14. Alarm Clock. + +`TERM' + 15. Termination. + +Other supported signal names have system-dependent corresponding +numbers. All systems conforming to POSIX 1003.1-2001 also support the +following signals: + +`BUS' + Access to an undefined portion of a memory object. + +`CHLD' + Child process terminated, stopped, or continued. + +`CONT' + Continue executing, if stopped. + +`FPE' + Erroneous arithmetic operation. + +`ILL' + Illegal Instruction. + +`PIPE' + Write on a pipe with no one to read it. + +`SEGV' + Invalid memory reference. + +`STOP' + Stop executing (cannot be caught or ignored). + +`TSTP' + Terminal stop. + +`TTIN' + Background process attempting read. + +`TTOU' + Background process attempting write. + +`URG' + High bandwidth data is available at a socket. + +`USR1' + User-defined signal 1. + +`USR2' + User-defined signal 2. + +POSIX 1003.1-2001 systems that support the XSI extension also support +the following signals: + +`POLL' + Pollable event. + +`PROF' + Profiling timer expired. + +`SYS' + Bad system call. + +`TRAP' + Trace/breakpoint trap. + +`VTALRM' + Virtual timer expired. + +`XCPU' + CPU time limit exceeded. + +`XFSZ' + File size limit exceeded. + +POSIX 1003.1-2001 systems that support the XRT extension also support +at least eight real-time signals called `RTMIN', `RTMIN+1', ..., +`RTMAX-1', `RTMAX'. + + +File: coreutils.info, Node: Delaying, Next: Numeric operations, Prev: Process control, Up: Top + +24 Delaying +*********** + +* Menu: + +* sleep invocation:: Delay for a specified time. + + +File: coreutils.info, Node: sleep invocation, Up: Delaying + +24.1 `sleep': Delay for a specified time +======================================== + +`sleep' pauses for an amount of time specified by the sum of the values +of the command line arguments. Synopsis: + + sleep NUMBER[smhd]... + + Each argument is a number followed by an optional unit; the default +is seconds. The units are: + +`s' + seconds + +`m' + minutes + +`h' + hours + +`d' + days + + Historical implementations of `sleep' have required that NUMBER be +an integer, and only accepted a single argument without a suffix. +However, GNU `sleep' accepts arbitrary floating point numbers (using a +period before any fractional digits). + + The only options are `--help' and `--version'. *Note Common +options::. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: Numeric operations, Next: File permissions, Prev: Delaying, Up: Top + +25 Numeric operations +********************* + +These programs do numerically-related operations. + +* Menu: + +* factor invocation:: Show factors of numbers. +* seq invocation:: Print sequences of numbers. + + +File: coreutils.info, Node: factor invocation, Next: seq invocation, Up: Numeric operations + +25.1 `factor': Print prime factors +================================== + +`factor' prints prime factors. Synopses: + + factor [NUMBER]... + factor OPTION + + If no NUMBER is specified on the command line, `factor' reads +numbers from standard input, delimited by newlines, tabs, or spaces. + + The only options are `--help' and `--version'. *Note Common +options::. + + The algorithm it uses is not very sophisticated, so for some inputs +`factor' runs for a long time. The hardest numbers to factor are the +products of large primes. Factoring the product of the two largest +32-bit prime numbers takes about 80 seconds of CPU time on a 1.6 GHz +Athlon. + + $ p=`echo '4294967279 * 4294967291'|bc` + $ factor $p + 18446743979220271189: 4294967279 4294967291 + + Similarly, it takes about 80 seconds for GNU factor (from +coreutils-5.1.2) to "factor" the largest 64-bit prime: + + $ factor 18446744073709551557 + 18446744073709551557: 18446744073709551557 + + In contrast, `factor' factors the largest 64-bit number in just over +a tenth of a second: + + $ factor `echo '2^64-1'|bc` + 18446744073709551615: 3 5 17 257 641 65537 6700417 + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: seq invocation, Prev: factor invocation, Up: Numeric operations + +25.2 `seq': Print numeric sequences +=================================== + +`seq' prints a sequence of numbers to standard output. Synopses: + + seq [OPTION]... LAST + seq [OPTION]... FIRST LAST + seq [OPTION]... FIRST INCREMENT LAST + + `seq' prints the numbers from FIRST to LAST by INCREMENT. By +default, each number is printed on a separate line. When INCREMENT is +not specified, it defaults to `1', even when FIRST is larger than LAST. +FIRST also defaults to `1'. So `seq 1' prints `1', but `seq 0' and +`seq 10 5' produce no output. Floating-point numbers may be specified +(using a period before any fractional digits). + + The program accepts the following options. Also see *Note Common +options::. Options must precede operands. + +`-f FORMAT' +`--format=FORMAT' + Print all numbers using FORMAT. FORMAT must contain exactly one + of the `printf'-style floating point conversion specifications + `%a', `%e', `%f', `%g', `%A', `%E', `%F', `%G'. The `%' may be + followed by zero or more flags taken from the set `-+#0 '', then + an optional width containing one or more digits, then an optional + precision consisting of a `.' followed by zero or more digits. + FORMAT may also contain any number of `%%' conversion + specifications. All conversion specifications have the same + meaning as with `printf'. + + The default format is derived from FIRST, STEP, and LAST. If + these all use a fixed point decimal representation, the default + format is `%.Pf', where P is the minimum precision that can + represent the output numbers exactly. Otherwise, the default + format is `%g'. + +`-s STRING' +`--separator=STRING' + Separate numbers with STRING; default is a newline. The output + always terminates with a newline. + +`-w' +`--equal-width' + Print all numbers with the same width, by padding with leading + zeros. FIRST, STEP, and LAST should all use a fixed point decimal + representation. (To have other kinds of padding, use `--format'). + + + You can get finer-grained control over output with `-f': + + $ seq -f '(%9.2E)' -9e5 1.1e6 1.3e6 + (-9.00E+05) + ( 2.00E+05) + ( 1.30E+06) + + If you want hexadecimal integer output, you can use `printf' to +perform the conversion: + + $ printf '%x\n' `seq 1048575 1024 1050623` + fffff + 1003ff + 1007ff + + For very long lists of numbers, use xargs to avoid system +limitations on the length of an argument list: + + $ seq 1000000 | xargs printf '%x\n' | tail -n 3 + f423e + f423f + f4240 + + To generate octal output, use the printf `%o' format instead of `%x'. + + On most systems, seq can produce whole-number output for values up to +at least `2^53'. Larger integers are approximated. The details differ +depending on your floating-point implementation, but a common case is +that `seq' works with integers through `2^64', and larger integers may +not be numerically correct: + + $ seq 18446744073709551616 1 18446744073709551618 + 18446744073709551616 + 18446744073709551616 + 18446744073709551618 + + Be careful when using `seq' with a fractional INCREMENT; otherwise +you may see surprising results. Most people would expect to see +`0.000003' printed as the last number in this example: + + $ seq -s ' ' 0 0.000001 0.000003 + 0.000000 0.000001 0.000002 + + But that doesn't happen on many systems because `seq' is implemented +using binary floating point arithmetic (via the C `long double' +type)--which means decimal fractions like `0.000001' cannot be +represented exactly. That in turn means some nonintuitive conditions +like `0.000001 * 3 > 0.000003' will end up being true. + + To work around that in the above example, use a slightly larger +number as the LAST value: + + $ seq -s ' ' 0 0.000001 0.0000031 + 0.000000 0.000001 0.000002 0.000003 + + In general, when using an INCREMENT with a fractional part, where +(LAST - FIRST) / INCREMENT is (mathematically) a whole number, specify +a slightly larger (or smaller, if INCREMENT is negative) value for LAST +to ensure that LAST is the final value printed by seq. + + An exit status of zero indicates success, and a nonzero value +indicates failure. + + +File: coreutils.info, Node: File permissions, Next: Date input formats, Prev: Numeric operations, Up: Top + +26 File permissions +******************* + +Each file has a set of "file mode bits" that control the kinds of +access that users have to that file. They can be represented either in +symbolic form or as an octal number. + +* Menu: + +* 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. + + +File: coreutils.info, Node: Mode Structure, Next: Symbolic Modes, Up: File permissions + +26.1 Structure of File Mode Bits +================================ + +The file mode bits have two parts: the "file permission bits", which +control ordinary access to the file, and "special mode bits", which +affect only some files. + + There are three kinds of permissions that a user can have for a file: + + 1. permission to read the file. For directories, this means + permission to list the contents of the directory. + + 2. permission to write to (change) the file. For directories, this + means permission to create and remove files in the directory. + + 3. permission to execute the file (run it as a program). For + directories, this means permission to access files in the + directory. + + There are three categories of users who may have different +permissions to perform any of the above operations on a file: + + 1. the file's owner; + + 2. other users who are in the file's group; + + 3. everyone else. + + Files are given an owner and group when they are created. Usually +the owner is the current user and the group is the group of the +directory the file is in, but this varies with the operating system, the +file system the file is created on, and the way the file is created. +You can change the owner and group of a file by using the `chown' and +`chgrp' commands. + + In addition to the three sets of three permissions listed above, the +file mode bits have three special components, which affect only +executable files (programs) and, on most systems, directories: + + 1. Set the process's effective user ID to that of the file upon + execution (called the "set-user-ID bit", or sometimes the "setuid + bit"). For directories on a few systems, give files created in + the directory the same owner as the directory, no matter who + creates them, and set the set-user-ID bit of newly-created + subdirectories. + + 2. Set the process's effective group ID to that of the file upon + execution (called the "set-group-ID bit", or sometimes the "setgid + bit"). For directories on most systems, give files created in the + directory the same group as the directory, no matter what group + the user who creates them is in, and set the set-group-ID bit of + newly-created subdirectories. + + 3. Prevent unprivileged users from removing or renaming a file in a + directory unless they own the file or the directory; this is + called the "restricted deletion flag" for the directory, and is + commonly found on world-writable directories like `/tmp'. + + For regular files on some older systems, save the program's text + image on the swap device so it will load more quickly when run; + this is called the "sticky bit". + + In addition to the file mode bits listed above, there may be file +attributes specific to the file system, e.g., access control lists +(ACLs), whether a file is compressed, whether a file can be modified +(immutability), and whether a file can be dumped. These are usually +set using programs specific to the file system. For example: + +ext2 + On GNU and GNU/Linux the file attributes specific to the ext2 file + system are set using `chattr'. + +FFS + On FreeBSD the file flags specific to the FFS file system are set + using `chflags'. + + Even if a file's mode bits allow an operation on that file, that +operation may still fail, because: + + * the file-system-specific attributes or flags do not permit it; or + + * the file system is mounted as read-only. + + For example, if the immutable attribute is set on a file, it cannot +be modified, regardless of the fact that you may have just run `chmod +a+w FILE'. + + +File: coreutils.info, Node: Symbolic Modes, Next: Numeric Modes, Prev: Mode Structure, Up: File permissions + +26.2 Symbolic Modes +=================== + +"Symbolic modes" represent changes to files' mode bits as operations on +single-character symbols. They allow you to modify either all or +selected parts of files' mode bits, optionally based on their previous +values, and perhaps on the current `umask' as well (*note Umask and +Protection::). + + The format of symbolic modes is: + + [ugoa...][+-=]PERMS...[,...] + +where PERMS is either zero or more letters from the set `rwxXst', or a +single letter from the set `ugo'. + + The following sections describe the operators and other details of +symbolic modes. + +* Menu: + +* Setting Permissions:: Basic operations on permissions. +* Copying Permissions:: Copying existing permissions. +* Changing Special Mode Bits:: Special mode bits. +* Conditional Executability:: Conditionally affecting executability. +* Multiple Changes:: Making multiple changes. +* Umask and Protection:: The effect of the umask. + + +File: coreutils.info, Node: Setting Permissions, Next: Copying Permissions, Up: Symbolic Modes + +26.2.1 Setting Permissions +-------------------------- + +The basic symbolic operations on a file's permissions are adding, +removing, and setting the permission that certain users have to read, +write, and execute or search the file. These operations have the +following format: + + USERS OPERATION PERMISSIONS + +The spaces between the three parts above are shown for readability only; +symbolic modes cannot contain spaces. + + The USERS part tells which users' access to the file is changed. It +consists of one or more of the following letters (or it can be empty; +*note Umask and Protection::, for a description of what happens then). +When more than one of these letters is given, the order that they are +in does not matter. + +`u' + the user who owns the file; + +`g' + other users who are in the file's group; + +`o' + all other users; + +`a' + all users; the same as `ugo'. + + The OPERATION part tells how to change the affected users' access to +the file, and is one of the following symbols: + +`+' + to add the PERMISSIONS to whatever permissions the USERS already + have for the file; + +`-' + to remove the PERMISSIONS from whatever permissions the USERS + already have for the file; + +`=' + to make the PERMISSIONS the only permissions that the USERS have + for the file. + + The PERMISSIONS part tells what kind of access to the file should be +changed; it is normally zero or more of the following letters. As with +the USERS part, the order does not matter when more than one letter is +given. Omitting the PERMISSIONS part is useful only with the `=' +operation, where it gives the specified USERS no access at all to the +file. + +`r' + the permission the USERS have to read the file; + +`w' + the permission the USERS have to write to the file; + +`x' + the permission the USERS have to execute the file, or search it if + it is a directory. + + For example, to give everyone permission to read and write a regular +file, but not to execute it, use: + + a=rw + + To remove write permission for all users other than the file's +owner, use: + + go-w + +The above command does not affect the access that the owner of the file +has to it, nor does it affect whether other users can read or execute +the file. + + To give everyone except a file's owner no permission to do anything +with that file, use the mode below. Other users could still remove the +file, if they have write permission on the directory it is in. + + go= + +Another way to specify the same thing is: + + og-rwx + + +File: coreutils.info, Node: Copying Permissions, Next: Changing Special Mode Bits, Prev: Setting Permissions, Up: Symbolic Modes + +26.2.2 Copying Existing Permissions +----------------------------------- + +You can base a file's permissions on its existing permissions. To do +this, instead of using a series of `r', `w', or `x' letters after the +operator, you use the letter `u', `g', or `o'. For example, the mode + + o+g + +adds the permissions for users who are in a file's group to the +permissions that other users have for the file. Thus, if the file +started out as mode 664 (`rw-rw-r--'), the above mode would change it +to mode 666 (`rw-rw-rw-'). If the file had started out as mode 741 +(`rwxr----x'), the above mode would change it to mode 745 +(`rwxr--r-x'). The `-' and `=' operations work analogously. + + +File: coreutils.info, Node: Changing Special Mode Bits, Next: Conditional Executability, Prev: Copying Permissions, Up: Symbolic Modes + +26.2.3 Changing Special Mode Bits +--------------------------------- + +In addition to changing a file's read, write, and execute/search +permissions, you can change its special mode bits. *Note Mode +Structure::, for a summary of these special mode bits. + + To change the file mode bits to set the user ID on execution, use +`u' in the USERS part of the symbolic mode and `s' in the PERMISSIONS +part. + + To change the file mode bits to set the group ID on execution, use +`g' in the USERS part of the symbolic mode and `s' in the PERMISSIONS +part. + + To set both user and group ID on execution, omit the USERS part of +the symbolic mode (or use `a') and use `s' in the PERMISSIONS part. + + To change the file mode bits to set the restricted deletion flag or +sticky bit, omit the USERS part of the symbolic mode (or use `a') and +use `t' in the PERMISSIONS part. + + For example, to set the set-user-ID mode bit of a program, you can +use the mode: + + u+s + + To remove both set-user-ID and set-group-ID mode bits from it, you +can use the mode: + + a-s + + To set the restricted deletion flag or sticky bit, you can use the +mode: + + +t + + The combination `o+s' has no effect. On GNU systems the +combinations `u+t' and `g+t' have no effect, and `o+t' acts like plain +`+t'. + + The `=' operator is not very useful with special mode bits. For +example, the mode: + + o=t + +does set the restricted deletion flag or sticky bit, but it also +removes all read, write, and execute/search permissions that users not +in the file's group might have had for it. + + *Note Directory Setuid and Setgid::, for additional rules concerning +set-user-ID and set-group-ID bits and directories. + + +File: coreutils.info, Node: Conditional Executability, Next: Multiple Changes, Prev: Changing Special Mode Bits, Up: Symbolic Modes + +26.2.4 Conditional Executability +-------------------------------- + +There is one more special type of symbolic permission: if you use `X' +instead of `x', execute/search permission is affected only if the file +is a directory or already had execute permission. + + For example, this mode: + + a+X + +gives all users permission to search directories, or to execute files if +anyone could execute them before. + + +File: coreutils.info, Node: Multiple Changes, Next: Umask and Protection, Prev: Conditional Executability, Up: Symbolic Modes + +26.2.5 Making Multiple Changes +------------------------------ + +The format of symbolic modes is actually more complex than described +above (*note Setting Permissions::). It provides two ways to make +multiple changes to files' mode bits. + + The first way is to specify multiple OPERATION and PERMISSIONS parts +after a USERS part in the symbolic mode. + + For example, the mode: + + og+rX-w + +gives users other than the owner of the file read permission and, if it +is a directory or if someone already had execute permission to it, +gives them execute/search permission; and it also denies them write +permission to the file. It does not affect the permission that the +owner of the file has for it. The above mode is equivalent to the two +modes: + + og+rX + og-w + + The second way to make multiple changes is to specify more than one +simple symbolic mode, separated by commas. For example, the mode: + + a+r,go-w + +gives everyone permission to read the file and removes write permission +on it for all users except its owner. Another example: + + u=rwx,g=rx,o= + +sets all of the permission bits for the file explicitly. (It gives +users who are not in the file's group no permission at all for it.) + + The two methods can be combined. The mode: + + a+r,g+x-w + +gives all users permission to read the file, and gives users who are in +the file's group permission to execute/search it as well, but not +permission to write to it. The above mode could be written in several +different ways; another is: + + u+r,g+rx,o+r,g-w + + +File: coreutils.info, Node: Umask and Protection, Prev: Multiple Changes, Up: Symbolic Modes + +26.2.6 The Umask and Protection +------------------------------- + +If the USERS part of a symbolic mode is omitted, it defaults to `a' +(affect all users), except that any permissions that are _set_ in the +system variable `umask' are _not affected_. The value of `umask' can +be set using the `umask' command. Its default value varies from system +to system. + + Omitting the USERS part of a symbolic mode is generally not useful +with operations other than `+'. It is useful with `+' because it +allows you to use `umask' as an easily customizable protection against +giving away more permission to files than you intended to. + + As an example, if `umask' has the value 2, which removes write +permission for users who are not in the file's group, then the mode: + + +w + +adds permission to write to the file to its owner and to other users who +are in the file's group, but _not_ to other users. In contrast, the +mode: + + a+w + +ignores `umask', and _does_ give write permission for the file to all +users. + + +File: coreutils.info, Node: Numeric Modes, Next: Directory Setuid and Setgid, Prev: Symbolic Modes, Up: File permissions + +26.3 Numeric Modes +================== + +As an alternative to giving a symbolic mode, you can give an octal +(base 8) number that represents the mode. This number is always +interpreted in octal; you do not have to add a leading `0', as you do +in C. Mode `0055' is the same as mode `55'. + + A numeric mode is usually shorter than the corresponding symbolic +mode, but it is limited in that normally it cannot take into account the +previous file mode bits; it can only set them absolutely. (As +discussed in the next section, the set-user-ID and set-group-ID bits of +directories are an exception to this general limitation.) + + The permissions granted to the user, to other users in the file's +group, and to other users not in the file's group each require three +bits, which are represented as one octal digit. The three special mode +bits also require one bit each, and they are as a group represented as +another octal digit. Here is how the bits are arranged, starting with +the lowest valued bit: + + Value in Corresponding + Mode Mode Bit + + Other users not in the file's group: + 1 Execute/search + 2 Write + 4 Read + + Other users in the file's group: + 10 Execute/search + 20 Write + 40 Read + + The file's owner: + 100 Execute/search + 200 Write + 400 Read + + Special mode bits: + 1000 Restricted deletion flag or sticky bit + 2000 Set group ID on execution + 4000 Set user ID on execution + + For example, numeric mode `4755' corresponds to symbolic mode +`u=rwxs,go=rx', and numeric mode `664' corresponds to symbolic mode +`ug=rw,o=r'. Numeric mode `0' corresponds to symbolic mode `a='. + + +File: coreutils.info, Node: Directory Setuid and Setgid, Prev: Numeric Modes, Up: File permissions + +26.4 Directories and the Set-User-ID and Set-Group-ID Bits +========================================================== + +On most systems, if a directory's set-group-ID bit is set, newly +created subfiles inherit the same group as the directory, and newly +created subdirectories inherit the set-group-ID bit of the parent +directory. On a few systems, a directory's set-user-ID bit has a +similar effect on the ownership of new subfiles and the set-user-ID +bits of new subdirectories. These mechanisms let users share files +more easily, by lessening the need to use `chmod' or `chown' to share +new files. + + These convenience mechanisms rely on the set-user-ID and set-group-ID +bits of directories. If commands like `chmod' and `mkdir' routinely +cleared these bits on directories, the mechanisms would be less +convenient and it would be harder to share files. Therefore, a command +like `chmod' does not affect the set-user-ID or set-group-ID bits of a +directory unless the user specifically mentions them in a symbolic +mode, or sets them in a numeric mode. For example, on systems that +support set-group-ID inheritance: + + # These commands leave the set-user-ID and + # set-group-ID bits of the subdirectories alone, + # so that they retain their default values. + mkdir A B C + chmod 755 A + chmod 0755 B + chmod u=rwx,go=rx C + mkdir -m 755 D + mkdir -m 0755 E + mkdir -m u=rwx,go=rx F + + If you want to try to set these bits, you must mention them +explicitly in the symbolic or numeric modes, e.g.: + + # These commands try to set the set-user-ID + # and set-group-ID bits of the subdirectories. + mkdir G H + chmod 6755 G + chmod u=rwx,go=rx,a+s H + mkdir -m 6755 I + mkdir -m u=rwx,go=rx,a+s J + + If you want to try to clear these bits, you must mention them +explicitly in a symbolic mode, e.g.: + + # This command tries to clear the set-user-ID + # and set-group-ID bits of the directory D. + chmod a-s D + + This behavior is a GNU extension. Portable scripts should not rely +on requests to set or clear these bits on directories, as POSIX allows +implementations to ignore these requests. + + +File: coreutils.info, Node: Date input formats, Next: Opening the software toolbox, Prev: File permissions, Up: Top + +27 Date input formats +********************* + +First, a quote: + + Our units of temporal measurement, from seconds on up to months, + are so complicated, asymmetrical and disjunctive so as to make + coherent mental reckoning in time all but impossible. Indeed, had + some tyrannical god contrived to enslave our minds to time, to + make it all but impossible for us to escape subjection to sodden + routines and unpleasant surprises, he could hardly have done + better than handing down our present system. It is like a set of + trapezoidal building blocks, with no vertical or horizontal + surfaces, like a language in which the simplest thought demands + ornate constructions, useless particles and lengthy + circumlocutions. Unlike the more successful patterns of language + and science, which enable us to face experience boldly or at least + level-headedly, our system of temporal calculation silently and + persistently encourages our terror of time. + + ... It is as though architects had to measure length in feet, + width in meters and height in ells; as though basic instruction + manuals demanded a knowledge of five different languages. It is + no wonder then that we often look into our own immediate past or + future, last Tuesday or a week from Sunday, with feelings of + helpless confusion. ... + + -- Robert Grudin, `Time and the Art of Living'. + + This section describes the textual date representations that GNU +programs accept. These are the strings you, as a user, can supply as +arguments to the various programs. The C interface (via the `get_date' +function) is not described here. + +* Menu: + +* General date syntax:: Common rules. +* Calendar date items:: 19 Dec 1994. +* Time of day items:: 9:20pm. +* Time zone items:: EST, PDT, 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. + + +File: coreutils.info, Node: General date syntax, Next: Calendar date items, Up: Date input formats + +27.1 General date syntax +======================== + +A "date" is a string, possibly empty, containing many items separated +by whitespace. The whitespace may be omitted when no ambiguity arises. +The empty string means the beginning of today (i.e., midnight). Order +of the items is immaterial. A date string may contain many flavors of +items: + + * calendar date items + + * time of day items + + * time zone items + + * day of the week items + + * relative items + + * pure numbers. + +We describe each of these item types in turn, below. + + A few ordinal numbers may be written out in words in some contexts. +This is most useful for specifying day of the week items or relative +items (see below). Among the most commonly used ordinal numbers, the +word `last' stands for -1, `this' stands for 0, and `first' and `next' +both stand for 1. Because the word `second' stands for the unit of +time there is no way to write the ordinal number 2, but for convenience +`third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6, +`seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10, +`eleventh' for 11 and `twelfth' for 12. + + When a month is written this way, it is still considered to be +written numerically, instead of being "spelled in full"; this changes +the allowed strings. + + In the current implementation, only English is supported for words +and abbreviations like `AM', `DST', `EST', `first', `January', +`Sunday', `tomorrow', and `year'. + + The output of the `date' command is not always acceptable as a date +string, not only because of the language problem, but also because +there is no standard meaning for time zone items like `IST'. When using +`date' to generate a date string intended to be parsed later, specify a +date format that is independent of language and that does not use time +zone items other than `UTC' and `Z'. Here are some ways to do this: + + $ LC_ALL=C TZ=UTC0 date + Mon Mar 1 00:21:42 UTC 2004 + $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' + 2004-03-01 00:21:42Z + $ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. + 2004-02-29 16:21:42,692722128-0800 + $ date --rfc-2822 # a GNU extension + Sun, 29 Feb 2004 16:21:42 -0800 + $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. + 2004-02-29 16:21:42 -0800 + $ date +'@%s.%N' # %s and %N are GNU extensions. + @1078100502.692722128 + + Alphabetic case is completely ignored in dates. Comments may be +introduced between round parentheses, as long as included parentheses +are properly nested. Hyphens not followed by a digit are currently +ignored. Leading zeros on numbers are ignored. + + Invalid dates like `2005-02-29' or times like `24:00' are rejected. +In the typical case of a host that does not support leap seconds, a +time like `23:59:60' is rejected even if it corresponds to a valid leap +second. + + +File: coreutils.info, Node: Calendar date items, Next: Time of day items, Prev: General date syntax, Up: Date input formats + +27.2 Calendar date items +======================== + +A "calendar date item" specifies a day of the year. It is specified +differently, depending on whether the month is specified numerically or +literally. All these strings specify the same calendar date: + + 1972-09-24 # ISO 8601. + 72-9-24 # Assume 19xx for 69 through 99, + # 20xx for 00 through 68. + 72-09-24 # Leading zeros are ignored. + 9/24/72 # Common U.S. writing. + 24 September 1972 + 24 Sept 72 # September has a special abbreviation. + 24 Sep 72 # Three-letter abbreviations always allowed. + Sep 24, 1972 + 24-sep-72 + 24sep72 + + The year can also be omitted. In this case, the last specified year +is used, or the current year if none. For example: + + 9/24 + sep 24 + + Here are the rules. + + For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed, +where YEAR is any positive number, MONTH is a number between 01 and 12, +and DAY is a number between 01 and 31. A leading zero must be present +if a number is less than ten. If YEAR is 68 or smaller, then 2000 is +added to it; otherwise, if YEAR is less than 100, then 1900 is added to +it. The construct `MONTH/DAY/YEAR', popular in the United States, is +accepted. Also `MONTH/DAY', omitting the year. + + Literal months may be spelled out in full: `January', `February', +`March', `April', `May', `June', `July', `August', `September', +`October', `November' or `December'. Literal months may be abbreviated +to their first three letters, possibly followed by an abbreviating dot. +It is also permitted to write `Sept' instead of `September'. + + When months are written literally, the calendar date may be given as +any of the following: + + DAY MONTH YEAR + DAY MONTH + MONTH DAY YEAR + DAY-MONTH-YEAR + + Or, omitting the year: + + MONTH DAY + + +File: coreutils.info, Node: Time of day items, Next: Time zone items, Prev: Calendar date items, Up: Date input formats + +27.3 Time of day items +====================== + +A "time of day item" in date strings specifies the time on a given day. +Here are some examples, all of which represent the same time: + + 20:02:00.000000 + 20:02 + 8:02pm + 20:02-0500 # In EST (U.S. Eastern Standard Time). + + More generally, the time of day may be given as +`HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE +is a number between 0 and 59, and SECOND is a number between 0 and 59 +possibly followed by `.' or `,' and a fraction containing one or more +digits. Alternatively, `:SECOND' can be omitted, in which case it is +taken to be zero. On the rare hosts that support leap seconds, SECOND +may be 60. + + If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR +is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken +to be zero). `am' indicates the first half of the day, `pm' indicates +the second half of the day. In this notation, 12 is the predecessor of +1: midnight is `12am' while noon is `12pm'. (This is the zero-oriented +interpretation of `12am' and `12pm', as opposed to the old tradition +derived from Latin which uses `12m' for noon and `12pm' for midnight.) + + The time may alternatively be followed by a time zone correction, +expressed as `SHHMM', where S is `+' or `-', HH is a number of zone +hours and MM is a number of zone minutes. You can also separate HH +from MM with a colon. When a time zone correction is given this way, it +forces interpretation of the time relative to Coordinated Universal +Time (UTC), overriding any previous specification for the time zone or +the local time zone. For example, `+0530' and `+05:30' both stand for +the time zone 5.5 hours ahead of UTC (e.g., India). The MINUTE part of +the time of day may not be elided when a time zone correction is used. +This is the best way to specify a time zone correction by fractional +parts of an hour. + + Either `am'/`pm' or a time zone correction may be specified, but not +both. + + +File: coreutils.info, Node: Time zone items, Next: Day of week items, Prev: Time of day items, Up: Date input formats + +27.4 Time zone items +==================== + +A "time zone item" specifies an international time zone, indicated by a +small set of letters, e.g., `UTC' or `Z' for Coordinated Universal +Time. Any included periods are ignored. By following a +non-daylight-saving time zone by the string `DST' in a separate word +(that is, separated by some white space), the corresponding daylight +saving time zone may be specified. Alternatively, a +non-daylight-saving time zone can be followed by a time zone +correction, to add the two values. This is normally done only for +`UTC'; for example, `UTC+05:30' is equivalent to `+05:30'. + + Time zone items other than `UTC' and `Z' are obsolescent and are not +recommended, because they are ambiguous; for example, `EST' has a +different meaning in Australia than in the United States. Instead, +it's better to use unambiguous numeric time zone corrections like +`-0500', as described in the previous section. + + If neither a time zone item nor a time zone correction is supplied, +time stamps are interpreted using the rules of the default time zone +(*note Specifying time zone rules::). + + +File: coreutils.info, Node: Day of week items, Next: Relative items in date strings, Prev: Time zone items, Up: Date input formats + +27.5 Day of week items +====================== + +The explicit mention of a day of the week will forward the date (only +if necessary) to reach that day of the week in the future. + + Days of the week may be spelled out in full: `Sunday', `Monday', +`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may +be abbreviated to their first three letters, optionally followed by a +period. The special abbreviations `Tues' for `Tuesday', `Wednes' for +`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed. + + A number may precede a day of the week item to move forward +supplementary weeks. It is best used in expression like `third +monday'. In this context, `last DAY' or `next DAY' is also acceptable; +they move one week before or after the day that DAY by itself would +represent. + + A comma following a day of the week item is ignored. + + +File: coreutils.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats + +27.6 Relative items in date strings +=================================== + +"Relative items" adjust a date (or the current date if none) forward or +backward. The effects of relative items accumulate. Here are some +examples: + + 1 year + 1 year ago + 3 years + 2 days + + The unit of time displacement may be selected by the string `year' +or `month' for moving by whole years or months. These are fuzzy units, +as years and months are not all of equal duration. More precise units +are `fortnight' which is worth 14 days, `week' worth 7 days, `day' +worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60 +seconds, and `second' or `sec' worth one second. An `s' suffix on +these units is accepted and ignored. + + The unit of time may be preceded by a multiplier, given as an +optionally signed number. Unsigned numbers are taken as positively +signed. No number at all implies 1 for a multiplier. Following a +relative item by the string `ago' is equivalent to preceding the unit +by a multiplier with value -1. + + The string `tomorrow' is worth one day in the future (equivalent to +`day'), the string `yesterday' is worth one day in the past (equivalent +to `day ago'). + + The strings `now' or `today' are relative items corresponding to +zero-valued time displacement, these strings come from the fact a +zero-valued time displacement represents the current time when not +otherwise changed by previous items. They may be used to stress other +items, like in `12:00 today'. The string `this' also has the meaning +of a zero-valued time displacement, but is preferred in date strings +like `this thursday'. + + When a relative item causes the resulting date to cross a boundary +where the clocks were adjusted, typically for daylight saving time, the +resulting date and time are adjusted accordingly. + + The fuzz in units can cause problems with relative items. For +example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because +2003-06-31 is an invalid date. To determine the previous month more +reliably, you can ask for the month before the 15th of the current +month. For example: + + $ date -R + Thu, 31 Jul 2003 13:02:39 -0700 + $ date --date='-1 month' +'Last month was %B?' + Last month was July? + $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' + Last month was June! + + Also, take care when manipulating dates around clock changes such as +daylight saving leaps. In a few cases these have added or subtracted +as much as 24 hours from the clock, so it is often wise to adopt +universal time by setting the `TZ' environment variable to `UTC0' +before embarking on calendrical calculations. + + +File: coreutils.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats + +27.7 Pure numbers in date strings +================================= + +The precise interpretation of a pure decimal number depends on the +context in the date string. + + If the decimal number is of the form YYYYMMDD and no other calendar +date item (*note Calendar date items::) appears before it in the date +string, then YYYY is read as the year, MM as the month number and DD as +the day of the month, for the specified calendar date. + + If the decimal number is of the form HHMM and no other time of day +item appears before it in the date string, then HH is read as the hour +of the day and MM as the minute of the hour, for the specified time of +day. MM can also be omitted. + + If both a calendar date and a time of day appear to the left of a +number in the date string, but no relative item, then the number +overrides the year. + + +File: coreutils.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats + +27.8 Seconds since the Epoch +============================ + +If you precede a number with `@', it represents an internal time stamp +as a count of seconds. The number can contain an internal decimal +point (either `.' or `,'); any excess precision not supported by the +internal representation is truncated toward minus infinity. Such a +number cannot be combined with any other date item, as it specifies a +complete time stamp. + + Internally, computer times are represented as a count of seconds +since an epoch--a well-defined point of time. On GNU and POSIX +systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this +time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and +most other POSIX-compliant systems support such times as an extension +to POSIX, using negative counts, so that `@-1' represents 1969-12-31 +23:59:59 UTC. + + Traditional Unix systems count seconds with 32-bit two's-complement +integers and can represent times from 1901-12-13 20:45:52 through +2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of +seconds with nanosecond subcounts, and can represent all the times in +the known lifetime of the universe to a resolution of 1 nanosecond. + + On most hosts, these counts ignore the presence of leap seconds. +For example, on most hosts `@915148799' represents 1998-12-31 23:59:59 +UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no +way to represent the intervening leap second 1998-12-31 23:59:60 UTC. + + +File: coreutils.info, Node: Specifying time zone rules, Next: Authors of get_date, Prev: Seconds since the Epoch, Up: Date input formats + +27.9 Specifying time zone rules +=============================== + +Normally, dates are interpreted using the rules of the current time +zone, which in turn are specified by the `TZ' environment variable, or +by a system default if `TZ' is not set. To specify a different set of +default time zone rules that apply just to one date, start the date +with a string of the form `TZ="RULE"'. The two quote characters (`"') +must be present in the date, and any quotes or backslashes within RULE +must be escaped by a backslash. + + For example, with the GNU `date' command you can answer the question +"What time is it in New York when a Paris clock shows 6:30am on October +31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown +in the following shell transcript: + + $ export TZ="America/New_York" + $ date --date='TZ="Europe/Paris" 2004-10-31 06:30' + Sun Oct 31 01:30:00 EDT 2004 + + In this example, the `--date' operand begins with its own `TZ' +setting, so the rest of that operand is processed according to +`Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it +were in Paris. However, since the output of the `date' command is +processed according to the overall time zone rules, it uses New York +time. (Paris was normally six hours ahead of New York in 2004, but +this example refers to a brief Halloween period when the gap was five +hours.) + + A `TZ' value is a rule that typically names a location in the `tz' +database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of +location names appears in the TWiki Date and Time Gateway +(http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a +colon before a location name in a `TZ' setting, e.g., +`TZ=":America/New_York"'. + + The `tz' database includes a wide variety of locations ranging from +`Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea +and have your own private time zone, or if you are using a non-GNU host +that does not support the `tz' database, you may need to use a POSIX +rule instead. Simple POSIX rules like `UTC0' specify a time zone +without daylight saving time; other rules can specify simple daylight +saving regimes. *Note Specifying the Time Zone with `TZ': (libc)TZ +Variable. + + +File: coreutils.info, Node: Authors of get_date, Prev: Specifying time zone rules, Up: Date input formats + +27.10 Authors of `get_date' +=========================== + +`get_date' was originally implemented by Steven M. Bellovin +(<smb@research.att.com>) while at the University of North Carolina at +Chapel Hill. The code was later tweaked by a couple of people on +Usenet, then completely overhauled by Rich $alz (<rsalz@bbn.com>) and +Jim Berets (<jberets@bbn.com>) in August, 1990. Various revisions for +the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert +and others. + + This chapter was originally produced by Franc,ois Pinard +(<pinard@iro.umontreal.ca>) from the `getdate.y' source code, and then +edited by K. Berry (<kb@cs.umb.edu>). + + +File: coreutils.info, Node: Opening the software toolbox, Next: Copying This Manual, Prev: Date input formats, Up: Top + +28 Opening the Software Toolbox +******************************* + +An earlier version of this chapter appeared in 2 (June 1994). It was +written by Arnold Robbins. + +* Menu: + +* Toolbox introduction:: Toolbox introduction +* I/O redirection:: I/O redirection +* The who command:: The `who' command +* The cut command:: The `cut' command +* The sort command:: The `sort' command +* The uniq command:: The `uniq' command +* Putting the tools together:: Putting the tools together + + +File: coreutils.info, Node: Toolbox introduction, Next: I/O redirection, Up: Opening the software toolbox + +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 might be used. What it's really about is the "Software +Tools" philosophy of program development and usage. + + The software tools philosophy was an important and integral concept +in the initial design and development of Unix (of which Linux and GNU +are essentially clones). Unfortunately, in the modern day press of +Internetworking and flashy GUIs, it seems to have fallen by the +wayside. This is a shame, since it provides a powerful mental model +for solving many kinds of problems. + + Many people carry a Swiss Army knife around in their pants pockets +(or purse). A Swiss Army knife is a handy tool to have: it has several +knife blades, a screwdriver, tweezers, toothpick, nail file, corkscrew, +and perhaps a number of other things on it. For the everyday, small +miscellaneous jobs where you need a simple, general purpose tool, it's +just the thing. + + On the other hand, an experienced carpenter doesn't build a house +using a Swiss Army knife. Instead, he has a toolbox chock full of +specialized tools--a saw, a hammer, a screwdriver, a plane, and so on. +And he knows exactly when and where to use each tool; you won't catch +him hammering nails with the handle of his screwdriver. + + The Unix developers at Bell Labs were all professional programmers +and trained computer scientists. They had found that while a +one-size-fits-all program might appeal to a user because there's only +one program to use, in practice such programs are + + a. difficult to write, + + b. difficult to maintain and debug, and + + c. difficult to extend to meet new situations. + + Instead, they felt that programs should be specialized tools. In +short, each program "should do one thing well." No more and no less. +Such programs are simpler to design, write, and get right--they only do +one thing. + + Furthermore, they found that with the right machinery for hooking +programs together, that the whole was greater than the sum of the +parts. By combining several special purpose programs, you could +accomplish a specific task that none of the programs was designed for, +and accomplish it much more quickly and easily than if you had to write +a special purpose program. We will see some (classic) examples of this +further on in the column. (An important additional point was that, if +necessary, take a detour and build any software tools you may need +first, if you don't already have something appropriate in the toolbox.) + + +File: coreutils.info, Node: I/O redirection, Next: The who command, Prev: Toolbox introduction, Up: Opening the software toolbox + +I/O Redirection +=============== + +Hopefully, you are familiar with the basics of I/O redirection in the +shell, in particular the concepts of "standard input," "standard +output," and "standard error". Briefly, "standard input" is a data +source, where data comes from. A program should not need to either +know or care if the data source is a disk file, a keyboard, a magnetic +tape, or even a punched card reader. Similarly, "standard output" is a +data sink, where data goes to. The program should neither know nor +care where this might be. Programs that only read their standard +input, do something to the data, and then send it on, are called +"filters", by analogy to filters in a water pipeline. + + With the Unix shell, it's very easy to set up data pipelines: + + program_to_create_data | filter1 | ... | filterN > final.pretty.data + + We start out by creating the raw data; each filter applies some +successive transformation to the data, until by the time it comes out +of the pipeline, it is in the desired form. + + This is fine and good for standard input and standard output. Where +does the standard error come in to play? Well, think about `filter1' in +the pipeline above. What happens if it encounters an error in the data +it sees? If it writes an error message to standard output, it will just +disappear down the pipeline into `filter2''s input, and the user will +probably never see it. So programs need a place where they can send +error messages so that the user will notice them. This is standard +error, and it is usually connected to your console or window, even if +you have redirected standard output of your program away from your +screen. + + For filter programs to work together, the format of the data has to +be agreed upon. The most straightforward and easiest format to use is +simply lines of text. Unix data files are generally just streams of +bytes, with lines delimited by the ASCII LF (Line Feed) character, +conventionally called a "newline" in the Unix literature. (This is +`'\n'' if you're a C programmer.) This is the format used by all the +traditional filtering programs. (Many earlier operating systems had +elaborate facilities and special purpose programs for managing binary +data. Unix has always shied away from such things, under the +philosophy that it's easiest to simply be able to view and edit your +data with a text editor.) + + OK, enough introduction. Let's take a look at some of the tools, +and then we'll see how to hook them together in interesting ways. In +the following discussion, we will only present those command line +options that interest us. As you should always do, double check your +system documentation for the full story. + + +File: coreutils.info, Node: The who command, Next: The cut command, Prev: I/O redirection, Up: Opening the software toolbox + +The `who' Command +================= + +The first program is the `who' command. By itself, it generates a list +of the users who are currently logged in. Although I'm writing this on +a single-user system, we'll pretend that several people are logged in: + + $ who + -| arnold console Jan 22 19:57 + -| miriam ttyp0 Jan 23 14:19(:0.0) + -| bill ttyp1 Jan 21 09:32(:0.0) + -| arnold ttyp2 Jan 23 20:48(:0.0) + + Here, the `$' is the usual shell prompt, at which I typed `who'. +There are three people logged in, and I am logged in twice. On +traditional Unix systems, user names are never more than eight +characters long. This little bit of trivia will be useful later. The +output of `who' is nice, but the data is not all that exciting. + + +File: coreutils.info, Node: The cut command, Next: The sort command, Prev: The who command, Up: Opening the software toolbox + +The `cut' Command +================= + +The next program we'll look at is the `cut' command. This program cuts +out columns or fields of input data. For example, we can tell it to +print just the login name and full name from the `/etc/passwd' file. +The `/etc/passwd' file has seven fields, separated by colons: + + arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/bash + + To get the first and fifth fields, we would use `cut' like this: + + $ cut -d: -f1,5 /etc/passwd + -| root:Operator + ... + -| arnold:Arnold D. Robbins + -| miriam:Miriam A. Robbins + ... + + With the `-c' option, `cut' will cut out specific characters (i.e., +columns) in the input lines. This is useful for input data that has +fixed width fields, and does not have a field separator. For example, +list the Monday dates for the current month: + + $ cal | cut -c 3-5 + -|Mo + -| + -| 6 + -| 13 + -| 20 + -| 27 + + +File: coreutils.info, Node: The sort command, Next: The uniq command, Prev: The cut command, Up: Opening the software toolbox + +The `sort' Command +================== + +Next we'll look at the `sort' command. This is one of the most +powerful commands on a Unix-style system; one that you will often find +yourself using when setting up fancy data plumbing. + + The `sort' command reads and sorts each file named on the command +line. It then merges the sorted data and writes it to standard output. +It will read standard input if no files are given on the command line +(thus making it into a filter). The sort is based on the character +collating sequence or based on user-supplied ordering criteria. + + +File: coreutils.info, Node: The uniq command, Next: Putting the tools together, Prev: The sort command, Up: Opening the software toolbox + +The `uniq' Command +================== + +Finally (at least for now), we'll look at the `uniq' program. When +sorting data, you will often end up with duplicate lines, lines that +are identical. Usually, all you need is one instance of each line. +This is where `uniq' comes in. The `uniq' program reads its standard +input. It prints only one copy of each repeated line. It does have +several options. Later on, we'll use the `-c' option, which prints +each unique line, preceded by a count of the number of times that line +occurred in the input. + + +File: coreutils.info, Node: Putting the tools together, Prev: The uniq command, Up: Opening the software toolbox + +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 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. + + The administrator could sit down with the system documentation and +write a C program that did this. It would take perhaps a couple of +hundred lines of code and about two hours to write it, test it, and +debug it. However, knowing the software toolbox, the administrator can +instead start out by generating just a list of logged on users: + + $ who | cut -c1-8 + -| arnold + -| miriam + -| bill + -| arnold + + Next, sort the list: + + $ who | cut -c1-8 | sort + -| arnold + -| arnold + -| bill + -| miriam + + Finally, run the sorted list through `uniq', to weed out duplicates: + + $ who | cut -c1-8 | sort | uniq + -| arnold + -| bill + -| miriam + + The `sort' command actually has a `-u' option that does what `uniq' +does. However, `uniq' has other uses for which one cannot substitute +`sort -u'. + + The administrator puts this pipeline into a shell script, and makes +it available for all the users on the system (`#' is the system +administrator, or `root', prompt): + + # cat > /usr/local/bin/listusers + who | cut -c1-8 | sort | uniq + ^D + # chmod +x /usr/local/bin/listusers + + There are four major points to note here. First, with just four +programs, on one command line, the administrator was able to save about +two hours worth of work. Furthermore, the shell pipeline is just about +as efficient as the C program would be, and it is much more efficient in +terms of programmer time. People time is much more expensive than +computer time, and in our modern "there's never enough time to do +everything" society, saving two hours of programmer time is no mean +feat. + + Second, it is also important to emphasize that with the +_combination_ of the tools, it is possible to do a special purpose job +never imagined by the authors of the individual programs. + + Third, it is also valuable to build up your pipeline in stages, as +we did here. This allows you to view the data at each stage in the +pipeline, which helps you acquire the confidence that you are indeed +using these tools correctly. + + Finally, by bundling the pipeline in a shell script, other users can +use your command, without having to remember the fancy plumbing you set +up for them. In terms of how you run them, shell scripts and compiled +programs are indistinguishable. + + After the previous warm-up exercise, we'll look at two additional, +more complicated pipelines. For them, we need to introduce two more +tools. + + The first is the `tr' command, which stands for "transliterate." +The `tr' command works on a character-by-character basis, changing +characters. Normally it is used for things like mapping upper case to +lower case: + + $ echo ThIs ExAmPlE HaS MIXED case! | tr '[:upper:]' '[:lower:]' + -| this example has mixed case! + + There are several options of interest: + +`-c' + work on the complement of the listed characters, i.e., operations + apply to characters not in the given set + +`-d' + delete characters in the first set from the output + +`-s' + squeeze repeated characters in the output into just one character. + + We will be using all three options in a moment. + + The other command we'll look at is `comm'. The `comm' command takes +two sorted input files as input data, and prints out the files' lines +in three columns. The output columns are the data lines unique to the +first file, the data lines unique to the second file, and the data +lines that are common to both. The `-1', `-2', and `-3' command line +options _omit_ the respective columns. (This is non-intuitive and +takes a little getting used to.) For example: + + $ cat f1 + -| 11111 + -| 22222 + -| 33333 + -| 44444 + $ cat f2 + -| 00000 + -| 22222 + -| 33333 + -| 55555 + $ comm f1 f2 + -| 00000 + -| 11111 + -| 22222 + -| 33333 + -| 44444 + -| 55555 + + The file name `-' tells `comm' to read standard input instead of a +regular file. + + Now we're ready to build a fancy pipeline. The first application is +a word frequency counter. This helps an author determine if he or she +is over-using certain words. + + The first step is to change the case of all the letters in our input +file to one case. "The" and "the" are the same word when doing +counting. + + $ tr '[:upper:]' '[:lower:]' < whats.gnu | ... + + The next step is to get rid of punctuation. Quoted words and +unquoted words should be treated identically; it's easiest to just get +the punctuation out of the way. + + $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | ... + + The second `tr' command operates on the complement of the listed +characters, which are all the letters, the digits, the underscore, and +the blank. The `\n' represents the newline character; it has to be +left alone. (The ASCII tab character should also be included for good +measure in a production script.) + + At this point, we have data consisting of words separated by blank +space. The words only contain alphanumeric characters (and the +underscore). The next step is break the data apart so that we have one +word per line. This makes the counting operation much easier, as we +will see shortly. + + $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | + > tr -s ' ' '\n' | ... + + This command turns blanks into newlines. The `-s' option squeezes +multiple newline characters in the output into just one. This helps us +avoid blank lines. (The `>' is the shell's "secondary prompt." This +is what the shell prints when it notices you haven't finished typing in +all of a command.) + + We now have data consisting of one word per line, no punctuation, +all one case. We're ready to count each word: + + $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | + > tr -s ' ' '\n' | sort | uniq -c | ... + + At this point, the data might look something like this: + + 60 a + 2 able + 6 about + 1 above + 2 accomplish + 1 acquire + 1 actually + 2 additional + + The output is sorted by word, not by count! What we want is the most +frequently used words first. Fortunately, this is easy to accomplish, +with the help of two more `sort' options: + +`-n' + do a numeric sort, not a textual one + +`-r' + reverse the order of the sort + + The final pipeline looks like this: + + $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | + > tr -s ' ' '\n' | sort | uniq -c | sort -n -r + -| 156 the + -| 60 a + -| 58 to + -| 51 of + -| 51 and + ... + + Whew! That's a lot to digest. Yet, the same principles apply. +With six commands, on two lines (really one long one split for +convenience), we've created a program that does something interesting +and useful, in much less time than we could have written a C program to +do the same thing. + + A minor modification to the above pipeline can give us a simple +spelling checker! To determine if you've spelled a word correctly, all +you have to do is look it up in a dictionary. If it is not there, then +chances are that your spelling is incorrect. So, we need a dictionary. +The conventional location for a dictionary is `/usr/dict/words'. On my +GNU/Linux system,(1) this is a is a sorted, 45,402 word dictionary. + + Now, how to compare our file with the dictionary? As before, we +generate a sorted list of words, one per line: + + $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | + > tr -s ' ' '\n' | sort -u | ... + + Now, all we need is a list of words that are _not_ in the +dictionary. Here is where the `comm' command comes in. + + $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | + > tr -s ' ' '\n' | sort -u | + > comm -23 - /usr/dict/words + + The `-2' and `-3' options eliminate lines that are only in the +dictionary (the second file), and lines that are in both files. Lines +only in the first file (standard input, our stream of words), are words +that are not in the dictionary. These are likely candidates for +spelling errors. This pipeline was the first cut at a production +spelling checker on Unix. + + There are some other tools that deserve brief mention. + +`grep' + search files for text that matches a regular expression + +`wc' + count lines, words, characters + +`tee' + a T-fitting for data pipes, copies data to files and to standard + output + +`sed' + the stream editor, an advanced tool + +`awk' + a data manipulation language, another advanced tool + + The software tools philosophy also espoused the following bit of +advice: "Let someone else do the hard part." This means, take +something that gives you most of what you need, and then massage it the +rest of the way until it's in the form that you want. + + To summarize: + + 1. Each program should do one thing well. No more, no less. + + 2. Combining programs with appropriate plumbing leads to results where + the whole is greater than the sum of the parts. It also leads to + novel uses of programs that the authors might never have imagined. + + 3. Programs should never print extraneous header or trailer data, + since these could get sent on down a pipeline. (A point we didn't + mention earlier.) + + 4. Let someone else do the hard part. + + 5. Know your toolbox! Use each program appropriately. If you don't + have an appropriate tool, build one. + + As of this writing, all the programs we've discussed are available +via anonymous `ftp' from: +`ftp://gnudist.gnu.org/textutils/textutils-1.22.tar.gz'. (There may be +more recent versions available now.) + + None of what I have presented in this column is new. The Software +Tools philosophy was first introduced in the book `Software Tools', by +Brian Kernighan and P.J. Plauger (Addison-Wesley, ISBN 0-201-03669-X). +This book showed how to write and use software tools. It was written in +1976, using a preprocessor for FORTRAN named `ratfor' (RATional +FORtran). At the time, C was not as ubiquitous as it is now; FORTRAN +was. The last chapter presented a `ratfor' to FORTRAN processor, +written in `ratfor'. `ratfor' looks an awful lot like C; if you know +C, you won't have any problem following the code. + + In 1981, the book was updated and made available as `Software Tools +in Pascal' (Addison-Wesley, ISBN 0-201-10342-7). Both books are still +in print and are well worth reading if you're a programmer. They +certainly made a major change in how I view programming. + + The programs in both books are available from Brian Kernighan's home +page (http://cm.bell-labs.com/who/bwk). For a number of years, there +was an active Software Tools Users Group, whose members had ported the +original `ratfor' programs to essentially every computer system with a +FORTRAN compiler. The popularity of the group waned in the middle 1980s +as Unix began to spread beyond universities. + + With the current proliferation of GNU code and other clones of Unix +programs, these programs now receive little attention; modern C +versions are much more efficient and do more than these programs do. +Nevertheless, as exposition of good programming style, and evangelism +for a still-valuable philosophy, these books are unparalleled, and I +recommend them highly. + + Acknowledgment: I would like to express my gratitude to Brian +Kernighan of Bell Labs, the original Software Toolsmith, for reviewing +this column. + + ---------- Footnotes ---------- + + (1) Redhat Linux 6.1, for the November 2000 revision of this article. + + +File: coreutils.info, Node: Copying This Manual, Next: Index, Prev: Opening the software toolbox, Up: Top + +Appendix A Copying This Manual +****************************** + +* Menu: + +* GNU Free Documentation License:: License for copying this manual. + + +File: coreutils.info, Node: GNU Free Documentation License, Up: Copying This Manual + +A.1 GNU Free Documentation License +================================== + + Version 1.2, November 2002 + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. + We recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in + the notice that says that the Document is released under this + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow + the conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the + title equally prominent and visible. You may add other material + on the covers in addition. Copying with changes limited to the + covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in + other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of + copies, to give them a chance to provide you with an updated + version of the Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with + the Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version to + whoever possesses a copy of it. In addition, you must do these + things in the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of + previous versions (which should, if there were any, be listed + in the History section of the Document). You may use the + same title as a previous version if the original publisher of + that version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on + the Title Page. If there is no section Entitled "History" in + the Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated in + the previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section + titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow + this License in all other respects regarding verbatim copying of + that document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + `http://www.gnu.org/copyleft/'. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software. + + +File: coreutils.info, Node: Index, Prev: Copying This Manual, Up: Top + +Index +***** + + +* Menu: + +* !: Connectives for test. + (line 9) +* !=: String tests. (line 25) +* %: Numeric expressions. (line 15) +* %b: printf invocation. (line 32) +* &: Relations for expr. (line 17) +* *: Numeric expressions. (line 15) +* + <1>: Numeric expressions. (line 11) +* +: String expressions. (line 53) +* +PAGE_RANGE: pr invocation. (line 60) +* - <1>: su invocation. (line 53) +* - <2>: env invocation. (line 45) +* -: Numeric expressions. (line 11) +* - and Unix rm: rm invocation. (line 110) +* -, removing files beginning with: rm invocation. (line 98) +* --: Common options. (line 36) +* --across: pr invocation. (line 84) +* --address-radix: od invocation. (line 36) +* --adjustment: nice invocation. (line 44) +* --all <1>: uname invocation. (line 30) +* --all <2>: who invocation. (line 36) +* --all <3>: stty invocation. (line 26) +* --all <4>: du invocation. (line 21) +* --all <5>: df invocation. (line 32) +* --all <6>: Which files are listed. + (line 13) +* --all: unexpand invocation. (line 37) +* --all-repeated: uniq invocation. (line 69) +* --almost-all: Which files are listed. + (line 17) +* --apparent-size: du invocation. (line 24) +* --append: tee invocation. (line 25) +* --archive: cp invocation. (line 54) +* --author: What information is listed. + (line 10) +* --backup <1>: ln invocation. (line 55) +* --backup <2>: mv invocation. (line 50) +* --backup <3>: install invocation. (line 40) +* --backup <4>: cp invocation. (line 61) +* --backup: Backup options. (line 13) +* --before: tac invocation. (line 21) +* --binary: md5sum invocation. (line 38) +* --block-size <1>: du invocation. (line 45) +* --block-size <2>: df invocation. (line 38) +* --block-size: Block size. (line 138) +* --block-size=SIZE: Block size. (line 12) +* --body-numbering: nl invocation. (line 47) +* --boot: who invocation. (line 40) +* --bourne-shell: dircolors invocation. + (line 27) +* --buffer-size: sort invocation. (line 237) +* --bytes <1>: du invocation. (line 41) +* --bytes <2>: cut invocation. (line 26) +* --bytes <3>: wc invocation. (line 41) +* --bytes <4>: split invocation. (line 37) +* --bytes <5>: tail invocation. (line 36) +* --bytes <6>: head invocation. (line 24) +* --bytes: fold invocation. (line 23) +* --c-shell: dircolors invocation. + (line 33) +* --canonicalize: readlink invocation. (line 29) +* --canonicalize-existing: readlink invocation. (line 35) +* --canonicalize-missing: readlink invocation. (line 41) +* --changes <1>: chmod invocation. (line 39) +* --changes <2>: chgrp invocation. (line 20) +* --changes: chown invocation. (line 70) +* --characters: cut invocation. (line 34) +* --chars: wc invocation. (line 45) +* --check: sort invocation. (line 18) +* --check-chars: uniq invocation. (line 103) +* --classify: General output formatting. + (line 36) +* --color: General output formatting. + (line 21) +* --columns: pr invocation. (line 70) +* --command: su invocation. (line 39) +* --complement: cut invocation. (line 71) +* --count <1>: who invocation. (line 55) +* --count: uniq invocation. (line 55) +* --count-links: du invocation. (line 91) +* --crown-margin: fmt invocation. (line 34) +* --csh: dircolors invocation. + (line 33) +* --date <1>: Options for date. (line 11) +* --date: touch invocation. (line 58) +* --dead: who invocation. (line 44) +* --decode: base64 invocation. (line 29) +* --delimiter: cut invocation. (line 51) +* --delimiters: paste invocation. (line 43) +* --dereference <1>: stat invocation. (line 17) +* --dereference <2>: du invocation. (line 96) +* --dereference <3>: chgrp invocation. (line 30) +* --dereference <4>: chown invocation. (line 103) +* --dereference <5>: cp invocation. (line 125) +* --dereference: Which files are listed. + (line 83) +* --dereference-args: du invocation. (line 56) +* --dereference-command-line: Which files are listed. + (line 36) +* --dereference-command-line-symlink-to-dir: Which files are listed. + (line 41) +* --dictionary-order: sort invocation. (line 85) +* --digits: csplit invocation. (line 80) +* --directory <1>: ln invocation. (line 61) +* --directory <2>: install invocation. (line 48) +* --directory: Which files are listed. + (line 28) +* --dired: What information is listed. + (line 16) +* --double-space: pr invocation. (line 96) +* --echo: shuf invocation. (line 19) +* --elide-empty-files: csplit invocation. (line 89) +* --escape: Formatting the file names. + (line 11) +* --exact: shred invocation. (line 133) +* --exclude-from=FILE: du invocation. (line 201) +* --exclude-type: df invocation. (line 138) +* --exclude=PATTERN: du invocation. (line 195) +* --expand-tabs: pr invocation. (line 120) +* --fast: su invocation. (line 44) +* --field-separator: sort invocation. (line 253) +* --fields: cut invocation. (line 44) +* --file <1>: Options for date. (line 22) +* --file: stty invocation. (line 31) +* --file-system: stat invocation. (line 23) +* --file-type: General output formatting. + (line 47) +* --files0-from=FILE <1>: du invocation. (line 62) +* --files0-from=FILE: wc invocation. (line 60) +* --first-line-number: pr invocation. (line 198) +* --follow: tail invocation. (line 41) +* --footer-numbering: nl invocation. (line 75) +* --force <1>: ln invocation. (line 67) +* --force <2>: shred invocation. (line 101) +* --force <3>: rm invocation. (line 35) +* --force <4>: mv invocation. (line 55) +* --force: cp invocation. (line 96) +* --form-feed: pr invocation. (line 128) +* --format <1>: General output formatting. + (line 10) +* --format <2>: What information is listed. + (line 130) +* --format: od invocation. (line 76) +* --format=FORMAT <1>: seq invocation. (line 24) +* --format=FORMAT: stat invocation. (line 28) +* --from: chown invocation. (line 80) +* --full-time: What information is listed. + (line 100) +* --general-numeric-sort: sort invocation. (line 98) +* --group <1>: id invocation. (line 23) +* --group: install invocation. (line 54) +* --group-directories-first: Which files are listed. + (line 50) +* --groups: id invocation. (line 27) +* --hardware-platform: uname invocation. (line 35) +* --head-lines: shuf invocation. (line 32) +* --header: pr invocation. (line 134) +* --header-numbering: nl invocation. (line 79) +* --heading: who invocation. (line 48) +* --help: Common options. (line 29) +* --hide-control-chars: Formatting the file names. + (line 23) +* --hide=PATTERN: Which files are listed. + (line 56) +* --human-readable <1>: du invocation. (line 75) +* --human-readable <2>: df invocation. (line 43) +* --human-readable <3>: What information is listed. + (line 116) +* --human-readable: Block size. (line 138) +* --ignore-backups: Which files are listed. + (line 23) +* --ignore-case <1>: join invocation. (line 69) +* --ignore-case <2>: uniq invocation. (line 59) +* --ignore-case: sort invocation. (line 92) +* --ignore-environment: env invocation. (line 45) +* --ignore-fail-on-non-empty: rmdir invocation. (line 17) +* --ignore-garbage: base64 invocation. (line 35) +* --ignore-interrupts: tee invocation. (line 30) +* --ignore-leading-blanks: sort invocation. (line 79) +* --ignore-nonprinting: sort invocation. (line 125) +* --ignore=PATTERN: Which files are listed. + (line 69) +* --indent: pr invocation. (line 204) +* --indicator-style: General output formatting. + (line 36) +* --initial: expand invocation. (line 34) +* --inode: What information is listed. + (line 122) +* --inodes: df invocation. (line 52) +* --input-range: shuf invocation. (line 23) +* --interactive <1>: ln invocation. (line 71) +* --interactive <2>: rm invocation. (line 50) +* --interactive <3>: mv invocation. (line 59) +* --interactive: cp invocation. (line 116) +* --iterations=NUMBER: shred invocation. (line 106) +* --join-blank-lines: nl invocation. (line 87) +* --join-lines: pr invocation. (line 147) +* --keep-files: csplit invocation. (line 85) +* --kernel-name: uname invocation. (line 65) +* --kernel-release: uname invocation. (line 61) +* --kernel-version: uname invocation. (line 76) +* --key: sort invocation. (line 193) +* --length: pr invocation. (line 156) +* --line-bytes: split invocation. (line 43) +* --lines <1>: wc invocation. (line 53) +* --lines <2>: split invocation. (line 30) +* --lines <3>: tail invocation. (line 130) +* --lines: head invocation. (line 30) +* --link: cp invocation. (line 121) +* --literal: Formatting the file names. + (line 17) +* --local: df invocation. (line 63) +* --login <1>: su invocation. (line 53) +* --login: who invocation. (line 68) +* --lookup: who invocation. (line 73) +* --machine: uname invocation. (line 41) +* --max-depth=DEPTH: du invocation. (line 111) +* --max-line-length: wc invocation. (line 57) +* --max-unchanged-stats: tail invocation. (line 118) +* --merge <1>: sort invocation. (line 32) +* --merge: pr invocation. (line 164) +* --mesg: who invocation. (line 86) +* --message: who invocation. (line 86) +* --mode <1>: mknod invocation. (line 43) +* --mode <2>: mkfifo invocation. (line 21) +* --mode <3>: mkdir invocation. (line 19) +* --mode: install invocation. (line 60) +* --month-sort: sort invocation. (line 131) +* --name: id invocation. (line 31) +* --no-create: touch invocation. (line 54) +* --no-dereference <1>: du invocation. (line 107) +* --no-dereference <2>: chgrp invocation. (line 35) +* --no-dereference <3>: chown invocation. (line 108) +* --no-dereference <4>: ln invocation. (line 75) +* --no-dereference: cp invocation. (line 129) +* --no-file-warnings: pr invocation. (line 211) +* --no-group: What information is listed. + (line 110) +* --no-newline: readlink invocation. (line 46) +* --no-preserve-root <1>: chmod invocation. (line 54) +* --no-preserve-root <2>: chgrp invocation. (line 48) +* --no-preserve-root <3>: chown invocation. (line 121) +* --no-preserve-root: rm invocation. (line 84) +* --no-renumber: nl invocation. (line 108) +* --no-sync: df invocation. (line 67) +* --no-target-directory <1>: ln invocation. (line 109) +* --no-target-directory <2>: mv invocation. (line 103) +* --no-target-directory <3>: install invocation. (line 101) +* --no-target-directory <4>: cp invocation. (line 272) +* --no-target-directory: Target directory. (line 15) +* --nodename: uname invocation. (line 46) +* --null: du invocation. (line 117) +* --number: cat invocation. (line 31) +* --number-format: nl invocation. (line 95) +* --number-lines: pr invocation. (line 177) +* --number-nonblank: cat invocation. (line 20) +* --number-separator: nl invocation. (line 112) +* --number-width: nl invocation. (line 122) +* --numeric-sort: sort invocation. (line 140) +* --numeric-suffixes: split invocation. (line 51) +* --numeric-uid-gid: What information is listed. + (line 232) +* --omit-header: pr invocation. (line 235) +* --omit-pagination: pr invocation. (line 246) +* --one-file-system <1>: du invocation. (line 191) +* --one-file-system <2>: rm invocation. (line 63) +* --one-file-system: cp invocation. (line 291) +* --only-delimited: cut invocation. (line 59) +* --operating-system: uname invocation. (line 57) +* --output <1>: shuf invocation. (line 37) +* --output: sort invocation. (line 213) +* --output-delimiter: cut invocation. (line 64) +* --output-duplicates: od invocation. (line 146) +* --output-tabs: pr invocation. (line 140) +* --owner: install invocation. (line 72) +* --page-increment: nl invocation. (line 83) +* --page_width: pr invocation. (line 264) +* --pages=PAGE_RANGE: pr invocation. (line 60) +* --parents <1>: rmdir invocation. (line 22) +* --parents <2>: mkdir invocation. (line 34) +* --parents: cp invocation. (line 177) +* --pid: tail invocation. (line 98) +* --portability <1>: pathchk invocation. (line 46) +* --portability: df invocation. (line 74) +* --prefix: csplit invocation. (line 62) +* --preserve: cp invocation. (line 134) +* --preserve-environment: su invocation. (line 64) +* --preserve-root <1>: chmod invocation. (line 49) +* --preserve-root <2>: chgrp invocation. (line 43) +* --preserve-root <3>: chown invocation. (line 116) +* --preserve-root: rm invocation. (line 79) +* --preserve-timestamps: install invocation. (line 78) +* --print-database: dircolors invocation. + (line 38) +* --print-type: df invocation. (line 113) +* --printf=FORMAT: stat invocation. (line 37) +* --processor: uname invocation. (line 50) +* --quiet <1>: tty invocation. (line 18) +* --quiet <2>: chmod invocation. (line 45) +* --quiet <3>: chgrp invocation. (line 26) +* --quiet <4>: chown invocation. (line 76) +* --quiet <5>: readlink invocation. (line 52) +* --quiet <6>: csplit invocation. (line 100) +* --quiet <7>: tail invocation. (line 135) +* --quiet: head invocation. (line 36) +* --quote-name: Formatting the file names. + (line 30) +* --quoting-style: Formatting the file names. + (line 11) +* --random-sort: sort invocation. (line 162) +* --random-source <1>: shred invocation. (line 112) +* --random-source <2>: shuf invocation. (line 43) +* --random-source: sort invocation. (line 226) +* --read-bytes: od invocation. (line 63) +* --real: id invocation. (line 36) +* --recursive <1>: chmod invocation. (line 69) +* --recursive <2>: chgrp invocation. (line 66) +* --recursive <3>: chown invocation. (line 140) +* --recursive <4>: rm invocation. (line 91) +* --recursive <5>: cp invocation. (line 200) +* --recursive: Which files are listed. + (line 90) +* --reference <1>: Options for date. (line 30) +* --reference <2>: touch invocation. (line 77) +* --reference <3>: chmod invocation. (line 62) +* --reference <4>: chgrp invocation. (line 52) +* --reference: chown invocation. (line 125) +* --regex: tac invocation. (line 26) +* --remove: shred invocation. (line 123) +* --remove-destination: cp invocation. (line 212) +* --repeated: uniq invocation. (line 63) +* --reply <1>: mv invocation. (line 64) +* --reply: cp invocation. (line 188) +* --retry: tail invocation. (line 84) +* --reverse <1>: Sorting the output. (line 27) +* --reverse: sort invocation. (line 157) +* --rfc-2822: Options for date. (line 36) +* --rfc-3339=TIMESPEC: Options for date. (line 48) +* --rfc-822: Options for date. (line 36) +* --save: stty invocation. (line 41) +* --section-delimiter: nl invocation. (line 68) +* --sep-string: pr invocation. (line 225) +* --separate-dirs: du invocation. (line 134) +* --separator <1>: pr invocation. (line 216) +* --separator: tac invocation. (line 33) +* --serial: paste invocation. (line 34) +* --set: Options for date. (line 78) +* --sh: dircolors invocation. + (line 27) +* --shell: su invocation. (line 75) +* --show-all: cat invocation. (line 16) +* --show-control-chars <1>: Formatting the file names. + (line 78) +* --show-control-chars: pr invocation. (line 90) +* --show-ends: cat invocation. (line 27) +* --show-nonprinting <1>: pr invocation. (line 251) +* --show-nonprinting: cat invocation. (line 49) +* --show-tabs: cat invocation. (line 42) +* --si <1>: du invocation. (line 123) +* --si <2>: df invocation. (line 93) +* --si <3>: What information is listed. + (line 258) +* --si: Block size. (line 138) +* --silent <1>: tty invocation. (line 18) +* --silent <2>: chmod invocation. (line 45) +* --silent <3>: chgrp invocation. (line 26) +* --silent <4>: chown invocation. (line 76) +* --silent <5>: readlink invocation. (line 52) +* --silent <6>: csplit invocation. (line 100) +* --silent <7>: tail invocation. (line 135) +* --silent: head invocation. (line 36) +* --size: What information is listed. + (line 242) +* --size=BYTES: shred invocation. (line 117) +* --skip-bytes: od invocation. (line 55) +* --skip-chars: uniq invocation. (line 41) +* --skip-fields: uniq invocation. (line 31) +* --sleep-interval: tail invocation. (line 90) +* --sort: Sorting the output. (line 32) +* --spaces: fold invocation. (line 29) +* --sparse=WHEN: cp invocation. (line 216) +* --split-only: fmt invocation. (line 47) +* --squeeze-blank: cat invocation. (line 35) +* --stable: sort invocation. (line 231) +* --starting-line-number: nl invocation. (line 117) +* --status: md5sum invocation. (line 69) +* --strings: od invocation. (line 68) +* --strip: install invocation. (line 88) +* --strip-trailing-slashes <1>: mv invocation. (line 89) +* --strip-trailing-slashes: cp invocation. (line 250) +* --suffix <1>: ln invocation. (line 100) +* --suffix <2>: mv invocation. (line 94) +* --suffix <3>: install invocation. (line 92) +* --suffix <4>: cp invocation. (line 263) +* --suffix <5>: csplit invocation. (line 66) +* --suffix: Backup options. (line 50) +* --suffix-length: split invocation. (line 26) +* --summarize: du invocation. (line 130) +* --symbolic: ln invocation. (line 94) +* --symbolic-link: cp invocation. (line 255) +* --sync: df invocation. (line 100) +* --sysv: sum invocation. (line 31) +* --tabs <1>: unexpand invocation. (line 24) +* --tabs: expand invocation. (line 22) +* --tabsize: General output formatting. + (line 92) +* --tagged-paragraph: fmt invocation. (line 40) +* --target-directory <1>: ln invocation. (line 105) +* --target-directory <2>: mv invocation. (line 99) +* --target-directory <3>: install invocation. (line 97) +* --target-directory <4>: cp invocation. (line 268) +* --target-directory: Target directory. (line 31) +* --temporary-directory: sort invocation. (line 273) +* --terse: stat invocation. (line 48) +* --text: md5sum invocation. (line 79) +* --time <1>: du invocation. (line 138) +* --time <2>: touch invocation. (line 50) +* --time: Sorting the output. (line 13) +* --time-style <1>: du invocation. (line 153) +* --time-style: Formatting file timestamps. + (line 26) +* --total: du invocation. (line 50) +* --traditional: od invocation. (line 197) +* --type: df invocation. (line 107) +* --uniform-spacing: fmt invocation. (line 53) +* --unique <1>: uniq invocation. (line 98) +* --unique: sort invocation. (line 282) +* --universal: Options for date. (line 83) +* --unset: env invocation. (line 39) +* --update <1>: mv invocation. (line 76) +* --update: cp invocation. (line 277) +* --user: id invocation. (line 41) +* --utc: Options for date. (line 83) +* --verbose <1>: chmod invocation. (line 59) +* --verbose <2>: chgrp invocation. (line 58) +* --verbose <3>: chown invocation. (line 132) +* --verbose <4>: rmdir invocation. (line 31) +* --verbose <5>: readlink invocation. (line 56) +* --verbose <6>: mkdir invocation. (line 51) +* --verbose <7>: ln invocation. (line 114) +* --verbose <8>: shred invocation. (line 129) +* --verbose <9>: rm invocation. (line 95) +* --verbose <10>: mv invocation. (line 86) +* --verbose <11>: install invocation. (line 106) +* --verbose <12>: cp invocation. (line 287) +* --verbose <13>: split invocation. (line 54) +* --verbose <14>: tail invocation. (line 139) +* --verbose: head invocation. (line 40) +* --version: Common options. (line 33) +* --warn: md5sum invocation. (line 88) +* --width <1>: General output formatting. + (line 104) +* --width <2>: fold invocation. (line 35) +* --width <3>: pr invocation. (line 255) +* --width <4>: fmt invocation. (line 59) +* --width: od invocation. (line 153) +* --words: wc invocation. (line 49) +* --wrap: base64 invocation. (line 21) +* --writable: who invocation. (line 86) +* --zero: shred invocation. (line 143) +* --zero-terminated <1>: shuf invocation. (line 48) +* --zero-terminated: sort invocation. (line 296) +* -0: du invocation. (line 116) +* -1 <1>: General output formatting. + (line 10) +* -1 <2>: join invocation. (line 74) +* -1: comm invocation. (line 23) +* -2 <1>: join invocation. (line 77) +* -2: comm invocation. (line 23) +* -3: comm invocation. (line 23) +* -a <1>: uname invocation. (line 30) +* -a <2>: who invocation. (line 36) +* -a <3>: stty invocation. (line 26) +* -a <4>: tee invocation. (line 25) +* -a <5>: Connectives for test. + (line 12) +* -a <6>: du invocation. (line 21) +* -a <7>: df invocation. (line 32) +* -a <8>: touch invocation. (line 50) +* -a: cp invocation. (line 54) +* -A: Which files are listed. + (line 17) +* -a <1>: Which files are listed. + (line 13) +* -a <2>: unexpand invocation. (line 37) +* -a <3>: join invocation. (line 60) +* -a <4>: split invocation. (line 26) +* -a <5>: pr invocation. (line 84) +* -a: od invocation. (line 166) +* -A <1>: od invocation. (line 36) +* -A: cat invocation. (line 16) +* -b <1>: who invocation. (line 40) +* -b: File type tests. (line 10) +* -B: du invocation. (line 45) +* -b: du invocation. (line 41) +* -B: df invocation. (line 38) +* -b <1>: ln invocation. (line 55) +* -b <2>: mv invocation. (line 50) +* -b <3>: install invocation. (line 40) +* -b <4>: cp invocation. (line 61) +* -b <5>: dircolors invocation. + (line 27) +* -b: Formatting the file names. + (line 11) +* -B: Which files are listed. + (line 23) +* -b <1>: cut invocation. (line 26) +* -b <2>: sort invocation. (line 79) +* -b <3>: md5sum invocation. (line 38) +* -b <4>: csplit invocation. (line 66) +* -b <5>: split invocation. (line 37) +* -b <6>: fold invocation. (line 23) +* -b <7>: od invocation. (line 169) +* -b <8>: nl invocation. (line 47) +* -b <9>: tac invocation. (line 21) +* -b <10>: cat invocation. (line 20) +* -b: Backup options. (line 13) +* -c <1>: su invocation. (line 39) +* -c <2>: File type tests. (line 13) +* -c <3>: stat invocation. (line 28) +* -c <4>: du invocation. (line 50) +* -c <5>: touch invocation. (line 54) +* -c <6>: chmod invocation. (line 39) +* -c <7>: chgrp invocation. (line 20) +* -c <8>: chown invocation. (line 70) +* -c <9>: install invocation. (line 44) +* -c: dircolors invocation. + (line 33) +* -C: General output formatting. + (line 15) +* -c <1>: Sorting the output. (line 13) +* -c <2>: cut invocation. (line 34) +* -c <3>: uniq invocation. (line 55) +* -c <4>: shuf invocation. (line 19) +* -c <5>: sort invocation. (line 18) +* -c: wc invocation. (line 41) +* -C: split invocation. (line 43) +* -c <1>: tail invocation. (line 36) +* -c <2>: head invocation. (line 24) +* -c <3>: pr invocation. (line 90) +* -c <4>: fmt invocation. (line 34) +* -c: od invocation. (line 172) +* -COLUMN: pr invocation. (line 70) +* -d <1>: Options for date. (line 11) +* -d <2>: who invocation. (line 44) +* -d: File type tests. (line 16) +* -D: du invocation. (line 56) +* -d <1>: touch invocation. (line 58) +* -d <2>: ln invocation. (line 61) +* -d <3>: install invocation. (line 48) +* -d: cp invocation. (line 89) +* -D: What information is listed. + (line 16) +* -d <1>: Which files are listed. + (line 28) +* -d <2>: paste invocation. (line 43) +* -d: cut invocation. (line 51) +* -D: uniq invocation. (line 69) +* -d <1>: uniq invocation. (line 63) +* -d <2>: sort invocation. (line 85) +* -d <3>: split invocation. (line 51) +* -d <4>: pr invocation. (line 96) +* -d <5>: base64 invocation. (line 29) +* -d <6>: od invocation. (line 176) +* -d: nl invocation. (line 68) +* -e: File characteristic tests. + (line 9) +* -E: echo invocation. (line 63) +* -e <1>: echo invocation. (line 20) +* -e <2>: readlink invocation. (line 35) +* -e <3>: join invocation. (line 64) +* -e: pr invocation. (line 120) +* -E: cat invocation. (line 27) +* -e: cat invocation. (line 23) +* -ef: File characteristic tests. + (line 23) +* -eq: Numeric tests. (line 16) +* -f <1>: su invocation. (line 44) +* -f: Options for date. (line 22) +* -F: stty invocation. (line 31) +* -f <1>: File type tests. (line 19) +* -f <2>: stat invocation. (line 23) +* -f <3>: touch invocation. (line 68) +* -f <4>: chmod invocation. (line 45) +* -f <5>: chgrp invocation. (line 26) +* -f <6>: chown invocation. (line 76) +* -f <7>: readlink invocation. (line 29) +* -f: ln invocation. (line 67) +* -F: ln invocation. (line 61) +* -f <1>: shred invocation. (line 101) +* -f <2>: rm invocation. (line 35) +* -f <3>: mv invocation. (line 55) +* -f: cp invocation. (line 96) +* -F: General output formatting. + (line 36) +* -f <1>: Sorting the output. (line 20) +* -f <2>: cut invocation. (line 44) +* -f <3>: uniq invocation. (line 31) +* -f <4>: sort invocation. (line 92) +* -f: csplit invocation. (line 62) +* -F: tail invocation. (line 79) +* -f <1>: tail invocation. (line 41) +* -f: pr invocation. (line 128) +* -F: pr invocation. (line 128) +* -f <1>: od invocation. (line 179) +* -f: nl invocation. (line 75) +* -f FORMAT: seq invocation. (line 24) +* -G: id invocation. (line 27) +* -g <1>: id invocation. (line 23) +* -g: stty invocation. (line 41) +* -G: Access permission tests. + (line 31) +* -g <1>: Access permission tests. + (line 9) +* -g: install invocation. (line 54) +* -G: What information is listed. + (line 110) +* -g <1>: What information is listed. + (line 105) +* -g: sort invocation. (line 98) +* -ge: Numeric tests. (line 16) +* -gt: Numeric tests. (line 16) +* -H: who invocation. (line 48) +* -h: File type tests. (line 23) +* -H: du invocation. (line 80) +* -h: du invocation. (line 75) +* -H: df invocation. (line 48) +* -h: df invocation. (line 43) +* -H: chgrp invocation. (line 70) +* -h: chgrp invocation. (line 35) +* -H: chown invocation. (line 143) +* -h: chown invocation. (line 108) +* -H: cp invocation. (line 109) +* -h: What information is listed. + (line 116) +* -H: Which files are listed. + (line 36) +* -h <1>: pr invocation. (line 134) +* -h: nl invocation. (line 79) +* -H: Traversing symlinks. (line 18) +* -h: Block size. (line 138) +* -i <1>: env invocation. (line 45) +* -i <2>: uname invocation. (line 35) +* -i <3>: tee invocation. (line 30) +* -i <4>: df invocation. (line 52) +* -i: ln invocation. (line 71) +* -I: rm invocation. (line 44) +* -i <1>: rm invocation. (line 39) +* -i <2>: mv invocation. (line 59) +* -i <3>: cp invocation. (line 116) +* -i: What information is listed. + (line 122) +* -I: Which files are listed. + (line 69) +* -i <1>: expand invocation. (line 34) +* -i <2>: join invocation. (line 69) +* -i <3>: uniq invocation. (line 59) +* -i <4>: shuf invocation. (line 23) +* -i <5>: sort invocation. (line 125) +* -i <6>: pr invocation. (line 140) +* -i <7>: base64 invocation. (line 35) +* -i <8>: od invocation. (line 182) +* -i: nl invocation. (line 83) +* -J: pr invocation. (line 147) +* -j: od invocation. (line 55) +* -k <1>: Access permission tests. + (line 12) +* -k <2>: du invocation. (line 85) +* -k <3>: df invocation. (line 57) +* -k <4>: General output formatting. + (line 72) +* -k <5>: sort invocation. (line 193) +* -k <6>: csplit invocation. (line 85) +* -k: Block size. (line 138) +* -l <1>: su invocation. (line 53) +* -l: who invocation. (line 68) +* -L <1>: File type tests. (line 23) +* -L <2>: stat invocation. (line 17) +* -L: du invocation. (line 96) +* -l <1>: du invocation. (line 91) +* -l: df invocation. (line 63) +* -L <1>: chgrp invocation. (line 75) +* -L <2>: chown invocation. (line 148) +* -L: cp invocation. (line 125) +* -l <1>: cp invocation. (line 121) +* -l: What information is listed. + (line 130) +* -L <1>: Which files are listed. + (line 83) +* -L: wc invocation. (line 57) +* -l <1>: wc invocation. (line 53) +* -l <2>: split invocation. (line 30) +* -l <3>: pr invocation. (line 156) +* -l <4>: od invocation. (line 185) +* -l: nl invocation. (line 87) +* -L: Traversing symlinks. (line 22) +* -le: Numeric tests. (line 16) +* -lt: Numeric tests. (line 16) +* -m <1>: su invocation. (line 64) +* -m <2>: uname invocation. (line 41) +* -m <3>: who invocation. (line 51) +* -m <4>: du invocation. (line 101) +* -m <5>: touch invocation. (line 73) +* -m <6>: readlink invocation. (line 41) +* -m <7>: mknod invocation. (line 43) +* -m <8>: mkfifo invocation. (line 21) +* -m <9>: mkdir invocation. (line 19) +* -m <10>: install invocation. (line 60) +* -m: General output formatting. + (line 78) +* -M: sort invocation. (line 131) +* -m <1>: sort invocation. (line 32) +* -m <2>: wc invocation. (line 45) +* -m: pr invocation. (line 164) +* -n <1>: nice invocation. (line 44) +* -n <2>: uname invocation. (line 46) +* -n <3>: id invocation. (line 31) +* -n <4>: String tests. (line 19) +* -n <5>: echo invocation. (line 17) +* -n <6>: readlink invocation. (line 46) +* -n: ln invocation. (line 75) +* -N: Formatting the file names. + (line 17) +* -n <1>: What information is listed. + (line 232) +* -n <2>: cut invocation. (line 55) +* -n <3>: shuf invocation. (line 32) +* -n <4>: sort invocation. (line 140) +* -n <5>: csplit invocation. (line 80) +* -n <6>: tail invocation. (line 130) +* -n: head invocation. (line 30) +* -N: pr invocation. (line 198) +* -n: pr invocation. (line 177) +* -N: od invocation. (line 63) +* -n <1>: nl invocation. (line 95) +* -n: cat invocation. (line 31) +* -n NUMBER: shred invocation. (line 106) +* -ne: Numeric tests. (line 16) +* -nt: File characteristic tests. + (line 15) +* -o <1>: uname invocation. (line 57) +* -o: Connectives for test. + (line 15) +* -O: Access permission tests. + (line 28) +* -o <1>: install invocation. (line 72) +* -o <2>: What information is listed. + (line 236) +* -o <3>: shuf invocation. (line 37) +* -o <4>: sort invocation. (line 213) +* -o <5>: pr invocation. (line 204) +* -o: od invocation. (line 188) +* -ot: File characteristic tests. + (line 19) +* -p <1>: su invocation. (line 64) +* -p: uname invocation. (line 50) +* -P: pathchk invocation. (line 42) +* -p <1>: pathchk invocation. (line 29) +* -p: File type tests. (line 28) +* -P <1>: du invocation. (line 107) +* -P <2>: df invocation. (line 74) +* -P <3>: chgrp invocation. (line 79) +* -P: chown invocation. (line 152) +* -p <1>: rmdir invocation. (line 22) +* -p <2>: mkdir invocation. (line 34) +* -p <3>: install invocation. (line 78) +* -p: cp invocation. (line 134) +* -P: cp invocation. (line 129) +* -p <1>: dircolors invocation. + (line 38) +* -p <2>: General output formatting. + (line 83) +* -p: nl invocation. (line 108) +* -P: Traversing symlinks. (line 26) +* -q <1>: who invocation. (line 55) +* -q: readlink invocation. (line 52) +* -Q: Formatting the file names. + (line 30) +* -q <1>: Formatting the file names. + (line 23) +* -q <2>: csplit invocation. (line 100) +* -q <3>: tail invocation. (line 135) +* -q: head invocation. (line 36) +* -r: uname invocation. (line 61) +* -R: Options for date. (line 36) +* -r <1>: Options for date. (line 30) +* -r <2>: id invocation. (line 36) +* -r <3>: Access permission tests. + (line 15) +* -r: touch invocation. (line 77) +* -R <1>: chmod invocation. (line 69) +* -R <2>: chgrp invocation. (line 66) +* -R <3>: chown invocation. (line 140) +* -R: rm invocation. (line 91) +* -r <1>: rm invocation. (line 91) +* -r: cp invocation. (line 200) +* -R: cp invocation. (line 200) +* -r: Sorting the output. (line 27) +* -R <1>: Which files are listed. + (line 90) +* -R: sort invocation. (line 162) +* -r <1>: sort invocation. (line 157) +* -r <2>: sum invocation. (line 25) +* -r <3>: pr invocation. (line 211) +* -r: tac invocation. (line 26) +* -s <1>: su invocation. (line 75) +* -s <2>: uname invocation. (line 65) +* -s <3>: Options for date. (line 78) +* -s <4>: who invocation. (line 59) +* -s <5>: tty invocation. (line 18) +* -s: File characteristic tests. + (line 12) +* -S <1>: File type tests. (line 31) +* -S: du invocation. (line 134) +* -s <1>: du invocation. (line 130) +* -s: readlink invocation. (line 52) +* -S: ln invocation. (line 100) +* -s: ln invocation. (line 94) +* -S <1>: mv invocation. (line 94) +* -S: install invocation. (line 92) +* -s: install invocation. (line 88) +* -S: cp invocation. (line 263) +* -s: cp invocation. (line 255) +* -S: Sorting the output. (line 32) +* -s <1>: What information is listed. + (line 242) +* -s <2>: paste invocation. (line 34) +* -s <3>: cut invocation. (line 59) +* -s: uniq invocation. (line 41) +* -S: sort invocation. (line 237) +* -s <1>: sort invocation. (line 231) +* -s <2>: sum invocation. (line 31) +* -s <3>: csplit invocation. (line 100) +* -s: fold invocation. (line 29) +* -S: pr invocation. (line 225) +* -s <1>: pr invocation. (line 216) +* -s <2>: fmt invocation. (line 47) +* -s: od invocation. (line 191) +* -S: od invocation. (line 68) +* -s <1>: nl invocation. (line 112) +* -s <2>: tac invocation. (line 33) +* -s: cat invocation. (line 35) +* -S: Backup options. (line 50) +* -s BYTES: shred invocation. (line 117) +* -su: su invocation. (line 25) +* -T: who invocation. (line 86) +* -t <1>: File type tests. (line 34) +* -t: stat invocation. (line 48) +* -T: df invocation. (line 113) +* -t: df invocation. (line 107) +* -T: ln invocation. (line 109) +* -t: ln invocation. (line 105) +* -T: mv invocation. (line 103) +* -t: mv invocation. (line 99) +* -T: install invocation. (line 101) +* -t: install invocation. (line 97) +* -T: cp invocation. (line 272) +* -t: cp invocation. (line 268) +* -T: General output formatting. + (line 92) +* -t <1>: Sorting the output. (line 36) +* -t <2>: unexpand invocation. (line 24) +* -t: expand invocation. (line 22) +* -T: sort invocation. (line 273) +* -t <1>: sort invocation. (line 253) +* -t: md5sum invocation. (line 79) +* -T: pr invocation. (line 246) +* -t <1>: pr invocation. (line 235) +* -t <2>: fmt invocation. (line 40) +* -t: od invocation. (line 76) +* -T: cat invocation. (line 42) +* -t: cat invocation. (line 38) +* -u <1>: env invocation. (line 39) +* -u <2>: Options for date. (line 83) +* -u <3>: who invocation. (line 62) +* -u <4>: id invocation. (line 41) +* -u <5>: Access permission tests. + (line 18) +* -u <6>: shred invocation. (line 123) +* -u <7>: mv invocation. (line 76) +* -u: cp invocation. (line 277) +* -U: Sorting the output. (line 49) +* -u <1>: Sorting the output. (line 42) +* -u <2>: uniq invocation. (line 98) +* -u <3>: sort invocation. (line 282) +* -u <4>: fmt invocation. (line 53) +* -u: cat invocation. (line 45) +* -v <1>: uname invocation. (line 76) +* -v <2>: chmod invocation. (line 59) +* -v <3>: chgrp invocation. (line 58) +* -v <4>: chown invocation. (line 132) +* -v <5>: rmdir invocation. (line 31) +* -v <6>: readlink invocation. (line 56) +* -v <7>: mkdir invocation. (line 51) +* -v <8>: ln invocation. (line 114) +* -v <9>: shred invocation. (line 129) +* -v <10>: rm invocation. (line 95) +* -v <11>: mv invocation. (line 86) +* -v <12>: install invocation. (line 106) +* -v <13>: cp invocation. (line 287) +* -v <14>: Sorting the output. (line 56) +* -v <15>: tail invocation. (line 139) +* -v <16>: head invocation. (line 40) +* -v <17>: pr invocation. (line 251) +* -v <18>: od invocation. (line 146) +* -v <19>: nl invocation. (line 117) +* -v: cat invocation. (line 49) +* -w <1>: who invocation. (line 86) +* -w <2>: Access permission tests. + (line 21) +* -w <3>: General output formatting. + (line 104) +* -w <4>: uniq invocation. (line 103) +* -w <5>: md5sum invocation. (line 88) +* -w <6>: wc invocation. (line 49) +* -w: fold invocation. (line 35) +* -W: pr invocation. (line 264) +* -w <1>: pr invocation. (line 255) +* -w <2>: fmt invocation. (line 59) +* -w <3>: base64 invocation. (line 21) +* -w <4>: od invocation. (line 153) +* -w: nl invocation. (line 122) +* -WIDTH: fmt invocation. (line 59) +* -x <1>: Access permission tests. + (line 24) +* -x <2>: du invocation. (line 191) +* -x <3>: df invocation. (line 138) +* -x <4>: shred invocation. (line 133) +* -x <5>: cp invocation. (line 291) +* -x: General output formatting. + (line 88) +* -X: Sorting the output. (line 63) +* -x: od invocation. (line 194) +* -X FILE: du invocation. (line 201) +* -z <1>: String tests. (line 15) +* -z <2>: shred invocation. (line 143) +* -z <3>: shuf invocation. (line 48) +* -z <4>: sort invocation. (line 296) +* -z: csplit invocation. (line 89) +* .cshrc: su invocation. (line 44) +* /: Numeric expressions. (line 15) +* /bin/sh: su invocation. (line 12) +* /etc/passwd: su invocation. (line 12) +* /etc/shells: su invocation. (line 64) +* 128-bit checksum: md5sum invocation. (line 6) +* 16-bit checksum: sum invocation. (line 6) +* 160-bit checksum: sha1sum invocation. (line 6) +* 224-bit checksum: sha2 utilities. (line 6) +* 256-bit checksum: sha2 utilities. (line 6) +* 384-bit checksum: sha2 utilities. (line 6) +* 4.2 file system type: df invocation. (line 125) +* 512-bit checksum: sha2 utilities. (line 6) +* <: Relations for expr. (line 22) +* <=: Relations for expr. (line 22) +* = <1>: Relations for expr. (line 22) +* =: String tests. (line 22) +* ==: Relations for expr. (line 22) +* >: Relations for expr. (line 22) +* >=: Relations for expr. (line 22) +* \( regexp operator: String expressions. (line 24) +* \+ regexp operator: String expressions. (line 28) +* \? regexp operator: String expressions. (line 28) +* \c: printf invocation. (line 23) +* \OOO: printf invocation. (line 57) +* \uhhhh: printf invocation. (line 62) +* \Uhhhhhhhh: printf invocation. (line 62) +* \xHH: printf invocation. (line 57) +* \| regexp operator: String expressions. (line 28) +* _POSIX2_VERSION <1>: touch invocation. (line 93) +* _POSIX2_VERSION <2>: uniq invocation. (line 46) +* _POSIX2_VERSION <3>: sort invocation. (line 328) +* _POSIX2_VERSION <4>: tail invocation. (line 150) +* _POSIX2_VERSION: Standards conformance. + (line 19) +* abbreviations for months: Calendar date items. (line 38) +* access permission tests: Access permission tests. + (line 6) +* access permissions, changing: chmod invocation. (line 6) +* access time: dd invocation. (line 171) +* access time, changing: touch invocation. (line 50) +* access time, printing or sorting files by: Sorting the output. + (line 42) +* access time, show the most recent: du invocation. (line 149) +* across columns: pr invocation. (line 84) +* across, listing files: General output formatting. + (line 88) +* adding permissions: Setting Permissions. (line 38) +* addition: Numeric expressions. (line 11) +* ago in date strings: Relative items in date strings. + (line 23) +* all repeated lines, outputting: uniq invocation. (line 69) +* alnum: Character sets. (line 91) +* alpha: Character sets. (line 94) +* alternate ebcdic, converting to: dd invocation. (line 67) +* always color option: General output formatting. + (line 27) +* always interactive option: rm invocation. (line 57) +* am i: who invocation. (line 21) +* am in date strings: Time of day items. (line 22) +* and operator <1>: Relations for expr. (line 17) +* and operator: Connectives for test. + (line 12) +* append: dd invocation. (line 141) +* appending to the output file: dd invocation. (line 141) +* appropriate privileges <1>: nice invocation. (line 6) +* appropriate privileges <2>: hostname invocation. (line 6) +* appropriate privileges <3>: Setting the time. (line 6) +* appropriate privileges: install invocation. (line 72) +* arbitrary date strings, parsing: Options for date. (line 11) +* arbitrary text, displaying: echo invocation. (line 6) +* arithmetic tests: Numeric tests. (line 6) +* ASCII dump of files: od invocation. (line 6) +* ascii, converting to: dd invocation. (line 59) +* atime, changing: touch invocation. (line 50) +* atime, printing or sorting files by: Sorting the output. (line 42) +* atime, show the most recent: du invocation. (line 149) +* attributes, file: Changing file attributes. + (line 6) +* authors of get_date: Authors of get_date. (line 6) +* auto color option: General output formatting. + (line 25) +* automounter file systems: df invocation. (line 32) +* b for block special file: mknod invocation. (line 26) +* background jobs, stopping at terminal write: Local. (line 41) +* backslash escapes <1>: echo invocation. (line 20) +* backslash escapes: Character sets. (line 14) +* backslash sequences for file names: Formatting the file names. + (line 11) +* backup files, ignoring: Which files are listed. + (line 23) +* backup options: Backup options. (line 6) +* backup suffix: Backup options. (line 50) +* backups, making <1>: ln invocation. (line 55) +* backups, making <2>: mv invocation. (line 50) +* backups, making <3>: install invocation. (line 40) +* backups, making <4>: cp invocation. (line 61) +* backups, making: Backup options. (line 13) +* backups, making only: cp invocation. (line 42) +* base64: base64 invocation. (line 6) +* Base64 decoding: base64 invocation. (line 29) +* base64 encoding: base64 invocation. (line 6) +* basename: basename invocation. (line 6) +* baud rate, setting: Special. (line 43) +* beeping at input buffer full: Input. (line 56) +* beginning of time: Time conversion specifiers. + (line 41) +* beginning of time, for POSIX: Seconds since the Epoch. + (line 13) +* Bellovin, Steven M.: Authors of get_date. (line 6) +* Berets, Jim: Authors of get_date. (line 6) +* Berry, K. <1>: Authors of get_date. (line 14) +* Berry, K.: Introduction. (line 19) +* binary: dd invocation. (line 188) +* binary I/O: dd invocation. (line 188) +* binary input files: md5sum invocation. (line 38) +* blank: Character sets. (line 97) +* blank lines, numbering: nl invocation. (line 87) +* blanks, ignoring leading: sort invocation. (line 79) +* block (space-padding): dd invocation. (line 76) +* block size <1>: dd invocation. (line 33) +* block size: Block size. (line 6) +* block size of conversion: dd invocation. (line 38) +* block size of input: dd invocation. (line 25) +* block size of output: dd invocation. (line 29) +* block special check: File type tests. (line 10) +* block special files: mknod invocation. (line 11) +* block special files, creating: mknod invocation. (line 6) +* BLOCK_SIZE: Block size. (line 12) +* BLOCKSIZE: Block size. (line 12) +* body, numbering: nl invocation. (line 17) +* Bourne shell syntax for color setup: dircolors invocation. + (line 27) +* breaks, cause interrupts: Input. (line 10) +* breaks, ignoring: Input. (line 7) +* brkint: Input. (line 10) +* bs: dd invocation. (line 33) +* BSD sum: sum invocation. (line 25) +* BSD tail: tail invocation. (line 19) +* BSD touch compatibility: touch invocation. (line 68) +* bsN: Output. (line 55) +* bugs, reporting: Introduction. (line 12) +* built-in shell commands, conflicts with <1>: nice invocation. + (line 35) +* built-in shell commands, conflicts with <2>: pwd invocation. + (line 10) +* built-in shell commands, conflicts with: test invocation. (line 28) +* byte count: wc invocation. (line 6) +* byte-swapping: dd invocation. (line 95) +* c for character special file: mknod invocation. (line 29) +* C shell syntax for color setup: dircolors invocation. + (line 33) +* C-s/C-q flow control: Input. (line 38) +* calendar date item: Calendar date items. (line 6) +* case folding: sort invocation. (line 92) +* case translation: Local. (line 36) +* case, ignored in dates: General date syntax. (line 64) +* cat: cat invocation. (line 6) +* cbreak: Combination. (line 52) +* cbs: dd invocation. (line 38) +* CD-ROM file system type: df invocation. (line 129) +* cdfs file system type: df invocation. (line 129) +* change or print terminal settings: stty invocation. (line 6) +* changed files, verbosely describing: chgrp invocation. (line 20) +* changed owners, verbosely describing: chown invocation. (line 70) +* changing access permissions: chmod invocation. (line 6) +* changing file attributes: Changing file attributes. + (line 6) +* changing file ownership: chown invocation. (line 6) +* changing file timestamps: touch invocation. (line 6) +* changing group ownership <1>: chgrp invocation. (line 6) +* changing group ownership: chown invocation. (line 6) +* changing special mode bits: Changing Special Mode Bits. + (line 6) +* character classes: Character sets. (line 78) +* character count: wc invocation. (line 6) +* character size: Control. (line 19) +* character special check: File type tests. (line 13) +* character special files: mknod invocation. (line 11) +* character special files, creating: mknod invocation. (line 6) +* characters, special: Characters. (line 6) +* check file types: test invocation. (line 6) +* checking for sortedness: sort invocation. (line 18) +* checksum, 128-bit: md5sum invocation. (line 6) +* checksum, 16-bit: sum invocation. (line 6) +* checksum, 160-bit: sha1sum invocation. (line 6) +* checksum, 224-bit: sha2 utilities. (line 6) +* checksum, 256-bit: sha2 utilities. (line 6) +* checksum, 384-bit: sha2 utilities. (line 6) +* checksum, 512-bit: sha2 utilities. (line 6) +* chgrp: chgrp invocation. (line 6) +* chmod: chmod invocation. (line 6) +* chown: chown invocation. (line 6) +* chroot: chroot invocation. (line 6) +* cksum: cksum invocation. (line 6) +* clocal: Control. (line 33) +* cntrl: Character sets. (line 100) +* color database, printing: dircolors invocation. + (line 38) +* color setup: dircolors invocation. + (line 6) +* color, distinguishing file types with: General output formatting. + (line 21) +* cols: Special. (line 27) +* column to wrap data after: base64 invocation. (line 21) +* COLUMNS: Special. (line 30) +* columns: Special. (line 27) +* COLUMNS: General output formatting. + (line 104) +* combination settings: Combination. (line 6) +* comm: comm invocation. (line 6) +* command-line operands to shuffle: shuf invocation. (line 19) +* commands for controlling processes: Process control. (line 6) +* commands for delaying: Delaying. (line 6) +* commands for exit status: Conditions. (line 6) +* commands for file name manipulation: File name manipulation. + (line 6) +* commands for invoking other commands: Modified command invocation. + (line 6) +* commands for printing text: Printing text. (line 6) +* commands for printing the working context: Working context. (line 6) +* commands for printing user information: User information. (line 6) +* commands for redirection: Redirection. (line 6) +* commands for system context: System context. (line 6) +* commas, outputting between files: General output formatting. + (line 78) +* comments, in dates: General date syntax. (line 64) +* common field, joining on: join invocation. (line 6) +* common lines: comm invocation. (line 18) +* common options: Common options. (line 6) +* compare values: test invocation. (line 6) +* comparing sorted files: comm invocation. (line 6) +* comparison operators: Relations for expr. (line 22) +* concatenate and write files: cat invocation. (line 6) +* conditional executability: Conditional Executability. + (line 6) +* conditions: Conditions. (line 6) +* conflicts with shell built-ins <1>: nice invocation. (line 35) +* conflicts with shell built-ins <2>: pwd invocation. (line 10) +* conflicts with shell built-ins: test invocation. (line 28) +* connectives, logical <1>: Relations for expr. (line 6) +* connectives, logical: Connectives for test. + (line 6) +* context splitting: csplit invocation. (line 6) +* context, system: System context. (line 6) +* control characters, using ^C: Local. (line 51) +* control settings: Control. (line 6) +* controlling terminal: dd invocation. (line 176) +* conv: dd invocation. (line 53) +* conversion block size: dd invocation. (line 38) +* conversion specifiers, date: Date conversion specifiers. + (line 6) +* conversion specifiers, literal: Literal conversion specifiers. + (line 6) +* conversion specifiers, time: Time conversion specifiers. + (line 6) +* converting tabs to spaces: expand invocation. (line 6) +* converting while copying a file: dd invocation. (line 6) +* cooked: Combination. (line 37) +* Coordinated Universal Time: Options for date. (line 83) +* copying directories recursively: cp invocation. (line 76) +* copying existing permissions: Copying Permissions. (line 6) +* copying files: cat invocation. (line 6) +* copying files and directories: cp invocation. (line 6) +* copying files and setting attributes: install invocation. (line 6) +* core utilities: Top. (line 19) +* count: dd invocation. (line 49) +* cp: cp invocation. (line 6) +* crashes and corruption: sync invocation. (line 11) +* CRC checksum: cksum invocation. (line 6) +* cread: Control. (line 30) +* creating directories: mkdir invocation. (line 6) +* creating FIFOs (named pipes): mkfifo invocation. (line 6) +* creating links (hard only): link invocation. (line 6) +* creating links (hard or soft): ln invocation. (line 6) +* creating output file, avoiding: dd invocation. (line 103) +* creating output file, requiring: dd invocation. (line 107) +* crN: Output. (line 45) +* crown margin: fmt invocation. (line 34) +* crt: Combination. (line 74) +* crterase: Local. (line 22) +* crtkill: Local. (line 56) +* crtscts: Control. (line 36) +* csh syntax for color setup: dircolors invocation. + (line 33) +* csN: Control. (line 19) +* csplit: csplit invocation. (line 6) +* cstopb: Control. (line 27) +* ctime, printing or sorting by: Sorting the output. (line 13) +* ctime, show the most recent: du invocation. (line 144) +* ctlecho: Local. (line 51) +* current working directory, printing: pwd invocation. (line 6) +* cut: cut invocation. (line 6) +* cyclic redundancy check: cksum invocation. (line 6) +* data, erasing: shred invocation. (line 6) +* database for color setup, printing: dircolors invocation. + (line 38) +* date: date invocation. (line 6) +* date conversion specifiers: Date conversion specifiers. + (line 6) +* date format, ISO 8601: Calendar date items. (line 30) +* date input formats: Date input formats. (line 6) +* date options: Options for date. (line 6) +* date strings, parsing: Options for date. (line 11) +* day in date strings: Relative items in date strings. + (line 15) +* day of week item: Day of week items. (line 6) +* dd: dd invocation. (line 6) +* dec: Combination. (line 77) +* decctlq: Combination. (line 63) +* Decode base64 data: base64 invocation. (line 29) +* delay for a specified time: sleep invocation. (line 6) +* delaying commands: Delaying. (line 6) +* deleting characters: Squeezing. (line 6) +* dereferencing symbolic links: ln invocation. (line 40) +* descriptor follow option: tail invocation. (line 41) +* destination directory <1>: ln invocation. (line 105) +* destination directory <2>: mv invocation. (line 99) +* destination directory <3>: install invocation. (line 97) +* destination directory <4>: cp invocation. (line 268) +* destination directory: Target directory. (line 15) +* destinations, multiple output: tee invocation. (line 6) +* device file, disk: df invocation. (line 19) +* df: df invocation. (line 6) +* DF_BLOCK_SIZE: Block size. (line 12) +* dictionary order: sort invocation. (line 85) +* differing lines: comm invocation. (line 18) +* digit: Character sets. (line 103) +* dir: dir invocation. (line 6) +* dircolors: dircolors invocation. + (line 6) +* direct: dd invocation. (line 149) +* direct I/O: dd invocation. (line 149) +* directories, copying: cp invocation. (line 6) +* directories, copying recursively: cp invocation. (line 76) +* directories, creating: mkdir invocation. (line 6) +* directories, creating with given attributes: install invocation. + (line 48) +* directories, removing (recursively): rm invocation. (line 91) +* directories, removing empty: rmdir invocation. (line 6) +* directory: dd invocation. (line 152) +* directory check: File type tests. (line 16) +* directory components, printing: dirname invocation. (line 6) +* directory deletion, ignoring failures: rmdir invocation. (line 17) +* directory deletion, reporting: rmdir invocation. (line 31) +* directory I/O: dd invocation. (line 152) +* directory listing: ls invocation. (line 6) +* directory listing, brief: dir invocation. (line 6) +* directory listing, recursive: Which files are listed. + (line 90) +* directory listing, verbose: vdir invocation. (line 6) +* directory order, listing by: Sorting the output. (line 20) +* directory, stripping from file names: basename invocation. (line 6) +* dired Emacs mode support: What information is listed. + (line 16) +* dirname: dirname invocation. (line 6) +* disabling special characters: Characters. (line 13) +* disambiguating group names and IDs: Disambiguating names and IDs. + (line 6) +* disk allocation: What information is listed. + (line 242) +* disk device file: df invocation. (line 19) +* disk usage: Disk usage. (line 6) +* disk usage by file system: df invocation. (line 6) +* disk usage for files: du invocation. (line 6) +* diskette file system: df invocation. (line 133) +* displacement of dates: Relative items in date strings. + (line 6) +* displaying text: echo invocation. (line 6) +* displaying value of a symbolic link: readlink invocation. (line 6) +* division: Numeric expressions. (line 15) +* do nothing, successfully: true invocation. (line 6) +* do nothing, unsuccessfully: false invocation. (line 6) +* DOS file system: df invocation. (line 133) +* double spacing: pr invocation. (line 96) +* down columns: pr invocation. (line 70) +* dsusp: Characters. (line 53) +* dsync: dd invocation. (line 157) +* du: du invocation. (line 6) +* DU_BLOCK_SIZE: Block size. (line 12) +* ebcdic, converting to: dd invocation. (line 63) +* echo <1>: Local. (line 18) +* echo: echo invocation. (line 6) +* echoctl: Local. (line 51) +* echoe: Local. (line 22) +* echok: Local. (line 26) +* echoke: Local. (line 56) +* echonl: Local. (line 29) +* echoprt: Local. (line 46) +* effective user and group IDs, printing: id invocation. (line 6) +* effective user ID, printing: whoami invocation. (line 6) +* efs file system type: df invocation. (line 125) +* Eggert, Paul: Authors of get_date. (line 6) +* eight-bit characters <1>: Combination. (line 55) +* eight-bit characters: Control. (line 19) +* eight-bit input: Input. (line 23) +* ek: Combination. (line 22) +* empty files, creating: touch invocation. (line 11) +* empty lines, numbering: nl invocation. (line 87) +* entire files, output of: Output of entire files. + (line 6) +* env: env invocation. (line 6) +* environment variables, printing: printenv invocation. (line 6) +* environment, preserving: su invocation. (line 64) +* environment, printing: env invocation. (line 30) +* environment, running a program in a modified: env invocation. + (line 6) +* eof: Characters. (line 32) +* eol: Characters. (line 35) +* eol2: Characters. (line 38) +* epoch, for POSIX: Seconds since the Epoch. + (line 13) +* epoch, seconds since: Time conversion specifiers. + (line 41) +* equal string check: String tests. (line 22) +* equivalence classes: Character sets. (line 127) +* erase: Characters. (line 26) +* erasing data: shred invocation. (line 6) +* error messages, omitting <1>: chmod invocation. (line 45) +* error messages, omitting <2>: chgrp invocation. (line 26) +* error messages, omitting: chown invocation. (line 76) +* evaluation of expressions: expr invocation. (line 6) +* even parity: Control. (line 13) +* evenp: Combination. (line 9) +* exabyte, definition of: Block size. (line 116) +* examples of date: Examples of date. (line 6) +* examples of expr: Examples of expr. (line 6) +* exbibyte, definition of: Block size. (line 120) +* excl: dd invocation. (line 107) +* excluding files from du: du invocation. (line 195) +* executable file check: Access permission tests. + (line 24) +* executables and file type, marking: General output formatting. + (line 36) +* execute/search permission: Mode Structure. (line 18) +* execute/search permission, symbolic: Setting Permissions. (line 63) +* existence-of-file check: File characteristic tests. + (line 9) +* existing backup method: Backup options. (line 39) +* exit status commands: Conditions. (line 6) +* exit status of chroot: chroot invocation. (line 47) +* exit status of env: env invocation. (line 49) +* exit status of expr: expr invocation. (line 39) +* exit status of false: false invocation. (line 6) +* exit status of ls: ls invocation. (line 29) +* exit status of nice: nice invocation. (line 53) +* exit status of nohup: nohup invocation. (line 42) +* exit status of pathchk: pathchk invocation. (line 50) +* exit status of printenv: printenv invocation. (line 17) +* exit status of sort: sort invocation. (line 58) +* exit status of su: su invocation. (line 80) +* exit status of test: test invocation. (line 40) +* exit status of true: true invocation. (line 6) +* exit status of tty: tty invocation. (line 21) +* expand: expand invocation. (line 6) +* expr: expr invocation. (line 6) +* expression evaluation <1>: expr invocation. (line 6) +* expression evaluation: test invocation. (line 6) +* expressions, numeric: Numeric expressions. (line 6) +* expressions, string: String expressions. (line 6) +* extension, sorting files by: Sorting the output. (line 63) +* factor: factor invocation. (line 6) +* failure exit status: false invocation. (line 6) +* false: false invocation. (line 6) +* fascism: su invocation. (line 87) +* fdatasync: dd invocation. (line 121) +* FDL, GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* ffN: Output. (line 63) +* field separator character: sort invocation. (line 253) +* fields, padding numeric: Padding and other flags. + (line 6) +* FIFOs, creating: mkfifo invocation. (line 6) +* file attributes, changing: Changing file attributes. + (line 6) +* file characteristic tests: File characteristic tests. + (line 6) +* file contents, dumping unambiguously: od invocation. (line 6) +* file information, preserving: cp invocation. (line 134) +* file mode bits, numeric: Numeric Modes. (line 6) +* file name manipulation: File name manipulation. + (line 6) +* file name pattern expansion, disabled: su invocation. (line 44) +* file names, checking validity and portability: pathchk invocation. + (line 6) +* file names, stripping directory and suffix: basename invocation. + (line 6) +* file offset radix: od invocation. (line 36) +* file ownership, changing: chown invocation. (line 6) +* file sizes: du invocation. (line 45) +* file space usage: du invocation. (line 6) +* file status: stat invocation. (line 6) +* file system disk usage: df invocation. (line 6) +* file system sizes: df invocation. (line 38) +* file system space, retrieving current data more slowly: df invocation. + (line 100) +* file system space, retrieving old data more quickly: df invocation. + (line 67) +* file system status: stat invocation. (line 6) +* file system types, limiting output to certain: df invocation. + (line 63) +* file system types, printing: df invocation. (line 113) +* file systems: stat invocation. (line 23) +* file systems and hard links: ln invocation. (line 6) +* file systems, omitting copying to different: cp invocation. (line 291) +* file timestamps, changing: touch invocation. (line 6) +* file type and executables, marking: General output formatting. + (line 36) +* file type tests: File type tests. (line 6) +* file type, marking: General output formatting. + (line 47) +* file types: Special file types. (line 9) +* file types, special: Special file types. (line 6) +* file utilities: Top. (line 19) +* files beginning with -, removing: rm invocation. (line 98) +* files, copying: cp invocation. (line 6) +* fingerprint, 128-bit: md5sum invocation. (line 6) +* fingerprint, 160-bit: sha1sum invocation. (line 6) +* fingerprint, 224-bit: sha2 utilities. (line 6) +* fingerprint, 256-bit: sha2 utilities. (line 6) +* fingerprint, 384-bit: sha2 utilities. (line 6) +* fingerprint, 512-bit: sha2 utilities. (line 6) +* first in date strings: General date syntax. (line 26) +* first part of files, outputting: head invocation. (line 6) +* fixed-length records, converting to variable-length: dd invocation. + (line 38) +* flow control, hardware: Control. (line 36) +* flow control, software: Input. (line 43) +* flushing, disabling: Local. (line 32) +* fmt: fmt invocation. (line 6) +* fold: fold invocation. (line 6) +* folding long input lines: fold invocation. (line 6) +* footers, numbering: nl invocation. (line 17) +* force deletion: shred invocation. (line 101) +* formatting file contents: Formatting file contents. + (line 6) +* formatting of numbers in seq: seq invocation. (line 24) +* formatting times <1>: date invocation. (line 20) +* formatting times: pr invocation. (line 100) +* fortnight in date strings: Relative items in date strings. + (line 15) +* fsync: dd invocation. (line 125) +* general date syntax: General date syntax. (line 6) +* general numeric sort: sort invocation. (line 98) +* get_date: Date input formats. (line 6) +* gibibyte, definition of: Block size. (line 99) +* gigabyte, definition of: Block size. (line 95) +* giving away permissions: Umask and Protection. + (line 12) +* globbing, disabled: su invocation. (line 44) +* GMT: Options for date. (line 83) +* grand total of disk space: du invocation. (line 50) +* graph: Character sets. (line 106) +* Greenwich Mean Time: Options for date. (line 83) +* group IDs, disambiguating: Disambiguating names and IDs. + (line 6) +* group names, disambiguating: Disambiguating names and IDs. + (line 6) +* group owner, default: Mode Structure. (line 31) +* group ownership of installed files, setting: install invocation. + (line 54) +* group ownership, changing <1>: chgrp invocation. (line 6) +* group ownership, changing: chown invocation. (line 6) +* group wheel, not supported: su invocation. (line 87) +* group, permissions for: Setting Permissions. (line 26) +* groups: groups invocation. (line 6) +* growing files: tail invocation. (line 41) +* hangups, immunity to: nohup invocation. (line 6) +* hard link check: File characteristic tests. + (line 23) +* hard link, defined: ln invocation. (line 32) +* hard links: dd invocation. (line 185) +* hard links to directories: ln invocation. (line 61) +* hard links, counting in du: du invocation. (line 91) +* hard links, creating <1>: ln invocation. (line 6) +* hard links, creating: link invocation. (line 6) +* hard links, preserving: cp invocation. (line 89) +* hardware class: uname invocation. (line 41) +* hardware flow control: Control. (line 36) +* hardware platform: uname invocation. (line 35) +* hardware type: uname invocation. (line 41) +* hat notation for control characters: Local. (line 51) +* head: head invocation. (line 6) +* head of output: shuf invocation. (line 32) +* headers, numbering: nl invocation. (line 17) +* help, online: Common options. (line 29) +* hex dump of files: od invocation. (line 6) +* High Sierra file system: df invocation. (line 129) +* holes, copying files with: cp invocation. (line 216) +* HOME: su invocation. (line 18) +* horizontal, listing files: General output formatting. + (line 88) +* host processor type: uname invocation. (line 50) +* hostid: hostid invocation. (line 6) +* hostname <1>: hostname invocation. (line 6) +* hostname: uname invocation. (line 46) +* hour in date strings: Relative items in date strings. + (line 15) +* hsfs file system type: df invocation. (line 129) +* human-readable output <1>: du invocation. (line 75) +* human-readable output <2>: df invocation. (line 43) +* human-readable output <3>: What information is listed. + (line 116) +* human-readable output: Block size. (line 43) +* hup[cl]: Control. (line 23) +* hurd, author, printing: What information is listed. + (line 10) +* ibs: dd invocation. (line 25) +* icanon: Local. (line 11) +* icrnl: Input. (line 32) +* id: id invocation. (line 6) +* idle time: who invocation. (line 62) +* iexten: Local. (line 15) +* if: dd invocation. (line 17) +* iflag: dd invocation. (line 130) +* ignbrk: Input. (line 7) +* igncr: Input. (line 29) +* ignore file systems: df invocation. (line 32) +* Ignore garbage in base64 stream: base64 invocation. (line 35) +* ignoring case: sort invocation. (line 92) +* ignpar: Input. (line 13) +* imaxbel: Input. (line 56) +* immunity to hangups: nohup invocation. (line 6) +* implementation, hardware: uname invocation. (line 35) +* including files from du <1>: du invocation. (line 62) +* including files from du: wc invocation. (line 60) +* indenting lines: pr invocation. (line 204) +* index: String expressions. (line 45) +* information, about current users: who invocation. (line 6) +* initial part of files, outputting: head invocation. (line 6) +* initial tabs, converting: expand invocation. (line 34) +* inlcr: Input. (line 26) +* inode number, printing: What information is listed. + (line 122) +* inode usage: df invocation. (line 52) +* inode, and hard links: ln invocation. (line 32) +* inodes, written buffered: sync invocation. (line 6) +* inpck: Input. (line 20) +* input block size: dd invocation. (line 25) +* input encoding, UTF-8: Input. (line 35) +* input range to shuffle: shuf invocation. (line 23) +* input settings: Input. (line 6) +* input tabs: pr invocation. (line 120) +* install: install invocation. (line 6) +* interactivity <1>: mv invocation. (line 64) +* interactivity: cp invocation. (line 188) +* intr: Characters. (line 20) +* invocation of commands, modified: Modified command invocation. + (line 6) +* isig: Local. (line 7) +* ISO 8601 date format: Calendar date items. (line 30) +* ISO/IEC 10646: printf invocation. (line 62) +* ispeed: Special. (line 16) +* istrip: Input. (line 23) +* items in date strings: General date syntax. (line 6) +* iterations, selecting the number of: shred invocation. (line 106) +* iuclc: Input. (line 48) +* iutf8: Input. (line 35) +* ixany: Input. (line 52) +* ixoff: Input. (line 43) +* ixon: Input. (line 38) +* join: join invocation. (line 6) +* kernel name: uname invocation. (line 65) +* kernel release: uname invocation. (line 61) +* kernel version: uname invocation. (line 76) +* kibibyte, definition of: Block size. (line 83) +* kibibytes for file sizes: du invocation. (line 85) +* kibibytes for file system sizes: df invocation. (line 57) +* kill <1>: kill invocation. (line 6) +* kill: Characters. (line 29) +* kilobyte, definition of: Block size. (line 78) +* Knuth, Donald E.: fmt invocation. (line 19) +* language, in dates: General date syntax. (line 40) +* last DAY <1>: Day of week items. (line 15) +* last DAY: Options for date. (line 11) +* last in date strings: General date syntax. (line 26) +* last modified dates, displaying in du: du invocation. (line 138) +* last part of files, outputting: tail invocation. (line 6) +* LC_ALL <1>: ls invocation. (line 17) +* LC_ALL: sort invocation. (line 49) +* LC_COLLATE <1>: Relations for expr. (line 22) +* LC_COLLATE <2>: join invocation. (line 14) +* LC_COLLATE <3>: comm invocation. (line 12) +* LC_COLLATE <4>: uniq invocation. (line 21) +* LC_COLLATE: sort invocation. (line 49) +* LC_CTYPE <1>: printf invocation. (line 62) +* LC_CTYPE: sort invocation. (line 79) +* LC_MESSAGES: pr invocation. (line 13) +* LC_NUMERIC <1>: printf invocation. (line 51) +* LC_NUMERIC <2>: sort invocation. (line 98) +* LC_NUMERIC: Block size. (line 57) +* LC_TIME <1>: date invocation. (line 11) +* LC_TIME <2>: du invocation. (line 158) +* LC_TIME <3>: Formatting file timestamps. + (line 30) +* LC_TIME <4>: sort invocation. (line 131) +* LC_TIME: pr invocation. (line 107) +* LCASE: Combination. (line 71) +* lcase: Combination. (line 71) +* lcase, converting to: dd invocation. (line 87) +* lchown <1>: chgrp invocation. (line 30) +* lchown: chown invocation. (line 103) +* leading directories, creating missing: install invocation. (line 48) +* leading directory components, stripping: basename invocation. + (line 6) +* left margin: pr invocation. (line 204) +* length: String expressions. (line 50) +* limiting output of du: du invocation. (line 111) +* line: Special. (line 37) +* line count: wc invocation. (line 6) +* line numbering: nl invocation. (line 6) +* line settings of terminal: stty invocation. (line 6) +* line-breaking: fmt invocation. (line 19) +* line-by-line comparison: comm invocation. (line 6) +* LINES: Special. (line 30) +* link: link invocation. (line 6) +* links, creating <1>: ln invocation. (line 6) +* links, creating: link invocation. (line 6) +* Linux file system types: df invocation. (line 125) +* literal conversion specifiers: Literal conversion specifiers. + (line 6) +* litout: Combination. (line 59) +* ln: ln invocation. (line 6) +* ln format for nl: nl invocation. (line 98) +* lnext: Characters. (line 62) +* local file system types: df invocation. (line 125) +* local settings: Local. (line 6) +* logging out and continuing to run: nohup invocation. (line 6) +* logical and operator <1>: Relations for expr. (line 17) +* logical and operator: Connectives for test. + (line 12) +* logical connectives <1>: Relations for expr. (line 6) +* logical connectives: Connectives for test. + (line 6) +* logical or operator <1>: Relations for expr. (line 11) +* logical or operator: Connectives for test. + (line 15) +* logical pages, numbering on: nl invocation. (line 12) +* login name, printing: logname invocation. (line 6) +* login sessions, printing users with: users invocation. (line 6) +* login shell: su invocation. (line 18) +* login shell, creating: su invocation. (line 53) +* login time: who invocation. (line 11) +* LOGNAME: su invocation. (line 18) +* logname: logname invocation. (line 6) +* long ls format: What information is listed. + (line 130) +* lower: Character sets. (line 109) +* lowercase, translating to output: Output. (line 12) +* ls: ls invocation. (line 6) +* LS_BLOCK_SIZE: Block size. (line 12) +* LS_COLORS: dircolors invocation. + (line 16) +* machine type: uname invocation. (line 41) +* machine-readable stty output: stty invocation. (line 41) +* MacKenzie, D.: Introduction. (line 19) +* MacKenzie, David: Authors of get_date. (line 6) +* Makefiles, installing programs in: install invocation. (line 30) +* manipulating files: Basic operations. (line 6) +* manipulation of file names: File name manipulation. + (line 6) +* match: String expressions. (line 36) +* matching patterns: String expressions. (line 11) +* MD5: md5sum invocation. (line 6) +* md5sum: md5sum invocation. (line 6) +* mebibyte, definition of: Block size. (line 92) +* mebibytes for file sizes: du invocation. (line 101) +* megabyte, definition of: Block size. (line 88) +* merging files: paste invocation. (line 6) +* merging files in parallel: pr invocation. (line 6) +* merging sorted files: sort invocation. (line 32) +* message status: who invocation. (line 86) +* message-digest, 128-bit: md5sum invocation. (line 6) +* message-digest, 160-bit: sha1sum invocation. (line 6) +* message-digest, 224-bit: sha2 utilities. (line 6) +* message-digest, 256-bit: sha2 utilities. (line 6) +* message-digest, 384-bit: sha2 utilities. (line 6) +* message-digest, 512-bit: sha2 utilities. (line 6) +* Meyering, J.: Introduction. (line 19) +* Meyering, Jim: Authors of get_date. (line 6) +* midnight in date strings: Time of day items. (line 22) +* min: Special. (line 7) +* minute in date strings: Relative items in date strings. + (line 15) +* minutes, time zone correction by: Time of day items. (line 30) +* MIT AI lab: su invocation. (line 92) +* mkdir: mkdir invocation. (line 6) +* mkfifo: mkfifo invocation. (line 6) +* mknod: mknod invocation. (line 6) +* modem control: Control. (line 33) +* modes and umask: Umask and Protection. + (line 6) +* modes of created directories, setting: mkdir invocation. (line 19) +* modes of created FIFOs, setting: mkfifo invocation. (line 21) +* modification time, sorting files by: Sorting the output. (line 36) +* modified command invocation: Modified command invocation. + (line 6) +* modified environment, running a program in a: env invocation. + (line 6) +* modify time, changing: touch invocation. (line 73) +* month in date strings: Relative items in date strings. + (line 15) +* month names in date strings: Calendar date items. (line 38) +* months, sorting by: sort invocation. (line 131) +* months, written-out: General date syntax. (line 36) +* MS-DOS file system: df invocation. (line 133) +* mtime, changing: touch invocation. (line 73) +* multicolumn output, generating: pr invocation. (line 6) +* multiple changes to permissions: Multiple Changes. (line 6) +* multiplication: Numeric expressions. (line 15) +* multipliers after numbers: dd invocation. (line 204) +* mv: mv invocation. (line 6) +* name follow option: tail invocation. (line 41) +* name of kernel: uname invocation. (line 65) +* named pipe check: File type tests. (line 28) +* named pipes, creating: mkfifo invocation. (line 6) +* network node name: uname invocation. (line 46) +* never interactive option: rm invocation. (line 52) +* newer files, copying only: cp invocation. (line 277) +* newer files, moving only: mv invocation. (line 76) +* newer-than file check: File characteristic tests. + (line 15) +* newline echoing after kill: Local. (line 26) +* newline, echoing: Local. (line 29) +* newline, translating to crlf: Output. (line 19) +* newline, translating to return: Input. (line 26) +* next DAY <1>: Day of week items. (line 15) +* next DAY: Options for date. (line 11) +* next in date strings: General date syntax. (line 26) +* NFS file system type: df invocation. (line 120) +* NFS mounts from BSD to HP-UX <1>: du invocation. (line 206) +* NFS mounts from BSD to HP-UX: What information is listed. + (line 250) +* nice: nice invocation. (line 6) +* niceness: nice invocation. (line 6) +* nl <1>: Combination. (line 18) +* nl: nl invocation. (line 6) +* nlN: Output. (line 39) +* no-op: true invocation. (line 6) +* noatime: dd invocation. (line 171) +* nocreat: dd invocation. (line 103) +* noctty: dd invocation. (line 176) +* node name: uname invocation. (line 46) +* noerror: dd invocation. (line 100) +* noflsh: Local. (line 32) +* nofollow: dd invocation. (line 182) +* nohup: nohup invocation. (line 6) +* nohup.out: nohup invocation. (line 6) +* nolinks: dd invocation. (line 185) +* non-directories, copying as special files: cp invocation. (line 76) +* non-directory suffix, stripping: dirname invocation. (line 6) +* nonblock: dd invocation. (line 168) +* nonblocking I/O: dd invocation. (line 168) +* none backup method: Backup options. (line 31) +* none color option: General output formatting. + (line 23) +* none, sorting option for ls: Sorting the output. (line 49) +* nonempty file check: File characteristic tests. + (line 12) +* nonprinting characters, ignoring: sort invocation. (line 125) +* nonzero-length string check: String tests. (line 19) +* noon in date strings: Time of day items. (line 22) +* not-equal string check: String tests. (line 25) +* notrunc: dd invocation. (line 113) +* now in date strings: Relative items in date strings. + (line 33) +* numbered backup method: Backup options. (line 35) +* numbering lines: nl invocation. (line 6) +* numbers, written-out: General date syntax. (line 26) +* numeric expressions: Numeric expressions. (line 6) +* numeric field padding: Padding and other flags. + (line 6) +* numeric modes: Numeric Modes. (line 6) +* numeric operations: Numeric operations. (line 6) +* numeric sequences: seq invocation. (line 6) +* numeric sort: sort invocation. (line 140) +* numeric tests: Numeric tests. (line 6) +* numeric uid and gid: What information is listed. + (line 232) +* numeric user and group IDs: What information is listed. + (line 232) +* obs: dd invocation. (line 29) +* ocrnl: Output. (line 16) +* octal dump of files: od invocation. (line 6) +* octal numbers for file modes: Numeric Modes. (line 6) +* od: od invocation. (line 6) +* odd parity: Control. (line 13) +* oddp: Combination. (line 14) +* of: dd invocation. (line 20) +* ofdel: Output. (line 34) +* ofill: Output. (line 30) +* oflag: dd invocation. (line 134) +* olcuc: Output. (line 12) +* older-than file check: File characteristic tests. + (line 19) +* once interactive option: rm invocation. (line 54) +* one file system, restricting du to: du invocation. (line 191) +* one file system, restricting rm to: rm invocation. (line 63) +* one-line output format: df invocation. (line 74) +* onlcr: Output. (line 19) +* onlret: Output. (line 27) +* onocr: Output. (line 23) +* operating on characters: Operating on characters. + (line 6) +* operating on sorted files: Operating on sorted files. + (line 6) +* operating system name: uname invocation. (line 57) +* opost: Output. (line 9) +* option delimiter: Common options. (line 36) +* options for date: Options for date. (line 6) +* or operator <1>: Relations for expr. (line 11) +* or operator: Connectives for test. + (line 15) +* ordinal numbers: General date syntax. (line 26) +* ospeed: Special. (line 19) +* other permissions: Setting Permissions. (line 29) +* output block size: dd invocation. (line 29) +* output file name prefix <1>: csplit invocation. (line 62) +* output file name prefix: split invocation. (line 14) +* output file name suffix: csplit invocation. (line 66) +* output format: stat invocation. (line 28) +* output format, portable: df invocation. (line 74) +* output null-byte-terminated lines: du invocation. (line 117) +* output of entire files: Output of entire files. + (line 6) +* output of parts of files: Output of parts of files. + (line 6) +* output settings: Output. (line 6) +* output tabs: pr invocation. (line 140) +* overwriting of input, allowed <1>: shuf invocation. (line 37) +* overwriting of input, allowed: sort invocation. (line 213) +* owned by effective group ID check: Access permission tests. + (line 31) +* owned by effective user ID check: Access permission tests. + (line 28) +* owner of file, permissions for: Setting Permissions. (line 23) +* owner, default: Mode Structure. (line 31) +* ownership of installed files, setting: install invocation. (line 72) +* p for FIFO file: mknod invocation. (line 23) +* pad character: Output. (line 34) +* pad instead of timing for delaying: Output. (line 30) +* padding of numeric fields: Padding and other flags. + (line 6) +* paragraphs, reformatting: fmt invocation. (line 6) +* parenb: Control. (line 9) +* parent directories and cp: cp invocation. (line 177) +* parent directories, creating: mkdir invocation. (line 34) +* parent directories, creating missing: install invocation. (line 48) +* parent directories, removing: rmdir invocation. (line 22) +* parentheses for grouping: expr invocation. (line 31) +* parity: Combination. (line 10) +* parity errors, marking: Input. (line 16) +* parity, ignoring: Input. (line 13) +* parmrk: Input. (line 16) +* parodd: Control. (line 13) +* parsing date strings: Options for date. (line 11) +* parts of files, output of: Output of parts of files. + (line 6) +* pass8: Combination. (line 55) +* passwd entry, and su shell: su invocation. (line 12) +* paste: paste invocation. (line 6) +* Paterson, R.: Introduction. (line 19) +* PATH <1>: su invocation. (line 53) +* PATH: env invocation. (line 24) +* pathchk: pathchk invocation. (line 6) +* pattern matching: String expressions. (line 11) +* PC file system: df invocation. (line 133) +* pcfs: df invocation. (line 133) +* pebibyte, definition of: Block size. (line 113) +* permission tests: Access permission tests. + (line 6) +* permissions of installed files, setting: install invocation. + (line 60) +* permissions, changing access: chmod invocation. (line 6) +* permissions, copying existing: Copying Permissions. (line 6) +* permissions, for changing file timestamps: touch invocation. + (line 16) +* permissions, output by ls: What information is listed. + (line 190) +* petabyte, definition of: Block size. (line 109) +* phone directory order: sort invocation. (line 85) +* pieces, splitting a file into: split invocation. (line 6) +* Pinard, F. <1>: Authors of get_date. (line 14) +* Pinard, F.: Introduction. (line 19) +* pipe fitting: tee invocation. (line 6) +* Plass, Michael F.: fmt invocation. (line 19) +* platform, hardware: uname invocation. (line 35) +* pm in date strings: Time of day items. (line 22) +* portable file names, checking for: pathchk invocation. (line 6) +* portable output format: df invocation. (line 74) +* POSIX: Introduction. (line 11) +* POSIX output format: df invocation. (line 74) +* POSIXLY_CORRECT <1>: printf invocation. (line 42) +* POSIXLY_CORRECT <2>: echo invocation. (line 68) +* POSIXLY_CORRECT <3>: dd invocation. (line 237) +* POSIXLY_CORRECT <4>: sort invocation. (line 221) +* POSIXLY_CORRECT <5>: tail invocation. (line 75) +* POSIXLY_CORRECT <6>: pr invocation. (line 107) +* POSIXLY_CORRECT <7>: Standards conformance. + (line 6) +* POSIXLY_CORRECT: Common options. (line 11) +* POSIXLY_CORRECT, and block size: Block size. (line 12) +* pr: pr invocation. (line 6) +* prime factors: factor invocation. (line 6) +* print: Character sets. (line 112) +* print name of current directory: pwd invocation. (line 6) +* print system information: uname invocation. (line 6) +* print terminal file name: tty invocation. (line 6) +* printenv: printenv invocation. (line 6) +* printf: printf invocation. (line 6) +* printing all or some environment variables: printenv invocation. + (line 6) +* printing color database: dircolors invocation. + (line 38) +* printing current user information: who invocation. (line 6) +* printing current usernames: users invocation. (line 6) +* printing groups a user is in: groups invocation. (line 6) +* printing real and effective user and group IDs: id invocation. + (line 6) +* printing text: echo invocation. (line 6) +* printing text, commands for: Printing text. (line 6) +* printing the current time: date invocation. (line 6) +* printing the effective user ID: whoami invocation. (line 6) +* printing the host identifier: hostid invocation. (line 6) +* printing the hostname: hostname invocation. (line 6) +* printing user's login name: logname invocation. (line 6) +* printing, preparing files for: pr invocation. (line 6) +* processes, commands for controlling: Process control. (line 6) +* prompting, and ln: ln invocation. (line 71) +* prompting, and mv: mv invocation. (line 34) +* prompting, and rm: rm invocation. (line 11) +* prompts, forcing: mv invocation. (line 59) +* prompts, omitting: mv invocation. (line 55) +* prterase: Local. (line 46) +* ptx: ptx invocation. (line 6) +* punct: Character sets. (line 115) +* pure numbers in date strings: Pure numbers in date strings. + (line 6) +* pwd: pwd invocation. (line 6) +* quit: Characters. (line 23) +* quoting style: Formatting the file names. + (line 34) +* radix for file offsets: od invocation. (line 36) +* random sort: sort invocation. (line 162) +* random source for shredding: shred invocation. (line 112) +* random source for shuffling: shuf invocation. (line 43) +* random source for sorting: sort invocation. (line 226) +* random sources: Random sources. (line 6) +* ranges: Character sets. (line 50) +* raw: Combination. (line 43) +* read errors, ignoring: dd invocation. (line 100) +* read from stdin and write to stdout and files: tee invocation. + (line 6) +* read permission: Mode Structure. (line 12) +* read permission, symbolic: Setting Permissions. (line 57) +* read system call, and holes: cp invocation. (line 216) +* readable file check: Access permission tests. + (line 15) +* readlink: readlink invocation. (line 6) +* real user and group IDs, printing: id invocation. (line 6) +* recursive directory listing: Which files are listed. + (line 90) +* recursively changing access permissions: chmod invocation. (line 69) +* recursively changing file ownership: chown invocation. (line 140) +* recursively changing group ownership: chgrp invocation. (line 66) +* recursively copying directories: cp invocation. (line 76) +* redirection: Redirection. (line 6) +* reformatting paragraph text: fmt invocation. (line 6) +* regular expression matching: String expressions. (line 11) +* regular file check: File type tests. (line 19) +* relations, numeric or string: Relations for expr. (line 6) +* relative items in date strings: Relative items in date strings. + (line 6) +* release of kernel: uname invocation. (line 61) +* remainder: Numeric expressions. (line 15) +* remote hostname: who invocation. (line 11) +* removing empty directories: rmdir invocation. (line 6) +* removing files after shredding: shred invocation. (line 123) +* removing files or directories: rm invocation. (line 6) +* removing files or directories (via the unlink syscall): unlink invocation. + (line 6) +* removing permissions: Setting Permissions. (line 42) +* repeated characters: Character sets. (line 71) +* repeated lines, outputting: uniq invocation. (line 63) +* repeated output of a string: yes invocation. (line 6) +* restricted deletion flag: Mode Structure. (line 56) +* restricted shell: su invocation. (line 64) +* return, ignoring: Input. (line 29) +* return, translating to newline <1>: Output. (line 16) +* return, translating to newline: Input. (line 32) +* reverse sorting <1>: Sorting the output. (line 27) +* reverse sorting: sort invocation. (line 157) +* reversing files: tac invocation. (line 6) +* rm: rm invocation. (line 6) +* rmdir: rmdir invocation. (line 6) +* rn format for nl: nl invocation. (line 101) +* root as default owner: install invocation. (line 72) +* root directory, allow recursive destruction: rm invocation. (line 84) +* root directory, allow recursive modification <1>: chmod invocation. + (line 54) +* root directory, allow recursive modification <2>: chgrp invocation. + (line 48) +* root directory, allow recursive modification: chown invocation. + (line 121) +* root directory, disallow recursive destruction: rm invocation. + (line 79) +* root directory, disallow recursive modification <1>: chmod invocation. + (line 49) +* root directory, disallow recursive modification <2>: chgrp invocation. + (line 43) +* root directory, disallow recursive modification: chown invocation. + (line 116) +* root directory, running a program in a specified: chroot invocation. + (line 6) +* root, becoming: su invocation. (line 6) +* rows: Special. (line 22) +* rprnt: Characters. (line 56) +* RTS/CTS flow control: Control. (line 36) +* running a program in a modified environment: env invocation. + (line 6) +* running a program in a specified root directory: chroot invocation. + (line 6) +* rz format for nl: nl invocation. (line 104) +* Salz, Rich: Authors of get_date. (line 6) +* same file check: File characteristic tests. + (line 23) +* sane: Combination. (line 26) +* scheduling, affecting: nice invocation. (line 6) +* screen columns: fold invocation. (line 14) +* seconds since the epoch: Time conversion specifiers. + (line 41) +* section delimiters of pages: nl invocation. (line 68) +* seek: dd invocation. (line 46) +* self-backups: cp invocation. (line 42) +* send a signal to processes: kill invocation. (line 6) +* sentences and line-breaking: fmt invocation. (line 19) +* separator for numbers in seq: seq invocation. (line 42) +* seq: seq invocation. (line 6) +* sequence of numbers: seq invocation. (line 6) +* set-group-ID: Mode Structure. (line 49) +* set-group-ID check: Access permission tests. + (line 9) +* set-user-ID: Mode Structure. (line 42) +* set-user-ID check: Access permission tests. + (line 18) +* setgid: Mode Structure. (line 49) +* setting permissions: Setting Permissions. (line 46) +* setting the hostname: hostname invocation. (line 6) +* setting the time: Setting the time. (line 6) +* setuid: Mode Structure. (line 42) +* setup for color: dircolors invocation. + (line 6) +* sh syntax for color setup: dircolors invocation. + (line 27) +* SHA-1: sha1sum invocation. (line 6) +* SHA-2: sha2 utilities. (line 6) +* sha1sum: sha1sum invocation. (line 6) +* sha224sum: sha2 utilities. (line 6) +* sha256sum: sha2 utilities. (line 6) +* sha384sum: sha2 utilities. (line 6) +* sha512sum: sha2 utilities. (line 6) +* SHELL: su invocation. (line 18) +* SHELL environment variable, and color: dircolors invocation. + (line 16) +* shell utilities: Top. (line 19) +* shred: shred invocation. (line 6) +* shuf: shuf invocation. (line 6) +* shuffling files: shuf invocation. (line 6) +* SI output <1>: du invocation. (line 123) +* SI output <2>: df invocation. (line 93) +* SI output <3>: What information is listed. + (line 258) +* SI output: Block size. (line 43) +* simple backup method: Backup options. (line 44) +* SIMPLE_BACKUP_SUFFIX: Backup options. (line 50) +* single-column output of files: General output formatting. + (line 10) +* size: Special. (line 30) +* size for main memory sorting: sort invocation. (line 237) +* size of file to shred: shred invocation. (line 117) +* size of files, reporting: What information is listed. + (line 242) +* size of files, sorting files by: Sorting the output. (line 32) +* skip: dd invocation. (line 43) +* sleep: sleep invocation. (line 6) +* socket check: File type tests. (line 31) +* software flow control: Input. (line 43) +* sort: sort invocation. (line 6) +* sort field: sort invocation. (line 193) +* sort stability: sort invocation. (line 38) +* sort zero-terminated lines <1>: shuf invocation. (line 48) +* sort zero-terminated lines: sort invocation. (line 296) +* sort's last-resort comparison: sort invocation. (line 38) +* sorted files, operations on: Operating on sorted files. + (line 6) +* sorting files: sort invocation. (line 6) +* sorting ls output: Sorting the output. (line 6) +* space: Character sets. (line 118) +* sparse files, copying: cp invocation. (line 216) +* special characters: Characters. (line 6) +* special file types: Special file types. (line 6) +* special files: mknod invocation. (line 11) +* special settings: Special. (line 6) +* specifying sets of characters: Character sets. (line 6) +* speed: Special. (line 40) +* split: split invocation. (line 6) +* splitting a file into pieces: split invocation. (line 6) +* splitting a file into pieces by context: csplit invocation. (line 6) +* squeezing blank lines: cat invocation. (line 35) +* squeezing repeat characters: Squeezing. (line 6) +* Stallman, R.: Introduction. (line 19) +* standard input: Common options. (line 41) +* standard output: Common options. (line 41) +* start: Characters. (line 44) +* stat: stat invocation. (line 6) +* status time, printing or sorting by: Sorting the output. (line 13) +* status time, show the most recent: du invocation. (line 144) +* sticky: Mode Structure. (line 56) +* sticky bit check: Access permission tests. + (line 12) +* stop: Characters. (line 47) +* stop bits: Control. (line 27) +* strftime and date: date invocation. (line 20) +* string constants, outputting: od invocation. (line 68) +* string expressions: String expressions. (line 6) +* string tests: String tests. (line 6) +* strip directory and suffix from file names: basename invocation. + (line 6) +* stripping non-directory suffix: dirname invocation. (line 6) +* stripping symbol table information: install invocation. (line 88) +* stripping trailing slashes <1>: mv invocation. (line 89) +* stripping trailing slashes: cp invocation. (line 250) +* stty: stty invocation. (line 6) +* su: su invocation. (line 6) +* substitute user and group IDs: su invocation. (line 6) +* substr: String expressions. (line 40) +* subtracting permissions: Setting Permissions. (line 42) +* subtraction: Numeric expressions. (line 11) +* successful exit: true invocation. (line 6) +* suffix, stripping from file names: basename invocation. (line 6) +* sum: sum invocation. (line 6) +* summarizing files: Summarizing files. (line 6) +* super-user, becoming: su invocation. (line 6) +* superblock, writing: sync invocation. (line 6) +* supplementary groups, printing: groups invocation. (line 6) +* susp: Characters. (line 50) +* swab (byte-swapping): dd invocation. (line 95) +* swap space, saving text image in: Mode Structure. (line 56) +* swtch: Characters. (line 41) +* symbol table information, stripping: install invocation. (line 88) +* symbolic (soft) links, creating: ln invocation. (line 6) +* symbolic link check: File type tests. (line 23) +* symbolic link to directory, controlling traversal of: Traversing symlinks. + (line 6) +* symbolic link to directory, never traverse <1>: chgrp invocation. + (line 79) +* symbolic link to directory, never traverse <2>: chown invocation. + (line 152) +* symbolic link to directory, never traverse: Traversing symlinks. + (line 26) +* symbolic link to directory, traverse each that is encountered <1>: chgrp invocation. + (line 75) +* symbolic link to directory, traverse each that is encountered <2>: chown invocation. + (line 148) +* symbolic link to directory, traverse each that is encountered: Traversing symlinks. + (line 22) +* symbolic link to directory, traverse each that is specified on the command line <1>: chgrp invocation. + (line 70) +* symbolic link to directory, traverse each that is specified on the command line <2>: chown invocation. + (line 143) +* symbolic link to directory, traverse each that is specified on the command line: Traversing symlinks. + (line 18) +* symbolic link, defined: ln invocation. (line 40) +* symbolic links and pwd: pwd invocation. (line 6) +* symbolic links, changing group: chgrp invocation. (line 35) +* symbolic links, changing owner <1>: chgrp invocation. (line 30) +* symbolic links, changing owner: chown invocation. (line 80) +* symbolic links, copying: cp invocation. (line 89) +* symbolic links, copying with: cp invocation. (line 255) +* symbolic links, dereferencing: Which files are listed. + (line 36) +* symbolic links, dereferencing in du: du invocation. (line 96) +* symbolic links, dereferencing in stat: stat invocation. (line 17) +* symbolic links, following: dd invocation. (line 182) +* symbolic links, permissions of: chmod invocation. (line 10) +* symbolic modes: Symbolic Modes. (line 6) +* sync <1>: sync invocation. (line 6) +* sync: dd invocation. (line 165) +* sync (padding with nulls): dd invocation. (line 116) +* synchronize disk and memory: sync invocation. (line 6) +* synchronized data and metadata I/O: dd invocation. (line 165) +* synchronized data and metadata writes, before finishing: dd invocation. + (line 125) +* synchronized data reads: dd invocation. (line 157) +* synchronized data writes, before finishing: dd invocation. (line 121) +* syslog: su invocation. (line 29) +* system context: System context. (line 6) +* system information, printing: uname invocation. (line 6) +* system name, printing: hostname invocation. (line 6) +* System V sum: sum invocation. (line 31) +* tab stops, setting: expand invocation. (line 22) +* tabN: Output. (line 51) +* tabs: Combination. (line 66) +* tabs to spaces, converting: expand invocation. (line 6) +* tac: tac invocation. (line 6) +* tagged paragraphs: fmt invocation. (line 40) +* tail: tail invocation. (line 6) +* tandem: Input. (line 43) +* target directory <1>: ln invocation. (line 105) +* target directory <2>: mv invocation. (line 99) +* target directory <3>: install invocation. (line 97) +* target directory <4>: cp invocation. (line 268) +* target directory: Target directory. (line 6) +* tebibyte, definition of: Block size. (line 106) +* tee: tee invocation. (line 6) +* telephone directory order: sort invocation. (line 85) +* temporary directory: sort invocation. (line 273) +* terabyte, definition of: Block size. (line 102) +* TERM: su invocation. (line 53) +* terminal check: File type tests. (line 34) +* terminal file name, printing: tty invocation. (line 6) +* terminal lines, currently used: who invocation. (line 11) +* terminal settings: stty invocation. (line 6) +* terminal, using color iff: General output formatting. + (line 25) +* terse output: stat invocation. (line 48) +* test: test invocation. (line 6) +* text: dd invocation. (line 192) +* text I/O: dd invocation. (line 192) +* text image, saving in swap space: Mode Structure. (line 56) +* text input files: md5sum invocation. (line 79) +* text utilities: Top. (line 19) +* text, displaying: echo invocation. (line 6) +* text, reformatting: fmt invocation. (line 6) +* this in date strings: Relative items in date strings. + (line 33) +* time <1>: Special. (line 11) +* time: touch invocation. (line 58) +* time conversion specifiers: Time conversion specifiers. + (line 6) +* time formats <1>: date invocation. (line 20) +* time formats: pr invocation. (line 100) +* time of day item: Time of day items. (line 6) +* time setting: Setting the time. (line 6) +* time style <1>: du invocation. (line 153) +* time style: Formatting file timestamps. + (line 26) +* time units: sleep invocation. (line 11) +* time zone correction: Time of day items. (line 30) +* time zone item <1>: Time zone items. (line 6) +* time zone item: General date syntax. (line 44) +* time, printing or setting: date invocation. (line 6) +* TIME_STYLE <1>: du invocation. (line 181) +* TIME_STYLE: Formatting file timestamps. + (line 106) +* timestamps of installed files, preserving: install invocation. + (line 78) +* timestamps, changing file: touch invocation. (line 6) +* TMPDIR: sort invocation. (line 64) +* today in date strings: Relative items in date strings. + (line 33) +* tomorrow: Options for date. (line 11) +* tomorrow in date strings: Relative items in date strings. + (line 29) +* topological sort: tsort invocation. (line 6) +* tostop: Local. (line 41) +* total counts: wc invocation. (line 12) +* touch: touch invocation. (line 6) +* tr: tr invocation. (line 6) +* trailing slashes: Trailing slashes. (line 6) +* translating characters: Translating. (line 6) +* true: true invocation. (line 6) +* truncating output file, avoiding: dd invocation. (line 113) +* tsort: tsort invocation. (line 6) +* tty: tty invocation. (line 6) +* Twenex: su invocation. (line 92) +* two-way parity: Control. (line 9) +* type size: od invocation. (line 113) +* TZ <1>: Specifying time zone rules. + (line 6) +* TZ <2>: Options for date. (line 83) +* TZ <3>: date invocation. (line 16) +* TZ <4>: who invocation. (line 26) +* TZ <5>: stat invocation. (line 131) +* TZ <6>: touch invocation. (line 37) +* TZ <7>: Formatting file timestamps. + (line 18) +* TZ: pr invocation. (line 113) +* u, and disabling special characters: Characters. (line 13) +* ucase, converting to: dd invocation. (line 90) +* ufs file system type: df invocation. (line 125) +* umask and modes: Umask and Protection. + (line 6) +* uname: uname invocation. (line 6) +* unblock: dd invocation. (line 81) +* unexpand: unexpand invocation. (line 6) +* Unicode: printf invocation. (line 62) +* uniq: uniq invocation. (line 6) +* unique lines, outputting: uniq invocation. (line 98) +* uniquify files: uniq invocation. (line 6) +* uniquifying output: sort invocation. (line 282) +* unlink: unlink invocation. (line 6) +* unprintable characters, ignoring: sort invocation. (line 125) +* unsorted directory listing: Sorting the output. (line 20) +* upper: Character sets. (line 121) +* uppercase, translating to lowercase: Input. (line 48) +* use time, changing: touch invocation. (line 50) +* use time, printing or sorting files by: Sorting the output. (line 13) +* use time, show the most recent: du invocation. (line 144) +* USER: su invocation. (line 18) +* user ID, switching: su invocation. (line 6) +* user IDs, disambiguating: Disambiguating names and IDs. + (line 6) +* user information, commands for: User information. (line 6) +* user name, printing: logname invocation. (line 6) +* user names, disambiguating: Disambiguating names and IDs. + (line 6) +* usernames, printing current: users invocation. (line 6) +* users: users invocation. (line 6) +* UTC: Options for date. (line 83) +* utmp <1>: who invocation. (line 15) +* utmp <2>: users invocation. (line 14) +* utmp: logname invocation. (line 6) +* valid file names, checking for: pathchk invocation. (line 6) +* variable-length records, converting to fixed-length: dd invocation. + (line 38) +* vdir: vdir invocation. (line 6) +* verbose ls format: What information is listed. + (line 130) +* verifying MD5 checksums: md5sum invocation. (line 69) +* version number, finding: Common options. (line 33) +* version of kernel: uname invocation. (line 76) +* version, sorting option for ls: Sorting the output. (line 56) +* version-control Emacs variable: Backup options. (line 24) +* VERSION_CONTROL <1>: ln invocation. (line 55) +* VERSION_CONTROL <2>: mv invocation. (line 50) +* VERSION_CONTROL <3>: install invocation. (line 40) +* VERSION_CONTROL <4>: cp invocation. (line 61) +* VERSION_CONTROL: Backup options. (line 13) +* vertical sorted files in columns: General output formatting. + (line 15) +* vtN: Output. (line 59) +* wc: wc invocation. (line 6) +* week in date strings: Relative items in date strings. + (line 15) +* werase: Characters. (line 59) +* wheel group, not supported: su invocation. (line 87) +* who: who invocation. (line 6) +* who am i: who invocation. (line 21) +* whoami: whoami invocation. (line 6) +* word count: wc invocation. (line 6) +* working context: Working context. (line 6) +* working directory, printing: pwd invocation. (line 6) +* wrap data: base64 invocation. (line 21) +* wrapping long input lines: fold invocation. (line 6) +* writable file check: Access permission tests. + (line 21) +* write permission: Mode Structure. (line 15) +* write permission, symbolic: Setting Permissions. (line 60) +* write, allowed: who invocation. (line 86) +* wtmp <1>: who invocation. (line 15) +* wtmp: users invocation. (line 14) +* xcase: Local. (line 36) +* xdigit: Character sets. (line 124) +* XON/XOFF flow control: Input. (line 38) +* year in date strings: Relative items in date strings. + (line 15) +* yes: yes invocation. (line 6) +* yesterday: Options for date. (line 11) +* yesterday in date strings: Relative items in date strings. + (line 29) +* yottabyte, definition of: Block size. (line 131) +* Youmans, B.: Introduction. (line 19) +* zero-length string check: String tests. (line 15) +* zettabyte, definition of: Block size. (line 123) +* |: Relations for expr. (line 11) + + + +Tag Table: +Node: Top7718 +Node: Introduction20818 +Node: Common options22377 +Node: Exit status25162 +Node: Backup options25892 +Node: Block size27816 +Node: Disambiguating names and IDs32732 +Ref: Disambiguating names and IDs-Footnote-134290 +Node: Random sources34360 +Node: Target directory36109 +Node: Trailing slashes39594 +Node: Traversing symlinks40615 +Node: Treating / specially41686 +Node: Special built-in utilities43227 +Node: Standards conformance44362 +Node: Output of entire files45878 +Node: cat invocation46479 +Node: tac invocation48207 +Node: nl invocation49469 +Node: od invocation53348 +Node: base64 invocation59711 +Node: Formatting file contents61073 +Node: fmt invocation61524 +Node: pr invocation64337 +Node: fold invocation77122 +Node: Output of parts of files78582 +Node: head invocation79090 +Node: tail invocation80806 +Node: split invocation88629 +Node: csplit invocation90715 +Node: Summarizing files94827 +Node: wc invocation95475 +Node: sum invocation98360 +Node: cksum invocation99765 +Node: md5sum invocation100905 +Node: sha1sum invocation105599 +Node: sha2 utilities106379 +Node: Operating on sorted files107003 +Node: sort invocation107659 +Ref: sort invocation-Footnote-1127034 +Node: shuf invocation127586 +Node: uniq invocation130150 +Node: comm invocation134230 +Node: tsort invocation135558 +Node: tsort background138592 +Node: ptx invocation140355 +Node: General options in ptx143159 +Node: Charset selection in ptx143740 +Node: Input processing in ptx144642 +Node: Output formatting in ptx150063 +Node: Compatibility in ptx156629 +Node: Operating on fields within a line159858 +Node: cut invocation160262 +Node: paste invocation163581 +Node: join invocation164909 +Node: Operating on characters169133 +Node: tr invocation169569 +Node: Character sets171287 +Node: Translating175718 +Node: Squeezing177809 +Node: expand invocation180876 +Node: unexpand invocation182358 +Node: Directory listing184176 +Node: ls invocation184662 +Ref: ls invocation-Footnote-1186476 +Node: Which files are listed186698 +Node: What information is listed190358 +Node: Sorting the output199334 +Node: More details about version sort201654 +Node: General output formatting203152 +Node: Formatting file timestamps207060 +Node: Formatting the file names212401 +Node: dir invocation215317 +Node: vdir invocation215728 +Node: dircolors invocation216106 +Node: Basic operations217586 +Node: cp invocation218206 +Node: dd invocation230266 +Node: install invocation238684 +Node: mv invocation242911 +Node: rm invocation247201 +Node: shred invocation251515 +Node: Special file types259000 +Node: link invocation260496 +Node: ln invocation261502 +Node: mkdir invocation266564 +Node: mkfifo invocation268813 +Node: mknod invocation269818 +Node: readlink invocation271577 +Node: rmdir invocation273320 +Node: unlink invocation274593 +Node: Changing file attributes275552 +Node: chown invocation276366 +Node: chgrp invocation282552 +Node: chmod invocation285602 +Node: touch invocation288357 +Node: Disk usage292953 +Node: df invocation293545 +Node: du invocation299217 +Node: stat invocation307207 +Node: sync invocation311049 +Node: Printing text311976 +Node: echo invocation312350 +Node: printf invocation314527 +Node: yes invocation319234 +Node: Conditions319846 +Node: false invocation320437 +Node: true invocation321472 +Node: test invocation322751 +Node: File type tests324711 +Node: Access permission tests325593 +Node: File characteristic tests326478 +Node: String tests327243 +Node: Numeric tests327908 +Node: Connectives for test328705 +Node: expr invocation329058 +Node: String expressions331319 +Node: Numeric expressions333902 +Node: Relations for expr334540 +Node: Examples of expr335740 +Node: Redirection336468 +Node: tee invocation336913 +Node: File name manipulation337978 +Node: basename invocation338426 +Node: dirname invocation339873 +Node: pathchk invocation341079 +Node: Working context342743 +Node: pwd invocation343387 +Node: stty invocation344061 +Node: Control346821 +Node: Input347581 +Node: Output349057 +Node: Local350313 +Node: Combination351895 +Node: Characters354057 +Node: Special355611 +Node: printenv invocation356977 +Node: tty invocation357740 +Node: User information358446 +Node: id invocation359081 +Node: logname invocation360297 +Node: whoami invocation360924 +Node: groups invocation361411 +Node: users invocation362147 +Node: who invocation363094 +Node: System context365863 +Node: date invocation366353 +Node: Time conversion specifiers368011 +Node: Date conversion specifiers370411 +Node: Literal conversion specifiers373535 +Node: Padding and other flags373893 +Node: Setting the time376087 +Node: Options for date377093 +Node: Examples of date380398 +Ref: %s-examples381841 +Node: uname invocation384026 +Node: hostname invocation386599 +Node: hostid invocation387212 +Node: Modified command invocation387899 +Node: chroot invocation388525 +Node: env invocation390644 +Node: nice invocation392723 +Node: nohup invocation396219 +Node: su invocation398210 +Node: Process control402683 +Node: kill invocation402906 +Node: Delaying407272 +Node: sleep invocation407469 +Node: Numeric operations408333 +Node: factor invocation408665 +Node: seq invocation410003 +Node: File permissions414284 +Node: Mode Structure414902 +Node: Symbolic Modes418597 +Node: Setting Permissions419695 +Node: Copying Permissions422308 +Node: Changing Special Mode Bits423127 +Node: Conditional Executability424949 +Node: Multiple Changes425493 +Node: Umask and Protection427160 +Node: Numeric Modes428265 +Node: Directory Setuid and Setgid430165 +Node: Date input formats432427 +Node: General date syntax434780 +Node: Calendar date items437739 +Node: Time of day items439744 +Node: Time zone items441868 +Node: Day of week items443110 +Node: Relative items in date strings444107 +Node: Pure numbers in date strings446917 +Node: Seconds since the Epoch447906 +Node: Specifying time zone rules449535 +Node: Authors of get_date451907 +Node: Opening the software toolbox452667 +Node: Toolbox introduction453328 +Node: I/O redirection456051 +Node: The who command458885 +Node: The cut command459782 +Node: The sort command460845 +Node: The uniq command461549 +Node: Putting the tools together462239 +Ref: Putting the tools together-Footnote-1474196 +Node: Copying This Manual474270 +Node: GNU Free Documentation License474525 +Node: Index496926 + +End Tag Table diff --git a/doc/coreutils.texi b/doc/coreutils.texi new file mode 100644 index 0000000..588147f --- /dev/null +++ b/doc/coreutils.texi @@ -0,0 +1,14638 @@ +\input texinfo +@c %**start of header +@setfilename coreutils.info +@settitle @sc{gnu} Coreutils + +@c %**end of header + +@include version.texi +@include constants.texi + +@c Define new indices. +@defcodeindex op +@defcodeindex fl + +@c Put everything in one index (arbitrarily chosen to be the concept index). +@syncodeindex fl cp +@syncodeindex fn cp +@syncodeindex ky cp +@syncodeindex op cp +@syncodeindex pg cp +@syncodeindex vr cp + +@dircategory Basics +@direntry +* Coreutils: (coreutils). Core GNU (file, text, shell) utilities. +* Common options: (coreutils)Common options. Common options. +* File permissions: (coreutils)File permissions. Access modes. +* Date input formats: (coreutils)Date input formats. +@end direntry + +@c FIXME: the following need documentation +@c * [: (coreutils)[ invocation. File/string tests. +@c * pinky: (coreutils)pinky invocation. FIXME. +@c * uptime: (coreutils)uptime invocation. FIXME. + +@dircategory Individual utilities +@direntry +* base64: (coreutils)base64 invocation. Base64 encode/decode data. +* basename: (coreutils)basename invocation. Strip directory and suffix. +* cat: (coreutils)cat invocation. Concatenate and write files. +* chgrp: (coreutils)chgrp invocation. Change file groups. +* chmod: (coreutils)chmod invocation. Change file permissions. +* chown: (coreutils)chown invocation. Change file owners/groups. +* chroot: (coreutils)chroot invocation. Specify the root directory. +* cksum: (coreutils)cksum invocation. Print POSIX CRC checksum. +* comm: (coreutils)comm invocation. Compare sorted files by line. +* cp: (coreutils)cp invocation. Copy files. +* csplit: (coreutils)csplit invocation. Split by context. +* cut: (coreutils)cut invocation. Print selected parts of lines. +* date: (coreutils)date invocation. Print/set system date and time. +* dd: (coreutils)dd invocation. Copy and convert a file. +* 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. +* du: (coreutils)du invocation. Report on disk usage. +* echo: (coreutils)echo invocation. Print a line of text. +* env: (coreutils)env invocation. Modify the environment. +* expand: (coreutils)expand invocation. Convert tabs to spaces. +* expr: (coreutils)expr invocation. Evaluate expressions. +* factor: (coreutils)factor invocation. Print prime factors +* false: (coreutils)false invocation. Do nothing, unsuccessfully. +* fmt: (coreutils)fmt invocation. Reformat paragraph text. +* fold: (coreutils)fold invocation. Wrap long input lines. +* groups: (coreutils)groups invocation. Print group names a user is in. +* head: (coreutils)head invocation. Output the first part of files. +* hostid: (coreutils)hostid invocation. Print numeric host identifier. +* hostname: (coreutils)hostname invocation. Print or set system name. +* id: (coreutils)id invocation. Print user identity. +* install: (coreutils)install invocation. Copy and change attributes. +* join: (coreutils)join invocation. Join lines on a common field. +* kill: (coreutils)kill invocation. Send a signal to processes. +* link: (coreutils)link invocation. Make hard links between files. +* ln: (coreutils)ln invocation. Make links between files. +* logname: (coreutils)logname invocation. Print current login name. +* ls: (coreutils)ls invocation. List directory contents. +* md5sum: (coreutils)md5sum invocation. Print or check MD5 digests. +* mkdir: (coreutils)mkdir invocation. Create directories. +* mkfifo: (coreutils)mkfifo invocation. Create FIFOs (named pipes). +* mknod: (coreutils)mknod invocation. Create special 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. +* 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. +* pr: (coreutils)pr invocation. Paginate or columnate files. +* printenv: (coreutils)printenv invocation. Print environment variables. +* printf: (coreutils)printf invocation. Format and print data. +* ptx: (coreutils)ptx invocation. Produce permuted indexes. +* pwd: (coreutils)pwd invocation. Print working directory. +* readlink: (coreutils)readlink invocation. Print referent of a symlink. +* rm: (coreutils)rm invocation. Remove files. +* rmdir: (coreutils)rmdir invocation. Remove empty directories. +* seq: (coreutils)seq invocation. Print numeric sequences +* sha1sum: (coreutils)sha1sum invocation. Print or check SHA-1 digests. +* sha2: (coreutils)sha2 utilities. Print or check SHA-2 digests. +* shred: (coreutils)shred invocation. Remove files more securely. +* 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. +* stat: (coreutils)stat invocation. Report file(system) status. +* stty: (coreutils)stty invocation. Print/change terminal settings. +* su: (coreutils)su invocation. Modify user and group ID. +* sum: (coreutils)sum invocation. Print traditional checksum. +* sync: (coreutils)sync invocation. Synchronize memory and disk. +* tac: (coreutils)tac invocation. Reverse files. +* tail: (coreutils)tail invocation. Output the last part of files. +* tee: (coreutils)tee invocation. Redirect to multiple files. +* test: (coreutils)test invocation. File/string tests. +* touch: (coreutils)touch invocation. Change file timestamps. +* tr: (coreutils)tr invocation. Translate characters. +* true: (coreutils)true invocation. Do nothing, successfully. +* tsort: (coreutils)tsort invocation. Topological sort. +* tty: (coreutils)tty invocation. Print terminal name. +* uname: (coreutils)uname invocation. Print system information. +* unexpand: (coreutils)unexpand invocation. Convert spaces to tabs. +* uniq: (coreutils)uniq invocation. Uniquify files. +* unlink: (coreutils)unlink invocation. Removal via unlink(2). +* users: (coreutils)users invocation. Print current user names. +* vdir: (coreutils)vdir invocation. List directories verbosely. +* wc: (coreutils)wc invocation. Line, word, and byte counts. +* who: (coreutils)who invocation. Print who is logged in. +* whoami: (coreutils)whoami invocation. Print effective user ID. +* yes: (coreutils)yes invocation. Print a string indefinitely. +@end direntry + +@copying +This manual documents version @value{VERSION} of the @sc{gnu} core +utilities, including the standard programs for text and file manipulation. + +Copyright @copyright{} 1994, 1995, 1996, 2000, 2001, 2002, 2003, 2004, +2005, 2006 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled ``GNU +Free Documentation License''. +@end quotation +@end copying + +@titlepage +@title @sc{gnu} @code{Coreutils} +@subtitle Core GNU utilities +@subtitle for version @value{VERSION}, @value{UPDATED} +@author David MacKenzie et al. + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + + +@ifnottex +@node Top +@top GNU Coreutils + +@insertcopying +@end ifnottex + +@cindex core utilities +@cindex text utilities +@cindex shell utilities +@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 +* 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 +* Modified command invocation:: chroot env nice nohup su +* 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. +* Copying This Manual:: License for copying this manual. +* 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 +* 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 + +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. + +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. + +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. + +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. + +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. + +@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} + +Operating on fields within a line + +* 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. + +@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. + +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} + +@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 + +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 + +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 the referent of a symbolic link +* 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 + +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 + +Printing text + +* 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 + +@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 + +@command{expr}: Evaluate expression + +* String expressions:: + : match substr index length +* Numeric expressions:: + - * / % +* Relations for expr:: | & < <= = == != >= > +* Examples of expr:: Examples of using @command{expr} + +Redirection + +* tee invocation:: Redirect output to multiple files + +File name manipulation + +* basename invocation:: Strip directory and suffix from a file name +* dirname invocation:: Strip non-directory suffix from a file name +* pathchk invocation:: Check file name portability + +Working context + +* pwd invocation:: Print working directory +* stty invocation:: Print or change terminal characteristics +* printenv invocation:: Print all or some environment variables +* tty invocation:: Print file name of terminal on standard input + +@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 + +User information + +* id invocation:: Print user identity +* logname invocation:: Print current login name +* whoami invocation:: Print effective user ID +* groups invocation:: Print group names a user is in +* users invocation:: Print login names of users currently logged in +* who invocation:: Print who is currently logged in + +System context + +* date invocation:: Print or set system date and time +* uname invocation:: Print system information +* hostname invocation:: Print or set system name +* hostid invocation:: Print numeric host identifier. + +@command{date}: Print or set system date and time + +* Time conversion specifiers:: %[HIklMNpPrRsSTXzZ] +* 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. +* Examples of date:: Examples. + +Modified command invocation + +* chroot invocation:: Run a command with a different root directory +* env invocation:: Run a command in a modified environment +* nice invocation:: Run a command with modified niceness +* nohup invocation:: Run a command immune to hangups +* su invocation:: Run a command with substitute user and group ID + +Process control + +* kill invocation:: Sending a signal to processes. + +Delaying + +* sleep invocation:: Delay for a specified time + +Numeric operations + +* factor invocation:: Print prime factors +* seq invocation:: Print numeric sequences + +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. + +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. + +Opening the software toolbox + +* Toolbox introduction:: Toolbox introduction +* I/O redirection:: I/O redirection +* The who command:: The @command{who} command +* The cut command:: The @command{cut} command +* The sort command:: The @command{sort} command +* The uniq command:: The @command{uniq} command +* Putting the tools together:: Putting the tools together + +Copying This Manual + +* GNU Free Documentation License:: License for copying this manual. + +@end detailmenu +@end menu + + +@node Introduction +@chapter Introduction + +This manual is a work in progress: many sections make no attempt to explain +basic concepts in a way suitable for novices. Thus, if you are interested, +please get involved in improving this manual. The entire @sc{gnu} community +will benefit. + +@cindex @acronym{POSIX} +The @sc{gnu} utilities documented here are mostly compatible with the +@acronym{POSIX} standard. +@cindex bugs, reporting +Please report bugs to @email{bug-coreutils@@gnu.org}. Remember +to include the version number, machine architecture, input files, and +any other information needed to reproduce the bug: your input, what you +expected, what you got, and why it is wrong. Diffs are welcome, but +please include a description of the problem as well, since this is +sometimes difficult to infer. @xref{Bugs, , , gcc, Using and Porting GNU CC}. + +@cindex Berry, K. +@cindex Paterson, R. +@cindex Stallman, R. +@cindex Pinard, F. +@cindex MacKenzie, D. +@cindex Meyering, J. +@cindex Youmans, B. +This manual was originally derived from the Unix man pages in the +distributions, which were written by David MacKenzie and updated by Jim +Meyering. What you are reading now is the authoritative documentation +for these utilities; the man pages are no longer being maintained. The +original @command{fmt} man page was written by Ross Paterson. Fran@,{c}ois +Pinard did the initial conversion to Texinfo format. Karl Berry did the +indexing, some reorganization, and editing of the results. Brian +Youmans of the Free Software Foundation office staff combined the +manuals for textutils, fileutils, and sh-utils to produce the present +omnibus manual. Richard Stallman contributed his usual invaluable +insights to the overall process. + +@node Common options +@chapter Common options + +@macro optBackup +@item -b +@itemx @w{@kbd{--backup}[=@var{method}]} +@opindex -b +@opindex --backup +@vindex VERSION_CONTROL +@cindex backups, making +@xref{Backup options}. +Make a backup of each file that would otherwise be overwritten or removed. +@end macro + +@macro optBackupSuffix +@item -S @var{suffix} +@itemx --suffix=@var{suffix} +@opindex -S +@opindex --suffix +Append @var{suffix} to each backup file made with @option{-b}. +@xref{Backup options}. +@end macro + +@macro optTargetDirectory +@item -t @var{directory} +@itemx @w{@kbd{--target-directory}=@var{directory}} +@opindex -t +@opindex --target-directory +@cindex target directory +@cindex destination directory +Specify the destination @var{directory}. +@xref{Target directory}. +@end macro + +@macro optNoTargetDirectory +@item -T +@itemx --no-target-directory +@opindex -T +@opindex --no-target-directory +@cindex target directory +@cindex destination directory +Do not treat the last operand specially when it is a directory or a +symbolic link to a directory. @xref{Target directory}. +@end macro + +@macro optSi +@itemx --si +@opindex --si +@cindex SI output +Append an SI-style abbreviation to each size, such as @samp{M} for +megabytes. Powers of 1000 are used, not 1024; @samp{M} stands for +1,000,000 bytes. This option is equivalent to +@option{--block-size=si}. Use the @option{-h} or +@option{--human-readable} option if +you prefer powers of 1024. +@end macro + +@macro optHumanReadable +@item -h +@itemx --human-readable +@opindex -h +@opindex --human-readable +@cindex human-readable output +Append a size letter to each size, such as @samp{M} for mebibytes. +Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes. +Use the @option{--si} option if you prefer powers of 1000. +@end macro + +@macro optStripTrailingSlashes +@itemx @w{@kbd{--strip-trailing-slashes}} +@opindex --strip-trailing-slashes +@cindex stripping trailing slashes +Remove any trailing slashes from each @var{source} argument. +@xref{Trailing slashes}. +@end macro + +@cindex common options + +Certain options are available in all of these programs. Rather than +writing identical descriptions for each of the programs, they are +described here. (In fact, every @sc{gnu} program accepts (or should accept) +these options.) + +@vindex POSIXLY_CORRECT +Normally options and operands can appear in any order, and programs act +as if all the options appear before any operands. For example, +@samp{sort -r passwd -t :} acts like @samp{sort -r -t : passwd}, since +@samp{:} is an option-argument of @option{-t}. However, if the +@env{POSIXLY_CORRECT} environment variable is set, options must appear +before operands, unless otherwise specified for a particular command. + +A few programs can usefully have trailing operands with leading +@samp{-}. With such a program, options must precede operands even if +@env{POSIXLY_CORRECT} is not set, and this fact is noted in the +program description. For example, the @command{env} command's options +must appear before its operands, since in some cases the operands +specify a command that itself contains options. + +Some of these programs recognize the @option{--help} and @option{--version} +options only when one of them is the sole command line argument. + +@table @samp + +@item --help +@opindex --help +@cindex help, online +Print a usage message listing all available options, then exit successfully. + +@item --version +@opindex --version +@cindex version number, finding +Print the version number, then exit successfully. + +@item -- +@opindex -- +@cindex option delimiter +Delimit the option list. Later arguments, if any, are treated as +operands even if they begin with @samp{-}. For example, @samp{sort -- +-r} reads from the file named @file{-r}. + +@end table + +@cindex standard input +@cindex standard output +A single @samp{-} operand is not really an option, though it looks like one. It +stands for standard input, or for standard output if that is clear from +the context. For example, @samp{sort -} reads from standard input, +and is equivalent to plain @samp{sort}, and @samp{tee -} writes an +extra copy of its input to standard output. Unless otherwise +specified, @samp{-} can appear as any operand that requires a file +name. + +@menu +* Exit status:: Indicating program success or failure. +* Backup options:: -b -S, in some programs. +* Block size:: BLOCK_SIZE and --block-size, in some programs. +* Disambiguating names and IDs:: chgrp and chown owner and group syntax +* Random sources:: --random-source, in some programs. +* Target directory:: Specifying a target directory, 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{} +* Standards conformance:: Conformance to the @acronym{POSIX} standard. +@end menu + + +@node Exit status +@section Exit status + +@macro exitstatus +An exit status of zero indicates success, +and a nonzero value indicates failure. +@end macro + +Nearly every command invocation yields an integral @dfn{exit status} +that can be used to change how other commands work. +For the vast majority of commands, an exit status of zero indicates +success. Failure is indicated by a nonzero value---typically +@samp{1}, though it may differ on unusual platforms as @acronym{POSIX} +requires only that it be nonzero. + +However, some of the programs documented here do produce +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{su}, @command{test}, @command{tty}. + + +@node Backup options +@section Backup options + +@cindex backup options + +Some @sc{gnu} programs (at least @command{cp}, @command{install}, +@command{ln}, and @command{mv}) optionally make backups of files +before writing new versions. +These options control the details of these backups. The options are also +briefly mentioned in the descriptions of the particular programs. + +@table @samp + +@item -b +@itemx @w{@kbd{--backup}[=@var{method}]} +@opindex -b +@opindex --backup +@vindex VERSION_CONTROL +@cindex backups, making +Make a backup of each file that would otherwise be overwritten or removed. +Without this option, the original versions are destroyed. +Use @var{method} to determine the type of backups to make. +When this option is used but @var{method} is not specified, +then the value of the @env{VERSION_CONTROL} +environment variable is used. And if @env{VERSION_CONTROL} is not set, +the default backup type is @samp{existing}. + +Note that the short form of this option, @option{-b} does not accept any +argument. Using @option{-b} is equivalent to using @option{--backup=existing}. + +@vindex version-control @r{Emacs variable} +This option corresponds to the Emacs variable @samp{version-control}; +the values for @var{method} are the same as those used in Emacs. +This option also accepts more descriptive names. +The valid @var{method}s are (unique abbreviations are accepted): + +@table @samp +@item none +@itemx off +@opindex none @r{backup method} +Never make backups. + +@item numbered +@itemx t +@opindex numbered @r{backup method} +Always make numbered backups. + +@item existing +@itemx nil +@opindex existing @r{backup method} +Make numbered backups of files that already have them, simple backups +of the others. + +@item simple +@itemx never +@opindex simple @r{backup method} +Always make simple backups. Please note @samp{never} is not to be +confused with @samp{none}. + +@end table + +@item -S @var{suffix} +@itemx --suffix=@var{suffix} +@opindex -S +@opindex --suffix +@cindex backup suffix +@vindex SIMPLE_BACKUP_SUFFIX +Append @var{suffix} to each backup file made with @option{-b}. If this +option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX} +environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not +set, the default is @samp{~}, just as in Emacs. + +@end table + +@node Block size +@section Block size + +@cindex block size + +Some @sc{gnu} programs (at least @command{df}, @command{du}, and +@command{ls}) display sizes in ``blocks''. You can adjust the block size +and method of display to make sizes easier to read. The block size +used for display is independent of any file system block size. +Fractional block counts are rounded up to the nearest integer. + +@opindex --block-size=@var{size} +@vindex BLOCKSIZE +@vindex BLOCK_SIZE +@vindex DF_BLOCK_SIZE +@vindex DU_BLOCK_SIZE +@vindex LS_BLOCK_SIZE +@vindex POSIXLY_CORRECT@r{, and block size} + +The default block size is chosen by examining the following environment +variables in turn; the first one that is set determines the block size. + +@table @code + +@item DF_BLOCK_SIZE +This specifies the default block size for the @command{df} command. +Similarly, @env{DU_BLOCK_SIZE} specifies the default for @command{du} and +@env{LS_BLOCK_SIZE} for @command{ls}. + +@item BLOCK_SIZE +This specifies the default block size for all three commands, if the +above command-specific environment variables are not set. + +@item BLOCKSIZE +This specifies the default block size for all values that are normally +printed as blocks, if neither @env{BLOCK_SIZE} nor the above +command-specific environment variables are set. Unlike the other +environment variables, @env{BLOCKSIZE} does not affect values that are +normally printed as byte counts, e.g., the file sizes contained in +@code{ls -l} output. + +@item POSIXLY_CORRECT +If neither @env{@var{command}_BLOCK_SIZE}, nor @env{BLOCK_SIZE}, nor +@env{BLOCKSIZE} is set, but this variable is set, the block size +defaults to 512. + +@end table + +If none of the above environment variables are set, the block size +currently defaults to 1024 bytes in most contexts, but this number may +change in the future. For @command{ls} file sizes, the block size +defaults to 1 byte. + +@cindex human-readable output +@cindex SI output + +A block size specification can be a positive integer specifying the number +of bytes per block, or it can be @code{human-readable} or @code{si} to +select a human-readable format. Integers may be followed by suffixes +that are upward compatible with the +@uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI prefixes} +for decimal multiples and with the +@uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2 +prefixes for binary multiples}. + +With human-readable formats, output sizes are followed by a size letter +such as @samp{M} for megabytes. @code{BLOCK_SIZE=human-readable} uses +powers of 1024; @samp{M} stands for 1,048,576 bytes. +@code{BLOCK_SIZE=si} is similar, but uses powers of 1000 and appends +@samp{B}; @samp{MB} stands for 1,000,000 bytes. + +@vindex LC_NUMERIC +A block size specification preceded by @samp{'} causes output sizes to +be displayed with thousands separators. The @env{LC_NUMERIC} locale +specifies the thousands separator and grouping. For example, in an +American English locale, @samp{--block-size="'1kB"} would cause a size +of 1234000 bytes to be displayed as @samp{1,234}. In the default C +locale, there is no thousands separator so a leading @samp{'} has no +effect. + +An integer block size can be followed by a suffix to specify a +multiple of that size. A bare size letter, +or one followed by @samp{iB}, specifies +a multiple using powers of 1024. A size letter followed by @samp{B} +specifies powers of 1000 instead. For example, @samp{1M} and +@samp{1MiB} are equivalent to @samp{1048576}, whereas @samp{1MB} is +equivalent to @samp{1000000}. + +A plain suffix without a preceding integer acts as if @samp{1} were +prepended, except that it causes a size indication to be appended to +the output. For example, @samp{--block-size="kB"} displays 3000 as +@samp{3kB}. + +The following suffixes are defined. Large sizes like @code{1Y} +may be rejected by your computer due to limitations of its arithmetic. + +@table @samp +@item kB +@cindex kilobyte, definition of +kilobyte: @math{10^3 = 1000}. +@item k +@itemx K +@itemx KiB +@cindex kibibyte, definition of +kibibyte: @math{2^10 = 1024}. @samp{K} is special: the SI prefix is +@samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and +@acronym{POSIX} use @samp{k} to mean @samp{KiB}. +@item MB +@cindex megabyte, definition of +megabyte: @math{10^6 = 1,000,000}. +@item M +@itemx MiB +@cindex mebibyte, definition of +mebibyte: @math{2^20 = 1,048,576}. +@item GB +@cindex gigabyte, definition of +gigabyte: @math{10^9 = 1,000,000,000}. +@item G +@itemx GiB +@cindex gibibyte, definition of +gibibyte: @math{2^30 = 1,073,741,824}. +@item TB +@cindex terabyte, definition of +terabyte: @math{10^12 = 1,000,000,000,000}. +@item T +@itemx TiB +@cindex tebibyte, definition of +tebibyte: @math{2^40 = 1,099,511,627,776}. +@item PB +@cindex petabyte, definition of +petabyte: @math{10^15 = 1,000,000,000,000,000}. +@item P +@itemx PiB +@cindex pebibyte, definition of +pebibyte: @math{2^50 = 1,125,899,906,842,624}. +@item EB +@cindex exabyte, definition of +exabyte: @math{10^18 = 1,000,000,000,000,000,000}. +@item E +@itemx EiB +@cindex exbibyte, definition of +exbibyte: @math{2^60 = 1,152,921,504,606,846,976}. +@item ZB +@cindex zettabyte, definition of +zettabyte: @math{10^21 = 1,000,000,000,000,000,000,000} +@item Z +@itemx ZiB +@math{2^70 = 1,180,591,620,717,411,303,424}. +(@samp{Zi} is a @acronym{GNU} extension to IEC 60027-2.) +@item YB +@cindex yottabyte, definition of +yottabyte: @math{10^24 = 1,000,000,000,000,000,000,000,000}. +@item Y +@itemx YiB +@math{2^80 = 1,208,925,819,614,629,174,706,176}. +(@samp{Yi} is a @acronym{GNU} extension to IEC 60027-2.) +@end table + +@opindex -k +@opindex -h +@opindex --block-size +@opindex --human-readable +@opindex --si + +Block size defaults can be overridden by an explicit +@option{--block-size=@var{size}} option. The @option{-k} +option is equivalent to @option{--block-size=1K}, which +is the default unless the @env{POSIXLY_CORRECT} environment variable is +set. The @option{-h} or @option{--human-readable} option is equivalent to +@option{--block-size=human-readable}. The @option{--si} option is +equivalent to @option{--block-size=si}. + +@node Disambiguating names and IDs +@section chown and chgrp: Disambiguating user names and IDs +@cindex user names, disambiguating +@cindex user IDs, disambiguating +@cindex group names, disambiguating +@cindex group IDs, disambiguating +@cindex disambiguating group names and IDs + +Since the @var{owner} and @var{group} arguments to @command{chown} and +@command{chgrp} may be specified as names or numeric IDs, there is an +apparent ambiguity. +What if a user or group @emph{name} is a string of digits? +@footnote{Using a number as a user name is common in some environments.} +Should the command interpret it as a user name or as an ID? +@acronym{POSIX} requires that @command{chown} and @command{chgrp} +first attempt to resolve the specified string as a name, and +only once that fails, then try to interpret it as an ID. +This is troublesome when you want to specify a numeric ID, say 42, +and it must work even in a pathological situation where +@samp{42} is a user name that maps to some other user ID, say 1000. +Simply invoking @code{chown 42 F}, will set @file{F}s owner ID to +1000---not what you intended. + +GNU @command{chown} and @command{chgrp} provide a way to work around this, +that at the same time may result in a significant performance improvement +by eliminating a database look-up. +Simply precede each numeric user ID and/or group ID with a @samp{+}, +in order to force its interpretation as an integer: + +@example +chown +42 F +chgrp +$numeric_group_id another-file +chown +0:+0 / +@end example + +GNU @command{chown} and @command{chgrp} +skip the name look-up process for each @samp{+}-prefixed string, +because a string containing @samp{+} is never a valid user or group name. +This syntax is accepted on most common Unix systems, but not on Solaris 10. + +@node Random sources +@section Sources of random data + +@cindex random sources + +The @command{shuf}, @command{shred}, and @command{sort} commands +sometimes need random data to do their work. For example, @samp{sort +-R} must choose a hash function at random, and it needs random data to +make this selection. + +Normally these commands use the device file @file{/dev/urandom} as the +source of random data. Typically, this device gathers environmental +noise from device drivers and other sources into an entropy pool, and +uses the pool to generate random bits. If the pool is short of data, +the device reuses the internal pool to produce more bits, using a +cryptographically secure pseudorandom number generator. + +@file{/dev/urandom} suffices for most practical uses, but applications +requiring high-value or long-term protection of private data may +require an alternate data source like @file{/dev/random} or +@file{/dev/arandom}. The set of available sources depends on your +operating system. + +To use such a source, specify the @option{--random-source=@var{file}} +option, e.g., @samp{shuf --random-source=/dev/random}. The contents +of @var{file} should be as random as possible. An error is reported +if @var{file} does not contain enough bytes to randomize the input +adequately. + +To reproduce the results of an earlier invocation of a command, you +can save some random data into a file and then use that file as the +random source in earlier and later invocations of the command. + +Some old-fashioned or stripped-down operating systems lack support for +@command{/dev/urandom}. On these systems commands like @command{shuf} +by default fall back on an internal pseudorandom generator initialized +by a small amount of entropy. + +@node Target directory +@section Target directory + +@cindex target directory + +The @command{cp}, @command{install}, @command{ln}, and @command{mv} +commands normally treat the last operand specially when it is a +directory or a symbolic link to a directory. For example, @samp{cp +source dest} is equivalent to @samp{cp source dest/source} if +@file{dest} is a directory. Sometimes this behavior is not exactly +what is wanted, so these commands support the following options to +allow more fine-grained control: + +@table @samp + +@item -T +@itemx --no-target-directory +@opindex --no-target-directory +@cindex target directory +@cindex destination directory +Do not treat the last operand specially when it is a directory or a +symbolic link to a directory. This can help avoid race conditions in +programs that operate in a shared area. For example, when the command +@samp{mv /tmp/source /tmp/dest} succeeds, there is no guarantee that +@file{/tmp/source} was renamed to @file{/tmp/dest}: it could have been +renamed to @file{/tmp/dest/source} instead, if some other process +created @file{/tmp/dest} as a directory. However, if @file{mv +-T /tmp/source /tmp/dest} succeeds, there is no +question that @file{/tmp/source} was renamed to @file{/tmp/dest}. + +In the opposite situation, where you want the last operand to be +treated as a directory and want a diagnostic otherwise, you can use +the @option{--target-directory} (@option{-t}) option. + +@item -t @var{directory} +@itemx @w{@kbd{--target-directory}=@var{directory}} +@opindex --target-directory +@cindex target directory +@cindex destination directory +Use @var{directory} as the directory component of each destination +file name. + +The interface for most programs is that after processing options and a +finite (possibly zero) number of fixed-position arguments, the remaining +argument list is either expected to be empty, or is a list of items +(usually files) that will all be handled identically. The @command{xargs} +program is designed to work well with this convention. + +The commands in the @command{mv}-family are unusual in that they take +a variable number of arguments with a special case at the @emph{end} +(namely, the target directory). This makes it nontrivial to perform some +operations, e.g., ``move all files from here to ../d/'', because +@code{mv * ../d/} might exhaust the argument space, and @code{ls | xargs ...} +doesn't have a clean way to specify an extra final argument for each +invocation of the subject command. (It can be done by going through a +shell command, but that requires more human labor and brain power than +it should.) + +The @w{@kbd{--target-directory}} (@option{-t}) option allows the @command{cp}, +@command{install}, @command{ln}, and @command{mv} programs to be used +conveniently with @command{xargs}. For example, you can move the files +from the current directory to a sibling directory, @code{d} like this: + +@smallexample +ls | xargs mv -t ../d -- +@end smallexample + +However, this doesn't move files whose names begin with @samp{.}. +If you use the @sc{gnu} @command{find} program, you can move those +files too, with this command: + +@example +find . -mindepth 1 -maxdepth 1 \ + | xargs mv -t ../d +@end example + +But both of the above approaches fail if there are no files in the +current directory, or if any file has a name containing a blank or +some other special characters. +The following example removes those limitations and requires both +@sc{gnu} @command{find} and @sc{gnu} @command{xargs}: + +@example +find . -mindepth 1 -maxdepth 1 -print0 \ + | xargs --null --no-run-if-empty \ + mv -t ../d +@end example + +@end table + +@noindent +The @option{--target-directory} (@option{-t}) and +@option{--no-target-directory} (@option{-T}) +options cannot be combined. + +@node Trailing slashes +@section Trailing slashes + +@cindex trailing slashes + +Some @sc{gnu} programs (at least @command{cp} and @command{mv}) allow you to +remove any trailing slashes from each @var{source} argument before +operating on it. The @w{@kbd{--strip-trailing-slashes}} option enables +this behavior. + +This is useful when a @var{source} argument may have a trailing slash and +@c FIXME: mv's behavior in this case is system-dependent +specify a symbolic link to a directory. This scenario is in fact rather +common because some shells can automatically append a trailing slash when +performing file name completion on such symbolic links. Without this +option, @command{mv}, for example, (via the system's rename function) must +interpret a trailing slash as a request to dereference the symbolic link +and so must rename the indirectly referenced @emph{directory} and not +the symbolic link. Although it may seem surprising that such behavior +be the default, it is required by @acronym{POSIX} and is consistent with +other parts of that standard. + +@node Traversing symlinks +@section Traversing symlinks + +@cindex symbolic link to directory, controlling traversal of + +The following options modify how @command{chown} and @command{chgrp} +@c FIXME: note that `du' has these options, too, but they have slightly +@c different meaning. +traverse a hierarchy when the @option{--recursive} (@option{-R}) +option is also specified. +If more than one of the following options is specified, only the final +one takes effect. +These options specify whether processing a symbolic link to a directory +entails operating on just the symbolic link or on all files in the +hierarchy rooted at that directory. + +These options are independent of @option{--dereference} and +@option{--no-dereference} (@option{-h}), which control whether to modify +a symlink or its referent. + +@table @samp + +@macro choptH +@item -H +@opindex -H +@cindex symbolic link to directory, traverse each that is specified 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 +@choptH + +@macro choptL +@item -L +@opindex -L +@cindex symbolic link to directory, traverse each that is encountered +In a recursive traversal, traverse every symbolic link to a directory +that is encountered. +@end macro +@choptL + +@macro choptP +@item -P +@opindex -P +@cindex symbolic link to directory, never traverse +Do not traverse any symbolic links. +This is the default if none of @option{-H}, @option{-L}, +or @option{-P} is specified. +@end macro +@choptP + +@end table + + +@node Treating / specially +@section Treating / specially + +Certain commands can operate destructively on entire hierarchies. +For example, if a user with appropriate privileges mistakenly runs +@samp{rm -rf / tmp/junk}, that may remove +all files on the entire system. Since there are so few +legitimate uses for such a command, +@sc{gnu} @command{rm} normally declines to operate on any directory +that resolves to @file{/}. If you really want to try to remove all +the files on your system, you can use the @option{--no-preserve-root} +option, but the default behavior, specified by the +@option{--preserve-option}, is safer for most purposes. + +The commands @command{chgrp}, @command{chmod} and @command{chown} +can also operate destructively on entire hierarchies, so they too +support these options. Although, unlike @command{rm}, they don't +actually unlink files, these commands are arguably more dangerous +when operating recursively on @file{/}, since they often work much +more quickly, and hence damage more files before an alert user can +interrupt them. Tradition and @acronym{POSIX} require these commands +to operate recursively on @file{/}, so they default to +@option{--no-preserve-root}, but using the @option{--preserve-root} +option makes them safer for most purposes. For convenience you can +specify @option{--preserve-root} in an alias or in a shell function. + +Note that the @option{--preserve-root} option also ensures +that @command{chgrp} and @command{chown} do not modify @file{/} +even when dereferencing a symlink pointing to @file{/}. + +@node Special built-in utilities +@section Special built-in utilities + +Some programs like @command{nice} can invoke other programs; for +example, the command @samp{nice cat file} invokes the program +@command{cat} by executing the command @samp{cat file}. However, +@dfn{special built-in utilities} like @command{exit} cannot be invoked +this way. For example, the command @samp{nice exit} does not have a +well-defined behavior: it may generate an error message instead of +exiting. + +Here is a list of the special built-in utilities that are standardized +by @acronym{POSIX} 1003.1-2004. + +@quotation +@t{.@: : break continue eval exec exit export readonly +return set shift times trap unset} +@end quotation + +For example, because @samp{.}, @samp{:}, and @samp{exec} are special, +the commands @samp{nice . foo.sh}, @samp{nice :}, and @samp{nice exec +pwd} do not work as you might expect. + +Many shells extend this list. For example, Bash has several extra +special built-in utilities like @command{history}, and +@command{suspend}, and with Bash the command @samp{nice suspend} +generates an error message instead of suspending. + +@node Standards conformance +@section Standards conformance + +@vindex POSIXLY_CORRECT +In a few cases, the @sc{gnu} utilities' default behavior is +incompatible with the @acronym{POSIX} standard. To suppress these +incompatibilities, define the @env{POSIXLY_CORRECT} environment +variable. Unless you are checking for @acronym{POSIX} conformance, you +probably do not need to define @env{POSIXLY_CORRECT}. + +Newer versions of @acronym{POSIX} are occasionally incompatible with older +versions. For example, older versions of @acronym{POSIX} required the +command @samp{sort +1} to sort based on the second and succeeding +fields in each input line, but starting with @acronym{POSIX} 1003.1-2001 +the same command is required to sort the file named @file{+1}, and you +must instead use the command @samp{sort -k 2} to get the field-based +sort. + +@vindex _POSIX2_VERSION +The @sc{gnu} utilities normally conform to the version of @acronym{POSIX} +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 +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 +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. + +@node Output of entire files +@chapter Output of entire files + +@cindex output of entire files +@cindex entire files, output of + +These commands read and write entire files, possibly transforming them +in some way. + +@menu +* 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. +@end menu + +@node cat invocation +@section @command{cat}: Concatenate and write files + +@pindex cat +@cindex concatenate and write files +@cindex copying files + +@command{cat} copies each @var{file} (@samp{-} means standard input), or +standard input if none are given, to standard output. Synopsis: + +@example +cat [@var{option}] [@var{file}]@dots{} +@end example + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -A +@itemx --show-all +@opindex -A +@opindex --show-all +Equivalent to @option{-vET}. + +@item -b +@itemx --number-nonblank +@opindex -b +@opindex --number-nonblank +Number all nonblank output lines, starting with 1. + +@item -e +@opindex -e +Equivalent to @option{-vE}. + +@item -E +@itemx --show-ends +@opindex -E +@opindex --show-ends +Display a @samp{$} after the end of each line. + +@item -n +@itemx --number +@opindex -n +@opindex --number +Number all output lines, starting with 1. + +@item -s +@itemx --squeeze-blank +@opindex -s +@opindex --squeeze-blank +@cindex squeezing blank lines +Replace multiple adjacent blank lines with a single blank line. + +@item -t +@opindex -t +Equivalent to @option{-vT}. + +@item -T +@itemx --show-tabs +@opindex -T +@opindex --show-tabs +Display TAB characters as @samp{^I}. + +@item -u +@opindex -u +Ignored; for @acronym{POSIX} compatibility. + +@item -v +@itemx --show-nonprinting +@opindex -v +@opindex --show-nonprinting +Display control characters except for LFD and TAB using +@samp{^} notation and precede characters that have the high bit set with +@samp{M-}. + +@end table + +On systems like MS-DOS that distinguish between text and binary files, +@command{cat} normally reads and writes in binary mode. However, +@command{cat} reads in text mode if one of the options +@option{-bensAE} is used or if @command{cat} is reading from standard +input and standard input is a terminal. Similarly, @command{cat} +writes in text mode if one of the options @option{-bensAE} is used or +if standard output is a terminal. + +@exitstatus + +Examples: + +@smallexample +# Output f's contents, then standard input, then g's contents. +cat f - g + +# Copy standard input to standard output. +cat +@end smallexample + + +@node tac invocation +@section @command{tac}: Concatenate and write files in reverse + +@pindex tac +@cindex reversing files + +@command{tac} copies each @var{file} (@samp{-} means standard input), or +standard input if none are given, to standard output, reversing the +records (lines by default) in each separately. Synopsis: + +@example +tac [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +@dfn{Records} are separated by instances of a string (newline by +default). By default, this separator string is attached to the end of +the record that it follows in the file. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -b +@itemx --before +@opindex -b +@opindex --before +The separator is attached to the beginning of the record that it +precedes in the file. + +@item -r +@itemx --regex +@opindex -r +@opindex --regex +Treat the separator string as a regular expression. Users of @command{tac} +on MS-DOS/MS-Windows should note that, since @command{tac} reads files in +binary mode, each line of a text file might end with a CR/LF pair +instead of the Unix-style LF. + +@item -s @var{separator} +@itemx --separator=@var{separator} +@opindex -s +@opindex --separator +Use @var{separator} as the record separator, instead of newline. + +@end table + +@exitstatus + + +@node nl invocation +@section @command{nl}: Number lines and write files + +@pindex nl +@cindex numbering lines +@cindex line numbering + +@command{nl} writes each @var{file} (@samp{-} means standard input), or +standard input if none are given, to standard output, with line numbers +added to some or all of the lines. Synopsis: + +@example +nl [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +@cindex logical pages, numbering on +@command{nl} decomposes its input into (logical) pages; by default, the +line number is reset to 1 at the top of each logical page. @command{nl} +treats all of the input files as a single document; it does not reset +line numbers or logical pages between files. + +@cindex headers, numbering +@cindex body, numbering +@cindex footers, numbering +A logical page consists of three sections: header, body, and footer. +Any of the sections can be empty. Each can be numbered in a different +style from the others. + +The beginnings of the sections of logical pages are indicated in the +input file by a line containing exactly one of these delimiter strings: + +@table @samp +@item \:\:\: +start of header; +@item \:\: +start of body; +@item \: +start of footer. +@end table + +The two characters from which these strings are made can be changed from +@samp{\} and @samp{:} via options (see below), but the pattern and +length of each string cannot be changed. + +A section delimiter is replaced by an empty line on output. Any text +that comes before the first section delimiter string in the input file +is considered to be part of a body section, so @command{nl} treats a +file that contains no section delimiters as a single body section. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -b @var{style} +@itemx --body-numbering=@var{style} +@opindex -b +@opindex --body-numbering +Select the numbering style for lines in the body section of each +logical page. When a line is not numbered, the current line number +is not incremented, but the line number separator character is still +prepended to the line. The styles are: + +@table @samp +@item a +number all lines, +@item t +number only nonempty lines (default for body), +@item n +do not number lines (default for header and footer), +@item p@var{bre} +number only lines that contain a match for the basic regular +expression @var{bre}. +@xref{Regular Expressions, , Regular Expressions, grep, The GNU Grep Manual}. +@end table + +@item -d @var{cd} +@itemx --section-delimiter=@var{cd} +@opindex -d +@opindex --section-delimiter +@cindex section delimiters of pages +Set the section delimiter characters to @var{cd}; default is +@samp{\:}. If only @var{c} is given, the second remains @samp{:}. +(Remember to protect @samp{\} or other metacharacters from shell +expansion with quotes or extra backslashes.) + +@item -f @var{style} +@itemx --footer-numbering=@var{style} +@opindex -f +@opindex --footer-numbering +Analogous to @option{--body-numbering}. + +@item -h @var{style} +@itemx --header-numbering=@var{style} +@opindex -h +@opindex --header-numbering +Analogous to @option{--body-numbering}. + +@item -i @var{number} +@itemx --page-increment=@var{number} +@opindex -i +@opindex --page-increment +Increment line numbers by @var{number} (default 1). + +@item -l @var{number} +@itemx --join-blank-lines=@var{number} +@opindex -l +@opindex --join-blank-lines +@cindex empty lines, numbering +@cindex blank lines, numbering +Consider @var{number} (default 1) consecutive empty lines to be one +logical line for numbering, and only number the last one. Where fewer +than @var{number} consecutive empty lines occur, do not number them. +An empty line is one that contains no characters, not even spaces +or tabs. + +@item -n @var{format} +@itemx --number-format=@var{format} +@opindex -n +@opindex --number-format +Select the line numbering format (default is @code{rn}): + +@table @samp +@item ln +@opindex ln @r{format for @command{nl}} +left justified, no leading zeros; +@item rn +@opindex rn @r{format for @command{nl}} +right justified, no leading zeros; +@item rz +@opindex rz @r{format for @command{nl}} +right justified, leading zeros. +@end table + +@item -p +@itemx --no-renumber +@opindex -p +@opindex --no-renumber +Do not reset the line number at the start of a logical page. + +@item -s @var{string} +@itemx --number-separator=@var{string} +@opindex -s +@opindex --number-separator +Separate the line number from the text line in the output with +@var{string} (default is the TAB character). + +@item -v @var{number} +@itemx --starting-line-number=@var{number} +@opindex -v +@opindex --starting-line-number +Set the initial line number on each logical page to @var{number} (default 1). + +@item -w @var{number} +@itemx --number-width=@var{number} +@opindex -w +@opindex --number-width +Use @var{number} characters for line numbers (default 6). + +@end table + +@exitstatus + + +@node od invocation +@section @command{od}: Write files in octal or other formats + +@pindex od +@cindex octal dump of files +@cindex hex dump of files +@cindex ASCII dump of files +@cindex file contents, dumping unambiguously + +@command{od} writes an unambiguous representation of each @var{file} +(@samp{-} means standard input), or standard input if none are given. +Synopses: + +@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]]] +@end smallexample + +Each line of output consists of the offset in the input, followed by +groups of data from the file. By default, @command{od} prints the offset in +octal, and each group of file data is a C @code{short int}'s worth of input +printed as a single octal number. + +If @var{offset} is given, it specifies how many input bytes to skip +before formatting and writing. By default, it is interpreted as an +octal number, but the optional trailing decimal point causes it to be +interpreted as decimal. If no decimal is specified and the offset +begins with @samp{0x} or @samp{0X} it is interpreted as a hexadecimal +number. If there is a trailing @samp{b}, the number of bytes skipped +will be @var{offset} multiplied by 512. + +If a command is of both the first and second forms, the second form is +assumed if the last operand begins with @samp{+} or (if there are two +operands) a digit. For example, in @samp{od foo 10} and @samp{od +10} +the @samp{10} is an offset, whereas in @samp{od 10} the @samp{10} is a +file name. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -A @var{radix} +@itemx --address-radix=@var{radix} +@opindex -A +@opindex --address-radix +@cindex radix for file offsets +@cindex file offset radix +Select the base in which file offsets are printed. @var{radix} can +be one of the following: + +@table @samp +@item d +decimal; +@item o +octal; +@item x +hexadecimal; +@item n +none (do not print offsets). +@end table + +The default is octal. + +@item -j @var{bytes} +@itemx --skip-bytes=@var{bytes} +@opindex -j +@opindex --skip-bytes +Skip @var{bytes} input bytes before formatting and writing. If +@var{bytes} begins with @samp{0x} or @samp{0X}, it is interpreted in +hexadecimal; otherwise, if it begins with @samp{0}, in octal; otherwise, +in decimal. Appending @samp{b} multiplies @var{bytes} by 512, @samp{k} +by 1024, and @samp{m} by 1048576. + +@item -N @var{bytes} +@itemx --read-bytes=@var{bytes} +@opindex -N +@opindex --read-bytes +Output at most @var{bytes} bytes of the input. Prefixes and suffixes on +@code{bytes} are interpreted as for the @option{-j} option. + +@item -S @var{n} +@itemx --strings[=@var{n}] +@opindex -S +@opindex --strings +@cindex string constants, outputting +Instead of the normal output, output only @dfn{string constants}: at +least @var{n} consecutive @acronym{ASCII} graphic characters, +followed by a null (zero) byte. + +If @var{n} is omitted with @option{--strings}, the default is 3. + +@item -t @var{type} +@itemx --format=@var{type} +@opindex -t +@opindex --format +Select the format in which to output the file data. @var{type} is a +string of one or more of the below type indicator characters. If you +include more than one type indicator character in a single @var{type} +string, or use this option more than once, @command{od} writes one copy +of each output line using each of the data types that you specified, +in the order that you specified. + +Adding a trailing ``z'' to any type specification appends a display +of the @acronym{ASCII} character representation of the printable characters +to the output line generated by the type specification. + +@table @samp +@item a +named character, ignoring high-order bit +@item c +@acronym{ASCII} character or backslash escape, +@item d +signed decimal +@item f +floating point +@item o +octal +@item u +unsigned decimal +@item x +hexadecimal +@end table + +The type @code{a} outputs things like @samp{sp} for space, @samp{nl} for +newline, and @samp{nul} for a null (zero) byte. Only the least significant +seven bits of each byte is used; the high-order bit is ignored. +Type @code{c} outputs +@samp{ }, @samp{\n}, and @code{\0}, respectively. + +@cindex type size +Except for types @samp{a} and @samp{c}, you can specify the number +of bytes to use in interpreting each number in the given data type +by following the type indicator character with a decimal integer. +Alternately, you can specify the size of one of the C compiler's +built-in data types by following the type indicator character with +one of the following characters. For integers (@samp{d}, @samp{o}, +@samp{u}, @samp{x}): + +@table @samp +@item C +char +@item S +short +@item I +int +@item L +long +@end table + +For floating point (@code{f}): + +@table @asis +@item F +float +@item D +double +@item L +long double +@end table + +@item -v +@itemx --output-duplicates +@opindex -v +@opindex --output-duplicates +Output consecutive lines that are identical. By default, when two or +more consecutive output lines would be identical, @command{od} outputs only +the first line, and puts just an asterisk on the following line to +indicate the elision. + +@item -w[@var{n}] +@itemx --width[=@var{n}] +@opindex -w +@opindex --width +Dump @code{n} input bytes per output line. This must be a multiple of +the least common multiple of the sizes associated with the specified +output types. + +If this option is not given at all, the default is 16. If @var{n} is +omitted, the default is 32. + +@end table + +The next several options are shorthands for format specifications. +@sc{gnu} @command{od} accepts any combination of shorthands and format +specification options. These options accumulate. + +@table @samp + +@item -a +@opindex -a +Output as named characters. Equivalent to @samp{-t a}. + +@item -b +@opindex -b +Output as octal bytes. Equivalent to @samp{-t o1}. + +@item -c +@opindex -c +Output as @acronym{ASCII} characters or backslash escapes. Equivalent to +@samp{-t c}. + +@item -d +@opindex -d +Output as unsigned decimal two-byte units. Equivalent to @samp{-t u2}. + +@item -f +@opindex -f +Output as floats. Equivalent to @samp{-t fF}. + +@item -i +@opindex -i +Output as decimal ints. Equivalent to @samp{-t dI}. + +@item -l +@opindex -l +Output as decimal long ints. Equivalent to @samp{-t dL}. + +@item -o +@opindex -o +Output as octal two-byte units. Equivalent to @option{-t o2}. + +@item -s +@opindex -s +Output as decimal two-byte units. Equivalent to @option{-t d2}. + +@item -x +@opindex -x +Output as hexadecimal two-byte units. Equivalent to @samp{-t x2}. + +@item --traditional +@opindex --traditional +Recognize the non-option label argument that traditional @command{od} +accepted. The following syntax: + +@smallexample +od --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]] +@end smallexample + +@noindent +can be used to specify at most one file and optional arguments +specifying an offset and a pseudo-start address, @var{label}. +The @var{label} argument is interpreted +just like @var{offset}, but it specifies an initial pseudo-address. The +pseudo-addresses are displayed in parentheses following any normal +address. + +@end table + +@exitstatus + +@node base64 invocation +@section @command{base64}: Transform data into printable data. + +@pindex base64 +@cindex base64 encoding + +@command{base64} transforms data read from a file, or standard input, +into (or from) base64 encoded form. The base64 encoded form uses +printable @acronym{ASCII} characters to represent binary data, see +@uref{ftp://ftp.rfc-editor.org/in-notes/rfc3548.txt, RFC 3548}. +Synopses: + +@smallexample +base64 [@var{option}]@dots{} [@var{file}] +base64 --decode [@var{option}]@dots{} [@var{file}] +@end smallexample + +The base64 encoding expands data to roughly 133% of the original. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -w @var{COLS} +@itemx --wrap=@var{COLS} +@opindex -w +@opindex --wrap +@cindex wrap data +@cindex column to wrap data after +During encoding, wrap lines after @var{COLS} characters. This must be +a positive number. + +The default is to wrap after 76 characters. Use the value 0 to +disable line wrapping altogether. + +@item -d +@itemx --decode +@opindex -d +@opindex --decode +@cindex Decode base64 data +@cindex Base64 decoding +Change the mode of operation, from the default of encoding data, to +decoding data. Input is expected to be base64 encoded data, and the +output will be the original data. + +@item -i +@itemx --ignore-garbage +@opindex -i +@opindex --ignore-garbage +@cindex Ignore garbage in base64 stream +When decoding, newlines are always accepted. +During decoding, ignore unrecognized bytes, +to permit distorted data to be decoded. + +@end table + +@exitstatus + + +@node Formatting file contents +@chapter Formatting file contents + +@cindex formatting file contents + +These commands reformat the contents of files. + +@menu +* fmt invocation:: Reformat paragraph text. +* pr invocation:: Paginate or columnate files for printing. +* fold invocation:: Wrap input lines to fit in specified width. +@end menu + + +@node fmt invocation +@section @command{fmt}: Reformat paragraph text + +@pindex fmt +@cindex reformatting paragraph text +@cindex paragraphs, reformatting +@cindex text, reformatting + +@command{fmt} fills and joins lines to produce output lines of (at most) +a given number of characters (75 by default). Synopsis: + +@example +fmt [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +@command{fmt} reads from the specified @var{file} arguments (or standard +input if none are given), and writes to standard output. + +By default, blank lines, spaces between words, and indentation are +preserved in the output; successive input lines with different +indentation are not joined; tabs are expanded on input and introduced on +output. + +@cindex line-breaking +@cindex sentences and line-breaking +@cindex Knuth, Donald E. +@cindex Plass, Michael F. +@command{fmt} prefers breaking lines at the end of a sentence, and tries to +avoid line breaks after the first word of a sentence or before the last +word of a sentence. A @dfn{sentence break} is defined as either the end +of a paragraph or a word ending in any of @samp{.?!}, followed by two +spaces or end of line, ignoring any intervening parentheses or quotes. +Like @TeX{}, @command{fmt} reads entire ``paragraphs'' before choosing line +breaks; the algorithm is a variant of that given by Donald E. Knuth +and Michael F. Plass in ``Breaking Paragraphs Into Lines'', +@cite{Software---Practice & Experience} @b{11}, 11 (November 1981), +1119--1184. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -c +@itemx --crown-margin +@opindex -c +@opindex --crown-margin +@cindex crown margin +@dfn{Crown margin} mode: preserve the indentation of the first two +lines within a paragraph, and align the left margin of each subsequent +line with that of the second line. + +@item -t +@itemx --tagged-paragraph +@opindex -t +@opindex --tagged-paragraph +@cindex tagged paragraphs +@dfn{Tagged paragraph} mode: like crown margin mode, except that if +indentation of the first line of a paragraph is the same as the +indentation of the second, the first line is treated as a one-line +paragraph. + +@item -s +@itemx --split-only +@opindex -s +@opindex --split-only +Split lines only. Do not join short lines to form longer ones. This +prevents sample lines of code, and other such ``formatted'' text from +being unduly combined. + +@item -u +@itemx --uniform-spacing +@opindex -u +@opindex --uniform-spacing +Uniform spacing. Reduce spacing between words to one space, and spacing +between sentences to two spaces. + +@item -@var{width} +@itemx -w @var{width} +@itemx --width=@var{width} +@opindex -@var{width} +@opindex -w +@opindex --width +Fill output lines up to @var{width} characters (default 75). @command{fmt} +initially tries to make lines about 7% shorter than this, to give it +room to balance line lengths. + +@item -p @var{prefix} +@itemx --prefix=@var{prefix} +Only lines beginning with @var{prefix} (possibly preceded by whitespace) +are subject to formatting. The prefix and any preceding whitespace are +stripped for the formatting and then re-attached to each formatted output +line. One use is to format certain kinds of program comments, while +leaving the code unchanged. + +@end table + +@exitstatus + + +@node pr invocation +@section @command{pr}: Paginate or columnate files for printing + +@pindex pr +@cindex printing, preparing files for +@cindex multicolumn output, generating +@cindex merging files in parallel + +@command{pr} writes each @var{file} (@samp{-} means standard input), or +standard input if none are given, to standard output, paginating and +optionally outputting in multicolumn format; optionally merges all +@var{file}s, printing all in parallel, one per column. Synopsis: + +@example +pr [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +@vindex LC_MESSAGES +By default, a 5-line header is printed at each page: two blank lines; +a line with the date, the file name, and the page count; and two more +blank lines. A footer of five blank lines is also printed. +With the @option{-F} +option, a 3-line header is printed: the leading two blank lines are +omitted; no footer is used. The default @var{page_length} in both cases is 66 +lines. The default number of text lines changes from 56 (without @option{-F}) +to 63 (with @option{-F}). The text line of the header takes the form +@samp{@var{date} @var{string} @var{page}}, with spaces inserted around +@var{string} so that the line takes up the full @var{page_width}. Here, +@var{date} is the date (see the @option{-D} or @option{--date-format} +option for details), @var{string} is the centered header string, and +@var{page} identifies the page number. The @env{LC_MESSAGES} locale +category affects the spelling of @var{page}; in the default C locale, it +is @samp{Page @var{number}} where @var{number} is the decimal page +number. + +Form feeds in the input cause page breaks in the output. Multiple form +feeds produce empty pages. + +Columns are of equal width, separated by an optional string (default +is @samp{space}). For multicolumn output, lines will always be truncated to +@var{page_width} (default 72), unless you use the @option{-J} option. +For single +column output no line truncation occurs by default. Use @option{-W} option to +truncate lines in that case. + +The following changes were made in version 1.22i and apply to later +versions of @command{pr}: +@c FIXME: this whole section here sounds very awkward to me. I +@c made a few small changes, but really it all needs to be redone. - Brian +@c OK, I fixed another sentence or two, but some of it I just don't understand. +@ - Brian +@itemize @bullet + +@item +Some small @var{letter options} (@option{-s}, @option{-w}) have been +redefined for better @acronym{POSIX} compliance. The output of some further +cases has been adapted to other Unix systems. These changes are not +compatible with earlier versions of the program. + +@item +Some @var{new capital letter} options (@option{-J}, @option{-S}, @option{-W}) +have been introduced to turn off unexpected interferences of small letter +options. The @option{-N} option and the second argument @var{last_page} +of @samp{+FIRST_PAGE} offer more flexibility. The detailed handling of +form feeds set in the input files requires the @option{-T} option. + +@item +Capital letter options override small letter ones. + +@item +Some of the option-arguments (compare @option{-s}, @option{-e}, +@option{-i}, @option{-n}) cannot be specified as separate arguments from the +preceding option letter (already stated in the @acronym{POSIX} specification). +@end itemize + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item +@var{first_page}[:@var{last_page}] +@itemx --pages=@var{first_page}[:@var{last_page}] +@c The two following @opindex lines evoke warnings because they contain `:' +@c The `info' spec does not permit that. If we use those lines, we end +@c up with truncated index entries that don't work. +@c @opindex +@var{first_page}[:@var{last_page}] +@c @opindex --pages=@var{first_page}[:@var{last_page}] +@opindex +@var{page_range} +@opindex --pages=@var{page_range} +Begin printing with page @var{first_page} and stop with @var{last_page}. +Missing @samp{:@var{last_page}} implies end of file. While estimating +the number of skipped pages each form feed in the input file results +in a new page. Page counting with and without @samp{+@var{first_page}} +is identical. By default, counting starts with the first page of input +file (not first page printed). Line numbering may be altered by @option{-N} +option. + +@item -@var{column} +@itemx --columns=@var{column} +@opindex -@var{column} +@opindex --columns +@cindex down columns +With each single @var{file}, produce @var{column} columns of output +(default is 1) and print columns down, unless @option{-a} is used. The +column width is automatically decreased as @var{column} increases; unless +you use the @option{-W/-w} option to increase @var{page_width} as well. +This option might well cause some lines to be truncated. The number of +lines in the columns on each page are balanced. The options @option{-e} +and @option{-i} are on for multiple text-column output. Together with +@option{-J} option column alignment and line truncation is turned off. +Lines of full length are joined in a free field format and @option{-S} +option may set field separators. @option{-@var{column}} may not be used +with @option{-m} option. + +@item -a +@itemx --across +@opindex -a +@opindex --across +@cindex across columns +With each single @var{file}, print columns across rather than down. The +@option{-@var{column}} option must be given with @var{column} greater than one. +If a line is too long to fit in a column, it is truncated. + +@item -c +@itemx --show-control-chars +@opindex -c +@opindex --show-control-chars +Print control characters using hat notation (e.g., @samp{^G}); print +other nonprinting characters in octal backslash notation. By default, +nonprinting characters are not changed. + +@item -d +@itemx --double-space +@opindex -d +@opindex --double-space +@cindex double spacing +Double space the output. + +@item -D @var{format} +@itemx --date-format=@var{format} +@cindex time formats +@cindex formatting times +Format header dates using @var{format}, using the same conventions as +for the command @samp{date +@var{format}}; @xref{date invocation}. +Except for directives, which start with +@samp{%}, characters in @var{format} are printed unchanged. You can use +this option to specify an arbitrary string in place of the header date, +e.g., @option{--date-format="Monday morning"}. + +@vindex POSIXLY_CORRECT +@vindex LC_TIME +Normally the date +format defaults to @samp{%Y-%m-%d %H:%M} (for example, @samp{2001-12-04 +23:59}); but if the @env{POSIXLY_CORRECT} environment variable is set +and the @env{LC_TIME} locale category specifies the @acronym{POSIX} +locale, the default is @samp{%b %e %H:%M %Y} (for example, +@samp{Dec@ @ 4 23:59 2001}. + +@vindex TZ +Time stamps are listed according to the time zone rules specified by +the @env{TZ} environment variable, or by the system default rules if +@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone +with @env{TZ}, libc, The GNU C Library}. + +@item -e[@var{in-tabchar}[@var{in-tabwidth}]] +@itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]] +@opindex -e +@opindex --expand-tabs +@cindex input tabs +Expand @var{tab}s to spaces on input. Optional argument @var{in-tabchar} is +the input tab character (default is the TAB character). Second optional +argument @var{in-tabwidth} is the input tab character's width (default +is 8). + +@item -f +@itemx -F +@itemx --form-feed +@opindex -F +@opindex -f +@opindex --form-feed +Use a form feed instead of newlines to separate output pages. The default +page length of 66 lines is not altered. But the number of lines of text +per page changes from default 56 to 63 lines. + +@item -h @var{HEADER} +@itemx --header=@var{HEADER} +@opindex -h +@opindex --header +Replace the file name in the header with the centered string @var{header}. +When using the shell, @var{header} should be quoted and should be +separated from @option{-h} by a space. + +@item -i[@var{out-tabchar}[@var{out-tabwidth}]] +@itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]] +@opindex -i +@opindex --output-tabs +@cindex output tabs +Replace spaces with @var{tab}s on output. Optional argument @var{out-tabchar} +is the output tab character (default is the TAB character). Second optional +argument @var{out-tabwidth} is the output tab character's width (default +is 8). + +@item -J +@itemx --join-lines +@opindex -J +@opindex --join-lines +Merge lines of full length. Used together with the column options +@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}. Turns off +@option{-W/-w} line truncation; +no column alignment used; may be used with +@option{--sep-string[=@var{string}]}. @option{-J} has been introduced +(together with @option{-W} and @option{--sep-string}) +to disentangle the old (@acronym{POSIX}-compliant) options @option{-w} and +@option{-s} along with the three column options. + + +@item -l @var{page_length} +@itemx --length=@var{page_length} +@opindex -l +@opindex --length +Set the page length to @var{page_length} (default 66) lines, including +the lines of the header [and the footer]. If @var{page_length} is less +than or equal to 10 (or <= 3 with @option{-F}), the header and footer are +omitted, and all form feeds set in input files are eliminated, as if +the @option{-T} option had been given. + +@item -m +@itemx --merge +@opindex -m +@opindex --merge +Merge and print all @var{file}s in parallel, one in each column. If a +line is too long to fit in a column, it is truncated, unless the @option{-J} +option is used. @option{--sep-string[=@var{string}]} may be used. +Empty pages in +some @var{file}s (form feeds set) produce empty columns, still marked +by @var{string}. The result is a continuous line numbering and column +marking throughout the whole merged file. Completely empty merged pages +show no separators or line numbers. The default header becomes +@samp{@var{date} @var{page}} with spaces inserted in the middle; this +may be used with the @option{-h} or @option{--header} option to fill up +the middle blank part. + +@item -n[@var{number-separator}[@var{digits}]] +@itemx --number-lines[=@var{number-separator}[@var{digits}]] +@opindex -n +@opindex --number-lines +Provide @var{digits} digit line numbering (default for @var{digits} is +5). With multicolumn output the number occupies the first @var{digits} +column positions of each text column or only each line of @option{-m} +output. With single column output the number precedes each line just as +@option{-m} does. Default counting of the line numbers starts with the +first line of the input file (not the first line printed, compare the +@option{--page} option and @option{-N} option). +Optional argument @var{number-separator} is the character appended to +the line number to separate it from the text followed. The default +separator is the TAB character. In a strict sense a TAB is always +printed with single column output only. The @var{TAB}-width varies +with the @var{TAB}-position, e.g., with the left @var{margin} specified +by @option{-o} option. With multicolumn output priority is given to +@samp{equal width of output columns} (a @acronym{POSIX} specification). +The @var{TAB}-width is fixed to the value of the first column and does +not change with different values of left @var{margin}. That means a +fixed number of spaces is always printed in the place of the +@var{number-separator tab}. The tabification depends upon the output +position. + +@item -N @var{line_number} +@itemx --first-line-number=@var{line_number} +@opindex -N +@opindex --first-line-number +Start line counting with the number @var{line_number} at first line of +first page printed (in most cases not the first line of the input file). + +@item -o @var{margin} +@itemx --indent=@var{margin} +@opindex -o +@opindex --indent +@cindex indenting lines +@cindex left margin +Indent each line with a margin @var{margin} spaces wide (default is zero). +The total page width is the size of the margin plus the @var{page_width} +set with the @option{-W/-w} option. A limited overflow may occur with +numbered single column output (compare @option{-n} option). + +@item -r +@itemx --no-file-warnings +@opindex -r +@opindex --no-file-warnings +Do not print a warning message when an argument @var{file} cannot be +opened. (The exit status will still be nonzero, however.) + +@item -s[@var{char}] +@itemx --separator[=@var{char}] +@opindex -s +@opindex --separator +Separate columns by a single character @var{char}. The default for +@var{char} is the TAB character without @option{-w} and @samp{no +character} with @option{-w}. Without @option{-s} the default separator +@samp{space} is set. @option{-s[char]} turns off line truncation of all +three column options (@option{-COLUMN}|@option{-a -COLUMN}|@option{-m}) unless +@option{-w} is set. This is a @acronym{POSIX}-compliant formulation. + + +@item -S@var{string} +@itemx --sep-string[=@var{string}] +@opindex -S +@opindex --sep-string +Use @var{string} to separate output columns. The @option{-S} option doesn't +affect the @option{-W/-w} option, unlike the @option{-s} option which does. It +does not affect line truncation or column alignment. +Without @option{-S}, and with @option{-J}, @command{pr} uses the default output +separator, TAB@. +Without @option{-S} or @option{-J}, @command{pr} uses a @samp{space} +(same as @option{-S"@w{ }"}). @option{--sep-string} with no +@samp{=@var{string}} is equivalent to @option{--sep-string=""}. + +@item -t +@itemx --omit-header +@opindex -t +@opindex --omit-header +Do not print the usual header [and footer] on each page, and do not fill +out the bottom of pages (with blank lines or a form feed). No page +structure is produced, but form feeds set in the input files are retained. +The predefined pagination is not changed. @option{-t} or @option{-T} may be +useful together with other options; e.g.: @option{-t -e4}, expand TAB characters +in the input file to 4 spaces but don't make any other changes. Use of +@option{-t} overrides @option{-h}. + +@item -T +@itemx --omit-pagination +@opindex -T +@opindex --omit-pagination +Do not print header [and footer]. In addition eliminate all form feeds +set in the input files. + +@item -v +@itemx --show-nonprinting +@opindex -v +@opindex --show-nonprinting +Print nonprinting characters in octal backslash notation. + +@item -w @var{page_width} +@itemx --width=@var{page_width} +@opindex -w +@opindex --width +Set page width to @var{page_width} characters for multiple text-column +output only (default for @var{page_width} is 72). @option{-s[CHAR]} turns +off the default page width and any line truncation and column alignment. +Lines of full length are merged, regardless of the column options +set. No @var{page_width} setting is possible with single column output. +A @acronym{POSIX}-compliant formulation. + +@item -W @var{page_width} +@itemx --page_width=@var{page_width} +@opindex -W +@opindex --page_width +Set the page width to @var{page_width} characters. That's valid with and +without a column option. Text lines are truncated, unless @option{-J} +is used. Together with one of the three column options +(@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}) column +alignment is always used. The separator options @option{-S} or @option{-s} +don't affect the @option{-W} option. Default is 72 characters. Without +@option{-W @var{page_width}} and without any of the column options NO line +truncation is used (defined to keep downward compatibility and to meet +most frequent tasks). That's equivalent to @option{-W 72 -J}. The header +line is never truncated. + +@end table + +@exitstatus + + +@node fold invocation +@section @command{fold}: Wrap input lines to fit in specified width + +@pindex fold +@cindex wrapping long input lines +@cindex folding long input lines + +@command{fold} writes each @var{file} (@option{-} means standard input), or +standard input if none are given, to standard output, breaking long +lines. Synopsis: + +@example +fold [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +By default, @command{fold} breaks lines wider than 80 columns. The output +is split into as many lines as necessary. + +@cindex screen columns +@command{fold} counts screen columns by default; thus, a tab may count more +than one column, backspace decreases the column count, and carriage +return sets the column to zero. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -b +@itemx --bytes +@opindex -b +@opindex --bytes +Count bytes rather than columns, so that tabs, backspaces, and carriage +returns are each counted as taking up one column, just like other +characters. + +@item -s +@itemx --spaces +@opindex -s +@opindex --spaces +Break at word boundaries: the line is broken after the last blank before +the maximum line length. If the line contains no such blanks, the line +is broken at the maximum line length as usual. + +@item -w @var{width} +@itemx --width=@var{width} +@opindex -w +@opindex --width +Use a maximum line length of @var{width} columns instead of 80. + +For compatibility @command{fold} supports an obsolete option syntax +@option{-@var{width}}. New scripts should use @option{-w @var{width}} +instead. + +@end table + +@exitstatus + + +@node Output of parts of files +@chapter Output of parts of files + +@cindex output of parts of files +@cindex parts of files, output of + +These commands output pieces of the input. + +@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. +* csplit invocation:: Split a file into context-determined pieces. +@end menu + +@node head invocation +@section @command{head}: Output the first part of files + +@pindex head +@cindex initial part of files, outputting +@cindex first part of files, outputting + +@command{head} prints the first part (10 lines by default) of each +@var{file}; it reads from standard input if no files are given or +when given a @var{file} of @option{-}. Synopsis: + +@example +head [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +If more than one @var{file} is specified, @command{head} prints a +one-line header consisting of: + +@example +==> @var{file name} <== +@end example + +@noindent +before the output for each @var{file}. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -c @var{n} +@itemx --bytes=@var{n} +@opindex -c +@opindex --bytes +Print the first @var{n} bytes, instead of initial lines. Appending +@samp{b} multiplies @var{n} by 512, @samp{k} by 1024, and @samp{m} +by 1048576. +However, if @var{n} starts with a @samp{-}, +print all but the last @var{n} bytes of each file. + +@itemx -n @var{n} +@itemx --lines=@var{n} +@opindex -n +@opindex --lines +Output the first @var{n} lines. +However, if @var{n} starts with a @samp{-}, +print all but the last @var{n} lines of each file. + +@item -q +@itemx --quiet +@itemx --silent +@opindex -q +@opindex --quiet +@opindex --silent +Never print file name headers. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Always print file name headers. + +@end table + +For compatibility @command{head} also supports an obsolete option syntax +@option{-@var{count}@var{options}}, which is recognized only if it is +specified first. @var{count} is a decimal number optionally followed +by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @option{-c}, or +@samp{l} to mean count by lines, or other option letters (@samp{cqv}). +Scripts intended for standard hosts should use @option{-c @var{count}} +or @option{-n @var{count}} instead. If your script must also run on +hosts that support only the obsolete syntax, it is usually simpler to +avoid @command{head}, e.g., by using @samp{sed 5q} instead of +@samp{head -5}. + +@exitstatus + + +@node tail invocation +@section @command{tail}: Output the last part of files + +@pindex tail +@cindex last part of files, outputting + +@command{tail} prints the last part (10 lines by default) of each +@var{file}; it reads from standard input if no files are given or +when given a @var{file} of @samp{-}. Synopsis: + +@example +tail [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +If more than one @var{file} is specified, @command{tail} prints a +one-line header consisting of: + +@example +==> @var{file name} <== +@end example + +@noindent +before the output for each @var{file}. + +@cindex BSD @command{tail} +@sc{gnu} @command{tail} can output any amount of data (some other versions of +@command{tail} cannot). It also has no @option{-r} option (print in +reverse), since reversing a file is really a different job from printing +the end of a file; BSD @command{tail} (which is the one with @option{-r}) can +only reverse files that are at most as large as its buffer, which is +typically 32 KiB@. A more reliable and versatile way to reverse files is +the @sc{gnu} @command{tac} command. + +If any option-argument is a number @var{n} starting with a @samp{+}, +@command{tail} begins printing with the @var{n}th item from the start of +each file, instead of from the end. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -c @var{bytes} +@itemx --bytes=@var{bytes} +@opindex -c +@opindex --bytes +Output the last @var{bytes} bytes, instead of final lines. Appending +@samp{b} multiplies @var{bytes} by 512, @samp{k} by 1024, and @samp{m} +by 1048576. + +@item -f +@itemx --follow[=@var{how}] +@opindex -f +@opindex --follow +@cindex growing files +@vindex name @r{follow option} +@vindex descriptor @r{follow option} +Loop forever trying to read more characters at the end of the file, +presumably because the file is growing. +If more than one file is given, @command{tail} prints a header whenever it +gets output from a different file, to indicate which file that output is +from. + +There are two ways to specify how you'd like to track files with this option, +but that difference is noticeable only when a followed file is removed or +renamed. +If you'd like to continue to track the end of a growing file even after +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. + +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 +and resumes tracking the end of the file from the newly-determined endpoint. + +When a file is removed, @command{tail}'s behavior depends on whether it is +following the name or the descriptor. When following by name, tail can +detect that a file has been removed and gives a message to that effect, +and if @option{--retry} has been specified it will continue checking +periodically to see if the file reappears. +When following a descriptor, tail does not detect that the file has +been unlinked or renamed and issues no message; even though the file +may no longer be accessible via its original name, it may still be +growing. + +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 +no @var{file} operand is specified and standard input is a FIFO or a pipe. + +@item -F +@opindex -F +This option is the same as @option{--follow=name --retry}. That is, tail +will attempt to reopen a file when it is removed. Should this fail, tail +will keep trying until it becomes accessible again. + +@itemx --retry +@opindex --retry +This option is useful mainly when following by name (i.e., with +@option{--follow=name}). +Without this option, when tail encounters a file that doesn't +exist or is otherwise inaccessible, it reports that fact and +never checks it again. + +@itemx --sleep-interval=@var{number} +@opindex --sleep-interval +Change the number of seconds to wait between iterations (the default is 1.0). +During one iteration, every specified file is checked to see if it has +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). + +@itemx --pid=@var{pid} +@opindex --pid +When following by name or by descriptor, you may specify the process ID, +@var{pid}, of the sole writer of all @var{file} arguments. Then, shortly +after that process terminates, tail will also terminate. This will +work properly only if the writer and the tailing process are running on +the same machine. For example, to save the output of a build in a file +and to watch the file grow, if you invoke @command{make} and @command{tail} +like this then the tail process will stop when your build completes. +Without this option, you would have had to kill the @code{tail -f} +process yourself. + +@example +$ make >& makerr & tail --pid=$! -f makerr +@end example + +If you specify a @var{pid} that is not in use or that does not correspond +to the process that is writing to the tailed files, then @command{tail} +may terminate long before any @var{file}s stop growing or it may not +terminate until long after the real writer has terminated. +Note that @option{--pid} cannot be supported on some systems; @command{tail} +will print a warning if this is the case. + +@itemx --max-unchanged-stats=@var{n} +@opindex --max-unchanged-stats +When tailing a file by name, if there have been @var{n} (default +n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive +iterations for which the file has not changed, then +@code{open}/@code{fstat} the file to determine if that file name is +still associated with the same device/inode-number pair as before. +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. + +@itemx -n @var{n} +@itemx --lines=@var{n} +@opindex -n +@opindex --lines +Output the last @var{n} lines. + +@item -q +@itemx --quiet +@itemx --silent +@opindex -q +@opindex --quiet +@opindex --silent +Never print file name headers. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Always print file name headers. + +@end table + +For compatibility @command{tail} also supports an obsolete usage +@samp{tail -[@var{count}][bcl][f] [@var{file}]}, which is recognized +only if it does not conflict with the usage described +above. This obsolete form uses exactly one option and at most one +file. In the option, @var{count} is an optional decimal number optionally +followed by a size letter (@samp{b}, @samp{c}, @samp{l}) to mean count +by 512-byte blocks, bytes, or lines, optionally followed by @samp{f} +which has the same meaning as @option{-f}. + +@vindex _POSIX2_VERSION +On older systems, the leading @samp{-} can be replaced by @samp{+} in +the obsolete option syntax with the same meaning as in counts, and +obsolete usage overrides normal usage when the two conflict. +This obsolete behavior can be enabled or disabled with the +@env{_POSIX2_VERSION} environment variable (@pxref{Standards +conformance}). + +Scripts intended for use on standard hosts should avoid obsolete +syntax and should use @option{-c @var{count}[b]}, @option{-n +@var{count}}, and/or @option{-f} instead. If your script must also +run on hosts that support only the obsolete syntax, you can often +rewrite it to avoid problematic usages, e.g., by using @samp{sed -n +'$p'} rather than @samp{tail -1}. If that's not possible, the script +can use a test like @samp{if tail -c +1 </dev/null >/dev/null 2>&1; +then @dots{}} to decide which syntax to use. + +Even if your script assumes the standard behavior, you should still +beware usages whose behaviors differ depending on the @acronym{POSIX} +version. For example, avoid @samp{tail - main.c}, since it might be +interpreted as either @samp{tail main.c} or as @samp{tail -- - +main.c}; avoid @samp{tail -c 4}, since it might mean either @samp{tail +-c4} or @samp{tail -c 10 4}; and avoid @samp{tail +4}, since it might +mean either @samp{tail ./+4} or @samp{tail -n +4}. + +@exitstatus + + +@node split invocation +@section @command{split}: Split a file into fixed-size 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: + +@example +split [@var{option}] [@var{input} [@var{prefix}]] +@end example + +By default, @command{split} puts 1000 lines of @var{input} (or whatever is +left over for the last section), into each output file. + +@cindex output file name 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. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -a @var{length} +@itemx --suffix-length=@var{length} +@opindex -a +@opindex --suffix-length +Use suffixes of length @var{length}. The default @var{length} is 2. + +@item -l @var{lines} +@itemx --lines=@var{lines} +@opindex -l +@opindex --lines +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. + +@item -b @var{bytes} +@itemx --bytes=@var{bytes} +@opindex -b +@opindex --bytes +Put the first @var{bytes} bytes of @var{input} into each output file. +Appending @samp{b} multiplies @var{bytes} by 512, @samp{k} by 1024, and +@samp{m} by 1048576. + +@item -C @var{bytes} +@itemx --line-bytes=@var{bytes} +@opindex -C +@opindex --line-bytes +Put into each output file as many complete lines of @var{input} as +possible without exceeding @var{bytes} bytes. For lines longer than +@var{bytes} bytes, put @var{bytes} bytes into each output file until +less than @var{bytes} bytes of the line are left, then continue +normally. @var{bytes} has the same format as for the @option{--bytes} +option. + +@item -d +@itemx --numeric-suffixes +@opindex -d +@opindex --numeric-suffixes +Use digits in suffixes rather than lower-case letters. + +@itemx --verbose +@opindex --verbose +Write a diagnostic to standard error just before each output file is opened. + +@end table + +@exitstatus + + +@node csplit invocation +@section @command{csplit}: Split a file into context-determined pieces + +@pindex csplit +@cindex context splitting +@cindex splitting a file into pieces by context + +@command{csplit} creates zero or more output files containing sections of +@var{input} (standard input if @var{input} is @samp{-}). Synopsis: + +@example +csplit [@var{option}]@dots{} @var{input} @var{pattern}@dots{} +@end example + +The contents of the output files are determined by the @var{pattern} +arguments, as detailed below. An error occurs if a @var{pattern} +argument refers to a nonexistent line of the input file (e.g., if no +remaining line matches a given regular expression). After every +@var{pattern} has been matched, any remaining input is copied into one +last output file. + +By default, @command{csplit} prints the number of bytes written to each +output file after it has been created. + +The types of pattern arguments are: + +@table @samp + +@item @var{n} +Create an output file containing the input up to but not including line +@var{n} (a positive integer). If followed by a repeat count, also +create an output file containing the next @var{n} lines of the input +file once for each repeat. + +@item /@var{regexp}/[@var{offset}] +Create an output file containing the current line up to (but not +including) the next line of the input file that contains a match for +@var{regexp}. The optional @var{offset} is an integer. +If it is given, the input up to (but not including) the +matching line plus or minus @var{offset} is put into the output file, +and the line after that begins the next section of input. + +@item %@var{regexp}%[@var{offset}] +Like the previous type, except that it does not create an output +file, so that section of the input file is effectively ignored. + +@item @{@var{repeat-count}@} +Repeat the previous pattern @var{repeat-count} additional +times. The @var{repeat-count} can either be a positive integer or an +asterisk, meaning repeat as many times as necessary until the input is +exhausted. + +@end table + +The output files' names consist of a prefix (@samp{xx} by default) +followed by a suffix. By default, the suffix is an ascending sequence +of two-digit decimal numbers from @samp{00} to @samp{99}. In any case, +concatenating the output files in sorted order by file name produces the +original input file. + +By default, if @command{csplit} encounters an error or receives a hangup, +interrupt, quit, or terminate signal, it removes any output files +that it has created so far before it exits. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -f @var{prefix} +@itemx --prefix=@var{prefix} +@opindex -f +@opindex --prefix +@cindex output file name prefix +Use @var{prefix} as the output file name prefix. + +@item -b @var{suffix} +@itemx --suffix=@var{suffix} +@opindex -b +@opindex --suffix +@cindex output file name suffix +Use @var{suffix} as the output file name suffix. When this option is +specified, the suffix string must include exactly one +@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}, +@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 +individual output files in turn. If this option is used, the +@option{--digits} option is ignored. + +@item -n @var{digits} +@itemx --digits=@var{digits} +@opindex -n +@opindex --digits +Use output file names containing numbers that are @var{digits} digits +long instead of the default 2. + +@item -k +@itemx --keep-files +@opindex -k +@opindex --keep-files +Do not remove output files when errors are encountered. + +@item -z +@itemx --elide-empty-files +@opindex -z +@opindex --elide-empty-files +Suppress the generation of zero-length output files. (In cases where +the section delimiters of the input file are supposed to mark the first +lines of each of the sections, the first output file will generally be a +zero-length file unless you use this option.) The output file sequence +numbers always run consecutively starting from 0, even when this option +is specified. + +@item -s +@itemx -q +@itemx --silent +@itemx --quiet +@opindex -s +@opindex -q +@opindex --silent +@opindex --quiet +Do not print counts of output file sizes. + +@end table + +@exitstatus + + +@node Summarizing files +@chapter Summarizing files + +@cindex summarizing files + +These commands generate just a few numbers representing entire +contents of files. + +@menu +* 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. +@end menu + + +@node wc invocation +@section @command{wc}: Print newline, word, and byte counts + +@pindex wc +@cindex byte count +@cindex character count +@cindex word count +@cindex line count + +@command{wc} counts the number of bytes, characters, whitespace-separated +words, and newlines in each given @var{file}, or standard input if none +are given or for a @var{file} of @samp{-}. Synopsis: + +@example +wc [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +@cindex total counts +@command{wc} prints one line of counts for each file, and if the file was +given as an argument, it prints the file name following the counts. If +more than one @var{file} is given, @command{wc} prints a final line +containing the cumulative counts, with the file name @file{total}. The +counts are printed in this order: newlines, words, characters, bytes, +maximum line length. +Each count is printed right-justified in a field with at least one +space between fields so that the numbers and file names normally line +up nicely in columns. The width of the count fields varies depending +on the inputs, so you should not depend on a particular field width. +However, as a @acronym{GNU} extension, if only one count is printed, +it is guaranteed to be printed without leading spaces. + +By default, @command{wc} prints three counts: the newline, words, and byte +counts. Options can specify that only certain counts be printed. +Options do not undo others previously given, so + +@example +wc --bytes --words +@end example + +@noindent +prints both the byte counts and the word counts. + +With the @option{--max-line-length} option, @command{wc} prints the length +of the longest line per file, and if there is more than one file it +prints the maximum (not the sum) of those lengths. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -c +@itemx --bytes +@opindex -c +@opindex --bytes +Print only the byte counts. + +@item -m +@itemx --chars +@opindex -m +@opindex --chars +Print only the character counts. + +@item -w +@itemx --words +@opindex -w +@opindex --words +Print only the word counts. + +@item -l +@itemx --lines +@opindex -l +@opindex --lines +Print only the newline counts. + +@item -L +@itemx --max-line-length +@opindex -L +@opindex --max-line-length +Print only the maximum line lengths. + +@itemx --files0-from=@var{FILE} +@opindex --files0-from=@var{FILE} +@cindex including files from @command{du} +Rather than processing files named on the command line, process those +named in file @var{FILE}; each name is terminated by a null byte. +This is useful when +the list of file names is so long that it may exceed a command line +length limitation. +In such cases, running @command{wc} via @command{xargs} is undesirable +because it splits the list into pieces and makes @command{wc} print a +total for each sublist rather than for the entire list. +One way to produce a list of null-byte-terminated file names is with @sc{gnu} +@command{find}, using its @option{-print0} predicate. For example, to find +the length of the longest line in any @file{.c} or @file{.h} file in the +current hierarchy, do this: + +@example +find . -name '*.[ch]' -print0 | wc -L --files0-from=- | tail -n1 +@end example + +Do not specify any @var{FILE} on the command line when using this option. + +@end table + +@exitstatus + + +@node sum invocation +@section @command{sum}: Print checksum and block counts + +@pindex sum +@cindex 16-bit checksum +@cindex checksum, 16-bit + +@command{sum} computes a 16-bit checksum for each given @var{file}, or +standard input if none are given or for a @var{file} of @samp{-}. Synopsis: + +@example +sum [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +@command{sum} prints the checksum for each @var{file} followed by the +number of blocks in the file (rounded up). If more than one @var{file} +is given, file names are also printed (by default). (With the +@option{--sysv} option, corresponding file names are printed when there is +at least one file argument.) + +By default, @sc{gnu} @command{sum} computes checksums using an algorithm +compatible with BSD @command{sum} and prints file sizes in units of +1024-byte blocks. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -r +@opindex -r +@cindex BSD @command{sum} +Use the default (BSD compatible) algorithm. This option is included for +compatibility with the System V @command{sum}. Unless @option{-s} was also +given, it has no effect. + +@item -s +@itemx --sysv +@opindex -s +@opindex --sysv +@cindex System V @command{sum} +Compute checksums using an algorithm compatible with System V +@command{sum}'s default, and print file sizes in units of 512-byte blocks. + +@end table + +@command{sum} is provided for compatibility; the @command{cksum} program (see +next section) is preferable in new applications. + +@exitstatus + + +@node cksum invocation +@section @command{cksum}: Print CRC checksum and byte counts + +@pindex cksum +@cindex cyclic redundancy check +@cindex CRC checksum + +@command{cksum} computes a cyclic redundancy check (CRC) checksum for each +given @var{file}, or standard input if none are given or for a +@var{file} of @samp{-}. Synopsis: + +@example +cksum [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +@command{cksum} prints the CRC checksum for each file along with the number +of bytes in the file, and the file name unless no arguments were given. + +@command{cksum} is typically used to ensure that files +transferred by unreliable means (e.g., netnews) have not been corrupted, +by comparing the @command{cksum} output for the received files with the +@command{cksum} output for the original files (typically given in the +distribution). + +The CRC algorithm is specified by the @acronym{POSIX} standard. It is not +compatible with the BSD or System V @command{sum} algorithms (see the +previous section); it is more robust. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +@exitstatus + + +@node md5sum invocation +@section @command{md5sum}: Print or check MD5 digests + +@pindex md5sum +@cindex MD5 +@cindex 128-bit checksum +@cindex checksum, 128-bit +@cindex fingerprint, 128-bit +@cindex message-digest, 128-bit + +@command{md5sum} computes a 128-bit checksum (or @dfn{fingerprint} or +@dfn{message-digest}) for each specified @var{file}. + +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}. + +If a @var{file} is specified as @samp{-} or if no files are given +@command{md5sum} computes the checksum for the standard input. +@command{md5sum} can also determine whether a file and checksum are +consistent. Synopsis: + +@example +md5sum [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +For each @var{file}, @samp{md5sum} outputs the MD5 checksum, a flag +indicating a binary or text input file, and the file name. +If @var{file} contains a backslash or newline, the +line is started with a backslash, and each problematic character in +the file name is escaped with a backslash, making the output +unambiguous even in the presence of arbitrary file names. +If @var{file} is omitted or specified as @samp{-}, standard input is read. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -b +@itemx --binary +@opindex -b +@opindex --binary +@cindex binary input files +Treat each input file as binary, by reading it in binary mode and +outputting a @samp{*} flag. This is the inverse of @option{--text}. +On systems like @acronym{GNU} that do not distinguish between binary +and text files, this option merely flags each input file as binary: +the MD5 checksum is unaffected. This option is the default on systems +like MS-DOS that distinguish between binary and text files, except +for reading standard input when standard input is a terminal. + +@item -c +@itemx --check +Read file names and checksum information (not data) from each +@var{file} (or from stdin if no @var{file} was specified) and report +whether the checksums match the contents of the named files. +The input to this mode of @command{md5sum} is usually the output of +a prior, checksum-generating run of @samp{md5sum}. +Each valid line of input consists of an MD5 checksum, a binary/text +flag, and then a file name. +Binary files are marked with @samp{*}, text with @samp{ }. +For each such line, @command{md5sum} reads the named file and computes its +MD5 checksum. Then, if the computed message digest does not match the +one on the line with the file name, the file is noted as having +failed the test. Otherwise, the file passes the test. +By default, for each valid line, one line is written to standard +output indicating whether the named file passed the test. +After all checks have been performed, if there were any failures, +a warning is issued to standard error. +Use the @option{--status} option to inhibit that output. +If any listed file cannot be opened or read, if any valid line has +an MD5 checksum inconsistent with the associated file, or if no valid +line is found, @command{md5sum} exits with nonzero status. Otherwise, +it exits successfully. + +@itemx --status +@opindex --status +@cindex verifying MD5 checksums +This option is useful only when verifying checksums. +When verifying checksums, don't generate the default one-line-per-file +diagnostic and don't output the warning summarizing any failures. +Failures to open or read a file still evoke individual diagnostics to +standard error. +If all listed files are readable and are consistent with the associated +MD5 checksums, exit successfully. Otherwise exit with a status code +indicating there was a failure. + +@item -t +@itemx --text +@opindex -t +@opindex --text +@cindex text input files +Treat each input file as text, by reading it in text mode and +outputting a @samp{ } flag. This is the inverse of @option{--binary}. +This option is the default on systems like @acronym{GNU} that do not +distinguish between binary and text files. On other systems, it is +the default for reading standard input when standard input is a +terminal. + +@item -w +@itemx --warn +@opindex -w +@opindex --warn +@cindex verifying MD5 checksums +When verifying checksums, warn about improperly formatted MD5 checksum lines. +This option is useful only if all but a few lines in the checked input +are valid. + +@end table + +@exitstatus + + +@node sha1sum invocation +@section @command{sha1sum}: Print or check SHA-1 digests + +@pindex sha1sum +@cindex SHA-1 +@cindex 160-bit checksum +@cindex checksum, 160-bit +@cindex fingerprint, 160-bit +@cindex message-digest, 160-bit + +@command{sha1sum} computes a 160-bit checksum for each specified +@var{file}. The usage and options of this command are precisely the +same as for @command{md5sum}. @xref{md5sum invocation}. + +Note: The SHA-1 digest is more secure than MD5, and no collisions of +it are known (different files having the same fingerprint). However, +it is known that they can be produced with considerable, but not +unreasonable, resources. For this reason, it is generally considered +that SHA-1 should be gradually phased out in favor of the more secure +SHA-2 hash algorithms. @xref{sha2 utilities}. + + +@node sha2 utilities +@section sha2 utilities: Print or check SHA-2 digests + +@pindex sha224sum +@pindex sha256sum +@pindex sha384sum +@pindex sha512sum +@cindex SHA-2 +@cindex 224-bit checksum +@cindex 256-bit checksum +@cindex 384-bit checksum +@cindex 512-bit checksum +@cindex checksum, 224-bit +@cindex checksum, 256-bit +@cindex checksum, 384-bit +@cindex checksum, 512-bit +@cindex fingerprint, 224-bit +@cindex fingerprint, 256-bit +@cindex fingerprint, 384-bit +@cindex fingerprint, 512-bit +@cindex message-digest, 224-bit +@cindex message-digest, 256-bit +@cindex message-digest, 384-bit +@cindex message-digest, 512-bit + +The commands @command{sha224sum}, @command{sha256sum}, +@command{sha384sum} and @command{sha512sum} compute checksums of +various lengths (respectively 224, 256, 384 and 512 bits), +collectively known as the SHA-2 hashes. The usage and options of +these commands are precisely the same as for @command{md5sum}. +@xref{md5sum invocation}. + +Note: The SHA384 and SHA512 digests are considerably slower to +compute, especially on 32-bit computers, than SHA224 or SHA256. + + +@node Operating on sorted files +@chapter Operating on sorted files + +@cindex operating on sorted files +@cindex sorted files, operations on + +These commands work with (or produce) sorted files. + +@menu +* 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. +* tsort background:: Where tsort came from. +@end menu + + +@node sort invocation +@section @command{sort}: Sort text files + +@pindex sort +@cindex sorting files + +@command{sort} sorts, merges, or compares all the lines from the given +files, or standard input if none are given or for a @var{file} of +@samp{-}. By default, @command{sort} writes the results to standard +output. Synopsis: + +@example +sort [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +@command{sort} has three modes of operation: sort (the default), merge, +and check for sortedness. The following options change the operation +mode: + +@table @samp + +@item -c +@itemx --check +@itemx --check=diagnose-first +@opindex -c +@opindex --check +@cindex checking for sortedness +Check whether the given file is already sorted: if it is not all +sorted, print a diagnostic containing the first out-of-order line and +exit with a status of 1. +Otherwise, exit successfully. +At most one input file can be given. + +@item -C +@itemx --check=quiet +@itemx --check=silent +@opindex -c +@opindex --check +@cindex checking for sortedness +Exit successfully if the given file is already sorted, and +exit with status 1 otherwise. +At most one input file can be given. +This is like @option{-c}, except it does not print a diagnostic. + +@item -m +@itemx --merge +@opindex -m +@opindex --merge +@cindex merging sorted files +Merge the given files by sorting them as a group. Each input file must +always be individually sorted. It always works to sort instead of +merge; merging is provided because it is faster, in the case where it +works. + +@end table + +@cindex sort stability +@cindex sort's last-resort comparison +A pair of lines is compared as follows: +@command{sort} compares each pair of fields, in the +order specified on the command line, according to the associated +ordering options, until a difference is found or no fields are left. +If no key fields are specified, @command{sort} uses a default key of +the entire line. Finally, as a last resort when all keys compare +equal, @command{sort} compares entire lines as if no ordering options +other than @option{--reverse} (@option{-r}) were specified. The +@option{--stable} (@option{-s}) option disables this @dfn{last-resort +comparison} so that lines in which all fields compare equal are left +in their original relative order. The @option{--unique} +(@option{-u}) option also disables the last-resort comparison. + +@vindex LC_ALL +@vindex LC_COLLATE +Unless otherwise specified, all comparisons use the character collating +sequence specified by the @env{LC_COLLATE} locale.@footnote{If you +use a non-@acronym{POSIX} locale (e.g., by setting @env{LC_ALL} +to @samp{en_US}), then @command{sort} may produce output that is sorted +differently than you're accustomed to. In that case, set the @env{LC_ALL} +environment variable to @samp{C}. Note that setting only @env{LC_COLLATE} +has two problems. First, it is ineffective if @env{LC_ALL} is also set. +Second, it has undefined behavior if @env{LC_CTYPE} (or @env{LANG}, if +@env{LC_CTYPE} is unset) is set to an incompatible value. For example, +you get undefined behavior if @env{LC_CTYPE} is @code{ja_JP.PCK} but +@env{LC_COLLATE} is @code{en_US.UTF-8}.} + +@sc{gnu} @command{sort} (as specified for all @sc{gnu} utilities) has no +limit on input line length or restrictions on bytes allowed within lines. +In addition, if the final byte of an input file is not a newline, @sc{gnu} +@command{sort} silently supplies one. A line's trailing newline is not +part of the line for comparison purposes. + +@cindex exit status of @command{sort} +Exit status: + +@display +0 if no error occurred +1 if invoked with @option{-c} or @option{-C} and the input is not sorted +2 if an error occurred +@end display + +@vindex TMPDIR +If the environment variable @env{TMPDIR} is set, @command{sort} uses its +value as the directory for temporary files instead of @file{/tmp}. The +@option{--temporary-directory} (@option{-T}) option in turn overrides +the environment variable. + +The following options affect the ordering of output lines. They may be +specified globally or as part of a specific key field. If no key +fields are specified, global options apply to comparison of entire +lines; otherwise the global options are inherited by key fields that do +not specify any special options of their own. In pre-@acronym{POSIX} +versions of @command{sort}, global options affect only later key fields, +so portable shell scripts should specify global options first. + +@table @samp + +@item -b +@itemx --ignore-leading-blanks +@opindex -b +@opindex --ignore-leading-blanks +@cindex blanks, ignoring leading +@vindex LC_CTYPE +Ignore leading blanks when finding sort keys in each line. +By default a blank is a space or a tab, but the @env{LC_CTYPE} locale +can change this. + +@item -d +@itemx --dictionary-order +@opindex -d +@opindex --dictionary-order +@cindex dictionary order +@cindex phone directory order +@cindex telephone directory order +@vindex LC_CTYPE +Sort in @dfn{phone directory} order: ignore all characters except +letters, digits and blanks when sorting. +By default letters and digits are those of @acronym{ASCII} and a blank +is a space or a tab, but the @env{LC_CTYPE} locale can change this. + +@item -f +@itemx --ignore-case +@opindex -f +@opindex --ignore-case +@cindex ignoring case +@cindex case folding +@vindex LC_CTYPE +Fold lowercase characters into the equivalent uppercase characters when +comparing so that, for example, @samp{b} and @samp{B} sort as equal. +The @env{LC_CTYPE} locale determines character types. + +@item -g +@itemx --general-numeric-sort +@opindex -g +@opindex --general-numeric-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. +Do not report overflow, underflow, or conversion errors. +Use the following collating sequence: + +@itemize @bullet +@item +Lines that do not start with numbers (all considered to be equal). +@item +NaNs (``Not a Number'' values, in IEEE floating point arithmetic) +in a consistent but machine-dependent order. +@item +Minus infinity. +@item +Finite numbers in ascending numeric order (with @math{-0} and @math{+0} equal). +@item +Plus infinity. +@end itemize + +Use this option only if there is no alternative; it is much slower than +@option{--numeric-sort} (@option{-n}) and it can lose information when +converting to floating point. + +@item -i +@itemx --ignore-nonprinting +@opindex -i +@opindex --ignore-nonprinting +@cindex nonprinting characters, ignoring +@cindex unprintable characters, ignoring +@vindex LC_CTYPE +Ignore nonprinting characters. +The @env{LC_CTYPE} locale determines character types. +This option has no effect if the stronger @option{--dictionary-order} +(@option{-d}) option is also given. + +@item -M +@itemx --month-sort +@opindex -M +@opindex --month-sort +@cindex months, sorting by +@vindex LC_TIME +An initial string, consisting of any amount of blanks, followed +by a month name abbreviation, is folded to UPPER case and +compared in the order @samp{JAN} < @samp{FEB} < @dots{} < @samp{DEC}. +Invalid names compare low to valid names. The @env{LC_TIME} locale +category determines the month spellings. +By default a blank is a space or a tab, but the @env{LC_CTYPE} locale +can change this. + +@item -n +@itemx --numeric-sort +@opindex -n +@opindex --numeric-sort +@cindex numeric sort +@vindex LC_NUMERIC +Sort numerically. The number begins each line and consists +of optional blanks, an optional @samp{-} sign, and zero or more +digits possibly separated by thousands separators, optionally followed +by a decimal-point character and zero or more digits. An empty +number is treated as @samp{0}. The @env{LC_NUMERIC} +locale specifies the decimal-point character and thousands separator. +By default a blank is a space or a tab, but the @env{LC_CTYPE} locale +can change this. + +Comparison is exact; there is no rounding error. + +Neither a leading @samp{+} nor exponential notation is recognized. +To compare such strings numerically, use the +@option{--general-numeric-sort} (@option{-g}) option. + +@item -r +@itemx --reverse +@opindex -r +@opindex --reverse +@cindex reverse sorting +Reverse the result of comparison, so that lines with greater key values +appear earlier in the output instead of later. + +@item -R +@itemx --random-sort +@opindex -R +@opindex --random-sort +@cindex random sort +Sort by hashing the input keys and then sorting the hash values. +Choose the hash function at random, ensuring that it is free of +collisions so that differing keys have differing hash values. This is +like a random permutation of the inputs (@pxref{shuf invocation}), +except that keys with the same value sort together. + +If multiple random sort fields are specified, the same random hash +function is used for all fields. To use different random hash +functions for different fields, you can invoke @command{sort} more +than once. + +The choice of hash function is affected by the +@option{--random-source} option. + +@end table + +Other options are: + +@table @samp + +@item --compress-program=@var{prog} +Compress any temporary files with the program @var{prog}. + +With no arguments, @var{prog} must compress standard input to standard +output, and when given the @option{-d} option it must decompress +standard input to standard output. + +Terminate with an error if @var{prog} exits with nonzero status. + +Whitespace and the backslash character should not appear in +@var{prog}; they are reserved for future use. + +@item -k @var{pos1}[,@var{pos2}] +@itemx --key=@var{pos1}[,@var{pos2}] +@opindex -k +@opindex --key +@cindex sort field +Specify a sort field that consists of the part of the line between +@var{pos1} and @var{pos2} (or the end of the line, if @var{pos2} is +omitted), @emph{inclusive}. + +Each @var{pos} has the form @samp{@var{f}[.@var{c}][@var{opts}]}, +where @var{f} is the number of the field to use, and @var{c} is the number +of the first character from the beginning of the field. Fields and character +positions are numbered starting with 1; a character position of zero in +@var{pos2} indicates the field's last character. If @samp{.@var{c}} is +omitted from @var{pos1}, it defaults to 1 (the beginning of the field); +if omitted from @var{pos2}, it defaults to 0 (the end of the field). +@var{opts} are ordering options, allowing individual keys to be sorted +according to different rules; see below for details. Keys can span +multiple fields. + +Example: To sort on the second field, use @option{--key=2,2} +(@option{-k 2,2}). See below for more examples. + +@item -o @var{output-file} +@itemx --output=@var{output-file} +@opindex -o +@opindex --output +@cindex overwriting of input, allowed +Write output to @var{output-file} instead of standard output. +Normally, @command{sort} reads all input before opening +@var{output-file}, so you can safely sort a file in place by using +commands like @code{sort -o F F} and @code{cat F | sort -o F}. +However, @command{sort} with @option{--merge} (@option{-m}) can open +the output file before reading all input, so a command like @code{cat +F | sort -m -o F - G} is not safe as @command{sort} might start +writing @file{F} before @command{cat} is done reading it. + +@vindex POSIXLY_CORRECT +On newer systems, @option{-o} cannot appear after an input file if +@env{POSIXLY_CORRECT} is set, e.g., @samp{sort F -o F}. Portable +scripts should specify @option{-o @var{output-file}} before any input +files. + +@item --random-source=@var{file} +@opindex --random-source +@cindex random source for sorting +Use @var{file} as a source of random data used to determine which +random hash function to use with the @option{-R} option. @xref{Random +sources}. + +@item -s +@itemx --stable +@opindex -s +@opindex --stable +@cindex sort stability +@cindex sort's last-resort comparison + +Make @command{sort} stable by disabling its last-resort comparison. +This option has no effect if no fields or global ordering options +other than @option{--reverse} (@option{-r}) are specified. + +@item -S @var{size} +@itemx --buffer-size=@var{size} +@opindex -S +@opindex --buffer-size +@cindex size for main memory sorting +Use a main-memory sort buffer of the given @var{size}. By default, +@var{size} is in units of 1024 bytes. Appending @samp{%} causes +@var{size} to be interpreted as a percentage of physical memory. +Appending @samp{K} multiplies @var{size} by 1024 (the default), +@samp{M} by 1,048,576, @samp{G} by 1,073,741,824, and so on for +@samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}. Appending +@samp{b} causes @var{size} to be interpreted as a byte count, with no +multiplication. + +This option can improve the performance of @command{sort} by causing it +to start with a larger or smaller sort buffer than the default. +However, this option affects only the initial buffer size. The buffer +grows beyond @var{size} if @command{sort} encounters input lines larger +than @var{size}. + +@item -t @var{separator} +@itemx --field-separator=@var{separator} +@opindex -t +@opindex --field-separator +@cindex field separator character +Use character @var{separator} as the field separator when finding the +sort keys in each line. By default, fields are separated by the empty +string between a non-blank character and a blank character. +By default a blank is a space or a tab, but the @env{LC_CTYPE} locale +can change this. + +That is, given the input line @w{@samp{ foo bar}}, @command{sort} breaks it +into fields @w{@samp{ foo}} and @w{@samp{ bar}}. The field separator is +not considered to be part of either the field preceding or the field +following, so with @samp{sort @w{-t " "}} the same input line has +three fields: an empty field, @samp{foo}, and @samp{bar}. +However, fields that extend to the end of the line, +as @option{-k 2}, or fields consisting of a range, as @option{-k 2,3}, +retain the field separators present between the endpoints of the range. + +To specify a null character (@acronym{ASCII} @sc{nul}) as +the field separator, use the two-character string @samp{\0}, e.g., +@samp{sort -t '\0'}. + +@item -T @var{tempdir} +@itemx --temporary-directory=@var{tempdir} +@opindex -T +@opindex --temporary-directory +@cindex temporary directory +@vindex TMPDIR +Use directory @var{tempdir} to store temporary files, overriding the +@env{TMPDIR} environment variable. If this option is given more than +once, temporary files are stored in all the directories given. If you +have a large sort or merge that is I/O-bound, you can often improve +performance by using this option to specify directories on different +disks and controllers. + +@item -u +@itemx --unique +@opindex -u +@opindex --unique +@cindex uniquifying output + +Normally, output only the first of a sequence of lines that compare +equal. For the @option{--check} (@option{-c} or @option{-C}) option, +check that no pair of consecutive lines compares equal. + +This option also disables the default last-resort comparison. + +The commands @code{sort -u} and @code{sort | uniq} are equivalent, but +this equivalence does not extend to arbitrary @command{sort} options. +For example, @code{sort -n -u} inspects only the value of the initial +numeric string when checking for uniqueness, whereas @code{sort -n | +uniq} inspects the entire line. @xref{uniq invocation}. + +@item -z +@itemx --zero-terminated +@opindex -z +@opindex --zero-terminated +@cindex sort zero-terminated lines +Treat the input as a set of lines, each terminated by a null character +(@acronym{ASCII} @sc{nul}) instead of a line feed +(@acronym{ASCII} @sc{lf}). +This option can be useful in conjunction with @samp{perl -0} or +@samp{find -print0} and @samp{xargs -0} which do the same in order to +reliably handle arbitrary file names (even those containing blanks +or other special characters). + +@end table + +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} +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 +affect the meaning of character positions in field specifications in +obscure cases. The only fix is to add an explicit @option{-b}. + +A position in a sort field specified with @option{-k} may have any +of the option letters @samp{Mbdfinr} appended to it, in which case the +global ordering options are not used for that particular field. The +@option{-b} option may be independently attached to either or both of +the start and end positions of a field specification, and if it is +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}, +@option{-g}, @option{-M}, or @option{-n}; 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 +the line or after the end field, the field is empty. If the @option{-b} +option was specified, the @samp{.@var{c}} part of a field specification +is counted from the first nonblank character of the field. + +@vindex _POSIX2_VERSION +@vindex POSIXLY_CORRECT +On older systems, @command{sort} supports an obsolete origin-zero +syntax @samp{+@var{pos1} [-@var{pos2}]} for specifying sort keys. +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 +not set by using the obsolete syntax with @samp{-@var{pos2}} present. + +Scripts intended for use on standard hosts should avoid obsolete +syntax and should use @option{-k} instead. For example, avoid +@samp{sort +2}, since it might be interpreted as either @samp{sort +./+2} or @samp{sort -k 3}. If your script must also run on hosts that +support only the obsolete syntax, it can use a test like @samp{if sort +-k 1 </dev/null >/dev/null 2>&1; then @dots{}} to decide which syntax +to use. + +Here are some examples to illustrate various combinations of options. + +@itemize @bullet + +@item +Sort in descending (reverse) numeric order. + +@example +sort -n -r +@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 +at the start of the first nonblank character in field three +and extending to the end of each line. + +@example +sort -k 3b +@end example + +@item +Sort numerically on the second field and resolve ties by sorting +alphabetically on the third and fourth characters of field five. +Use @samp{:} as the field delimiter. + +@example +sort -t : -k 2,2n -k 5.3,5.4 +@end example + +Note that if you had written @option{-k 2n} instead of @option{-k 2,2n} +@command{sort} would have used all characters beginning in the second field +and extending to the end of the line as the primary @emph{numeric} +key. For the large majority of applications, treating keys spanning +more than one field as numeric will not do what you expect. + +Also note that the @samp{n} modifier was applied to the field-end +specifier for the first key. It would have been equivalent to +specify @option{-k 2n,2} or @option{-k 2n,2n}. All modifiers except +@samp{b} apply to the associated @emph{field}, regardless of whether +the modifier character is attached to the field-start and/or the +field-end part of the key specifier. + +@item +Sort the password file on the fifth field and ignore any +leading blanks. Sort lines with equal values in field five +on the numeric user ID in field three. Fields are separated +by @samp{:}. + +@example +sort -t : -k 5b,5 -k 3,3n /etc/passwd +sort -t : -n -k 5b,5 -k 3,3 /etc/passwd +sort -t : -b -k 5,5 -k 3,3n /etc/passwd +@end example + +These three commands have equivalent effect. The first specifies that +the first key's start position ignores leading blanks and the second +key is sorted numerically. The other two commands rely on global +options being inherited by sort keys that lack modifiers. The inheritance +works in this case because @option{-k 5b,5b} and @option{-k 5b,5} are +equivalent, as the location of a field-end lacking a @samp{.@var{c}} +character position is not affected by whether initial blanks are +skipped. + +@item +Sort a set of log files, primarily by IPv4 address and secondarily by +time stamp. If two lines' primary and secondary keys are identical, +output the lines in the same order that they were input. The log +files contain lines that look like this: + +@example +4.150.156.3 - - [01/Apr/2004:06:31:51 +0000] message 1 +211.24.3.231 - - [24/Apr/2004:20:17:39 +0000] message 2 +@end example + +Fields are separated by exactly one space. Sort IPv4 addresses +lexicographically, e.g., 212.61.52.2 sorts before 212.129.233.201 +because 61 is less than 129. + +@example +sort -s -t ' ' -k 4.9n -k 4.5M -k 4.2n -k 4.14,4.21 file*.log | +sort -s -t '.' -k 1,1n -k 2,2n -k 3,3n -k 4,4n +@end example + +This example cannot be done with a single @command{sort} invocation, +since IPv4 address components are separated by @samp{.} while dates +come just after a space. So it is broken down into two invocations of +@command{sort}: the first sorts by time stamp and the second by IPv4 +address. The time stamp is sorted by year, then month, then day, and +finally by hour-minute-second field, using @option{-k} to isolate each +field. Except for hour-minute-second there's no need to specify the +end of each key field, since the @samp{n} and @samp{M} modifiers sort +based on leading prefixes that cannot cross field boundaries. The +IPv4 addresses are sorted lexicographically. The second sort uses +@samp{-s} so that ties in the primary key are broken by the secondary +key; the first sort uses @samp{-s} so that the combination of the two +sorts is stable. + +@item +Generate a tags file in case-insensitive sorted order. + +@smallexample +find src -type f -print0 | sort -z -f | xargs -0 etags --append +@end smallexample + +The use of @option{-print0}, @option{-z}, and @option{-0} in this case means +that file names that contain blanks or other special characters are +not broken up +by the sort operation. + +@c This example is a bit contrived and needs more explanation. +@c @item +@c Sort records separated by an arbitrary string by using a pipe to convert +@c each record delimiter string to @samp{\0}, then using sort's -z option, +@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 @end example + +@item +Shuffle a list of directories, but preserve the order of files within +each directory. For instance, one could use this to generate a music +playlist in which albums are shuffled but the songs of each album are +played in order. + +@example +ls */* | sort -t / -k 1,1R -k 2,2 +@end example + +@end itemize + + +@node shuf invocation +@section @command{shuf}: Shuffling text + +@pindex shuf +@cindex shuffling files + +@command{shuf} shuffles its input by outputting a random permutation +of its input lines. Each output permutation is equally likely. +Synopses: + +@example +shuf [@var{option}]@dots{} [@var{file}] +shuf -e [@var{option}]@dots{} [@var{arg}]@dots{} +shuf -i @var{lo}-@var{hi} [@var{option}]@dots{} +@end example + +@command{shuf} has three modes of operation that affect where it +obtains its input lines. By default, it reads lines from standard +input. The following options change the operation mode: + +@table @samp + +@item -e +@itemx --echo +@opindex -c +@opindex --echo +@cindex command-line operands to shuffle +Treat each command-line operand as an input line. + +@item -i @var{lo}-@var{hi} +@itemx --input-range=@var{lo}-@var{hi} +@opindex -i +@opindex --input-range +@cindex input range to shuffle +Act as if input came from a file containing the range of unsigned +decimal integers @var{lo}@dots{}@var{hi}, one per line. + +@end table + +@command{shuf}'s other options can affect its behavior in all +operation modes: + +@table @samp + +@item -n @var{lines} +@itemx --head-lines=@var{lines} +@opindex -n +@opindex --head-lines +@cindex head of output +Output at most @var{lines} lines. By default, all input lines are +output. + +@item -o @var{output-file} +@itemx --output=@var{output-file} +@opindex -o +@opindex --output +@cindex overwriting of input, allowed +Write output to @var{output-file} instead of standard output. +@command{shuf} reads all input before opening +@var{output-file}, so you can safely shuffle a file in place by using +commands like @code{shuf -o F <F} and @code{cat F | shuf -o F}. + +@item --random-source=@var{file} +@opindex --random-source +@cindex random source for shuffling +Use @var{file} as a source of random data used to determine which +permutation to generate. @xref{Random sources}. + +@item -z +@itemx --zero-terminated +@opindex -z +@opindex --zero-terminated +@cindex sort zero-terminated lines +Treat the input and output as a set of lines, each terminated by a zero byte +(@acronym{ASCII} @sc{nul} (Null) character) instead of an +@acronym{ASCII} @sc{lf} (Line Feed). +This option can be useful in conjunction with @samp{perl -0} or +@samp{find -print0} and @samp{xargs -0} which do the same in order to +reliably handle arbitrary file names (even those containing blanks +or other special characters). + +@end table + +For example: + +@example +shuf <<EOF +A man, +a plan, +a canal: +Panama! +EOF +@end example + +@noindent +might produce the output + +@example +Panama! +A man, +a canal: +a plan, +@end example + +@noindent +Similarly, the command: + +@example +shuf -e clubs hearts diamonds spades +@end example + +@noindent +might output: + +@example +clubs +diamonds +spades +hearts +@end example + +@noindent +and the command @samp{shuf -i 1-4} might output: + +@example +4 +2 +1 +3 +@end example + +@noindent +These examples all have four input lines, so @command{shuf} might +produce any of the twenty-four possible permutations of the input. In +general, if there are @var{N} input lines, there are @var{N}! (i.e., +@var{N} factorial, or @var{N} * (@var{N} - 1) * @dots{} * 1) possible +output permutations. + +@exitstatus + + +@node uniq invocation +@section @command{uniq}: Uniquify files + +@pindex uniq +@cindex uniquify files + +@command{uniq} writes the unique lines in the given @file{input}, or +standard input if nothing is given or for an @var{input} name of +@samp{-}. Synopsis: + +@example +uniq [@var{option}]@dots{} [@var{input} [@var{output}]] +@end example + +By default, @command{uniq} prints its input lines, except that +it discards all but the first of adjacent repeated lines, so that +no output lines are repeated. Optionally, it can instead discard +lines that are not repeated, or all repeated lines. + +The input need not be sorted, but repeated input lines are detected +only if they are adjacent. If you want to discard non-adjacent +duplicate lines, perhaps you want to use @code{sort -u}. +@xref{sort invocation}. + +@vindex LC_COLLATE +Comparisons use the character collating sequence specified by the +@env{LC_COLLATE} locale category. + +If no @var{output} file is specified, @command{uniq} writes to standard +output. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -f @var{n} +@itemx --skip-fields=@var{n} +@opindex -f +@opindex --skip-fields +Skip @var{n} fields on each line before checking for uniqueness. Use +a null string for comparison if a line has fewer than @var{n} fields. Fields +are sequences of non-space non-tab characters that are separated from +each other by at least one space or tab. + +For compatibility @command{uniq} supports an obsolete option syntax +@option{-@var{n}}. New scripts should use @option{-f @var{n}} instead. + +@item -s @var{n} +@itemx --skip-chars=@var{n} +@opindex -s +@opindex --skip-chars +Skip @var{n} characters before checking for uniqueness. Use a null string +for comparison if a line has fewer than @var{n} characters. If you use both +the field and character skipping options, fields are skipped over first. + +@vindex _POSIX2_VERSION +On older systems, @command{uniq} supports an obsolete option syntax +@option{+@var{n}}. +This obsolete behavior can be enabled or disabled with the +@env{_POSIX2_VERSION} environment variable (@pxref{Standards +conformance}), but portable scripts should avoid commands whose +behavior depends on this variable. +For example, use @samp{uniq ./+10} or @samp{uniq -s 10} rather than +the ambiguous @samp{uniq +10}. + +@item -c +@itemx --count +@opindex -c +@opindex --count +Print the number of times each line occurred along with the line. + +@item -i +@itemx --ignore-case +@opindex -i +@opindex --ignore-case +Ignore differences in case when comparing lines. + +@item -d +@itemx --repeated +@opindex -d +@opindex --repeated +@cindex repeated lines, outputting +Discard lines that are not repeated. When used by itself, this option +causes @command{uniq} to print the first copy of each repeated line, +and nothing else. + +@item -D +@itemx --all-repeated[=@var{delimit-method}] +@opindex -D +@opindex --all-repeated +@cindex all repeated lines, outputting +Do not discard the second and subsequent repeated input lines, +but discard lines that are not repeated. +This option is useful mainly in conjunction with other options e.g., +to ignore case or to compare only selected fields. +The optional @var{delimit-method} tells how to delimit +groups of repeated lines, and must be one of the following: + +@table @samp + +@item none +Do not delimit groups of repeated lines. +This is equivalent to @option{--all-repeated} (@option{-D}). + +@item prepend +Output a newline before each group of repeated lines. + +@item separate +Separate groups of repeated lines with a single newline. +This is the same as using @samp{prepend}, except that +there is no newline before the first group, and hence +may be better suited for output direct to users. +@end table + +Note that when groups are delimited and the input stream contains +two or more consecutive blank lines, then the output is ambiguous. +To avoid that, filter the input through @samp{tr -s '\n'} to replace +each sequence of consecutive newlines with a single newline. + +This is a @sc{gnu} extension. +@c FIXME: give an example showing *how* it's useful + +@item -u +@itemx --unique +@opindex -u +@opindex --unique +@cindex unique lines, outputting +Discard the first repeated line. When used by itself, this option +causes @command{uniq} to print unique lines, and nothing else. + +@item -w @var{n} +@itemx --check-chars=@var{n} +@opindex -w +@opindex --check-chars +Compare at most @var{n} characters on each line (after skipping any specified +fields and characters). By default the entire rest of the lines are +compared. + +@end table + +@exitstatus + + +@node comm invocation +@section @command{comm}: Compare two sorted files line by line + +@pindex comm +@cindex line-by-line comparison +@cindex comparing sorted files + +@command{comm} writes to standard output lines that are common, and lines +that are unique, to two input files; a file name of @samp{-} means +standard input. Synopsis: + +@example +comm [@var{option}]@dots{} @var{file1} @var{file2} +@end example + +@vindex LC_COLLATE +Before @command{comm} can be used, the input files must be sorted using the +collating sequence specified by the @env{LC_COLLATE} locale. +If an input file ends in a non-newline +character, a newline is silently appended. The @command{sort} command with +no options always outputs a file that is suitable input to @command{comm}. + +@cindex differing lines +@cindex common lines +With no options, @command{comm} produces three-column output. Column one +contains lines unique to @var{file1}, column two contains lines unique +to @var{file2}, and column three contains lines common to both files. +Columns are separated by a single TAB character. +@c FIXME: when there's an option to supply an alternative separator +@c string, append `by default' to the above sentence. + +@opindex -1 +@opindex -2 +@opindex -3 +The options @option{-1}, @option{-2}, and @option{-3} suppress printing of +the corresponding columns. Also see @ref{Common options}. + +Unlike some other comparison utilities, @command{comm} has an exit +status that does not depend on the result of the comparison. +Upon normal completion @command{comm} produces an exit code of zero. +If there is an error it exits with nonzero status. + + +@node tsort invocation +@section @command{tsort}: Topological sort + +@pindex tsort +@cindex topological sort + +@command{tsort} performs a topological sort on the given @var{file}, or +standard input if no input file is given or for a @var{file} of +@samp{-}. For more details and some history, see @ref{tsort background}. +Synopsis: + +@example +tsort [@var{option}] [@var{file}] +@end example + +@command{tsort} reads its input as pairs of strings, separated by blanks, +indicating a partial ordering. The output is a total ordering that +corresponds to the given partial ordering. + +For example + +@example +tsort <<EOF +a b c +d +e f +b c d e +EOF +@end example + +@noindent +will produce the output + +@example +a +b +c +d +e +f +@end example + +Consider a more realistic example. +You have a large set of functions all in one file, and they may all be +declared static except one. Currently that one (say @code{main}) is the +first function defined in the file, and the ones it calls directly follow +it, followed by those they call, etc. Let's say that you are determined +to take advantage of prototypes, so you have to choose between declaring +all of those functions (which means duplicating a lot of information from +the definitions) and rearranging the functions so that as many as possible +are defined before they are used. One way to automate the latter process +is to get a list for each function of the functions it calls directly. +Many programs can generate such lists. They describe a call graph. +Consider the following list, in which a given line indicates that the +function on the left calls the one on the right directly. + +@example +main parse_options +main tail_file +main tail_forever +tail_file pretty_name +tail_file write_header +tail_file tail +tail_forever recheck +tail_forever pretty_name +tail_forever write_header +tail_forever dump_remainder +tail tail_lines +tail tail_bytes +tail_lines start_lines +tail_lines dump_remainder +tail_lines file_lines +tail_lines pipe_lines +tail_bytes xlseek +tail_bytes start_bytes +tail_bytes dump_remainder +tail_bytes pipe_bytes +file_lines dump_remainder +recheck pretty_name +@end example + +then you can use @command{tsort} to produce an ordering of those +functions that satisfies your requirement. + +@example +example$ tsort call-graph | tac +dump_remainder +start_lines +file_lines +pipe_lines +xlseek +start_bytes +pipe_bytes +tail_lines +tail_bytes +pretty_name +write_header +tail +recheck +parse_options +tail_file +tail_forever +main +@end example + +@command{tsort} detects any cycles in the input and writes the first cycle +encountered to standard error. + +Note that for a given partial ordering, generally there is no unique +total ordering. In the context of the call graph above, the function +@code{parse_options} may be placed anywhere in the list as long as it +precedes @code{main}. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +@node tsort background +@section @command{tsort}: Background + +@command{tsort} exists because very early versions of the Unix linker processed +an archive file exactly once, and in order. As @command{ld} read each object +in the archive, it decided whether it was needed in the program based on +whether it defined any symbols which were undefined at that point in +the link. + +This meant that dependencies within the archive had to be handled +specially. For example, @code{scanf} probably calls @code{read}. That means +that in a single pass through an archive, it was important for @code{scanf.o} +to appear before read.o, because otherwise a program which calls +@code{scanf} but not @code{read} might end up with an unexpected unresolved +reference to @code{read}. + +The way to address this problem was to first generate a set of +dependencies of one object file on another. This was done by a shell +script called @command{lorder}. The GNU tools don't provide a version of +lorder, as far as I know, but you can still find it in BSD +distributions. + +Then you ran @command{tsort} over the @command{lorder} output, and you used the +resulting sort to define the order in which you added objects to the archive. + +This whole procedure has been obsolete since about 1980, because +Unix archives now contain a symbol table (traditionally built by +@command{ranlib}, now generally built by @command{ar} itself), and the Unix +linker uses the symbol table to effectively make multiple passes over +an archive file. + +Anyhow, that's where tsort came from. To solve an old problem with +the way the linker handled archive files, which has since been solved +in different ways. + +@exitstatus + + +@node ptx invocation +@section @command{ptx}: Produce permuted indexes + +@pindex ptx + +@command{ptx} reads a text file and essentially produces a permuted index, with +each keyword in its context. The calling sketch is either one of: + +@example +ptx [@var{option} @dots{}] [@var{file} @dots{}] +ptx -G [@var{option} @dots{}] [@var{input} [@var{output}]] +@end example + +The @option{-G} (or its equivalent: @option{--traditional}) option disables +all @sc{gnu} extensions and reverts to traditional mode, thus introducing some +limitations and changing several of the program's default option values. +When @option{-G} is not specified, @sc{gnu} extensions are always enabled. +@sc{gnu} extensions to @command{ptx} are documented wherever appropriate in this +document. For the full list, see @xref{Compatibility in ptx}. + +Individual options are explained in the following sections. + +When @sc{gnu} extensions are enabled, there may be zero, one or several +@var{file}s after the options. If there is no @var{file}, the program +reads the standard input. If there is one or several @var{file}s, they +give the name of input files which are all read in turn, as if all the +input files were concatenated. However, there is a full contextual +break between each file and, when automatic referencing is requested, +file names and line numbers refer to individual text input files. In +all cases, the program outputs the permuted index to the standard +output. + +When @sc{gnu} extensions are @emph{not} enabled, that is, when the program +operates in traditional mode, there may be zero, one or two parameters +besides the options. If there are no parameters, the program reads the +standard input and outputs the permuted index to the standard output. +If there is only one parameter, it names the text @var{input} to be read +instead of the standard input. If two parameters are given, they give +respectively the name of the @var{input} file to read and the name of +the @var{output} file to produce. @emph{Be very careful} to note that, +in this case, the contents of file given by the second parameter is +destroyed. This behavior is dictated by System V @command{ptx} +compatibility; @sc{gnu} Standards normally discourage output parameters not +introduced by an option. + +Note that for @emph{any} file named as the value of an option or as an +input text file, a single dash @kbd{-} may be used, in which case +standard input is assumed. However, it would not make sense to use this +convention more than once per program invocation. + +@menu +* 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:: +@end menu + + +@node General options in ptx +@subsection General options + +@table @samp + +@item -G +@itemx --traditional +As already explained, this option disables all @sc{gnu} extensions to +@command{ptx} and switches to traditional mode. + +@item --help +Print a short help on standard output, then exit without further +processing. + +@item --version +Print the program version on standard output, then exit without further +processing. + +@end table + +@exitstatus + + +@node Charset selection in ptx +@subsection Charset selection + +@c FIXME: People don't necessarily know what an IBM-PC was these days. +As it is set up now, the program assumes that the input file is coded +using 8-bit @acronym{ISO} 8859-1 code, also known as Latin-1 character set, +@emph{unless} it is compiled for MS-DOS, in which case it uses the +character set of the IBM-PC@. (@sc{gnu} @command{ptx} is not known to work on +smaller MS-DOS machines anymore.) Compared to 7-bit @acronym{ASCII}, the set +of characters which are letters is different; this alters the behavior +of regular expression matching. Thus, the default regular expression +for a keyword allows foreign or diacriticized letters. Keyword sorting, +however, is still crude; it obeys the underlying character set ordering +quite blindly. + +@table @samp + +@item -f +@itemx --ignore-case +Fold lower case letters to upper case for sorting. + +@end table + + +@node Input processing in ptx +@subsection Word selection and input processing + +@table @samp + +@item -b @var{file} +@itemx --break-file=@var{file} + +This option provides an alternative (to @option{-W}) method of describing +which characters make up words. It introduces the name of a +file which contains a list of characters which can@emph{not} be part of +one word; this file is called the @dfn{Break file}. Any character which +is not part of the Break file is a word constituent. If both options +@option{-b} and @option{-W} are specified, then @option{-W} has precedence and +@option{-b} is ignored. + +When @sc{gnu} extensions are enabled, the only way to avoid newline as a +break character is to write all the break characters in the file with no +newline at all, not even at the end of the file. When @sc{gnu} extensions +are disabled, spaces, tabs and newlines are always considered as break +characters even if not included in the Break file. + +@item -i @var{file} +@itemx --ignore-file=@var{file} + +The file associated with this option contains a list of words which will +never be taken as keywords in concordance output. It is called the +@dfn{Ignore file}. The file contains exactly one word in each line; the +end of line separation of words is not subject to the value of the +@option{-S} option. + +@item -o @var{file} +@itemx --only-file=@var{file} + +The file associated with this option contains a list of words which will +be retained in concordance output; any word not mentioned in this file +is ignored. The file is called the @dfn{Only file}. The file contains +exactly one word in each line; the end of line separation of words is +not subject to the value of the @option{-S} option. + +There is no default for the Only file. When both an Only file and an +Ignore file are specified, a word is considered a keyword only +if it is listed in the Only file and not in the Ignore file. + +@item -r +@itemx --references + +On each input line, the leading sequence of non-white space characters will be +taken to be a reference that has the purpose of identifying this input +line in the resulting permuted index. For more information about reference +production, see @xref{Output formatting in ptx}. +Using this option changes the default value for option @option{-S}. + +Using this option, the program does not try very hard to remove +references from contexts in output, but it succeeds in doing so +@emph{when} the context ends exactly at the newline. If option +@option{-r} is used with @option{-S} default value, or when @sc{gnu} extensions +are disabled, this condition is always met and references are completely +excluded from the output contexts. + +@item -S @var{regexp} +@itemx --sentence-regexp=@var{regexp} + +This option selects which regular expression will describe the end of a +line or the end of a sentence. In fact, this regular expression is not +the only distinction between end of lines or end of sentences, and input +line boundaries have no special significance outside this option. By +default, when @sc{gnu} extensions are enabled and if @option{-r} option is not +used, end of sentences are used. In this case, this @var{regex} is +imported from @sc{gnu} Emacs: + +@example +[.?!][]\"')@}]*\\($\\|\t\\| \\)[ \t\n]* +@end example + +Whenever @sc{gnu} extensions are disabled or if @option{-r} option is used, end +of lines are used; in this case, the default @var{regexp} is just: + +@example +\n +@end example + +Using an empty @var{regexp} is equivalent to completely disabling end of +line or end of sentence recognition. In this case, the whole file is +considered to be a single big line or sentence. The user might want to +disallow all truncation flag generation as well, through option @option{-F +""}. @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs +Manual}. + +When the keywords happen to be near the beginning of the input line or +sentence, this often creates an unused area at the beginning of the +output context line; when the keywords happen to be near the end of the +input line or sentence, this often creates an unused area at the end of +the output context line. The program tries to fill those unused areas +by wrapping around context in them; the tail of the input line or +sentence is used to fill the unused area on the left of the output line; +the head of the input line or sentence is used to fill the unused area +on the right of the output line. + +As a matter of convenience to the user, many usual backslashed escape +sequences from the C language are recognized and converted to the +corresponding characters by @command{ptx} itself. + +@item -W @var{regexp} +@itemx --word-regexp=@var{regexp} + +This option selects which regular expression will describe each keyword. +By default, if @sc{gnu} extensions are enabled, a word is a sequence of +letters; the @var{regexp} used is @samp{\w+}. When @sc{gnu} extensions are +disabled, a word is by default anything which ends with a space, a tab +or a newline; the @var{regexp} used is @samp{[^ \t\n]+}. + +An empty @var{regexp} is equivalent to not using this option. +@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs +Manual}. + +As a matter of convenience to the user, many usual backslashed escape +sequences, as found in the C language, are recognized and converted to +the corresponding characters by @command{ptx} itself. + +@end table + + +@node Output formatting in ptx +@subsection Output formatting + +Output format is mainly controlled by the @option{-O} and @option{-T} options +described in the table below. When neither @option{-O} nor @option{-T} are +selected, and if @sc{gnu} extensions are enabled, the program chooses an +output format suitable for a dumb terminal. Each keyword occurrence is +output to the center of one line, surrounded by its left and right +contexts. Each field is properly justified, so the concordance output +can be readily observed. As a special feature, if automatic +references are selected by option @option{-A} and are output before the +left context, that is, if option @option{-R} is @emph{not} selected, then +a colon is added after the reference; this nicely interfaces with @sc{gnu} +Emacs @code{next-error} processing. In this default output format, each +white space character, like newline and tab, is merely changed to +exactly one space, with no special attempt to compress consecutive +spaces. This might change in the future. Except for those white space +characters, every other character of the underlying set of 256 +characters is transmitted verbatim. + +Output format is further controlled by the following options. + +@table @samp + +@item -g @var{number} +@itemx --gap-size=@var{number} + +Select the size of the minimum white space gap between the fields on the +output line. + +@item -w @var{number} +@itemx --width=@var{number} + +Select the maximum output width of each final line. If references are +used, they are included or excluded from the maximum output width +depending on the value of option @option{-R}. If this option is not +selected, that is, when references are output before the left context, +the maximum output width takes into account the maximum length of all +references. If this option is selected, that is, when references are +output after the right context, the maximum output width does not take +into account the space taken by references, nor the gap that precedes +them. + +@item -A +@itemx --auto-reference + +Select automatic references. Each input line will have an automatic +reference made up of the file name and the line ordinal, with a single +colon between them. However, the file name will be empty when standard +input is being read. If both @option{-A} and @option{-r} are selected, then +the input reference is still read and skipped, but the automatic +reference is used at output time, overriding the input reference. + +@item -R +@itemx --right-side-refs + +In the default output format, when option @option{-R} is not used, any +references produced by the effect of options @option{-r} or @option{-A} are +placed to the far right of output lines, after the right context. With +default output format, when the @option{-R} option is specified, references +are rather placed at the beginning of each output line, before the left +context. For any other output format, option @option{-R} is +ignored, with one exception: with @option{-R} the width of references +is @emph{not} taken into account in total output width given by @option{-w}. + +This option is automatically selected whenever @sc{gnu} extensions are +disabled. + +@item -F @var{string} +@itemx --flac-truncation=@var{string} + +This option will request that any truncation in the output be reported +using the string @var{string}. Most output fields theoretically extend +towards the beginning or the end of the current line, or current +sentence, as selected with option @option{-S}. But there is a maximum +allowed output line width, changeable through option @option{-w}, which is +further divided into space for various output fields. When a field has +to be truncated because it cannot extend beyond the beginning or the end of +the current line to fit in, then a truncation occurs. By default, +the string used is a single slash, as in @option{-F /}. + +@var{string} may have more than one character, as in @option{-F ...}. +Also, in the particular case when @var{string} is empty (@option{-F ""}), +truncation flagging is disabled, and no truncation marks are appended in +this case. + +As a matter of convenience to the user, many usual backslashed escape +sequences, as found in the C language, are recognized and converted to +the corresponding characters by @command{ptx} itself. + +@item -M @var{string} +@itemx --macro-name=@var{string} + +Select another @var{string} to be used instead of @samp{xx}, while +generating output suitable for @command{nroff}, @command{troff} or @TeX{}. + +@item -O +@itemx --format=roff + +Choose an output format suitable for @command{nroff} or @command{troff} +processing. Each output line will look like: + +@smallexample +.xx "@var{tail}" "@var{before}" "@var{keyword_and_after}" "@var{head}" "@var{ref}" +@end smallexample + +so it will be possible to write a @samp{.xx} roff macro to take care of +the output typesetting. This is the default output format when @sc{gnu} +extensions are disabled. Option @option{-M} can be used to change +@samp{xx} to another macro name. + +In this output format, each non-graphical character, like newline and +tab, is merely changed to exactly one space, with no special attempt to +compress consecutive spaces. Each quote character: @kbd{"} is doubled +so it will be correctly processed by @command{nroff} or @command{troff}. + +@item -T +@itemx --format=tex + +Choose an output format suitable for @TeX{} processing. Each output +line will look like: + +@smallexample +\xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@{@var{after}@}@{@var{head}@}@{@var{ref}@} +@end smallexample + +@noindent +so it will be possible to write a @code{\xx} definition to take care of +the output typesetting. Note that when references are not being +produced, that is, neither option @option{-A} nor option @option{-r} is +selected, the last parameter of each @code{\xx} call is inhibited. +Option @option{-M} can be used to change @samp{xx} to another macro +name. + +In this output format, some special characters, like @kbd{$}, @kbd{%}, +@kbd{&}, @kbd{#} and @kbd{_} are automatically protected with a +backslash. Curly brackets @kbd{@{}, @kbd{@}} are protected with a +backslash and a pair of dollar signs (to force mathematical mode). The +backslash itself produces the sequence @code{\backslash@{@}}. +Circumflex and tilde diacritical marks produce the sequence @code{^\@{ @}} and +@code{~\@{ @}} respectively. Other diacriticized characters of the +underlying character set produce an appropriate @TeX{} sequence as far +as possible. The other non-graphical characters, like newline and tab, +and all other characters which are not part of @acronym{ASCII}, are merely +changed to exactly one space, with no special attempt to compress +consecutive spaces. Let me know how to improve this special character +processing for @TeX{}. + +@end table + + +@node Compatibility in ptx +@subsection The @sc{gnu} extensions to @command{ptx} + +This version of @command{ptx} contains a few features which do not exist in +System V @command{ptx}. These extra features are suppressed by using the +@option{-G} command line option, unless overridden by other command line +options. Some @sc{gnu} extensions cannot be recovered by overriding, so the +simple rule is to avoid @option{-G} if you care about @sc{gnu} extensions. +Here are the differences between this program and System V @command{ptx}. + +@itemize @bullet + +@item +This program can read many input files at once, it always writes the +resulting concordance on standard output. On the other hand, System V +@command{ptx} reads only one file and sends the result to standard output +or, if a second @var{file} parameter is given on the command, to that +@var{file}. + +Having output parameters not introduced by options is a dangerous +practice which @sc{gnu} avoids as far as possible. So, for using @command{ptx} +portably between @sc{gnu} and System V, you should always use it with a +single input file, and always expect the result on standard output. You +might also want to automatically configure in a @option{-G} option to +@command{ptx} calls in products using @command{ptx}, if the configurator finds +that the installed @command{ptx} accepts @option{-G}. + +@item +The only options available in System V @command{ptx} are options @option{-b}, +@option{-f}, @option{-g}, @option{-i}, @option{-o}, @option{-r}, @option{-t} and +@option{-w}. All other options are @sc{gnu} extensions and are not repeated in +this enumeration. Moreover, some options have a slightly different +meaning when @sc{gnu} extensions are enabled, as explained below. + +@item +By default, concordance output is not formatted for @command{troff} or +@command{nroff}. It is rather formatted for a dumb terminal. @command{troff} +or @command{nroff} output may still be selected through option @option{-O}. + +@item +Unless @option{-R} option is used, the maximum reference width is +subtracted from the total output line width. With @sc{gnu} extensions +disabled, width of references is not taken into account in the output +line width computations. + +@item +All 256 bytes, even null bytes, are always read and processed from +input file with no adverse effect, even if @sc{gnu} extensions are disabled. +However, System V @command{ptx} does not accept 8-bit characters, a few +control characters are rejected, and the tilde @kbd{~} is also rejected. + +@item +Input line length is only limited by available memory, even if @sc{gnu} +extensions are disabled. However, System V @command{ptx} processes only +the first 200 characters in each line. + +@item +The break (non-word) characters default to be every character except all +letters of the underlying character set, diacriticized or not. When @sc{gnu} +extensions are disabled, the break characters default to space, tab and +newline only. + +@item +The program makes better use of output line width. If @sc{gnu} extensions +are disabled, the program rather tries to imitate System V @command{ptx}, +but still, there are some slight disposition glitches this program does +not completely reproduce. + +@item +The user can specify both an Ignore file and an Only file. This is not +allowed with System V @command{ptx}. + +@end itemize + + +@node Operating on fields within a line +@chapter Operating on fields within a line + +@menu +* cut invocation:: Print selected parts of lines. +* paste invocation:: Merge lines of files. +* join invocation:: Join lines on a common field. +@end menu + + +@node cut invocation +@section @command{cut}: Print selected parts of lines + +@pindex cut +@command{cut} writes to standard output selected parts of each line of each +input file, or standard input if no files are given or for a file name of +@samp{-}. Synopsis: + +@example +cut [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +In the table which follows, the @var{byte-list}, @var{character-list}, +and @var{field-list} are one or more numbers or ranges (two numbers +separated by a dash) separated by commas. Bytes, characters, and +fields are numbered starting at 1. Incomplete ranges may be +given: @option{-@var{m}} means @samp{1-@var{m}}; @samp{@var{n}-} means +@samp{@var{n}} through end of line or last field. The list elements +can be repeated, can overlap, and can be specified in any order; but +the selected input is written in the same order that it is read, and +is written exactly once. + +The program accepts the following options. Also see @ref{Common +options}. + +@table @samp + +@item -b @var{byte-list} +@itemx --bytes=@var{byte-list} +@opindex -b +@opindex --bytes +Select for printing only the bytes in positions listed in +@var{byte-list}. Tabs and backspaces are treated like any other +character; they take up 1 byte. If an output delimiter is specified, +(see the description of @option{--output-delimiter}), then output that +string between ranges of selected bytes. + +@item -c @var{character-list} +@itemx --characters=@var{character-list} +@opindex -c +@opindex --characters +Select for printing only the characters in positions listed in +@var{character-list}. The same as @option{-b} for now, but +internationalization will change that. Tabs and backspaces are +treated like any other character; they take up 1 character. If an +output delimiter is specified, (see the description of +@option{--output-delimiter}), then output that string between ranges +of selected bytes. + +@item -f @var{field-list} +@itemx --fields=@var{field-list} +@opindex -f +@opindex --fields +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 + +@item -d @var{input_delim_byte} +@itemx --delimiter=@var{input_delim_byte} +@opindex -d +@opindex --delimiter +With @option{-f}, use the first byte of @var{input_delim_byte} as +the input fields separator (default is TAB). + +@item -n +@opindex -n +Do not split multi-byte characters (no-op for now). + +@item -s +@itemx --only-delimited +@opindex -s +@opindex --only-delimited +For @option{-f}, do not print lines that do not contain the field separator +character. Normally, any line without a field separator is printed verbatim. + +@item --output-delimiter=@var{output_delim_string} +@opindex --output-delimiter +With @option{-f}, output fields are separated by @var{output_delim_string}. +The default with @option{-f} is to use the input delimiter. +When using @option{-b} or @option{-c} to select ranges of byte or +character offsets (as opposed to ranges of fields), +output @var{output_delim_string} between non-overlapping +ranges of selected bytes. + +@item --complement +@opindex --complement +This option is a @acronym{GNU} extension. +Select for printing the complement of the bytes, characters or fields +selected with the @option{-b}, @option{-c} or @option{-f} options. +In other words, do @emph{not} print the bytes, characters or fields +specified via those options. This option is useful when you have +many fields and want to print all but a few of them. + +@end table + +@exitstatus + + +@node paste invocation +@section @command{paste}: Merge lines of files + +@pindex paste +@cindex merging files + +@command{paste} writes to standard output lines consisting of sequentially +corresponding lines of each given file, separated by a TAB character. +Standard input is used for a file name of @samp{-} or if no input files +are given. + +For example: + +@example +$ cat num2 +1 +2 +$ cat let3 +a +b +c +$ paste num2 let3 +1 a +2 b + @ c +@end example + +Synopsis: + +@example +paste [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -s +@itemx --serial +@opindex -s +@opindex --serial +Paste the lines of one file at a time rather than one line from each +file. Using the above example data: + +@example +$ paste -s num2 let3 +1 2 +a b c +@end example + +@item -d @var{delim-list} +@itemx --delimiters=@var{delim-list} +@opindex -d +@opindex --delimiters +Consecutively use the characters in @var{delim-list} instead of +TAB to separate merged lines. When @var{delim-list} is +exhausted, start again at its beginning. Using the above example data: + +@example +$ paste -d '%_' num2 let3 num2 +1%a_1 +2%b_2 +%c_ +@end example + +@end table + +@exitstatus + + +@node join invocation +@section @command{join}: Join lines on a common field + +@pindex join +@cindex common field, joining on + +@command{join} writes to standard output a line for each pair of input +lines that have identical join fields. Synopsis: + +@example +join [@var{option}]@dots{} @var{file1} @var{file2} +@end example + +Either @var{file1} or @var{file2} (but not both) can be @samp{-}, +meaning standard input. @var{file1} and @var{file2} should be +sorted on the join fields. + +@vindex LC_COLLATE +Normally, the sort order is that of the +collating sequence specified by the @env{LC_COLLATE} locale. Unless +the @option{-t} option is given, the sort comparison ignores blanks at +the start of the join field, as in @code{sort -b}. If the +@option{--ignore-case} option is given, the sort comparison ignores +the case of characters in the join field, as in @code{sort -f}. + +The @command{sort} and @command{join} commands should use consistent +locales and options if the output of @command{sort} is fed to +@command{join}. You can use a command like @samp{sort -k 1b,1} to +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}. + +As a @acronym{GNU} extension, if the input has no unpairable lines the +sort order can be any order that considers two fields to be equal if and +only if the sort comparison described above considers them to be equal. +For example: + +@example +$ cat file1 +a a1 +c c1 +b b1 +$ cat file2 +a a2 +c c2 +b b2 +$ join file1 file2 +a a1 a2 +c c1 c2 +b b1 b2 +@end example + +The defaults are: +@itemize +@item the join field is the first field in each line; +@item fields in the input are separated by one or more blanks, with leading + blanks on the line ignored; +@item fields in the output are separated by a space; +@item each output line consists of the join field, the remaining +fields from @var{file1}, then the remaining fields from @var{file2}. +@end itemize + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -a @var{file-number} +@opindex -a +Print a line for each unpairable line in file @var{file-number} (either +@samp{1} or @samp{2}), in addition to the normal output. + +@item -e @var{string} +@opindex -e +Replace those output fields that are missing in the input with +@var{string}. + +@item -i +@itemx --ignore-case +@opindex -i +@opindex --ignore-case +Ignore differences in case when comparing keys. +With this option, the lines of the input files must be ordered in the same way. +Use @samp{sort -f} to produce this ordering. + +@item -1 @var{field} +@opindex -1 +Join on field @var{field} (a positive integer) of file 1. + +@item -2 @var{field} +@opindex -2 +Join on field @var{field} (a positive integer) of file 2. + +@item -j @var{field} +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. + +A field specification of @samp{0} denotes the join field. +In most cases, the functionality of the @samp{0} field spec +may be reproduced using the explicit @var{m.n} that corresponds +to the join field. However, when printing unpairable lines +(using either of the @option{-a} or @option{-v} options), there is no way +to specify the join field using @var{m.n} in @var{field-list} +if there are unpairable lines in both files. +To give @command{join} that functionality, @acronym{POSIX} invented the @samp{0} +field specification notation. + +The elements in @var{field-list} +are separated by commas or blanks. +Blank separators typically need to be quoted for the shell. For +example, the commands @samp{join -o 1.2,2.2} and @samp{join -o '1.2 +2.2'} are equivalent. + +All output lines---including those printed because of any -a or -v +option---are subject to the specified @var{field-list}. + +@item -t @var{char} +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. + +@item -v @var{file-number} +Print a line for each unpairable line in file @var{file-number} +(either @samp{1} or @samp{2}), instead of the normal output. + +@end table + +@exitstatus + + +@node Operating on characters +@chapter Operating on characters + +@cindex operating on characters + +This commands operate on individual characters. + +@menu +* tr invocation:: Translate, squeeze, and/or delete characters. +* expand invocation:: Convert tabs to spaces. +* unexpand invocation:: Convert spaces to tabs. +@end menu + + +@node tr invocation +@section @command{tr}: Translate, squeeze, and/or delete characters + +@pindex tr + +Synopsis: + +@example +tr [@var{option}]@dots{} @var{set1} [@var{set2}] +@end example + +@command{tr} copies standard input to standard output, performing +one of the following operations: + +@itemize @bullet +@item +translate, and optionally squeeze repeated characters in the result, +@item +squeeze repeated characters, +@item +delete characters, +@item +delete characters, then squeeze repeated characters from the result. +@end itemize + +The @var{set1} and (if given) @var{set2} arguments define ordered +sets of characters, referred to below as @var{set1} and @var{set2}. These +sets are the characters of the input that @command{tr} operates on. +The @option{--complement} (@option{-c}, @option{-C}) option replaces +@var{set1} with its +complement (all of the characters that are not in @var{set1}). + +Currently @command{tr} fully supports only single-byte characters. +Eventually it will support multibyte characters; when it does, the +@option{-C} option will cause it to complement the set of characters, +whereas @option{-c} will cause it to complement the set of values. +This distinction will matter only when some values are not characters, +and this is possible only in locales using multibyte encodings when +the input contains encoding errors. + +The program accepts the @option{--help} and @option{--version} +options. @xref{Common options}. Options must precede operands. + +@exitstatus + +@menu +* Character sets:: Specifying sets of characters. +* Translating:: Changing one set of characters to another. +* Squeezing:: Squeezing repeats and deleting. +@end menu + + +@node Character sets +@subsection Specifying sets of characters + +@cindex specifying sets of characters + +The format of the @var{set1} and @var{set2} arguments resembles +the format of regular expressions; however, they are not regular +expressions, only lists of characters. Most characters simply +represent themselves in these strings, but the strings can contain +the shorthands listed below, for convenience. Some of them can be +used only in @var{set1} or @var{set2}, as noted below. + +@table @asis + +@item Backslash escapes +@cindex backslash escapes + +The following backslash escape sequences are recognized: + +@table @samp +@item \a +Control-G. +@item \b +Control-H. +@item \f +Control-L. +@item \n +Control-J. +@item \r +Control-M. +@item \t +Control-I. +@item \v +Control-K. +@item \@var{ooo} +The character with the value given by @var{ooo}, which is 1 to 3 +octal digits, +@item \\ +A backslash. +@end table + +While a backslash followed by a character not listed above is +interpreted as that character, the backslash also effectively +removes any special significance, so it is useful to escape +@samp{[}, @samp{]}, @samp{*}, and @samp{-}. + +@item Ranges +@cindex ranges + +The notation @samp{@var{m}-@var{n}} expands to all of the characters +from @var{m} through @var{n}, in ascending order. @var{m} should +collate before @var{n}; if it doesn't, an error results. As an example, +@samp{0-9} is the same as @samp{0123456789}. + +@sc{gnu} @command{tr} does not support the System V syntax that uses square +brackets to enclose ranges. Translations specified in that format +sometimes work as expected, since the brackets are often transliterated +to themselves. However, they should be avoided because they sometimes +behave unexpectedly. For example, @samp{tr -d '[0-9]'} deletes brackets +as well as digits. + +Many historically common and even accepted uses of ranges are not +portable. For example, on @acronym{EBCDIC} hosts using the @samp{A-Z} +range will not do what most would expect because @samp{A} through @samp{Z} +are not contiguous as they are in @acronym{ASCII}. +If you can rely on a @acronym{POSIX} compliant version of @command{tr}, then +the best way to work around this is to use character classes (see below). +Otherwise, it is most portable (and most ugly) to enumerate the members +of the ranges. + +@item Repeated characters +@cindex repeated characters + +The notation @samp{[@var{c}*@var{n}]} in @var{set2} expands to @var{n} +copies of character @var{c}. Thus, @samp{[y*6]} is the same as +@samp{yyyyyy}. The notation @samp{[@var{c}*]} in @var{string2} expands +to as many copies of @var{c} as are needed to make @var{set2} as long as +@var{set1}. If @var{n} begins with @samp{0}, it is interpreted in +octal, otherwise in decimal. + +@item Character classes +@cindex character classes + +The notation @samp{[:@var{class}:]} expands to all of the characters in +the (predefined) class @var{class}. The characters expand in no +particular order, except for the @code{upper} and @code{lower} classes, +which expand in ascending order. When the @option{--delete} (@option{-d}) +and @option{--squeeze-repeats} (@option{-s}) options are both given, any +character class can be used in @var{set2}. Otherwise, only the +character classes @code{lower} and @code{upper} are accepted in +@var{set2}, and then only if the corresponding character class +(@code{upper} and @code{lower}, respectively) is specified in the same +relative position in @var{set1}. Doing this specifies case conversion. +The class names are given below; an error results when an invalid class +name is given. + +@table @code +@item alnum +@opindex alnum +Letters and digits. +@item alpha +@opindex alpha +Letters. +@item blank +@opindex blank +Horizontal whitespace. +@item cntrl +@opindex cntrl +Control characters. +@item digit +@opindex digit +Digits. +@item graph +@opindex graph +Printable characters, not including space. +@item lower +@opindex lower +Lowercase letters. +@item print +@opindex print +Printable characters, including space. +@item punct +@opindex punct +Punctuation characters. +@item space +@opindex space +Horizontal or vertical whitespace. +@item upper +@opindex upper +Uppercase letters. +@item xdigit +@opindex xdigit +Hexadecimal digits. +@end table + +@item Equivalence classes +@cindex equivalence classes + +The syntax @samp{[=@var{c}=]} expands to all of the characters that are +equivalent to @var{c}, in no particular order. Equivalence classes are +a relatively recent invention intended to support non-English alphabets. +But there seems to be no standard way to define them or determine their +contents. Therefore, they are not fully implemented in @sc{gnu} @command{tr}; +each character's equivalence class consists only of that character, +which is of no particular use. + +@end table + + +@node Translating +@subsection Translating + +@cindex translating characters + +@command{tr} performs translation when @var{set1} and @var{set2} are +both given and the @option{--delete} (@option{-d}) option is not given. +@command{tr} translates each character of its input that is in @var{set1} +to the corresponding character in @var{set2}. Characters not in +@var{set1} are passed through unchanged. When a character appears more +than once in @var{set1} and the corresponding characters in @var{set2} +are not all the same, only the final one is used. For example, these +two commands are equivalent: + +@example +tr aaa xyz +tr a z +@end example + +A common use of @command{tr} is to convert lowercase characters to +uppercase. This can be done in many ways. Here are three of them: + +@example +tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ +tr a-z A-Z +tr '[:lower:]' '[:upper:]' +@end example + +@noindent +But note that using ranges like @code{a-z} above is not portable. + +When @command{tr} is performing translation, @var{set1} and @var{set2} +typically have the same length. If @var{set1} is shorter than +@var{set2}, the extra characters at the end of @var{set2} are ignored. + +On the other hand, making @var{set1} longer than @var{set2} is not +portable; @acronym{POSIX} says that the result is undefined. In this situation, +BSD @command{tr} pads @var{set2} to the length of @var{set1} by repeating +the last character of @var{set2} as many times as necessary. System V +@command{tr} truncates @var{set1} to the length of @var{set2}. + +By default, @sc{gnu} @command{tr} handles this case like BSD @command{tr}. +When the @option{--truncate-set1} (@option{-t}) option is given, +@sc{gnu} @command{tr} handles this case like the System V @command{tr} +instead. This option is ignored for operations other than translation. + +Acting like System V @command{tr} in this case breaks the relatively common +BSD idiom: + +@example +tr -cs A-Za-z0-9 '\012' +@end example + +@noindent +because it converts only zero bytes (the first element in the +complement of @var{set1}), rather than all non-alphanumerics, to +newlines. + +@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: + +@example +tr -cs '[:alnum:]' '[\n*]' +@end example + + +@node Squeezing +@subsection Squeezing repeats and deleting + +@cindex squeezing repeat characters +@cindex deleting characters + +When given just the @option{--delete} (@option{-d}) option, @command{tr} +removes any input characters that are in @var{set1}. + +When given just the @option{--squeeze-repeats} (@option{-s}) option, +@command{tr} replaces each input sequence of a repeated character that +is in @var{set1} with a single occurrence of that character. + +When given both @option{--delete} and @option{--squeeze-repeats}, @command{tr} +first performs any deletions using @var{set1}, then squeezes repeats +from any remaining characters using @var{set2}. + +The @option{--squeeze-repeats} option may also be used when translating, +in which case @command{tr} first performs translation, then squeezes +repeats from any remaining characters using @var{set2}. + +Here are some examples to illustrate various combinations of options: + +@itemize @bullet + +@item +Remove all zero bytes: + +@example +tr -d '\0' +@end example + +@item +Put all words on lines by themselves. This converts all +non-alphanumeric characters to newlines, then squeezes each string +of repeated newlines into a single newline: + +@example +tr -cs '[:alnum:]' '[\n*]' +@end example + +@item +Convert each sequence of repeated newlines to a single newline: + +@example +tr -s '\n' +@end example + +@item +Find doubled occurrences of words in a document. +@c Separate the following two "the"s, so typo checkers don't complain. +For example, people often write ``the @w{}the'' with the repeated words +separated by a newline. The Bourne shell script below works first +by converting each sequence of punctuation and blank characters to a +single newline. That puts each ``word'' on a line by itself. +Next it maps all uppercase characters to lower case, and finally it +runs @command{uniq} with the @option{-d} option to print out only the words +that were repeated. + +@example +#!/bin/sh +cat -- "$@@" \ + | tr -s '[:punct:][:blank:]' '[\n*]' \ + | tr '[:upper:]' '[:lower:]' \ + | uniq -d +@end example + +@item +Deleting a small set of characters is usually straightforward. For example, +to remove all @samp{a}s, @samp{x}s, and @samp{M}s you would do this: + +@example +tr -d axM +@end example + +However, when @samp{-} is one of those characters, it can be tricky because +@samp{-} has special meanings. Performing the same task as above but also +removing all @samp{-} characters, we might try @code{tr -d -axM}, but +that would fail because @command{tr} would try to interpret @option{-a} as +a command-line option. Alternatively, we could try putting the hyphen +inside the string, @code{tr -d a-xM}, but that wouldn't work either because +it would make @command{tr} interpret @code{a-x} as the range of characters +@samp{a}@dots{}@samp{x} rather than the three. +One way to solve the problem is to put the hyphen at the end of the list +of characters: + +@example +tr -d axM- +@end example + +Or you can use @samp{--} to terminate option processing: + +@example +tr -d -- -axM +@end example + +More generally, use the character class notation @code{[=c=]} +with @samp{-} (or any other character) in place of the @samp{c}: + +@example +tr -d '[=-=]axM' +@end example + +Note how single quotes are used in the above example to protect the +square brackets from interpretation by a shell. + +@end itemize + + +@node expand invocation +@section @command{expand}: Convert tabs to spaces + +@pindex expand +@cindex tabs to spaces, converting +@cindex converting tabs to spaces + +@command{expand} writes the contents of each given @var{file}, or standard +input if none are given or for a @var{file} of @samp{-}, to standard +output, with tab characters converted to the appropriate number of +spaces. Synopsis: + +@example +expand [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +By default, @command{expand} converts all tabs to spaces. It preserves +backspace characters in the output; they decrement the column count for +tab calculations. The default action is equivalent to @option{-t 8} (set +tabs every 8 columns). + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -t @var{tab1}[,@var{tab2}]@dots{} +@itemx --tabs=@var{tab1}[,@var{tab2}]@dots{} +@opindex -t +@opindex --tabs +@cindex tab stops, setting +If only one tab stop is given, set the tabs @var{tab1} spaces apart +(default is 8). Otherwise, set the tabs at columns @var{tab1}, +@var{tab2}, @dots{} (numbered from 0), and replace any tabs beyond the +last tab stop given with single spaces. Tab stops can be separated by +blanks as well as by commas. + +For compatibility, GNU @command{expand} also accepts the obsolete +option syntax, @option{-@var{t1}[,@var{t2}]@dots{}}. New scripts +should use @option{-t @var{t1}[,@var{t2}]@dots{}} instead. + +@item -i +@itemx --initial +@opindex -i +@opindex --initial +@cindex initial tabs, converting +Only convert initial tabs (those that precede all non-space or non-tab +characters) on each line to spaces. + +@end table + +@exitstatus + + +@node unexpand invocation +@section @command{unexpand}: Convert spaces to tabs + +@pindex unexpand + +@command{unexpand} writes the contents of each given @var{file}, or +standard input if none are given or for a @var{file} of @samp{-}, to +standard output, converting blanks at the beginning of each line into +as many tab characters as needed. In the default @acronym{POSIX} +locale, a @dfn{blank} is a space or a tab; other locales may specify +additional blank characters. Synopsis: + +@example +unexpand [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +By default, @command{unexpand} converts only initial blanks (those +that precede all non-blank characters) on each line. It +preserves backspace characters in the output; they decrement the column +count for tab calculations. By default, tabs are set at every 8th +column. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -t @var{tab1}[,@var{tab2}]@dots{} +@itemx --tabs=@var{tab1}[,@var{tab2}]@dots{} +@opindex -t +@opindex --tabs +If only one tab stop is given, set the tabs @var{tab1} columns apart +instead of the default 8. Otherwise, set the tabs at columns +@var{tab1}, @var{tab2}, @dots{} (numbered from 0), and leave blanks +beyond the tab stops given unchanged. Tab stops can be separated by +blanks as well as by commas. This option implies the @option{-a} option. + +For compatibility, GNU @command{unexpand} supports the obsolete option syntax, +@option{-@var{tab1}[,@var{tab2}]@dots{}}, where tab stops must be +separated by commas. (Unlike @option{-t}, this obsolete option does +not imply @option{-a}.) New scripts should use @option{--first-only -t +@var{tab1}[,@var{tab2}]@dots{}} instead. + +@item -a +@itemx --all +@opindex -a +@opindex --all +Also convert all sequences of two or more blanks just before a tab stop, +even if they occur after non-blank characters in a line. + +@end table + +@exitstatus + + +@node Directory listing +@chapter Directory listing + +This chapter describes the @command{ls} command and its variants @command{dir} +and @command{vdir}, which list information about files. + +@menu +* ls invocation:: List directory contents. +* dir invocation:: Briefly ls. +* vdir invocation:: Verbosely ls. +* dircolors invocation:: Color setup for ls, etc. +@end menu + + +@node ls invocation +@section @command{ls}: List directory contents + +@pindex ls +@cindex directory listing + +The @command{ls} program lists information about files (of any type, +including directories). Options and file arguments can be intermixed +arbitrarily, as usual. + +For non-option command-line arguments that are directories, by default +@command{ls} lists the contents of directories, not recursively, and +omitting files with names beginning with @samp{.}. For other non-option +arguments, by default @command{ls} lists just the file name. If no +non-option argument is specified, @command{ls} operates on the current +directory, acting as if it had been invoked with a single argument of @samp{.}. + +@vindex LC_ALL +By default, the output is sorted alphabetically, according to the locale +settings in effect.@footnote{If you use a non-@acronym{POSIX} +locale (e.g., by setting @env{LC_ALL} to @samp{en_US}), then @command{ls} may +produce output that is sorted differently than you're accustomed to. +In that case, set the @env{LC_ALL} environment variable to @samp{C}.} +If standard output is +a terminal, the output is in columns (sorted vertically) and control +characters are output as question marks; otherwise, the output is listed +one per line and control characters are output as-is. + +Because @command{ls} is such a fundamental program, it has accumulated many +options over the years. They are described in the subsections below; +within each section, options are listed alphabetically (ignoring case). +The division of options into the subsections is not absolute, since some +options affect more than one aspect of @command{ls}'s operation. + +@cindex exit status of @command{ls} +Exit status: + +@display +0 success +1 minor problems (e.g., a subdirectory was not found) +2 serious trouble (e.g., memory exhausted) +@end display + +Also see @ref{Common options}. + +@menu +* Which files are listed:: +* What information is listed:: +* Sorting the output:: +* More details about version sort:: +* General output formatting:: +* Formatting file timestamps:: +* Formatting the file names:: +@end menu + + +@node Which files are listed +@subsection Which files are listed + +These options determine which files @command{ls} lists information for. +By default, @command{ls} lists files and the contents of any +directories on the command line, except that in directories it ignores +files whose names start with @samp{.}. + +@table @samp + +@item -a +@itemx --all +@opindex -a +@opindex --all +In directories, do not ignore file names that start with @samp{.}. + +@item -A +@itemx --almost-all +@opindex -A +@opindex --almost-all +In directories, do not ignore all file names that start with @samp{.}; +ignore only @file{.} and @file{..}. The @option{--all} (@option{-a}) +option overrides this option. + +@item -B +@itemx --ignore-backups +@opindex -B +@opindex --ignore-backups +@cindex backup files, ignoring +In directories, ignore files that end with @samp{~}. This option is +equivalent to @samp{--ignore='*~' --ignore='.*~'}. + +@item -d +@itemx --directory +@opindex -d +@opindex --directory +List just the names of directories, as with other types of files, rather +than listing their contents. +@c The following sentence is the same as the one for -F. +Do not follow symbolic links listed on the +command line unless the @option{--dereference-command-line} (@option{-H}), +@option{--dereference} (@option{-L}), or +@option{--dereference-command-line-symlink-to-dir} options are specified. + +@item -H +@itemx --dereference-command-line +@opindex -H +@opindex --dereference-command-line +@cindex symbolic links, dereferencing +If a command line argument specifies a symbolic link, show information +for the file the link references rather than for the link itself. + +@itemx --dereference-command-line-symlink-to-dir +@opindex --dereference-command-line-symlink-to-dir +@cindex symbolic links, dereferencing +Do not dereference symbolic links, with one exception: +if a command line argument specifies a symbolic link that refers to +a directory, show information for that directory rather than for the +link itself. +This is the default behavior when no other dereferencing-related +option has been specified (@option{--classify} (@option{-F}), +@option{--directory} (@option{-d}), +(@option{-l}), +@option{--dereference} (@option{-L}), or +@option{--dereference-command-line} (@option{-H})). + +@item --group-directories-first +@opindex --group-directories-first +Group all the directories before the files and then sort the +directories and the files separately using the selected sort key +(see --sort option). +That is, this option specifies a primary sort key, +and the --sort option specifies a secondary key. + +@item --hide=PATTERN +@opindex --hide=@var{pattern} +In directories, ignore files whose names match the shell pattern +@var{pattern}, unless the @option{--all} (@option{-a}) or +@option{--almost-all} (@option{-A}) is also given. This +option acts like @option{--ignore=@var{pattern}} except that it has no +effect if @option{--all} (@option{-a}) or @option{--almost-all} +(@option{-A}) is also given. + +This option can be useful in shell aliases. For example, if +@command{lx} is an alias for @samp{ls --hide='*~'} and @command{ly} is +an alias for @samp{ls --ignore='*~'}, then the command @samp{lx -A} +lists the file @file{README~} even though @samp{ly -A} would not. + +@item -I @var{pattern} +@itemx --ignore=@var{pattern} +@opindex -I +@opindex --ignore=@var{pattern} +In directories, ignore files whose names match the shell pattern +(not regular expression) @var{pattern}. As +in the shell, an initial @samp{.} in a file name does not match a +wildcard at the start of @var{pattern}. Sometimes it is useful +to give this option several times. For example, + +@smallexample +$ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*' +@end smallexample + +The first option ignores names of length 3 or more that start with @samp{.}, +the second ignores all two-character names that start with @samp{.} +except @samp{..}, and the third ignores names that start with @samp{#}. + +@item -L +@itemx --dereference +@opindex -L +@opindex --dereference +@cindex symbolic links, dereferencing +When showing file information for a symbolic link, show information +for the file the link references rather than the link itself. +However, even with this option, @command{ls} still prints the name +of the link itself, not the name of the file that the link points to. + +@item -R +@itemx --recursive +@opindex -R +@opindex --recursive +@cindex recursive directory listing +@cindex directory listing, recursive +List the contents of all directories recursively. + +@end table + + +@node What information is listed +@subsection What information is listed + +These options affect the information that @command{ls} displays. By +default, only file names are shown. + +@table @samp + +@item --author +@opindex --author +@cindex hurd, author, printing +List each file's author when producing long format directory listings. +In GNU/Hurd, file authors can differ from their owners, but in other +operating systems the two are the same. + +@item -D +@itemx --dired +@opindex -D +@opindex --dired +@cindex dired Emacs mode support +With the long listing (@option{-l}) format, print an additional line after +the main output: + +@example +//DIRED// @var{beg1} @var{end1} @var{beg2} @var{end2} @dots{} +@end example + +@noindent +The @var{begN} and @var{endN} are unsigned integers that record the +byte position of the beginning and end of each file name in the output. +This makes it easy for Emacs to find the names, even when they contain +unusual characters such as space or newline, without fancy searching. + +If directories are being listed recursively (@option{-R}), output a similar +line with offsets for each subdirectory name: + +@example +//SUBDIRED// @var{beg1} @var{end1} @dots{} +@end example + +Finally, output a line of the form: + +@example +//DIRED-OPTIONS// --quoting-style=@var{word} +@end example + +@noindent +where @var{word} is the quoting style (@pxref{Formatting the file names}). + +Here is an actual example: + +@example +$ mkdir -p a/sub/deeper a/sub2 +$ touch a/f1 a/f2 +$ touch a/sub/deeper/file +$ ls -gloRF --dired a + a: + total 8 + -rw-r--r-- 1 0 Jun 10 12:27 f1 + -rw-r--r-- 1 0 Jun 10 12:27 f2 + drwxr-xr-x 3 4096 Jun 10 12:27 sub/ + drwxr-xr-x 2 4096 Jun 10 12:27 sub2/ + + a/sub: + total 4 + drwxr-xr-x 2 4096 Jun 10 12:27 deeper/ + + a/sub/deeper: + total 0 + -rw-r--r-- 1 0 Jun 10 12:27 file + + a/sub2: + total 0 +//DIRED// 48 50 84 86 120 123 158 162 217 223 282 286 +//SUBDIRED// 2 3 167 172 228 240 290 296 +//DIRED-OPTIONS// --quoting-style=literal +@end example + +Note that the pairs of offsets on the @samp{//DIRED//} line above delimit +these names: @file{f1}, @file{f2}, @file{sub}, @file{sub2}, @file{deeper}, +@file{file}. +The offsets on the @samp{//SUBDIRED//} line delimit the following +directory names: @file{a}, @file{a/sub}, @file{a/sub/deeper}, @file{a/sub2}. + +Here is an example of how to extract the fifth entry name, @samp{deeper}, +corresponding to the pair of offsets, 222 and 228: + +@example +$ ls -gloRF --dired a > out +$ dd bs=1 skip=222 count=6 < out 2>/dev/null; echo +deeper +@end example + +Note that although the listing above includes a trailing slash +for the @samp{deeper} entry, the offsets select the name without +the trailing slash. However, if you invoke @command{ls} with @option{--dired} +along with an option like @option{--escape} (aka @option{-b}) and operate +on a file whose name contains special characters, notice that the backslash +@emph{is} included: + +@example +$ touch 'a b' +$ ls -blog --dired 'a b' + -rw-r--r-- 1 0 Jun 10 12:28 a\ b +//DIRED// 30 34 +//DIRED-OPTIONS// --quoting-style=escape +@end example + +If you use a quoting style that adds quote marks +(e.g., @option{--quoting-style=c}), then the offsets include the quote marks. +So beware that the user may select the quoting style via the environment +variable @env{QUOTING_STYLE}. Hence, applications using @option{--dired} +should either specify an explicit @option{--quoting-style=literal} option +(aka @option{-N} or @option{--literal}) on the command line, or else be +prepared to parse the escaped names. + +@item --full-time +@opindex --full-time +Produce long format directory listings, and list times in full. It is +equivalent to using @option{--format=long} with +@option{--time-style=full-iso} (@pxref{Formatting file timestamps}). + +@item -g +@opindex -g +Produce long format directory listings, but don't display owner information. + +@item -G +@itemx --no-group +@opindex -G +@opindex --no-group +Inhibit display of group information in a long format directory listing. +(This is the default in some non-@sc{gnu} versions of @command{ls}, so we +provide this option for compatibility.) + +@optHumanReadable + +@item -i +@itemx --inode +@opindex -i +@opindex --inode +@cindex inode number, printing +Print the inode number (also called the file serial number and index +number) of each file to the left of the file name. (This number +uniquely identifies each file within a particular file system.) + +@item -l +@itemx --format=long +@itemx --format=verbose +@opindex -l +@opindex --format +@opindex long ls @r{format} +@opindex verbose ls @r{format} +In addition to the name of each file, print the file type, file mode bits, +number of hard links, owner name, group name, size, and +timestamp (@pxref{Formatting file timestamps}), normally +the modification time. Print question marks for information that +cannot be determined. + +Normally the size is printed as a byte count without punctuation, but +this can be overridden (@pxref{Block size}). For example, @option{-h} +prints an abbreviated, human-readable count, and +@samp{--block-size="'1"} prints a byte count with the thousands +separator of the current locale. + +For each directory that is listed, preface the files with a line +@samp{total @var{blocks}}, where @var{blocks} is the total disk allocation +for all files in that directory. The block size currently defaults to 1024 +bytes, but this can be overridden (@pxref{Block size}). +The @var{blocks} computed counts each hard link separately; +this is arguably a deficiency. + +The file type is one of the following characters: + +@c The commented-out entries are ones we're not sure about. + +@table @samp +@item - +regular file +@item b +block special file +@item c +character special file +@item C +high performance (``contiguous data'') file +@item d +directory +@item D +door (Solaris 2.5 and up) +@c @item F +@c semaphore, if this is a distinct file type +@item l +symbolic link +@c @item m +@c multiplexed file (7th edition Unix; obsolete) +@item M +off-line (``migrated'') file (Cray DMF) +@item n +network special file (HP-UX) +@item p +FIFO (named pipe) +@item P +port (Solaris 10 and up) +@c @item Q +@c message queue, if this is a distinct file type +@item s +socket +@c @item S +@c shared memory object, if this is a distinct file type +@c @item T +@c typed memory object, if this is a distinct file type +@c @item w +@c whiteout (4.4BSD; not implemented) +@item ? +some other file type +@end table + +@cindex permissions, output by @command{ls} +The file mode bits listed are similar to symbolic mode specifications +(@pxref{Symbolic Modes}). But @command{ls} combines multiple bits into the +third character of each set of permissions as follows: + +@table @samp +@item s +If the set-user-ID or set-group-ID bit and the corresponding executable bit +are both set. + +@item S +If the set-user-ID or set-group-ID bit is set but the corresponding +executable bit is not set. + +@item t +If the restricted deletion flag or sticky bit, and the +other-executable bit, are both set. The restricted deletion flag is +another name for the sticky bit. @xref{Mode Structure}. + +@item T +If the restricted deletion flag or sticky bit is set but the +other-executable bit is not set. + +@item x +If the executable bit is set and none of the above apply. + +@item - +Otherwise. +@end table + +Following the file mode bits is a single character that specifies +whether an alternate access method such as an access control list +applies to the file. When the character following the file mode bits is a +space, there is no alternate access method. When it is a printing +character, then there is such a method. + +For a file with an extended access control list, a @samp{+} character is +listed. Basic access control lists are equivalent to the permissions +listed, and are not considered an alternate access method. + +@item -n +@itemx --numeric-uid-gid +@opindex -n +@opindex --numeric-uid-gid +@cindex numeric uid and gid +@cindex numeric user and group IDs +Produce long format directory listings, but +display numeric user and group IDs instead of the owner and group names. + +@item -o +@opindex -o +Produce long format directory listings, but don't display group information. +It is equivalent to using @option{--format=long} with @option{--no-group} . + +@item -s +@itemx --size +@opindex -s +@opindex --size +@cindex disk allocation +@cindex size of files, reporting +Print the disk allocation of each file to the left of the file name. +This is the amount of disk space used by the file, which is usually a +bit more than the file's size, but it can be less if the file has holes. + +Normally the disk allocation is printed in units of +1024 bytes, but this can be overridden (@pxref{Block size}). + +@cindex NFS mounts from BSD to HP-UX +For files that are NFS-mounted from an HP-UX system to a BSD system, +this option reports sizes that are half the correct values. On HP-UX +systems, it reports sizes that are twice the correct values for files +that are NFS-mounted from BSD systems. This is due to a flaw in HP-UX; +it also affects the HP-UX @command{ls} program. + +@optSi + +@end table + + +@node Sorting the output +@subsection Sorting the output + +@cindex sorting @command{ls} output +These options change the order in which @command{ls} sorts the information +it outputs. By default, sorting is done by character code +(e.g., @acronym{ASCII} order). + +@table @samp + +@item -c +@itemx --time=ctime +@itemx --time=status +@opindex -c +@opindex --time +@opindex ctime@r{, printing or sorting by} +@opindex status time@r{, printing or sorting by} +@opindex use time@r{, printing or sorting files by} +If the long listing format (e.g., @option{-l}, @option{-o}) is being used, +print the status change time (the @samp{ctime} in the inode) instead of +the modification time. +When explicitly sorting by time (@option{--sort=time} or @option{-t}) +or when not using a long listing format, +sort according to the status change time. + +@item -f +@opindex -f +@cindex unsorted directory listing +@cindex directory order, listing by +Primarily, like @option{-U}---do not sort; list the files in whatever +order they are stored in the directory. But also enable @option{-a} (list +all files) and disable @option{-l}, @option{--color}, and @option{-s} (if they +were specified before the @option{-f}). + +@item -r +@itemx --reverse +@opindex -r +@opindex --reverse +@cindex reverse sorting +Reverse whatever the sorting method is---e.g., list files in reverse +alphabetical order, youngest first, smallest first, or whatever. + +@item -S +@itemx --sort=size +@opindex -S +@opindex --sort +@opindex size of files@r{, sorting files by} +Sort by file size, largest first. + +@item -t +@itemx --sort=time +@opindex -t +@opindex --sort +@opindex modification time@r{, sorting files by} +Sort by modification time (the @samp{mtime} in the inode), newest first. + +@item -u +@itemx --time=atime +@itemx --time=access +@itemx --time=use +@opindex -u +@opindex --time +@opindex use time@r{, printing or sorting files by} +@opindex atime@r{, printing or sorting files by} +@opindex access time@r{, printing or sorting files by} +If the long listing format (e.g., @option{--format=long}) is being used, +print the last access time (the @samp{atime} in the inode). +When explicitly sorting by time (@option{--sort=time} or @option{-t}) +or when not using a long listing format, sort according to the access time. + +@item -U +@itemx --sort=none +@opindex -U +@opindex --sort +@opindex none@r{, sorting option for @command{ls}} +Do not sort; list the files in whatever order they are +stored in the directory. (Do not do any of the other unrelated things +that @option{-f} does.) This is especially useful when listing very large +directories, since not doing any sorting can be noticeably faster. + +@item -v +@itemx --sort=version +@opindex -v +@opindex --sort +@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}.) + +@item -X +@itemx --sort=extension +@opindex -X +@opindex --sort +@opindex extension@r{, sorting files by} +Sort directory contents alphabetically by file extension (characters +after the last @samp{.}); files with no extension are sorted first. + +@end table + + +@node More details about version sort +@subsection More 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: + +@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 +@end example + +Note also that numeric parts with leading zeros are considered as +fractional one: + +@example +$ ls -1 $ ls -1v +abc-1.007.tgz abc-1.007.tgz +abc-1.012b.tgz abc-1.01a.tgz +abc-1.01a.tgz abc-1.012b.tgz +@end example + +This functionality is implemented using the @code{strverscmp} function. +@xref{String/Array Comparison, , , libc, The GNU C Library Reference Manual}. +One result of that implementation decision is that @code{ls -v} does not +use the locale category, @env{LC_COLLATE}. As a result, non-numeric prefixes +are sorted as if @env{LC_COLLATE} were set to @code{C}. + +@node General output formatting +@subsection General output formatting + +These options affect the appearance of the overall output. + +@table @samp + +@item -1 +@itemx --format=single-column +@opindex -1 +@opindex --format +@opindex single-column @r{output of files} +List one file per line. This is the default for @command{ls} when standard +output is not a terminal. + +@item -C +@itemx --format=vertical +@opindex -C +@opindex --format +@opindex vertical @r{sorted files in columns} +List files in columns, sorted vertically. This is the default for +@command{ls} if standard output is a terminal. It is always the default +for the @command{dir} program. +@sc{gnu} @command{ls} uses variable width columns to display as many files as +possible in the fewest lines. + +@item --color [=@var{when}] +@opindex --color +@cindex color, distinguishing file types with +Specify whether to use color for distinguishing file types. @var{when} +may be omitted, or one of: +@itemize @bullet +@item none +@vindex none @r{color option} +- Do not use color at all. This is the default. +@item auto +@vindex auto @r{color option} +@cindex terminal, using color iff +- Only use color if standard output is a terminal. +@item always +@vindex always @r{color option} +- Always use color. +@end itemize +Specifying @option{--color} and no @var{when} is equivalent to +@option{--color=always}. +Piping a colorized listing through a pager like @command{more} or +@command{less} usually produces unreadable results. However, using +@code{more -f} does seem to work. + +@item -F +@itemx --classify +@itemx --indicator-style=classify +@opindex -F +@opindex --classify +@opindex --indicator-style +@cindex file type and executables, marking +@cindex executables and file type, marking +Append a character to each file name indicating the file type. Also, +for regular files that are executable, append @samp{*}. The file type +indicators are @samp{/} for directories, @samp{@@} for symbolic links, +@samp{|} for FIFOs, @samp{=} for sockets, @samp{>} for doors, +and nothing for regular files. +@c The following sentence is the same as the one for -d. +Do not follow symbolic links listed on the +command line unless the @option{--dereference-command-line} (@option{-H}), +@option{--dereference} (@option{-L}), or +@option{--dereference-command-line-symlink-to-dir} options are specified. + +@item --file-type +@itemx --indicator-style=file-type +@opindex --file-type +@opindex --indicator-style +@cindex file type, marking +Append a character to each file name indicating the file type. This is +like @option{-F}, except that executables are not marked. + +@item --indicator-style=@var{word} +@opindex --indicator-style +Append a character indicator with style @var{word} to entry names, +as follows: + +@table @samp +@item none +Do not append any character indicator; this is the default. +@item slash +Append @samp{/} for directories. This is the same as the @option{-p} +option. +@item file-type +Append @samp{/} for directories, @samp{@@} for symbolic links, @samp{|} +for FIFOs, @samp{=} for sockets, and nothing for regular files. This is +the same as the @option{--file-type} option. +@item classify +Append @samp{*} for executable regular files, otherwise behave as for +@samp{file-type}. This is the same as the @option{-F} or +@option{--classify} option. +@end table + +@item -k +@opindex -k +Print file sizes in 1024-byte blocks, overriding the default block +size (@pxref{Block size}). +This option is equivalent to @option{--block-size=1K}. + +@item -m +@itemx --format=commas +@opindex -m +@opindex --format +@opindex commas@r{, outputting between files} +List files horizontally, with as many as will fit on each line, +separated by @samp{, } (a comma and a space). + +@item -p +@itemx --indicator-style=slash +@opindex -p +@opindex --indicator-style +@cindex file type, marking +Append a @samp{/} to directory names. + +@item -x +@itemx --format=across +@itemx --format=horizontal +@opindex -x +@opindex --format +@opindex across@r{, listing files} +@opindex horizontal@r{, listing files} +List the files in columns, sorted horizontally. + +@item -T @var{cols} +@itemx --tabsize=@var{cols} +@opindex -T +@opindex --tabsize +Assume that each tab stop is @var{cols} columns wide. The default is 8. +@command{ls} uses tabs where possible in the output, for efficiency. If +@var{cols} is zero, do not use tabs at all. + +@c FIXME: remove in 2009, if Apple Terminal has been fixed for long enough. +Some terminal emulators (at least Apple Terminal 1.5 (133) from Mac OS X 10.4.8) +do not properly align columns to the right of a TAB following a +non-@acronym{ASCII} byte. If you use such a terminal emulator, use the +@option{-T0} option or put @code{TABSIZE=0} in your environment to tell +@command{ls} to align using spaces, not tabs. + +@item -w +@itemx --width=@var{cols} +@opindex -w +@opindex --width +@vindex COLUMNS +Assume the screen is @var{cols} columns wide. The default is taken +from the terminal settings if possible; otherwise the environment +variable @env{COLUMNS} is used if it is set; otherwise the default +is 80. + +@end table + + +@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. + +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 +today is not listed in recent form, the timestamp is in the future, +which means you probably have clock skew problems which may break +programs like @command{make} that rely on file timestamps. + +@vindex TZ +Time stamps are listed according to the time zone rules specified by +the @env{TZ} environment variable, or by the system default rules if +@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone +with @env{TZ}, libc, The GNU C Library}. + +The following option changes how file timestamps are printed. + +@table @samp +@item --time-style=@var{style} +@opindex --time-style +@cindex time style +List timestamps in style @var{style}. The @var{style} should +be one of the following: + +@table @samp +@item +@var{format} +@vindex LC_TIME +List timestamps using @var{format}, where @var{format} is interpreted +like the format argument of @command{date} (@pxref{date invocation}). +For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes +@command{ls} to list timestamps like @samp{2002-03-30 23:45:56}. As +with @command{date}, @var{format}'s interpretation is affected by the +@env{LC_TIME} locale category. + +If @var{format} contains two format strings separated by a newline, +the former is used for non-recent files and the latter for recent +files; if you want output columns to line up, you may need to insert +spaces in one of the two formats. + +@item full-iso +List timestamps in full using @acronym{ISO} 8601 date, time, and time zone +format with nanosecond precision, e.g., @samp{2002-03-30 +23:45:56.477817180 -0700}. This style is equivalent to +@samp{+%Y-%m-%d %H:%M:%S.%N %z}. + +This is useful because the time output includes all the information that +is available from the operating system. For example, this can help +explain @command{make}'s behavior, since @acronym{GNU} @command{make} +uses the full timestamp to determine whether a file is out of date. + +@item long-iso +List @acronym{ISO} 8601 date and time in minutes, e.g., +@samp{2002-03-30 23:45}. These timestamps are shorter than +@samp{full-iso} timestamps, and are usually good enough for everyday +work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}. + +@item iso +List @acronym{ISO} 8601 dates for non-recent timestamps (e.g., +@samp{2002-03-30@ }), and @acronym{ISO} 8601 month, day, hour, and +minute for recent timestamps (e.g., @samp{03-30 23:45}). These +timestamps are uglier than @samp{long-iso} timestamps, but they carry +nearly the same information in a smaller space and their brevity helps +@command{ls} output fit within traditional 80-column output lines. +The following two @command{ls} invocations are equivalent: + +@example +newline=' +' +ls -l --time-style="+%Y-%m-%d $newline%m-%d %H:%M" +ls -l --time-style="iso" +@end example + +@item locale +@vindex LC_TIME +List timestamps in a locale-dependent form. For example, a Finnish +locale might list non-recent timestamps like @samp{maalis 30@ @ 2002} +and recent timestamps like @samp{maalis 30 23:45}. Locale-dependent +timestamps typically consume more space than @samp{iso} timestamps and +are harder for programs to parse because locale conventions vary so +widely, but they are easier for many people to read. + +The @env{LC_TIME} locale category specifies the timestamp format. The +default @acronym{POSIX} locale uses timestamps like @samp{Mar 30@ +@ 2002} and @samp{Mar 30 23:45}; in this locale, the following two +@command{ls} invocations are equivalent: + +@example +newline=' +' +ls -l --time-style="+%b %e %Y$newline%b %e %H:%M" +ls -l --time-style="locale" +@end example + +Other locales behave differently. For example, in a German locale, +@option{--time-style="locale"} might be equivalent to +@option{--time-style="+%e. %b %Y $newline%e. %b %H:%M"} +and might generate timestamps like @samp{30. M@"ar 2002@ } and +@samp{30. M@"ar 23:45}. + +@item posix-@var{style} +@vindex LC_TIME +List @acronym{POSIX}-locale timestamps if the @env{LC_TIME} locale +category is @acronym{POSIX}, @var{style} timestamps otherwise. For +example, the @samp{posix-long-iso} style lists +timestamps like @samp{Mar 30@ @ 2002} and @samp{Mar 30 23:45} when in +the @acronym{POSIX} locale, and like @samp{2002-03-30 23:45} otherwise. +@end table +@end table + +@vindex TIME_STYLE +You can specify the default value of the @option{--time-style} option +with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set +the default style is @samp{locale}. @acronym{GNU} Emacs 21.3 and +later use the @option{--dired} option and therefore can parse any date +format, but if you are using Emacs 21.1 or 21.2 and specify a +non-@acronym{POSIX} locale you may need to set +@samp{TIME_STYLE="posix-long-iso"}. + +To avoid certain denial-of-service attacks, timestamps that would be +longer than 1000 bytes may be treated as errors. + + +@node Formatting the file names +@subsection Formatting the file names + +These options change how file names themselves are printed. + +@table @samp + +@item -b +@itemx --escape +@itemx --quoting-style=escape +@opindex -b +@opindex --escape +@opindex --quoting-style +@cindex backslash sequences for file names +Quote nongraphic characters in file names using alphabetic and octal +backslash sequences like those used in C. + +@item -N +@itemx --literal +@itemx --quoting-style=literal +@opindex -N +@opindex --literal +@opindex --quoting-style +Do not quote file names. However, with @command{ls} nongraphic +characters are still printed as question marks if the output is a +terminal and you do not specify the @option{--show-control-chars} +option. + +@item -q +@itemx --hide-control-chars +@opindex -q +@opindex --hide-control-chars +Print question marks instead of nongraphic characters in file names. +This is the default if the output is a terminal and the program is +@command{ls}. + +@item -Q +@itemx --quote-name +@itemx --quoting-style=c +@opindex -Q +@opindex --quote-name +@opindex --quoting-style +Enclose file names in double quotes and quote nongraphic characters as +in C. + +@item --quoting-style=@var{word} +@opindex --quoting-style +@cindex quoting style +Use style @var{word} to quote file names and other strings that may +contain arbitrary characters. The @var{word} should +be one of the following: + +@table @samp +@item literal +Output strings as-is; this is the same as the @option{-N} or +@option{--literal} option. +@item shell +Quote strings for the shell if they contain shell metacharacters or would +cause ambiguous output. +The quoting is suitable for @acronym{POSIX}-compatible shells like +@command{bash}, but it does not always work for incompatible shells +like @command{csh}. +@item shell-always +Quote strings for the shell, even if they would normally not require quoting. +@item c +Quote strings as for C character string literals, including the +surrounding double-quote characters; this is the same as the +@option{-Q} or @option{--quote-name} option. +@item escape +Quote strings as for C character string literals, except omit the +surrounding double-quote +characters; this is the same as the @option{-b} or @option{--escape} option. +@item clocale +Quote strings as for C character string literals, except use +surrounding quotation marks appropriate for the +locale. +@item locale +@c Use @t instead of @samp to avoid duplicate quoting in some output styles. +Quote strings as for C character string literals, except use +surrounding quotation marks appropriate for the locale, and quote +@t{`like this'} instead of @t{"like +this"} in the default C locale. This looks nicer on many displays. +@end table + +You can specify the default value of the @option{--quoting-style} option +with the environment variable @env{QUOTING_STYLE}. If that environment +variable is not set, the default value is @samp{literal}, but this +default may change to @samp{shell} in a future version of this package. + +@item --show-control-chars +@opindex --show-control-chars +Print nongraphic characters as-is in file names. +This is the default unless the output is a terminal and the program is +@command{ls}. + +@end table + + +@node dir invocation +@section @command{dir}: Briefly list directory contents + +@pindex dir +@cindex directory listing, brief + +@command{dir} is equivalent to @code{ls -C +-b}; that is, by default files are listed in columns, sorted vertically, +and special characters are represented by backslash escape sequences. + +@xref{ls invocation, @command{ls}}. + + +@node vdir invocation +@section @command{vdir}: Verbosely list directory contents + +@pindex vdir +@cindex directory listing, verbose + +@command{vdir} is equivalent to @code{ls -l +-b}; that is, by default files are listed in long format and special +characters are represented by backslash escape sequences. + +@node dircolors invocation +@section @command{dircolors}: Color setup for @command{ls} + +@pindex dircolors +@cindex color setup +@cindex setup for color + +@command{dircolors} outputs a sequence of shell commands to set up the +terminal for color output from @command{ls} (and @command{dir}, etc.). +Typical usage: + +@example +eval "`dircolors [@var{option}]@dots{} [@var{file}]`" +@end example + +If @var{file} is specified, @command{dircolors} reads it to determine which +colors to use for which file types and extensions. Otherwise, a +precompiled database is used. For details on the format of these files, +run @samp{dircolors --print-database}. + +@vindex LS_COLORS +@vindex SHELL @r{environment variable, and color} +The output is a shell command to set the @env{LS_COLORS} environment +variable. You can specify the shell syntax to use on the command line, +or @command{dircolors} will guess it from the value of the @env{SHELL} +environment variable. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp +@item -b +@itemx --sh +@itemx --bourne-shell +@opindex -b +@opindex --sh +@opindex --bourne-shell +@cindex Bourne shell syntax for color setup +@cindex @command{sh} syntax for color setup +Output Bourne shell commands. This is the default if the @env{SHELL} +environment variable is set and does not end with @samp{csh} or +@samp{tcsh}. + +@item -c +@itemx --csh +@itemx --c-shell +@opindex -c +@opindex --csh +@opindex --c-shell +@cindex C shell syntax for color setup +@cindex @command{csh} syntax for color setup +Output C shell commands. This is the default if @code{SHELL} ends with +@command{csh} or @command{tcsh}. + +@item -p +@itemx --print-database +@opindex -p +@opindex --print-database +@cindex color database, printing +@cindex database for color setup, printing +@cindex printing color database +Print the (compiled-in) default color configuration database. This +output is itself a valid configuration file, and is fairly descriptive +of the possibilities. + +@end table + +@exitstatus + + +@node Basic operations +@chapter Basic operations + +@cindex manipulating files + +This chapter describes the commands for basic file manipulation: +copying, moving (renaming), and deleting (removing). + +@menu +* cp invocation:: Copy files. +* 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. +@end menu + + +@node cp invocation +@section @command{cp}: Copy files and directories + +@pindex cp +@cindex copying files and directories +@cindex files, copying +@cindex directories, copying + +@command{cp} copies files (or, optionally, directories). The copy is +completely independent of the original. You can either copy one file to +another, or copy arbitrarily many files to a destination directory. +Synopses: + +@example +cp [@var{option}]@dots{} [-T] @var{source} @var{dest} +cp [@var{option}]@dots{} @var{source}@dots{} @var{directory} +cp [@var{option}]@dots{} -t @var{directory} @var{source}@dots{} +@end example + +@itemize @bullet +@item +If two file names are given, @command{cp} copies the first file to the +second. + +@item +If the @option{--target-directory} (@option{-t}) option is given, or +failing that if the last file is a directory and the +@option{--no-target-directory} (@option{-T}) option is not given, +@command{cp} copies each @var{source} file to the specified directory, +using the @var{source}s' names. +@end itemize + +Generally, files are written just as they are read. For exceptions, +see the @option{--sparse} option below. + +By default, @command{cp} does not copy directories. However, the +@option{-R}, @option{-a}, and @option{-r} options cause @command{cp} to +copy recursively by descending into source directories and copying files +to corresponding destination directories. + +By default, @command{cp} follows symbolic links only when not copying +recursively. This default can be overridden with the +@option{--archive} (@option{-a}), @option{-d}, @option{--dereference} +(@option{-L}), @option{--no-dereference} (@option{-P}), and +@option{-H} options. If more than one of these options is specified, +the last one silently overrides the others. + +By default, @command{cp} copies the contents of special files only +when not copying recursively. This default can be overridden with the +@option{--copy-contents} option. + +@cindex self-backups +@cindex backups, making only +@command{cp} generally refuses to copy a file onto itself, with the +following exception: if @option{--force --backup} is specified with +@var{source} and @var{dest} identical, and referring to a regular file, +@command{cp} will make a backup file, either regular or numbered, as +specified in the usual ways (@pxref{Backup options}). This is useful when +you simply want to make a backup of an existing file before changing it. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp +@item -a +@itemx --archive +@opindex -a +@opindex --archive +Preserve as much as possible of the structure and attributes of the +original files in the copy (but do not attempt to preserve internal +directory structure; i.e., @samp{ls -U} may list the entries in a copied +directory in a different order). +Equivalent to @option{-dpPR}. + +@item -b +@itemx @w{@kbd{--backup}[=@var{method}]} +@opindex -b +@opindex --backup +@vindex VERSION_CONTROL +@cindex backups, making +@xref{Backup options}. +Make a backup of each file that would otherwise be overwritten or removed. +As a special case, @command{cp} makes a backup of @var{source} when the force +and backup options are given and @var{source} and @var{dest} are the same +name for an existing, regular file. One useful application of this +combination of options is this tiny Bourne shell script: + +@example +#!/bin/sh +# Usage: backup FILE... +# Create a @sc{gnu}-style backup of each listed FILE. +for i; do + cp --backup --force -- "$i" "$i" +done +@end example + +@item --copy-contents +@cindex directories, copying recursively +@cindex copying directories recursively +@cindex recursively copying directories +@cindex non-directories, copying as special files +If copying recursively, copy the contents of any special files (e.g., +FIFOs and device files) as if they were regular files. This means +trying to read the data in each source file and writing it to the +destination. It is usually a mistake to use this option, as it +normally has undesirable effects on special files like FIFOs and the +ones typically found in the @file{/dev} directory. In most cases, +@code{cp -R --copy-contents} will hang indefinitely trying to read +from FIFOs and special files like @file{/dev/console}, and it will +fill up your destination disk if you use it to copy @file{/dev/zero}. +This option has no effect unless copying recursively, and it does not +affect the copying of symbolic links. + +@item -d +@opindex -d +@cindex symbolic links, copying +@cindex hard links, preserving +Copy symbolic links as symbolic links rather than copying the files that +they point to, and preserve hard links between source files in the copies. +Equivalent to @option{--no-dereference --preserve=links}. + +@item -f +@itemx --force +@opindex -f +@opindex --force +When copying without this option and an existing destination file cannot +be opened for writing, the copy fails. However, with @option{--force}), +when a destination file cannot be opened, @command{cp} then unlinks it and +tries to open it again. Contrast this behavior with that enabled by +@option{--link} and @option{--symbolic-link}, whereby the destination file +is never opened but rather is unlinked unconditionally. Also see the +description of @option{--remove-destination}. + +This option is independent of the @option{--interactive} or +@option{-i} option: neither cancels the effect of the other. + +@item -H +@opindex -H +If a command line argument specifies a symbolic link, then copy the +file it points to rather than the symbolic link itself. However, +copy (preserving its nature) any symbolic link that is encountered +via recursive traversal. + +@item -i +@itemx --interactive +@opindex -i +@opindex --interactive +When copying a file other than a directory, prompt whether to +overwrite an existing destination file. + +@item -l +@itemx --link +@opindex -l +@opindex --link +Make hard links instead of copies of non-directories. + +@item -L +@itemx --dereference +@opindex -L +@opindex --dereference +Always follow symbolic links. + +@item -P +@itemx --no-dereference +@opindex -P +@opindex --no-dereference +@cindex symbolic links, copying +Copy symbolic links as symbolic links rather than copying the files that +they point to. + +@item -p +@itemx @w{@kbd{--preserve}[=@var{attribute_list}]} +@opindex -p +@opindex --preserve +@cindex file information, preserving +Preserve the specified attributes of the original files. +If specified, the @var{attribute_list} must be a comma-separated list +of one or more of the following strings: + +@table @samp +@itemx mode +Preserve the file mode bits and access control lists. +@itemx ownership +Preserve the owner and group. On most modern systems, +only users with appropriate privileges may change the owner of a file, +and ordinary users +may preserve the group ownership of a file only if they happen to be +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 +when the affected file is a symbolic link. +However, FreeBSD now provides the @code{lutimes} function, which makes +it possibile even for symbolic links. However, this implementation does +not yet take advantage of that. +@c FIXME: once we provide lutimes support, update the above. +@itemx links +Preserve in the destination files +any links between corresponding source files. +@c Give examples illustrating how hard links are preserved. +@c Also, show how soft links map to hard links with -L and -H. +@itemx all +Preserve all file attributes. +Equivalent to specifying all of the above. +@end table + +Using @option{--preserve} with no @var{attribute_list} is equivalent +to @option{--preserve=mode,ownership,timestamps}. + +In the absence of this option, each destination file is created with the +mode bits of the corresponding source file, minus the bits set in the +umask and minus the set-user-ID and set-group-ID bits. +@xref{File permissions}. + +@itemx @w{@kbd{--no-preserve}=@var{attribute_list}} +@cindex file information, preserving +Do not preserve the specified attributes. The @var{attribute_list} +has the same form as for @option{--preserve}. + +@itemx --parents +@opindex --parents +@cindex parent directories and @command{cp} +Form the name of each destination file by appending to the target +directory a slash and the specified name of the source file. The last +argument given to @command{cp} must be the name of an existing directory. +For example, the command: + +@example +cp --parents a/b/c existing_dir +@end example + +@noindent +copies the file @file{a/b/c} to @file{existing_dir/a/b/c}, creating +any missing intermediate directories. + +@itemx @w{@kbd{--reply}=@var{how}} +@opindex --reply +@cindex interactivity +@c FIXME: remove in 2008 +@strong{Deprecated: to be removed in 2008.}@* +Using @option{--reply=yes} makes @command{cp} act as if @samp{yes} were +given as a response to every prompt about a destination file. That effectively +cancels any preceding @option{--interactive} or @option{-i} option. +Specify @option{--reply=no} to make @command{cp} act as if @samp{no} were +given as a response to every prompt about a destination file. +Specify @option{--reply=query} to make @command{cp} prompt the user +about each existing destination file. + +@item -R +@itemx -r +@itemx --recursive +@opindex -R +@opindex -r +@opindex --recursive +@cindex directories, copying recursively +@cindex copying directories recursively +@cindex recursively copying directories +@cindex non-directories, copying as special files +Copy directories recursively. Symbolic links are not followed by +default; see the @option{--archive} (@option{-a}), @option{-d}, +@option{--dereference} (@option{-L}), @option{--no-dereference} +(@option{-P}), and @option{-H} options. Special files are copied by +creating a destination file of the same type as the source; see the +@option{--copy-contents} option. It is not portable to use +@option{-r} to copy symbolic links or special files. On some +non-@sc{gnu} systems, @option{-r} implies the equivalent of +@option{-L} and @option{--copy-contents} for historical reasons. +Also, it is not portable to use @option{-R} to copy symbolic links +unless you also specify @option{-P}, as @acronym{POSIX} allows +implementations that dereference symbolic links by default. + +@item --remove-destination +@opindex --remove-destination +Remove each existing destination file before attempting to open it +(contrast with @option{-f} above). + +@item --sparse=@var{when} +@opindex --sparse=@var{when} +@cindex sparse files, copying +@cindex holes, copying files with +@findex read @r{system call, and holes} +A @dfn{sparse file} contains @dfn{holes}---a sequence of zero bytes that +does not occupy any physical disk blocks; the @samp{read} system call +reads these as zeros. This can both save considerable disk space and +increase speed, since many binary files contain lots of consecutive zero +bytes. By default, @command{cp} detects holes in input source files via a crude +heuristic and makes the corresponding output file sparse as well. +Only regular files may be sparse. + +The @var{when} value can be one of the following: + +@table @samp +@item auto +The default behavior: if the input file is sparse, attempt to make +the output file sparse, too. However, if an output file exists but +refers to a non-regular file, then do not attempt to make it sparse. + +@item always +For each sufficiently long sequence of zero bytes in the input file, +attempt to create a corresponding hole in the output file, even if the +input file does not appear to be sparse. +This is useful when the input file resides on a file system +that does not support sparse files +(for example, @samp{efs} file systems in SGI IRIX 5.3 and earlier), +but the output file is on a type of file system that does support them. +Holes may be created only in regular files, so if the destination file +is of some other type, @command{cp} does not even try to make it sparse. + +@item never +Never make the output file sparse. +This is useful in creating a file for use with the @command{mkswap} command, +since such a file must not have any holes. +@end table + +@optStripTrailingSlashes + +@item -s +@itemx --symbolic-link +@opindex -s +@opindex --symbolic-link +@cindex symbolic links, copying with +Make symbolic links instead of copies of non-directories. All source +file names must be absolute (starting with @samp{/}) unless the +destination files are in the current directory. This option merely +results in an error message on systems that do not support symbolic links. + +@optBackupSuffix + +@optTargetDirectory + +@optNoTargetDirectory + +@item -u +@itemx --update +@opindex -u +@opindex --update +@cindex newer files, copying only +Do not copy a non-directory that has an existing destination with the +same or newer modification time. If time stamps are being preserved, +the comparison is to the source time stamp truncated to the +resolutions of the destination file system and of the system calls +used to update time stamps; this avoids duplicate work if several +@samp{cp -pu} commands are executed with the same source and +destination. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Print the name of each file before copying it. + +@item -x +@itemx --one-file-system +@opindex -x +@opindex --one-file-system +@cindex file systems, omitting copying to different +Skip subdirectories that are on different file systems from the one that +the copy started on. +However, mount point directories @emph{are} copied. + +@end table + +@exitstatus + + +@node dd invocation +@section @command{dd}: Convert and copy a file + +@pindex dd +@cindex converting while copying a file + +@command{dd} copies a file (from standard input to standard output, by +default) with a changeable I/O block size, while optionally performing +conversions on it. Synopses: + +@example +dd [@var{operand}]@dots{} +dd @var{option} +@end example + +The only options are @option{--help} and @option{--version}. +@xref{Common options}. @command{dd} accepts the following operands. + +@table @samp + +@item if=@var{file} +@opindex if +Read from @var{file} instead of standard input. + +@item of=@var{file} +@opindex of +Write to @var{file} instead of standard output. Unless +@samp{conv=notrunc} is given, @command{dd} truncates @var{file} to zero +bytes (or the size specified with @samp{seek=}). + +@item ibs=@var{bytes} +@opindex ibs +@cindex block size of input +@cindex input block size +Set the input block size to @var{bytes}. +This makes @command{dd} read @var{bytes} per block. + +@item obs=@var{bytes} +@opindex obs +@cindex block size of output +@cindex output block size +Set the output block size to @var{bytes}. +This makes @command{dd} write @var{bytes} per block. + +@item bs=@var{bytes} +@opindex bs +@cindex block size +Set both input and output block sizes to @var{bytes}. +This makes @command{dd} read and write @var{bytes} per block, +overriding any @samp{ibs} and @samp{obs} settings. + +@item cbs=@var{bytes} +@opindex cbs +@cindex block size of conversion +@cindex conversion block size +@cindex fixed-length records, converting to variable-length +@cindex variable-length records, converting to fixed-length +Set the conversion block size to @var{bytes}. +When converting variable-length records to fixed-length ones +(@option{conv=block}) or the reverse (@option{conv=unblock}), +use @var{bytes} as the fixed record length. + +@item skip=@var{blocks} +@opindex skip +Skip @var{blocks} @samp{ibs}-byte blocks in the input file before copying. + +@item seek=@var{blocks} +@opindex seek +Skip @var{blocks} @samp{obs}-byte blocks in the output file before copying. + +@item count=@var{blocks} +@opindex count +Copy @var{blocks} @samp{ibs}-byte blocks from the input file, instead +of everything until the end of the file. + +@item conv=@var{conversion}[,@var{conversion}]@dots{} +@opindex conv +Convert the file as specified by the @var{conversion} argument(s). +(No spaces around any comma(s).) + +Conversions: + +@table @samp + +@item ascii +@opindex ascii@r{, converting to} +Convert @acronym{EBCDIC} to @acronym{ASCII}, +using the conversion table specified by @acronym{POSIX}. +This provides a 1:1 translation for all 256 bytes. + +@item ebcdic +@opindex ebcdic@r{, converting to} +Convert @acronym{ASCII} to @acronym{EBCDIC}. +This is the inverse of the @samp{ascii} conversion. + +@item ibm +@opindex alternate ebcdic@r{, converting to} +Convert @acronym{ASCII} to alternate @acronym{EBCDIC}, +using the alternate conversion table specified by @acronym{POSIX}. +This is not a 1:1 translation, but reflects common historical practice +for @samp{~}, @samp{[}, and @samp{]}. + +The @samp{ascii}, @samp{ebcdic}, and @samp{ibm} conversions are +mutually exclusive. + +@item block +@opindex block @r{(space-padding)} +For each line in the input, output @samp{cbs} bytes, replacing the +input newline with a space and padding with spaces as necessary. + +@item unblock +@opindex unblock +Replace trailing spaces in each @samp{cbs}-sized input block with a +newline. + +The @samp{block} and @samp{unblock} conversions are mutually exclusive. + +@item lcase +@opindex lcase@r{, converting to} +Change uppercase letters to lowercase. + +@item ucase +@opindex ucase@r{, converting to} +Change lowercase letters to uppercase. + +The @samp{lcase} and @samp{ucase} conversions are mutually exclusive. + +@item swab +@opindex swab @r{(byte-swapping)} +@cindex byte-swapping +Swap every pair of input bytes. @sc{gnu} @command{dd}, unlike others, works +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 nocreat +@opindex nocreat +@cindex creating output file, avoiding +Do not create the output file; the output file must already exist. + +@item excl +@opindex excl +@cindex creating output file, requiring +Fail if the output file already exists; @command{dd} must create the +output file itself. + +The @samp{excl} and @samp{nocreat} conversions are mutually exclusive. + +@item notrunc +@opindex notrunc +@cindex truncating output file, avoiding +Do not truncate the output file. + +@item sync +@opindex sync @r{(padding with nulls)} +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 fdatasync +@opindex fdatasync +@cindex synchronized data writes, before finishing +Synchronize output data just before finishing. This forces a physical +write of output data. + +@item fsync +@opindex fsync +@cindex synchronized data and metadata writes, before finishing +Synchronize output data and metadata just before finishing. This +forces a physical write of output data and metadata. + +@end table + +@item iflag=@var{flag}[,@var{flag}]@dots{} +@opindex iflag +Access the input file using the flags specified by the @var{flag} +argument(s). (No spaces around any comma(s).) + +@item oflag=@var{flag}[,@var{flag}]@dots{} +@opindex oflag +Access the output file using the flags specified by the @var{flag} +argument(s). (No spaces around any comma(s).) + +Here are the flags. Not every flag is supported on every operating +system. + +@table @samp + +@item append +@opindex append +@cindex appending to the output file +Write in append mode, so that even if some other process is writing to +this file, every @command{dd} write will append to the current +contents of the file. This flag makes sense only for output. +If you combine this flag with the @samp{of=@var{file}} operand, +you should also specify @samp{conv=notrunc} unless you want the +output file to be truncated before being appended to. + +@item direct +@opindex direct +@cindex direct I/O +Use direct I/O for data, avoiding the buffer cache. + +@item directory +@opindex directory +@cindex directory I/O + +Fail unless the file is a directory. Most operating systems do not +allow I/O to a directory, so this flag has limited utility. + +@item dsync +@opindex dsync +@cindex synchronized data reads +Use synchronized I/O for data. For the output file, this forces a +physical write of output data on each write. For the input file, +this flag can matter when reading from a remote file that has been +written to synchronously by some other process. Metadata (e.g., +last-access and last-modified time) is not necessarily synchronized. + +@item sync +@opindex sync +@cindex synchronized data and metadata I/O +Use synchronized I/O for both data and metadata. + +@item nonblock +@opindex nonblock +@cindex nonblocking I/O +Use non-blocking I/O. + +@item noatime +@opindex noatime +@cindex access time +Do not update the file's access time. +Some older file systems silently ignore this flag, so it is a good +idea to test it on your files before relying on it. + +@item noctty +@opindex noctty +@cindex controlling terminal +Do not assign the file to be a controlling terminal for @command{dd}. +This has no effect when the file is not a terminal. +On many hosts (e.g., @acronym{GNU}/Linux hosts), this option has no effect +at all. + +@item nofollow +@opindex nofollow +@cindex symbolic links, following +Do not follow symbolic links. + +@item nolinks +@opindex nolinks +@cindex hard links +Fail if the file has multiple hard links. + +@item binary +@opindex binary +@cindex binary I/O +Use binary I/O. This option has an effect only on nonstandard +platforms that distinguish binary from text I/O. + +@item text +@opindex text +@cindex text I/O +Use text I/O. Like @samp{binary}, this option has no effect on +standard platforms. + +@end table + +These flags are not supported on all systems, and @samp{dd} rejects +attempts to use them when they are not supported. When reading from +standard input or writing to standard output, the @samp{nofollow} and +@samp{noctty} flags should not be specified, and the other flags +(e.g., @samp{nonblock}) can affect how other processes behave with the +affected file descriptors, even after @command{dd} exits. + +@end table + +@cindex multipliers after numbers +The numeric-valued strings above (@var{bytes} and @var{blocks}) can be +followed by a multiplier: @samp{b}=512, @samp{c}=1, +@samp{w}=2, @samp{x@var{m}}=@var{m}, or any of the +standard block size suffixes like @samp{k}=1024 (@pxref{Block size}). + +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 +4 KiB label at the start of the disk: + +@example +disk=/dev/rdsk/c0t1d0s2 +tape=/dev/rmt/0 + +# Copy all but the label from disk to tape. +(dd bs=4k skip=1 count=0 && dd bs=512k) <$disk >$tape + +# Copy from tape back to disk, but leave the disk label alone. +(dd bs=4k seek=1 count=0 && dd bs=512k) <$tape >$disk +@end example + +Sending an @samp{INFO} signal to a running @command{dd} +process makes it print I/O statistics to standard error +and then resume copying. In the example below, +@command{dd} is run in the background to copy 10 million blocks. +The @command{kill} command makes it output intermediate I/O statistics, +and when @command{dd} completes, it outputs the final statistics. + +@example +$ dd if=/dev/zero of=/dev/null count=10MB & pid=$! +$ kill -s INFO $pid; wait $pid +3385223+0 records in +3385223+0 records out +1733234176 bytes (1.7 GB) copied, 6.42173 seconds, 270 MB/s +10000000+0 records in +10000000+0 records out +5120000000 bytes (5.1 GB) copied, 18.913 seconds, 271 MB/s +@end example + +@vindex POSIXLY_CORRECT +On systems lacking the @samp{INFO} signal @command{dd} responds to the +@samp{USR1} signal instead, unless the @env{POSIXLY_CORRECT} +environment variable is set. + +@exitstatus + + +@node install invocation +@section @command{install}: Copy files and set attributes + +@pindex install +@cindex copying files and setting attributes + +@command{install} copies files while setting their file mode bits and, if +possible, their owner and group. Synopses: + +@example +install [@var{option}]@dots{} [-T] @var{source} @var{dest} +install [@var{option}]@dots{} @var{source}@dots{} @var{directory} +install [@var{option}]@dots{} -t @var{directory} @var{source}@dots{} +install [@var{option}]@dots{} -d @var{directory}@dots{} +@end example + +@itemize @bullet +@item +If two file names are given, @command{install} copies the first file to the +second. + +@item +If the @option{--target-directory} (@option{-t}) option is given, or +failing that if the last file is a directory and the +@option{--no-target-directory} (@option{-T}) option is not given, +@command{install} copies each @var{source} file to the specified +directory, using the @var{source}s' names. + +@item +If the @option{--directory} (@option{-d}) option is given, +@command{install} creates each @var{directory} and any missing parent +directories. Parent directories are created with mode +@samp{u=rwx,go=rx} (755), regardless of the @option{-m} option or the +current umask. @xref{Directory Setuid and Setgid}, for how the +set-user-ID and set-group-ID bits of parent directories are inherited. +@end itemize + +@cindex Makefiles, installing programs in +@command{install} is similar to @command{cp}, but allows you to control the +attributes of destination files. It is typically used in Makefiles to +copy programs into their destination directories. It refuses to copy +files onto themselves. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@optBackup + +@item -c +@opindex -c +Ignored; for compatibility with old Unix versions of @command{install}. + +@item -d +@itemx --directory +@opindex -d +@opindex --directory +@cindex directories, creating with given attributes +@cindex parent directories, creating missing +@cindex leading directories, creating missing +Create any missing parent directories, giving them the default +attributes. Then create each given directory, setting their owner, +group and mode as given on the command line or to the defaults. + +@item -g @var{group} +@itemx --group=@var{group} +@opindex -g +@opindex --group +@cindex group ownership of installed files, setting +Set the group ownership of installed files or directories to +@var{group}. The default is the process's current group. @var{group} +may be either a group name or a numeric group ID. + +@item -m @var{mode} +@itemx --mode=@var{mode} +@opindex -m +@opindex --mode +@cindex permissions of installed files, setting +Set the file mode bits for the installed file or directory to @var{mode}, +which can be either an octal number, or a symbolic mode as in +@command{chmod}, with @samp{a=} (no access allowed to anyone) as the +point of departure (@pxref{File permissions}). +The default mode is @samp{u=rwx,go=rx,a-s}---read, write, and +execute for the owner, read and execute for group and other, and with +set-user-ID and set-group-ID disabled. +This default is not quite the same as @samp{755}, since it disables +instead of preserving set-user-ID and set-group-ID on directories. +@xref{Directory Setuid and Setgid}. + +@item -o @var{owner} +@itemx --owner=@var{owner} +@opindex -o +@opindex --owner +@cindex ownership of installed files, setting +@cindex appropriate privileges +@vindex root @r{as default owner} +If @command{install} has appropriate privileges (is run as root), set the +ownership of installed files or directories to @var{owner}. The default +is @code{root}. @var{owner} may be either a user name or a numeric user +ID. + +@item -p +@itemx --preserve-timestamps +@opindex -p +@opindex --preserve-timestamps +@cindex timestamps of installed files, preserving +Set the time of last access and the time of last modification of each +installed file to match those of each corresponding original file. +When a file is installed without this option, its last access and +last modification times are both set to the time of installation. +This option is useful if you want to use the last modification times +of installed files to keep track of when they were last built as opposed +to when they were last installed. + +@item -s +@itemx --strip +@opindex -s +@opindex --strip +@cindex symbol table information, stripping +@cindex stripping symbol table information +Strip the symbol tables from installed binary executables. + +@optBackupSuffix + +@optTargetDirectory + +@optNoTargetDirectory + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Print the name of each file before copying it. + +@end table + +@exitstatus + + +@node mv invocation +@section @command{mv}: Move (rename) files + +@pindex mv + +@command{mv} moves or renames files (or directories). Synopses: + +@example +mv [@var{option}]@dots{} [-T] @var{source} @var{dest} +mv [@var{option}]@dots{} @var{source}@dots{} @var{directory} +mv [@var{option}]@dots{} -t @var{directory} @var{source}@dots{} +@end example + +@itemize @bullet +@item +If two file names are given, @command{mv} moves the first file to the +second. + +@item +If the @option{--target-directory} (@option{-t}) option is given, or +failing that if the last file is a directory and the +@option{--no-target-directory} (@option{-T}) option is not given, +@command{mv} moves each @var{source} file to the specified +directory, using the @var{source}s' names. +@end itemize + +@command{mv} can move any type of file from one file system to another. +Prior to version @code{4.0} of the fileutils, +@command{mv} could move only regular files between file systems. +For example, now @command{mv} can move an entire directory hierarchy +including special device files from one partition to another. It first +uses some of the same code that's used by @code{cp -a} to copy the +requested directories and files, then (assuming the copy succeeded) +it removes the originals. If the copy fails, then the part that was +copied to the destination partition is removed. If you were to copy +three directories from one partition to another and the copy of the first +directory succeeded, but the second didn't, the first would be left on +the destination partition and the second and third would be left on the +original partition. + +@cindex prompting, and @command{mv} +If a destination file exists but is normally unwritable, standard input +is a terminal, and the @option{-f} or @option{--force} option is not given, +@command{mv} prompts the user for whether to replace the file. (You might +own the file, or have write permission on its directory.) If the +response is not affirmative, the file is skipped. + +@emph{Warning}: If you try to move a symlink that points to a directory, +and you specify the symlink with a trailing slash, then @command{mv} +doesn't move the symlink but instead moves the directory referenced +by the symlink. @xref{Trailing slashes}. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@optBackup + +@item -f +@itemx --force +@opindex -f +@opindex --force +@cindex prompts, omitting +Do not prompt the user before removing a destination file. + +@item -i +@itemx --interactive +@opindex -i +@opindex --interactive +@cindex prompts, forcing +Prompt whether to overwrite each existing destination file, regardless +of its permissions. +If the response is not affirmative, the file is skipped. + +@itemx @w{@kbd{--reply}=@var{how}} +@opindex --reply +@cindex interactivity +@c FIXME: remove in 2008 +@strong{Deprecated: to be removed in 2008.}@* +Specifying @option{--reply=yes} is equivalent to using @option{--force}. +Specify @option{--reply=no} to make @command{mv} act as if @samp{no} were +given as a response to every prompt about a destination file. +Specify @option{--reply=query} to make @command{mv} prompt the user +about each existing destination file. +Note that @option{--reply=no} has an effect only when @command{mv} would prompt +without @option{-i} or equivalent, i.e., when a destination file exists and is +not writable, standard input is a terminal, and no @option{-f} (or equivalent) +option is specified. + +@item -u +@itemx --update +@opindex -u +@opindex --update +@cindex newer files, moving only +Do not move a non-directory that has an existing destination with the +same or newer modification time. +If the move is across file system boundaries, the comparison is to the +source time stamp truncated to the resolutions of the destination file +system and of the system calls used to update time stamps; this avoids +duplicate work if several @samp{mv -u} commands are executed with the +same source and destination. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Print the name of each file before moving it. + +@optStripTrailingSlashes + +@optBackupSuffix + +@optTargetDirectory + +@optNoTargetDirectory + +@end table + +@exitstatus + + +@node rm invocation +@section @command{rm}: Remove files or directories + +@pindex rm +@cindex removing files or directories + +@command{rm} removes each given @var{file}. By default, it does not remove +directories. Synopsis: + +@example +rm [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +@cindex prompting, and @command{rm} +If the @option{-I} or @option{--interactive=once} option is given, +and there are more than three files or the @option{-r}, @option{-R}, +or @option{--recursive} are given, then @command{rm} prompts the user +for whether to proceed with the entire operation. If the response is +not affirmative, the entire command is aborted. + +Otherwise, if a file is unwritable, standard input is a terminal, and +the @option{-f} or @option{--force} option is not given, or the +@option{-i} or @option{--interactive=always} option @emph{is} given, +@command{rm} prompts the user for whether to remove the file. +If the response is not affirmative, the file is skipped. + +Any attempt to remove a file whose last file name component is +@file{.} or @file{..} is rejected without any prompting. + +@emph{Warning}: If you use @command{rm} to remove a file, it is usually +possible to recover the contents of that file. If you want more assurance +that the contents are truly unrecoverable, consider using @command{shred}. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -f +@itemx --force +@opindex -f +@opindex --force +Ignore nonexistent files and never prompt the user. +Ignore any previous @option{--interactive} (@option{-i}) option. + +@item -i +@opindex -i +Prompt whether to remove each file. +If the response is not affirmative, the file is skipped. +Ignore any previous @option{--force} (@option{-f}) option. +Equivalent to @option{--interactive=always}. + +@item -I +@opindex -I +Prompt once whether to proceed with the command, if more than three +files are named or if a recursive removal is requested. Ignore any +previous @option{--force} (@option{-f}) option. Equivalent to +@option{--interactive=once}. + +@itemx --interactive [=@var{when}] +@opindex --interactive +Specify when to issue an interactive prompt. @var{when} may be +omitted, or one of: +@itemize @bullet +@item never +@vindex never @r{interactive option} +- Do not prompt at all. +@item once +@vindex once @r{interactive option} +- Prompt once if more than three files are named or if a recursive +removal is requested. Equivalent to @option{-I}. +@item always +@vindex always @r{interactive option} +- Prompt for every file being removed. Equivalent to @option{-i}. +@end itemize +Specifying @option{--interactive} and no @var{when} is equivalent to +@option{--interactive=always}. + +@itemx --one-file-system +@opindex --one-file-system +@cindex one file system, restricting @command{rm} to +When removing a hierarchy recursively, skip any directory that is on a +file system different from that of the corresponding command line argument. + +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 +use one's start-up file. The catch is that it's easy to forget to +unmount @file{/home}. Then, when you use @command{rm -rf} to remove +your normally throw-away chroot, that command will remove everything +under @file{/home}, too. +Use the @option{--one-file-system} option, and it will +warn about and skip directories on other file systems. +Of course, this will not save your @file{/home} if it and your +chroot happen to be on the same file system. + +@itemx --preserve-root +@opindex --preserve-root +@cindex root directory, disallow recursive destruction +Fail upon any attempt to remove the root directory, @file{/}, +when used with the @option{--recursive} option. +This is the default behavior. +@xref{Treating / specially}. + +@itemx --no-preserve-root +@opindex --no-preserve-root +@cindex root directory, allow recursive destruction +Do not treat @file{/} specially when removing recursively. +This option is not recommended unless you really want to +remove all the files on your computer. +@xref{Treating / specially}. + +@item -r +@itemx -R +@itemx --recursive +@opindex -r +@opindex -R +@opindex --recursive +@cindex directories, removing (recursively) +Remove the listed directories and their contents recursively. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Print the name of each file before removing it. + +@end table + +@cindex files beginning with @samp{-}, removing +@cindex @samp{-}, removing files beginning with +One common question is how to remove files whose names begin with a +@samp{-}. @sc{gnu} @command{rm}, like every program that uses the @code{getopt} +function to parse its arguments, lets you use the @samp{--} option to +indicate that all following arguments are non-options. To remove a file +called @file{-f} in the current directory, you could type either: + +@example +rm -- -f +@end example + +@noindent +or: + +@example +rm ./-f +@end example + +@opindex - @r{and Unix @command{rm}} +The Unix @command{rm} program's use of a single @samp{-} for this purpose +predates the development of the getopt standard syntax. + +@exitstatus + + +@node shred invocation +@section @command{shred}: Remove files more securely + +@pindex shred +@cindex data, erasing +@cindex erasing data + +@command{shred} overwrites devices or files, to help prevent even +very expensive hardware from recovering the data. + +Ordinarily when you remove a file (@pxref{rm invocation}), the data is +not actually destroyed. Only the index listing where the file is +stored is destroyed, and the storage is made available for reuse. +There are undelete utilities that will attempt to reconstruct the index +and can bring the file back if the parts were not reused. + +On a busy system with a nearly-full drive, space can get reused in a few +seconds. But there is no way to know for sure. If you have sensitive +data, you may want to be sure that recovery is not possible by actually +overwriting the file with non-sensitive data. + +However, even after doing that, it is possible to take the disk back +to a laboratory and use a lot of sensitive (and expensive) equipment +to look for the faint ``echoes'' of the original data underneath the +overwritten data. If the data has only been overwritten once, it's not +even that hard. + +The best way to remove something irretrievably is to destroy the media +it's on with acid, melt it down, or the like. For cheap removable media +like floppy disks, this is the preferred method. However, hard drives +are expensive and hard to melt, so the @command{shred} utility tries +to achieve a similar effect non-destructively. + +This uses many overwrite passes, with the data patterns chosen to +maximize the damage they do to the old data. While this will work on +floppies, the patterns are designed for best effect on hard drives. +For more details, see the source code and Peter Gutmann's paper +@uref{http://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html, +@cite{Secure Deletion of Data from Magnetic and Solid-State Memory}}, +from the proceedings of the Sixth @acronym{USENIX} Security Symposium (San Jose, +California, July 22--25, 1996). + +@strong{Please note} that @command{shred} relies on a very important assumption: +that the file system overwrites data in place. This is the traditional +way to do things, but many modern file system designs do not satisfy this +assumption. Exceptions include: + +@itemize @bullet + +@item +Log-structured or journaled file systems, such as those supplied with +AIX and Solaris, and JFS, ReiserFS, XFS, Ext3 (in @code{data=journal} mode), +BFS, NTFS, etc.@: when they are configured to journal @emph{data}. + +@item +File systems that write redundant data and carry on even if some writes +fail, such as RAID-based file systems. + +@item +File systems that make snapshots, such as Network Appliance's NFS server. + +@item +File systems that cache in temporary locations, such as NFS version 3 +clients. + +@item +Compressed file systems. +@end itemize + +In the particular case of ext3 file systems, the above disclaimer applies (and +@command{shred} is thus of limited effectiveness) only in @code{data=journal} +mode, which journals file data in addition to just metadata. In both +the @code{data=ordered} (default) and @code{data=writeback} modes, +@command{shred} works as usual. Ext3 journaling modes can be changed +by adding the @code{data=something} option to the mount options for a +particular file system in the @file{/etc/fstab} file, as documented in +the mount man page (man mount). + +If you are not sure how your file system operates, then you should assume +that it does not overwrite data in place, which means that shred cannot +reliably operate on regular files in your file system. + +Generally speaking, it is more reliable to shred a device than a file, +since this bypasses the problem of file system design mentioned above. +However, even shredding devices is not always completely reliable. For +example, most disks map out bad sectors invisibly to the application; if +the bad sectors contain sensitive data, @command{shred} won't be able to +destroy it. + +@command{shred} makes no attempt to detect or report this problem, just as +it makes no attempt to do anything about backups. However, since it is +more reliable to shred devices than files, @command{shred} by default does +not truncate or remove the output file. This default is more suitable +for devices, which typically cannot be truncated and should not be +removed. + +Finally, consider the risk of backups and mirrors. +File system backups and remote mirrors may contain copies of the +file that cannot be removed, and that will allow a shredded file +to be recovered later. So if you keep any data you may later want +to destroy using @command{shred}, be sure that it is not backed up or mirrored. + +@example +shred [@var{option}]@dots{} @var{file}[@dots{}] +@end example + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -f +@itemx --force +@opindex -f +@opindex --force +@cindex force deletion +Override file permissions if necessary to allow overwriting. + +@item -@var{NUMBER} +@itemx -n @var{NUMBER} +@itemx --iterations=@var{NUMBER} +@opindex -n @var{NUMBER} +@opindex --iterations=@var{NUMBER} +@cindex iterations, selecting the number of +By default, @command{shred} uses 25 passes of overwrite. This is enough +for all of the useful overwrite patterns to be used at least once. +You can reduce this to save time, or increase it if you have a lot of +time to waste. + +@item --random-source=@var{file} +@opindex --random-source +@cindex random source for shredding +Use @var{file} as a source of random data used to overwrite and to +choose pass ordering. @xref{Random sources}. + +@item -s @var{BYTES} +@itemx --size=@var{BYTES} +@opindex -s @var{BYTES} +@opindex --size=@var{BYTES} +@cindex size of file to shred +Shred the first @var{BYTES} bytes of the file. The default is to shred +the whole file. @var{BYTES} can be followed by a size specification like +@samp{K}, @samp{M}, or @samp{G} to specify a multiple. @xref{Block size}. + +@item -u +@itemx --remove +@opindex -u +@opindex --remove +@cindex removing files after shredding +After shredding a file, truncate it (if possible) and then remove it. +If a file has multiple links, only the named links will be removed. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Display status updates as sterilization proceeds. + +@item -x +@itemx --exact +@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. +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 does not increase the apparent size of the file. + +@item -z +@itemx --zero +@opindex -z +@opindex --zero +Normally, the last pass that @command{shred} writes is made up of +random data. If this would be conspicuous on your hard drive (for +example, because it looks like encrypted data), or you just think +it's tidier, the @option{--zero} option adds an additional overwrite pass with +all zero bits. This is in addition to the number of passes specified +by the @option{--iterations} option. + +@end table + +You might use the following command to erase all trace of the +file system you'd created on the floppy disk in your first drive. +That command takes about 20 minutes to erase a ``1.44MB'' (actually +1440 KiB) floppy. + +@example +shred --verbose /dev/fd0 +@end example + +Similarly, to erase all data on a selected partition of +your hard disk, you could give a command like this: + +@example +shred --verbose /dev/sda5 +@end example + +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` +exec 3<>"$i" +rm -- "$i" +echo "Hello, world" >&3 +shred - >&3 +exec 3>- +@end example + +However, the command @samp{shred - >file} does not shred the contents +of @var{file}, since the shell truncates @var{file} before invoking +@command{shred}. Use the command @samp{shred file} or (if using a +Bourne-compatible shell) the command @samp{shred - 1<>file} instead. + +@exitstatus + + +@node Special file types +@chapter Special file types + +@cindex special file types +@cindex file types, special + +This chapter describes commands which create special types of files (and +@command{rmdir}, which removes directories, one special file type). + +@cindex special file types +@cindex file types +Although Unix-like operating systems have markedly fewer special file +types than others, not @emph{everything} can be treated only as the +undifferentiated byte stream of @dfn{normal files}. For example, when a +file is created or removed, the system must record this information, +which it does in a @dfn{directory}---a special type of file. Although +you can read directories as normal files, if you're curious, in order +for the system to do its job it must impose a structure, a certain +order, on the bytes of the file. Thus it is a ``special'' type of file. + +Besides directories, other special file types include named pipes +(FIFOs), symbolic links, sockets, and so-called @dfn{special files}. + +@menu +* 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 the referent of a symbolic link. +* rmdir invocation:: Remove empty directories. +* unlink invocation:: Remove files via the unlink syscall +@end menu + + +@node link invocation +@section @command{link}: Make a hard link via the link syscall + +@pindex link +@cindex links, creating +@cindex hard links, creating +@cindex creating links (hard only) + +@command{link} creates a single hard link at a time. +It is a minimalist interface to the system-provided +@code{link} function. @xref{Hard Links, , , libc, +The GNU C Library Reference Manual}. +It avoids the bells and whistles of the more commonly-used +@command{ln} command (@pxref{ln invocation}). +Synopsis: + +@example +link @var{filename} @var{linkname} +@end example + +@var{filename} must specify an existing file, and @var{linkname} +must specify a nonexistent entry in an existing directory. +@command{link} simply calls @code{link (@var{filename}, @var{linkname})} +to create the link. + +On a @acronym{GNU} system, this command acts like @samp{ln --directory +--no-target-directory @var{filename} @var{linkname}}. However, the +@option{--directory} and @option{--no-target-directory} options are +not specified by @acronym{POSIX}, and the @command{link} command is +more portable in practice. + +@exitstatus + + +@node ln invocation +@section @command{ln}: Make links between files + +@pindex ln +@cindex links, creating +@cindex hard links, creating +@cindex symbolic (soft) links, creating +@cindex creating links (hard or soft) + +@cindex file systems and hard links +@command{ln} makes links between files. By default, it makes hard links; +with the @option{-s} option, it makes symbolic (or @dfn{soft}) links. +Synopses: + +@example +ln [@var{option}]@dots{} [-T] @var{target} @var{linkname} +ln [@var{option}]@dots{} @var{target} +ln [@var{option}]@dots{} @var{target}@dots{} @var{directory} +ln [@var{option}]@dots{} -t @var{directory} @var{target}@dots{} +@end example + +@itemize @bullet + +@item +If two file names are given, @command{ln} creates a link to the first +file from the second. + +@item +If one @var{target} is given, @command{ln} creates a link to that file +in the current directory. + +@item +If the @option{--target-directory} (@option{-t}) option is given, or +failing that if the last file is a directory and the +@option{--no-target-directory} (@option{-T}) option is not given, +@command{ln} creates a link to each @var{target} file in the specified +directory, using the @var{target}s' names. + +@end itemize + +Normally @command{ln} does not remove existing files. Use the +@option{--force} (@option{-f}) option to remove them unconditionally, +the @option{--interactive} (@option{-i}) option to remove them +conditionally, and the @option{--backup} (@option{-b}) option to +rename them. + +@cindex hard link, defined +@cindex inode, and hard links +A @dfn{hard link} is another name for an existing file; the link and the +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 +restrictions are not mandated by @acronym{POSIX}, however.) + +@cindex dereferencing symbolic links +@cindex symbolic link, defined +@dfn{Symbolic links} (@dfn{symlinks} for short), on the other hand, are +a special file type (which not all kernels support: System V release 3 +(and older) systems lack symlinks) in which the link file actually +refers to a different file, by name. When most operations (opening, +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. @xref{Symbolic Links,,, +libc, The GNU C Library Reference Manual}. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@optBackup + +@item -d +@itemx -F +@itemx --directory +@opindex -d +@opindex -F +@opindex --directory +@cindex hard links to directories +Allow users with appropriate privileges to attempt to make hard links +to directories. +However, note that this will probably fail due to +system restrictions, even for the super-user. + +@item -f +@itemx --force +@opindex -f +@opindex --force +Remove existing destination files. + +@item -i +@itemx --interactive +@opindex -i +@opindex --interactive +@cindex prompting, and @command{ln} +Prompt whether to remove existing destination files. + +@item -n +@itemx --no-dereference +@opindex -n +@opindex --no-dereference +Do not treat the last operand specially when it is a symbolic link to +a directory. Instead, treat it as if it were a normal file. + +When the destination is an actual directory (not a symlink to one), +there is no ambiguity. The link is created in that directory. +But when the specified destination is a symlink to a directory, +there are two ways to treat the user's request. @command{ln} can +treat the destination just as it would a normal directory and create +the link in it. On the other hand, the destination can be viewed as a +non-directory---as the symlink itself. In that case, @command{ln} +must delete or backup that symlink before creating the new link. +The default is to treat a destination that is a symlink to a directory +just like a directory. + +This option is weaker than the @option{--no-target-directory} +(@option{-T}) option, so it has no effect if both options are given. + +@item -s +@itemx --symbolic +@opindex -s +@opindex --symbolic +Make symbolic links instead of hard links. This option merely produces +an error message on systems that do not support symbolic links. + +@optBackupSuffix + +@optTargetDirectory + +@optNoTargetDirectory + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Print the name of each file after linking it successfully. + +@end table + +@exitstatus + +Examples: + +@smallexample +Bad Example: + +# Create link ../a pointing to a in that directory. +# Not really useful because it points to itself. +ln -s a .. + +Better Example: + +# Change to the target before creating symlinks to avoid being confused. +cd .. +ln -s adir/a . + +Bad Example: + +# Hard coded file names don't move well. +ln -s $(pwd)/a /some/dir/ + +Better Example: + +# Relative file names survive directory moves and also +# work across networked file systems. +ln -s afile anotherfile +ln -s ../adir/afile yetanotherfile +@end smallexample + + +@node mkdir invocation +@section @command{mkdir}: Make directories + +@pindex mkdir +@cindex directories, creating +@cindex creating directories + +@command{mkdir} creates directories with the specified names. Synopsis: + +@example +mkdir [@var{option}]@dots{} @var{name}@dots{} +@end example + +@command{mkdir} creates each directory @var{name} in the order given. +It reports an error if @var{name} already exists, unless the +@option{-p} option is given and @var{name} is a directory. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -m @var{mode} +@itemx --mode=@var{mode} +@opindex -m +@opindex --mode +@cindex modes of created directories, setting +Set the file permission bits of created directories to @var{mode}, +which uses the same syntax as +in @command{chmod} and uses @samp{a=rwx} (read, write and execute allowed for +everyone) for the point of the departure. @xref{File permissions}. + +Normally the directory has the desired file mode bits at the moment it +is created. As a @acronym{GNU} extension, @var{mode} may also mention +special mode bits, but in this case there may be a temporary window +during which the directory exists but its special mode bits are +incorrect. @xref{Directory Setuid and Setgid}, for how the +set-user-ID and set-group-ID bits of directories are inherited unless +overridden in this way. + +@item -p +@itemx --parents +@opindex -p +@opindex --parents +@cindex parent directories, creating +Make any missing parent directories for each argument, setting their +file permission bits to the umask modified by @samp{u+wx}. Ignore +existing parent directories, and do not change their file permission +bits. + +To set the file permission bits of any newly-created parent +directories to a value that includes @samp{u+wx}, you can set the +umask before invoking @command{mkdir}. For example, if the shell +command @samp{(umask u=rwx,go=rx; mkdir -p P/Q)} creates the parent +@file{P} it sets the parent's permission bits to @samp{u=rwx,go=rx}. +To set a parent's special mode bits as well, you can invoke +@command{chmod} after @command{mkdir}. @xref{Directory Setuid and +Setgid}, for how the set-user-ID and set-group-ID bits of +newly-created parent directories are inherited. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Print a message for each created directory. This is most useful with +@option{--parents}. +@end table + +@exitstatus + + +@node mkfifo invocation +@section @command{mkfifo}: Make FIFOs (named pipes) + +@pindex mkfifo +@cindex FIFOs, creating +@cindex named pipes, creating +@cindex creating FIFOs (named pipes) + +@command{mkfifo} creates FIFOs (also called @dfn{named pipes}) with the +specified names. Synopsis: + +@example +mkfifo [@var{option}] @var{name}@dots{} +@end example + +A @dfn{FIFO} is a special file type that permits independent processes +to communicate. One process opens the FIFO file for writing, and +another for reading, after which data can flow as with the usual +anonymous pipe in shells or elsewhere. + +The program accepts the following option. Also see @ref{Common options}. + +@table @samp + +@item -m @var{mode} +@itemx --mode=@var{mode} +@opindex -m +@opindex --mode +@cindex modes of created FIFOs, setting +Set the mode of created FIFOs to @var{mode}, which is symbolic as in +@command{chmod} and uses @samp{a=rw} (read and write allowed for everyone) +for the point of departure. @var{mode} should specify only file +permission bits. @xref{File permissions}. + +@end table + +@exitstatus + + +@node mknod invocation +@section @command{mknod}: Make block or character special files + +@pindex mknod +@cindex block special files, creating +@cindex character special files, creating + +@command{mknod} creates a FIFO, character special file, or block special +file with the specified name. Synopsis: + +@example +mknod [@var{option}]@dots{} @var{name} @var{type} [@var{major} @var{minor}] +@end example + +@cindex special files +@cindex block special files +@cindex character special files +Unlike the phrase ``special file type'' above, the term @dfn{special +file} has a technical meaning on Unix: something that can generate or +receive data. Usually this corresponds to a physical piece of hardware, +e.g., a printer or a disk. (These files are typically created at +system-configuration time.) The @command{mknod} command is what creates +files of this type. Such devices can be read either a character at a +time or a ``block'' (many characters) at a time, hence we say there are +@dfn{block special} files and @dfn{character special} files. + +The arguments after @var{name} specify the type of file to make: + +@table @samp + +@item p +@opindex p @r{for FIFO file} +for a FIFO + +@item b +@opindex b @r{for block special file} +for a block special file + +@item c +@c Don't document the `u' option -- it's just a synonym for `c'. +@c Do *any* versions of mknod still use it? +@c @itemx u +@opindex c @r{for character special file} +@c @opindex u @r{for character special file} +for a character special file + +@end table + +When making a block or character special file, the major and minor +device numbers must be given after the file type. +If a major or minor device number begins with @samp{0x} or @samp{0X}, +it is interpreted as hexadecimal; otherwise, if it begins with @samp{0}, +as octal; otherwise, as decimal. + +The program accepts the following option. Also see @ref{Common options}. + +@table @samp + +@item -m @var{mode} +@itemx --mode=@var{mode} +@opindex -m +@opindex --mode +Set the mode of created files to @var{mode}, which is symbolic as in +@command{chmod} and uses @samp{a=rw} as the point of departure. +@var{mode} should specify only file permission bits. +@xref{File permissions}. + +@end table + +@exitstatus + + +@node readlink invocation +@section @command{readlink}: Print the referent of a symbolic link + +@pindex readlink +@cindex displaying value of a symbolic link + +@command{readlink} may work in one of two supported modes: + +@table @samp + +@item Readlink mode + +@command{readlink} outputs the value of the given symbolic link. +If @command{readlink} is invoked with an argument other than the name +of a symbolic link, it produces no output and exits with a nonzero exit code. + +@item Canonicalize mode + +@command{readlink} outputs the absolute name of the given file which contains +no @file{.}, @file{..} components nor any repeated separators +(@file{/}) or symbolic links. + +@end table + +@example +readlink [@var{option}] @var{file} +@end example + +By default, @command{readlink} operates in readlink mode. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -f +@itemx --canonicalize +@opindex -f +@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. + +@item -e +@itemx --canonicalize-existing +@opindex -e +@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. + +@item -m +@itemx --canonicalize-missing +@opindex -m +@opindex --canonicalize-missing +Activate canonicalize mode. +If any component is missing or unavailable, @command{readlink} treats it +as a directory. + +@item -n +@itemx --no-newline +@opindex -n +@opindex --no-newline +Do not output the trailing newline. + +@item -s +@itemx -q +@itemx --silent +@itemx --quiet +@opindex -s +@opindex -q +@opindex --silent +@opindex --quiet +Suppress most error messages. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Report error messages. + +@end table + +The @command{readlink} utility first appeared in OpenBSD 2.1. + +@exitstatus + + +@node rmdir invocation +@section @command{rmdir}: Remove empty directories + +@pindex rmdir +@cindex removing empty directories +@cindex directories, removing empty + +@command{rmdir} removes empty directories. Synopsis: + +@example +rmdir [@var{option}]@dots{} @var{directory}@dots{} +@end example + +If any @var{directory} argument does not refer to an existing empty +directory, it is an error. + +The program accepts the following option. Also see @ref{Common options}. + +@table @samp + +@item --ignore-fail-on-non-empty +@opindex --ignore-fail-on-non-empty +@cindex directory deletion, ignoring failures +Ignore each failure to remove a directory that is solely because +the directory is non-empty. + +@item -p +@itemx --parents +@opindex -p +@opindex --parents +@cindex parent directories, removing +Remove @var{directory}, then try to remove each component of @var{directory}. +So, for example, @samp{rmdir -p a/b/c} is similar to @samp{rmdir a/b/c a/b a}. +As such, it fails if any of those directories turns out not to be empty. +Use the @option{--ignore-fail-on-non-empty} option to make it so such +a failure does not evoke a diagnostic and does not cause @command{rmdir} to +exit unsuccessfully. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +@cindex directory deletion, reporting +Give a diagnostic for each successful removal. +@var{directory} is removed. + +@end table + +@xref{rm invocation}, for how to remove non-empty directories (recursively). + +@exitstatus + + +@node unlink invocation +@section @command{unlink}: Remove files via the unlink syscall + +@pindex unlink +@cindex removing files or directories (via the unlink syscall) + +@command{unlink} deletes a single specified file name. +It is a minimalist interface to the system-provided +@code{unlink} function. @xref{Deleting Files, , , libc, +The GNU C Library Reference Manual}. Synopsis: +It avoids the bells and whistles of the more commonly-used +@command{rm} command (@pxref{rm invocation}). + +@example +unlink @var{filename} +@end example + +On some systems @code{unlink} can be used to delete the name of a +directory. On others, it can be used that way only by a privileged user. +In the GNU system @code{unlink} can never delete the name of a directory. + +The @command{unlink} command honors the @option{--help} and +@option{--version} options. To remove a file whose name begins with +@samp{-}, prefix the name with @samp{./}, e.g., @samp{unlink ./--help}. + +@exitstatus + + +@node Changing file attributes +@chapter Changing file attributes + +@cindex changing file attributes +@cindex file attributes, changing +@cindex attributes, file + +A file is not merely its contents, a name, and a file type +(@pxref{Special file types}). A file also has an owner (a user ID), a +group (a group ID), permissions (what the owner can do with the file, +what people in the group can do, and what everyone else can do), various +timestamps, and other information. Collectively, we call these a file's +@dfn{attributes}. + +These commands change file attributes. + +@menu +* chgrp invocation:: Change file groups. +* chmod invocation:: Change access permissions. +* chown invocation:: Change file owners and groups. +* touch invocation:: Change file timestamps. +@end menu + + +@node chown invocation +@section @command{chown}: Change file owner and group + +@pindex chown +@cindex file ownership, changing +@cindex group ownership, changing +@cindex changing file ownership +@cindex changing group ownership + +@command{chown} changes the user and/or group ownership of each given @var{file} +to @var{new-owner} or to the user and group of an existing reference file. +Synopsis: + +@example +chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@} @var{file}@dots{} +@end example + +If used, @var{new-owner} specifies the new owner and/or group as follows +(with no embedded white space): + +@example +[@var{owner}] [ : [@var{group}] ] +@end example + +Specifically: + +@table @var +@item owner +If only an @var{owner} (a user name or numeric user ID) is given, that +user is made the owner of each given file, and the files' group is not +changed. + +@item owner@samp{:}group +If the @var{owner} is followed by a colon and a @var{group} (a +group name or numeric group ID), with no spaces between them, the group +ownership of the files is changed as well (to @var{group}). + +@item owner@samp{:} +If a colon but no group name follows @var{owner}, that user is +made the owner of the files and the group of the files is changed to +@var{owner}'s login group. + +@item @samp{:}group +If the colon and following @var{group} are given, but the owner +is omitted, only the group of the files is changed; in this case, +@command{chown} performs the same function as @command{chgrp}. + +@item @samp{:} +If only a colon is given, or if @var{new-owner} is empty, neither the +owner nor the group is changed. + +@end table + +If @var{owner} or @var{group} is intended to represent a numeric user +or group ID, then you may specify it with a leading @samp{+}. +@xref{Disambiguating names and IDs}. + +Some older scripts may still use @samp{.} in place of the @samp{:} separator. +@acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not +require support for that, but for backward compatibility @acronym{GNU} +@command{chown} supports @samp{.} so long as no ambiguity results. +New scripts should avoid the use of @samp{.} because it is not +portable, and because it has undesirable results if the entire +@var{owner@samp{.}group} happens to identify a user whose name +contains @samp{.}. + +The @command{chown} command sometimes clears the set-user-ID or +set-group-ID permission bits. This behavior depends on the policy and +functionality of the underlying @code{chown} system call, which may +make system-dependent file mode modifications outside the control of +the @command{chown} command. For example, the @command{chown} command +might not affect those bits when invoked by a user with appropriate +privileges, or when the +bits signify some function other than executable permission (e.g., +mandatory locking). +When in doubt, check the underlying system behavior. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -c +@itemx --changes +@opindex -c +@opindex --changes +@cindex changed owners, verbosely describing +Verbosely describe the action for each @var{file} whose ownership +actually changes. + +@item -f +@itemx --silent +@itemx --quiet +@opindex -f +@opindex --silent +@opindex --quiet +@cindex error messages, omitting +Do not print error messages about files whose ownership cannot be +changed. + +@itemx @w{@kbd{--from}=@var{old-owner}} +@opindex --from +@cindex symbolic links, changing owner +Change a @var{file}'s ownership only if it has current attributes specified +by @var{old-owner}. @var{old-owner} has the same form as @var{new-owner} +described above. +This option is useful primarily from a security standpoint in that +it narrows considerably the window of potential abuse. +For example, to reflect a user ID numbering change for one user's files +without an option like this, @code{root} might run + +@smallexample +find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER +@end smallexample + +But that is dangerous because the interval between when the @command{find} +tests the existing file's owner and when the @command{chown} is actually run +may be quite large. +One way to narrow the gap would be to invoke chown for each file +as it is found: + +@example +find / -owner OLDUSER -exec chown -h NEWUSER @{@} \; +@end example + +But that is very slow if there are many affected files. +With this option, it is safer (the gap is narrower still) +though still not perfect: + +@example +chown -h -R --from=OLDUSER NEWUSER / +@end example + +@item --dereference +@opindex --dereference +@cindex symbolic links, changing owner +@findex lchown +Do not act on symbolic links themselves but rather on what they point to. +This is the default. + +@item -h +@itemx --no-dereference +@opindex -h +@opindex --no-dereference +@cindex symbolic links, changing owner +@findex lchown +Act on symbolic links themselves instead of what they point to. +This mode relies on the @code{lchown} system call. +On systems that do not provide the @code{lchown} system call, +@command{chown} fails when a file specified on the command line +is a symbolic link. +By default, no diagnostic is issued for symbolic links encountered +during a recursive traversal, but see @option{--verbose}. + +@itemx --preserve-root +@opindex --preserve-root +@cindex root directory, disallow recursive modification +Fail upon any attempt to recursively change the root directory, @file{/}. +Without @option{--recursive}, this option has no effect. +@xref{Treating / specially}. + +@itemx --no-preserve-root +@opindex --no-preserve-root +@cindex root directory, allow recursive modification +Cancel the effect of any preceding @option{--preserve-root} option. +@xref{Treating / specially}. + +@item --reference=@var{ref_file} +@opindex --reference +Change the user and group of each @var{file} to be the same as those of +@var{ref_file}. If @var{ref_file} is a symbolic link, do not use the +user and group of the symbolic link, but rather those of the file it +refers to. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Output a diagnostic for every file processed. +If a symbolic link is encountered during a recursive traversal +on a system without the @code{lchown} system call, and @option{--no-dereference} +is in effect, then issue a diagnostic saying neither the symbolic link nor +its referent is being changed. + +@item -R +@itemx --recursive +@opindex -R +@opindex --recursive +@cindex recursively changing file ownership +Recursively change ownership of directories and their contents. + +@choptH +@xref{Traversing symlinks}. + +@choptL +@xref{Traversing symlinks}. + +@choptP +@xref{Traversing symlinks}. + +@end table + +@exitstatus + +Examples: + +@smallexample +# Change the owner of /u to "root". +chown root /u + +# Likewise, but also change its group to "staff". +chown root:staff /u + +# Change the owner of /u and subfiles to "root". +chown -hR root /u +@end smallexample + + +@node chgrp invocation +@section @command{chgrp}: Change group ownership + +@pindex chgrp +@cindex group ownership, changing +@cindex changing group ownership + +@command{chgrp} changes the group ownership of each given @var{file} +to @var{group} (which can be either a group name or a numeric group ID) +or to the group of an existing reference file. Synopsis: + +@example +chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@} @var{file}@dots{} +@end example + +If @var{group} is intended to represent a +numeric group ID, then you may specify it with a leading @samp{+}. +@xref{Disambiguating names and IDs}. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -c +@itemx --changes +@opindex -c +@opindex --changes +@cindex changed files, verbosely describing +Verbosely describe the action for each @var{file} whose group actually +changes. + +@item -f +@itemx --silent +@itemx --quiet +@opindex -f +@opindex --silent +@opindex --quiet +@cindex error messages, omitting +Do not print error messages about files whose group cannot be +changed. + +@item --dereference +@opindex --dereference +@cindex symbolic links, changing owner +@findex lchown +Do not act on symbolic links themselves but rather on what they point to. +This is the default. + +@item -h +@itemx --no-dereference +@opindex -h +@opindex --no-dereference +@cindex symbolic links, changing group +@findex lchown +Act on symbolic links themselves instead of what they point to. +This mode relies on the @code{lchown} system call. +On systems that do not provide the @code{lchown} system call, +@command{chgrp} fails when a file specified on the command line +is a symbolic link. +By default, no diagnostic is issued for symbolic links encountered +during a recursive traversal, but see @option{--verbose}. + +@itemx --preserve-root +@opindex --preserve-root +@cindex root directory, disallow recursive modification +Fail upon any attempt to recursively change the root directory, @file{/}. +Without @option{--recursive}, this option has no effect. +@xref{Treating / specially}. + +@itemx --no-preserve-root +@opindex --no-preserve-root +@cindex root directory, allow recursive modification +Cancel the effect of any preceding @option{--preserve-root} option. +@xref{Treating / specially}. + +@item --reference=@var{ref_file} +@opindex --reference +Change the group of each @var{file} to be the same as that of +@var{ref_file}. If @var{ref_file} is a symbolic link, do not use the +group of the symbolic link, but rather that of the file it refers to. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Output a diagnostic for every file processed. +If a symbolic link is encountered during a recursive traversal +on a system without the @code{lchown} system call, and @option{--no-dereference} +is in effect, then issue a diagnostic saying neither the symbolic link nor +its referent is being changed. + +@item -R +@itemx --recursive +@opindex -R +@opindex --recursive +@cindex recursively changing group ownership +Recursively change the group ownership of directories and their contents. + +@choptH +@xref{Traversing symlinks}. + +@choptL +@xref{Traversing symlinks}. + +@choptP +@xref{Traversing symlinks}. + +@end table + +@exitstatus + +Examples: + +@smallexample +# Change the group of /u to "staff". +chgrp staff /u + +# Change the group of /u and subfiles to "staff". +chgrp -hR staff /u +@end smallexample + + +@node chmod invocation +@section @command{chmod}: Change access permissions + +@pindex chmod +@cindex changing access permissions +@cindex access permissions, changing +@cindex permissions, changing access + +@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{} +@end example + +@cindex symbolic links, permissions of +@command{chmod} never changes the permissions of symbolic links, since +the @command{chmod} system call cannot change their permissions. +This is not a problem since the permissions of symbolic links are +never used. However, for each symbolic link listed on the command +line, @command{chmod} changes the permissions of the pointed-to file. +In contrast, @command{chmod} ignores symbolic links encountered during +recursive directory traversals. + +A successful use of @command{chmod} clears the set-group-ID bit of a +regular file if the file's group ID does not match the user's +effective group ID or one of the user's supplementary group IDs, +unless the user has appropriate privileges. Additional restrictions +may cause the set-user-ID and set-group-ID bits of @var{mode} or +@var{ref_file} to be ignored. This behavior depends on the policy and +functionality of the underlying @code{chmod} system call. When in +doubt, check the underlying system behavior. + +If used, @var{mode} specifies the new file mode bits. +For details, see the section on @ref{File permissions}. +If you really want @var{mode} to have a leading @samp{-}, you should +use @option{--} first, e.g., @samp{chmod -- -w file}. Typically, +though, @samp{chmod a-w file} is preferable, and @command{chmod -w +file} (without the @option{--}) complains if it behaves differently +from what @samp{chmod a-w file} would do. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -c +@itemx --changes +@opindex -c +@opindex --changes +Verbosely describe the action for each @var{file} whose permissions +actually changes. + +@item -f +@itemx --silent +@itemx --quiet +@opindex -f +@opindex --silent +@opindex --quiet +@cindex error messages, omitting +Do not print error messages about files whose permissions cannot be +changed. + +@itemx --preserve-root +@opindex --preserve-root +@cindex root directory, disallow recursive modification +Fail upon any attempt to recursively change the root directory, @file{/}. +Without @option{--recursive}, this option has no effect. +@xref{Treating / specially}. + +@itemx --no-preserve-root +@opindex --no-preserve-root +@cindex root directory, allow recursive modification +Cancel the effect of any preceding @option{--preserve-root} option. +@xref{Treating / specially}. + +@item -v +@itemx --verbose +@opindex -v +@opindex --verbose +Verbosely describe the action or non-action taken for every @var{file}. + +@item --reference=@var{ref_file} +@opindex --reference +Change the mode of each @var{file} to be the same as that of @var{ref_file}. +@xref{File permissions}. +If @var{ref_file} is a symbolic link, do not use the mode +of the symbolic link, but rather that of the file it refers to. + +@item -R +@itemx --recursive +@opindex -R +@opindex --recursive +@cindex recursively changing access permissions +Recursively change permissions of directories and their contents. + +@end table + +@exitstatus + + +@node touch invocation +@section @command{touch}: Change file timestamps + +@pindex touch +@cindex changing file timestamps +@cindex file timestamps, changing +@cindex timestamps, changing file + +@command{touch} changes the access and/or modification times of the +specified files. Synopsis: + +@example +touch [@var{option}]@dots{} @var{file}@dots{} +@end example + +@cindex empty files, creating +Any @var{file} that does not exist is created empty. + +A @var{file} of @samp{-} causes @command{touch} to change the +times of the file associated with standard output. + +@cindex permissions, for changing file timestamps +If changing both the access and modification times to the current +time, @command{touch} can change the timestamps for files that the user +running it does not own but has write permission for. Otherwise, the +user must own the files. + +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}. +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 +the atime doesn't change, nor does it modify the file, so the mtime +doesn't change. Yet, something about the file itself has changed, +and this must be noted somewhere. This is the job of the ctime field. +This is necessary, so that, for example, a backup program can make a +fresh copy of the file, including the new permissions value. +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. + +@vindex TZ +Time stamps assume the time zone rules specified by the @env{TZ} +environment variable, or by the system default rules if @env{TZ} is +not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ}, +libc, The GNU C Library}. You can avoid ambiguities during +daylight saving transitions by using @sc{utc} time stamps. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -a +@itemx --time=atime +@itemx --time=access +@itemx --time=use +@opindex -a +@opindex --time +@opindex atime@r{, changing} +@opindex access @r{time, changing} +@opindex use @r{time, changing} +Change the access time only. + +@item -c +@itemx --no-create +@opindex -c +@opindex --no-create +Do not create files that do not exist. + +@item -d +@itemx --date=@var{time} +@opindex -d +@opindex --date +@opindex time +Use @var{time} instead of the current time. It can contain month names, +time zones, @samp{am} and @samp{pm}, @samp{yesterday}, etc. For +example, @option{--date="2004-02-27 14:19:13.489392193 +0530"} +specifies the instant of time that is 489,392,193 nanoseconds after +February 27, 2004 at 2:19:13 PM in a time zone that is 5 hours and 30 +minutes east of @acronym{UTC}. @xref{Date input formats}. +File systems that do not support high-resolution time stamps +silently ignore any excess precision here. + +@item -f +@opindex -f +@cindex BSD @command{touch} compatibility +Ignored; for compatibility with BSD versions of @command{touch}. + +@item -m +@itemx --time=mtime +@itemx --time=modify +@opindex -m +@opindex --time +@opindex mtime@r{, changing} +@opindex modify @r{time, changing} +Change the modification time only. + +@item -r @var{file} +@itemx --reference=@var{file} +@opindex -r +@opindex --reference +Use the times of the reference @var{file} instead of the current time. +If this option is combined with the @option{--date=@var{time}} +(@option{-d @var{time}}) option, the reference @var{file}'s time is +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}. + +@item -t [[@var{CC}]@var{YY}]@var{MMDDhhmm}[.@var{ss}] +Use the argument (optional four-digit or two-digit years, months, +days, hours, minutes, optional seconds) instead of the current time. +If the year is specified with only two digits, then @var{CC} +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. + +@end table + +@vindex _POSIX2_VERSION +On older systems, @command{touch} supports an obsolete syntax, as follows. +If no timestamp is given with any of the @option{-d}, @option{-r}, or +@option{-t} options, and if there are two or more @var{file}s and the +first @var{file} is of the form @samp{@var{MMDDhhmm}[@var{YY}]} and this +would be a valid argument to the @option{-t} option (if the @var{YY}, if +any, were moved to the front), and if the represented year +is in the range 1969--1999, that argument is interpreted as the time +for the other files instead of as a file name. +This obsolete behavior can be enabled or disabled with the +@env{_POSIX2_VERSION} environment variable (@pxref{Standards +conformance}), but portable scripts should avoid commands whose +behavior depends on this variable. +For example, use @samp{touch ./12312359 main.c} or @samp{touch -t +12312359 main.c} rather than the ambiguous @samp{touch 12312359 main.c}. + +@exitstatus + + +@node Disk usage +@chapter Disk usage + +@cindex disk usage + +No disk can hold an infinite amount of data. These commands report +how much disk storage is in use or available, report other file and +file status information, and write buffers to disk. + +@menu +* 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 memory and disk. +@end menu + + +@node df invocation +@section @command{df}: Report file system disk space usage + +@pindex df +@cindex file system disk usage +@cindex disk usage by file system + +@command{df} reports the amount of disk space used and available on +file systems. Synopsis: + +@example +df [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +With no arguments, @command{df} reports the space used and available on all +currently mounted file systems (of all types). Otherwise, @command{df} +reports on the file system containing each argument @var{file}. + +Normally the disk space is printed in units of +1024 bytes, but this can be overridden (@pxref{Block size}). +Non-integer quantities are rounded up to the next higher unit. + +@cindex disk device file +@cindex device file, disk +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 +on unmounted file systems, because on most kinds of systems doing so +requires extremely nonportable intimate knowledge of file system +structures. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -a +@itemx --all +@opindex -a +@opindex --all +@cindex automounter file systems +@cindex ignore file systems +Include in the listing dummy file systems, which +are omitted by default. Such file systems are typically special-purpose +pseudo-file-systems, such as automounter entries. + +@item -B @var{size} +@itemx --block-size=@var{size} +@opindex -B +@opindex --block-size +@cindex file system sizes +Scale sizes by @var{size} before printing them (@pxref{Block size}). +For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes. + +@optHumanReadable + +@item -H +@opindex -H +Equivalent to @option{--si}. + +@item -i +@itemx --inodes +@opindex -i +@opindex --inodes +@cindex inode usage +List inode usage information instead of block usage. An inode (short +for index node) contains information about a file such as its owner, +permissions, timestamps, and location on the disk. + +@item -k +@opindex -k +@cindex kibibytes for file system sizes +Print sizes in 1024-byte blocks, overriding the default block size +(@pxref{Block size}). +This option is equivalent to @option{--block-size=1K}. + +@item -l +@itemx --local +@opindex -l +@opindex --local +@cindex file system types, limiting output to certain +Limit the listing to local file systems. By default, remote file systems +are also listed. + +@item --no-sync +@opindex --no-sync +@cindex file system space, retrieving old data more quickly +Do not invoke the @code{sync} system call before getting any usage data. +This may make @command{df} run significantly faster on systems with many +disks, but on some systems (notably SunOS) the results may be slightly +out of date. This is the default. + +@item -P +@itemx --portability +@opindex -P +@opindex --portability +@cindex one-line output format +@cindex @acronym{POSIX} output format +@cindex portable output format +@cindex output format, portable +Use the @acronym{POSIX} output format. This is like the default format except +for the following: + +@enumerate +@item +The information about each file system is always printed on exactly +one line; a mount device is never put on a line by itself. This means +that if the mount device name is more than 20 characters long (e.g., for +some network mounts), the columns are misaligned. + +@item +The labels in the header output line are changed to conform to @acronym{POSIX}. + +@item +The default block size and output format are unaffected by the +@env{DF_BLOCK_SIZE}, @env{BLOCK_SIZE} and @env{BLOCKSIZE} environment +variables. However, the default block size is still affected by +@env{POSIXLY_CORRECT}: it is 512 if @env{POSIXLY_CORRECT} is set, 1024 +otherwise. @xref{Block size}. +@end enumerate + +@optSi + +@item --sync +@opindex --sync +@cindex file system space, retrieving current data more slowly +Invoke the @code{sync} system call before getting any usage data. On +some systems (notably SunOS), doing this yields more up to date results, +but in general this option makes @command{df} much slower, especially when +there are many or very busy file systems. + +@item -t @var{fstype} +@itemx --type=@var{fstype} +@opindex -t +@opindex --type +@cindex file system types, limiting output to certain +Limit the listing to file systems of type @var{fstype}. Multiple +file system types can be specified by giving multiple @option{-t} options. +By default, nothing is omitted. + +@item -T +@itemx --print-type +@opindex -T +@opindex --print-type +@cindex file system types, printing +Print each file system's type. The types printed here are the same ones +you can include or exclude with @option{-t} and @option{-x}. The particular +types printed are whatever is supported by the system. Here are some of +the common names (this list is certainly not exhaustive): + +@table @samp + +@item nfs +@cindex @acronym{NFS} file system type +An @acronym{NFS} file system, i.e., one mounted over a network from another +machine. This is the one type name which seems to be used uniformly by +all systems. + +@item 4.2@r{, }ufs@r{, }efs@dots{} +@cindex Linux file system types +@cindex local file system types +@opindex 4.2 @r{file system type} +@opindex ufs @r{file system type} +@opindex efs @r{file system type} +A file system on a locally-mounted hard disk. (The system might even +support more than one type here; Linux does.) + +@item hsfs@r{, }cdfs +@cindex CD-ROM file system type +@cindex High Sierra file system +@opindex hsfs @r{file system type} +@opindex cdfs @r{file system type} +A file system on a CD-ROM drive. HP-UX uses @samp{cdfs}, most other +systems use @samp{hsfs} (@samp{hs} for ``High Sierra''). + +@item pcfs +@cindex PC file system +@cindex DOS file system +@cindex MS-DOS file system +@cindex diskette file system +@opindex pcfs +An MS-DOS file system, usually on a diskette. + +@end table + +@item -x @var{fstype} +@itemx --exclude-type=@var{fstype} +@opindex -x +@opindex --exclude-type +Limit the listing to file systems not of type @var{fstype}. +Multiple file system types can be eliminated by giving multiple +@option{-x} options. By default, no file system types are omitted. + +@item -v +Ignored; for compatibility with System V versions of @command{df}. + +@end table + +@exitstatus +Failure includes the case where no output is generated, so you can +inspect the exit status of a command like @samp{df -t ext3 -t reiserfs +@var{dir}} to test whether @var{dir} is on a file system of type +@samp{ext3} or @samp{reiserfs}. + + +@node du invocation +@section @command{du}: Estimate file space usage + +@pindex du +@cindex file space usage +@cindex disk usage for files + +@command{du} reports the amount of disk space used by the specified files +and for each subdirectory (of directory arguments). Synopsis: + +@example +du [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +With no arguments, @command{du} reports the disk space for the current +directory. Normally the disk space is printed in units of +1024 bytes, but this can be overridden (@pxref{Block size}). +Non-integer quantities are rounded up to the next higher unit. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -a +@itemx --all +@opindex -a +@opindex --all +Show counts for all files, not just directories. + +@itemx --apparent-size +@opindex --apparent-size +Print apparent sizes, rather than disk usage. The apparent size of a +file is the number of bytes reported by @code{wc -c} on regular files, +or more generally, @code{ls -l --block-size=1} or @code{stat --format=%s}. +For example, a file containing the word @samp{zoo} with no newline would, +of course, have an apparent size of 3. Such a small file may require +anywhere from 0 to 16 KiB or more of disk space, depending on +the type and configuration of the file system on which the file resides. +However, a sparse file created with this command: + +@example +dd bs=1 seek=2GiB if=/dev/null of=big +@end example + +@noindent +has an apparent size of 2 GiB, yet on most modern +systems, it actually uses almost no disk space. + +@item -b +@itemx --bytes +@opindex -b +@opindex --bytes +Equivalent to @code{--apparent-size --block-size=1}. + +@item -B @var{size} +@itemx --block-size=@var{size} +@opindex -B +@opindex --block-size +@cindex file sizes +Scale sizes by @var{size} before printing them (@pxref{Block size}). +For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes. + +@item -c +@itemx --total +@opindex -c +@opindex --total +@cindex grand total of disk space +Print a grand total of all arguments after all arguments have +been processed. This can be used to find out the total disk usage of +a given set of files or directories. + +@item -D +@itemx --dereference-args +@opindex -D +@opindex --dereference-args +Dereference symbolic links that are command line arguments. +Does not affect other symbolic links. This is helpful for finding +out the disk usage of directories, such as @file{/usr/tmp}, which +are often symbolic links. + +@itemx --files0-from=@var{FILE} +@opindex --files0-from=@var{FILE} +@cindex including files from @command{du} +Rather than processing files named on the command line, process those +named in file @var{FILE}; each name is terminated by a null byte. +This is useful with the @option{--total} (@option{-c}) option when +the list of file names is so long that it may exceed a command line +length limitation. +In such cases, running @command{du} via @command{xargs} is undesirable +because it splits the list into pieces and makes @command{du} print a +total for each sublist rather than for the entire list. +One way to produce a list of null-byte-terminated file names is with @sc{gnu} +@command{find}, using its @option{-print0} predicate. +Do not specify any @var{FILE} on the command line when using this option. + +@optHumanReadable + +@item -H +@opindex -H +Currently, @option{-H} is the same as @option{--si}, +except that @option{-H} evokes a warning. +This option will be changed to be equivalent to +@option{--dereference-args} (@option{-D}). + +@item -k +@opindex -k +@cindex kibibytes for file sizes +Print sizes in 1024-byte blocks, overriding the default block size +(@pxref{Block size}). +This option is equivalent to @option{--block-size=1K}. + +@item -l +@itemx --count-links +@opindex -l +@opindex --count-links +@cindex hard links, counting in @command{du} +Count the size of all files, even if they have appeared already (as a +hard link). + +@item -L +@itemx --dereference +@opindex -L +@opindex --dereference +@cindex symbolic links, dereferencing in @command{du} +Dereference symbolic links (show the disk space used by the file +or directory that the link points to instead of the space used by +the link). + +@item -m +@opindex -m +@cindex mebibytes for file sizes +Print sizes in 1,048,576-byte blocks, overriding the default block size +(@pxref{Block size}). +This option is equivalent to @option{--block-size=1M}. + +@item -P +@itemx --no-dereference +@opindex -P +@opindex --no-dereference +@cindex symbolic links, dereferencing in @command{du} +For each symbolic links encountered by @command{du}, +consider the disk space used by the symbolic link. + +@item --max-depth=@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 null byte 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. + +@itemx --si +@opindex --si +@cindex SI output +Append an SI-style abbreviation to each size, such as @samp{MB} for +megabytes. Powers of 1000 are used, not 1024; @samp{MB} stands for +1,000,000 bytes. Use the @option{-h} or @option{--human-readable} option if +you prefer powers of 1024. + +@item -s +@itemx --summarize +@opindex -s +@opindex --summarize +Display only a total for each argument. + +@item -S +@itemx --separate-dirs +@opindex -S +@opindex --separate-dirs +Report the size of each directory separately, not including the sizes +of subdirectories. + +@itemx --time +@opindex --time +@cindex last modified dates, displaying in @command{du} +Show time of the most recent modification of any file in the directory, +or any of its subdirectories. + +@itemx --time=ctime +@itemx --time=status +@itemx --time=use +@opindex --time +@opindex ctime@r{, show the most recent} +@opindex status time@r{, show the most recent} +@opindex use time@r{, show the most recent} +Show the most recent status change time (the @samp{ctime} in the inode) of +any file in the directory, instead of the modification time. + +@itemx --time=atime +@itemx --time=access +@opindex --time +@opindex atime@r{, show the most recent} +@opindex access time@r{, show the most recent} +Show the most recent access time (the @samp{atime} in the inode) of +any file in the directory, instead of the modification time. + +@item --time-style=@var{style} +@opindex --time-style +@cindex time style +List timestamps in style @var{style}. This option has an effect only if +the @option{--time} option is also specified. The @var{style} should +be one of the following: + +@table @samp +@item +@var{format} +@vindex LC_TIME +List timestamps using @var{format}, where @var{format} is interpreted +like the format argument of @command{date} (@pxref{date invocation}). +For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes +@command{du} to list timestamps like @samp{2002-03-30 23:45:56}. As +with @command{date}, @var{format}'s interpretation is affected by the +@env{LC_TIME} locale category. + +@item full-iso +List timestamps in full using @acronym{ISO} 8601 date, time, and time zone +format with nanosecond precision, e.g., @samp{2002-03-30 +23:45:56.477817180 -0700}. This style is equivalent to +@samp{+%Y-%m-%d %H:%M:%S.%N %z}. + +@item long-iso +List @acronym{ISO} 8601 date and time in minutes, e.g., +@samp{2002-03-30 23:45}. These timestamps are shorter than +@samp{full-iso} timestamps, and are usually good enough for everyday +work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}. + +@item iso +List @acronym{ISO} 8601 dates for timestamps, e.g., @samp{2002-03-30}. +This style is equivalent to @samp{+%Y-%m-%d}. +@end table + +@vindex TIME_STYLE +You can specify the default value of the @option{--time-style} option +with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set +the default style is @samp{long-iso}. For compatibility with @command{ls}, +if @env{TIME_STYLE} begins with @samp{+} and contains a newline, +the newline and any later characters are ignored; if @env{TIME_STYLE} +begins with @samp{posix-} the @samp{posix-} is ignored; and if +@env{TIME_STYLE} is @samp{locale} it is ignored. + +@item -x +@itemx --one-file-system +@opindex -x +@opindex --one-file-system +@cindex one file system, restricting @command{du} to +Skip directories that are on different file systems from the one that +the argument being processed is on. + +@item --exclude=@var{PATTERN} +@opindex --exclude=@var{PATTERN} +@cindex excluding files from @command{du} +When recursing, skip subdirectories or files matching @var{PATTERN}. +For example, @code{du --exclude='*.o'} excludes files whose names +end in @samp{.o}. + +@item -X @var{FILE} +@itemx --exclude-from=@var{FILE} +@opindex -X @var{FILE} +@opindex --exclude-from=@var{FILE} +@cindex excluding files from @command{du} +Like @option{--exclude}, except take the patterns to exclude from @var{FILE}, +one per line. If @var{FILE} is @samp{-}, take the patterns from standard +input. + +@end table + +@cindex NFS mounts from BSD to HP-UX +On BSD systems, @command{du} reports sizes that are half the correct +values for files that are NFS-mounted from HP-UX systems. On HP-UX +systems, it reports sizes that are twice the correct values for +files that are NFS-mounted from BSD systems. This is due to a flaw +in HP-UX; it also affects the HP-UX @command{du} program. + +@exitstatus + + +@node stat invocation +@section @command{stat}: Report file or file system status + +@pindex stat +@cindex file status +@cindex file system status + +@command{stat} displays information about the specified file(s). Synopsis: + +@example +stat [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +With no option, @command{stat} reports all information about the given files. +But it also can be used to report the information of the file systems the +given files are located on. If the files are links, @command{stat} can +also give information about the files the links point to. + + +@table @samp + +@item -L +@itemx --dereference +@opindex -L +@opindex --dereference +@cindex symbolic links, dereferencing in @command{stat} +Change how @command{stat} treats symbolic links. +With this option, @command{stat} acts on the file referenced +by each symbolic link argument. +Without it, @command{stat} acts on any symbolic link argument directly. + +@item -f +@itemx --file-system +@opindex -f +@opindex --file-system +@cindex file systems +Report information about the file systems where the given files are located +instead of information about the files themselves. + +@item -c +@itemx --format=@var{format} +@opindex -c +@opindex --format=@var{format} +@cindex output format +Use @var{format} rather than the default format. +@var{format} is automatically newline-terminated, so +running a command like the following with two or more @var{file} +operands produces a line of output for each operand: +@example +$ stat --format=%d:%i / /usr +2050:2 +2057:2 +@end example + +@itemx --printf=@var{format} +@opindex --printf=@var{format} +@cindex output format +Use @var{format} rather than the default format. +Like @option{--format}, but interpret backslash escapes, +and do not output a mandatory trailing newline. +If you want a newline, include @samp{\n} in the @var{format}. +Here's how you would use @option{--printf} to print the device +and inode numbers of @file{/} and @file{/usr}: +@example +$ stat --printf='%d:%i\n' / /usr +2050:2 +2057:2 +@end example + +@item -t +@itemx --terse +@opindex -t +@opindex --terse +@cindex terse output +Print the information in terse form, suitable for parsing by other programs. + +The valid format sequences for files are: + +@itemize @bullet +@item %a - Access rights in octal +@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 %d - Device number in decimal +@item %D - Device number in hex +@item %f - Raw mode in hex +@item %F - File type +@item %g - Group ID of owner +@item %G - Group name of owner +@item %h - Number of hard links +@item %i - Inode number +@item %n - File name +@item %N - Quoted file name with dereference if symbolic link +@item %o - I/O block size +@item %s - Total size, in bytes +@item %t - Major device type in hex +@item %T - Minor device type in hex +@item %u - User ID of owner +@item %U - User name of owner +@item %x - Time of last access +@item %X - Time of last access as seconds since Epoch +@item %y - Time of last modification +@item %Y - Time of last modification as seconds since Epoch +@item %z - Time of last change +@item %Z - Time of last change as seconds since Epoch +@end itemize + +The valid format sequences for file systems are: + +@itemize @bullet +@item %a - Free blocks available to non-super-user +@item %b - Total data blocks in file system +@item %c - Total file nodes in file system +@item %d - Free file nodes in file system +@item %f - Free blocks in file system +@item %i - File System ID in hex +@item %l - Maximum length of file names +@item %n - File name +@item %s - Block size (for faster transfers) +@item %S - Fundamental block size (for block counts) +@item %t - Type in hex +@item %T - Type in human readable form +@end itemize + +@vindex TZ +Time stamps are listed according to the time zone rules specified by +the @env{TZ} environment variable, or by the system default rules if +@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone +with @env{TZ}, libc, The GNU C Library}. +@end table + +@exitstatus + + +@node sync invocation +@section @command{sync}: Synchronize data on disk with memory + +@pindex sync +@cindex synchronize disk and memory + +@cindex superblock, writing +@cindex inodes, written buffered +@command{sync} writes any data buffered in memory out to disk. This can +include (but is not limited to) modified superblocks, modified inodes, +and delayed reads and writes. This must be implemented by the kernel; +The @command{sync} program does nothing but exercise the @code{sync} system +call. + +@cindex crashes and corruption +The kernel keeps data in memory to avoid doing (relatively slow) disk +reads and writes. This improves performance, but if the computer +crashes, data may be lost or the file system corrupted as a +result. The @command{sync} command ensures everything in memory +is written to disk. + +Any arguments are ignored, except for a lone @option{--help} or +@option{--version} (@pxref{Common options}). + +@exitstatus + + +@node Printing text +@chapter Printing text + +@cindex printing text, commands for +@cindex commands for printing text + +This section describes commands that display text strings. + +@menu +* echo invocation:: Print a line of text. +* printf invocation:: Format and print data. +* yes invocation:: Print a string until interrupted. +@end menu + + +@node echo invocation +@section @command{echo}: Print a line of text + +@pindex echo +@cindex displaying text +@cindex printing text +@cindex text, displaying +@cindex arbitrary text, displaying + +@command{echo} writes each given @var{string} to standard output, with a +space between each and a newline after the last one. Synopsis: + +@example +echo [@var{option}]@dots{} [@var{string}]@dots{} +@end example + +The program accepts the following options. Also see @ref{Common options}. +Options must precede operands, and the normally-special argument +@samp{--} has no special meaning and is treated like any other +@var{string}. + +@table @samp +@item -n +@opindex -n +Do not output the trailing newline. + +@item -e +@opindex -e +@cindex backslash escapes +Enable interpretation of the following backslash-escaped characters in +each @var{string}: + +@table @samp +@item \a +alert (bell) +@item \b +backspace +@item \c +suppress trailing newline +@item \f +form feed +@item \n +new line +@item \r +carriage return +@item \t +horizontal tab +@item \v +vertical tab +@item \\ +backslash +@item \0@var{nnn} +the eight-bit value that is the octal number @var{nnn} +(zero to three octal digits) +@item \@var{nnn} +the eight-bit value that is the octal number @var{nnn} +(one to three octal digits) +@item \x@var{hh} +the eight-bit value that is the hexadecimal number @var{hh} +(one or two hexadecimal digits) +@end table + +@item -E +@opindex -E +@cindex backslash escapes +Disable interpretation of backslash escapes in each @var{string}. +This is the default. If @option{-e} and @option{-E} are both +specified, the last one given takes effect. + +@end table + +@vindex POSIXLY_CORRECT +If the @env{POSIXLY_CORRECT} environment variable is set, then when +@command{echo}'s first argument is not @option{-n} it outputs +option-like arguments instead of treating them as options. For +example, @code{echo -ne hello} outputs @samp{-ne hello} instead of +plain @samp{hello}. + +@acronym{POSIX} does not require support for any options, and says +that the behavior of @command{echo} is implementation-defined if any +@var{string} contains a backslash or if the first argument is +@option{-n}. Portable programs can use the @command{printf} command +if they need to omit trailing newlines or output control characters or +backslashes. @xref{printf invocation}. + +@exitstatus + + +@node printf invocation +@section @command{printf}: Format and print data + +@pindex printf +@command{printf} does formatted printing of text. Synopsis: + +@example +printf @var{format} [@var{argument}]@dots{} +@end example + +@command{printf} prints the @var{format} string, interpreting @samp{%} +directives and @samp{\} escapes to format numeric and string arguments +in a way that is mostly similar to the C @samp{printf} function. The +differences are as follows: + +@itemize @bullet + +@item +The @var{format} argument is reused as necessary to convert all the +given @var{argument}s. For example, the command @samp{printf %s a b} +outputs @samp{ab}. + +@item +Missing @var{argument}s are treated as null strings or as zeros, +depending on whether the context expects a string or a number. For +example, the command @samp{printf %sx%d} prints @samp{x0}. + +@item +@kindex \c +An additional escape, @samp{\c}, causes @command{printf} to produce no +further output. For example, the command @samp{printf 'A%sC\cD%sF' B +E} prints @samp{ABC}. + +@item +The hexadecimal escape sequence @samp{\x@var{hh}} has at most two +digits, as opposed to C where it can have an unlimited number of +digits. For example, the command @samp{printf '\x07e'} prints two +bytes, whereas the C statement @samp{printf ("\x07e")} prints just +one. + +@item +@kindex %b +@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. +If a precision is also given, it limits the number of bytes printed +from the converted string. + +@item +Numeric arguments must be single C constants, possibly with leading +@samp{+} or @samp{-}. For example, @samp{printf %.4d -3} outputs +@samp{-0003}. + +@item +@vindex POSIXLY_CORRECT +If the leading character of a numeric argument is @samp{"} or @samp{'} +then its value is the numeric value of the immediately following +character. Any remaining characters are silently ignored if the +@env{POSIXLY_CORRECT} environment variable is set; otherwise, a +warning is printed. For example, @samp{printf "%d" "'a"} outputs +@samp{97} on hosts that use the @acronym{ASCII} character set, since +@samp{a} has the numeric value 97 in @acronym{ASCII}. + +@end itemize + +@vindex LC_NUMERIC +A floating-point argument must use a period before any fractional +digits, but is printed according to the @env{LC_NUMERIC} category of the +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. + +@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, +and @samp{\x@var{hh}} as a hexadecimal number (if @var{hh} is 1 to 2 hex +digits) specifying a character to print. + +@kindex \uhhhh +@kindex \Uhhhhhhhh +@cindex Unicode +@cindex ISO/IEC 10646 +@vindex LC_CTYPE +@command{printf} interprets two character syntaxes introduced in +@acronym{ISO} C 99: +@samp{\u} for 16-bit Unicode (@acronym{ISO}/@acronym{IEC} 10646) +characters, specified as +four hexadecimal digits @var{hhhh}, and @samp{\U} for 32-bit Unicode +characters, specified as eight hexadecimal digits @var{hhhhhhhh}. +@command{printf} outputs the Unicode characters +according to the @env{LC_CTYPE} locale. + +The processing of @samp{\u} and @samp{\U} requires a full-featured +@code{iconv} facility. It is activated on systems with glibc 2.2 (or newer), +or when @code{libiconv} is installed prior to this package. Otherwise +@samp{\u} and @samp{\U} will print as-is. + +The only options are a lone @option{--help} or +@option{--version}. @xref{Common options}. +Options must precede operands. + +The Unicode character syntaxes are useful for writing strings in a locale +independent way. For example, a string containing the Euro currency symbol + +@example +$ /usr/local/bin/printf '\u20AC 14.95' +@end example + +@noindent +will be output correctly in all locales supporting the Euro symbol +(@acronym{ISO}-8859-15, UTF-8, and others). Similarly, a Chinese string + +@example +$ /usr/local/bin/printf '\u4e2d\u6587' +@end example + +@noindent +will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8, etc). + +Note that in these examples, the full name of @command{printf} has been +given, to distinguish it from the GNU @code{bash} built-in function +@command{printf}. + +For larger strings, you don't need to look up the hexadecimal code +values of each character one by one. @acronym{ASCII} characters mixed with \u +escape sequences is also known as the JAVA source file encoding. You can +use GNU recode 3.5c (or newer) to convert strings to this encoding. Here +is how to convert a piece of text into a shell script which will output +this text in a locale-independent way: + +@smallexample +$ LC_CTYPE=zh_CN.big5 /usr/local/bin/printf \ + '\u4e2d\u6587\n' > sample.txt +$ recode BIG5..JAVA < sample.txt \ + | sed -e "s|^|/usr/local/bin/printf '|" -e "s|$|\\\\n'|" \ + > sample.sh +@end smallexample + +@exitstatus + + +@node yes invocation +@section @command{yes}: Print a string until interrupted + +@pindex yes +@cindex repeated output of a string + +@command{yes} prints the command line arguments, separated by spaces and +followed by a newline, forever until it is killed. If no arguments are +given, it prints @samp{y} followed by a newline forever until killed. + +Upon a write error, @command{yes} exits with status @samp{1}. + +The only options are a lone @option{--help} or @option{--version}. +To output an argument that begins with +@samp{-}, precede it with @option{--}, e.g., @samp{yes -- --help}. +@xref{Common options}. + + +@node Conditions +@chapter Conditions + +@cindex conditions +@cindex commands for exit status +@cindex exit status commands + +This section describes commands that are primarily useful for their exit +status, rather than their output. Thus, they are often used as the +condition of shell @code{if} statements, or as the last command in a +pipeline. + +@menu +* false invocation:: Do nothing, unsuccessfully. +* true invocation:: Do nothing, successfully. +* test invocation:: Check file types and compare values. +* expr invocation:: Evaluate expressions. +@end menu + + +@node false invocation +@section @command{false}: Do nothing, unsuccessfully + +@pindex false +@cindex do nothing, unsuccessfully +@cindex failure exit status +@cindex exit status of @command{false} + +@command{false} does nothing except return an exit status of 1, meaning +@dfn{failure}. It can be used as a place holder in shell scripts +where an unsuccessful command is needed. +In most modern shells, @command{false} is a built-in command, so when +you use @samp{false} in a script, you're probably using the built-in +command, not the one documented here. + +@command{false} honors the @option{--help} and @option{--version} options. + +This version of @command{false} is implemented as a C program, and is thus +more secure and faster than a shell script implementation, and may safely +be used as a dummy shell for the purpose of disabling accounts. + +Note that @command{false} (unlike all other programs documented herein) +exits unsuccessfully, even when invoked with +@option{--help} or @option{--version}. + +Portable programs should not assume that the exit status of +@command{false} is 1, as it is greater than 1 on some +non-@acronym{GNU} hosts. + + +@node true invocation +@section @command{true}: Do nothing, successfully + +@pindex true +@cindex do nothing, successfully +@cindex no-op +@cindex successful exit +@cindex exit status of @command{true} + +@command{true} does nothing except return an exit status of 0, meaning +@dfn{success}. It can be used as a place holder in shell scripts +where a successful command is needed, although the shell built-in +command @code{:} (colon) may do the same thing faster. +In most modern shells, @command{true} is a built-in command, so when +you use @samp{true} in a script, you're probably using the built-in +command, not the one documented here. + +@command{true} honors the @option{--help} and @option{--version} options. + +Note, however, that it is possible to cause @command{true} +to exit with nonzero status: with the @option{--help} or @option{--version} +option, and with standard +output already closed or redirected to a file that evokes an I/O error. +For example, using a Bourne-compatible shell: + +@example +$ ./true --version >&- +./true: write error: Bad file number +$ ./true --version > /dev/full +./true: write error: No space left on device +@end example + +This version of @command{true} is implemented as a C program, and is thus +more secure and faster than a shell script implementation, and may safely +be used as a dummy shell for the purpose of disabling accounts. + +@node test invocation +@section @command{test}: Check file types and compare values + +@pindex test +@cindex check file types +@cindex compare values +@cindex expression evaluation + +@command{test} returns a status of 0 (true) or 1 (false) depending on the +evaluation of the conditional expression @var{expr}. Each part of the +expression must be a separate argument. + +@command{test} has file status checks, string operators, and numeric +comparison operators. + +@command{test} has an alternate form that uses opening and closing +square brackets instead a leading @samp{test}. For example, instead +of @samp{test -d /}, you can write @samp{[ -d / ]}. The square +brackets must be separate arguments; for example, @samp{[-d /]} does +not have the desired effect. Since @samp{test @var{expr}} and @samp{[ +@var{expr} ]} have the same meaning, only the former form is discussed +below. + +Synopses: + +@example +test @var{expression} +test +[ @var{expression} ] +[ ] +[ @var{option} +@end example + +@cindex conflicts with shell built-ins +@cindex built-in shell commands, conflicts with +Because most shells have a built-in @command{test} command, using an +unadorned @command{test} in a script or interactively may get you +different functionality than that described here. + +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 +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, +invoke the commands @samp{[ --help} and @samp{[ --version}, without +the usual closing brackets. @xref{Common options}. + +@cindex exit status of @command{test} +Exit status: + +@display +0 if the expression is true, +1 if the expression is false, +2 if an error occurred. +@end display + +@menu +* File type tests:: -[bcdfhLpSt] +* Access permission tests:: -[gkruwxOG] +* File characteristic tests:: -e -s -nt -ot -ef +* String tests:: -z -n = != +* Numeric tests:: -eq -ne -lt -le -gt -ge +* Connectives for test:: ! -a -o +@end menu + + +@node File type tests +@subsection File type tests + +@cindex file type tests + +These options test for particular types of files. (Everything's a file, +but not all files are the same!) + +@table @samp + +@item -b @var{file} +@opindex -b +@cindex block special check +True if @var{file} exists and is a block special device. + +@item -c @var{file} +@opindex -c +@cindex character special check +True if @var{file} exists and is a character special device. + +@item -d @var{file} +@opindex -d +@cindex directory check +True if @var{file} exists and is a directory. + +@item -f @var{file} +@opindex -f +@cindex regular file check +True if @var{file} exists and is a regular file. + +@item -h @var{file} +@itemx -L @var{file} +@opindex -L +@opindex -h +@cindex symbolic link check +True if @var{file} exists and is a symbolic link. +Unlike all other file-related tests, this test does not dereference +@var{file} if it is a symbolic link. + +@item -p @var{file} +@opindex -p +@cindex named pipe check +True if @var{file} exists and is a named pipe. + +@item -S @var{file} +@opindex -S +@cindex socket check +True if @var{file} exists and is a socket. + +@item -t @var{fd} +@opindex -t +@cindex terminal check +True if @var{fd} is a file descriptor that is associated with a +terminal. + +@end table + + +@node Access permission tests +@subsection Access permission tests + +@cindex access permission tests +@cindex permission tests + +These options test for particular access permissions. + +@table @samp + +@item -g @var{file} +@opindex -g +@cindex set-group-ID check +True if @var{file} exists and has its set-group-ID bit set. + +@item -k @var{file} +@opindex -k +@cindex sticky bit check +True if @var{file} exists and has its @dfn{sticky} bit set. + +@item -r @var{file} +@opindex -r +@cindex readable file check +True if @var{file} exists and read permission is granted. + +@item -u @var{file} +@opindex -u +@cindex set-user-ID check +True if @var{file} exists and has its set-user-ID bit set. + +@item -w @var{file} +@opindex -w +@cindex writable file check +True if @var{file} exists and write permission is granted. + +@item -x @var{file} +@opindex -x +@cindex executable file check +True if @var{file} exists and execute permission is granted +(or search permission, if it is a directory). + +@item -O @var{file} +@opindex -O +@cindex owned by effective user ID check +True if @var{file} exists and is owned by the current effective user ID. + +@item -G @var{file} +@opindex -G +@cindex owned by effective group ID check +True if @var{file} exists and is owned by the current effective group ID. + +@end table + +@node File characteristic tests +@subsection File characteristic tests + +@cindex file characteristic tests + +These options test other file characteristics. + +@table @samp + +@item -e @var{file} +@opindex -e +@cindex existence-of-file check +True if @var{file} exists. + +@item -s @var{file} +@opindex -s +@cindex nonempty file check +True if @var{file} exists and has a size greater than zero. + +@item @var{file1} -nt @var{file2} +@opindex -nt +@cindex newer-than file check +True if @var{file1} is newer (according to modification date) than +@var{file2}, or if @var{file1} exists and @var{file2} does not. + +@item @var{file1} -ot @var{file2} +@opindex -ot +@cindex older-than file check +True if @var{file1} is older (according to modification date) than +@var{file2}, or if @var{file2} exists and @var{file1} does not. + +@item @var{file1} -ef @var{file2} +@opindex -ef +@cindex same file check +@cindex hard link check +True if @var{file1} and @var{file2} have the same device and inode +numbers, i.e., if they are hard links to each other. + +@end table + + +@node String tests +@subsection String tests + +@cindex string tests + +These options test string characteristics. You may need to quote +@var{string} arguments for the shell. For example: + +@example +test -n "$V" +@end example + +The quotes here prevent the wrong arguments from being passed to +@command{test} if @samp{$V} is empty or contains special characters. + +@table @samp + +@item -z @var{string} +@opindex -z +@cindex zero-length string check +True if the length of @var{string} is zero. + +@item -n @var{string} +@itemx @var{string} +@opindex -n +@cindex nonzero-length string check +True if the length of @var{string} is nonzero. + +@item @var{string1} = @var{string2} +@opindex = +@cindex equal string check +True if the strings are equal. + +@item @var{string1} != @var{string2} +@opindex != +@cindex not-equal string check +True if the strings are not equal. + +@end table + + +@node Numeric tests +@subsection Numeric tests + +@cindex numeric tests +@cindex arithmetic tests + +Numeric relationals. The arguments must be entirely numeric (possibly +negative), or the special expression @w{@code{-l @var{string}}}, which +evaluates to the length of @var{string}. + +@table @samp + +@item @var{arg1} -eq @var{arg2} +@itemx @var{arg1} -ne @var{arg2} +@itemx @var{arg1} -lt @var{arg2} +@itemx @var{arg1} -le @var{arg2} +@itemx @var{arg1} -gt @var{arg2} +@itemx @var{arg1} -ge @var{arg2} +@opindex -eq +@opindex -ne +@opindex -lt +@opindex -le +@opindex -gt +@opindex -ge +These arithmetic binary operators return true if @var{arg1} is equal, +not-equal, less-than, less-than-or-equal, greater-than, or +greater-than-or-equal than @var{arg2}, respectively. + +@end table + +For example: + +@example +test -1 -gt -2 && echo yes +@result{} yes +test -l abc -gt 1 && echo yes +@result{} yes +test 0x100 -eq 1 +@error{} test: integer expression expected before -eq +@end example + + +@node Connectives for test +@subsection Connectives for @command{test} + +@cindex logical connectives +@cindex connectives, logical + +The usual logical connectives. + +@table @samp + +@item ! @var{expr} +@opindex ! +True if @var{expr} is false. + +@item @var{expr1} -a @var{expr2} +@opindex -a +@cindex logical and operator +@cindex and operator +True if both @var{expr1} and @var{expr2} are true. + +@item @var{expr1} -o @var{expr2} +@opindex -o +@cindex logical or operator +@cindex or operator +True if either @var{expr1} or @var{expr2} is true. + +@end table + + +@node expr invocation +@section @command{expr}: Evaluate expressions + +@pindex expr +@cindex expression evaluation +@cindex evaluation of expressions + +@command{expr} evaluates an expression and writes the result on standard +output. Each token of the expression must be a separate argument. + +Operands are either integers or strings. Integers consist of one or +more decimal digits, with an optional leading @samp{-}. +@command{expr} converts +anything appearing in an operand position to an integer or a string +depending on the operation being applied to it. + +Strings are not quoted for @command{expr} itself, though you may need to +quote them to protect characters with special meaning to the shell, +e.g., spaces. However, regardless of whether it is quoted, a string +operand should not be a parenthesis or any of @command{expr}'s +operators like @code{+}, so you cannot safely pass an arbitrary string +@code{$str} to expr merely by quoting it to the shell. One way to +work around this is to use the @sc{gnu} extension @code{+}, +(e.g., @code{+ "$str" = foo}); a more portable way is to use +@code{@w{" $str"}} and to adjust the rest of the expression to take +the leading space into account (e.g., @code{@w{" $str" = " foo"}}). + +You should not pass a negative integer or a string with leading +@samp{-} as @command{expr}'s first argument, as it might be +misinterpreted as an option; this can be avoided by parenthesization. +Also, portable scripts should not use a string operand that happens to +take the form of an integer; this can be worked around by inserting +leading spaces as mentioned above. + +@cindex parentheses for grouping +Operators may be given as infix symbols or prefix keywords. Parentheses +may be used for grouping in the usual manner. You must quote +parentheses and many operators to avoid the shell evaluating them, +however. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. Options must precede operands. + +@cindex exit status of @command{expr} +Exit status: + +@display +0 if the expression is neither null nor 0, +1 if the expression is null or 0, +2 if the expression is invalid, +3 if an internal error occurred (e.g., arithmetic overflow). +@end display + +@menu +* String expressions:: + : match substr index length +* Numeric expressions:: + - * / % +* Relations for expr:: | & < <= = == != >= > +* Examples of expr:: Examples. +@end menu + + +@node String expressions +@subsection String expressions + +@cindex string expressions +@cindex expressions, string + +@command{expr} supports pattern matching and other string operators. These +have lower precedence than both the numeric and relational operators (in +the next sections). + +@table @samp + +@item @var{string} : @var{regex} +@cindex pattern matching +@cindex regular expression matching +@cindex matching patterns +Perform pattern matching. The arguments are converted to strings and the +second is considered to be a (basic, a la GNU @code{grep}) regular +expression, with a @code{^} implicitly prepended. The first argument is +then matched against this regular expression. + +If the match succeeds and @var{regex} uses @samp{\(} and @samp{\)}, the +@code{:} expression returns the part of @var{string} that matched the +subexpression; otherwise, it returns the number of characters matched. + +If the match fails, the @code{:} operator returns the null string if +@samp{\(} and @samp{\)} are used in @var{regex}, otherwise 0. + +@kindex \( @r{regexp operator} +Only the first @samp{\( @dots{} \)} pair is relevant to the return +value; additional pairs are meaningful only for grouping the regular +expression operators. + +@kindex \+ @r{regexp operator} +@kindex \? @r{regexp operator} +@kindex \| @r{regexp operator} +In the regular expression, @code{\+}, @code{\?}, and @code{\|} are +operators which respectively match one or more, zero or one, or separate +alternatives. SunOS and other @command{expr}'s treat these as regular +characters. (@acronym{POSIX} allows either behavior.) +@xref{Top, , Regular Expression Library, regex, Regex}, for details of +regular expression syntax. Some examples are in @ref{Examples of expr}. + +@item match @var{string} @var{regex} +@findex match +An alternative way to do pattern matching. This is the same as +@w{@samp{@var{string} : @var{regex}}}. + +@item substr @var{string} @var{position} @var{length} +@findex substr +Returns the substring of @var{string} beginning at @var{position} +with length at most @var{length}. If either @var{position} or +@var{length} is negative, zero, or non-numeric, returns the null string. + +@item index @var{string} @var{charset} +@findex index +Returns the first position in @var{string} where the first character in +@var{charset} was found. If no character in @var{charset} is found in +@var{string}, return 0. + +@item length @var{string} +@findex length +Returns the length of @var{string}. + +@item + @var{token} +@kindex + +Interpret @var{token} as a string, even if it is a keyword like @var{match} +or an operator like @code{/}. +This makes it possible to test @code{expr length + "$x"} or +@code{expr + "$x" : '.*/\(.\)'} and have it do the right thing even if +the value of @var{$x} happens to be (for example) @code{/} or @code{index}. +This operator is a @acronym{GNU} extension. Portable shell scripts should use +@code{@w{" $token"} : @w{' \(.*\)'}} instead of @code{+ "$token"}. + +@end table + +To make @command{expr} interpret keywords as strings, you must use the +@code{quote} operator. + + +@node Numeric expressions +@subsection Numeric expressions + +@cindex numeric expressions +@cindex expressions, numeric + +@command{expr} supports the usual numeric operators, in order of increasing +precedence. The string operators (previous section) have lower precedence, +the connectives (next section) have higher. + +@table @samp + +@item + - +@kindex + +@kindex - +@cindex addition +@cindex subtraction +Addition and subtraction. Both arguments are converted to integers; +an error occurs if this cannot be done. + +@item * / % +@kindex * +@kindex / +@kindex % +@cindex multiplication +@cindex division +@cindex remainder +Multiplication, division, remainder. Both arguments are converted to +integers; an error occurs if this cannot be done. + +@end table + + +@node Relations for expr +@subsection Relations for @command{expr} + +@cindex connectives, logical +@cindex logical connectives +@cindex relations, numeric or string + +@command{expr} supports the usual logical connectives and relations. These +are higher precedence than either the string or numeric operators +(previous sections). Here is the list, lowest-precedence operator first. + +@table @samp + +@item | +@kindex | +@cindex logical or operator +@cindex or operator +Returns its first argument if that is neither null nor zero, otherwise +its second argument if it is neither null nor zero, otherwise 0. It +does not evaluate its second argument if its first argument is neither +null nor zero. + +@item & +@kindex & +@cindex logical and operator +@cindex and operator +Return its first argument if neither argument is null or zero, otherwise +0. It does not evaluate its second argument if its first argument is +null or zero. + +@item < <= = == != >= > +@kindex < +@kindex <= +@kindex = +@kindex == +@kindex > +@kindex >= +@cindex comparison operators +@vindex LC_COLLATE +Compare the arguments and return 1 if the relation is true, 0 otherwise. +@code{==} is a synonym for @code{=}. @command{expr} first tries to convert +both arguments to integers and do a numeric comparison; if either +conversion fails, it does a lexicographic comparison using the character +collating sequence specified by the @env{LC_COLLATE} locale. + +@end table + + +@node Examples of expr +@subsection Examples of using @command{expr} + +@cindex examples of @command{expr} +Here are a few examples, including quoting for shell metacharacters. + +To add 1 to the shell variable @code{foo}, in Bourne-compatible shells: + +@example +foo=`expr $foo + 1` +@end example + +To print the non-directory part of the file name stored in +@code{$fname}, which need not contain a @code{/}: + +@example +expr $fname : '.*/\(.*\)' '|' $fname +@end example + +An example showing that @code{\+} is an operator: + +@example +expr aaa : 'a\+' +@result{} 3 +@end example + +@example +expr abc : 'a\(.\)c' +@result{} b +expr index abcdef cz +@result{} 3 +expr index index a +@error{} expr: syntax error +expr index quote index a +@result{} 0 +@end example + + +@node Redirection +@chapter Redirection + +@cindex redirection +@cindex commands for redirection + +Unix shells commonly provide several forms of @dfn{redirection}---ways +to change the input source or output destination of a command. But one +useful redirection is performed by a separate command, not by the shell; +it's described here. + +@menu +* tee invocation:: Redirect output to multiple files. +@end menu + + +@node tee invocation +@section @command{tee}: Redirect output to multiple files + +@pindex tee +@cindex pipe fitting +@cindex destinations, multiple output +@cindex read from stdin and write to stdout and files + +The @command{tee} command copies standard input to standard output and also +to any files given as arguments. This is useful when you want not only +to send some data down a pipe, but also to save a copy. Synopsis: + +@example +tee [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +If a file being written to does not already exist, it is created. If a +file being written to already exists, the data it previously contained +is overwritten unless the @option{-a} option is used. + +A @var{file} of @samp{-} causes @command{tee} to send another copy of +input to standard output, but this is typically not that useful as the +copies are interleaved. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp +@item -a +@itemx --append +@opindex -a +@opindex --append +Append standard input to the given files rather than overwriting +them. + +@item -i +@itemx --ignore-interrupts +@opindex -i +@opindex --ignore-interrupts +Ignore interrupt signals. + +@end table + +@exitstatus + + +@node File name manipulation +@chapter File name manipulation + +@cindex file name manipulation +@cindex manipulation of file names +@cindex commands for file name manipulation + +This section describes commands that manipulate file names. + +@menu +* basename invocation:: Strip directory and suffix from a file name. +* dirname invocation:: Strip non-directory suffix from a file name. +* pathchk invocation:: Check file name portability. +@end menu + + +@node basename invocation +@section @command{basename}: Strip directory and suffix from a file name + +@pindex basename +@cindex strip directory and suffix from file names +@cindex directory, stripping from file names +@cindex suffix, stripping from file names +@cindex file names, stripping directory and suffix +@cindex leading directory components, stripping + +@command{basename} removes any leading directory components from +@var{name}. Synopsis: + +@example +basename @var{name} [@var{suffix}] +@end example + +If @var{suffix} is specified and is identical to the end of @var{name}, +it is removed from @var{name} as well. Note that since trailing slashes +are removed prior to suffix matching, @var{suffix} will do nothing if it +contains slashes. @command{basename} prints the result on standard +output. + +@c This test is used both here and in the section on dirname. +@macro basenameAndDirname +Together, @command{basename} and @command{dirname} are designed such +that if @samp{ls "$name"} succeeds, then the command sequence @samp{cd +"$(dirname "$name")"; ls "$(basename "$name")"} will, too. This works +for everything except file names containing a trailing newline. +@end macro +@basenameAndDirname + +@acronym{POSIX} allows the implementation to define the results if +@var{name} is empty or @samp{//}. In the former case, @acronym{GNU} +@command{basename} returns the empty string. In the latter case, the +result is @samp{//} on platforms where @var{//} is distinct from +@var{/}, and @samp{/} on platforms where there is no difference. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. Options must precede operands. + +@exitstatus + +Examples: + +@smallexample +# Output "sort". +basename /usr/bin/sort + +# Output "stdio". +basename include/stdio.h .h +@end smallexample + + +@node dirname invocation +@section @command{dirname}: Strip non-directory suffix from a file name + +@pindex dirname +@cindex directory components, printing +@cindex stripping non-directory suffix +@cindex non-directory suffix, stripping + +@command{dirname} prints all but the final slash-delimited component of +a string (presumably a file name). Synopsis: + +@example +dirname @var{name} +@end example + +If @var{name} is a single component, @command{dirname} prints @samp{.} +(meaning the current directory). + +@basenameAndDirname + +@acronym{POSIX} allows the implementation to define the results if +@var{name} is @samp{//}. With @acronym{GNU} @command{dirname}, the +result is @samp{//} on platforms where @var{//} is distinct from +@var{/}, and @samp{/} on platforms where there is no difference. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +@exitstatus + +Examples: + +@smallexample +# Output "/usr/bin". +dirname /usr/bin/sort + +# Output ".". +dirname stdio.h +@end smallexample + + +@node pathchk invocation +@section @command{pathchk}: Check file name portability + +@pindex pathchk +@cindex file names, checking validity and portability +@cindex valid file names, checking for +@cindex portable file names, checking for + +@command{pathchk} checks portability of file names. Synopsis: + +@example +pathchk [@var{option}]@dots{} @var{name}@dots{} +@end example + +For each @var{name}, @command{pathchk} prints a message if any of +these conditions is true: + +@enumerate +@item +One of the existing directories in @var{name} does not have search +(execute) permission, +@item +The length of @var{name} is larger than the maximum supported by the +operating system. +@item +The length of one component of @var{name} is longer than +its file system's maximum. +@end enumerate + +A nonexistent @var{name} is not an error, so long a file with that +name could be created under the above conditions. + +The program accepts the following options. Also see @ref{Common options}. +Options must precede operands. + +@table @samp + +@item -p +@opindex -p +Instead of performing checks based on the underlying file system, +print a message if any of these conditions is true: + +@enumerate +@item +A file name is empty. + +@item +The length of a file name or one of its components exceeds the +@acronym{POSIX} minimum limits for portability. + +@item +A file name contains a character outside the portable file name +character set, namely, the ASCII letters and digits, @samp{-}, +@samp{.}, @samp{/}, and @samp{_}. +@end enumerate + +@item -P +@opindex -P +Print a message if a file name is empty, or if it contains a component +that begins with @samp{-}. + +@item --portability +@opindex --portability +Print a message if a file name is not portable to all @acronym{POSIX} +hosts. This option is equivalent to @samp{-p -P}. + +@end table + +@cindex exit status of @command{pathchk} +Exit status: + +@display +0 if all specified file names passed all checks, +1 otherwise. +@end display + + +@node Working context +@chapter Working context + +@cindex working context +@cindex commands for printing the working context + +This section describes commands that display or alter the context in +which you are working: the current directory, the terminal settings, and +so forth. See also the user-related commands in the next section. + +@menu +* pwd invocation:: Print working directory. +* stty invocation:: Print or change terminal characteristics. +* printenv invocation:: Print environment variables. +* tty invocation:: Print file name of terminal on standard input. +@end menu + + +@node pwd invocation +@section @command{pwd}: Print working directory + +@pindex pwd +@cindex print name of current directory +@cindex current working directory, printing +@cindex working directory, printing + +@cindex symbolic links and @command{pwd} +@command{pwd} prints the fully resolved name of the current directory. +That is, all components of the printed name will be actual directory +names---none will be symbolic links. + +@cindex conflicts with shell built-ins +@cindex built-in shell commands, conflicts with +Because most shells have a built-in @command{pwd} command, using an +unadorned @command{pwd} in a script or interactively may get you +different functionality than that described here. + +The only options are a lone @option{--help} or +@option{--version}. @xref{Common options}. + +@exitstatus + + +@node stty invocation +@section @command{stty}: Print or change terminal characteristics + +@pindex stty +@cindex change or print terminal settings +@cindex terminal settings +@cindex line settings of terminal + +@command{stty} prints or changes terminal characteristics, such as baud rate. +Synopses: + +@example +stty [@var{option}] [@var{setting}]@dots{} +stty [@var{option}] +@end example + +If given no line settings, @command{stty} prints the baud rate, line +discipline number (on systems that support it), and line settings +that have been changed from the values set by @samp{stty sane}. +By default, mode reading and setting are performed on the tty line +connected to standard input, although this can be modified by the +@option{--file} option. + +@command{stty} accepts many non-option arguments that change aspects of +the terminal line operation, as described below. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp +@item -a +@itemx --all +@opindex -a +@opindex --all +Print all current settings in human-readable form. This option may not +be used in combination with any line settings. + +@item -F @var{device} +@itemx --file=@var{device} +@opindex -F +@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 +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. + +@item -g +@itemx --save +@opindex -g +@opindex --save +@cindex machine-readable @command{stty} output +Print all current settings in a form that can be used as an argument to +another @command{stty} command to restore the current settings. This option +may not be used in combination with any line settings. + +@end table + +Many settings can be turned off by preceding them with a @samp{-}. +Such arguments are marked below with ``May be negated'' in their +description. The descriptions themselves refer to the positive +case, that is, when @emph{not} negated (unless stated otherwise, +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 +be available, but it's not feasible to document all the variations: just +try it and see. + +@exitstatus + +@menu +* Control:: Control settings +* Input:: Input settings +* Output:: Output settings +* Local:: Local settings +* Combination:: Combination settings +* Characters:: Special characters +* Special:: Special settings +@end menu + + +@node Control +@subsection Control settings + +@cindex control settings +Control settings: + +@table @samp +@item parenb +@opindex parenb +@cindex two-way parity +Generate parity bit in output and expect parity bit in input. +May be negated. + +@item parodd +@opindex parodd +@cindex odd parity +@cindex even parity +Set odd parity (even if negated). May be negated. + +@item cs5 +@itemx cs6 +@itemx cs7 +@itemx cs8 +@opindex cs@var{n} +@cindex character size +@cindex eight-bit characters +Set character size to 5, 6, 7, or 8 bits. + +@item hup +@itemx hupcl +@opindex hup[cl] +Send a hangup signal when the last process closes the tty. May be +negated. + +@item cstopb +@opindex cstopb +@cindex stop bits +Use two stop bits per character (one if negated). May be negated. + +@item cread +@opindex cread +Allow input to be received. May be negated. + +@item clocal +@opindex clocal +@cindex modem control +Disable modem control signals. May be negated. + +@item crtscts +@opindex crtscts +@cindex hardware flow control +@cindex flow control, hardware +@cindex RTS/CTS flow control +Enable RTS/CTS flow control. Non-@acronym{POSIX}. May be negated. +@end table + + +@node Input +@subsection Input settings + +@cindex input settings + +@table @samp +@item ignbrk +@opindex ignbrk +@cindex breaks, ignoring +Ignore break characters. May be negated. + +@item brkint +@opindex brkint +@cindex breaks, cause interrupts +Make breaks cause an interrupt signal. May be negated. + +@item ignpar +@opindex ignpar +@cindex parity, ignoring +Ignore characters with parity errors. May be negated. + +@item parmrk +@opindex parmrk +@cindex parity errors, marking +Mark parity errors (with a 255-0-character sequence). May be negated. + +@item inpck +@opindex inpck +Enable input parity checking. May be negated. + +@item istrip +@opindex istrip +@cindex eight-bit input +Clear high (8th) bit of input characters. May be negated. + +@item inlcr +@opindex inlcr +@cindex newline, translating to return +Translate newline to carriage return. May be negated. + +@item igncr +@opindex igncr +@cindex return, ignoring +Ignore carriage return. May be negated. + +@item icrnl +@opindex icrnl +@cindex return, translating to newline +Translate carriage return to newline. May be negated. + +@item iutf8 +@opindex iutf8 +@cindex input encoding, UTF-8 +Assume input characters are UTF-8 encoded. May be negated. + +@item ixon +@opindex ixon +@kindex C-s/C-q flow control +@cindex XON/XOFF flow control +Enable XON/XOFF flow control (that is, @kbd{CTRL-S}/@kbd{CTRL-Q}). May +be negated. + +@item ixoff +@itemx tandem +@opindex ixoff +@opindex tandem +@cindex software flow control +@cindex flow control, software +Enable sending of @code{stop} character when the system input buffer +is almost full, and @code{start} character when it becomes almost +empty again. May be negated. + +@item iuclc +@opindex iuclc +@cindex uppercase, translating to lowercase +Translate uppercase characters to lowercase. Non-@acronym{POSIX}. May be +negated. + +@item ixany +@opindex ixany +Allow any character to restart output (only the start character +if negated). Non-@acronym{POSIX}. May be negated. + +@item imaxbel +@opindex imaxbel +@cindex beeping at input buffer full +Enable beeping and not flushing input buffer if a character arrives +when the input buffer is full. Non-@acronym{POSIX}. May be negated. +@end table + + +@node Output +@subsection Output settings + +@cindex output settings +These arguments specify output-related operations. + +@table @samp +@item opost +@opindex opost +Postprocess output. May be negated. + +@item olcuc +@opindex olcuc +@cindex lowercase, translating to output +Translate lowercase characters to uppercase. Non-@acronym{POSIX}. May be +negated. + +@item ocrnl +@opindex ocrnl +@cindex return, translating to newline +Translate carriage return to newline. Non-@acronym{POSIX}. May be negated. + +@item onlcr +@opindex onlcr +@cindex newline, translating to crlf +Translate newline to carriage return-newline. Non-@acronym{POSIX}. May be +negated. + +@item onocr +@opindex onocr +Do not print carriage returns in the first column. Non-@acronym{POSIX}. +May be negated. + +@item onlret +@opindex onlret +Newline performs a carriage return. Non-@acronym{POSIX}. May be negated. + +@item ofill +@opindex ofill +@cindex pad instead of timing for delaying +Use fill (padding) characters instead of timing for delays. Non-@acronym{POSIX}. +May be negated. + +@item ofdel +@opindex ofdel +@cindex pad character +Use delete characters for fill instead of null characters. Non-@acronym{POSIX}. +May be negated. + +@item nl1 +@itemx nl0 +@opindex nl@var{n} +Newline delay style. Non-@acronym{POSIX}. + +@item cr3 +@itemx cr2 +@itemx cr1 +@itemx cr0 +@opindex cr@var{n} +Carriage return delay style. Non-@acronym{POSIX}. + +@item tab3 +@itemx tab2 +@itemx tab1 +@itemx tab0 +@opindex tab@var{n} +Horizontal tab delay style. Non-@acronym{POSIX}. + +@item bs1 +@itemx bs0 +@opindex bs@var{n} +Backspace delay style. Non-@acronym{POSIX}. + +@item vt1 +@itemx vt0 +@opindex vt@var{n} +Vertical tab delay style. Non-@acronym{POSIX}. + +@item ff1 +@itemx ff0 +@opindex ff@var{n} +Form feed delay style. Non-@acronym{POSIX}. +@end table + + +@node Local +@subsection Local settings + +@cindex local settings + +@table @samp +@item isig +@opindex isig +Enable @code{interrupt}, @code{quit}, and @code{suspend} special +characters. May be negated. + +@item icanon +@opindex icanon +Enable @code{erase}, @code{kill}, @code{werase}, and @code{rprnt} +special characters. May be negated. + +@item iexten +@opindex iexten +Enable non-@acronym{POSIX} special characters. May be negated. + +@item echo +@opindex echo +Echo input characters. May be negated. + +@item echoe +@itemx crterase +@opindex echoe +@opindex crterase +Echo @code{erase} characters as backspace-space-backspace. May be +negated. + +@item echok +@opindex echok +@cindex newline echoing after @code{kill} +Echo a newline after a @code{kill} character. May be negated. + +@item echonl +@opindex echonl +@cindex newline, echoing +Echo newline even if not echoing other characters. May be negated. + +@item noflsh +@opindex noflsh +@cindex flushing, disabling +Disable flushing after @code{interrupt} and @code{quit} special +characters. May be negated. + +@item xcase +@opindex xcase +@cindex case translation +Enable input and output of uppercase characters by preceding their +lowercase equivalents with @samp{\}, when @code{icanon} is set. +Non-@acronym{POSIX}. May be negated. + +@item tostop +@opindex tostop +@cindex background jobs, stopping at terminal write +Stop background jobs that try to write to the terminal. Non-@acronym{POSIX}. +May be negated. + +@item echoprt +@itemx prterase +@opindex echoprt +@opindex prterase +Echo erased characters backward, between @samp{\} and @samp{/}. +Non-@acronym{POSIX}. May be negated. + +@item echoctl +@itemx ctlecho +@opindex echoctl +@opindex ctlecho +@cindex control characters, using @samp{^@var{c}} +@cindex hat notation for control characters +Echo control characters in hat notation (@samp{^@var{c}}) instead +of literally. Non-@acronym{POSIX}. May be negated. + +@item echoke +@itemx crtkill +@opindex echoke +@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}. +May be negated. +@end table + + +@node Combination +@subsection Combination settings + +@cindex combination settings +Combination settings: + +@table @samp +@item evenp +@opindex evenp +@itemx parity +@opindex parity +Same as @code{parenb -parodd cs7}. May be negated. If negated, same +as @code{-parenb cs8}. + +@item oddp +@opindex oddp +Same as @code{parenb parodd cs7}. May be negated. If negated, same +as @code{-parenb cs8}. + +@item nl +@opindex nl +Same as @code{-icrnl -onlcr}. May be negated. If negated, same as +@code{icrnl -inlcr -igncr onlcr -ocrnl -onlret}. + +@item ek +@opindex ek +Reset the @code{erase} and @code{kill} special characters to their default +values. + +@item sane +@opindex sane +Same as: + +@c This is too long to write inline. +@example +cread -ignbrk brkint -inlcr -igncr icrnl -ixoff +-iuclc -ixany imaxbel opost -olcuc -ocrnl onlcr +-onocr -onlret -ofill -ofdel nl0 cr0 tab0 bs0 vt0 +ff0 isig icanon iexten echo echoe echok -echonl +-noflsh -xcase -tostop -echoprt echoctl echoke +@end example + +@noindent +and also sets all special characters to their default values. + +@item cooked +@opindex cooked +Same as @code{brkint ignpar istrip icrnl ixon opost isig icanon}, plus +sets the @code{eof} and @code{eol} characters to their default values +if they are the same as the @code{min} and @code{time} characters. +May be negated. If negated, same as @code{raw}. + +@item raw +@opindex raw +Same as: + +@example +-ignbrk -brkint -ignpar -parmrk -inpck -istrip +-inlcr -igncr -icrnl -ixon -ixoff -iuclc -ixany +-imaxbel -opost -isig -icanon -xcase min 1 time 0 +@end example + +@noindent +May be negated. If negated, same as @code{cooked}. + +@item cbreak +@opindex cbreak +Same as @option{-icanon}. May be negated. If negated, same as +@code{icanon}. + +@item pass8 +@opindex pass8 +@cindex eight-bit characters +Same as @code{-parenb -istrip cs8}. May be negated. If negated, +same as @code{parenb istrip cs7}. + +@item litout +@opindex litout +Same as @option{-parenb -istrip -opost cs8}. May be negated. +If negated, same as @code{parenb istrip opost cs7}. + +@item decctlq +@opindex decctlq +Same as @option{-ixany}. Non-@acronym{POSIX}. May be negated. + +@item tabs +@opindex tabs +Same as @code{tab0}. Non-@acronym{POSIX}. May be negated. If negated, same +as @code{tab3}. + +@item lcase +@itemx LCASE +@opindex lcase +@opindex LCASE +Same as @code{xcase iuclc olcuc}. Non-@acronym{POSIX}. May be negated. + +@item crt +@opindex crt +Same as @code{echoe echoctl echoke}. + +@item dec +@opindex dec +Same as @code{echoe echoctl echoke -ixany intr ^C erase ^? kill C-u}. +@end table + + +@node Characters +@subsection Special characters + +@cindex special characters +@cindex characters, special + +The special characters' default values vary from system to system. +They are set with the syntax @samp{name value}, where the names are +listed below and the value can be given either literally, in hat +notation (@samp{^@var{c}}), or as an integer which may start with +@samp{0x} to indicate hexadecimal, @samp{0} to indicate octal, or +any other digit to indicate decimal. + +@cindex disabling special characters +@kindex u@r{, and disabling special characters} +For GNU stty, giving a value of @code{^-} or @code{undef} disables that +special character. (This is incompatible with Ultrix @command{stty}, +which uses a value of @samp{u} to disable a special character. GNU +@command{stty} treats a value @samp{u} like any other, namely to set that +special character to @key{U}.) + +@table @samp + +@item intr +@opindex intr +Send an interrupt signal. + +@item quit +@opindex quit +Send a quit signal. + +@item erase +@opindex erase +Erase the last character typed. + +@item kill +@opindex kill +Erase the current line. + +@item eof +@opindex eof +Send an end of file (terminate the input). + +@item eol +@opindex eol +End the line. + +@item eol2 +@opindex eol2 +Alternate character to end the line. Non-@acronym{POSIX}. + +@item swtch +@opindex swtch +Switch to a different shell layer. Non-@acronym{POSIX}. + +@item start +@opindex start +Restart the output after stopping it. + +@item stop +@opindex stop +Stop the output. + +@item susp +@opindex susp +Send a terminal stop signal. + +@item dsusp +@opindex dsusp +Send a terminal stop signal after flushing the input. Non-@acronym{POSIX}. + +@item rprnt +@opindex rprnt +Redraw the current line. Non-@acronym{POSIX}. + +@item werase +@opindex werase +Erase the last word typed. Non-@acronym{POSIX}. + +@item lnext +@opindex lnext +Enter the next character typed literally, even if it is a special +character. Non-@acronym{POSIX}. +@end table + + +@node Special +@subsection Special settings + +@cindex special settings + +@table @samp +@item min @var{n} +@opindex min +Set the minimum number of characters that will satisfy a read until +the time value has expired, when @option{-icanon} is set. + +@item time @var{n} +@opindex time +Set the number of tenths of a second before reads time out if the minimum +number of characters have not been read, when @option{-icanon} is set. + +@item ispeed @var{n} +@opindex ispeed +Set the input speed to @var{n}. + +@item ospeed @var{n} +@opindex ospeed +Set the output speed to @var{n}. + +@item rows @var{n} +@opindex rows +Tell the tty kernel driver that the terminal has @var{n} rows. Non-@acronym{POSIX}. + +@item cols @var{n} +@itemx columns @var{n} +@opindex cols +@opindex columns +Tell the kernel that the terminal has @var{n} columns. Non-@acronym{POSIX}. + +@item size +@opindex size +@vindex LINES +@vindex COLUMNS +Print the number of rows and columns that the kernel thinks the +terminal has. (Systems that don't support rows and columns in the kernel +typically use the environment variables @env{LINES} and @env{COLUMNS} +instead; however, GNU @command{stty} does not know anything about them.) +Non-@acronym{POSIX}. + +@item line @var{n} +@opindex line +Use line discipline @var{n}. Non-@acronym{POSIX}. + +@item speed +@opindex speed +Print the terminal speed. + +@item @var{n} +@cindex baud rate, setting +@c FIXME: Is this still true that the baud rate can't be set +@c higher than 38400? +Set the input and output speeds to @var{n}. @var{n} can be one +of: 0 50 75 110 134 134.5 150 200 300 600 1200 1800 2400 4800 9600 +19200 38400 @code{exta} @code{extb}. @code{exta} is the same as +19200; @code{extb} is the same as 38400. 0 hangs up the line if +@option{-clocal} is set. +@end table + + +@node printenv invocation +@section @command{printenv}: Print all or some environment variables + +@pindex printenv +@cindex printing all or some environment variables +@cindex environment variables, printing + +@command{printenv} prints environment variable values. Synopsis: + +@example +printenv [@var{option}] [@var{variable}]@dots{} +@end example + +If no @var{variable}s are specified, @command{printenv} prints the value of +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}. + +@cindex exit status of @command{printenv} +Exit status: + +@display +0 if all variables specified were found +1 if at least one specified variable was not found +2 if a write error occurred +@end display + + +@node tty invocation +@section @command{tty}: Print file name of terminal on standard input + +@pindex tty +@cindex print terminal file name +@cindex terminal file name, printing + +@command{tty} prints the file name of the terminal connected to its standard +input. It prints @samp{not a tty} if standard input is not a terminal. +Synopsis: + +@example +tty [@var{option}]@dots{} +@end example + +The program accepts the following option. Also see @ref{Common options}. + +@table @samp + +@item -s +@itemx --silent +@itemx --quiet +@opindex -s +@opindex --silent +@opindex --quiet +Print nothing; only return an exit status. + +@end table + +@cindex exit status of @command{tty} +Exit status: + +@display +0 if standard input is a terminal +1 if standard input is not a terminal +2 if given incorrect arguments +3 if a write error occurs +@end display + + +@node User information +@chapter User information + +@cindex user information, commands for +@cindex commands for printing user information + +This section describes commands that print user-related information: +logins, groups, and so forth. + +@menu +* id invocation:: Print user identity. +* logname invocation:: Print current login name. +* whoami invocation:: Print effective user ID. +* groups invocation:: Print group names a user is in. +* users invocation:: Print login names of users currently logged in. +* who invocation:: Print who is currently logged in. +@end menu + + +@node id invocation +@section @command{id}: Print user identity + +@pindex id +@cindex real user and group IDs, printing +@cindex effective user and group IDs, printing +@cindex printing real and effective user and group IDs + +@command{id} prints information about the given user, or the process +running it if no user is specified. Synopsis: + +@example +id [@var{option}]@dots{} [@var{username}] +@end example + +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. + +Each of these numeric values is preceded by an identifying string and +followed by the corresponding user or group name in parentheses. + +The options cause @command{id} to print only part of the above information. +Also see @ref{Common options}. + +@table @samp +@item -g +@itemx --group +@opindex -g +@opindex --group +Print only the group ID. + +@item -G +@itemx --groups +@opindex -G +@opindex --groups +Print only the group ID and the supplementary groups. + +@item -n +@itemx --name +@opindex -n +@opindex --name +Print the user or group name instead of the ID number. Requires +@option{-u}, @option{-g}, or @option{-G}. + +@item -r +@itemx --real +@opindex -r +@opindex --real +Print the real, instead of effective, user or group ID. Requires +@option{-u}, @option{-g}, or @option{-G}. + +@item -u +@itemx --user +@opindex -u +@opindex --user +Print only the user ID. + +@end table + +@exitstatus + + +@node logname invocation +@section @command{logname}: Print current login name + +@pindex logname +@cindex printing user's login name +@cindex login name, printing +@cindex user name, printing + +@flindex utmp +@command{logname} prints the calling user's name, as found in a +system-maintained file (often @file{/var/run/utmp} or +@file{/etc/utmp}), and exits with a status of 0. If there is no entry +for the calling process, @command{logname} prints +an error message and exits with a status of 1. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +@exitstatus + + +@node whoami invocation +@section @command{whoami}: Print effective user ID + +@pindex whoami +@cindex effective user ID, printing +@cindex printing the effective user ID + +@command{whoami} prints the user name associated with the current +effective user ID. It is equivalent to the command @samp{id -un}. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +@exitstatus + + +@node groups invocation +@section @command{groups}: Print group names a user is in + +@pindex groups +@cindex printing groups a user is in +@cindex supplementary groups, printing + +@command{groups} prints the names of the primary and any supplementary +groups for each given @var{username}, or the current process if no names +are given. If more than one name is given, the name of each user is +printed before +the list of that user's groups. Synopsis: + +@example +groups [@var{username}]@dots{} +@end example + +The group lists are equivalent to the output of the command @samp{id -Gn}. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +@exitstatus + + +@node users invocation +@section @command{users}: Print login names of users currently logged in + +@pindex users +@cindex printing current usernames +@cindex usernames, printing current + +@cindex login sessions, printing users with +@command{users} prints on a single line a blank-separated list of user +names of users currently logged in to the current host. Each user name +corresponds to a login session, so if a user has more than one login +session, that user's name will appear the same number of times in the +output. Synopsis: + +@example +users [@var{file}] +@end example + +@flindex utmp +@flindex wtmp +With no @var{file} argument, @command{users} extracts its information from +a system-maintained file (often @file{/var/run/utmp} or +@file{/etc/utmp}). If a file argument is given, @command{users} uses +that file instead. A common choice is @file{/var/log/wtmp}. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +@exitstatus + + +@node who invocation +@section @command{who}: Print who is currently logged in + +@pindex who +@cindex printing current user information +@cindex information, about current users + +@command{who} prints information about users who are currently logged on. +Synopsis: + +@example +@command{who} [@var{option}] [@var{file}] [am i] +@end example + +@cindex terminal lines, currently used +@cindex login time +@cindex remote hostname +If given no non-option arguments, @command{who} prints the following +information for each user currently logged on: login name, terminal +line, login time, and remote hostname or X display. + +@flindex utmp +@flindex wtmp +If given one non-option argument, @command{who} uses that instead of +a default system-maintained file (often @file{/var/run/utmp} or +@file{/etc/utmp}) as the name of the file containing the record of +users logged on. @file{/var/log/wtmp} is commonly given as an argument +to @command{who} to look at who has previously logged on. + +@opindex am i +@opindex who am i +If given two non-option arguments, @command{who} prints only the entry +for the user running it (determined from its standard input), preceded +by the hostname. Traditionally, the two arguments given are @samp{am +i}, as in @samp{who am i}. + +@vindex TZ +Time stamps are listed according to the time zone rules specified by +the @env{TZ} environment variable, or by the system default rules if +@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone +with @env{TZ}, libc, The GNU C Library}. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -a +@itemx --all +@opindex -a +@opindex --all +Same as @samp{-b -d --login -p -r -t -T -u}. + +@item -b +@itemx --boot +@opindex -b +@opindex --boot +Print the date and time of last system boot. + +@item -d +@itemx --dead +@opindex -d +@opindex --dead +Print information corresponding to dead processes. + +@item -H +@itemx --heading +@opindex -H +@opindex --heading +Print column headings. + +@item -m +@opindex -m +Same as @samp{who am i}. + +@item -q +@itemx --count +@opindex -q +@opindex --count +Print only the login names and the number of users logged on. +Overrides all other options. + +@item -s +@opindex -s +Ignored; for compatibility with other versions of @command{who}. + +@itemx -u +@opindex -u +@cindex idle time +After the login time, print the number of hours and minutes that the +user has been idle. @samp{.} means the user was active in the last minute. +@samp{old} means the user has been idle for more than 24 hours. + +@item -l +@itemx --login +@opindex -l +@opindex --login +List only the entries that correspond to processes via which the +system is waiting for a user to login. The user name is always @samp{LOGIN}. + +@itemx --lookup +@opindex --lookup +Attempt to canonicalize hostnames found in utmp through a DNS lookup. This +is not the default because it can cause significant delays on systems with +automatic dial-up internet access. + +@item -H +@itemx --heading +@opindex -H +@opindex --heading +Print a line of column headings. + +@item -w +@itemx -T +@itemx --mesg +@itemx --message +@itemx --writable +@opindex -w +@opindex -T +@opindex --mesg +@opindex --message +@opindex --writable +@cindex message status +@pindex write@r{, allowed} +After each login name print a character indicating the user's message status: + +@display +@samp{+} allowing @code{write} messages +@samp{-} disallowing @code{write} messages +@samp{?} cannot find terminal device +@end display + +@end table + +@exitstatus + + +@node System context +@chapter System context + +@cindex system context +@cindex context, system +@cindex commands for system context + +This section describes commands that print or change system-wide +information. + +@menu +* date invocation:: Print or set system date and time. +* uname invocation:: Print system information. +* hostname invocation:: Print or set system name. +* hostid invocation:: Print numeric host identifier. +@end menu + + +@node date invocation +@section @command{date}: Print or set system date and time + +@pindex date +@cindex time, printing or setting +@cindex printing the current time + +Synopses: + +@example +date [@var{option}]@dots{} [+@var{format}] +date [-u|--utc|--universal] @c this avoids a newline in the output +[ MMDDhhmm[[CC]YY][.ss] ] +@end example + +@vindex LC_TIME +Invoking @command{date} with no @var{format} argument is equivalent to invoking +it with a default format that depends on the @env{LC_TIME} locale category. +In the default C locale, this format is @samp{'+%a %b %e %H:%M:%S %Z %Y'}, +so the output looks like @samp{Thu Mar @ 3 13:47:51 PST 2005}. + +@vindex TZ +Normally, @command{date} uses the time zone rules indicated by the +@env{TZ} environment variable, or the system default rules if @env{TZ} +is not set. @xref{TZ Variable,, Specifying the Time Zone with +@env{TZ}, libc, The GNU C Library}. + +@findex strftime @r{and @command{date}} +@cindex time formats +@cindex formatting times +If given an argument that starts with a @samp{+}, @command{date} prints the +current date and time (or the date and time specified by the +@option{--date} option, see below) in the format defined by that argument, +which is similar to that of the @code{strftime} function. Except for +conversion specifiers, which start with @samp{%}, characters in the +format string are printed unchanged. The conversion specifiers are +described below. + +@exitstatus + +@menu +* Time conversion specifiers:: %[HIklMNpPrRsSTXzZ] +* 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. +* Examples of date:: Examples. +@end menu + +@node Time conversion specifiers +@subsection Time conversion specifiers + +@cindex time conversion specifiers +@cindex conversion specifiers, time + +@command{date} conversion specifiers related to times. + +@table @samp +@item %H +hour (@samp{00}@dots{}@samp{23}) +@item %I +hour (@samp{01}@dots{}@samp{12}) +@item %k +hour (@samp{ 0}@dots{}@samp{23}). +This is a @acronym{GNU} extension. +@item %l +hour (@samp{ 1}@dots{}@samp{12}). +This is a @acronym{GNU} extension. +@item %M +minute (@samp{00}@dots{}@samp{59}) +@item %N +nanoseconds (@samp{000000000}@dots{}@samp{999999999}). +This is a @acronym{GNU} extension. +@item %p +locale's equivalent of either @samp{AM} or @samp{PM}; +blank in many locales. +Noon is treated as @samp{PM} and midnight as @samp{AM}. +@item %P +like @samp{%p}, except lower case. +This is a @acronym{GNU} extension. +@item %r +locale's 12-hour clock time (e.g., @samp{11:11:04 PM}) +@item %R +24-hour hour and minute. Same as @samp{%H:%M}. +This is a @acronym{GNU} extension. +@item %s +@cindex epoch, seconds since +@cindex seconds since the epoch +@cindex beginning of time +seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. +Leap seconds are not counted unless leap second support is available. +@xref{%s-examples}, for examples. +This is a @acronym{GNU} extension. +@item %S +second (@samp{00}@dots{}@samp{60}). +This may be @samp{60} if leap seconds are supported. +@item %T +24-hour hour, minute, and second. Same as @samp{%H:%M:%S}. +@item %X +locale's time representation (e.g., @samp{23:13:48}) +@item %z +@w{@acronym{RFC} 2822/@acronym{ISO} 8601} style numeric time zone +(e.g., @samp{-0600} or @samp{+0530}), or nothing if no +time zone is determinable. This value reflects the numeric time zone +appropriate for the current time, using the time zone rules specified +by the @env{TZ} environment variable. +The time (and optionally, the time zone rules) can be overridden +by the @option{--date} option. +This is a @acronym{GNU} extension. +@item %:z +@w{@acronym{RFC} 3339/@acronym{ISO} 8601} style numeric time zone with +@samp{:} (e.g., @samp{-06:00} or @samp{+05:30}), or nothing if no time +zone is determinable. +This is a @acronym{GNU} extension. +@item %::z +Numeric time zone to the nearest second with @samp{:} (e.g., +@samp{-06:00:00} or @samp{+05:30:00}), or nothing if no time zone is +determinable. +This is a @acronym{GNU} extension. +@item %:::z +Numeric time zone with @samp{:} using the minimum necessary precision +(e.g., @samp{-06}, @samp{+05:30}, or @samp{-04:56:02}), or nothing if +no time zone is determinable. +This is a @acronym{GNU} extension. +@item %Z +alphabetic time zone abbreviation (e.g., @samp{EDT}), or nothing if no +time zone is determinable. See @samp{%z} for how it is determined. +@end table + + +@node Date conversion specifiers +@subsection Date conversion specifiers + +@cindex date conversion specifiers +@cindex conversion specifiers, date + +@command{date} conversion specifiers related to dates. + +@table @samp +@item %a +locale's abbreviated weekday name (e.g., @samp{Sun}) +@item %A +locale's full weekday name, variable length (e.g., @samp{Sunday}) +@item %b +locale's abbreviated month name (e.g., @samp{Jan}) +@item %B +locale's full month name, variable length (e.g., @samp{January}) +@item %c +locale's date and time (e.g., @samp{Thu Mar @ 3 23:05:25 2005}) +@item %C +century. This is like @samp{%Y}, except the last two digits are omitted. +For example, it is @samp{20} if @samp{%Y} is @samp{2000}, +and is @samp{-0} if @samp{%Y} is @samp{-001}. +It is normally at least two characters, but it may be more. +@item %d +day of month (e.g., @samp{01}) +@item %D +date; same as @samp{%m/%d/%y} +@item %e +day of month, space padded; same as @samp{%_d} +@item %F +full date in @acronym{ISO} 8601 format; same as @samp{%Y-%m-%d}. +This is a good choice for a date format, as it is standard and +is easy to sort in the usual case where years are in the range +0000@dots{}9999. +This is a @acronym{GNU} extension. +@item %g +year corresponding to the @acronym{ISO} week number, but without the century +(range @samp{00} through @samp{99}). This has the same format and value +as @samp{%y}, except that if the @acronym{ISO} week number (see +@samp{%V}) belongs +to the previous or next year, that year is used instead. +This is a @acronym{GNU} extension. +@item %G +year corresponding to the @acronym{ISO} week number. This has the +same format and value as @samp{%Y}, except that if the @acronym{ISO} +week number (see +@samp{%V}) belongs to the previous or next year, that year is used +instead. +It is normally useful only if @samp{%V} is also used; +for example, the format @samp{%G-%m-%d} is probably a mistake, +since it combines the ISO week number year with the conventional month and day. +This is a @acronym{GNU} extension. +@item %h +same as @samp{%b} +@item %j +day of year (@samp{001}@dots{}@samp{366}) +@item %m +month (@samp{01}@dots{}@samp{12}) +@item %u +day of week (@samp{1}@dots{}@samp{7}) with @samp{1} corresponding to Monday +@item %U +week number of year, with Sunday as the first day of the week +(@samp{00}@dots{}@samp{53}). +Days in a new year preceding the first Sunday are in week zero. +@item %V +@acronym{ISO} week number, that is, the +week number of year, with Monday as the first day of the week +(@samp{01}@dots{}@samp{53}). +If the week containing January 1 has four or more days in +the new year, then it is considered week 1; otherwise, it is week 53 of +the previous year, and the next week is week 1. (See the @acronym{ISO} 8601 +standard.) +@item %w +day of week (@samp{0}@dots{}@samp{6}) with 0 corresponding to Sunday +@item %W +week number of year, with Monday as first day of week +(@samp{00}@dots{}@samp{53}). +Days in a new year preceding the first Monday are in week zero. +@item %x +locale's date representation (e.g., @samp{12/31/99}) +@item %y +last two digits of year (@samp{00}@dots{}@samp{99}) +@item %Y +year. This is normally at least four characters, but it may be more. +Year @samp{0000} precedes year @samp{0001}, and year @samp{-001} +precedes year @samp{0000}. +@end table + + +@node Literal conversion specifiers +@subsection Literal conversion specifiers + +@cindex literal conversion specifiers +@cindex conversion specifiers, literal + +@command{date} conversion specifiers that produce literal strings. + +@table @samp +@item %% +a literal % +@item %n +a newline +@item %t +a horizontal tab +@end table + + +@node Padding and other flags +@subsection Padding and other flags + +@cindex numeric field padding +@cindex padding of numeric fields +@cindex fields, padding numeric + +Unless otherwise specified, @command{date} normally pads numeric fields +with zeros, so that, for +example, numeric months are always output as two digits. +Seconds since the epoch are not padded, though, +since there is no natural width for them. + +As a @acronym{GNU} extension, @command{date} recognizes any of the +following optional flags after the @samp{%}: + +@table @samp +@item - +(hyphen) Do not pad the field; useful if the output is intended for +human consumption. +@item _ +(underscore) Pad with spaces; useful if you need a fixed +number of characters in the output, but zeros are too distracting. +@item 0 +(zero) Pad with zeros even if the conversion specifier +would normally pad with spaces. +@item ^ +Use upper case characters if possible. +@item # +Use opposite case characters if possible. +A field that is normally upper case becomes lower case, and vice versa. +@end table + +@noindent +Here are some examples of padding: + +@example +date +%d/%m -d "Feb 1" +@result{} 01/02 +date +%-d/%-m -d "Feb 1" +@result{} 1/2 +date +%_d/%_m -d "Feb 1" +@result{} 1/ 2 +@end example + +As a @acronym{GNU} extension, you can specify the field width +(after any flag, if present) as a decimal number. If the natural size of the +output is of the field has less than the specified number of characters, +the result is written right adjusted and padded to the given +size. For example, @samp{%9B} prints the right adjusted month name in +a field of width 9. + +An optional modifier can follow the optional flag and width +specification. The modifiers are: + +@table @samp +@item E +Use the locale's alternate representation for date and time. This +modifier applies to the @samp{%c}, @samp{%C}, @samp{%x}, @samp{%X}, +@samp{%y} and @samp{%Y} conversion specifiers. In a Japanese locale, for +example, @samp{%Ex} might yield a date format based on the Japanese +Emperors' reigns. + +@item O +Use the locale's alternate numeric symbols for numbers. This modifier +applies only to numeric conversion specifiers. +@end table + +If the format supports the modifier but no alternate representation +is available, it is ignored. + + +@node Setting the time +@subsection Setting the time + +@cindex setting the time +@cindex time setting +@cindex appropriate privileges + +If given an argument that does not start with @samp{+}, @command{date} sets +the system clock to the date and time specified by that argument (as +described below). You must have appropriate privileges to set the +system clock. The @option{--date} and @option{--set} options may not be +used with such an argument. The @option{--universal} option may be used +with such an argument to indicate that the specified date and time are +relative to Coordinated Universal Time rather than to the local time +zone. + +The argument must consist entirely of digits, which have the following +meaning: + +@table @samp +@item MM +month +@item DD +day within month +@item hh +hour +@item mm +minute +@item CC +first two digits of year (optional) +@item YY +last two digits of year (optional) +@item ss +second (optional) +@end table + +The @option{--set} option also sets the system clock; see the next section. + + +@node Options for date +@subsection Options for @command{date} + +@cindex @command{date} options +@cindex options for @command{date} + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -d @var{datestr} +@itemx --date=@var{datestr} +@opindex -d +@opindex --date +@cindex parsing date strings +@cindex date strings, parsing +@cindex arbitrary date strings, parsing +@opindex yesterday +@opindex tomorrow +@opindex next @var{day} +@opindex last @var{day} +Display the date and time specified in @var{datestr} instead of the +current date and time. @var{datestr} can be in almost any common +format. It can contain month names, time zones, @samp{am} and @samp{pm}, +@samp{yesterday}, etc. For example, @option{--date="2004-02-27 +14:19:13.489392193 +0530"} specifies the instant of time that is +489,392,193 nanoseconds after February 27, 2004 at 2:19:13 PM in a +time zone that is 5 hours and 30 minutes east of @acronym{UTC}. +@xref{Date input formats}. + +@item -f @var{datefile} +@itemx --file=@var{datefile} +@opindex -f +@opindex --file +Parse each line in @var{datefile} as with @option{-d} and display the +resulting date and time. If @var{datefile} is @samp{-}, use standard +input. This is useful when you have many dates to process, because the +system overhead of starting up the @command{date} executable many times can +be considerable. + +@item -r @var{file} +@itemx --reference=@var{file} +@opindex -r +@opindex --reference +Display the date and time of the last modification of @var{file}, +instead of the current date and time. + +@item -R +@itemx --rfc-822 +@itemx --rfc-2822 +@opindex -R +@opindex --rfc-822 +@opindex --rfc-2822 +Display the date and time using the format @samp{%a, %d %b %Y %H:%M:%S +%z}, evaluated in the C locale so abbreviations are always in English. +For example: + +@example +Fri, 09 Sep 2005 13:51:39 -0700 +@end example + +This format conforms to +@uref{ftp://ftp.rfc-editor.org/in-notes/rfc2822.txt, Internet +@acronym{RFCs} 2822} and +@uref{ftp://ftp.rfc-editor.org/in-notes/rfc822.txt, 822}, the +current and previous standards for Internet email. + +@item --rfc-3339=@var{timespec} +@opindex --rfc-3339=@var{timespec} +Display the date using a format specified by +@uref{ftp://ftp.rfc-editor.org/in-notes/rfc3339.txt, Internet +@acronym{RFC} 3339}. This is a subset of the @acronym{ISO} 8601 +format, except that it also permits applications to use a space rather +than a @samp{T} to separate dates from times. Unlike the other +standard formats, @acronym{RFC} 3339 format is always suitable as +input for the @option{--date} (@option{-d}) and @option{--file} +(@option{-f}) options, regardless of the current locale. + +The argument @var{timespec} specifies how much of the time to include. +It can be one of the following: + +@table @samp +@item date +Print just the full-date, e.g., @samp{2005-09-14}. +This is equivalent to the format @samp{%Y-%m-%d}. + +@item seconds +Print the full-date and full-time separated by a space, e.g., +@samp{2005-09-14 00:56:06+05:30}. The output ends with a numeric +time-offset; here the @samp{+05:30} means that local time is five +hours and thirty minutes east of @acronym{UTC}. This is equivalent to +the format @samp{%Y-%m-%d %H:%M:%S%:z}. + +@item ns +Like @samp{seconds}, but also print nanoseconds, e.g., +@samp{2005-09-14 00:56:06.998458565+05:30}. +This is equivalent to the format @samp{%Y-%m-%d %H:%M:%S.%N%:z}. + +@end table + +@item -s @var{datestr} +@itemx --set=@var{datestr} +@opindex -s +@opindex --set +Set the date and time to @var{datestr}. See @option{-d} above. + +@item -u +@itemx --utc +@itemx --universal +@opindex -u +@opindex --utc +@opindex --universal +@cindex Coordinated Universal Time +@cindex UTC +@cindex Greenwich Mean Time +@cindex GMT +@vindex TZ +Use Coordinated Universal Time (@acronym{UTC}) by operating as if the +@env{TZ} environment variable were set to the string @samp{UTC0}. +Coordinated +Universal Time is often called ``Greenwich Mean Time'' (@sc{gmt}) for +historical reasons. +@end table + + +@node Examples of date +@subsection Examples of @command{date} + +@cindex examples of @command{date} + +Here are a few examples. Also see the documentation for the @option{-d} +option in the previous section. + +@itemize @bullet + +@item +To print the date of the day before yesterday: + +@example +date --date='2 days ago' +@end example + +@item +To print the date of the day three months and one day hence: + +@example +date --date='3 months 1 day' +@end example + +@item +To print the day of year of Christmas in the current year: + +@example +date --date='25 Dec' +%j +@end example + +@item +To print the current full month name and the day of the month: + +@example +date '+%B %d' +@end example + +But this may not be what you want because for the first nine days of +the month, the @samp{%d} expands to a zero-padded two-digit field, +for example @samp{date -d 1may '+%B %d'} will print @samp{May 01}. + +@item +To print a date without the leading zero for one-digit days +of the month, you can use the (@acronym{GNU} extension) +@samp{-} flag to suppress +the padding altogether: + +@example +date -d 1may '+%B %-d +@end example + +@item +To print the current date and time in the format required by many +non-@acronym{GNU} versions of @command{date} when setting the system clock: + +@example +date +%m%d%H%M%Y.%S +@end example + +@item +To set the system clock forward by two minutes: + +@example +date --set='+2 minutes' +@end example + +@item +To print the date in @acronym{RFC} 2822 format, +use @samp{date --rfc-2822}. Here is some example output: + +@example +Fri, 09 Sep 2005 13:51:39 -0700 +@end example + +@anchor{%s-examples} +@item +To convert a date string to the number of seconds since the epoch +(which is 1970-01-01 00:00:00 UTC), use the @option{--date} option with +the @samp{%s} format. That can be useful in sorting and/or graphing +and/or comparing data by date. The following command outputs the +number of the seconds since the epoch for the time two minutes after the +epoch: + +@example +date --date='1970-01-01 00:02:00 +0000' +%s +120 +@end example + +If you do not specify time zone information in the date string, +@command{date} uses your computer's idea of the time zone when +interpreting the string. For example, if your computer's time zone is +that of Cambridge, Massachusetts, which was then 5 hours (i.e., 18,000 +seconds) behind UTC: + +@example +# local time zone used +date --date='1970-01-01 00:02:00' +%s +18120 +@end example + +@item +If you're sorting or graphing dated data, your raw date values may be +represented as seconds since the epoch. But few people can look at +the date @samp{946684800} and casually note ``Oh, that's the first second +of the year 2000 in Greenwich, England.'' + +@example +date --date='2000-01-01 UTC' +%s +946684800 +@end example + +An alternative is to use the @option{--utc} (@option{-u}) option. +Then you may omit @samp{UTC} from the date string. Although this +produces the same result for @samp{%s} and many other format sequences, +with a time zone offset different from zero, it would give a different +result for zone-dependent formats like @samp{%z}. + +@example +date -u --date=2000-01-01 +%s +946684800 +@end example + +To convert such an unwieldy number of seconds back to +a more readable form, use a command like this: + +@smallexample +# local time zone used +date -d '1970-01-01 UTC 946684800 seconds' +"%Y-%m-%d %T %z" +1999-12-31 19:00:00 -0500 +@end smallexample + +Or if you do not mind depending on the @samp{@@} feature present since +coreutils 5.3.0, you could shorten this to: + +@smallexample +date -d @@946684800 +"%F %T %z" +1999-12-31 19:00:00 -0500 +@end smallexample + +Often it is better to output UTC-relative date and time: + +@smallexample +date -u -d '1970-01-01 946684800 seconds' +"%Y-%m-%d %T %z" +2000-01-01 00:00:00 +0000 +@end smallexample + +@end itemize + + +@node uname invocation +@section @command{uname}: Print system information + +@pindex uname +@cindex print system information +@cindex system information, printing + +@command{uname} prints information about the machine and operating system +it is run on. If no options are given, @command{uname} acts as if the +@option{-s} option were given. Synopsis: + +@example +uname [@var{option}]@dots{} +@end example + +If multiple options or @option{-a} are given, the selected information is +printed in this order: + +@example +@var{kernel-name} @var{nodename} @var{kernel-release} @var{kernel-version} +@var{machine} @var{processor} @var{hardware-platform} @var{operating-system} +@end example + +The information may contain internal spaces, so such output cannot be +parsed reliably. In the following example, @var{release} is +@samp{2.2.18ss.e820-bda652a #4 SMP Tue Jun 5 11:24:08 PDT 2001}: + +@smallexample +uname -a +@result{} Linux dum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 i686 unknown unknown GNU/Linux +@end smallexample + + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp + +@item -a +@itemx --all +@opindex -a +@opindex --all +Print all of the below information, except omit the processor type +and the hardware platform name if they are unknown. + +@item -i +@itemx --hardware-platform +@opindex -i +@opindex --hardware-platform +@cindex implementation, hardware +@cindex hardware platform +@cindex platform, hardware +Print the hardware platform name +(sometimes called the hardware implementation). +Print @samp{unknown} if the kernel does not make this information +easily available, as is the case with Linux kernels. + +@item -m +@itemx --machine +@opindex -m +@opindex --machine +@cindex machine type +@cindex hardware class +@cindex hardware type +Print the machine hardware name (sometimes called the hardware class +or hardware type). + +@item -n +@itemx --nodename +@opindex -n +@opindex --nodename +@cindex hostname +@cindex node name +@cindex network node name +Print the network node hostname. + +@item -p +@itemx --processor +@opindex -p +@opindex --processor +@cindex host processor type +Print the processor type (sometimes called the instruction set +architecture or ISA). +Print @samp{unknown} if the kernel does not make this information +easily available, as is the case with Linux kernels. + +@item -o +@itemx --operating-system +@opindex -o +@opindex --operating-system +@cindex operating system name +Print the name of the operating system. + +@item -r +@itemx --kernel-release +@opindex -r +@opindex --kernel-release +@cindex kernel release +@cindex release of kernel +Print the kernel release. + +@item -s +@itemx --kernel-name +@opindex -s +@opindex --kernel-name +@cindex kernel name +@cindex name of kernel +Print the kernel name. +@acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) calls this +``the implementation of the operating system'', because the +@acronym{POSIX} specification itself has no notion of ``kernel''. +The kernel name might be the same as the operating system name printed +by the @option{-o} or @option{--operating-system} option, but it might +differ. Some operating systems (e.g., FreeBSD, HP-UX) have the same +name as their underlying kernels; others (e.g., GNU/Linux, Solaris) +do not. + +@item -v +@itemx --kernel-version +@opindex -v +@opindex --kernel-version +@cindex kernel version +@cindex version of kernel +Print the kernel version. + +@end table + +@exitstatus + + +@node hostname invocation +@section @command{hostname}: Print or set system name + +@pindex hostname +@cindex setting the hostname +@cindex printing the hostname +@cindex system name, printing +@cindex appropriate privileges + +With no arguments, @command{hostname} prints the name of the current host +system. With one argument, it sets the current host name to the +specified string. You must have appropriate privileges to set the host +name. Synopsis: + +@example +hostname [@var{name}] +@end example + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +@exitstatus + + +@node hostid invocation +@section @command{hostid}: Print numeric host identifier. + +@pindex hostid +@cindex printing the host identifier + +@command{hostid} prints the numeric identifier of the current host +in hexadecimal. This command accepts no arguments. +The only options are @option{--help} and @option{--version}. +@xref{Common options}. + +For example, here's what it prints on one system I use: + +@example +$ hostid +1bac013d +@end example + +On that system, the 32-bit quantity happens to be closely +related to the system's Internet address, but that isn't always +the case. + +@exitstatus + + +@node Modified command invocation +@chapter Modified command invocation + +@cindex modified command invocation +@cindex invocation of commands, modified +@cindex commands for invoking other commands + +This section describes commands that run other commands in some context +different than the current one: a modified environment, as a different +user, etc. + +@menu +* chroot invocation:: Modify the root directory. +* env invocation:: Modify environment variables. +* nice invocation:: Modify niceness. +* nohup invocation:: Immunize to hangups. +* su invocation:: Modify user and group ID. +@end menu + + +@node chroot invocation +@section @command{chroot}: Run a command with a different root directory + +@pindex chroot +@cindex running a program in a specified root directory +@cindex root directory, running a program in a specified + +@command{chroot} runs a command with a specified root directory. +On many systems, only the super-user can do this. +Synopses: + +@example +chroot @var{newroot} [@var{command} [@var{args}]@dots{}] +chroot @var{option} +@end example + +Ordinarily, file names are looked up starting at the root of the +directory structure, i.e., @file{/}. @command{chroot} changes the root to +the directory @var{newroot} (which must exist) and then runs +@var{command} with optional @var{args}. If @var{command} is not +specified, the default is the value of the @env{SHELL} environment +variable or @command{/bin/sh} if not set, invoked with the @option{-i} option. +@var{command} must not be a special built-in utility +(@pxref{Special built-in utilities}). + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. Options must precede operands. + +Here are a few tips to help avoid common problems in using chroot. +To start with a simple example, make @var{command} refer to a statically +linked binary. If you were to use a dynamically linked executable, then +you'd have to arrange to have the shared libraries in the right place under +your new root directory. + +For example, if you create a statically linked @command{ls} executable, +and put it in @file{/tmp/empty}, you can run this command as root: + +@example +$ chroot /tmp/empty /ls -Rl / +@end example + +Then you'll see output like this: + +@example +/: +total 1023 +-rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls +@end example + +If you want to use a dynamically linked executable, say @command{bash}, +then first run @samp{ldd bash} to see what shared objects it needs. +Then, in addition to copying the actual binary, also copy the listed +files to the required positions under your intended new root directory. +Finally, if the executable requires any other files (e.g., data, state, +device files), copy them into place, too. + +@cindex exit status of @command{chroot} +Exit status: + +@display +1 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 +@end display + + +@node env invocation +@section @command{env}: Run a command in a modified environment + +@pindex env +@cindex environment, running a program in a modified +@cindex modified environment, running a program in a +@cindex running a program in a modified environment + +@command{env} runs a command with a modified environment. Synopses: + +@example +env [@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c +[@var{command} [@var{args}]@dots{}] +env +@end example + +Operands of the form @samp{@var{variable}=@var{value}} set +the environment variable @var{variable} to value @var{value}. +@var{value} may be empty (@samp{@var{variable}=}). Setting a variable +to an empty value is different from unsetting it. +These operands are evaluated left-to-right, so if two operands +mention the same variable the earlier is ignored. + +Environment variable names can be empty, and can contain any +characters other than @samp{=} and the null character (@acronym{ASCII} +@sc{nul}). However, it is wise to limit yourself to names that +consist solely of underscores, digits, and @acronym{ASCII} letters, +and that begin with a non-digit, as applications like the shell do not +work well with other names. + +@vindex PATH +The first operand that does not contain the character @samp{=} +specifies the program to invoke; it is +searched for according to the @env{PATH} environment variable. Any +remaining arguments are passed as arguments to that program. +The program should not be a special built-in utility +(@pxref{Special built-in utilities}). + +@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. + +The program accepts the following options. Also see @ref{Common options}. +Options must precede operands. + +@table @samp + +@item -u @var{name} +@itemx --unset=@var{name} +@opindex -u +@opindex --unset +Remove variable @var{name} from the environment, if it was in the +environment. + +@item - +@itemx -i +@itemx --ignore-environment +@opindex - +@opindex -i +@opindex --ignore-environment +Start with an empty environment, ignoring the inherited environment. + +@end table + +@cindex exit status of @command{env} +Exit status: + +@display +0 if no @var{command} is specified and the environment is output +1 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 +@end display + + +@node nice invocation +@section @command{nice}: Run a command with modified niceness + +@pindex nice +@cindex niceness +@cindex scheduling, affecting +@cindex appropriate privileges + +@command{nice} prints or modifies a process's @dfn{niceness}, +a parameter that affects whether the process is scheduled favorably. +Synopsis: + +@example +nice [@var{option}]@dots{} [@var{command} [@var{arg}]@dots{}] +@end example + +If no arguments are given, @command{nice} prints the current niceness. +Otherwise, @command{nice} runs the given @var{command} with its +niceness adjusted. By default, its niceness is incremented by 10. + +Nicenesses range at least from @minus{}20 (resulting in the most +favorable scheduling) through 19 (the least favorable). Some systems +may have a wider range of nicenesses; conversely, other systems may +enforce more restrictive limits. An attempt to set the niceness +outside the supported range is treated as an attempt to use the +minimum or maximum supported value. + +A niceness should not be confused with a scheduling priority, which +lets applications determine the order in which threads are scheduled +to run. Unlike a priority, a niceness is merely advice to the +scheduler, which the scheduler is free to ignore. Also, as a point of +terminology, @acronym{POSIX} defines the behavior of @command{nice} in +terms of a @dfn{nice value}, which is the nonnegative difference +between a niceness and the minimum niceness. Though @command{nice} +conforms to @acronym{POSIX}, its documentation and diagnostics use the +term ``niceness'' for compatibility with historical practice. + +@var{command} must not be a special built-in utility (@pxref{Special +built-in utilities}). + +@cindex conflicts with shell built-ins +@cindex built-in shell commands, conflicts with +Because many shells have a built-in @command{nice} command, using an +unadorned @command{nice} in a script or interactively may get you +different functionality than that described here. + +The program accepts the following option. Also see @ref{Common options}. +Options must precede operands. + +@table @samp +@item -n @var{adjustment} +@itemx --adjustment=@var{adjustment} +@opindex -n +@opindex --adjustment +Add @var{adjustment} instead of 10 to the command's niceness. If +@var{adjustment} is negative and you lack appropriate privileges, +@command{nice} issues a warning but otherwise acts as if you specified +a zero adjustment. + +For compatibility @command{nice} also supports an obsolete +option syntax @option{-@var{adjustment}}. New scripts should use +@option{-n @var{adjustment}} instead. + +@end table + +@cindex exit status of @command{nice} +Exit status: + +@display +0 if no @var{command} is specified and the niceness is output +1 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 +@end display + +It is sometimes useful to run a non-interactive program with reduced niceness. + +@example +$ nice factor 4611686018427387903 +@end example + +Since @command{nice} prints the current niceness, +you can invoke it through itself to demonstrate how it works. + +The default behavior is to increase the niceness by @samp{10}: + +@example +$ nice +0 +$ nice nice +10 +$ nice -n 10 nice +10 +@end example + +The @var{adjustment} is relative to the current niceness. In the +next example, the first @command{nice} invocation runs the second one +with niceness 10, and it in turn runs the final one with a niceness +that is 3 more: + +@example +$ nice nice -n 3 nice +13 +@end example + +Specifying a niceness larger than the supported range +is the same as specifying the maximum supported value: + +@example +$ nice -n 10000000000 nice +19 +@end example + +Only a privileged user may run a process with lower niceness: + +@example +$ nice -n -1 nice +nice: cannot set niceness: Permission denied +0 +$ sudo nice -n -1 nice +-1 +@end example + + +@node nohup invocation +@section @command{nohup}: Run a command immune to hangups + +@pindex nohup +@cindex hangups, immunity to +@cindex immunity to hangups +@cindex logging out and continuing to run + +@flindex nohup.out +@command{nohup} runs the given @var{command} with hangup signals ignored, +so that the command can continue running in the background after you log +out. Synopsis: + +@example +nohup @var{command} [@var{arg}]@dots{} +@end example + +If standard input is a terminal, it is redirected from +@file{/dev/null} so that terminal sessions do not mistakenly consider +the terminal to be used by the command. This is a @acronym{GNU} +extension; programs intended to be portable to non-@acronym{GNU} hosts +should use @samp{nohup @var{command} [@var{arg}]@dots{} </dev/null} +instead. + +@flindex nohup.out +If standard output is a terminal, the command's standard output is appended +to the file @file{nohup.out}; if that cannot be written to, it is appended +to the file @file{$HOME/nohup.out}; and if that cannot be written to, the +command is not run. +Any @file{nohup.out} or @file{$HOME/nohup.out} file created by +@command{nohup} is made readable and writable only to the user, +regardless of the current umask settings. + +If standard error is a terminal, it is normally redirected to the same file +descriptor as the (possibly-redirected) standard output. +However, if standard output is closed, standard error terminal output +is instead appended to the file @file{nohup.out} or +@file{$HOME/nohup.out} as above. + +@command{nohup} does not automatically put the command it runs in the +background; you must do that explicitly, by ending the command line +with an @samp{&}. Also, @command{nohup} does not alter the +niceness of @var{command}; use @command{nice} for that, +e.g., @samp{nohup nice @var{command}}. + +@var{command} must not be a special built-in utility (@pxref{Special +built-in utilities}). + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. Options must precede operands. + +@cindex exit status of @command{nohup} +Exit status: + +@display +126 if @var{command} is found but cannot be invoked +127 if @command{nohup} itself fails or if @var{command} cannot be found +the exit status of @var{command} otherwise +@end display + + +@node su invocation +@section @command{su}: Run a command with substitute user and group ID + +@pindex su +@cindex substitute user and group IDs +@cindex user ID, switching +@cindex super-user, becoming +@cindex root, becoming + +@command{su} allows one user to temporarily become another user. It runs a +command (often an interactive shell) with the real and effective user +ID, group ID, and supplemental groups of a given @var{user}. Synopsis: + +@example +su [@var{option}]@dots{} [@var{user} [@var{arg}]@dots{}] +@end example + +@cindex passwd entry, and @command{su} shell +@flindex /bin/sh +@flindex /etc/passwd +If no @var{user} is given, the default is @code{root}, the super-user. +The shell to use is taken from @var{user}'s @code{passwd} entry, or +@file{/bin/sh} if none is specified there. If @var{user} has a +password, @command{su} prompts for the password unless run by a user with +effective user ID of zero (the super-user). + +@vindex HOME +@vindex SHELL +@vindex USER +@vindex LOGNAME +@cindex login shell +By default, @command{su} does not change the current directory. +It sets the environment variables @env{HOME} and @env{SHELL} +from the password entry for @var{user}, and if @var{user} is not +the super-user, sets @env{USER} and @env{LOGNAME} to @var{user}. +By default, the shell is not a login shell. + +Any additional @var{arg}s are passed as additional arguments to the +shell. + +@cindex @option{-su} +GNU @command{su} does not treat @file{/bin/sh} or any other shells specially +(e.g., by setting @code{argv[0]} to @option{-su}, passing @option{-c} only +to certain shells, etc.). + +@findex syslog +@command{su} can optionally be compiled to use @code{syslog} to report +failed, and optionally successful, @command{su} attempts. (If the system +supports @code{syslog}.) However, GNU @command{su} does not check if the +user is a member of the @code{wheel} group; see below. + +The program accepts the following options. Also see @ref{Common options}. + +@table @samp +@item -c @var{command} +@itemx --command=@var{command} +@opindex -c +@opindex --command +Pass @var{command}, a single command line to run, to the shell with +a @option{-c} option instead of starting an interactive shell. + +@item -f +@itemx --fast +@opindex -f +@opindex --fast +@flindex .cshrc +@cindex file name pattern expansion, disabled +@cindex globbing, disabled +Pass the @option{-f} option to the shell. This probably only makes sense +if the shell run is @command{csh} or @command{tcsh}, for which the @option{-f} +option prevents reading the startup file (@file{.cshrc}). With +Bourne-like shells, the @option{-f} option disables file name pattern +expansion (globbing), which is not likely to be useful. + +@item - +@itemx -l +@itemx --login +@opindex - +@opindex -l +@opindex --login +@c other variables already indexed above +@vindex TERM +@vindex PATH +@cindex login shell, creating +Make the shell a login shell. This means the following. Unset all +environment variables except @env{TERM}, @env{HOME}, and @env{SHELL} +(which are set as described above), and @env{USER} and @env{LOGNAME} +(which are set, even for the super-user, as described above), and set +@env{PATH} to a compiled-in default value. Change to @var{user}'s home +directory. Prepend @samp{-} to the shell's name, intended to make it +read its login startup file(s). + +@item -m +@itemx -p +@itemx --preserve-environment +@opindex -m +@opindex -p +@opindex --preserve-environment +@cindex environment, preserving +@flindex /etc/shells +@cindex restricted shell +Do not change the environment variables @env{HOME}, @env{USER}, +@env{LOGNAME}, or @env{SHELL}. Run the shell given in the environment +variable @env{SHELL} instead of the shell from @var{user}'s passwd +entry, unless the user running @command{su} is not the super-user and +@var{user}'s shell is restricted. A @dfn{restricted shell} is one that +is not listed in the file @file{/etc/shells}, or in a compiled-in list +if that file does not exist. Parts of what this option does can be +overridden by @option{--login} and @option{--shell}. + +@item -s @var{shell} +@itemx --shell=@var{shell} +@opindex -s +@opindex --shell +Run @var{shell} instead of the shell from @var{user}'s passwd entry, +unless the user running @command{su} is not the super-user and @var{user}'s +shell is restricted (see @option{-m} just above). + +@end table + +@cindex exit status of @command{su} +Exit status: + +@display +1 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 +@end display + +@cindex wheel group, not supported +@cindex group wheel, not supported +@cindex fascism +@subsection Why GNU @command{su} does not support the @samp{wheel} group + +(This section is by Richard Stallman.) + +@cindex Twenex +@cindex MIT AI lab +Sometimes a few of the users try to hold total power over all the +rest. For example, in 1984, a few users at the MIT AI lab decided to +seize power by changing the operator password on the Twenex system and +keeping it secret from everyone else. (I was able to thwart this coup +and give power back to the users by patching the kernel, but I +wouldn't know how to do that in Unix.) + +However, occasionally the rulers do tell someone. Under the usual +@command{su} mechanism, once someone learns the root password who +sympathizes with the ordinary users, he or she can tell the rest. The +``wheel group'' feature would make this impossible, and thus cement the +power of the rulers. + +I'm on the side of the masses, not that of the rulers. If you are +used to supporting the bosses and sysadmins in whatever they do, you +might find this idea strange at first. + + +@node Process control +@chapter Process control + +@cindex processes, commands for controlling +@cindex commands for controlling processes + +@menu +* kill invocation:: Sending a signal to processes. +@end menu + + +@node kill invocation +@section @command{kill}: Send a signal to processes + +@pindex kill +@cindex send a signal to processes + +The @command{kill} command sends a signal to processes, causing them +to terminate or otherwise act upon receiving the signal in some way. +Alternatively, it lists information about signals. Synopses: + +@example +kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{} +kill [-l | --list | -t | --table] [@var{signal}]@dots{} +@end example + +The first form of the @command{kill} command sends a signal to all +@var{pid} arguments. The default signal to send if none is specified +is @samp{TERM}. The special signal number @samp{0} does not denote a +valid signal, but can be used to test whether the @var{pid} arguments +specify processes to which a signal could be sent. + +If @var{pid} is positive, the signal is sent to the process with the +process ID @var{pid}. If @var{pid} is zero, the signal is sent to all +processes in the process group of the current process. If @var{pid} +is @minus{}1, the signal is sent to all processes for which the user has +permission to send a signal. If @var{pid} is less than @minus{}1, the signal +is sent to all processes in the process group that equals the absolute +value of @var{pid}. + +If @var{pid} is not positive, a system-dependent set of system +processes is excluded from the list of processes to which the signal +is sent. + +If a negative @var{PID} argument is desired as the first one, it +should be preceded by @option{--}. However, as a common extension to +@acronym{POSIX}, @option{--} is not required with @samp{kill +-@var{signal} -@var{pid}}. The following commands are equivalent: + +@example +kill -15 -1 +kill -TERM -1 +kill -s TERM -- -1 +kill -- -1 +@end example + +The first form of the @command{kill} command succeeds if every @var{pid} +argument specifies at least one process that the signal was sent to. + +The second form of the @command{kill} command lists signal information. +Either the @option{-l} or @option{--list} option, or the @option{-t} +or @option{--table} option must be specified. Without any +@var{signal} argument, all supported signals are listed. The output +of @option{-l} or @option{--list} is a list of the signal names, one +per line; if @var{signal} is already a name, the signal number is +printed instead. The output of @option{-t} or @option{--table} is a +table of signal numbers, names, and descriptions. This form of the +@command{kill} command succeeds if all @var{signal} arguments are valid +and if there is no output error. + +The @command{kill} command also supports the @option{--help} and +@option{--version} options. @xref{Common options}. + +A @var{signal} may be a signal name like @samp{HUP}, or a signal +number like @samp{1}, or an exit status of a process terminated by the +signal. A signal name can be given in canonical form or prefixed by +@samp{SIG}. The case of the letters is ignored, except for the +@option{-@var{signal}} option which must use upper case to avoid +ambiguity with lower case option letters. The following signal names +and numbers are supported on all @acronym{POSIX} compliant systems: + +@table @samp +@item HUP +1. Hangup. +@item INT +2. Terminal interrupt. +@item QUIT +3. Terminal quit. +@item ABRT +6. Process abort. +@item KILL +9. Kill (cannot be caught or ignored). +@item ALRM +14. Alarm Clock. +@item TERM +15. Termination. +@end table + +@noindent +Other supported signal names have system-dependent corresponding +numbers. All systems conforming to @acronym{POSIX} 1003.1-2001 also +support the following signals: + +@table @samp +@item BUS +Access to an undefined portion of a memory object. +@item CHLD +Child process terminated, stopped, or continued. +@item CONT +Continue executing, if stopped. +@item FPE +Erroneous arithmetic operation. +@item ILL +Illegal Instruction. +@item PIPE +Write on a pipe with no one to read it. +@item SEGV +Invalid memory reference. +@item STOP +Stop executing (cannot be caught or ignored). +@item TSTP +Terminal stop. +@item TTIN +Background process attempting read. +@item TTOU +Background process attempting write. +@item URG +High bandwidth data is available at a socket. +@item USR1 +User-defined signal 1. +@item USR2 +User-defined signal 2. +@end table + +@noindent +@acronym{POSIX} 1003.1-2001 systems that support the @acronym{XSI} extension +also support the following signals: + +@table @samp +@item POLL +Pollable event. +@item PROF +Profiling timer expired. +@item SYS +Bad system call. +@item TRAP +Trace/breakpoint trap. +@item VTALRM +Virtual timer expired. +@item XCPU +CPU time limit exceeded. +@item XFSZ +File size limit exceeded. +@end table + +@noindent +@acronym{POSIX} 1003.1-2001 systems that support the @acronym{XRT} extension +also support at least eight real-time signals called @samp{RTMIN}, +@samp{RTMIN+1}, @dots{}, @samp{RTMAX-1}, @samp{RTMAX}. + + +@node Delaying +@chapter Delaying + +@cindex delaying commands +@cindex commands for delaying + +@c Perhaps @command{wait} or other commands should be described here also? + +@menu +* sleep invocation:: Delay for a specified time. +@end menu + + +@node sleep invocation +@section @command{sleep}: Delay for a specified time + +@pindex sleep +@cindex delay for a specified time + +@command{sleep} pauses for an amount of time specified by the sum of +the values of the command line arguments. +Synopsis: + +@example +sleep @var{number}[smhd]@dots{} +@end example + +@cindex time units +Each argument is a number 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 + +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). + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +@exitstatus + + +@node Numeric operations +@chapter Numeric operations + +@cindex numeric operations +These programs do numerically-related operations. + +@menu +* factor invocation:: Show factors of numbers. +* seq invocation:: Print sequences of numbers. +@end menu + + +@node factor invocation +@section @command{factor}: Print prime factors + +@pindex factor +@cindex prime factors + +@command{factor} prints prime factors. Synopses: + +@example +factor [@var{number}]@dots{} +factor @var{option} +@end example + +If no @var{number} is specified on the command line, @command{factor} reads +numbers from standard input, delimited by newlines, tabs, or spaces. + +The only options are @option{--help} and @option{--version}. @xref{Common +options}. + +The algorithm it uses is not very sophisticated, so for some inputs +@command{factor} runs for a long time. The hardest numbers to factor are +the products of large primes. Factoring the product of the two largest 32-bit +prime numbers takes about 80 seconds of CPU time on a 1.6 GHz Athlon. + +@example +$ p=`echo '4294967279 * 4294967291'|bc` +$ factor $p +18446743979220271189: 4294967279 4294967291 +@end example + +Similarly, it takes about 80 seconds for GNU factor (from coreutils-5.1.2) +to ``factor'' the largest 64-bit prime: + +@example +$ factor 18446744073709551557 + 18446744073709551557: 18446744073709551557 +@end example + +In contrast, @command{factor} factors the largest 64-bit number in just +over a tenth of a second: + +@example +$ factor `echo '2^64-1'|bc` +18446744073709551615: 3 5 17 257 641 65537 6700417 +@end example + +@exitstatus + + +@node seq invocation +@section @command{seq}: Print numeric sequences + +@pindex seq +@cindex numeric sequences +@cindex sequence of numbers + +@command{seq} prints a sequence of numbers to standard output. Synopses: + +@example +seq [@var{option}]@dots{} @var{last} +seq [@var{option}]@dots{} @var{first} @var{last} +seq [@var{option}]@dots{} @var{first} @var{increment} @var{last} +@end example + +@command{seq} prints the numbers from @var{first} to @var{last} by +@var{increment}. By default, each number is printed on a separate line. +When @var{increment} is not specified, it defaults to @samp{1}, +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). + +The program accepts the following options. Also see @ref{Common options}. +Options must precede operands. + +@table @samp +@item -f @var{format} +@itemx --format=@var{format} +@opindex -f @var{format} +@opindex --format=@var{format} +@cindex formatting of numbers in @command{seq} +Print all numbers using @var{format}. +@var{format} must contain exactly one of the @samp{printf}-style +floating point conversion specifications @samp{%a}, @samp{%e}, +@samp{%f}, @samp{%g}, @samp{%A}, @samp{%E}, @samp{%F}, @samp{%G}. +The @samp{%} may be followed by zero or more flags taken from the set +@samp{-+#0 '}, then an optional width containing one or more digits, +then an optional precision consisting of a @samp{.} followed by zero +or more digits. @var{format} may also contain any number of @samp{%%} +conversion specifications. All conversion specifications have the +same meaning as with @samp{printf}. + +The default format is derived from @var{first}, @var{step}, and +@var{last}. If these all use a fixed point decimal representation, +the default format is @samp{%.@var{p}f}, where @var{p} is the minimum +precision that can represent the output numbers exactly. Otherwise, +the default format is @samp{%g}. + +@item -s @var{string} +@itemx --separator=@var{string} +@cindex separator for numbers in @command{seq} +Separate numbers with @var{string}; default is a newline. +The output always terminates with a newline. + +@item -w +@itemx --equal-width +Print all numbers with the same width, by padding with leading zeros. +@var{first}, @var{step}, and @var{last} should all use a fixed point +decimal representation. +(To have other kinds of padding, use @option{--format}). + +@end table + +You can get finer-grained control over output with @option{-f}: + +@example +$ seq -f '(%9.2E)' -9e5 1.1e6 1.3e6 +(-9.00E+05) +( 2.00E+05) +( 1.30E+06) +@end example + +If you want hexadecimal integer output, you can use @command{printf} +to perform the conversion: + +@example +$ printf '%x\n' `seq 1048575 1024 1050623` +fffff +1003ff +1007ff +@end example + +For very long lists of numbers, use xargs to avoid +system limitations on the length of an argument list: + +@example +$ seq 1000000 | xargs printf '%x\n' | tail -n 3 +f423e +f423f +f4240 +@end example + +To generate octal output, use the printf @code{%o} format instead +of @code{%x}. + +On most systems, seq can produce whole-number output for values up to +at least @code{2^53}. Larger integers are approximated. The details +differ depending on your floating-point implementation, but a common +case is that @command{seq} works with integers through @code{2^64}, +and larger integers may not be numerically correct: + +@example +$ seq 18446744073709551616 1 18446744073709551618 +18446744073709551616 +18446744073709551616 +18446744073709551618 +@end example + +Be careful when using @command{seq} with a fractional @var{increment}; +otherwise you may see surprising results. Most people would expect to +see @code{0.000003} printed as the last number in this example: + +@example +$ seq -s ' ' 0 0.000001 0.000003 +0.000000 0.000001 0.000002 +@end example + +But that doesn't happen on many systems because @command{seq} is +implemented using binary floating point arithmetic (via the C +@code{long double} type)---which means decimal fractions like @code{0.000001} +cannot be represented exactly. That in turn means some nonintuitive +conditions like @w{@code{0.000001 * 3 > 0.000003}} will end up being true. + +To work around that in the above example, use a slightly larger number as +the @var{last} value: + +@example +$ seq -s ' ' 0 0.000001 0.0000031 +0.000000 0.000001 0.000002 0.000003 +@end example + +In general, when using an @var{increment} with a fractional part, where +(@var{last} - @var{first}) / @var{increment} is (mathematically) a whole +number, specify a slightly larger (or smaller, if @var{increment} is negative) +value for @var{last} to ensure that @var{last} is the final value printed +by seq. + +@exitstatus + + +@node File permissions +@chapter File permissions +@include perm.texi + +@include getdate.texi + +@c What's GNU? +@c Arnold Robbins +@node Opening the software toolbox +@chapter Opening the Software Toolbox + +An earlier version of this chapter appeared in +@uref{http://www.linuxjournal.com/article.php?sid=2762, the +@cite{What's GNU?} column of @cite{Linux Journal}, 2 (June, 1994)}. +It was written by Arnold Robbins. + +@menu +* Toolbox introduction:: Toolbox introduction +* I/O redirection:: I/O redirection +* The who command:: The @command{who} command +* The cut command:: The @command{cut} command +* The sort command:: The @command{sort} command +* The uniq command:: The @command{uniq} command +* Putting the tools together:: Putting the tools together +@end menu + + +@node Toolbox introduction +@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 +might be used. What it's really about is the ``Software Tools'' philosophy +of program development and usage. + +The software tools philosophy was an important and integral concept +in the initial design and development of Unix (of which Linux and GNU are +essentially clones). Unfortunately, in the modern day press of +Internetworking and flashy GUIs, it seems to have fallen by the +wayside. This is a shame, since it provides a powerful mental model +for solving many kinds of problems. + +Many people carry a Swiss Army knife around in their pants pockets (or +purse). A Swiss Army knife is a handy tool to have: it has several knife +blades, a screwdriver, tweezers, toothpick, nail file, corkscrew, and perhaps +a number of other things on it. For the everyday, small miscellaneous jobs +where you need a simple, general purpose tool, it's just the thing. + +On the other hand, an experienced carpenter doesn't build a house using +a Swiss Army knife. Instead, he has a toolbox chock full of specialized +tools---a saw, a hammer, a screwdriver, a plane, and so on. And he knows +exactly when and where to use each tool; you won't catch him hammering nails +with the handle of his screwdriver. + +The Unix developers at Bell Labs were all professional programmers and trained +computer scientists. They had found that while a one-size-fits-all program +might appeal to a user because there's only one program to use, in practice +such programs are + +@enumerate a +@item +difficult to write, + +@item +difficult to maintain and +debug, and + +@item +difficult to extend to meet new situations. +@end enumerate + +Instead, they felt that programs should be specialized tools. In short, each +program ``should do one thing well.'' No more and no less. Such programs are +simpler to design, write, and get right---they only do one thing. + +Furthermore, they found that with the right machinery for hooking programs +together, that the whole was greater than the sum of the parts. By combining +several special purpose programs, you could accomplish a specific task +that none of the programs was designed for, and accomplish it much more +quickly and easily than if you had to write a special purpose program. +We will see some (classic) examples of this further on in the column. +(An important additional point was that, if necessary, take a detour +and build any software tools you may need first, if you don't already +have something appropriate in the toolbox.) + +@node I/O redirection +@unnumberedsec I/O Redirection + +Hopefully, you are familiar with the basics of I/O redirection in the +shell, in particular the concepts of ``standard input,'' ``standard output,'' +and ``standard error''. Briefly, ``standard input'' is a data source, where +data comes from. A program should not need to either know or care if the +data source is a disk file, a keyboard, a magnetic tape, or even a punched +card reader. Similarly, ``standard output'' is a data sink, where data goes +to. The program should neither know nor care where this might be. +Programs that only read their standard input, do something to the data, +and then send it on, are called @dfn{filters}, by analogy to filters in a +water pipeline. + +With the Unix shell, it's very easy to set up data pipelines: + +@smallexample +program_to_create_data | filter1 | ... | filterN > final.pretty.data +@end smallexample + +We start out by creating the raw data; each filter applies some successive +transformation to the data, until by the time it comes out of the pipeline, +it is in the desired form. + +This is fine and good for standard input and standard output. Where does the +standard error come in to play? Well, think about @command{filter1} in +the pipeline above. What happens if it encounters an error in the data it +sees? If it writes an error message to standard output, it will just +disappear down the pipeline into @command{filter2}'s input, and the +user will probably never see it. So programs need a place where they can send +error messages so that the user will notice them. This is standard error, +and it is usually connected to your console or window, even if you have +redirected standard output of your program away from your screen. + +For filter programs to work together, the format of the data has to be +agreed upon. The most straightforward and easiest format to use is simply +lines of text. Unix data files are generally just streams of bytes, with +lines delimited by the @acronym{ASCII} @sc{lf} (Line Feed) character, +conventionally called a ``newline'' in the Unix literature. (This is +@code{'\n'} if you're a C programmer.) This is the format used by all +the traditional filtering programs. (Many earlier operating systems +had elaborate facilities and special purpose programs for managing +binary data. Unix has always shied away from such things, under the +philosophy that it's easiest to simply be able to view and edit your +data with a text editor.) + +OK, enough introduction. Let's take a look at some of the tools, and then +we'll see how to hook them together in interesting ways. In the following +discussion, we will only present those command line options that interest +us. As you should always do, double check your system documentation +for the full story. + +@node The who command +@unnumberedsec The @command{who} Command + +The first program is the @command{who} command. By itself, it generates a +list of the users who are currently logged in. Although I'm writing +this on a single-user system, we'll pretend that several people are +logged in: + +@example +$ who +@print{} arnold console Jan 22 19:57 +@print{} miriam ttyp0 Jan 23 14:19(:0.0) +@print{} bill ttyp1 Jan 21 09:32(:0.0) +@print{} arnold ttyp2 Jan 23 20:48(:0.0) +@end example + +Here, the @samp{$} is the usual shell prompt, at which I typed @samp{who}. +There are three people logged in, and I am logged in twice. On traditional +Unix systems, user names are never more than eight characters long. This +little bit of trivia will be useful later. The output of @command{who} is nice, +but the data is not all that exciting. + +@node The cut command +@unnumberedsec The @command{cut} Command + +The next program we'll look at is the @command{cut} command. This program +cuts out columns or fields of input data. For example, we can tell it +to print just the login name and full name from the @file{/etc/passwd} +file. The @file{/etc/passwd} file has seven fields, separated by +colons: + +@example +arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/bash +@end example + +To get the first and fifth fields, we would use @command{cut} like this: + +@example +$ cut -d: -f1,5 /etc/passwd +@print{} root:Operator +@dots{} +@print{} arnold:Arnold D. Robbins +@print{} miriam:Miriam A. Robbins +@dots{} +@end example + +With the @option{-c} option, @command{cut} will cut out specific characters +(i.e., columns) in the input lines. This is useful for input data +that has fixed width fields, and does not have a field separator. For +example, list the Monday dates for the current month: + +@c Is using cal ok? Looked at gcal, but I don't like it. +@example +$ cal | cut -c 3-5 +@print{}Mo +@print{} +@print{} 6 +@print{} 13 +@print{} 20 +@print{} 27 +@end example + +@node The sort command +@unnumberedsec The @command{sort} Command + +Next we'll look at the @command{sort} command. This is one of the most +powerful commands on a Unix-style system; one that you will often find +yourself using when setting up fancy data plumbing. + +The @command{sort} +command reads and sorts each file named on the command line. It then +merges the sorted data and writes it to standard output. It will read +standard input if no files are given on the command line (thus +making it into a filter). The sort is based on the character collating +sequence or based on user-supplied ordering criteria. + + +@node The uniq command +@unnumberedsec The @command{uniq} Command + +Finally (at least for now), we'll look at the @command{uniq} program. When +sorting data, you will often end up with duplicate lines, lines that +are identical. Usually, all you need is one instance of each line. +This is where @command{uniq} comes in. The @command{uniq} program reads its +standard input. It prints only one +copy of each repeated line. It does have several options. Later on, +we'll use the @option{-c} option, which prints each unique line, preceded +by a count of the number of times that line occurred in the input. + + +@node Putting the tools together +@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 +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. + +The administrator could sit down with the system documentation and write a C +program that did this. It would take perhaps a couple of hundred lines +of code and about two hours to write it, test it, and debug it. +However, knowing the software toolbox, the administrator can instead start out +by generating just a list of logged on users: + +@example +$ who | cut -c1-8 +@print{} arnold +@print{} miriam +@print{} bill +@print{} arnold +@end example + +Next, sort the list: + +@example +$ who | cut -c1-8 | sort +@print{} arnold +@print{} arnold +@print{} bill +@print{} miriam +@end example + +Finally, run the sorted list through @command{uniq}, to weed out duplicates: + +@example +$ who | cut -c1-8 | sort | uniq +@print{} arnold +@print{} bill +@print{} miriam +@end example + +The @command{sort} command actually has a @option{-u} option that does what +@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 +all the users on the system (@samp{#} is the system administrator, +or @code{root}, prompt): + +@example +# cat > /usr/local/bin/listusers +who | cut -c1-8 | sort | uniq +^D +# chmod +x /usr/local/bin/listusers +@end example + +There are four major points to note here. First, with just four +programs, on one command line, the administrator was able to save about two +hours worth of work. Furthermore, the shell pipeline is just about as +efficient as the C program would be, and it is much more efficient in +terms of programmer time. People time is much more expensive than +computer time, and in our modern ``there's never enough time to do +everything'' society, saving two hours of programmer time is no mean +feat. + +Second, it is also important to emphasize that with the +@emph{combination} of the tools, it is possible to do a special +purpose job never imagined by the authors of the individual programs. + +Third, it is also valuable to build up your pipeline in stages, as we did here. +This allows you to view the data at each stage in the pipeline, which helps +you acquire the confidence that you are indeed using these tools correctly. + +Finally, by bundling the pipeline in a shell script, other users can use +your command, without having to remember the fancy plumbing you set up for +them. In terms of how you run them, shell scripts and compiled programs are +indistinguishable. + +After the previous warm-up exercise, we'll look at two additional, more +complicated pipelines. For them, we need to introduce two more tools. + +The first is the @command{tr} command, which stands for ``transliterate.'' +The @command{tr} command works on a character-by-character basis, changing +characters. Normally it is used for things like mapping upper case to +lower case: + +@example +$ echo ThIs ExAmPlE HaS MIXED case! | tr '[:upper:]' '[:lower:]' +@print{} this example has mixed case! +@end example + +There are several options of interest: + +@table @code +@item -c +work on the complement of the listed characters, i.e., +operations apply to characters not in the given set + +@item -d +delete characters in the first set from the output + +@item -s +squeeze repeated characters in the output into just one character. +@end table + +We will be using all three options in a moment. + +The other command we'll look at is @command{comm}. The @command{comm} +command takes two sorted input files as input data, and prints out the +files' lines in three columns. The output columns are the data lines +unique to the first file, the data lines unique to the second file, and +the data lines that are common to both. The @option{-1}, @option{-2}, and +@option{-3} command line options @emph{omit} the respective columns. (This is +non-intuitive and takes a little getting used to.) For example: + +@example +$ cat f1 +@print{} 11111 +@print{} 22222 +@print{} 33333 +@print{} 44444 +$ cat f2 +@print{} 00000 +@print{} 22222 +@print{} 33333 +@print{} 55555 +$ comm f1 f2 +@print{} 00000 +@print{} 11111 +@print{} 22222 +@print{} 33333 +@print{} 44444 +@print{} 55555 +@end example + +The file name @file{-} tells @command{comm} to read standard input +instead of a regular file. + +Now we're ready to build a fancy pipeline. The first application is a word +frequency counter. This helps an author determine if he or she is over-using +certain words. + +The first step is to change the case of all the letters in our input file +to one case. ``The'' and ``the'' are the same word when doing counting. + +@example +$ tr '[:upper:]' '[:lower:]' < whats.gnu | ... +@end example + +The next step is to get rid of punctuation. Quoted words and unquoted words +should be treated identically; it's easiest to just get the punctuation out of +the way. + +@smallexample +$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | ... +@end smallexample + +The second @command{tr} command operates on the complement of the listed +characters, which are all the letters, the digits, the underscore, and +the blank. The @samp{\n} represents the newline character; it has to +be left alone. (The @acronym{ASCII} tab character should also be included for +good measure in a production script.) + +At this point, we have data consisting of words separated by blank space. +The words only contain alphanumeric characters (and the underscore). The +next step is break the data apart so that we have one word per line. This +makes the counting operation much easier, as we will see shortly. + +@smallexample +$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | +> tr -s ' ' '\n' | ... +@end smallexample + +This command turns blanks into newlines. The @option{-s} option squeezes +multiple newline characters in the output into just one. This helps us +avoid blank lines. (The @samp{>} is the shell's ``secondary prompt.'' +This is what the shell prints when it notices you haven't finished +typing in all of a command.) + +We now have data consisting of one word per line, no punctuation, all one +case. We're ready to count each word: + +@smallexample +$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | +> tr -s ' ' '\n' | sort | uniq -c | ... +@end smallexample + +At this point, the data might look something like this: + +@example + 60 a + 2 able + 6 about + 1 above + 2 accomplish + 1 acquire + 1 actually + 2 additional +@end example + +The output is sorted by word, not by count! What we want is the most +frequently used words first. Fortunately, this is easy to accomplish, +with the help of two more @command{sort} options: + +@table @code +@item -n +do a numeric sort, not a textual one + +@item -r +reverse the order of the sort +@end table + +The final pipeline looks like this: + +@smallexample +$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | +> tr -s ' ' '\n' | sort | uniq -c | sort -n -r +@print{} 156 the +@print{} 60 a +@print{} 58 to +@print{} 51 of +@print{} 51 and +@dots{} +@end smallexample + +Whew! That's a lot to digest. Yet, the same principles apply. With six +commands, on two lines (really one long one split for convenience), we've +created a program that does something interesting and useful, in much +less time than we could have written a C program to do the same thing. + +A minor modification to the above pipeline can give us a simple spelling +checker! To determine if you've spelled a word correctly, all you have to +do is look it up in a dictionary. If it is not there, then chances are +that your spelling is incorrect. So, we need a dictionary. +The conventional location for a dictionary is @file{/usr/dict/words}. +On my GNU/Linux system,@footnote{Redhat Linux 6.1, for the November 2000 +revision of this article.} +this is a is a sorted, 45,402 word dictionary. + +Now, how to compare our file with the dictionary? As before, we generate +a sorted list of words, one per line: + +@smallexample +$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | +> tr -s ' ' '\n' | sort -u | ... +@end smallexample + +Now, all we need is a list of words that are @emph{not} in the +dictionary. Here is where the @command{comm} command comes in. + +@smallexample +$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | +> tr -s ' ' '\n' | sort -u | +> comm -23 - /usr/dict/words +@end smallexample + +The @option{-2} and @option{-3} options eliminate lines that are only in the +dictionary (the second file), and lines that are in both files. Lines +only in the first file (standard input, our stream of words), are +words that are not in the dictionary. These are likely candidates for +spelling errors. This pipeline was the first cut at a production +spelling checker on Unix. + +There are some other tools that deserve brief mention. + +@table @command +@item grep +search files for text that matches a regular expression + +@item wc +count lines, words, characters + +@item tee +a T-fitting for data pipes, copies data to files and to standard output + +@item sed +the stream editor, an advanced tool + +@item awk +a data manipulation language, another advanced tool +@end table + +The software tools philosophy also espoused the following bit of +advice: ``Let someone else do the hard part.'' This means, take +something that gives you most of what you need, and then massage it the +rest of the way until it's in the form that you want. + +To summarize: + +@enumerate 1 +@item +Each program should do one thing well. No more, no less. + +@item +Combining programs with appropriate plumbing leads to results where +the whole is greater than the sum of the parts. It also leads to novel +uses of programs that the authors might never have imagined. + +@item +Programs should never print extraneous header or trailer data, since these +could get sent on down a pipeline. (A point we didn't mention earlier.) + +@item +Let someone else do the hard part. + +@item +Know your toolbox! Use each program appropriately. If you don't have an +appropriate tool, build one. +@end enumerate + +As of this writing, all the programs we've discussed are available via +anonymous @command{ftp} from: @* +@uref{ftp://gnudist.gnu.org/textutils/textutils-1.22.tar.gz}. (There may +be more recent versions available now.) + +None of what I have presented in this column is new. The Software Tools +philosophy was first introduced in the book @cite{Software Tools}, by +Brian Kernighan and P.J. Plauger (Addison-Wesley, ISBN 0-201-03669-X). +This book showed how to write and use software tools. It was written in +1976, using a preprocessor for FORTRAN named @command{ratfor} (RATional +FORtran). At the time, C was not as ubiquitous as it is now; FORTRAN +was. The last chapter presented a @command{ratfor} to FORTRAN +processor, written in @command{ratfor}. @command{ratfor} looks an awful +lot like C; if you know C, you won't have any problem following the +code. + +In 1981, the book was updated and made available as @cite{Software Tools +in Pascal} (Addison-Wesley, ISBN 0-201-10342-7). Both books are +still in print and are well worth +reading if you're a programmer. They certainly made a major change in +how I view programming. + +The programs in both books are available from +@uref{http://cm.bell-labs.com/who/bwk, Brian Kernighan's home page}. +For a number of years, there was an active +Software Tools Users Group, whose members had ported the original +@command{ratfor} programs to essentially every computer system with a +FORTRAN compiler. The popularity of the group waned in the middle 1980s +as Unix began to spread beyond universities. + +With the current proliferation of GNU code and other clones of Unix programs, +these programs now receive little attention; modern C versions are +much more efficient and do more than these programs do. Nevertheless, as +exposition of good programming style, and evangelism for a still-valuable +philosophy, these books are unparalleled, and I recommend them highly. + +Acknowledgment: I would like to express my gratitude to Brian Kernighan +of Bell Labs, the original Software Toolsmith, for reviewing this column. + +@node Copying This Manual +@appendix Copying This Manual + +@menu +* GNU Free Documentation License:: License for copying this manual. +@end menu + +@include fdl.texi + +@node Index +@unnumbered Index + +@printindex cp + +@shortcontents +@contents +@bye + +@c Local variables: +@c texinfo-column-for-description: 32 +@c End: diff --git a/doc/fdl.texi b/doc/fdl.texi new file mode 100644 index 0000000..9c6d9af --- /dev/null +++ b/doc/fdl.texi @@ -0,0 +1,452 @@ + +@node GNU Free Documentation License +@appendixsec GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@center Version 1.2, November 2002 + +@display +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + diff --git a/doc/getdate.texi b/doc/getdate.texi new file mode 100644 index 0000000..eae4526 --- /dev/null +++ b/doc/getdate.texi @@ -0,0 +1,553 @@ +@c GNU date syntax documentation + +@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +@node Date input formats +@chapter Date input formats + +@cindex date input formats +@findex get_date + +First, a quote: + +@quotation +Our units of temporal measurement, from seconds on up to months, are so +complicated, asymmetrical and disjunctive so as to make coherent mental +reckoning in time all but impossible. Indeed, had some tyrannical god +contrived to enslave our minds to time, to make it all but impossible +for us to escape subjection to sodden routines and unpleasant surprises, +he could hardly have done better than handing down our present system. +It is like a set of trapezoidal building blocks, with no vertical or +horizontal surfaces, like a language in which the simplest thought +demands ornate constructions, useless particles and lengthy +circumlocutions. Unlike the more successful patterns of language and +science, which enable us to face experience boldly or at least +level-headedly, our system of temporal calculation silently and +persistently encourages our terror of time. + +@dots{} It is as though architects had to measure length in feet, width +in meters and height in ells; as though basic instruction manuals +demanded a knowledge of five different languages. It is no wonder then +that we often look into our own immediate past or future, last Tuesday +or a week from Sunday, with feelings of helpless confusion. @dots{} + +--- Robert Grudin, @cite{Time and the Art of Living}. +@end quotation + +This section describes the textual date representations that @sc{gnu} +programs accept. These are the strings you, as a user, can supply as +arguments to the various programs. The C interface (via the +@code{get_date} function) is not described here. + +@menu +* 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. +@end menu + + +@node General date syntax +@section General date syntax + +@cindex general date syntax + +@cindex items in date strings +A @dfn{date} is a string, possibly empty, containing many items +separated by whitespace. The whitespace may be omitted when no +ambiguity arises. The empty string means the beginning of today (i.e., +midnight). Order of the items is immaterial. A date string may contain +many flavors of items: + +@itemize @bullet +@item calendar date items +@item time of day items +@item time zone items +@item day of the week items +@item relative items +@item pure numbers. +@end itemize + +@noindent We describe each of these item types in turn, below. + +@cindex numbers, written-out +@cindex ordinal numbers +@findex first @r{in date strings} +@findex next @r{in date strings} +@findex last @r{in date strings} +A few ordinal numbers may be written out in words in some contexts. This is +most useful for specifying day of the week items or relative items (see +below). Among the most commonly used ordinal numbers, the word +@samp{last} stands for @math{-1}, @samp{this} stands for 0, and +@samp{first} and @samp{next} both stand for 1. Because the word +@samp{second} stands for the unit of time there is no way to write the +ordinal number 2, but for convenience @samp{third} stands for 3, +@samp{fourth} for 4, @samp{fifth} for 5, +@samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8, +@samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and +@samp{twelfth} for 12. + +@cindex months, written-out +When a month is written this way, it is still considered to be written +numerically, instead of being ``spelled in full''; this changes the +allowed strings. + +@cindex language, in dates +In the current implementation, only English is supported for words and +abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first}, +@samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}. + +@cindex language, in dates +@cindex time zone item +The output of the @command{date} command +is not always acceptable as a date string, +not only because of the language problem, but also because there is no +standard meaning for time zone items like @samp{IST}. When using +@command{date} to generate a date string intended to be parsed later, +specify a date format that is independent of language and that does not +use time zone items other than @samp{UTC} and @samp{Z}. Here are some +ways to do this: + +@example +$ LC_ALL=C TZ=UTC0 date +Mon Mar 1 00:21:42 UTC 2004 +$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' +2004-03-01 00:21:42Z +$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. +2004-02-29 16:21:42,692722128-0800 +$ date --rfc-2822 # a GNU extension +Sun, 29 Feb 2004 16:21:42 -0800 +$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. +2004-02-29 16:21:42 -0800 +$ date +'@@%s.%N' # %s and %N are GNU extensions. +@@1078100502.692722128 +@end example + +@cindex case, ignored in dates +@cindex comments, in dates +Alphabetic case is completely ignored in dates. Comments may be introduced +between round parentheses, as long as included parentheses are properly +nested. Hyphens not followed by a digit are currently ignored. Leading +zeros on numbers are ignored. + +Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are +rejected. In the typical case of a host that does not support leap +seconds, a time like @samp{23:59:60} is rejected even if it +corresponds to a valid leap second. + + +@node Calendar date items +@section Calendar date items + +@cindex calendar date item + +A @dfn{calendar date item} specifies a day of the year. It is +specified differently, depending on whether the month is specified +numerically or literally. All these strings specify the same calendar date: + +@example +1972-09-24 # @sc{iso} 8601. +72-9-24 # Assume 19xx for 69 through 99, + # 20xx for 00 through 68. +72-09-24 # Leading zeros are ignored. +9/24/72 # Common U.S. writing. +24 September 1972 +24 Sept 72 # September has a special abbreviation. +24 Sep 72 # Three-letter abbreviations always allowed. +Sep 24, 1972 +24-sep-72 +24sep72 +@end example + +The year can also be omitted. In this case, the last specified year is +used, or the current year if none. For example: + +@example +9/24 +sep 24 +@end example + +Here are the rules. + +@cindex @sc{iso} 8601 date format +@cindex date format, @sc{iso} 8601 +For numeric months, the @sc{iso} 8601 format +@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is +any positive number, @var{month} is a number between 01 and 12, and +@var{day} is a number between 01 and 31. A leading zero must be present +if a number is less than ten. If @var{year} is 68 or smaller, then 2000 +is added to it; otherwise, if @var{year} is less than 100, +then 1900 is added to it. The construct +@samp{@var{month}/@var{day}/@var{year}}, popular in the United States, +is accepted. Also @samp{@var{month}/@var{day}}, omitting the year. + +@cindex month names in date strings +@cindex abbreviations for months +Literal months may be spelled out in full: @samp{January}, +@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June}, +@samp{July}, @samp{August}, @samp{September}, @samp{October}, +@samp{November} or @samp{December}. Literal months may be abbreviated +to their first three letters, possibly followed by an abbreviating dot. +It is also permitted to write @samp{Sept} instead of @samp{September}. + +When months are written literally, the calendar date may be given as any +of the following: + +@example +@var{day} @var{month} @var{year} +@var{day} @var{month} +@var{month} @var{day} @var{year} +@var{day}-@var{month}-@var{year} +@end example + +Or, omitting the year: + +@example +@var{month} @var{day} +@end example + + +@node Time of day items +@section Time of day items + +@cindex time of day item + +A @dfn{time of day item} in date strings specifies the time on a given +day. Here are some examples, all of which represent the same time: + +@example +20:02:00.000000 +20:02 +8:02pm +20:02-0500 # In @sc{est} (U.S. Eastern Standard Time). +@end example + +More generally, the time of day may be given as +@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is +a number between 0 and 23, @var{minute} is a number between 0 and +59, and @var{second} is a number between 0 and 59 possibly followed by +@samp{.} or @samp{,} and a fraction containing one or more digits. +Alternatively, +@samp{:@var{second}} can be omitted, in which case it is taken to +be zero. On the rare hosts that support leap seconds, @var{second} +may be 60. + +@findex am @r{in date strings} +@findex pm @r{in date strings} +@findex midnight @r{in date strings} +@findex noon @r{in date strings} +If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.} +or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and +@samp{:@var{minute}} may be omitted (taken to be zero). @samp{am} +indicates the first half of the day, @samp{pm} indicates the second +half of the day. In this notation, 12 is the predecessor of 1: +midnight is @samp{12am} while noon is @samp{12pm}. +(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm}, +as opposed to the old tradition derived from Latin +which uses @samp{12m} for noon and @samp{12pm} for midnight.) + +@cindex time zone correction +@cindex minutes, time zone correction by +The time may alternatively be followed by a time zone correction, +expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+} +or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number +of zone minutes. You can also separate @var{hh} from @var{mm} with a colon. +When a time zone correction is given this way, it +forces interpretation of the time relative to +Coordinated Universal Time (@sc{utc}), overriding any previous +specification for the time zone or the local time zone. For example, +@samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours +ahead of @sc{utc} (e.g., India). The @var{minute} +part of the time of day may not be elided when a time zone correction +is used. This is the best way to specify a time zone correction by +fractional parts of an hour. + +Either @samp{am}/@samp{pm} or a time zone correction may be specified, +but not both. + + +@node Time zone items +@section Time zone items + +@cindex time zone item + +A @dfn{time zone item} specifies an international time zone, indicated +by a small set of letters, e.g., @samp{UTC} or @samp{Z} +for Coordinated Universal +Time. Any included periods are ignored. By following a +non-daylight-saving time zone by the string @samp{DST} in a separate +word (that is, separated by some white space), the corresponding +daylight saving time zone may be specified. +Alternatively, a non-daylight-saving time zone can be followed by a +time zone correction, to add the two values. This is normally done +only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to +@samp{+05:30}. + +Time zone items other than @samp{UTC} and @samp{Z} +are obsolescent and are not recommended, because they +are ambiguous; for example, @samp{EST} has a different meaning in +Australia than in the United States. Instead, it's better to use +unambiguous numeric time zone corrections like @samp{-0500}, as +described in the previous section. + +If neither a time zone item nor a time zone correction is supplied, +time stamps are interpreted using the rules of the default time zone +(@pxref{Specifying time zone rules}). + + +@node Day of week items +@section Day of week items + +@cindex day of week item + +The explicit mention of a day of the week will forward the date +(only if necessary) to reach that day of the week in the future. + +Days of the week may be spelled out in full: @samp{Sunday}, +@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday}, +@samp{Friday} or @samp{Saturday}. Days may be abbreviated to their +first three letters, optionally followed by a period. The special +abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for +@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are +also allowed. + +@findex next @var{day} +@findex last @var{day} +A number may precede a day of the week item to move forward +supplementary weeks. It is best used in expression like @samp{third +monday}. In this context, @samp{last @var{day}} or @samp{next +@var{day}} is also acceptable; they move one week before or after +the day that @var{day} by itself would represent. + +A comma following a day of the week item is ignored. + + +@node Relative items in date strings +@section Relative items in date strings + +@cindex relative items in date strings +@cindex displacement of dates + +@dfn{Relative items} adjust a date (or the current date if none) forward +or backward. The effects of relative items accumulate. Here are some +examples: + +@example +1 year +1 year ago +3 years +2 days +@end example + +@findex year @r{in date strings} +@findex month @r{in date strings} +@findex fortnight @r{in date strings} +@findex week @r{in date strings} +@findex day @r{in date strings} +@findex hour @r{in date strings} +@findex minute @r{in date strings} +The unit of time displacement may be selected by the string @samp{year} +or @samp{month} for moving by whole years or months. These are fuzzy +units, as years and months are not all of equal duration. More precise +units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7 +days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes, +@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or +@samp{sec} worth one second. An @samp{s} suffix on these units is +accepted and ignored. + +@findex ago @r{in date strings} +The unit of time may be preceded by a multiplier, given as an optionally +signed number. Unsigned numbers are taken as positively signed. No +number at all implies 1 for a multiplier. Following a relative item by +the string @samp{ago} is equivalent to preceding the unit by a +multiplier with value @math{-1}. + +@findex day @r{in date strings} +@findex tomorrow @r{in date strings} +@findex yesterday @r{in date strings} +The string @samp{tomorrow} is worth one day in the future (equivalent +to @samp{day}), the string @samp{yesterday} is worth +one day in the past (equivalent to @samp{day ago}). + +@findex now @r{in date strings} +@findex today @r{in date strings} +@findex this @r{in date strings} +The strings @samp{now} or @samp{today} are relative items corresponding +to zero-valued time displacement, these strings come from the fact +a zero-valued time displacement represents the current time when not +otherwise changed by previous items. They may be used to stress other +items, like in @samp{12:00 today}. The string @samp{this} also has +the meaning of a zero-valued time displacement, but is preferred in +date strings like @samp{this thursday}. + +When a relative item causes the resulting date to cross a boundary +where the clocks were adjusted, typically for daylight saving time, +the resulting date and time are adjusted accordingly. + +The fuzz in units can cause problems with relative items. For +example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01, +because 2003-06-31 is an invalid date. To determine the previous +month more reliably, you can ask for the month before the 15th of the +current month. For example: + +@example +$ date -R +Thu, 31 Jul 2003 13:02:39 -0700 +$ date --date='-1 month' +'Last month was %B?' +Last month was July? +$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' +Last month was June! +@end example + +Also, take care when manipulating dates around clock changes such as +daylight saving leaps. In a few cases these have added or subtracted +as much as 24 hours from the clock, so it is often wise to adopt +universal time by setting the @env{TZ} environment variable to +@samp{UTC0} before embarking on calendrical calculations. + +@node Pure numbers in date strings +@section Pure numbers in date strings + +@cindex pure numbers in date strings + +The precise interpretation of a pure decimal number depends +on the context in the date string. + +If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no +other calendar date item (@pxref{Calendar date items}) appears before it +in the date string, then @var{yyyy} is read as the year, @var{mm} as the +month number and @var{dd} as the day of the month, for the specified +calendar date. + +If the decimal number is of the form @var{hh}@var{mm} and no other time +of day item appears before it in the date string, then @var{hh} is read +as the hour of the day and @var{mm} as the minute of the hour, for the +specified time of day. @var{mm} can also be omitted. + +If both a calendar date and a time of day appear to the left of a number +in the date string, but no relative item, then the number overrides the +year. + + +@node Seconds since the Epoch +@section Seconds since the Epoch + +If you precede a number with @samp{@@}, it represents an internal time +stamp as a count of seconds. The number can contain an internal +decimal point (either @samp{.} or @samp{,}); any excess precision not +supported by the internal representation is truncated toward minus +infinity. Such a number cannot be combined with any other date +item, as it specifies a complete time stamp. + +@cindex beginning of time, for @acronym{POSIX} +@cindex epoch, for @acronym{POSIX} +Internally, computer times are represented as a count of seconds since +an epoch---a well-defined point of time. On @acronym{GNU} and +@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so +@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01 +00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other +@acronym{POSIX}-compliant systems support such times as an extension +to @acronym{POSIX}, using negative counts, so that @samp{@@-1} +represents 1969-12-31 23:59:59 @sc{utc}. + +Traditional Unix systems count seconds with 32-bit two's-complement +integers and can represent times from 1901-12-13 20:45:52 through +2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts +of seconds with nanosecond subcounts, and can represent all the times +in the known lifetime of the universe to a resolution of 1 nanosecond. + +On most hosts, these counts ignore the presence of leap seconds. +For example, on most hosts @samp{@@915148799} represents 1998-12-31 +23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00 +@sc{utc}, and there is no way to represent the intervening leap second +1998-12-31 23:59:60 @sc{utc}. + +@node Specifying time zone rules +@section Specifying time zone rules + +@vindex TZ +Normally, dates are interpreted using the rules of the current time +zone, which in turn are specified by the @env{TZ} environment +variable, or by a system default if @env{TZ} is not set. To specify a +different set of default time zone rules that apply just to one date, +start the date with a string of the form @samp{TZ="@var{rule}"}. The +two quote characters (@samp{"}) must be present in the date, and any +quotes or backslashes within @var{rule} must be escaped by a +backslash. + +For example, with the @acronym{GNU} @command{date} command you can +answer the question ``What time is it in New York when a Paris clock +shows 6:30am on October 31, 2004?'' by using a date beginning with +@samp{TZ="Europe/Paris"} as shown in the following shell transcript: + +@example +$ export TZ="America/New_York" +$ date --date='TZ="Europe/Paris" 2004-10-31 06:30' +Sun Oct 31 01:30:00 EDT 2004 +@end example + +In this example, the @option{--date} operand begins with its own +@env{TZ} setting, so the rest of that operand is processed according +to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31 +06:30} as if it were in Paris. However, since the output of the +@command{date} command is processed according to the overall time zone +rules, it uses New York time. (Paris was normally six hours ahead of +New York in 2004, but this example refers to a brief Halloween period +when the gap was five hours.) + +A @env{TZ} value is a rule that typically names a location in the +@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}. +A recent catalog of location names appears in the +@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time +Gateway}. A few non-@acronym{GNU} hosts require a colon before a +location name in a @env{TZ} setting, e.g., +@samp{TZ=":America/New_York"}. + +The @samp{tz} database includes a wide variety of locations ranging +from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but +if you are at sea and have your own private time zone, or if you are +using a non-@acronym{GNU} host that does not support the @samp{tz} +database, you may need to use a @acronym{POSIX} rule instead. Simple +@acronym{POSIX} rules like @samp{UTC0} specify a time zone without +daylight saving time; other rules can specify simple daylight saving +regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ}, +libc, The GNU C Library}. + +@node Authors of get_date +@section Authors of @code{get_date} + +@cindex authors of @code{get_date} + +@cindex Bellovin, Steven M. +@cindex Salz, Rich +@cindex Berets, Jim +@cindex MacKenzie, David +@cindex Meyering, Jim +@cindex Eggert, Paul +@code{get_date} was originally implemented by Steven M. Bellovin +(@email{smb@@research.att.com}) while at the University of North Carolina +at Chapel Hill. The code was later tweaked by a couple of people on +Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com}) +and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various +revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering, +Paul Eggert and others. + +@cindex Pinard, F. +@cindex Berry, K. +This chapter was originally produced by Fran@,{c}ois Pinard +(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code, +and then edited by K.@: Berry (@email{kb@@cs.umb.edu}). diff --git a/doc/perm.texi b/doc/perm.texi new file mode 100644 index 0000000..78b5919 --- /dev/null +++ b/doc/perm.texi @@ -0,0 +1,604 @@ +@c File mode bits + +@c Copyright (C) 1994, 1996, 1999, 2000, 2001, 2003, 2004, 2005, 2006 +@c Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +Each file has a set of @dfn{file mode bits} that control the kinds of +access that users have to that file. They can be represented either in +symbolic form or as an octal number. + +@menu +* 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. +@end menu + +@node Mode Structure +@section Structure of File Mode Bits + +The file mode bits have two parts: the @dfn{file permission bits}, +which control ordinary access to the file, and @dfn{special mode +bits}, which affect only some files. + +There are three kinds of permissions that a user can have for a file: + +@enumerate +@item +@cindex read permission +permission to read the file. For directories, this means permission to +list the contents of the directory. +@item +@cindex write permission +permission to write to (change) the file. For directories, this means +permission to create and remove files in the directory. +@item +@cindex execute/search permission +permission to execute the file (run it as a program). For directories, +this means permission to access files in the directory. +@end enumerate + +There are three categories of users who may have different permissions +to perform any of the above operations on a file: + +@enumerate +@item +the file's owner; +@item +other users who are in the file's group; +@item +everyone else. +@end enumerate + +@cindex owner, default +@cindex group owner, default +Files are given an owner and group when they are created. Usually the +owner is the current user and the group is the group of the directory +the file is in, but this varies with the operating system, the +file system the file is created on, and the way the file is created. You +can change the owner and group of a file by using the @command{chown} and +@command{chgrp} commands. + +In addition to the three sets of three permissions listed above, the +file mode bits have three special components, which affect only +executable files (programs) and, on most systems, directories: + +@enumerate +@item +@cindex set-user-ID +@cindex setuid +Set the process's effective user ID to that of the file upon execution +(called the @dfn{set-user-ID bit}, or sometimes the @dfn{setuid bit}). +For directories on a few systems, give files created in the directory +the same owner as the directory, no matter who creates them, and set +the set-user-ID bit of newly-created subdirectories. +@item +@cindex set-group-ID +@cindex setgid +Set the process's effective group ID to that of the file upon execution +(called the @dfn{set-group-ID bit}, or sometimes the @dfn{setgid bit}). +For directories on most systems, give files created in the directory +the same group as the directory, no matter what group the user who +creates them is in, and set the set-group-ID bit of newly-created +subdirectories. +@item +@cindex sticky +@cindex swap space, saving text image in +@cindex text image, saving in swap space +@cindex restricted deletion flag +Prevent unprivileged users from removing or renaming a file in a directory +unless they own the file or the directory; this is called the +@dfn{restricted deletion flag} for the directory, and is commonly +found on world-writable directories like @file{/tmp}. + +For regular files on some older systems, save the program's text image on the +swap device so it will load more quickly when run; this is called the +@dfn{sticky bit}. +@end enumerate + +In addition to the file mode bits listed above, there may be file attributes +specific to the file system, e.g., access control lists (ACLs), whether a +file is compressed, whether a file can be modified (immutability), and whether +a file can be dumped. These are usually set using programs +specific to the file system. For example: +@c should probably say a lot more about ACLs... someday + +@table @asis +@item ext2 +On @acronym{GNU} and @acronym{GNU}/Linux the file attributes specific to +the ext2 file system are set using @command{chattr}. + +@item FFS +On FreeBSD the file flags specific to the FFS +file system are set using @command{chflags}. +@end table + +Even if a file's mode bits allow an operation on that file, +that operation may still fail, because: + +@itemize +@item +the file-system-specific attributes or flags do not permit it; or + +@item +the file system is mounted as read-only. +@end itemize + +For example, if the immutable attribute is set on a file, +it cannot be modified, regardless of the fact that you +may have just run @code{chmod a+w FILE}. + +@node Symbolic Modes +@section Symbolic Modes + +@cindex symbolic modes +@dfn{Symbolic modes} represent changes to files' mode bits as +operations on single-character symbols. They allow you to modify either +all or selected parts of files' mode bits, optionally based on +their previous values, and perhaps on the current @code{umask} as well +(@pxref{Umask and Protection}). + +The format of symbolic modes is: + +@example +@r{[}ugoa@dots{}@r{][}+-=@r{]}@var{perms}@dots{}@r{[},@dots{}@r{]} +@end example + +@noindent +where @var{perms} is either zero or more letters from the set +@samp{rwxXst}, or a single letter from the set @samp{ugo}. + +The following sections describe the operators and other details of +symbolic modes. + +@menu +* Setting Permissions:: Basic operations on permissions. +* Copying Permissions:: Copying existing permissions. +* Changing Special Mode Bits:: Special mode bits. +* Conditional Executability:: Conditionally affecting executability. +* Multiple Changes:: Making multiple changes. +* Umask and Protection:: The effect of the umask. +@end menu + +@node Setting Permissions +@subsection Setting Permissions + +The basic symbolic operations on a file's permissions are adding, +removing, and setting the permission that certain users have to read, +write, and execute or search the file. These operations have the following +format: + +@example +@var{users} @var{operation} @var{permissions} +@end example + +@noindent +The spaces between the three parts above are shown for readability only; +symbolic modes cannot contain spaces. + +The @var{users} part tells which users' access to the file is changed. +It consists of one or more of the following letters (or it can be empty; +@pxref{Umask and Protection}, for a description of what happens then). When +more than one of these letters is given, the order that they are in does +not matter. + +@table @code +@item u +@cindex owner of file, permissions for +the user who owns the file; +@item g +@cindex group, permissions for +other users who are in the file's group; +@item o +@cindex other permissions +all other users; +@item a +all users; the same as @samp{ugo}. +@end table + +The @var{operation} part tells how to change the affected users' access +to the file, and is one of the following symbols: + +@table @code +@item + +@cindex adding permissions +to add the @var{permissions} to whatever permissions the @var{users} +already have for the file; +@item - +@cindex removing permissions +@cindex subtracting permissions +to remove the @var{permissions} from whatever permissions the +@var{users} already have for the file; +@item = +@cindex setting permissions +to make the @var{permissions} the only permissions that the @var{users} +have for the file. +@end table + +The @var{permissions} part tells what kind of access to the file should +be changed; it is normally zero or more of the following letters. As with the +@var{users} part, the order does not matter when more than one letter is +given. Omitting the @var{permissions} part is useful only with the +@samp{=} operation, where it gives the specified @var{users} no access +at all to the file. + +@table @code +@item r +@cindex read permission, symbolic +the permission the @var{users} have to read the file; +@item w +@cindex write permission, symbolic +the permission the @var{users} have to write to the file; +@item x +@cindex execute/search permission, symbolic +the permission the @var{users} have to execute the file, +or search it if it is a directory. +@end table + +For example, to give everyone permission to read and write a regular file, +but not to execute it, use: + +@example +a=rw +@end example + +To remove write permission for all users other than the file's +owner, use: + +@example +go-w +@end example + +@noindent +The above command does not affect the access that the owner of +the file has to it, nor does it affect whether other users can +read or execute the file. + +To give everyone except a file's owner no permission to do anything with +that file, use the mode below. Other users could still remove the file, +if they have write permission on the directory it is in. + +@example +go= +@end example + +@noindent +Another way to specify the same thing is: + +@example +og-rwx +@end example + +@node Copying Permissions +@subsection Copying Existing Permissions + +@cindex copying existing permissions +@cindex permissions, copying existing +You can base a file's permissions on its existing permissions. To do +this, instead of using a series of @samp{r}, @samp{w}, or @samp{x} +letters after the +operator, you use the letter @samp{u}, @samp{g}, or @samp{o}. For +example, the mode + +@example +o+g +@end example + +@noindent +adds the permissions for users who are in a file's group to the +permissions that other users have for the file. Thus, if the file +started out as mode 664 (@samp{rw-rw-r--}), the above mode would change +it to mode 666 (@samp{rw-rw-rw-}). If the file had started out as mode +741 (@samp{rwxr----x}), the above mode would change it to mode 745 +(@samp{rwxr--r-x}). The @samp{-} and @samp{=} operations work +analogously. + +@node Changing Special Mode Bits +@subsection Changing Special Mode Bits + +@cindex changing special mode bits +In addition to changing a file's read, write, and execute/search permissions, +you can change its special mode bits. @xref{Mode Structure}, for a +summary of these special mode bits. + +To change the file mode bits to set the user ID on execution, use +@samp{u} in the @var{users} part of the symbolic mode and +@samp{s} in the @var{permissions} part. + +To change the file mode bits to set the group ID on execution, use +@samp{g} in the @var{users} part of the symbolic mode and +@samp{s} in the @var{permissions} part. + +To set both user and group ID on execution, omit the @var{users} part +of the symbolic mode (or use @samp{a}) and use @samp{s} in the +@var{permissions} part. + +To change the file mode bits to set the restricted deletion flag or sticky bit, +omit the @var{users} part of the symbolic mode (or use @samp{a}) and use +@samp{t} in the @var{permissions} part. + +For example, to set the set-user-ID mode bit of a program, +you can use the mode: + +@example +u+s +@end example + +To remove both set-user-ID and set-group-ID mode bits from +it, you can use the mode: + +@example +a-s +@end example + +To set the restricted deletion flag or sticky bit, you can use +the mode: + +@example ++t +@end example + +The combination @samp{o+s} has no effect. On @acronym{GNU} systems +the combinations @samp{u+t} and @samp{g+t} have no effect, and +@samp{o+t} acts like plain @samp{+t}. + +The @samp{=} operator is not very useful with special mode bits. +For example, the mode: + +@example +o=t +@end example + +@noindent +does set the restricted deletion flag or sticky bit, but it also +removes all read, write, and execute/search permissions that users not in the +file's group might have had for it. + +@xref{Directory Setuid and Setgid}, for additional rules concerning +set-user-ID and set-group-ID bits and directories. + +@node Conditional Executability +@subsection Conditional Executability + +@cindex conditional executability +There is one more special type of symbolic permission: if you use +@samp{X} instead of @samp{x}, execute/search permission is affected only if the +file is a directory or already had execute permission. + +For example, this mode: + +@example +a+X +@end example + +@noindent +gives all users permission to search directories, or to execute files if +anyone could execute them before. + +@node Multiple Changes +@subsection Making Multiple Changes + +@cindex multiple changes to permissions +The format of symbolic modes is actually more complex than described +above (@pxref{Setting Permissions}). It provides two ways to make +multiple changes to files' mode bits. + +The first way is to specify multiple @var{operation} and +@var{permissions} parts after a @var{users} part in the symbolic mode. + +For example, the mode: + +@example +og+rX-w +@end example + +@noindent +gives users other than the owner of the file read permission and, if +it is a directory or if someone already had execute permission +to it, gives them execute/search permission; and it also denies them write +permission to the file. It does not affect the permission that the +owner of the file has for it. The above mode is equivalent to +the two modes: + +@example +og+rX +og-w +@end example + +The second way to make multiple changes is to specify more than one +simple symbolic mode, separated by commas. For example, the mode: + +@example +a+r,go-w +@end example + +@noindent +gives everyone permission to read the file and removes write +permission on it for all users except its owner. Another example: + +@example +u=rwx,g=rx,o= +@end example + +@noindent +sets all of the permission bits for the file explicitly. (It +gives users who are not in the file's group no permission at all for +it.) + +The two methods can be combined. The mode: + +@example +a+r,g+x-w +@end example + +@noindent +gives all users permission to read the file, and gives users who are in +the file's group permission to execute/search it as well, but not permission +to write to it. The above mode could be written in several different +ways; another is: + +@example +u+r,g+rx,o+r,g-w +@end example + +@node Umask and Protection +@subsection The Umask and Protection + +@cindex umask and modes +@cindex modes and umask +If the @var{users} part of a symbolic mode is omitted, it defaults to +@samp{a} (affect all users), except that any permissions that are +@emph{set} in the system variable @code{umask} are @emph{not affected}. +The value of @code{umask} can be set using the +@code{umask} command. Its default value varies from system to system. + +@cindex giving away permissions +Omitting the @var{users} part of a symbolic mode is generally not useful +with operations other than @samp{+}. It is useful with @samp{+} because +it allows you to use @code{umask} as an easily customizable protection +against giving away more permission to files than you intended to. + +As an example, if @code{umask} has the value 2, which removes write +permission for users who are not in the file's group, then the mode: + +@example ++w +@end example + +@noindent +adds permission to write to the file to its owner and to other users who +are in the file's group, but @emph{not} to other users. In contrast, +the mode: + +@example +a+w +@end example + +@noindent +ignores @code{umask}, and @emph{does} give write permission for +the file to all users. + +@node Numeric Modes +@section Numeric Modes + +@cindex numeric modes +@cindex file mode bits, numeric +@cindex octal numbers for file modes +As an +alternative to giving a symbolic mode, you can give an octal (base 8) +number that represents the mode. +This number is always interpreted in octal; you do not have to add a +leading @samp{0}, as you do in C. Mode @samp{0055} is the same as +mode @samp{55}. + +A numeric mode is usually shorter than the corresponding symbolic +mode, but it is limited in that normally it cannot take into account the +previous file mode bits; it can only set them absolutely. +(As discussed in the next section, the set-user-ID and set-group-ID +bits of directories are an exception to this general limitation.) + +The permissions granted to the user, +to other users in the file's group, +and to other users not in the file's group each require three +bits, which are represented as one octal digit. The three special +mode bits also require one bit each, and they are as a group +represented as another octal digit. Here is how the bits are arranged, +starting with the lowest valued bit: + +@example +Value in Corresponding +Mode Mode Bit + + Other users not in the file's group: + 1 Execute/search + 2 Write + 4 Read + + Other users in the file's group: + 10 Execute/search + 20 Write + 40 Read + + The file's owner: + 100 Execute/search + 200 Write + 400 Read + + Special mode bits: +1000 Restricted deletion flag or sticky bit +2000 Set group ID on execution +4000 Set user ID on execution +@end example + +For example, numeric mode @samp{4755} corresponds to symbolic mode +@samp{u=rwxs,go=rx}, and numeric mode @samp{664} corresponds to symbolic mode +@samp{ug=rw,o=r}. Numeric mode @samp{0} corresponds to symbolic mode +@samp{a=}. + +@node Directory Setuid and Setgid +@section Directories and the Set-User-ID and Set-Group-ID Bits + +On most systems, if a directory's set-group-ID bit is set, newly +created subfiles inherit the same group as the directory, and newly +created subdirectories inherit the set-group-ID bit of the parent +directory. On a few systems, a directory's set-user-ID bit has a +similar effect on the ownership of new subfiles and the set-user-ID +bits of new subdirectories. These mechanisms let users share files +more easily, by lessening the need to use @command{chmod} or +@command{chown} to share new files. + +These convenience mechanisms rely on the set-user-ID and set-group-ID +bits of directories. If commands like @command{chmod} and +@command{mkdir} routinely cleared these bits on directories, the +mechanisms would be less convenient and it would be harder to share +files. Therefore, a command like @command{chmod} does not affect the +set-user-ID or set-group-ID bits of a directory unless the user +specifically mentions them in a symbolic mode, or sets them in +a numeric mode. For example, on systems that support +set-group-ID inheritance: + +@example +# These commands leave the set-user-ID and +# set-group-ID bits of the subdirectories alone, +# so that they retain their default values. +mkdir A B C +chmod 755 A +chmod 0755 B +chmod u=rwx,go=rx C +mkdir -m 755 D +mkdir -m 0755 E +mkdir -m u=rwx,go=rx F +@end example + +If you want to try to set these bits, you must mention them +explicitly in the symbolic or numeric modes, e.g.: + +@example +# These commands try to set the set-user-ID +# and set-group-ID bits of the subdirectories. +mkdir G H +chmod 6755 G +chmod u=rwx,go=rx,a+s H +mkdir -m 6755 I +mkdir -m u=rwx,go=rx,a+s J +@end example + +If you want to try to clear these bits, you must mention them +explicitly in a symbolic mode, e.g.: + +@example +# This command tries to clear the set-user-ID +# and set-group-ID bits of the directory D. +chmod a-s D +@end example + +This behavior is a @acronym{GNU} extension. Portable scripts should +not rely on requests to set or clear these bits on directories, as +@acronym{POSIX} allows implementations to ignore these requests. diff --git a/doc/stamp-vti b/doc/stamp-vti new file mode 100644 index 0000000..f556ae3 --- /dev/null +++ b/doc/stamp-vti @@ -0,0 +1,4 @@ +@set UPDATED 22 March 2007 +@set UPDATED-MONTH March 2007 +@set EDITION 6.9 +@set VERSION 6.9 diff --git a/doc/version.texi b/doc/version.texi new file mode 100644 index 0000000..f556ae3 --- /dev/null +++ b/doc/version.texi @@ -0,0 +1,4 @@ +@set UPDATED 22 March 2007 +@set UPDATED-MONTH March 2007 +@set EDITION 6.9 +@set VERSION 6.9 |