3 @setfilename coreutils.info
4 @settitle @sc{gnu} Coreutils
9 @include constants.texi
11 @c Define new indices.
15 @c Put everything in one index (arbitrarily chosen to be the concept index).
25 * Coreutils: (coreutils). Core GNU (file, text, shell) utilities.
26 * Common options: (coreutils)Common options. Common options.
27 * File permissions: (coreutils)File permissions. Access modes.
28 * Date input formats: (coreutils)Date input formats.
31 @c FIXME: the following need documentation
32 @c * [: (coreutils)[ invocation. File/string tests.
33 @c * pinky: (coreutils)pinky invocation. FIXME.
34 @c * uptime: (coreutils)uptime invocation. FIXME.
36 @dircategory Individual utilities
38 * arch: (coreutils)arch invocation. Print machine hardware name.
39 * base64: (coreutils)base64 invocation. Base64 encode/decode data.
40 * basename: (coreutils)basename invocation. Strip directory and suffix.
41 * cat: (coreutils)cat invocation. Concatenate and write files.
42 * chgrp: (coreutils)chgrp invocation. Change file groups.
43 * chmod: (coreutils)chmod invocation. Change file permissions.
44 * chown: (coreutils)chown invocation. Change file owners/groups.
45 * chroot: (coreutils)chroot invocation. Specify the root directory.
46 * cksum: (coreutils)cksum invocation. Print POSIX CRC checksum.
47 * comm: (coreutils)comm invocation. Compare sorted files by line.
48 * cp: (coreutils)cp invocation. Copy files.
49 * csplit: (coreutils)csplit invocation. Split by context.
50 * cut: (coreutils)cut invocation. Print selected parts of lines.
51 * date: (coreutils)date invocation. Print/set system date and time.
52 * dd: (coreutils)dd invocation. Copy and convert a file.
53 * df: (coreutils)df invocation. Report file system disk usage.
54 * dir: (coreutils)dir invocation. List directories briefly.
55 * dircolors: (coreutils)dircolors invocation. Color setup for ls.
56 * dirname: (coreutils)dirname invocation. Strip non-directory suffix.
57 * du: (coreutils)du invocation. Report on disk usage.
58 * echo: (coreutils)echo invocation. Print a line of text.
59 * env: (coreutils)env invocation. Modify the environment.
60 * expand: (coreutils)expand invocation. Convert tabs to spaces.
61 * expr: (coreutils)expr invocation. Evaluate expressions.
62 * factor: (coreutils)factor invocation. Print prime factors
63 * false: (coreutils)false invocation. Do nothing, unsuccessfully.
64 * fmt: (coreutils)fmt invocation. Reformat paragraph text.
65 * fold: (coreutils)fold invocation. Wrap long input lines.
66 * groups: (coreutils)groups invocation. Print group names a user is in.
67 * head: (coreutils)head invocation. Output the first part of files.
68 * hostid: (coreutils)hostid invocation. Print numeric host identifier.
69 * hostname: (coreutils)hostname invocation. Print or set system name.
70 * id: (coreutils)id invocation. Print user identity.
71 * install: (coreutils)install invocation. Copy and change attributes.
72 * join: (coreutils)join invocation. Join lines on a common field.
73 * kill: (coreutils)kill invocation. Send a signal to processes.
74 * link: (coreutils)link invocation. Make hard links between files.
75 * ln: (coreutils)ln invocation. Make links between files.
76 * logname: (coreutils)logname invocation. Print current login name.
77 * ls: (coreutils)ls invocation. List directory contents.
78 * md5sum: (coreutils)md5sum invocation. Print or check MD5 digests.
79 * mkdir: (coreutils)mkdir invocation. Create directories.
80 * mkfifo: (coreutils)mkfifo invocation. Create FIFOs (named pipes).
81 * mknod: (coreutils)mknod invocation. Create special files.
82 * mv: (coreutils)mv invocation. Rename files.
83 * nice: (coreutils)nice invocation. Modify niceness.
84 * nl: (coreutils)nl invocation. Number lines and write files.
85 * nohup: (coreutils)nohup invocation. Immunize to hangups.
86 * od: (coreutils)od invocation. Dump files in octal, etc.
87 * paste: (coreutils)paste invocation. Merge lines of files.
88 * pathchk: (coreutils)pathchk invocation. Check file name portability.
89 * pr: (coreutils)pr invocation. Paginate or columnate files.
90 * printenv: (coreutils)printenv invocation. Print environment variables.
91 * printf: (coreutils)printf invocation. Format and print data.
92 * ptx: (coreutils)ptx invocation. Produce permuted indexes.
93 * pwd: (coreutils)pwd invocation. Print working directory.
94 * readlink: (coreutils)readlink invocation. Print referent of a symlink.
95 * rm: (coreutils)rm invocation. Remove files.
96 * rmdir: (coreutils)rmdir invocation. Remove empty directories.
97 * seq: (coreutils)seq invocation. Print numeric sequences
98 * sha1sum: (coreutils)sha1sum invocation. Print or check SHA-1 digests.
99 * sha2: (coreutils)sha2 utilities. Print or check SHA-2 digests.
100 * shred: (coreutils)shred invocation. Remove files more securely.
101 * shuf: (coreutils)shuf invocation. Shuffling text files.
102 * sleep: (coreutils)sleep invocation. Delay for a specified time.
103 * sort: (coreutils)sort invocation. Sort text files.
104 * split: (coreutils)split invocation. Split into fixed-size pieces.
105 * stat: (coreutils)stat invocation. Report file(system) status.
106 * stty: (coreutils)stty invocation. Print/change terminal settings.
107 * su: (coreutils)su invocation. Modify user and group ID.
108 * sum: (coreutils)sum invocation. Print traditional checksum.
109 * sync: (coreutils)sync invocation. Synchronize memory and disk.
110 * tac: (coreutils)tac invocation. Reverse files.
111 * tail: (coreutils)tail invocation. Output the last part of files.
112 * tee: (coreutils)tee invocation. Redirect to multiple files.
113 * test: (coreutils)test invocation. File/string tests.
114 * touch: (coreutils)touch invocation. Change file timestamps.
115 * tr: (coreutils)tr invocation. Translate characters.
116 * true: (coreutils)true invocation. Do nothing, successfully.
117 * tsort: (coreutils)tsort invocation. Topological sort.
118 * tty: (coreutils)tty invocation. Print terminal name.
119 * uname: (coreutils)uname invocation. Print system information.
120 * unexpand: (coreutils)unexpand invocation. Convert spaces to tabs.
121 * uniq: (coreutils)uniq invocation. Uniquify files.
122 * unlink: (coreutils)unlink invocation. Removal via unlink(2).
123 * users: (coreutils)users invocation. Print current user names.
124 * vdir: (coreutils)vdir invocation. List directories verbosely.
125 * wc: (coreutils)wc invocation. Line, word, and byte counts.
126 * who: (coreutils)who invocation. Print who is logged in.
127 * whoami: (coreutils)whoami invocation. Print effective user ID.
128 * yes: (coreutils)yes invocation. Print a string indefinitely.
132 This manual documents version @value{VERSION} of the @sc{gnu} core
133 utilities, including the standard programs for text and file manipulation.
135 Copyright @copyright{} 1994-1996, 2000-2008 Free Software Foundation, Inc.
138 Permission is granted to copy, distribute and/or modify this document
139 under the terms of the GNU Free Documentation License, Version 1.2 or
140 any later version published by the Free Software Foundation; with no
141 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
142 Texts. A copy of the license is included in the section entitled ``GNU
143 Free Documentation License''.
148 @title @sc{gnu} @code{Coreutils}
149 @subtitle Core GNU utilities
150 @subtitle for version @value{VERSION}, @value{UPDATED}
151 @author David MacKenzie et al.
154 @vskip 0pt plus 1filll
166 @cindex core utilities
167 @cindex text utilities
168 @cindex shell utilities
169 @cindex file utilities
172 * Introduction:: Caveats, overview, and authors.
173 * Common options:: Common options.
174 * Output of entire files:: cat tac nl od
175 * Formatting file contents:: fmt pr fold
176 * Output of parts of files:: head tail split csplit
177 * Summarizing files:: wc sum cksum md5sum sha1sum sha2
178 * Operating on sorted files:: sort shuf uniq comm ptx tsort
179 * Operating on fields within a line:: cut paste join
180 * Operating on characters:: tr expand unexpand
181 * Directory listing:: ls dir vdir dircolors
182 * Basic operations:: cp dd install mv rm shred
183 * Special file types:: ln mkdir rmdir mkfifo mknod
184 * Changing file attributes:: chgrp chmod chown touch
185 * Disk usage:: df du stat sync
186 * Printing text:: echo printf yes
187 * Conditions:: false true test expr
189 * File name manipulation:: dirname basename pathchk
190 * Working context:: pwd stty printenv tty
191 * User information:: id logname whoami groups users who
192 * System context:: date uname hostname hostid
193 * Modified command invocation:: chroot env nice nohup su
194 * Process control:: kill
196 * Numeric operations:: factor seq
197 * File permissions:: Access modes.
198 * Date input formats:: Specifying date strings.
199 * Opening the software toolbox:: The software tools philosophy.
200 * GNU Free Documentation License:: Copying and sharing this manual.
201 * Concept index:: General index.
204 --- The Detailed Node Listing ---
208 * Exit status:: Indicating program success or failure.
209 * Backup options:: Backup options
210 * Block size:: Block size
211 * Disambiguating names and IDs:: chgrp and chown owner and group syntax
212 * Random sources:: Sources of random data
213 * Target directory:: Target directory
214 * Trailing slashes:: Trailing slashes
215 * Traversing symlinks:: Traversing symlinks to directories
216 * Treating / specially:: Treating / specially
217 * Standards conformance:: Standards conformance
219 Output of entire files
221 * cat invocation:: Concatenate and write files.
222 * tac invocation:: Concatenate and write files in reverse.
223 * nl invocation:: Number lines and write files.
224 * od invocation:: Write files in octal or other formats.
225 * base64 invocation:: Transform data into printable data.
227 Formatting file contents
229 * fmt invocation:: Reformat paragraph text.
230 * pr invocation:: Paginate or columnate files for printing.
231 * fold invocation:: Wrap input lines to fit in specified width.
233 Output of parts of files
235 * head invocation:: Output the first part of files.
236 * tail invocation:: Output the last part of files.
237 * split invocation:: Split a file into fixed-size pieces.
238 * csplit invocation:: Split a file into context-determined pieces.
242 * wc invocation:: Print newline, word, and byte counts.
243 * sum invocation:: Print checksum and block counts.
244 * cksum invocation:: Print CRC checksum and byte counts.
245 * md5sum invocation:: Print or check MD5 digests.
246 * sha1sum invocation:: Print or check SHA-1 digests.
247 * sha2 utilities:: Print or check SHA-2 digests.
249 Operating on sorted files
251 * sort invocation:: Sort text files.
252 * shuf invocation:: Shuffle text files.
253 * uniq invocation:: Uniquify files.
254 * comm invocation:: Compare two sorted files line by line.
255 * ptx invocation:: Produce a permuted index of file contents.
256 * tsort invocation:: Topological sort.
258 @command{ptx}: Produce permuted indexes
260 * General options in ptx:: Options which affect general program behavior.
261 * Charset selection in ptx:: Underlying character set considerations.
262 * Input processing in ptx:: Input fields, contexts, and keyword selection.
263 * Output formatting in ptx:: Types of output format, and sizing the fields.
264 * Compatibility in ptx:: The @acronym{GNU} extensions to @command{ptx}
266 Operating on fields within a line
268 * cut invocation:: Print selected parts of lines.
269 * paste invocation:: Merge lines of files.
270 * join invocation:: Join lines on a common field.
272 Operating on characters
274 * tr invocation:: Translate, squeeze, and/or delete characters.
275 * expand invocation:: Convert tabs to spaces.
276 * unexpand invocation:: Convert spaces to tabs.
278 @command{tr}: Translate, squeeze, and/or delete characters
280 * Character sets:: Specifying sets of characters.
281 * Translating:: Changing one set of characters to another.
282 * Squeezing:: Squeezing repeats and deleting.
286 * ls invocation:: List directory contents
287 * dir invocation:: Briefly list directory contents
288 * vdir invocation:: Verbosely list directory contents
289 * dircolors invocation:: Color setup for @command{ls}
291 @command{ls}: List directory contents
293 * Which files are listed:: Which files are listed
294 * What information is listed:: What information is listed
295 * Sorting the output:: Sorting the output
296 * More details about version sort:: More details about version sort
297 * General output formatting:: General output formatting
298 * Formatting the file names:: Formatting the file names
302 * cp invocation:: Copy files and directories
303 * dd invocation:: Convert and copy a file
304 * install invocation:: Copy files and set attributes
305 * mv invocation:: Move (rename) files
306 * rm invocation:: Remove files or directories
307 * shred invocation:: Remove files more securely
311 * link invocation:: Make a hard link via the link syscall
312 * ln invocation:: Make links between files
313 * mkdir invocation:: Make directories
314 * mkfifo invocation:: Make FIFOs (named pipes)
315 * mknod invocation:: Make block or character special files
316 * readlink invocation:: Print the referent of a symbolic link
317 * rmdir invocation:: Remove empty directories
318 * unlink invocation:: Remove files via unlink syscall
320 Changing file attributes
322 * chown invocation:: Change file owner and group
323 * chgrp invocation:: Change group ownership
324 * chmod invocation:: Change access permissions
325 * touch invocation:: Change file timestamps
329 * df invocation:: Report file system disk space usage
330 * du invocation:: Estimate file space usage
331 * stat invocation:: Report file or file system status
332 * sync invocation:: Synchronize data on disk with memory
336 * echo invocation:: Print a line of text
337 * printf invocation:: Format and print data
338 * yes invocation:: Print a string until interrupted
342 * false invocation:: Do nothing, unsuccessfully
343 * true invocation:: Do nothing, successfully
344 * test invocation:: Check file types and compare values
345 * expr invocation:: Evaluate expressions
347 @command{test}: Check file types and compare values
349 * File type tests:: File type tests
350 * Access permission tests:: Access permission tests
351 * File characteristic tests:: File characteristic tests
352 * String tests:: String tests
353 * Numeric tests:: Numeric tests
355 @command{expr}: Evaluate expression
357 * String expressions:: + : match substr index length
358 * Numeric expressions:: + - * / %
359 * Relations for expr:: | & < <= = == != >= >
360 * Examples of expr:: Examples of using @command{expr}
364 * tee invocation:: Redirect output to multiple files or processes
366 File name manipulation
368 * basename invocation:: Strip directory and suffix from a file name
369 * dirname invocation:: Strip non-directory suffix from a file name
370 * pathchk invocation:: Check file name portability
374 * pwd invocation:: Print working directory
375 * stty invocation:: Print or change terminal characteristics
376 * printenv invocation:: Print all or some environment variables
377 * tty invocation:: Print file name of terminal on standard input
379 @command{stty}: Print or change terminal characteristics
381 * Control:: Control settings
382 * Input:: Input settings
383 * Output:: Output settings
384 * Local:: Local settings
385 * Combination:: Combination settings
386 * Characters:: Special characters
387 * Special:: Special settings
391 * id invocation:: Print user identity
392 * logname invocation:: Print current login name
393 * whoami invocation:: Print effective user ID
394 * groups invocation:: Print group names a user is in
395 * users invocation:: Print login names of users currently logged in
396 * who invocation:: Print who is currently logged in
400 * arch invocation:: Print machine hardware name
401 * date invocation:: Print or set system date and time
402 * uname invocation:: Print system information
403 * hostname invocation:: Print or set system name
404 * hostid invocation:: Print numeric host identifier.
406 @command{date}: Print or set system date and time
408 * Time conversion specifiers:: %[HIklMNpPrRsSTXzZ]
409 * Date conversion specifiers:: %[aAbBcCdDeFgGhjmuUVwWxyY]
410 * Literal conversion specifiers:: %[%nt]
411 * Padding and other flags:: Pad with zeros, spaces, etc.
412 * Setting the time:: Changing the system clock.
413 * Options for date:: Instead of the current time.
414 * Date input formats:: Specifying date strings.
415 * Examples of date:: Examples.
417 Modified command invocation
419 * chroot invocation:: Run a command with a different root directory
420 * env invocation:: Run a command in a modified environment
421 * nice invocation:: Run a command with modified niceness
422 * nohup invocation:: Run a command immune to hangups
423 * su invocation:: Run a command with substitute user and group ID
427 * kill invocation:: Sending a signal to processes.
431 * sleep invocation:: Delay for a specified time
435 * factor invocation:: Print prime factors
436 * seq invocation:: Print numeric sequences
440 * Mode Structure:: Structure of file mode bits.
441 * Symbolic Modes:: Mnemonic representation of file mode bits.
442 * Numeric Modes:: File mode bits as octal numbers.
443 * Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories.
447 * General date syntax:: Common rules.
448 * Calendar date items:: 19 Dec 1994.
449 * Time of day items:: 9:20pm.
450 * Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
451 * Day of week items:: Monday and others.
452 * Relative items in date strings:: next tuesday, 2 years ago.
453 * Pure numbers in date strings:: 19931219, 1440.
454 * Seconds since the Epoch:: @@1078100502.
455 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
456 * Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
458 Opening the software toolbox
460 * Toolbox introduction:: Toolbox introduction
461 * I/O redirection:: I/O redirection
462 * The who command:: The @command{who} command
463 * The cut command:: The @command{cut} command
464 * The sort command:: The @command{sort} command
465 * The uniq command:: The @command{uniq} command
466 * Putting the tools together:: Putting the tools together
470 * GNU Free Documentation License:: Copying and sharing this manual.
477 @chapter Introduction
479 This manual is a work in progress: many sections make no attempt to explain
480 basic concepts in a way suitable for novices. Thus, if you are interested,
481 please get involved in improving this manual. The entire @sc{gnu} community
484 @cindex @acronym{POSIX}
485 The @sc{gnu} utilities documented here are mostly compatible with the
486 @acronym{POSIX} standard.
487 @cindex bugs, reporting
488 Please report bugs to @email{bug-coreutils@@gnu.org}. Remember
489 to include the version number, machine architecture, input files, and
490 any other information needed to reproduce the bug: your input, what you
491 expected, what you got, and why it is wrong. Diffs are welcome, but
492 please include a description of the problem as well, since this is
493 sometimes difficult to infer. @xref{Bugs, , , gcc, Using and Porting GNU CC}.
499 @cindex MacKenzie, D.
502 This manual was originally derived from the Unix man pages in the
503 distributions, which were written by David MacKenzie and updated by Jim
504 Meyering. What you are reading now is the authoritative documentation
505 for these utilities; the man pages are no longer being maintained. The
506 original @command{fmt} man page was written by Ross Paterson. Fran@,{c}ois
507 Pinard did the initial conversion to Texinfo format. Karl Berry did the
508 indexing, some reorganization, and editing of the results. Brian
509 Youmans of the Free Software Foundation office staff combined the
510 manuals for textutils, fileutils, and sh-utils to produce the present
511 omnibus manual. Richard Stallman contributed his usual invaluable
512 insights to the overall process.
515 @chapter Common options
519 @itemx @w{@kbd{--backup}[=@var{method}]}
522 @vindex VERSION_CONTROL
523 @cindex backups, making
524 @xref{Backup options}.
525 Make a backup of each file that would otherwise be overwritten or removed.
528 @macro optBackupSuffix
529 @item -S @var{suffix}
530 @itemx --suffix=@var{suffix}
533 Append @var{suffix} to each backup file made with @option{-b}.
534 @xref{Backup options}.
537 @macro optTargetDirectory
538 @item -t @var{directory}
539 @itemx @w{@kbd{--target-directory}=@var{directory}}
541 @opindex --target-directory
542 @cindex target directory
543 @cindex destination directory
544 Specify the destination @var{directory}.
545 @xref{Target directory}.
548 @macro optNoTargetDirectory
550 @itemx --no-target-directory
552 @opindex --no-target-directory
553 @cindex target directory
554 @cindex destination directory
555 Do not treat the last operand specially when it is a directory or a
556 symbolic link to a directory. @xref{Target directory}.
563 Append an SI-style abbreviation to each size, such as @samp{M} for
564 megabytes. Powers of 1000 are used, not 1024; @samp{M} stands for
565 1,000,000 bytes. This option is equivalent to
566 @option{--block-size=si}. Use the @option{-h} or
567 @option{--human-readable} option if
568 you prefer powers of 1024.
571 @macro optHumanReadable
573 @itemx --human-readable
575 @opindex --human-readable
576 @cindex human-readable output
577 Append a size letter to each size, such as @samp{M} for mebibytes.
578 Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes.
579 This option is equivalent to @option{--block-size=human-readable}.
580 Use the @option{--si} option if you prefer powers of 1000.
583 @macro optStripTrailingSlashes
584 @itemx @w{@kbd{--strip-trailing-slashes}}
585 @opindex --strip-trailing-slashes
586 @cindex stripping trailing slashes
587 Remove any trailing slashes from each @var{source} argument.
588 @xref{Trailing slashes}.
591 @cindex common options
593 Certain options are available in all of these programs. Rather than
594 writing identical descriptions for each of the programs, they are
595 described here. (In fact, every @sc{gnu} program accepts (or should accept)
598 @vindex POSIXLY_CORRECT
599 Normally options and operands can appear in any order, and programs act
600 as if all the options appear before any operands. For example,
601 @samp{sort -r passwd -t :} acts like @samp{sort -r -t : passwd}, since
602 @samp{:} is an option-argument of @option{-t}. However, if the
603 @env{POSIXLY_CORRECT} environment variable is set, options must appear
604 before operands, unless otherwise specified for a particular command.
606 A few programs can usefully have trailing operands with leading
607 @samp{-}. With such a program, options must precede operands even if
608 @env{POSIXLY_CORRECT} is not set, and this fact is noted in the
609 program description. For example, the @command{env} command's options
610 must appear before its operands, since in some cases the operands
611 specify a command that itself contains options.
613 Some of these programs recognize the @option{--help} and @option{--version}
614 options only when one of them is the sole command line argument.
621 Print a usage message listing all available options, then exit successfully.
625 @cindex version number, finding
626 Print the version number, then exit successfully.
630 @cindex option delimiter
631 Delimit the option list. Later arguments, if any, are treated as
632 operands even if they begin with @samp{-}. For example, @samp{sort --
633 -r} reads from the file named @file{-r}.
637 @cindex standard input
638 @cindex standard output
639 A single @samp{-} operand is not really an option, though it looks like one. It
640 stands for standard input, or for standard output if that is clear from
641 the context. For example, @samp{sort -} reads from standard input,
642 and is equivalent to plain @samp{sort}, and @samp{tee -} writes an
643 extra copy of its input to standard output. Unless otherwise
644 specified, @samp{-} can appear as any operand that requires a file
648 * Exit status:: Indicating program success or failure.
649 * Backup options:: -b -S, in some programs.
650 * Block size:: BLOCK_SIZE and --block-size, in some programs.
651 * Disambiguating names and IDs:: chgrp and chown owner and group syntax
652 * Random sources:: --random-source, in some programs.
653 * Target directory:: Specifying a target directory, in some programs.
654 * Trailing slashes:: --strip-trailing-slashes, in some programs.
655 * Traversing symlinks:: -H, -L, or -P, in some programs.
656 * Treating / specially:: --preserve-root and --no-preserve-root.
657 * Special built-in utilities:: @command{break}, @command{:}, @command{eval}, @dots{}
658 * Standards conformance:: Conformance to the @acronym{POSIX} standard.
666 An exit status of zero indicates success,
667 and a nonzero value indicates failure.
670 Nearly every command invocation yields an integral @dfn{exit status}
671 that can be used to change how other commands work.
672 For the vast majority of commands, an exit status of zero indicates
673 success. Failure is indicated by a nonzero value---typically
674 @samp{1}, though it may differ on unusual platforms as @acronym{POSIX}
675 requires only that it be nonzero.
677 However, some of the programs documented here do produce
678 other exit status values and a few associate different
679 meanings with the values @samp{0} and @samp{1}.
680 Here are some of the exceptions:
681 @command{chroot}, @command{env}, @command{expr},
682 @command{nice}, @command{nohup}, @command{printenv},
683 @command{sort}, @command{su}, @command{test}, @command{tty}.
687 @section Backup options
689 @cindex backup options
691 Some @sc{gnu} programs (at least @command{cp}, @command{install},
692 @command{ln}, and @command{mv}) optionally make backups of files
693 before writing new versions.
694 These options control the details of these backups. The options are also
695 briefly mentioned in the descriptions of the particular programs.
700 @itemx @w{@kbd{--backup}[=@var{method}]}
703 @vindex VERSION_CONTROL
704 @cindex backups, making
705 Make a backup of each file that would otherwise be overwritten or removed.
706 Without this option, the original versions are destroyed.
707 Use @var{method} to determine the type of backups to make.
708 When this option is used but @var{method} is not specified,
709 then the value of the @env{VERSION_CONTROL}
710 environment variable is used. And if @env{VERSION_CONTROL} is not set,
711 the default backup type is @samp{existing}.
713 Note that the short form of this option, @option{-b} does not accept any
714 argument. Using @option{-b} is equivalent to using @option{--backup=existing}.
716 @vindex version-control @r{Emacs variable}
717 This option corresponds to the Emacs variable @samp{version-control};
718 the values for @var{method} are the same as those used in Emacs.
719 This option also accepts more descriptive names.
720 The valid @var{method}s are (unique abbreviations are accepted):
725 @opindex none @r{backup method}
730 @opindex numbered @r{backup method}
731 Always make numbered backups.
735 @opindex existing @r{backup method}
736 Make numbered backups of files that already have them, simple backups
741 @opindex simple @r{backup method}
742 Always make simple backups. Please note @samp{never} is not to be
743 confused with @samp{none}.
747 @item -S @var{suffix}
748 @itemx --suffix=@var{suffix}
751 @cindex backup suffix
752 @vindex SIMPLE_BACKUP_SUFFIX
753 Append @var{suffix} to each backup file made with @option{-b}. If this
754 option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
755 environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
756 set, the default is @samp{~}, just as in Emacs.
765 Some @sc{gnu} programs (at least @command{df}, @command{du}, and
766 @command{ls}) display sizes in ``blocks''. You can adjust the block size
767 and method of display to make sizes easier to read. The block size
768 used for display is independent of any file system block size.
769 Fractional block counts are rounded up to the nearest integer.
771 @opindex --block-size=@var{size}
774 @vindex DF_BLOCK_SIZE
775 @vindex DU_BLOCK_SIZE
776 @vindex LS_BLOCK_SIZE
777 @vindex POSIXLY_CORRECT@r{, and block size}
779 The default block size is chosen by examining the following environment
780 variables in turn; the first one that is set determines the block size.
785 This specifies the default block size for the @command{df} command.
786 Similarly, @env{DU_BLOCK_SIZE} specifies the default for @command{du} and
787 @env{LS_BLOCK_SIZE} for @command{ls}.
790 This specifies the default block size for all three commands, if the
791 above command-specific environment variables are not set.
794 This specifies the default block size for all values that are normally
795 printed as blocks, if neither @env{BLOCK_SIZE} nor the above
796 command-specific environment variables are set. Unlike the other
797 environment variables, @env{BLOCKSIZE} does not affect values that are
798 normally printed as byte counts, e.g., the file sizes contained in
801 @item POSIXLY_CORRECT
802 If neither @env{@var{command}_BLOCK_SIZE}, nor @env{BLOCK_SIZE}, nor
803 @env{BLOCKSIZE} is set, but this variable is set, the block size
808 If none of the above environment variables are set, the block size
809 currently defaults to 1024 bytes in most contexts, but this number may
810 change in the future. For @command{ls} file sizes, the block size
813 @cindex human-readable output
816 A block size specification can be a positive integer specifying the number
817 of bytes per block, or it can be @code{human-readable} or @code{si} to
818 select a human-readable format. Integers may be followed by suffixes
819 that are upward compatible with the
820 @uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI prefixes}
821 for decimal multiples and with the
822 @uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2
823 prefixes for binary multiples}.
825 With human-readable formats, output sizes are followed by a size letter
826 such as @samp{M} for megabytes. @code{BLOCK_SIZE=human-readable} uses
827 powers of 1024; @samp{M} stands for 1,048,576 bytes.
828 @code{BLOCK_SIZE=si} is similar, but uses powers of 1000 and appends
829 @samp{B}; @samp{MB} stands for 1,000,000 bytes.
832 A block size specification preceded by @samp{'} causes output sizes to
833 be displayed with thousands separators. The @env{LC_NUMERIC} locale
834 specifies the thousands separator and grouping. For example, in an
835 American English locale, @samp{--block-size="'1kB"} would cause a size
836 of 1234000 bytes to be displayed as @samp{1,234}. In the default C
837 locale, there is no thousands separator so a leading @samp{'} has no
840 An integer block size can be followed by a suffix to specify a
841 multiple of that size. A bare size letter,
842 or one followed by @samp{iB}, specifies
843 a multiple using powers of 1024. A size letter followed by @samp{B}
844 specifies powers of 1000 instead. For example, @samp{1M} and
845 @samp{1MiB} are equivalent to @samp{1048576}, whereas @samp{1MB} is
846 equivalent to @samp{1000000}.
848 A plain suffix without a preceding integer acts as if @samp{1} were
849 prepended, except that it causes a size indication to be appended to
850 the output. For example, @samp{--block-size="kB"} displays 3000 as
853 The following suffixes are defined. Large sizes like @code{1Y}
854 may be rejected by your computer due to limitations of its arithmetic.
858 @cindex kilobyte, definition of
859 kilobyte: @math{10^3 = 1000}.
863 @cindex kibibyte, definition of
864 kibibyte: @math{2^{10} = 1024}. @samp{K} is special: the SI prefix is
865 @samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and
866 @acronym{POSIX} use @samp{k} to mean @samp{KiB}.
868 @cindex megabyte, definition of
869 megabyte: @math{10^6 = 1,000,000}.
872 @cindex mebibyte, definition of
873 mebibyte: @math{2^{20} = 1,048,576}.
875 @cindex gigabyte, definition of
876 gigabyte: @math{10^9 = 1,000,000,000}.
879 @cindex gibibyte, definition of
880 gibibyte: @math{2^{30} = 1,073,741,824}.
882 @cindex terabyte, definition of
883 terabyte: @math{10^{12} = 1,000,000,000,000}.
886 @cindex tebibyte, definition of
887 tebibyte: @math{2^{40} = 1,099,511,627,776}.
889 @cindex petabyte, definition of
890 petabyte: @math{10^{15} = 1,000,000,000,000,000}.
893 @cindex pebibyte, definition of
894 pebibyte: @math{2^{50} = 1,125,899,906,842,624}.
896 @cindex exabyte, definition of
897 exabyte: @math{10^{18} = 1,000,000,000,000,000,000}.
900 @cindex exbibyte, definition of
901 exbibyte: @math{2^{60} = 1,152,921,504,606,846,976}.
903 @cindex zettabyte, definition of
904 zettabyte: @math{10^{21} = 1,000,000,000,000,000,000,000}
907 @math{2^{70} = 1,180,591,620,717,411,303,424}.
908 (@samp{Zi} is a @acronym{GNU} extension to IEC 60027-2.)
910 @cindex yottabyte, definition of
911 yottabyte: @math{10^{24} = 1,000,000,000,000,000,000,000,000}.
914 @math{2^{80} = 1,208,925,819,614,629,174,706,176}.
915 (@samp{Yi} is a @acronym{GNU} extension to IEC 60027-2.)
920 @opindex --block-size
921 @opindex --human-readable
924 Block size defaults can be overridden by an explicit
925 @option{--block-size=@var{size}} option. The @option{-k}
926 option is equivalent to @option{--block-size=1K}, which
927 is the default unless the @env{POSIXLY_CORRECT} environment variable is
928 set. The @option{-h} or @option{--human-readable} option is equivalent to
929 @option{--block-size=human-readable}. The @option{--si} option is
930 equivalent to @option{--block-size=si}.
932 @node Disambiguating names and IDs
933 @section chown and chgrp: Disambiguating user names and IDs
934 @cindex user names, disambiguating
935 @cindex user IDs, disambiguating
936 @cindex group names, disambiguating
937 @cindex group IDs, disambiguating
938 @cindex disambiguating group names and IDs
940 Since the @var{owner} and @var{group} arguments to @command{chown} and
941 @command{chgrp} may be specified as names or numeric IDs, there is an
943 What if a user or group @emph{name} is a string of digits?
944 @footnote{Using a number as a user name is common in some environments.}
945 Should the command interpret it as a user name or as an ID?
946 @acronym{POSIX} requires that @command{chown} and @command{chgrp}
947 first attempt to resolve the specified string as a name, and
948 only once that fails, then try to interpret it as an ID.
949 This is troublesome when you want to specify a numeric ID, say 42,
950 and it must work even in a pathological situation where
951 @samp{42} is a user name that maps to some other user ID, say 1000.
952 Simply invoking @code{chown 42 F}, will set @file{F}s owner ID to
953 1000---not what you intended.
955 GNU @command{chown} and @command{chgrp} provide a way to work around this,
956 that at the same time may result in a significant performance improvement
957 by eliminating a database look-up.
958 Simply precede each numeric user ID and/or group ID with a @samp{+},
959 in order to force its interpretation as an integer:
963 chgrp +$numeric_group_id another-file
967 GNU @command{chown} and @command{chgrp}
968 skip the name look-up process for each @samp{+}-prefixed string,
969 because a string containing @samp{+} is never a valid user or group name.
970 This syntax is accepted on most common Unix systems, but not on Solaris 10.
973 @section Sources of random data
975 @cindex random sources
977 The @command{shuf}, @command{shred}, and @command{sort} commands
978 sometimes need random data to do their work. For example, @samp{sort
979 -R} must choose a hash function at random, and it needs random data to
982 Normally these commands use the device file @file{/dev/urandom} as the
983 source of random data. Typically, this device gathers environmental
984 noise from device drivers and other sources into an entropy pool, and
985 uses the pool to generate random bits. If the pool is short of data,
986 the device reuses the internal pool to produce more bits, using a
987 cryptographically secure pseudorandom number generator.
989 @file{/dev/urandom} suffices for most practical uses, but applications
990 requiring high-value or long-term protection of private data may
991 require an alternate data source like @file{/dev/random} or
992 @file{/dev/arandom}. The set of available sources depends on your
995 To use such a source, specify the @option{--random-source=@var{file}}
996 option, e.g., @samp{shuf --random-source=/dev/random}. The contents
997 of @var{file} should be as random as possible. An error is reported
998 if @var{file} does not contain enough bytes to randomize the input
1001 To reproduce the results of an earlier invocation of a command, you
1002 can save some random data into a file and then use that file as the
1003 random source in earlier and later invocations of the command.
1005 Some old-fashioned or stripped-down operating systems lack support for
1006 @command{/dev/urandom}. On these systems commands like @command{shuf}
1007 by default fall back on an internal pseudorandom generator initialized
1008 by a small amount of entropy.
1010 @node Target directory
1011 @section Target directory
1013 @cindex target directory
1015 The @command{cp}, @command{install}, @command{ln}, and @command{mv}
1016 commands normally treat the last operand specially when it is a
1017 directory or a symbolic link to a directory. For example, @samp{cp
1018 source dest} is equivalent to @samp{cp source dest/source} if
1019 @file{dest} is a directory. Sometimes this behavior is not exactly
1020 what is wanted, so these commands support the following options to
1021 allow more fine-grained control:
1026 @itemx --no-target-directory
1027 @opindex --no-target-directory
1028 @cindex target directory
1029 @cindex destination directory
1030 Do not treat the last operand specially when it is a directory or a
1031 symbolic link to a directory. This can help avoid race conditions in
1032 programs that operate in a shared area. For example, when the command
1033 @samp{mv /tmp/source /tmp/dest} succeeds, there is no guarantee that
1034 @file{/tmp/source} was renamed to @file{/tmp/dest}: it could have been
1035 renamed to @file{/tmp/dest/source} instead, if some other process
1036 created @file{/tmp/dest} as a directory. However, if @file{mv
1037 -T /tmp/source /tmp/dest} succeeds, there is no
1038 question that @file{/tmp/source} was renamed to @file{/tmp/dest}.
1040 In the opposite situation, where you want the last operand to be
1041 treated as a directory and want a diagnostic otherwise, you can use
1042 the @option{--target-directory} (@option{-t}) option.
1044 @item -t @var{directory}
1045 @itemx @w{@kbd{--target-directory}=@var{directory}}
1046 @opindex --target-directory
1047 @cindex target directory
1048 @cindex destination directory
1049 Use @var{directory} as the directory component of each destination
1052 The interface for most programs is that after processing options and a
1053 finite (possibly zero) number of fixed-position arguments, the remaining
1054 argument list is either expected to be empty, or is a list of items
1055 (usually files) that will all be handled identically. The @command{xargs}
1056 program is designed to work well with this convention.
1058 The commands in the @command{mv}-family are unusual in that they take
1059 a variable number of arguments with a special case at the @emph{end}
1060 (namely, the target directory). This makes it nontrivial to perform some
1061 operations, e.g., ``move all files from here to ../d/'', because
1062 @code{mv * ../d/} might exhaust the argument space, and @code{ls | xargs ...}
1063 doesn't have a clean way to specify an extra final argument for each
1064 invocation of the subject command. (It can be done by going through a
1065 shell command, but that requires more human labor and brain power than
1068 The @w{@kbd{--target-directory}} (@option{-t}) option allows the @command{cp},
1069 @command{install}, @command{ln}, and @command{mv} programs to be used
1070 conveniently with @command{xargs}. For example, you can move the files
1071 from the current directory to a sibling directory, @code{d} like this:
1074 ls | xargs mv -t ../d --
1077 However, this doesn't move files whose names begin with @samp{.}.
1078 If you use the @sc{gnu} @command{find} program, you can move those
1079 files too, with this command:
1082 find . -mindepth 1 -maxdepth 1 \
1086 But both of the above approaches fail if there are no files in the
1087 current directory, or if any file has a name containing a blank or
1088 some other special characters.
1089 The following example removes those limitations and requires both
1090 @sc{gnu} @command{find} and @sc{gnu} @command{xargs}:
1093 find . -mindepth 1 -maxdepth 1 -print0 \
1094 | xargs --null --no-run-if-empty \
1101 The @option{--target-directory} (@option{-t}) and
1102 @option{--no-target-directory} (@option{-T})
1103 options cannot be combined.
1105 @node Trailing slashes
1106 @section Trailing slashes
1108 @cindex trailing slashes
1110 Some @sc{gnu} programs (at least @command{cp} and @command{mv}) allow you to
1111 remove any trailing slashes from each @var{source} argument before
1112 operating on it. The @w{@kbd{--strip-trailing-slashes}} option enables
1115 This is useful when a @var{source} argument may have a trailing slash and
1116 @c FIXME: mv's behavior in this case is system-dependent
1117 specify a symbolic link to a directory. This scenario is in fact rather
1118 common because some shells can automatically append a trailing slash when
1119 performing file name completion on such symbolic links. Without this
1120 option, @command{mv}, for example, (via the system's rename function) must
1121 interpret a trailing slash as a request to dereference the symbolic link
1122 and so must rename the indirectly referenced @emph{directory} and not
1123 the symbolic link. Although it may seem surprising that such behavior
1124 be the default, it is required by @acronym{POSIX} and is consistent with
1125 other parts of that standard.
1127 @node Traversing symlinks
1128 @section Traversing symlinks
1130 @cindex symbolic link to directory, controlling traversal of
1132 The following options modify how @command{chown} and @command{chgrp}
1133 @c FIXME: note that `du' has these options, too, but they have slightly
1134 @c different meaning.
1135 traverse a hierarchy when the @option{--recursive} (@option{-R})
1136 option is also specified.
1137 If more than one of the following options is specified, only the final
1139 These options specify whether processing a symbolic link to a directory
1140 entails operating on just the symbolic link or on all files in the
1141 hierarchy rooted at that directory.
1143 These options are independent of @option{--dereference} and
1144 @option{--no-dereference} (@option{-h}), which control whether to modify
1145 a symlink or its referent.
1152 @cindex symbolic link to directory, traverse each that is specified on the command line
1153 If @option{--recursive} (@option{-R}) is specified and
1154 a command line argument is a symbolic link to a directory, traverse it.
1161 @cindex symbolic link to directory, traverse each that is encountered
1162 In a recursive traversal, traverse every symbolic link to a directory
1163 that is encountered.
1170 @cindex symbolic link to directory, never traverse
1171 Do not traverse any symbolic links.
1172 This is the default if none of @option{-H}, @option{-L},
1173 or @option{-P} is specified.
1180 @node Treating / specially
1181 @section Treating @file{/} specially
1183 Certain commands can operate destructively on entire hierarchies.
1184 For example, if a user with appropriate privileges mistakenly runs
1185 @samp{rm -rf / tmp/junk}, that may remove
1186 all files on the entire system. Since there are so few
1187 legitimate uses for such a command,
1188 @sc{gnu} @command{rm} normally declines to operate on any directory
1189 that resolves to @file{/}. If you really want to try to remove all
1190 the files on your system, you can use the @option{--no-preserve-root}
1191 option, but the default behavior, specified by the
1192 @option{--preserve-option}, is safer for most purposes.
1194 The commands @command{chgrp}, @command{chmod} and @command{chown}
1195 can also operate destructively on entire hierarchies, so they too
1196 support these options. Although, unlike @command{rm}, they don't
1197 actually unlink files, these commands are arguably more dangerous
1198 when operating recursively on @file{/}, since they often work much
1199 more quickly, and hence damage more files before an alert user can
1200 interrupt them. Tradition and @acronym{POSIX} require these commands
1201 to operate recursively on @file{/}, so they default to
1202 @option{--no-preserve-root}, but using the @option{--preserve-root}
1203 option makes them safer for most purposes. For convenience you can
1204 specify @option{--preserve-root} in an alias or in a shell function.
1206 Note that the @option{--preserve-root} option also ensures
1207 that @command{chgrp} and @command{chown} do not modify @file{/}
1208 even when dereferencing a symlink pointing to @file{/}.
1210 @node Special built-in utilities
1211 @section Special built-in utilities
1213 Some programs like @command{nice} can invoke other programs; for
1214 example, the command @samp{nice cat file} invokes the program
1215 @command{cat} by executing the command @samp{cat file}. However,
1216 @dfn{special built-in utilities} like @command{exit} cannot be invoked
1217 this way. For example, the command @samp{nice exit} does not have a
1218 well-defined behavior: it may generate an error message instead of
1221 Here is a list of the special built-in utilities that are standardized
1222 by @acronym{POSIX} 1003.1-2004.
1225 @t{.@: : break continue eval exec exit export readonly
1226 return set shift times trap unset}
1229 For example, because @samp{.}, @samp{:}, and @samp{exec} are special,
1230 the commands @samp{nice . foo.sh}, @samp{nice :}, and @samp{nice exec
1231 pwd} do not work as you might expect.
1233 Many shells extend this list. For example, Bash has several extra
1234 special built-in utilities like @command{history}, and
1235 @command{suspend}, and with Bash the command @samp{nice suspend}
1236 generates an error message instead of suspending.
1238 @node Standards conformance
1239 @section Standards conformance
1241 @vindex POSIXLY_CORRECT
1242 In a few cases, the @sc{gnu} utilities' default behavior is
1243 incompatible with the @acronym{POSIX} standard. To suppress these
1244 incompatibilities, define the @env{POSIXLY_CORRECT} environment
1245 variable. Unless you are checking for @acronym{POSIX} conformance, you
1246 probably do not need to define @env{POSIXLY_CORRECT}.
1248 Newer versions of @acronym{POSIX} are occasionally incompatible with older
1249 versions. For example, older versions of @acronym{POSIX} required the
1250 command @samp{sort +1} to sort based on the second and succeeding
1251 fields in each input line, but starting with @acronym{POSIX} 1003.1-2001
1252 the same command is required to sort the file named @file{+1}, and you
1253 must instead use the command @samp{sort -k 2} to get the field-based
1256 @vindex _POSIX2_VERSION
1257 The @sc{gnu} utilities normally conform to the version of @acronym{POSIX}
1258 that is standard for your system. To cause them to conform to a
1259 different version of @acronym{POSIX}, define the @env{_POSIX2_VERSION}
1260 environment variable to a value of the form @var{yyyymm} specifying
1261 the year and month the standard was adopted. Two values are currently
1262 supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
1263 @acronym{POSIX} 1003.2-1992, and @samp{200112} stands for @acronym{POSIX}
1264 1003.1-2001. For example, if you have a newer system but are running software
1265 that assumes an older version of @acronym{POSIX} and uses @samp{sort +1}
1266 or @samp{tail +10}, you can work around any compatibility problems by setting
1267 @samp{_POSIX2_VERSION=199209} in your environment.
1269 @node Output of entire files
1270 @chapter Output of entire files
1272 @cindex output of entire files
1273 @cindex entire files, output of
1275 These commands read and write entire files, possibly transforming them
1279 * cat invocation:: Concatenate and write files.
1280 * tac invocation:: Concatenate and write files in reverse.
1281 * nl invocation:: Number lines and write files.
1282 * od invocation:: Write files in octal or other formats.
1283 * base64 invocation:: Transform data into printable data.
1286 @node cat invocation
1287 @section @command{cat}: Concatenate and write files
1290 @cindex concatenate and write files
1291 @cindex copying files
1293 @command{cat} copies each @var{file} (@samp{-} means standard input), or
1294 standard input if none are given, to standard output. Synopsis:
1297 cat [@var{option}] [@var{file}]@dots{}
1300 The program accepts the following options. Also see @ref{Common options}.
1308 Equivalent to @option{-vET}.
1311 @itemx --number-nonblank
1313 @opindex --number-nonblank
1314 Number all nonempty output lines, starting with 1.
1318 Equivalent to @option{-vE}.
1323 @opindex --show-ends
1324 Display a @samp{$} after the end of each line.
1330 Number all output lines, starting with 1.
1333 @itemx --squeeze-blank
1335 @opindex --squeeze-blank
1336 @cindex squeezing empty lines
1337 Suppress repeated adjacent empty lines; output just one empty line
1342 Equivalent to @option{-vT}.
1347 @opindex --show-tabs
1348 Display TAB characters as @samp{^I}.
1352 Ignored; for @acronym{POSIX} compatibility.
1355 @itemx --show-nonprinting
1357 @opindex --show-nonprinting
1358 Display control characters except for LFD and TAB using
1359 @samp{^} notation and precede characters that have the high bit set with
1364 On systems like MS-DOS that distinguish between text and binary files,
1365 @command{cat} normally reads and writes in binary mode. However,
1366 @command{cat} reads in text mode if one of the options
1367 @option{-bensAE} is used or if @command{cat} is reading from standard
1368 input and standard input is a terminal. Similarly, @command{cat}
1369 writes in text mode if one of the options @option{-bensAE} is used or
1370 if standard output is a terminal.
1377 # Output f's contents, then standard input, then g's contents.
1380 # Copy standard input to standard output.
1385 @node tac invocation
1386 @section @command{tac}: Concatenate and write files in reverse
1389 @cindex reversing files
1391 @command{tac} copies each @var{file} (@samp{-} means standard input), or
1392 standard input if none are given, to standard output, reversing the
1393 records (lines by default) in each separately. Synopsis:
1396 tac [@var{option}]@dots{} [@var{file}]@dots{}
1399 @dfn{Records} are separated by instances of a string (newline by
1400 default). By default, this separator string is attached to the end of
1401 the record that it follows in the file.
1403 The program accepts the following options. Also see @ref{Common options}.
1411 The separator is attached to the beginning of the record that it
1412 precedes in the file.
1418 Treat the separator string as a regular expression. Users of @command{tac}
1419 on MS-DOS/MS-Windows should note that, since @command{tac} reads files in
1420 binary mode, each line of a text file might end with a CR/LF pair
1421 instead of the Unix-style LF.
1423 @item -s @var{separator}
1424 @itemx --separator=@var{separator}
1426 @opindex --separator
1427 Use @var{separator} as the record separator, instead of newline.
1435 @section @command{nl}: Number lines and write files
1438 @cindex numbering lines
1439 @cindex line numbering
1441 @command{nl} writes each @var{file} (@samp{-} means standard input), or
1442 standard input if none are given, to standard output, with line numbers
1443 added to some or all of the lines. Synopsis:
1446 nl [@var{option}]@dots{} [@var{file}]@dots{}
1449 @cindex logical pages, numbering on
1450 @command{nl} decomposes its input into (logical) pages; by default, the
1451 line number is reset to 1 at the top of each logical page. @command{nl}
1452 treats all of the input files as a single document; it does not reset
1453 line numbers or logical pages between files.
1455 @cindex headers, numbering
1456 @cindex body, numbering
1457 @cindex footers, numbering
1458 A logical page consists of three sections: header, body, and footer.
1459 Any of the sections can be empty. Each can be numbered in a different
1460 style from the others.
1462 The beginnings of the sections of logical pages are indicated in the
1463 input file by a line containing exactly one of these delimiter strings:
1474 The two characters from which these strings are made can be changed from
1475 @samp{\} and @samp{:} via options (see below), but the pattern and
1476 length of each string cannot be changed.
1478 A section delimiter is replaced by an empty line on output. Any text
1479 that comes before the first section delimiter string in the input file
1480 is considered to be part of a body section, so @command{nl} treats a
1481 file that contains no section delimiters as a single body section.
1483 The program accepts the following options. Also see @ref{Common options}.
1487 @item -b @var{style}
1488 @itemx --body-numbering=@var{style}
1490 @opindex --body-numbering
1491 Select the numbering style for lines in the body section of each
1492 logical page. When a line is not numbered, the current line number
1493 is not incremented, but the line number separator character is still
1494 prepended to the line. The styles are:
1500 number only nonempty lines (default for body),
1502 do not number lines (default for header and footer),
1504 number only lines that contain a match for the basic regular
1505 expression @var{bre}.
1506 @xref{Regular Expressions, , Regular Expressions, grep, The GNU Grep Manual}.
1510 @itemx --section-delimiter=@var{cd}
1512 @opindex --section-delimiter
1513 @cindex section delimiters of pages
1514 Set the section delimiter characters to @var{cd}; default is
1515 @samp{\:}. If only @var{c} is given, the second remains @samp{:}.
1516 (Remember to protect @samp{\} or other metacharacters from shell
1517 expansion with quotes or extra backslashes.)
1519 @item -f @var{style}
1520 @itemx --footer-numbering=@var{style}
1522 @opindex --footer-numbering
1523 Analogous to @option{--body-numbering}.
1525 @item -h @var{style}
1526 @itemx --header-numbering=@var{style}
1528 @opindex --header-numbering
1529 Analogous to @option{--body-numbering}.
1531 @item -i @var{number}
1532 @itemx --page-increment=@var{number}
1534 @opindex --page-increment
1535 Increment line numbers by @var{number} (default 1).
1537 @item -l @var{number}
1538 @itemx --join-blank-lines=@var{number}
1540 @opindex --join-blank-lines
1541 @cindex empty lines, numbering
1542 @cindex blank lines, numbering
1543 Consider @var{number} (default 1) consecutive empty lines to be one
1544 logical line for numbering, and only number the last one. Where fewer
1545 than @var{number} consecutive empty lines occur, do not number them.
1546 An empty line is one that contains no characters, not even spaces
1549 @item -n @var{format}
1550 @itemx --number-format=@var{format}
1552 @opindex --number-format
1553 Select the line numbering format (default is @code{rn}):
1557 @opindex ln @r{format for @command{nl}}
1558 left justified, no leading zeros;
1560 @opindex rn @r{format for @command{nl}}
1561 right justified, no leading zeros;
1563 @opindex rz @r{format for @command{nl}}
1564 right justified, leading zeros.
1568 @itemx --no-renumber
1570 @opindex --no-renumber
1571 Do not reset the line number at the start of a logical page.
1573 @item -s @var{string}
1574 @itemx --number-separator=@var{string}
1576 @opindex --number-separator
1577 Separate the line number from the text line in the output with
1578 @var{string} (default is the TAB character).
1580 @item -v @var{number}
1581 @itemx --starting-line-number=@var{number}
1583 @opindex --starting-line-number
1584 Set the initial line number on each logical page to @var{number} (default 1).
1586 @item -w @var{number}
1587 @itemx --number-width=@var{number}
1589 @opindex --number-width
1590 Use @var{number} characters for line numbers (default 6).
1598 @section @command{od}: Write files in octal or other formats
1601 @cindex octal dump of files
1602 @cindex hex dump of files
1603 @cindex ASCII dump of files
1604 @cindex file contents, dumping unambiguously
1606 @command{od} writes an unambiguous representation of each @var{file}
1607 (@samp{-} means standard input), or standard input if none are given.
1611 od [@var{option}]@dots{} [@var{file}]@dots{}
1612 od [-abcdfilosx]@dots{} [@var{file}] [[+]@var{offset}[.][b]]
1613 od [@var{option}]@dots{} --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
1616 Each line of output consists of the offset in the input, followed by
1617 groups of data from the file. By default, @command{od} prints the offset in
1618 octal, and each group of file data is a C @code{short int}'s worth of input
1619 printed as a single octal number.
1621 If @var{offset} is given, it specifies how many input bytes to skip
1622 before formatting and writing. By default, it is interpreted as an
1623 octal number, but the optional trailing decimal point causes it to be
1624 interpreted as decimal. If no decimal is specified and the offset
1625 begins with @samp{0x} or @samp{0X} it is interpreted as a hexadecimal
1626 number. If there is a trailing @samp{b}, the number of bytes skipped
1627 will be @var{offset} multiplied by 512.
1629 If a command is of both the first and second forms, the second form is
1630 assumed if the last operand begins with @samp{+} or (if there are two
1631 operands) a digit. For example, in @samp{od foo 10} and @samp{od +10}
1632 the @samp{10} is an offset, whereas in @samp{od 10} the @samp{10} is a
1635 The program accepts the following options. Also see @ref{Common options}.
1639 @item -A @var{radix}
1640 @itemx --address-radix=@var{radix}
1642 @opindex --address-radix
1643 @cindex radix for file offsets
1644 @cindex file offset radix
1645 Select the base in which file offsets are printed. @var{radix} can
1646 be one of the following:
1656 none (do not print offsets).
1659 The default is octal.
1661 @item -j @var{bytes}
1662 @itemx --skip-bytes=@var{bytes}
1664 @opindex --skip-bytes
1665 Skip @var{bytes} input bytes before formatting and writing. If
1666 @var{bytes} begins with @samp{0x} or @samp{0X}, it is interpreted in
1667 hexadecimal; otherwise, if it begins with @samp{0}, in octal; otherwise,
1668 in decimal. Appending @samp{b} multiplies @var{bytes} by 512,
1669 @samp{kB} by 1000, @samp{K} by 1024,
1670 @samp{MB} by 1000*1000, @samp{M} by 1024*1024,
1671 @samp{GB} by 1000*1000*1000, @samp{G} by 1024*1024*1024,
1672 and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
1674 @item -N @var{bytes}
1675 @itemx --read-bytes=@var{bytes}
1677 @opindex --read-bytes
1678 Output at most @var{bytes} bytes of the input. Prefixes and suffixes on
1679 @code{bytes} are interpreted as for the @option{-j} option.
1681 @item -S @var{bytes}
1682 @itemx --strings[=@var{bytes}]
1685 @cindex string constants, outputting
1686 Instead of the normal output, output only @dfn{string constants}: at
1687 least @var{bytes} consecutive @acronym{ASCII} graphic characters,
1688 followed by a null (zero) byte.
1689 Prefixes and suffixes on @code{bytes} are interpreted as for the
1692 If @var{n} is omitted with @option{--strings}, the default is 3.
1695 @itemx --format=@var{type}
1698 Select the format in which to output the file data. @var{type} is a
1699 string of one or more of the below type indicator characters. If you
1700 include more than one type indicator character in a single @var{type}
1701 string, or use this option more than once, @command{od} writes one copy
1702 of each output line using each of the data types that you specified,
1703 in the order that you specified.
1705 Adding a trailing ``z'' to any type specification appends a display
1706 of the @acronym{ASCII} character representation of the printable characters
1707 to the output line generated by the type specification.
1711 named character, ignoring high-order bit
1713 @acronym{ASCII} character or backslash escape,
1726 The type @code{a} outputs things like @samp{sp} for space, @samp{nl} for
1727 newline, and @samp{nul} for a null (zero) byte. Only the least significant
1728 seven bits of each byte is used; the high-order bit is ignored.
1729 Type @code{c} outputs
1730 @samp{ }, @samp{\n}, and @code{\0}, respectively.
1733 Except for types @samp{a} and @samp{c}, you can specify the number
1734 of bytes to use in interpreting each number in the given data type
1735 by following the type indicator character with a decimal integer.
1736 Alternately, you can specify the size of one of the C compiler's
1737 built-in data types by following the type indicator character with
1738 one of the following characters. For integers (@samp{d}, @samp{o},
1739 @samp{u}, @samp{x}):
1752 For floating point (@code{f}):
1764 @itemx --output-duplicates
1766 @opindex --output-duplicates
1767 Output consecutive lines that are identical. By default, when two or
1768 more consecutive output lines would be identical, @command{od} outputs only
1769 the first line, and puts just an asterisk on the following line to
1770 indicate the elision.
1773 @itemx --width[=@var{n}]
1776 Dump @code{n} input bytes per output line. This must be a multiple of
1777 the least common multiple of the sizes associated with the specified
1780 If this option is not given at all, the default is 16. If @var{n} is
1781 omitted, the default is 32.
1785 The next several options are shorthands for format specifications.
1786 @sc{gnu} @command{od} accepts any combination of shorthands and format
1787 specification options. These options accumulate.
1793 Output as named characters. Equivalent to @samp{-t a}.
1797 Output as octal bytes. Equivalent to @samp{-t o1}.
1801 Output as @acronym{ASCII} characters or backslash escapes. Equivalent to
1806 Output as unsigned decimal two-byte units. Equivalent to @samp{-t u2}.
1810 Output as floats. Equivalent to @samp{-t fF}.
1814 Output as decimal ints. Equivalent to @samp{-t dI}.
1818 Output as decimal long ints. Equivalent to @samp{-t dL}.
1822 Output as octal two-byte units. Equivalent to @option{-t o2}.
1826 Output as decimal two-byte units. Equivalent to @option{-t d2}.
1830 Output as hexadecimal two-byte units. Equivalent to @samp{-t x2}.
1833 @opindex --traditional
1834 Recognize the non-option label argument that traditional @command{od}
1835 accepted. The following syntax:
1838 od --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
1842 can be used to specify at most one file and optional arguments
1843 specifying an offset and a pseudo-start address, @var{label}.
1844 The @var{label} argument is interpreted
1845 just like @var{offset}, but it specifies an initial pseudo-address. The
1846 pseudo-addresses are displayed in parentheses following any normal
1853 @node base64 invocation
1854 @section @command{base64}: Transform data into printable data.
1857 @cindex base64 encoding
1859 @command{base64} transforms data read from a file, or standard input,
1860 into (or from) base64 encoded form. The base64 encoded form uses
1861 printable @acronym{ASCII} characters to represent binary data, see
1862 @uref{ftp://ftp.rfc-editor.org/in-notes/rfc3548.txt, RFC 3548}.
1866 base64 [@var{option}]@dots{} [@var{file}]
1867 base64 --decode [@var{option}]@dots{} [@var{file}]
1870 The base64 encoding expands data to roughly 133% of the original.
1872 The program accepts the following options. Also see @ref{Common options}.
1877 @itemx --wrap=@var{COLS}
1881 @cindex column to wrap data after
1882 During encoding, wrap lines after @var{COLS} characters. This must be
1885 The default is to wrap after 76 characters. Use the value 0 to
1886 disable line wrapping altogether.
1892 @cindex Decode base64 data
1893 @cindex Base64 decoding
1894 Change the mode of operation, from the default of encoding data, to
1895 decoding data. Input is expected to be base64 encoded data, and the
1896 output will be the original data.
1899 @itemx --ignore-garbage
1901 @opindex --ignore-garbage
1902 @cindex Ignore garbage in base64 stream
1903 When decoding, newlines are always accepted.
1904 During decoding, ignore unrecognized bytes,
1905 to permit distorted data to be decoded.
1912 @node Formatting file contents
1913 @chapter Formatting file contents
1915 @cindex formatting file contents
1917 These commands reformat the contents of files.
1920 * fmt invocation:: Reformat paragraph text.
1921 * pr invocation:: Paginate or columnate files for printing.
1922 * fold invocation:: Wrap input lines to fit in specified width.
1926 @node fmt invocation
1927 @section @command{fmt}: Reformat paragraph text
1930 @cindex reformatting paragraph text
1931 @cindex paragraphs, reformatting
1932 @cindex text, reformatting
1934 @command{fmt} fills and joins lines to produce output lines of (at most)
1935 a given number of characters (75 by default). Synopsis:
1938 fmt [@var{option}]@dots{} [@var{file}]@dots{}
1941 @command{fmt} reads from the specified @var{file} arguments (or standard
1942 input if none are given), and writes to standard output.
1944 By default, blank lines, spaces between words, and indentation are
1945 preserved in the output; successive input lines with different
1946 indentation are not joined; tabs are expanded on input and introduced on
1949 @cindex line-breaking
1950 @cindex sentences and line-breaking
1951 @cindex Knuth, Donald E.
1952 @cindex Plass, Michael F.
1953 @command{fmt} prefers breaking lines at the end of a sentence, and tries to
1954 avoid line breaks after the first word of a sentence or before the last
1955 word of a sentence. A @dfn{sentence break} is defined as either the end
1956 of a paragraph or a word ending in any of @samp{.?!}, followed by two
1957 spaces or end of line, ignoring any intervening parentheses or quotes.
1958 Like @TeX{}, @command{fmt} reads entire ``paragraphs'' before choosing line
1959 breaks; the algorithm is a variant of that given by Donald E. Knuth
1960 and Michael F. Plass in ``Breaking Paragraphs Into Lines'',
1961 @cite{Software---Practice & Experience} @b{11}, 11 (November 1981),
1964 The program accepts the following options. Also see @ref{Common options}.
1969 @itemx --crown-margin
1971 @opindex --crown-margin
1972 @cindex crown margin
1973 @dfn{Crown margin} mode: preserve the indentation of the first two
1974 lines within a paragraph, and align the left margin of each subsequent
1975 line with that of the second line.
1978 @itemx --tagged-paragraph
1980 @opindex --tagged-paragraph
1981 @cindex tagged paragraphs
1982 @dfn{Tagged paragraph} mode: like crown margin mode, except that if
1983 indentation of the first line of a paragraph is the same as the
1984 indentation of the second, the first line is treated as a one-line
1990 @opindex --split-only
1991 Split lines only. Do not join short lines to form longer ones. This
1992 prevents sample lines of code, and other such ``formatted'' text from
1993 being unduly combined.
1996 @itemx --uniform-spacing
1998 @opindex --uniform-spacing
1999 Uniform spacing. Reduce spacing between words to one space, and spacing
2000 between sentences to two spaces.
2003 @itemx -w @var{width}
2004 @itemx --width=@var{width}
2005 @opindex -@var{width}
2008 Fill output lines up to @var{width} characters (default 75). @command{fmt}
2009 initially tries to make lines about 7% shorter than this, to give it
2010 room to balance line lengths.
2012 @item -p @var{prefix}
2013 @itemx --prefix=@var{prefix}
2014 Only lines beginning with @var{prefix} (possibly preceded by whitespace)
2015 are subject to formatting. The prefix and any preceding whitespace are
2016 stripped for the formatting and then re-attached to each formatted output
2017 line. One use is to format certain kinds of program comments, while
2018 leaving the code unchanged.
2026 @section @command{pr}: Paginate or columnate files for printing
2029 @cindex printing, preparing files for
2030 @cindex multicolumn output, generating
2031 @cindex merging files in parallel
2033 @command{pr} writes each @var{file} (@samp{-} means standard input), or
2034 standard input if none are given, to standard output, paginating and
2035 optionally outputting in multicolumn format; optionally merges all
2036 @var{file}s, printing all in parallel, one per column. Synopsis:
2039 pr [@var{option}]@dots{} [@var{file}]@dots{}
2043 By default, a 5-line header is printed at each page: two blank lines;
2044 a line with the date, the file name, and the page count; and two more
2045 blank lines. A footer of five blank lines is also printed.
2046 The default @var{page_length} is 66
2047 lines. The default number of text lines is therefore 56.
2048 The text line of the header takes the form
2049 @samp{@var{date} @var{string} @var{page}}, with spaces inserted around
2050 @var{string} so that the line takes up the full @var{page_width}. Here,
2051 @var{date} is the date (see the @option{-D} or @option{--date-format}
2052 option for details), @var{string} is the centered header string, and
2053 @var{page} identifies the page number. The @env{LC_MESSAGES} locale
2054 category affects the spelling of @var{page}; in the default C locale, it
2055 is @samp{Page @var{number}} where @var{number} is the decimal page
2058 Form feeds in the input cause page breaks in the output. Multiple form
2059 feeds produce empty pages.
2061 Columns are of equal width, separated by an optional string (default
2062 is @samp{space}). For multicolumn output, lines will always be truncated to
2063 @var{page_width} (default 72), unless you use the @option{-J} option.
2065 column output no line truncation occurs by default. Use @option{-W} option to
2066 truncate lines in that case.
2068 The following changes were made in version 1.22i and apply to later
2069 versions of @command{pr}:
2070 @c FIXME: this whole section here sounds very awkward to me. I
2071 @c made a few small changes, but really it all needs to be redone. - Brian
2072 @c OK, I fixed another sentence or two, but some of it I just don't understand.
2077 Some small @var{letter options} (@option{-s}, @option{-w}) have been
2078 redefined for better @acronym{POSIX} compliance. The output of some further
2079 cases has been adapted to other Unix systems. These changes are not
2080 compatible with earlier versions of the program.
2083 Some @var{new capital letter} options (@option{-J}, @option{-S}, @option{-W})
2084 have been introduced to turn off unexpected interferences of small letter
2085 options. The @option{-N} option and the second argument @var{last_page}
2086 of @samp{+FIRST_PAGE} offer more flexibility. The detailed handling of
2087 form feeds set in the input files requires the @option{-T} option.
2090 Capital letter options override small letter ones.
2093 Some of the option-arguments (compare @option{-s}, @option{-e},
2094 @option{-i}, @option{-n}) cannot be specified as separate arguments from the
2095 preceding option letter (already stated in the @acronym{POSIX} specification).
2098 The program accepts the following options. Also see @ref{Common options}.
2102 @item +@var{first_page}[:@var{last_page}]
2103 @itemx --pages=@var{first_page}[:@var{last_page}]
2104 @c The two following @opindex lines evoke warnings because they contain `:'
2105 @c The `info' spec does not permit that. If we use those lines, we end
2106 @c up with truncated index entries that don't work.
2107 @c @opindex +@var{first_page}[:@var{last_page}]
2108 @c @opindex --pages=@var{first_page}[:@var{last_page}]
2109 @opindex +@var{page_range}
2110 @opindex --pages=@var{page_range}
2111 Begin printing with page @var{first_page} and stop with @var{last_page}.
2112 Missing @samp{:@var{last_page}} implies end of file. While estimating
2113 the number of skipped pages each form feed in the input file results
2114 in a new page. Page counting with and without @samp{+@var{first_page}}
2115 is identical. By default, counting starts with the first page of input
2116 file (not first page printed). Line numbering may be altered by @option{-N}
2120 @itemx --columns=@var{column}
2121 @opindex -@var{column}
2123 @cindex down columns
2124 With each single @var{file}, produce @var{column} columns of output
2125 (default is 1) and print columns down, unless @option{-a} is used. The
2126 column width is automatically decreased as @var{column} increases; unless
2127 you use the @option{-W/-w} option to increase @var{page_width} as well.
2128 This option might well cause some lines to be truncated. The number of
2129 lines in the columns on each page are balanced. The options @option{-e}
2130 and @option{-i} are on for multiple text-column output. Together with
2131 @option{-J} option column alignment and line truncation is turned off.
2132 Lines of full length are joined in a free field format and @option{-S}
2133 option may set field separators. @option{-@var{column}} may not be used
2134 with @option{-m} option.
2140 @cindex across columns
2141 With each single @var{file}, print columns across rather than down. The
2142 @option{-@var{column}} option must be given with @var{column} greater than one.
2143 If a line is too long to fit in a column, it is truncated.
2146 @itemx --show-control-chars
2148 @opindex --show-control-chars
2149 Print control characters using hat notation (e.g., @samp{^G}); print
2150 other nonprinting characters in octal backslash notation. By default,
2151 nonprinting characters are not changed.
2154 @itemx --double-space
2156 @opindex --double-space
2157 @cindex double spacing
2158 Double space the output.
2160 @item -D @var{format}
2161 @itemx --date-format=@var{format}
2162 @cindex time formats
2163 @cindex formatting times
2164 Format header dates using @var{format}, using the same conventions as
2165 for the command @samp{date +@var{format}}; @xref{date invocation}.
2166 Except for directives, which start with
2167 @samp{%}, characters in @var{format} are printed unchanged. You can use
2168 this option to specify an arbitrary string in place of the header date,
2169 e.g., @option{--date-format="Monday morning"}.
2171 @vindex POSIXLY_CORRECT
2173 The default date format is @samp{%Y-%m-%d %H:%M} (for example,
2174 @samp{2001-12-04 23:59});
2175 but if the @env{POSIXLY_CORRECT} environment variable is set
2176 and the @env{LC_TIME} locale category specifies the @acronym{POSIX}
2177 locale, the default is @samp{%b %e %H:%M %Y} (for example,
2178 @samp{Dec@ @ 4 23:59 2001}.
2181 Time stamps are listed according to the time zone rules specified by
2182 the @env{TZ} environment variable, or by the system default rules if
2183 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
2184 with @env{TZ}, libc, The GNU C Library Reference Manual}.
2186 @item -e[@var{in-tabchar}[@var{in-tabwidth}]]
2187 @itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]]
2189 @opindex --expand-tabs
2191 Expand @var{tab}s to spaces on input. Optional argument @var{in-tabchar} is
2192 the input tab character (default is the TAB character). Second optional
2193 argument @var{in-tabwidth} is the input tab character's width (default
2201 @opindex --form-feed
2202 Use a form feed instead of newlines to separate output pages. This does
2203 not alter the default page length of 66 lines.
2205 @item -h @var{HEADER}
2206 @itemx --header=@var{HEADER}
2209 Replace the file name in the header with the centered string @var{header}.
2210 When using the shell, @var{header} should be quoted and should be
2211 separated from @option{-h} by a space.
2213 @item -i[@var{out-tabchar}[@var{out-tabwidth}]]
2214 @itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]]
2216 @opindex --output-tabs
2218 Replace spaces with @var{tab}s on output. Optional argument @var{out-tabchar}
2219 is the output tab character (default is the TAB character). Second optional
2220 argument @var{out-tabwidth} is the output tab character's width (default
2226 @opindex --join-lines
2227 Merge lines of full length. Used together with the column options
2228 @option{-@var{column}}, @option{-a -@var{column}} or @option{-m}. Turns off
2229 @option{-W/-w} line truncation;
2230 no column alignment used; may be used with
2231 @option{--sep-string[=@var{string}]}. @option{-J} has been introduced
2232 (together with @option{-W} and @option{--sep-string})
2233 to disentangle the old (@acronym{POSIX}-compliant) options @option{-w} and
2234 @option{-s} along with the three column options.
2237 @item -l @var{page_length}
2238 @itemx --length=@var{page_length}
2241 Set the page length to @var{page_length} (default 66) lines, including
2242 the lines of the header [and the footer]. If @var{page_length} is less
2243 than or equal to 10, the header and footer are omitted, as if the
2244 @option{-t} option had been given.
2250 Merge and print all @var{file}s in parallel, one in each column. If a
2251 line is too long to fit in a column, it is truncated, unless the @option{-J}
2252 option is used. @option{--sep-string[=@var{string}]} may be used.
2254 some @var{file}s (form feeds set) produce empty columns, still marked
2255 by @var{string}. The result is a continuous line numbering and column
2256 marking throughout the whole merged file. Completely empty merged pages
2257 show no separators or line numbers. The default header becomes
2258 @samp{@var{date} @var{page}} with spaces inserted in the middle; this
2259 may be used with the @option{-h} or @option{--header} option to fill up
2260 the middle blank part.
2262 @item -n[@var{number-separator}[@var{digits}]]
2263 @itemx --number-lines[=@var{number-separator}[@var{digits}]]
2265 @opindex --number-lines
2266 Provide @var{digits} digit line numbering (default for @var{digits} is
2267 5). With multicolumn output the number occupies the first @var{digits}
2268 column positions of each text column or only each line of @option{-m}
2269 output. With single column output the number precedes each line just as
2270 @option{-m} does. Default counting of the line numbers starts with the
2271 first line of the input file (not the first line printed, compare the
2272 @option{--page} option and @option{-N} option).
2273 Optional argument @var{number-separator} is the character appended to
2274 the line number to separate it from the text followed. The default
2275 separator is the TAB character. In a strict sense a TAB is always
2276 printed with single column output only. The @var{TAB}-width varies
2277 with the @var{TAB}-position, e.g., with the left @var{margin} specified
2278 by @option{-o} option. With multicolumn output priority is given to
2279 @samp{equal width of output columns} (a @acronym{POSIX} specification).
2280 The @var{TAB}-width is fixed to the value of the first column and does
2281 not change with different values of left @var{margin}. That means a
2282 fixed number of spaces is always printed in the place of the
2283 @var{number-separator tab}. The tabification depends upon the output
2286 @item -N @var{line_number}
2287 @itemx --first-line-number=@var{line_number}
2289 @opindex --first-line-number
2290 Start line counting with the number @var{line_number} at first line of
2291 first page printed (in most cases not the first line of the input file).
2293 @item -o @var{margin}
2294 @itemx --indent=@var{margin}
2297 @cindex indenting lines
2299 Indent each line with a margin @var{margin} spaces wide (default is zero).
2300 The total page width is the size of the margin plus the @var{page_width}
2301 set with the @option{-W/-w} option. A limited overflow may occur with
2302 numbered single column output (compare @option{-n} option).
2305 @itemx --no-file-warnings
2307 @opindex --no-file-warnings
2308 Do not print a warning message when an argument @var{file} cannot be
2309 opened. (The exit status will still be nonzero, however.)
2311 @item -s[@var{char}]
2312 @itemx --separator[=@var{char}]
2314 @opindex --separator
2315 Separate columns by a single character @var{char}. The default for
2316 @var{char} is the TAB character without @option{-w} and @samp{no
2317 character} with @option{-w}. Without @option{-s} the default separator
2318 @samp{space} is set. @option{-s[char]} turns off line truncation of all
2319 three column options (@option{-COLUMN}|@option{-a -COLUMN}|@option{-m}) unless
2320 @option{-w} is set. This is a @acronym{POSIX}-compliant formulation.
2323 @item -S@var{string}
2324 @itemx --sep-string[=@var{string}]
2326 @opindex --sep-string
2327 Use @var{string} to separate output columns. The @option{-S} option doesn't
2328 affect the @option{-W/-w} option, unlike the @option{-s} option which does. It
2329 does not affect line truncation or column alignment.
2330 Without @option{-S}, and with @option{-J}, @command{pr} uses the default output
2332 Without @option{-S} or @option{-J}, @command{pr} uses a @samp{space}
2333 (same as @option{-S"@w{ }"}). @option{--sep-string} with no
2334 @samp{=@var{string}} is equivalent to @option{--sep-string=""}.
2337 @itemx --omit-header
2339 @opindex --omit-header
2340 Do not print the usual header [and footer] on each page, and do not fill
2341 out the bottom of pages (with blank lines or a form feed). No page
2342 structure is produced, but form feeds set in the input files are retained.
2343 The predefined pagination is not changed. @option{-t} or @option{-T} may be
2344 useful together with other options; e.g.: @option{-t -e4}, expand TAB characters
2345 in the input file to 4 spaces but don't make any other changes. Use of
2346 @option{-t} overrides @option{-h}.
2349 @itemx --omit-pagination
2351 @opindex --omit-pagination
2352 Do not print header [and footer]. In addition eliminate all form feeds
2353 set in the input files.
2356 @itemx --show-nonprinting
2358 @opindex --show-nonprinting
2359 Print nonprinting characters in octal backslash notation.
2361 @item -w @var{page_width}
2362 @itemx --width=@var{page_width}
2365 Set page width to @var{page_width} characters for multiple text-column
2366 output only (default for @var{page_width} is 72). @option{-s[CHAR]} turns
2367 off the default page width and any line truncation and column alignment.
2368 Lines of full length are merged, regardless of the column options
2369 set. No @var{page_width} setting is possible with single column output.
2370 A @acronym{POSIX}-compliant formulation.
2372 @item -W @var{page_width}
2373 @itemx --page_width=@var{page_width}
2375 @opindex --page_width
2376 Set the page width to @var{page_width} characters. That's valid with and
2377 without a column option. Text lines are truncated, unless @option{-J}
2378 is used. Together with one of the three column options
2379 (@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}) column
2380 alignment is always used. The separator options @option{-S} or @option{-s}
2381 don't affect the @option{-W} option. Default is 72 characters. Without
2382 @option{-W @var{page_width}} and without any of the column options NO line
2383 truncation is used (defined to keep downward compatibility and to meet
2384 most frequent tasks). That's equivalent to @option{-W 72 -J}. The header
2385 line is never truncated.
2392 @node fold invocation
2393 @section @command{fold}: Wrap input lines to fit in specified width
2396 @cindex wrapping long input lines
2397 @cindex folding long input lines
2399 @command{fold} writes each @var{file} (@option{-} means standard input), or
2400 standard input if none are given, to standard output, breaking long
2404 fold [@var{option}]@dots{} [@var{file}]@dots{}
2407 By default, @command{fold} breaks lines wider than 80 columns. The output
2408 is split into as many lines as necessary.
2410 @cindex screen columns
2411 @command{fold} counts screen columns by default; thus, a tab may count more
2412 than one column, backspace decreases the column count, and carriage
2413 return sets the column to zero.
2415 The program accepts the following options. Also see @ref{Common options}.
2423 Count bytes rather than columns, so that tabs, backspaces, and carriage
2424 returns are each counted as taking up one column, just like other
2431 Break at word boundaries: the line is broken after the last blank before
2432 the maximum line length. If the line contains no such blanks, the line
2433 is broken at the maximum line length as usual.
2435 @item -w @var{width}
2436 @itemx --width=@var{width}
2439 Use a maximum line length of @var{width} columns instead of 80.
2441 For compatibility @command{fold} supports an obsolete option syntax
2442 @option{-@var{width}}. New scripts should use @option{-w @var{width}}
2450 @node Output of parts of files
2451 @chapter Output of parts of files
2453 @cindex output of parts of files
2454 @cindex parts of files, output of
2456 These commands output pieces of the input.
2459 * head invocation:: Output the first part of files.
2460 * tail invocation:: Output the last part of files.
2461 * split invocation:: Split a file into fixed-size pieces.
2462 * csplit invocation:: Split a file into context-determined pieces.
2465 @node head invocation
2466 @section @command{head}: Output the first part of files
2469 @cindex initial part of files, outputting
2470 @cindex first part of files, outputting
2472 @command{head} prints the first part (10 lines by default) of each
2473 @var{file}; it reads from standard input if no files are given or
2474 when given a @var{file} of @option{-}. Synopsis:
2477 head [@var{option}]@dots{} [@var{file}]@dots{}
2480 If more than one @var{file} is specified, @command{head} prints a
2481 one-line header consisting of:
2484 ==> @var{file name} <==
2488 before the output for each @var{file}.
2490 The program accepts the following options. Also see @ref{Common options}.
2495 @itemx --bytes=@var{n}
2498 Print the first @var{n} bytes, instead of initial lines.
2499 However, if @var{n} starts with a @samp{-},
2500 print all but the last @var{n} bytes of each file.
2501 Appending @samp{b} multiplies @var{n} by 512,
2502 @samp{kB} by 1000, @samp{K} by 1024,
2503 @samp{MB} by 1000*1000, @samp{M} by 1024*1024,
2504 @samp{GB} by 1000*1000*1000, @samp{G} by 1024*1024*1024,
2505 and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
2508 @itemx --lines=@var{n}
2511 Output the first @var{n} lines.
2512 However, if @var{n} starts with a @samp{-},
2513 print all but the last @var{n} lines of each file.
2514 Size multiplier suffixes are the same as with the @option{-c} option.
2522 Never print file name headers.
2528 Always print file name headers.
2532 For compatibility @command{head} also supports an obsolete option syntax
2533 @option{-@var{count}@var{options}}, which is recognized only if it is
2534 specified first. @var{count} is a decimal number optionally followed
2535 by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @option{-c}, or
2536 @samp{l} to mean count by lines, or other option letters (@samp{cqv}).
2537 Scripts intended for standard hosts should use @option{-c @var{count}}
2538 or @option{-n @var{count}} instead. If your script must also run on
2539 hosts that support only the obsolete syntax, it is usually simpler to
2540 avoid @command{head}, e.g., by using @samp{sed 5q} instead of
2546 @node tail invocation
2547 @section @command{tail}: Output the last part of files
2550 @cindex last part of files, outputting
2552 @command{tail} prints the last part (10 lines by default) of each
2553 @var{file}; it reads from standard input if no files are given or
2554 when given a @var{file} of @samp{-}. Synopsis:
2557 tail [@var{option}]@dots{} [@var{file}]@dots{}
2560 If more than one @var{file} is specified, @command{tail} prints a
2561 one-line header consisting of:
2564 ==> @var{file name} <==
2568 before the output for each @var{file}.
2570 @cindex BSD @command{tail}
2571 @sc{gnu} @command{tail} can output any amount of data (some other versions of
2572 @command{tail} cannot). It also has no @option{-r} option (print in
2573 reverse), since reversing a file is really a different job from printing
2574 the end of a file; BSD @command{tail} (which is the one with @option{-r}) can
2575 only reverse files that are at most as large as its buffer, which is
2576 typically 32 KiB@. A more reliable and versatile way to reverse files is
2577 the @sc{gnu} @command{tac} command.
2579 The program accepts the following options. Also see @ref{Common options}.
2583 @item -c @var{bytes}
2584 @itemx --bytes=@var{bytes}
2587 Output the last @var{bytes} bytes, instead of final lines.
2588 However, if @var{n} starts with a @samp{+}, start printing with the
2589 @var{n}th byte from the start of each file, instead of from the end.
2590 Appending @samp{b} multiplies @var{bytes} by 512,
2591 @samp{kB} by 1000, @samp{K} by 1024,
2592 @samp{MB} by 1000*1000, @samp{M} by 1024*1024,
2593 @samp{GB} by 1000*1000*1000, @samp{G} by 1024*1024*1024,
2594 and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
2597 @itemx --follow[=@var{how}]
2600 @cindex growing files
2601 @vindex name @r{follow option}
2602 @vindex descriptor @r{follow option}
2603 Loop forever trying to read more characters at the end of the file,
2604 presumably because the file is growing.
2605 If more than one file is given, @command{tail} prints a header whenever it
2606 gets output from a different file, to indicate which file that output is
2609 There are two ways to specify how you'd like to track files with this option,
2610 but that difference is noticeable only when a followed file is removed or
2612 If you'd like to continue to track the end of a growing file even after
2613 it has been unlinked, use @option{--follow=descriptor}. This is the default
2614 behavior, but it is not useful if you're tracking a log file that may be
2615 rotated (removed or renamed, then reopened). In that case, use
2616 @option{--follow=name} to track the named file by reopening it periodically
2617 to see if it has been removed and recreated by some other program.
2619 No matter which method you use, if the tracked file is determined to have
2620 shrunk, @command{tail} prints a message saying the file has been truncated
2621 and resumes tracking the end of the file from the newly-determined endpoint.
2623 When a file is removed, @command{tail}'s behavior depends on whether it is
2624 following the name or the descriptor. When following by name, tail can
2625 detect that a file has been removed and gives a message to that effect,
2626 and if @option{--retry} has been specified it will continue checking
2627 periodically to see if the file reappears.
2628 When following a descriptor, tail does not detect that the file has
2629 been unlinked or renamed and issues no message; even though the file
2630 may no longer be accessible via its original name, it may still be
2633 The option values @samp{descriptor} and @samp{name} may be specified only
2634 with the long form of the option, not with @option{-f}.
2636 @vindex POSIXLY_CORRECT
2637 If @env{POSIXLY_CORRECT} is set, the @option{-f} option is ignored if
2638 no @var{file} operand is specified and standard input is a FIFO or a pipe.
2642 This option is the same as @option{--follow=name --retry}. That is, tail
2643 will attempt to reopen a file when it is removed. Should this fail, tail
2644 will keep trying until it becomes accessible again.
2648 This option is useful mainly when following by name (i.e., with
2649 @option{--follow=name}).
2650 Without this option, when tail encounters a file that doesn't
2651 exist or is otherwise inaccessible, it reports that fact and
2652 never checks it again.
2654 @itemx --sleep-interval=@var{number}
2655 @opindex --sleep-interval
2656 Change the number of seconds to wait between iterations (the default is 1.0).
2657 During one iteration, every specified file is checked to see if it has
2659 Historical implementations of @command{tail} have required that
2660 @var{number} be an integer. However, GNU @command{tail} accepts
2661 an arbitrary floating point number (using a period before any
2664 @itemx --pid=@var{pid}
2666 When following by name or by descriptor, you may specify the process ID,
2667 @var{pid}, of the sole writer of all @var{file} arguments. Then, shortly
2668 after that process terminates, tail will also terminate. This will
2669 work properly only if the writer and the tailing process are running on
2670 the same machine. For example, to save the output of a build in a file
2671 and to watch the file grow, if you invoke @command{make} and @command{tail}
2672 like this then the tail process will stop when your build completes.
2673 Without this option, you would have had to kill the @code{tail -f}
2677 $ make >& makerr & tail --pid=$! -f makerr
2680 If you specify a @var{pid} that is not in use or that does not correspond
2681 to the process that is writing to the tailed files, then @command{tail}
2682 may terminate long before any @var{file}s stop growing or it may not
2683 terminate until long after the real writer has terminated.
2684 Note that @option{--pid} cannot be supported on some systems; @command{tail}
2685 will print a warning if this is the case.
2687 @itemx --max-unchanged-stats=@var{n}
2688 @opindex --max-unchanged-stats
2689 When tailing a file by name, if there have been @var{n} (default
2690 n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive
2691 iterations for which the file has not changed, then
2692 @code{open}/@code{fstat} the file to determine if that file name is
2693 still associated with the same device/inode-number pair as before.
2694 When following a log file that is rotated, this is approximately the
2695 number of seconds between when tail prints the last pre-rotation lines
2696 and when it prints the lines that have accumulated in the new log file.
2697 This option is meaningful only when following by name.
2700 @itemx --lines=@var{n}
2703 Output the last @var{n} lines.
2704 However, if @var{n} starts with a @samp{+}, start printing with the
2705 @var{n}th line from the start of each file, instead of from the end.
2706 Size multiplier suffixes are the same as with the @option{-c} option.
2714 Never print file name headers.
2720 Always print file name headers.
2724 For compatibility @command{tail} also supports an obsolete usage
2725 @samp{tail -[@var{count}][bcl][f] [@var{file}]}, which is recognized
2726 only if it does not conflict with the usage described
2727 above. This obsolete form uses exactly one option and at most one
2728 file. In the option, @var{count} is an optional decimal number optionally
2729 followed by a size letter (@samp{b}, @samp{c}, @samp{l}) to mean count
2730 by 512-byte blocks, bytes, or lines, optionally followed by @samp{f}
2731 which has the same meaning as @option{-f}.
2733 @vindex _POSIX2_VERSION
2734 On older systems, the leading @samp{-} can be replaced by @samp{+} in
2735 the obsolete option syntax with the same meaning as in counts, and
2736 obsolete usage overrides normal usage when the two conflict.
2737 This obsolete behavior can be enabled or disabled with the
2738 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
2741 Scripts intended for use on standard hosts should avoid obsolete
2742 syntax and should use @option{-c @var{count}[b]}, @option{-n
2743 @var{count}}, and/or @option{-f} instead. If your script must also
2744 run on hosts that support only the obsolete syntax, you can often
2745 rewrite it to avoid problematic usages, e.g., by using @samp{sed -n
2746 '$p'} rather than @samp{tail -1}. If that's not possible, the script
2747 can use a test like @samp{if tail -c +1 </dev/null >/dev/null 2>&1;
2748 then @dots{}} to decide which syntax to use.
2750 Even if your script assumes the standard behavior, you should still
2751 beware usages whose behaviors differ depending on the @acronym{POSIX}
2752 version. For example, avoid @samp{tail - main.c}, since it might be
2753 interpreted as either @samp{tail main.c} or as @samp{tail -- -
2754 main.c}; avoid @samp{tail -c 4}, since it might mean either @samp{tail
2755 -c4} or @samp{tail -c 10 4}; and avoid @samp{tail +4}, since it might
2756 mean either @samp{tail ./+4} or @samp{tail -n +4}.
2761 @node split invocation
2762 @section @command{split}: Split a file into fixed-size pieces
2765 @cindex splitting a file into pieces
2766 @cindex pieces, splitting a file into
2768 @command{split} creates output files containing consecutive sections of
2769 @var{input} (standard input if none is given or @var{input} is
2770 @samp{-}). Synopsis:
2773 split [@var{option}] [@var{input} [@var{prefix}]]
2776 By default, @command{split} puts 1000 lines of @var{input} (or whatever is
2777 left over for the last section), into each output file.
2779 @cindex output file name prefix
2780 The output files' names consist of @var{prefix} (@samp{x} by default)
2781 followed by a group of characters (@samp{aa}, @samp{ab}, @dots{} by
2782 default), such that concatenating the output files in traditional
2783 sorted order by file name produces
2784 the original input file. If the output file names are exhausted,
2785 @command{split} reports an error without deleting the output files
2788 The program accepts the following options. Also see @ref{Common options}.
2792 @item -l @var{lines}
2793 @itemx --lines=@var{lines}
2796 Put @var{lines} lines of @var{input} into each output file.
2798 For compatibility @command{split} also supports an obsolete
2799 option syntax @option{-@var{lines}}. New scripts should use @option{-l
2800 @var{lines}} instead.
2803 @itemx --bytes=@var{size}
2806 Put @var{size} bytes of @var{input} into each output file.
2807 @var{size} is a number which may be followed by one of these
2808 multiplicative suffixes:
2810 @samp{b} => 512 ("blocks")
2811 @samp{KB} => 1000 (KiloBytes)
2812 @samp{K} => 1024 (KibiBytes)
2813 @samp{MB} => 1000*1000 (MegaBytes)
2814 @samp{M} => 1024*1024 (MebiBytes)
2816 and so on for @samp{G}, @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
2819 @itemx --line-bytes=@var{size}
2821 @opindex --line-bytes
2822 Put into each output file as many complete lines of @var{input} as
2823 possible without exceeding @var{size} bytes. Individual lines longer than
2824 @var{size} bytes are broken into multiple files.
2825 @var{size} has the same format as for the @option{--bytes} option.
2827 @item -a @var{length}
2828 @itemx --suffix-length=@var{length}
2830 @opindex --suffix-length
2831 Use suffixes of length @var{length}. The default @var{length} is 2.
2834 @itemx --numeric-suffixes
2836 @opindex --numeric-suffixes
2837 Use digits in suffixes rather than lower-case letters.
2841 Write a diagnostic just before each output file is opened.
2848 @node csplit invocation
2849 @section @command{csplit}: Split a file into context-determined pieces
2852 @cindex context splitting
2853 @cindex splitting a file into pieces by context
2855 @command{csplit} creates zero or more output files containing sections of
2856 @var{input} (standard input if @var{input} is @samp{-}). Synopsis:
2859 csplit [@var{option}]@dots{} @var{input} @var{pattern}@dots{}
2862 The contents of the output files are determined by the @var{pattern}
2863 arguments, as detailed below. An error occurs if a @var{pattern}
2864 argument refers to a nonexistent line of the input file (e.g., if no
2865 remaining line matches a given regular expression). After every
2866 @var{pattern} has been matched, any remaining input is copied into one
2869 By default, @command{csplit} prints the number of bytes written to each
2870 output file after it has been created.
2872 The types of pattern arguments are:
2877 Create an output file containing the input up to but not including line
2878 @var{n} (a positive integer). If followed by a repeat count, also
2879 create an output file containing the next @var{n} lines of the input
2880 file once for each repeat.
2882 @item /@var{regexp}/[@var{offset}]
2883 Create an output file containing the current line up to (but not
2884 including) the next line of the input file that contains a match for
2885 @var{regexp}. The optional @var{offset} is an integer.
2886 If it is given, the input up to (but not including) the
2887 matching line plus or minus @var{offset} is put into the output file,
2888 and the line after that begins the next section of input.
2890 @item %@var{regexp}%[@var{offset}]
2891 Like the previous type, except that it does not create an output
2892 file, so that section of the input file is effectively ignored.
2894 @item @{@var{repeat-count}@}
2895 Repeat the previous pattern @var{repeat-count} additional
2896 times. The @var{repeat-count} can either be a positive integer or an
2897 asterisk, meaning repeat as many times as necessary until the input is
2902 The output files' names consist of a prefix (@samp{xx} by default)
2903 followed by a suffix. By default, the suffix is an ascending sequence
2904 of two-digit decimal numbers from @samp{00} to @samp{99}. In any case,
2905 concatenating the output files in sorted order by file name produces the
2906 original input file.
2908 By default, if @command{csplit} encounters an error or receives a hangup,
2909 interrupt, quit, or terminate signal, it removes any output files
2910 that it has created so far before it exits.
2912 The program accepts the following options. Also see @ref{Common options}.
2916 @item -f @var{prefix}
2917 @itemx --prefix=@var{prefix}
2920 @cindex output file name prefix
2921 Use @var{prefix} as the output file name prefix.
2923 @item -b @var{suffix}
2924 @itemx --suffix=@var{suffix}
2927 @cindex output file name suffix
2928 Use @var{suffix} as the output file name suffix. When this option is
2929 specified, the suffix string must include exactly one
2930 @code{printf(3)}-style conversion specification, possibly including
2931 format specification flags, a field width, a precision specifications,
2932 or all of these kinds of modifiers. The format letter must convert a
2933 binary integer argument to readable form; thus, only @samp{d}, @samp{i},
2934 @samp{u}, @samp{o}, @samp{x}, and @samp{X} conversions are allowed. The
2935 entire @var{suffix} is given (with the current output file number) to
2936 @code{sprintf(3)} to form the file name suffixes for each of the
2937 individual output files in turn. If this option is used, the
2938 @option{--digits} option is ignored.
2940 @item -n @var{digits}
2941 @itemx --digits=@var{digits}
2944 Use output file names containing numbers that are @var{digits} digits
2945 long instead of the default 2.
2950 @opindex --keep-files
2951 Do not remove output files when errors are encountered.
2954 @itemx --elide-empty-files
2956 @opindex --elide-empty-files
2957 Suppress the generation of zero-length output files. (In cases where
2958 the section delimiters of the input file are supposed to mark the first
2959 lines of each of the sections, the first output file will generally be a
2960 zero-length file unless you use this option.) The output file sequence
2961 numbers always run consecutively starting from 0, even when this option
2972 Do not print counts of output file sizes.
2979 @node Summarizing files
2980 @chapter Summarizing files
2982 @cindex summarizing files
2984 These commands generate just a few numbers representing entire
2988 * wc invocation:: Print newline, word, and byte counts.
2989 * sum invocation:: Print checksum and block counts.
2990 * cksum invocation:: Print CRC checksum and byte counts.
2991 * md5sum invocation:: Print or check MD5 digests.
2992 * sha1sum invocation:: Print or check SHA-1 digests.
2993 * sha2 utilities:: Print or check SHA-2 digests.
2998 @section @command{wc}: Print newline, word, and byte counts
3002 @cindex character count
3006 @command{wc} counts the number of bytes, characters, whitespace-separated
3007 words, and newlines in each given @var{file}, or standard input if none
3008 are given or for a @var{file} of @samp{-}. Synopsis:
3011 wc [@var{option}]@dots{} [@var{file}]@dots{}
3014 @cindex total counts
3015 @command{wc} prints one line of counts for each file, and if the file was
3016 given as an argument, it prints the file name following the counts. If
3017 more than one @var{file} is given, @command{wc} prints a final line
3018 containing the cumulative counts, with the file name @file{total}. The
3019 counts are printed in this order: newlines, words, characters, bytes,
3020 maximum line length.
3021 Each count is printed right-justified in a field with at least one
3022 space between fields so that the numbers and file names normally line
3023 up nicely in columns. The width of the count fields varies depending
3024 on the inputs, so you should not depend on a particular field width.
3025 However, as a @acronym{GNU} extension, if only one count is printed,
3026 it is guaranteed to be printed without leading spaces.
3028 By default, @command{wc} prints three counts: the newline, words, and byte
3029 counts. Options can specify that only certain counts be printed.
3030 Options do not undo others previously given, so
3037 prints both the byte counts and the word counts.
3039 With the @option{--max-line-length} option, @command{wc} prints the length
3040 of the longest line per file, and if there is more than one file it
3041 prints the maximum (not the sum) of those lengths.
3043 The program accepts the following options. Also see @ref{Common options}.
3051 Print only the byte counts.
3057 Print only the character counts.
3063 Print only the word counts.
3069 Print only the newline counts.
3072 @itemx --max-line-length
3074 @opindex --max-line-length
3075 Print only the maximum line lengths.
3077 @macro filesZeroFromOption{cmd,withTotalOption}
3078 @itemx --files0-from=@var{FILE}
3079 @opindex --files0-from=@var{FILE}
3080 @c This is commented out to avoid a texi2dvi failure.
3081 @c texi2dvi (GNU Texinfo 4.11) 1.104
3082 @c @cindex including files from @command{\cmd\}
3083 Rather than processing files named on the command line, process those
3084 named in file @var{FILE}; each name is terminated by a null byte.
3085 This is useful \withTotalOption\
3086 when the list of file names is so long that it may exceed a command line
3088 In such cases, running @command{\cmd\} via @command{xargs} is undesirable
3089 because it splits the list into pieces and makes @command{\cmd\} print a
3090 total for each sublist rather than for the entire list.
3091 One way to produce a list of null-byte-terminated file names is with @sc{gnu}
3092 @command{find}, using its @option{-print0} predicate.
3093 Do not specify any @var{FILE} on the command line when using this option.
3095 @filesZeroFromOption{wc,}
3097 For example, to find the length of the longest line in any @file{.c} or
3098 @file{.h} file in the current hierarchy, do this:
3101 find . -name '*.[ch]' -print0 |
3102 wc -L --files0-from=- | tail -n1
3110 @node sum invocation
3111 @section @command{sum}: Print checksum and block counts
3114 @cindex 16-bit checksum
3115 @cindex checksum, 16-bit
3117 @command{sum} computes a 16-bit checksum for each given @var{file}, or
3118 standard input if none are given or for a @var{file} of @samp{-}. Synopsis:
3121 sum [@var{option}]@dots{} [@var{file}]@dots{}
3124 @command{sum} prints the checksum for each @var{file} followed by the
3125 number of blocks in the file (rounded up). If more than one @var{file}
3126 is given, file names are also printed (by default). (With the
3127 @option{--sysv} option, corresponding file names are printed when there is
3128 at least one file argument.)
3130 By default, @sc{gnu} @command{sum} computes checksums using an algorithm
3131 compatible with BSD @command{sum} and prints file sizes in units of
3134 The program accepts the following options. Also see @ref{Common options}.
3140 @cindex BSD @command{sum}
3141 Use the default (BSD compatible) algorithm. This option is included for
3142 compatibility with the System V @command{sum}. Unless @option{-s} was also
3143 given, it has no effect.
3149 @cindex System V @command{sum}
3150 Compute checksums using an algorithm compatible with System V
3151 @command{sum}'s default, and print file sizes in units of 512-byte blocks.
3155 @command{sum} is provided for compatibility; the @command{cksum} program (see
3156 next section) is preferable in new applications.
3161 @node cksum invocation
3162 @section @command{cksum}: Print CRC checksum and byte counts
3165 @cindex cyclic redundancy check
3166 @cindex CRC checksum
3168 @command{cksum} computes a cyclic redundancy check (CRC) checksum for each
3169 given @var{file}, or standard input if none are given or for a
3170 @var{file} of @samp{-}. Synopsis:
3173 cksum [@var{option}]@dots{} [@var{file}]@dots{}
3176 @command{cksum} prints the CRC checksum for each file along with the number
3177 of bytes in the file, and the file name unless no arguments were given.
3179 @command{cksum} is typically used to ensure that files
3180 transferred by unreliable means (e.g., netnews) have not been corrupted,
3181 by comparing the @command{cksum} output for the received files with the
3182 @command{cksum} output for the original files (typically given in the
3185 The CRC algorithm is specified by the @acronym{POSIX} standard. It is not
3186 compatible with the BSD or System V @command{sum} algorithms (see the
3187 previous section); it is more robust.
3189 The only options are @option{--help} and @option{--version}. @xref{Common
3195 @node md5sum invocation
3196 @section @command{md5sum}: Print or check MD5 digests
3200 @cindex 128-bit checksum
3201 @cindex checksum, 128-bit
3202 @cindex fingerprint, 128-bit
3203 @cindex message-digest, 128-bit
3205 @command{md5sum} computes a 128-bit checksum (or @dfn{fingerprint} or
3206 @dfn{message-digest}) for each specified @var{file}.
3208 Note: The MD5 digest is more reliable than a simple CRC (provided by
3209 the @command{cksum} command) for detecting accidental file corruption,
3210 as the chances of accidentally having two files with identical MD5
3211 are vanishingly small. However, it should not be considered truly
3212 secure against malicious tampering: although finding a file with a
3213 given MD5 fingerprint, or modifying a file so as to retain its MD5 are
3214 considered infeasible at the moment, it is known how to produce
3215 different files with identical MD5 (a ``collision''), something which
3216 can be a security issue in certain contexts. For more secure hashes,
3217 consider using SHA-1 or SHA-2. @xref{sha1sum invocation}, and
3218 @ref{sha2 utilities}.
3220 If a @var{file} is specified as @samp{-} or if no files are given
3221 @command{md5sum} computes the checksum for the standard input.
3222 @command{md5sum} can also determine whether a file and checksum are
3223 consistent. Synopsis:
3226 md5sum [@var{option}]@dots{} [@var{file}]@dots{}
3229 For each @var{file}, @samp{md5sum} outputs the MD5 checksum, a flag
3230 indicating a binary or text input file, and the file name.
3231 If @var{file} contains a backslash or newline, the
3232 line is started with a backslash, and each problematic character in
3233 the file name is escaped with a backslash, making the output
3234 unambiguous even in the presence of arbitrary file names.
3235 If @var{file} is omitted or specified as @samp{-}, standard input is read.
3237 The program accepts the following options. Also see @ref{Common options}.
3245 @cindex binary input files
3246 Treat each input file as binary, by reading it in binary mode and
3247 outputting a @samp{*} flag. This is the inverse of @option{--text}.
3248 On systems like @acronym{GNU} that do not distinguish between binary
3249 and text files, this option merely flags each input file as binary:
3250 the MD5 checksum is unaffected. This option is the default on systems
3251 like MS-DOS that distinguish between binary and text files, except
3252 for reading standard input when standard input is a terminal.
3256 Read file names and checksum information (not data) from each
3257 @var{file} (or from stdin if no @var{file} was specified) and report
3258 whether the checksums match the contents of the named files.
3259 The input to this mode of @command{md5sum} is usually the output of
3260 a prior, checksum-generating run of @samp{md5sum}.
3261 Each valid line of input consists of an MD5 checksum, a binary/text
3262 flag, and then a file name.
3263 Binary files are marked with @samp{*}, text with @samp{ }.
3264 For each such line, @command{md5sum} reads the named file and computes its
3265 MD5 checksum. Then, if the computed message digest does not match the
3266 one on the line with the file name, the file is noted as having
3267 failed the test. Otherwise, the file passes the test.
3268 By default, for each valid line, one line is written to standard
3269 output indicating whether the named file passed the test.
3270 After all checks have been performed, if there were any failures,
3271 a warning is issued to standard error.
3272 Use the @option{--status} option to inhibit that output.
3273 If any listed file cannot be opened or read, if any valid line has
3274 an MD5 checksum inconsistent with the associated file, or if no valid
3275 line is found, @command{md5sum} exits with nonzero status. Otherwise,
3276 it exits successfully.
3280 @cindex verifying MD5 checksums
3281 This option is useful only when verifying checksums.
3282 When verifying checksums, don't generate the default one-line-per-file
3283 diagnostic and don't output the warning summarizing any failures.
3284 Failures to open or read a file still evoke individual diagnostics to
3286 If all listed files are readable and are consistent with the associated
3287 MD5 checksums, exit successfully. Otherwise exit with a status code
3288 indicating there was a failure.
3294 @cindex text input files
3295 Treat each input file as text, by reading it in text mode and
3296 outputting a @samp{ } flag. This is the inverse of @option{--binary}.
3297 This option is the default on systems like @acronym{GNU} that do not
3298 distinguish between binary and text files. On other systems, it is
3299 the default for reading standard input when standard input is a
3306 @cindex verifying MD5 checksums
3307 When verifying checksums, warn about improperly formatted MD5 checksum lines.
3308 This option is useful only if all but a few lines in the checked input
3316 @node sha1sum invocation
3317 @section @command{sha1sum}: Print or check SHA-1 digests
3321 @cindex 160-bit checksum
3322 @cindex checksum, 160-bit
3323 @cindex fingerprint, 160-bit
3324 @cindex message-digest, 160-bit
3326 @command{sha1sum} computes a 160-bit checksum for each specified
3327 @var{file}. The usage and options of this command are precisely the
3328 same as for @command{md5sum}. @xref{md5sum invocation}.
3330 Note: The SHA-1 digest is more secure than MD5, and no collisions of
3331 it are known (different files having the same fingerprint). However,
3332 it is known that they can be produced with considerable, but not
3333 unreasonable, resources. For this reason, it is generally considered
3334 that SHA-1 should be gradually phased out in favor of the more secure
3335 SHA-2 hash algorithms. @xref{sha2 utilities}.
3338 @node sha2 utilities
3339 @section sha2 utilities: Print or check SHA-2 digests
3346 @cindex 224-bit checksum
3347 @cindex 256-bit checksum
3348 @cindex 384-bit checksum
3349 @cindex 512-bit checksum
3350 @cindex checksum, 224-bit
3351 @cindex checksum, 256-bit
3352 @cindex checksum, 384-bit
3353 @cindex checksum, 512-bit
3354 @cindex fingerprint, 224-bit
3355 @cindex fingerprint, 256-bit
3356 @cindex fingerprint, 384-bit
3357 @cindex fingerprint, 512-bit
3358 @cindex message-digest, 224-bit
3359 @cindex message-digest, 256-bit
3360 @cindex message-digest, 384-bit
3361 @cindex message-digest, 512-bit
3363 The commands @command{sha224sum}, @command{sha256sum},
3364 @command{sha384sum} and @command{sha512sum} compute checksums of
3365 various lengths (respectively 224, 256, 384 and 512 bits),
3366 collectively known as the SHA-2 hashes. The usage and options of
3367 these commands are precisely the same as for @command{md5sum}.
3368 @xref{md5sum invocation}.
3370 Note: The SHA384 and SHA512 digests are considerably slower to
3371 compute, especially on 32-bit computers, than SHA224 or SHA256.
3374 @node Operating on sorted files
3375 @chapter Operating on sorted files
3377 @cindex operating on sorted files
3378 @cindex sorted files, operations on
3380 These commands work with (or produce) sorted files.
3383 * sort invocation:: Sort text files.
3384 * shuf invocation:: Shuffle text files.
3385 * uniq invocation:: Uniquify files.
3386 * comm invocation:: Compare two sorted files line by line.
3387 * ptx invocation:: Produce a permuted index of file contents.
3388 * tsort invocation:: Topological sort.
3389 * tsort background:: Where tsort came from.
3393 @node sort invocation
3394 @section @command{sort}: Sort text files
3397 @cindex sorting files
3399 @command{sort} sorts, merges, or compares all the lines from the given
3400 files, or standard input if none are given or for a @var{file} of
3401 @samp{-}. By default, @command{sort} writes the results to standard
3405 sort [@var{option}]@dots{} [@var{file}]@dots{}
3408 @command{sort} has three modes of operation: sort (the default), merge,
3409 and check for sortedness. The following options change the operation
3416 @itemx --check=diagnose-first
3419 @cindex checking for sortedness
3420 Check whether the given file is already sorted: if it is not all
3421 sorted, print a diagnostic containing the first out-of-order line and
3422 exit with a status of 1.
3423 Otherwise, exit successfully.
3424 At most one input file can be given.
3427 @itemx --check=quiet
3428 @itemx --check=silent
3431 @cindex checking for sortedness
3432 Exit successfully if the given file is already sorted, and
3433 exit with status 1 otherwise.
3434 At most one input file can be given.
3435 This is like @option{-c}, except it does not print a diagnostic.
3441 @cindex merging sorted files
3442 Merge the given files by sorting them as a group. Each input file must
3443 always be individually sorted. It always works to sort instead of
3444 merge; merging is provided because it is faster, in the case where it
3449 @cindex sort stability
3450 @cindex sort's last-resort comparison
3451 A pair of lines is compared as follows:
3452 @command{sort} compares each pair of fields, in the
3453 order specified on the command line, according to the associated
3454 ordering options, until a difference is found or no fields are left.
3455 If no key fields are specified, @command{sort} uses a default key of
3456 the entire line. Finally, as a last resort when all keys compare
3457 equal, @command{sort} compares entire lines as if no ordering options
3458 other than @option{--reverse} (@option{-r}) were specified. The
3459 @option{--stable} (@option{-s}) option disables this @dfn{last-resort
3460 comparison} so that lines in which all fields compare equal are left
3461 in their original relative order. The @option{--unique}
3462 (@option{-u}) option also disables the last-resort comparison.
3466 Unless otherwise specified, all comparisons use the character collating
3467 sequence specified by the @env{LC_COLLATE} locale.@footnote{If you
3468 use a non-@acronym{POSIX} locale (e.g., by setting @env{LC_ALL}
3469 to @samp{en_US}), then @command{sort} may produce output that is sorted
3470 differently than you're accustomed to. In that case, set the @env{LC_ALL}
3471 environment variable to @samp{C}. Note that setting only @env{LC_COLLATE}
3472 has two problems. First, it is ineffective if @env{LC_ALL} is also set.
3473 Second, it has undefined behavior if @env{LC_CTYPE} (or @env{LANG}, if
3474 @env{LC_CTYPE} is unset) is set to an incompatible value. For example,
3475 you get undefined behavior if @env{LC_CTYPE} is @code{ja_JP.PCK} but
3476 @env{LC_COLLATE} is @code{en_US.UTF-8}.}
3478 @sc{gnu} @command{sort} (as specified for all @sc{gnu} utilities) has no
3479 limit on input line length or restrictions on bytes allowed within lines.
3480 In addition, if the final byte of an input file is not a newline, @sc{gnu}
3481 @command{sort} silently supplies one. A line's trailing newline is not
3482 part of the line for comparison purposes.
3484 @cindex exit status of @command{sort}
3488 0 if no error occurred
3489 1 if invoked with @option{-c} or @option{-C} and the input is not sorted
3490 2 if an error occurred
3494 If the environment variable @env{TMPDIR} is set, @command{sort} uses its
3495 value as the directory for temporary files instead of @file{/tmp}. The
3496 @option{--temporary-directory} (@option{-T}) option in turn overrides
3497 the environment variable.
3499 The following options affect the ordering of output lines. They may be
3500 specified globally or as part of a specific key field. If no key
3501 fields are specified, global options apply to comparison of entire
3502 lines; otherwise the global options are inherited by key fields that do
3503 not specify any special options of their own. In pre-@acronym{POSIX}
3504 versions of @command{sort}, global options affect only later key fields,
3505 so portable shell scripts should specify global options first.
3510 @itemx --ignore-leading-blanks
3512 @opindex --ignore-leading-blanks
3513 @cindex blanks, ignoring leading
3515 Ignore leading blanks when finding sort keys in each line.
3516 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
3520 @itemx --dictionary-order
3522 @opindex --dictionary-order
3523 @cindex dictionary order
3524 @cindex phone directory order
3525 @cindex telephone directory order
3527 Sort in @dfn{phone directory} order: ignore all characters except
3528 letters, digits and blanks when sorting.
3529 By default letters and digits are those of @acronym{ASCII} and a blank
3530 is a space or a tab, but the @env{LC_CTYPE} locale can change this.
3533 @itemx --ignore-case
3535 @opindex --ignore-case
3536 @cindex ignoring case
3537 @cindex case folding
3539 Fold lowercase characters into the equivalent uppercase characters when
3540 comparing so that, for example, @samp{b} and @samp{B} sort as equal.
3541 The @env{LC_CTYPE} locale determines character types.
3544 @itemx --general-numeric-sort
3545 @itemx --sort=general-numeric
3547 @opindex --general-numeric-sort
3549 @cindex general numeric sort
3551 Sort numerically, using the standard C function @code{strtod} to convert
3552 a prefix of each line to a double-precision floating point number.
3553 This allows floating point numbers to be specified in scientific notation,
3554 like @code{1.0e-34} and @code{10e100}.
3555 The @env{LC_NUMERIC} locale determines the decimal-point character.
3556 Do not report overflow, underflow, or conversion errors.
3557 Use the following collating sequence:
3561 Lines that do not start with numbers (all considered to be equal).
3563 NaNs (``Not a Number'' values, in IEEE floating point arithmetic)
3564 in a consistent but machine-dependent order.
3568 Finite numbers in ascending numeric order (with @math{-0} and @math{+0} equal).
3573 Use this option only if there is no alternative; it is much slower than
3574 @option{--numeric-sort} (@option{-n}) and it can lose information when
3575 converting to floating point.
3578 @itemx --ignore-nonprinting
3580 @opindex --ignore-nonprinting
3581 @cindex nonprinting characters, ignoring
3582 @cindex unprintable characters, ignoring
3584 Ignore nonprinting characters.
3585 The @env{LC_CTYPE} locale determines character types.
3586 This option has no effect if the stronger @option{--dictionary-order}
3587 (@option{-d}) option is also given.
3593 @opindex --month-sort
3595 @cindex months, sorting by
3597 An initial string, consisting of any amount of blanks, followed
3598 by a month name abbreviation, is folded to UPPER case and
3599 compared in the order @samp{JAN} < @samp{FEB} < @dots{} < @samp{DEC}.
3600 Invalid names compare low to valid names. The @env{LC_TIME} locale
3601 category determines the month spellings.
3602 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
3606 @itemx --numeric-sort
3607 @itemx --sort=numeric
3609 @opindex --numeric-sort
3611 @cindex numeric sort
3613 Sort numerically. The number begins each line and consists
3614 of optional blanks, an optional @samp{-} sign, and zero or more
3615 digits possibly separated by thousands separators, optionally followed
3616 by a decimal-point character and zero or more digits. An empty
3617 number is treated as @samp{0}. The @env{LC_NUMERIC}
3618 locale specifies the decimal-point character and thousands separator.
3619 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
3622 Comparison is exact; there is no rounding error.
3624 Neither a leading @samp{+} nor exponential notation is recognized.
3625 To compare such strings numerically, use the
3626 @option{--general-numeric-sort} (@option{-g}) option.
3632 @cindex reverse sorting
3633 Reverse the result of comparison, so that lines with greater key values
3634 appear earlier in the output instead of later.
3637 @itemx --random-sort
3638 @itemx --sort=random
3640 @opindex --random-sort
3643 Sort by hashing the input keys and then sorting the hash values.
3644 Choose the hash function at random, ensuring that it is free of
3645 collisions so that differing keys have differing hash values. This is
3646 like a random permutation of the inputs (@pxref{shuf invocation}),
3647 except that keys with the same value sort together.
3649 If multiple random sort fields are specified, the same random hash
3650 function is used for all fields. To use different random hash
3651 functions for different fields, you can invoke @command{sort} more
3654 The choice of hash function is affected by the
3655 @option{--random-source} option.
3663 @item --compress-program=@var{prog}
3664 Compress any temporary files with the program @var{prog}.
3666 With no arguments, @var{prog} must compress standard input to standard
3667 output, and when given the @option{-d} option it must decompress
3668 standard input to standard output.
3670 Terminate with an error if @var{prog} exits with nonzero status.
3672 Whitespace and the backslash character should not appear in
3673 @var{prog}; they are reserved for future use.
3675 @item -k @var{pos1}[,@var{pos2}]
3676 @itemx --key=@var{pos1}[,@var{pos2}]
3680 Specify a sort field that consists of the part of the line between
3681 @var{pos1} and @var{pos2} (or the end of the line, if @var{pos2} is
3682 omitted), @emph{inclusive}.
3684 Each @var{pos} has the form @samp{@var{f}[.@var{c}][@var{opts}]},
3685 where @var{f} is the number of the field to use, and @var{c} is the number
3686 of the first character from the beginning of the field. Fields and character
3687 positions are numbered starting with 1; a character position of zero in
3688 @var{pos2} indicates the field's last character. If @samp{.@var{c}} is
3689 omitted from @var{pos1}, it defaults to 1 (the beginning of the field);
3690 if omitted from @var{pos2}, it defaults to 0 (the end of the field).
3691 @var{opts} are ordering options, allowing individual keys to be sorted
3692 according to different rules; see below for details. Keys can span
3695 Example: To sort on the second field, use @option{--key=2,2}
3696 (@option{-k 2,2}). See below for more examples.
3698 @item -o @var{output-file}
3699 @itemx --output=@var{output-file}
3702 @cindex overwriting of input, allowed
3703 Write output to @var{output-file} instead of standard output.
3704 Normally, @command{sort} reads all input before opening
3705 @var{output-file}, so you can safely sort a file in place by using
3706 commands like @code{sort -o F F} and @code{cat F | sort -o F}.
3707 However, @command{sort} with @option{--merge} (@option{-m}) can open
3708 the output file before reading all input, so a command like @code{cat
3709 F | sort -m -o F - G} is not safe as @command{sort} might start
3710 writing @file{F} before @command{cat} is done reading it.
3712 @vindex POSIXLY_CORRECT
3713 On newer systems, @option{-o} cannot appear after an input file if
3714 @env{POSIXLY_CORRECT} is set, e.g., @samp{sort F -o F}. Portable
3715 scripts should specify @option{-o @var{output-file}} before any input
3718 @item --random-source=@var{file}
3719 @opindex --random-source
3720 @cindex random source for sorting
3721 Use @var{file} as a source of random data used to determine which
3722 random hash function to use with the @option{-R} option. @xref{Random
3729 @cindex sort stability
3730 @cindex sort's last-resort comparison
3732 Make @command{sort} stable by disabling its last-resort comparison.
3733 This option has no effect if no fields or global ordering options
3734 other than @option{--reverse} (@option{-r}) are specified.
3737 @itemx --buffer-size=@var{size}
3739 @opindex --buffer-size
3740 @cindex size for main memory sorting
3741 Use a main-memory sort buffer of the given @var{size}. By default,
3742 @var{size} is in units of 1024 bytes. Appending @samp{%} causes
3743 @var{size} to be interpreted as a percentage of physical memory.
3744 Appending @samp{K} multiplies @var{size} by 1024 (the default),
3745 @samp{M} by 1,048,576, @samp{G} by 1,073,741,824, and so on for
3746 @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}. Appending
3747 @samp{b} causes @var{size} to be interpreted as a byte count, with no
3750 This option can improve the performance of @command{sort} by causing it
3751 to start with a larger or smaller sort buffer than the default.
3752 However, this option affects only the initial buffer size. The buffer
3753 grows beyond @var{size} if @command{sort} encounters input lines larger
3756 @item -t @var{separator}
3757 @itemx --field-separator=@var{separator}
3759 @opindex --field-separator
3760 @cindex field separator character
3761 Use character @var{separator} as the field separator when finding the
3762 sort keys in each line. By default, fields are separated by the empty
3763 string between a non-blank character and a blank character.
3764 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
3767 That is, given the input line @w{@samp{ foo bar}}, @command{sort} breaks it
3768 into fields @w{@samp{ foo}} and @w{@samp{ bar}}. The field separator is
3769 not considered to be part of either the field preceding or the field
3770 following, so with @samp{sort @w{-t " "}} the same input line has
3771 three fields: an empty field, @samp{foo}, and @samp{bar}.
3772 However, fields that extend to the end of the line,
3773 as @option{-k 2}, or fields consisting of a range, as @option{-k 2,3},
3774 retain the field separators present between the endpoints of the range.
3776 To specify a null character (@acronym{ASCII} @sc{nul}) as
3777 the field separator, use the two-character string @samp{\0}, e.g.,
3778 @samp{sort -t '\0'}.
3780 @item -T @var{tempdir}
3781 @itemx --temporary-directory=@var{tempdir}
3783 @opindex --temporary-directory
3784 @cindex temporary directory
3786 Use directory @var{tempdir} to store temporary files, overriding the
3787 @env{TMPDIR} environment variable. If this option is given more than
3788 once, temporary files are stored in all the directories given. If you
3789 have a large sort or merge that is I/O-bound, you can often improve
3790 performance by using this option to specify directories on different
3791 disks and controllers.
3797 @cindex uniquifying output
3799 Normally, output only the first of a sequence of lines that compare
3800 equal. For the @option{--check} (@option{-c} or @option{-C}) option,
3801 check that no pair of consecutive lines compares equal.
3803 This option also disables the default last-resort comparison.
3805 The commands @code{sort -u} and @code{sort | uniq} are equivalent, but
3806 this equivalence does not extend to arbitrary @command{sort} options.
3807 For example, @code{sort -n -u} inspects only the value of the initial
3808 numeric string when checking for uniqueness, whereas @code{sort -n |
3809 uniq} inspects the entire line. @xref{uniq invocation}.
3812 @itemx --zero-terminated
3814 @opindex --zero-terminated
3815 @cindex sort zero-terminated lines
3816 Treat the input as a set of lines, each terminated by a null character
3817 (@acronym{ASCII} @sc{nul}) instead of a line feed
3818 (@acronym{ASCII} @sc{lf}).
3819 This option can be useful in conjunction with @samp{perl -0} or
3820 @samp{find -print0} and @samp{xargs -0} which do the same in order to
3821 reliably handle arbitrary file names (even those containing blanks
3822 or other special characters).
3826 Historical (BSD and System V) implementations of @command{sort} have
3827 differed in their interpretation of some options, particularly
3828 @option{-b}, @option{-f}, and @option{-n}. @sc{gnu} sort follows the @acronym{POSIX}
3829 behavior, which is usually (but not always!) like the System V behavior.
3830 According to @acronym{POSIX}, @option{-n} no longer implies @option{-b}. For
3831 consistency, @option{-M} has been changed in the same way. This may
3832 affect the meaning of character positions in field specifications in
3833 obscure cases. The only fix is to add an explicit @option{-b}.
3835 A position in a sort field specified with @option{-k} may have any
3836 of the option letters @samp{Mbdfinr} appended to it, in which case the
3837 global ordering options are not used for that particular field. The
3838 @option{-b} option may be independently attached to either or both of
3839 the start and end positions of a field specification, and if it is
3840 inherited from the global options it will be attached to both.
3841 If input lines can contain leading or adjacent blanks and @option{-t}
3842 is not used, then @option{-k} is typically combined with @option{-b},
3843 @option{-g}, @option{-M}, or @option{-n}; otherwise the varying
3844 numbers of leading blanks in fields can cause confusing results.
3846 If the start position in a sort field specifier falls after the end of
3847 the line or after the end field, the field is empty. If the @option{-b}
3848 option was specified, the @samp{.@var{c}} part of a field specification
3849 is counted from the first nonblank character of the field.
3851 @vindex _POSIX2_VERSION
3852 @vindex POSIXLY_CORRECT
3853 On older systems, @command{sort} supports an obsolete origin-zero
3854 syntax @samp{+@var{pos1} [-@var{pos2}]} for specifying sort keys.
3855 This obsolete behavior can be enabled or disabled with the
3856 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
3857 conformance}); it can also be enabled when @env{POSIXLY_CORRECT} is
3858 not set by using the obsolete syntax with @samp{-@var{pos2}} present.
3860 Scripts intended for use on standard hosts should avoid obsolete
3861 syntax and should use @option{-k} instead. For example, avoid
3862 @samp{sort +2}, since it might be interpreted as either @samp{sort
3863 ./+2} or @samp{sort -k 3}. If your script must also run on hosts that
3864 support only the obsolete syntax, it can use a test like @samp{if sort
3865 -k 1 </dev/null >/dev/null 2>&1; then @dots{}} to decide which syntax
3868 Here are some examples to illustrate various combinations of options.
3873 Sort in descending (reverse) numeric order.
3880 Sort alphabetically, omitting the first and second fields
3881 and the blanks at the start of the third field.
3882 This uses a single key composed of the characters beginning
3883 at the start of the first nonblank character in field three
3884 and extending to the end of each line.
3891 Sort numerically on the second field and resolve ties by sorting
3892 alphabetically on the third and fourth characters of field five.
3893 Use @samp{:} as the field delimiter.
3896 sort -t : -k 2,2n -k 5.3,5.4
3899 Note that if you had written @option{-k 2n} instead of @option{-k 2,2n}
3900 @command{sort} would have used all characters beginning in the second field
3901 and extending to the end of the line as the primary @emph{numeric}
3902 key. For the large majority of applications, treating keys spanning
3903 more than one field as numeric will not do what you expect.
3905 Also note that the @samp{n} modifier was applied to the field-end
3906 specifier for the first key. It would have been equivalent to
3907 specify @option{-k 2n,2} or @option{-k 2n,2n}. All modifiers except
3908 @samp{b} apply to the associated @emph{field}, regardless of whether
3909 the modifier character is attached to the field-start and/or the
3910 field-end part of the key specifier.
3913 Sort the password file on the fifth field and ignore any
3914 leading blanks. Sort lines with equal values in field five
3915 on the numeric user ID in field three. Fields are separated
3919 sort -t : -k 5b,5 -k 3,3n /etc/passwd
3920 sort -t : -n -k 5b,5 -k 3,3 /etc/passwd
3921 sort -t : -b -k 5,5 -k 3,3n /etc/passwd
3924 These three commands have equivalent effect. The first specifies that
3925 the first key's start position ignores leading blanks and the second
3926 key is sorted numerically. The other two commands rely on global
3927 options being inherited by sort keys that lack modifiers. The inheritance
3928 works in this case because @option{-k 5b,5b} and @option{-k 5b,5} are
3929 equivalent, as the location of a field-end lacking a @samp{.@var{c}}
3930 character position is not affected by whether initial blanks are
3934 Sort a set of log files, primarily by IPv4 address and secondarily by
3935 time stamp. If two lines' primary and secondary keys are identical,
3936 output the lines in the same order that they were input. The log
3937 files contain lines that look like this:
3940 4.150.156.3 - - [01/Apr/2004:06:31:51 +0000] message 1
3941 211.24.3.231 - - [24/Apr/2004:20:17:39 +0000] message 2
3944 Fields are separated by exactly one space. Sort IPv4 addresses
3945 lexicographically, e.g., 212.61.52.2 sorts before 212.129.233.201
3946 because 61 is less than 129.
3949 sort -s -t ' ' -k 4.9n -k 4.5M -k 4.2n -k 4.14,4.21 file*.log |
3950 sort -s -t '.' -k 1,1n -k 2,2n -k 3,3n -k 4,4n
3953 This example cannot be done with a single @command{sort} invocation,
3954 since IPv4 address components are separated by @samp{.} while dates
3955 come just after a space. So it is broken down into two invocations of
3956 @command{sort}: the first sorts by time stamp and the second by IPv4
3957 address. The time stamp is sorted by year, then month, then day, and
3958 finally by hour-minute-second field, using @option{-k} to isolate each
3959 field. Except for hour-minute-second there's no need to specify the
3960 end of each key field, since the @samp{n} and @samp{M} modifiers sort
3961 based on leading prefixes that cannot cross field boundaries. The
3962 IPv4 addresses are sorted lexicographically. The second sort uses
3963 @samp{-s} so that ties in the primary key are broken by the secondary
3964 key; the first sort uses @samp{-s} so that the combination of the two
3968 Generate a tags file in case-insensitive sorted order.
3971 find src -type f -print0 | sort -z -f | xargs -0 etags --append
3974 The use of @option{-print0}, @option{-z}, and @option{-0} in this case means
3975 that file names that contain blanks or other special characters are
3977 by the sort operation.
3979 @c This example is a bit contrived and needs more explanation.
3981 @c Sort records separated by an arbitrary string by using a pipe to convert
3982 @c each record delimiter string to @samp{\0}, then using sort's -z option,
3983 @c and converting each @samp{\0} back to the original record delimiter.
3986 @c printf 'c\n\nb\n\na\n'|perl -0pe 's/\n\n/\n\0/g'|sort -z|perl -0pe 's/\0/\n/g'
3990 Shuffle a list of directories, but preserve the order of files within
3991 each directory. For instance, one could use this to generate a music
3992 playlist in which albums are shuffled but the songs of each album are
3996 ls */* | sort -t / -k 1,1R -k 2,2
4002 @node shuf invocation
4003 @section @command{shuf}: Shuffling text
4006 @cindex shuffling files
4008 @command{shuf} shuffles its input by outputting a random permutation
4009 of its input lines. Each output permutation is equally likely.
4013 shuf [@var{option}]@dots{} [@var{file}]
4014 shuf -e [@var{option}]@dots{} [@var{arg}]@dots{}
4015 shuf -i @var{lo}-@var{hi} [@var{option}]@dots{}
4018 @command{shuf} has three modes of operation that affect where it
4019 obtains its input lines. By default, it reads lines from standard
4020 input. The following options change the operation mode:
4028 @cindex command-line operands to shuffle
4029 Treat each command-line operand as an input line.
4031 @item -i @var{lo}-@var{hi}
4032 @itemx --input-range=@var{lo}-@var{hi}
4034 @opindex --input-range
4035 @cindex input range to shuffle
4036 Act as if input came from a file containing the range of unsigned
4037 decimal integers @var{lo}@dots{}@var{hi}, one per line.
4041 @command{shuf}'s other options can affect its behavior in all
4046 @item -n @var{lines}
4047 @itemx --head-lines=@var{lines}
4049 @opindex --head-lines
4050 @cindex head of output
4051 Output at most @var{lines} lines. By default, all input lines are
4054 @item -o @var{output-file}
4055 @itemx --output=@var{output-file}
4058 @cindex overwriting of input, allowed
4059 Write output to @var{output-file} instead of standard output.
4060 @command{shuf} reads all input before opening
4061 @var{output-file}, so you can safely shuffle a file in place by using
4062 commands like @code{shuf -o F <F} and @code{cat F | shuf -o F}.
4064 @item --random-source=@var{file}
4065 @opindex --random-source
4066 @cindex random source for shuffling
4067 Use @var{file} as a source of random data used to determine which
4068 permutation to generate. @xref{Random sources}.
4071 @itemx --zero-terminated
4073 @opindex --zero-terminated
4074 @cindex sort zero-terminated lines
4075 Treat the input and output as a set of lines, each terminated by a zero byte
4076 (@acronym{ASCII} @sc{nul} (Null) character) instead of an
4077 @acronym{ASCII} @sc{lf} (Line Feed).
4078 This option can be useful in conjunction with @samp{perl -0} or
4079 @samp{find -print0} and @samp{xargs -0} which do the same in order to
4080 reliably handle arbitrary file names (even those containing blanks
4081 or other special characters).
4097 might produce the output
4107 Similarly, the command:
4110 shuf -e clubs hearts diamonds spades
4124 and the command @samp{shuf -i 1-4} might output:
4134 These examples all have four input lines, so @command{shuf} might
4135 produce any of the twenty-four possible permutations of the input. In
4136 general, if there are @var{N} input lines, there are @var{N}! (i.e.,
4137 @var{N} factorial, or @var{N} * (@var{N} - 1) * @dots{} * 1) possible
4138 output permutations.
4143 @node uniq invocation
4144 @section @command{uniq}: Uniquify files
4147 @cindex uniquify files
4149 @command{uniq} writes the unique lines in the given @file{input}, or
4150 standard input if nothing is given or for an @var{input} name of
4154 uniq [@var{option}]@dots{} [@var{input} [@var{output}]]
4157 By default, @command{uniq} prints its input lines, except that
4158 it discards all but the first of adjacent repeated lines, so that
4159 no output lines are repeated. Optionally, it can instead discard
4160 lines that are not repeated, or all repeated lines.
4162 The input need not be sorted, but repeated input lines are detected
4163 only if they are adjacent. If you want to discard non-adjacent
4164 duplicate lines, perhaps you want to use @code{sort -u}.
4165 @xref{sort invocation}.
4168 Comparisons use the character collating sequence specified by the
4169 @env{LC_COLLATE} locale category.
4171 If no @var{output} file is specified, @command{uniq} writes to standard
4174 The program accepts the following options. Also see @ref{Common options}.
4179 @itemx --skip-fields=@var{n}
4181 @opindex --skip-fields
4182 Skip @var{n} fields on each line before checking for uniqueness. Use
4183 a null string for comparison if a line has fewer than @var{n} fields. Fields
4184 are sequences of non-space non-tab characters that are separated from
4185 each other by at least one space or tab.
4187 For compatibility @command{uniq} supports an obsolete option syntax
4188 @option{-@var{n}}. New scripts should use @option{-f @var{n}} instead.
4191 @itemx --skip-chars=@var{n}
4193 @opindex --skip-chars
4194 Skip @var{n} characters before checking for uniqueness. Use a null string
4195 for comparison if a line has fewer than @var{n} characters. If you use both
4196 the field and character skipping options, fields are skipped over first.
4198 @vindex _POSIX2_VERSION
4199 On older systems, @command{uniq} supports an obsolete option syntax
4201 This obsolete behavior can be enabled or disabled with the
4202 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
4203 conformance}), but portable scripts should avoid commands whose
4204 behavior depends on this variable.
4205 For example, use @samp{uniq ./+10} or @samp{uniq -s 10} rather than
4206 the ambiguous @samp{uniq +10}.
4212 Print the number of times each line occurred along with the line.
4215 @itemx --ignore-case
4217 @opindex --ignore-case
4218 Ignore differences in case when comparing lines.
4224 @cindex repeated lines, outputting
4225 Discard lines that are not repeated. When used by itself, this option
4226 causes @command{uniq} to print the first copy of each repeated line,
4230 @itemx --all-repeated[=@var{delimit-method}]
4232 @opindex --all-repeated
4233 @cindex all repeated lines, outputting
4234 Do not discard the second and subsequent repeated input lines,
4235 but discard lines that are not repeated.
4236 This option is useful mainly in conjunction with other options e.g.,
4237 to ignore case or to compare only selected fields.
4238 The optional @var{delimit-method} tells how to delimit
4239 groups of repeated lines, and must be one of the following:
4244 Do not delimit groups of repeated lines.
4245 This is equivalent to @option{--all-repeated} (@option{-D}).
4248 Output a newline before each group of repeated lines.
4249 With @option{--zero-terminated} (@option{-z}), use
4250 an @acronym{ASCII} @sc{nul} (zero) byte instead of a newline.
4253 Separate groups of repeated lines with a single newline.
4254 With @option{--zero-terminated} (@option{-z}), use
4255 an @acronym{ASCII} @sc{nul} (zero) byte instead of a newline.
4256 This is the same as using @samp{prepend}, except that
4257 no delimiter is inserted before the first group, and hence
4258 may be better suited for output direct to users.
4261 Note that when groups are delimited and the input stream contains
4262 two or more consecutive blank lines, then the output is ambiguous.
4263 To avoid that, filter the input through @samp{tr -s '\n'} to replace
4264 each sequence of consecutive newlines with a single newline.
4266 This is a @sc{gnu} extension.
4267 @c FIXME: give an example showing *how* it's useful
4273 @cindex unique lines, outputting
4274 Discard the first repeated line. When used by itself, this option
4275 causes @command{uniq} to print unique lines, and nothing else.
4278 @itemx --check-chars=@var{n}
4280 @opindex --check-chars
4281 Compare at most @var{n} characters on each line (after skipping any specified
4282 fields and characters). By default the entire rest of the lines are
4286 @itemx --zero-terminated
4288 @opindex --zero-terminated
4289 @cindex sort zero-terminated lines
4290 Treat the input as a set of lines, each terminated by a null character
4291 (@acronym{ASCII} @sc{nul}) instead of a line feed
4292 (@acronym{ASCII} @sc{lf}).
4293 This option can be useful in conjunction with @samp{sort -z}, @samp{perl -0} or
4294 @samp{find -print0} and @samp{xargs -0} which do the same in order to
4295 reliably handle arbitrary file names (even those containing blanks
4296 or other special characters).
4303 @node comm invocation
4304 @section @command{comm}: Compare two sorted files line by line
4307 @cindex line-by-line comparison
4308 @cindex comparing sorted files
4310 @command{comm} writes to standard output lines that are common, and lines
4311 that are unique, to two input files; a file name of @samp{-} means
4312 standard input. Synopsis:
4315 comm [@var{option}]@dots{} @var{file1} @var{file2}
4319 Before @command{comm} can be used, the input files must be sorted using the
4320 collating sequence specified by the @env{LC_COLLATE} locale.
4321 If an input file ends in a non-newline
4322 character, a newline is silently appended. The @command{sort} command with
4323 no options always outputs a file that is suitable input to @command{comm}.
4325 @cindex differing lines
4326 @cindex common lines
4327 With no options, @command{comm} produces three-column output. Column one
4328 contains lines unique to @var{file1}, column two contains lines unique
4329 to @var{file2}, and column three contains lines common to both files.
4330 Columns are separated by a single TAB character.
4331 @c FIXME: when there's an option to supply an alternative separator
4332 @c string, append `by default' to the above sentence.
4337 The options @option{-1}, @option{-2}, and @option{-3} suppress printing of
4338 the corresponding columns. Also see @ref{Common options}.
4340 Unlike some other comparison utilities, @command{comm} has an exit
4341 status that does not depend on the result of the comparison.
4342 Upon normal completion @command{comm} produces an exit code of zero.
4343 If there is an error it exits with nonzero status.
4346 @node tsort invocation
4347 @section @command{tsort}: Topological sort
4350 @cindex topological sort
4352 @command{tsort} performs a topological sort on the given @var{file}, or
4353 standard input if no input file is given or for a @var{file} of
4354 @samp{-}. For more details and some history, see @ref{tsort background}.
4358 tsort [@var{option}] [@var{file}]
4361 @command{tsort} reads its input as pairs of strings, separated by blanks,
4362 indicating a partial ordering. The output is a total ordering that
4363 corresponds to the given partial ordering.
4377 will produce the output
4388 Consider a more realistic example.
4389 You have a large set of functions all in one file, and they may all be
4390 declared static except one. Currently that one (say @code{main}) is the
4391 first function defined in the file, and the ones it calls directly follow
4392 it, followed by those they call, etc. Let's say that you are determined
4393 to take advantage of prototypes, so you have to choose between declaring
4394 all of those functions (which means duplicating a lot of information from
4395 the definitions) and rearranging the functions so that as many as possible
4396 are defined before they are used. One way to automate the latter process
4397 is to get a list for each function of the functions it calls directly.
4398 Many programs can generate such lists. They describe a call graph.
4399 Consider the following list, in which a given line indicates that the
4400 function on the left calls the one on the right directly.
4406 tail_file pretty_name
4407 tail_file write_header
4409 tail_forever recheck
4410 tail_forever pretty_name
4411 tail_forever write_header
4412 tail_forever dump_remainder
4415 tail_lines start_lines
4416 tail_lines dump_remainder
4417 tail_lines file_lines
4418 tail_lines pipe_lines
4420 tail_bytes start_bytes
4421 tail_bytes dump_remainder
4422 tail_bytes pipe_bytes
4423 file_lines dump_remainder
4427 then you can use @command{tsort} to produce an ordering of those
4428 functions that satisfies your requirement.
4431 example$ tsort call-graph | tac
4451 @command{tsort} detects any cycles in the input and writes the first cycle
4452 encountered to standard error.
4454 Note that for a given partial ordering, generally there is no unique
4455 total ordering. In the context of the call graph above, the function
4456 @code{parse_options} may be placed anywhere in the list as long as it
4457 precedes @code{main}.
4459 The only options are @option{--help} and @option{--version}. @xref{Common
4462 @node tsort background
4463 @section @command{tsort}: Background
4465 @command{tsort} exists because very early versions of the Unix linker processed
4466 an archive file exactly once, and in order. As @command{ld} read each object
4467 in the archive, it decided whether it was needed in the program based on
4468 whether it defined any symbols which were undefined at that point in
4471 This meant that dependencies within the archive had to be handled
4472 specially. For example, @code{scanf} probably calls @code{read}. That means
4473 that in a single pass through an archive, it was important for @code{scanf.o}
4474 to appear before read.o, because otherwise a program which calls
4475 @code{scanf} but not @code{read} might end up with an unexpected unresolved
4476 reference to @code{read}.
4478 The way to address this problem was to first generate a set of
4479 dependencies of one object file on another. This was done by a shell
4480 script called @command{lorder}. The GNU tools don't provide a version of
4481 lorder, as far as I know, but you can still find it in BSD
4484 Then you ran @command{tsort} over the @command{lorder} output, and you used the
4485 resulting sort to define the order in which you added objects to the archive.
4487 This whole procedure has been obsolete since about 1980, because
4488 Unix archives now contain a symbol table (traditionally built by
4489 @command{ranlib}, now generally built by @command{ar} itself), and the Unix
4490 linker uses the symbol table to effectively make multiple passes over
4493 Anyhow, that's where tsort came from. To solve an old problem with
4494 the way the linker handled archive files, which has since been solved
4500 @node ptx invocation
4501 @section @command{ptx}: Produce permuted indexes
4505 @command{ptx} reads a text file and essentially produces a permuted index, with
4506 each keyword in its context. The calling sketch is either one of:
4509 ptx [@var{option} @dots{}] [@var{file} @dots{}]
4510 ptx -G [@var{option} @dots{}] [@var{input} [@var{output}]]
4513 The @option{-G} (or its equivalent: @option{--traditional}) option disables
4514 all @sc{gnu} extensions and reverts to traditional mode, thus introducing some
4515 limitations and changing several of the program's default option values.
4516 When @option{-G} is not specified, @sc{gnu} extensions are always enabled.
4517 @sc{gnu} extensions to @command{ptx} are documented wherever appropriate in this
4518 document. For the full list, see @xref{Compatibility in ptx}.
4520 Individual options are explained in the following sections.
4522 When @sc{gnu} extensions are enabled, there may be zero, one or several
4523 @var{file}s after the options. If there is no @var{file}, the program
4524 reads the standard input. If there is one or several @var{file}s, they
4525 give the name of input files which are all read in turn, as if all the
4526 input files were concatenated. However, there is a full contextual
4527 break between each file and, when automatic referencing is requested,
4528 file names and line numbers refer to individual text input files. In
4529 all cases, the program outputs the permuted index to the standard
4532 When @sc{gnu} extensions are @emph{not} enabled, that is, when the program
4533 operates in traditional mode, there may be zero, one or two parameters
4534 besides the options. If there are no parameters, the program reads the
4535 standard input and outputs the permuted index to the standard output.
4536 If there is only one parameter, it names the text @var{input} to be read
4537 instead of the standard input. If two parameters are given, they give
4538 respectively the name of the @var{input} file to read and the name of
4539 the @var{output} file to produce. @emph{Be very careful} to note that,
4540 in this case, the contents of file given by the second parameter is
4541 destroyed. This behavior is dictated by System V @command{ptx}
4542 compatibility; @sc{gnu} Standards normally discourage output parameters not
4543 introduced by an option.
4545 Note that for @emph{any} file named as the value of an option or as an
4546 input text file, a single dash @kbd{-} may be used, in which case
4547 standard input is assumed. However, it would not make sense to use this
4548 convention more than once per program invocation.
4551 * General options in ptx:: Options which affect general program behavior.
4552 * Charset selection in ptx:: Underlying character set considerations.
4553 * Input processing in ptx:: Input fields, contexts, and keyword selection.
4554 * Output formatting in ptx:: Types of output format, and sizing the fields.
4555 * Compatibility in ptx::
4559 @node General options in ptx
4560 @subsection General options
4565 @itemx --traditional
4566 As already explained, this option disables all @sc{gnu} extensions to
4567 @command{ptx} and switches to traditional mode.
4570 Print a short help on standard output, then exit without further
4574 Print the program version on standard output, then exit without further
4582 @node Charset selection in ptx
4583 @subsection Charset selection
4585 @c FIXME: People don't necessarily know what an IBM-PC was these days.
4586 As it is set up now, the program assumes that the input file is coded
4587 using 8-bit @acronym{ISO} 8859-1 code, also known as Latin-1 character set,
4588 @emph{unless} it is compiled for MS-DOS, in which case it uses the
4589 character set of the IBM-PC@. (@sc{gnu} @command{ptx} is not known to work on
4590 smaller MS-DOS machines anymore.) Compared to 7-bit @acronym{ASCII}, the set
4591 of characters which are letters is different; this alters the behavior
4592 of regular expression matching. Thus, the default regular expression
4593 for a keyword allows foreign or diacriticized letters. Keyword sorting,
4594 however, is still crude; it obeys the underlying character set ordering
4600 @itemx --ignore-case
4601 Fold lower case letters to upper case for sorting.
4606 @node Input processing in ptx
4607 @subsection Word selection and input processing
4612 @itemx --break-file=@var{file}
4614 This option provides an alternative (to @option{-W}) method of describing
4615 which characters make up words. It introduces the name of a
4616 file which contains a list of characters which can@emph{not} be part of
4617 one word; this file is called the @dfn{Break file}. Any character which
4618 is not part of the Break file is a word constituent. If both options
4619 @option{-b} and @option{-W} are specified, then @option{-W} has precedence and
4620 @option{-b} is ignored.
4622 When @sc{gnu} extensions are enabled, the only way to avoid newline as a
4623 break character is to write all the break characters in the file with no
4624 newline at all, not even at the end of the file. When @sc{gnu} extensions
4625 are disabled, spaces, tabs and newlines are always considered as break
4626 characters even if not included in the Break file.
4629 @itemx --ignore-file=@var{file}
4631 The file associated with this option contains a list of words which will
4632 never be taken as keywords in concordance output. It is called the
4633 @dfn{Ignore file}. The file contains exactly one word in each line; the
4634 end of line separation of words is not subject to the value of the
4638 @itemx --only-file=@var{file}
4640 The file associated with this option contains a list of words which will
4641 be retained in concordance output; any word not mentioned in this file
4642 is ignored. The file is called the @dfn{Only file}. The file contains
4643 exactly one word in each line; the end of line separation of words is
4644 not subject to the value of the @option{-S} option.
4646 There is no default for the Only file. When both an Only file and an
4647 Ignore file are specified, a word is considered a keyword only
4648 if it is listed in the Only file and not in the Ignore file.
4653 On each input line, the leading sequence of non-white space characters will be
4654 taken to be a reference that has the purpose of identifying this input
4655 line in the resulting permuted index. For more information about reference
4656 production, see @xref{Output formatting in ptx}.
4657 Using this option changes the default value for option @option{-S}.
4659 Using this option, the program does not try very hard to remove
4660 references from contexts in output, but it succeeds in doing so
4661 @emph{when} the context ends exactly at the newline. If option
4662 @option{-r} is used with @option{-S} default value, or when @sc{gnu} extensions
4663 are disabled, this condition is always met and references are completely
4664 excluded from the output contexts.
4666 @item -S @var{regexp}
4667 @itemx --sentence-regexp=@var{regexp}
4669 This option selects which regular expression will describe the end of a
4670 line or the end of a sentence. In fact, this regular expression is not
4671 the only distinction between end of lines or end of sentences, and input
4672 line boundaries have no special significance outside this option. By
4673 default, when @sc{gnu} extensions are enabled and if @option{-r} option is not
4674 used, end of sentences are used. In this case, this @var{regex} is
4675 imported from @sc{gnu} Emacs:
4678 [.?!][]\"')@}]*\\($\\|\t\\| \\)[ \t\n]*
4681 Whenever @sc{gnu} extensions are disabled or if @option{-r} option is used, end
4682 of lines are used; in this case, the default @var{regexp} is just:
4688 Using an empty @var{regexp} is equivalent to completely disabling end of
4689 line or end of sentence recognition. In this case, the whole file is
4690 considered to be a single big line or sentence. The user might want to
4691 disallow all truncation flag generation as well, through option @option{-F
4692 ""}. @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
4695 When the keywords happen to be near the beginning of the input line or
4696 sentence, this often creates an unused area at the beginning of the
4697 output context line; when the keywords happen to be near the end of the
4698 input line or sentence, this often creates an unused area at the end of
4699 the output context line. The program tries to fill those unused areas
4700 by wrapping around context in them; the tail of the input line or
4701 sentence is used to fill the unused area on the left of the output line;
4702 the head of the input line or sentence is used to fill the unused area
4703 on the right of the output line.
4705 As a matter of convenience to the user, many usual backslashed escape
4706 sequences from the C language are recognized and converted to the
4707 corresponding characters by @command{ptx} itself.
4709 @item -W @var{regexp}
4710 @itemx --word-regexp=@var{regexp}
4712 This option selects which regular expression will describe each keyword.
4713 By default, if @sc{gnu} extensions are enabled, a word is a sequence of
4714 letters; the @var{regexp} used is @samp{\w+}. When @sc{gnu} extensions are
4715 disabled, a word is by default anything which ends with a space, a tab
4716 or a newline; the @var{regexp} used is @samp{[^ \t\n]+}.
4718 An empty @var{regexp} is equivalent to not using this option.
4719 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
4722 As a matter of convenience to the user, many usual backslashed escape
4723 sequences, as found in the C language, are recognized and converted to
4724 the corresponding characters by @command{ptx} itself.
4729 @node Output formatting in ptx
4730 @subsection Output formatting
4732 Output format is mainly controlled by the @option{-O} and @option{-T} options
4733 described in the table below. When neither @option{-O} nor @option{-T} are
4734 selected, and if @sc{gnu} extensions are enabled, the program chooses an
4735 output format suitable for a dumb terminal. Each keyword occurrence is
4736 output to the center of one line, surrounded by its left and right
4737 contexts. Each field is properly justified, so the concordance output
4738 can be readily observed. As a special feature, if automatic
4739 references are selected by option @option{-A} and are output before the
4740 left context, that is, if option @option{-R} is @emph{not} selected, then
4741 a colon is added after the reference; this nicely interfaces with @sc{gnu}
4742 Emacs @code{next-error} processing. In this default output format, each
4743 white space character, like newline and tab, is merely changed to
4744 exactly one space, with no special attempt to compress consecutive
4745 spaces. This might change in the future. Except for those white space
4746 characters, every other character of the underlying set of 256
4747 characters is transmitted verbatim.
4749 Output format is further controlled by the following options.
4753 @item -g @var{number}
4754 @itemx --gap-size=@var{number}
4756 Select the size of the minimum white space gap between the fields on the
4759 @item -w @var{number}
4760 @itemx --width=@var{number}
4762 Select the maximum output width of each final line. If references are
4763 used, they are included or excluded from the maximum output width
4764 depending on the value of option @option{-R}. If this option is not
4765 selected, that is, when references are output before the left context,
4766 the maximum output width takes into account the maximum length of all
4767 references. If this option is selected, that is, when references are
4768 output after the right context, the maximum output width does not take
4769 into account the space taken by references, nor the gap that precedes
4773 @itemx --auto-reference
4775 Select automatic references. Each input line will have an automatic
4776 reference made up of the file name and the line ordinal, with a single
4777 colon between them. However, the file name will be empty when standard
4778 input is being read. If both @option{-A} and @option{-r} are selected, then
4779 the input reference is still read and skipped, but the automatic
4780 reference is used at output time, overriding the input reference.
4783 @itemx --right-side-refs
4785 In the default output format, when option @option{-R} is not used, any
4786 references produced by the effect of options @option{-r} or @option{-A} are
4787 placed to the far right of output lines, after the right context. With
4788 default output format, when the @option{-R} option is specified, references
4789 are rather placed at the beginning of each output line, before the left
4790 context. For any other output format, option @option{-R} is
4791 ignored, with one exception: with @option{-R} the width of references
4792 is @emph{not} taken into account in total output width given by @option{-w}.
4794 This option is automatically selected whenever @sc{gnu} extensions are
4797 @item -F @var{string}
4798 @itemx --flac-truncation=@var{string}
4800 This option will request that any truncation in the output be reported
4801 using the string @var{string}. Most output fields theoretically extend
4802 towards the beginning or the end of the current line, or current
4803 sentence, as selected with option @option{-S}. But there is a maximum
4804 allowed output line width, changeable through option @option{-w}, which is
4805 further divided into space for various output fields. When a field has
4806 to be truncated because it cannot extend beyond the beginning or the end of
4807 the current line to fit in, then a truncation occurs. By default,
4808 the string used is a single slash, as in @option{-F /}.
4810 @var{string} may have more than one character, as in @option{-F ...}.
4811 Also, in the particular case when @var{string} is empty (@option{-F ""}),
4812 truncation flagging is disabled, and no truncation marks are appended in
4815 As a matter of convenience to the user, many usual backslashed escape
4816 sequences, as found in the C language, are recognized and converted to
4817 the corresponding characters by @command{ptx} itself.
4819 @item -M @var{string}
4820 @itemx --macro-name=@var{string}
4822 Select another @var{string} to be used instead of @samp{xx}, while
4823 generating output suitable for @command{nroff}, @command{troff} or @TeX{}.
4826 @itemx --format=roff
4828 Choose an output format suitable for @command{nroff} or @command{troff}
4829 processing. Each output line will look like:
4832 .xx "@var{tail}" "@var{before}" "@var{keyword_and_after}" "@var{head}" "@var{ref}"
4835 so it will be possible to write a @samp{.xx} roff macro to take care of
4836 the output typesetting. This is the default output format when @sc{gnu}
4837 extensions are disabled. Option @option{-M} can be used to change
4838 @samp{xx} to another macro name.
4840 In this output format, each non-graphical character, like newline and
4841 tab, is merely changed to exactly one space, with no special attempt to
4842 compress consecutive spaces. Each quote character: @kbd{"} is doubled
4843 so it will be correctly processed by @command{nroff} or @command{troff}.
4848 Choose an output format suitable for @TeX{} processing. Each output
4849 line will look like:
4852 \xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@{@var{after}@}@{@var{head}@}@{@var{ref}@}
4856 so it will be possible to write a @code{\xx} definition to take care of
4857 the output typesetting. Note that when references are not being
4858 produced, that is, neither option @option{-A} nor option @option{-r} is
4859 selected, the last parameter of each @code{\xx} call is inhibited.
4860 Option @option{-M} can be used to change @samp{xx} to another macro
4863 In this output format, some special characters, like @kbd{$}, @kbd{%},
4864 @kbd{&}, @kbd{#} and @kbd{_} are automatically protected with a
4865 backslash. Curly brackets @kbd{@{}, @kbd{@}} are protected with a
4866 backslash and a pair of dollar signs (to force mathematical mode). The
4867 backslash itself produces the sequence @code{\backslash@{@}}.
4868 Circumflex and tilde diacritical marks produce the sequence @code{^\@{ @}} and
4869 @code{~\@{ @}} respectively. Other diacriticized characters of the
4870 underlying character set produce an appropriate @TeX{} sequence as far
4871 as possible. The other non-graphical characters, like newline and tab,
4872 and all other characters which are not part of @acronym{ASCII}, are merely
4873 changed to exactly one space, with no special attempt to compress
4874 consecutive spaces. Let me know how to improve this special character
4875 processing for @TeX{}.
4880 @node Compatibility in ptx
4881 @subsection The @sc{gnu} extensions to @command{ptx}
4883 This version of @command{ptx} contains a few features which do not exist in
4884 System V @command{ptx}. These extra features are suppressed by using the
4885 @option{-G} command line option, unless overridden by other command line
4886 options. Some @sc{gnu} extensions cannot be recovered by overriding, so the
4887 simple rule is to avoid @option{-G} if you care about @sc{gnu} extensions.
4888 Here are the differences between this program and System V @command{ptx}.
4893 This program can read many input files at once, it always writes the
4894 resulting concordance on standard output. On the other hand, System V
4895 @command{ptx} reads only one file and sends the result to standard output
4896 or, if a second @var{file} parameter is given on the command, to that
4899 Having output parameters not introduced by options is a dangerous
4900 practice which @sc{gnu} avoids as far as possible. So, for using @command{ptx}
4901 portably between @sc{gnu} and System V, you should always use it with a
4902 single input file, and always expect the result on standard output. You
4903 might also want to automatically configure in a @option{-G} option to
4904 @command{ptx} calls in products using @command{ptx}, if the configurator finds
4905 that the installed @command{ptx} accepts @option{-G}.
4908 The only options available in System V @command{ptx} are options @option{-b},
4909 @option{-f}, @option{-g}, @option{-i}, @option{-o}, @option{-r}, @option{-t} and
4910 @option{-w}. All other options are @sc{gnu} extensions and are not repeated in
4911 this enumeration. Moreover, some options have a slightly different
4912 meaning when @sc{gnu} extensions are enabled, as explained below.
4915 By default, concordance output is not formatted for @command{troff} or
4916 @command{nroff}. It is rather formatted for a dumb terminal. @command{troff}
4917 or @command{nroff} output may still be selected through option @option{-O}.
4920 Unless @option{-R} option is used, the maximum reference width is
4921 subtracted from the total output line width. With @sc{gnu} extensions
4922 disabled, width of references is not taken into account in the output
4923 line width computations.
4926 All 256 bytes, even null bytes, are always read and processed from
4927 input file with no adverse effect, even if @sc{gnu} extensions are disabled.
4928 However, System V @command{ptx} does not accept 8-bit characters, a few
4929 control characters are rejected, and the tilde @kbd{~} is also rejected.
4932 Input line length is only limited by available memory, even if @sc{gnu}
4933 extensions are disabled. However, System V @command{ptx} processes only
4934 the first 200 characters in each line.
4937 The break (non-word) characters default to be every character except all
4938 letters of the underlying character set, diacriticized or not. When @sc{gnu}
4939 extensions are disabled, the break characters default to space, tab and
4943 The program makes better use of output line width. If @sc{gnu} extensions
4944 are disabled, the program rather tries to imitate System V @command{ptx},
4945 but still, there are some slight disposition glitches this program does
4946 not completely reproduce.
4949 The user can specify both an Ignore file and an Only file. This is not
4950 allowed with System V @command{ptx}.
4955 @node Operating on fields within a line
4956 @chapter Operating on fields within a line
4959 * cut invocation:: Print selected parts of lines.
4960 * paste invocation:: Merge lines of files.
4961 * join invocation:: Join lines on a common field.
4965 @node cut invocation
4966 @section @command{cut}: Print selected parts of lines
4969 @command{cut} writes to standard output selected parts of each line of each
4970 input file, or standard input if no files are given or for a file name of
4974 cut @var{option}@dots{} [@var{file}]@dots{}
4977 In the table which follows, the @var{byte-list}, @var{character-list},
4978 and @var{field-list} are one or more numbers or ranges (two numbers
4979 separated by a dash) separated by commas. Bytes, characters, and
4980 fields are numbered starting at 1. Incomplete ranges may be
4981 given: @option{-@var{m}} means @samp{1-@var{m}}; @samp{@var{n}-} means
4982 @samp{@var{n}} through end of line or last field. The list elements
4983 can be repeated, can overlap, and can be specified in any order; but
4984 the selected input is written in the same order that it is read, and
4985 is written exactly once.
4987 The program accepts the following options. Also see @ref{Common
4992 @item -b @var{byte-list}
4993 @itemx --bytes=@var{byte-list}
4996 Select for printing only the bytes in positions listed in
4997 @var{byte-list}. Tabs and backspaces are treated like any other
4998 character; they take up 1 byte. If an output delimiter is specified,
4999 (see the description of @option{--output-delimiter}), then output that
5000 string between ranges of selected bytes.
5002 @item -c @var{character-list}
5003 @itemx --characters=@var{character-list}
5005 @opindex --characters
5006 Select for printing only the characters in positions listed in
5007 @var{character-list}. The same as @option{-b} for now, but
5008 internationalization will change that. Tabs and backspaces are
5009 treated like any other character; they take up 1 character. If an
5010 output delimiter is specified, (see the description of
5011 @option{--output-delimiter}), then output that string between ranges
5014 @item -f @var{field-list}
5015 @itemx --fields=@var{field-list}
5018 Select for printing only the fields listed in @var{field-list}.
5019 Fields are separated by a TAB character by default. Also print any
5020 line that contains no delimiter character, unless the
5021 @option{--only-delimited} (@option{-s}) option is specified
5023 @item -d @var{input_delim_byte}
5024 @itemx --delimiter=@var{input_delim_byte}
5026 @opindex --delimiter
5027 With @option{-f}, use the first byte of @var{input_delim_byte} as
5028 the input fields separator (default is TAB).
5032 Do not split multi-byte characters (no-op for now).
5035 @itemx --only-delimited
5037 @opindex --only-delimited
5038 For @option{-f}, do not print lines that do not contain the field separator
5039 character. Normally, any line without a field separator is printed verbatim.
5041 @item --output-delimiter=@var{output_delim_string}
5042 @opindex --output-delimiter
5043 With @option{-f}, output fields are separated by @var{output_delim_string}.
5044 The default with @option{-f} is to use the input delimiter.
5045 When using @option{-b} or @option{-c} to select ranges of byte or
5046 character offsets (as opposed to ranges of fields),
5047 output @var{output_delim_string} between non-overlapping
5048 ranges of selected bytes.
5051 @opindex --complement
5052 This option is a @acronym{GNU} extension.
5053 Select for printing the complement of the bytes, characters or fields
5054 selected with the @option{-b}, @option{-c} or @option{-f} options.
5055 In other words, do @emph{not} print the bytes, characters or fields
5056 specified via those options. This option is useful when you have
5057 many fields and want to print all but a few of them.
5064 @node paste invocation
5065 @section @command{paste}: Merge lines of files
5068 @cindex merging files
5070 @command{paste} writes to standard output lines consisting of sequentially
5071 corresponding lines of each given file, separated by a TAB character.
5072 Standard input is used for a file name of @samp{-} or if no input files
5094 paste [@var{option}]@dots{} [@var{file}]@dots{}
5097 The program accepts the following options. Also see @ref{Common options}.
5105 Paste the lines of one file at a time rather than one line from each
5106 file. Using the above example data:
5109 $ paste -s num2 let3
5114 @item -d @var{delim-list}
5115 @itemx --delimiters=@var{delim-list}
5117 @opindex --delimiters
5118 Consecutively use the characters in @var{delim-list} instead of
5119 TAB to separate merged lines. When @var{delim-list} is
5120 exhausted, start again at its beginning. Using the above example data:
5123 $ paste -d '%_' num2 let3 num2
5134 @node join invocation
5135 @section @command{join}: Join lines on a common field
5138 @cindex common field, joining on
5140 @command{join} writes to standard output a line for each pair of input
5141 lines that have identical join fields. Synopsis:
5144 join [@var{option}]@dots{} @var{file1} @var{file2}
5147 Either @var{file1} or @var{file2} (but not both) can be @samp{-},
5148 meaning standard input. @var{file1} and @var{file2} should be
5149 sorted on the join fields.
5152 Normally, the sort order is that of the
5153 collating sequence specified by the @env{LC_COLLATE} locale. Unless
5154 the @option{-t} option is given, the sort comparison ignores blanks at
5155 the start of the join field, as in @code{sort -b}. If the
5156 @option{--ignore-case} option is given, the sort comparison ignores
5157 the case of characters in the join field, as in @code{sort -f}.
5159 The @command{sort} and @command{join} commands should use consistent
5160 locales and options if the output of @command{sort} is fed to
5161 @command{join}. You can use a command like @samp{sort -k 1b,1} to
5162 sort a file on its default join field, but if you select a non-default
5163 locale, join field, separator, or comparison options, then you should
5164 do so consistently between @command{join} and @command{sort}.
5166 If the input has no unpairable lines, a @acronym{GNU} extension is
5167 available; the sort order can be any order that considers two fields
5168 to be equal if and only if the sort comparison described above
5169 considers them to be equal. For example:
5186 If the @option{--check-order} option is given, unsorted inputs will
5187 cause a fatal error message. If the option @option{--nocheck-order}
5188 is given, unsorted inputs will never cause an error message. If
5189 neither of these options is given, wrongly sorted inputs are diagnosed
5190 only if an input file is found to contain unpairable lines. If an
5191 input file is diagnosed as being unsorted, the @command{join} command
5192 will exit with a nonzero status (and the output should not be used).
5194 Forcing @command{join} to process wrongly sorted input files
5195 containing unpairable lines by specifying @option{--nocheck-order} is
5196 not guaranteed to produce any particular output. The output will
5197 probably not correspond with whatever you hoped it would be.
5201 @item the join field is the first field in each line;
5202 @item fields in the input are separated by one or more blanks, with leading
5203 blanks on the line ignored;
5204 @item fields in the output are separated by a space;
5205 @item each output line consists of the join field, the remaining
5206 fields from @var{file1}, then the remaining fields from @var{file2}.
5209 The program accepts the following options. Also see @ref{Common options}.
5213 @item -a @var{file-number}
5215 Print a line for each unpairable line in file @var{file-number} (either
5216 @samp{1} or @samp{2}), in addition to the normal output.
5219 Fail with an error message if either input file is wrongly ordered.
5221 @item --nocheck-order
5222 Do not check that both input files are in sorted order. This is the default.
5224 @item -e @var{string}
5226 Replace those output fields that are missing in the input with
5230 @itemx --ignore-case
5232 @opindex --ignore-case
5233 Ignore differences in case when comparing keys.
5234 With this option, the lines of the input files must be ordered in the same way.
5235 Use @samp{sort -f} to produce this ordering.
5237 @item -1 @var{field}
5239 Join on field @var{field} (a positive integer) of file 1.
5241 @item -2 @var{field}
5243 Join on field @var{field} (a positive integer) of file 2.
5245 @item -j @var{field}
5246 Equivalent to @option{-1 @var{field} -2 @var{field}}.
5248 @item -o @var{field-list}
5249 Construct each output line according to the format in @var{field-list}.
5250 Each element in @var{field-list} is either the single character @samp{0} or
5251 has the form @var{m.n} where the file number, @var{m}, is @samp{1} or
5252 @samp{2} and @var{n} is a positive field number.
5254 A field specification of @samp{0} denotes the join field.
5255 In most cases, the functionality of the @samp{0} field spec
5256 may be reproduced using the explicit @var{m.n} that corresponds
5257 to the join field. However, when printing unpairable lines
5258 (using either of the @option{-a} or @option{-v} options), there is no way
5259 to specify the join field using @var{m.n} in @var{field-list}
5260 if there are unpairable lines in both files.
5261 To give @command{join} that functionality, @acronym{POSIX} invented the @samp{0}
5262 field specification notation.
5264 The elements in @var{field-list}
5265 are separated by commas or blanks.
5266 Blank separators typically need to be quoted for the shell. For
5267 example, the commands @samp{join -o 1.2,2.2} and @samp{join -o '1.2
5268 2.2'} are equivalent.
5270 All output lines---including those printed because of any -a or -v
5271 option---are subject to the specified @var{field-list}.
5274 Use character @var{char} as the input and output field separator.
5275 Treat as significant each occurrence of @var{char} in the input file.
5276 Use @samp{sort -t @var{char}}, without the @option{-b} option of
5277 @samp{sort}, to produce this ordering.
5279 @item -v @var{file-number}
5280 Print a line for each unpairable line in file @var{file-number}
5281 (either @samp{1} or @samp{2}), instead of the normal output.
5288 @node Operating on characters
5289 @chapter Operating on characters
5291 @cindex operating on characters
5293 This commands operate on individual characters.
5296 * tr invocation:: Translate, squeeze, and/or delete characters.
5297 * expand invocation:: Convert tabs to spaces.
5298 * unexpand invocation:: Convert spaces to tabs.
5303 @section @command{tr}: Translate, squeeze, and/or delete characters
5310 tr [@var{option}]@dots{} @var{set1} [@var{set2}]
5313 @command{tr} copies standard input to standard output, performing
5314 one of the following operations:
5318 translate, and optionally squeeze repeated characters in the result,
5320 squeeze repeated characters,
5324 delete characters, then squeeze repeated characters from the result.
5327 The @var{set1} and (if given) @var{set2} arguments define ordered
5328 sets of characters, referred to below as @var{set1} and @var{set2}. These
5329 sets are the characters of the input that @command{tr} operates on.
5330 The @option{--complement} (@option{-c}, @option{-C}) option replaces
5332 complement (all of the characters that are not in @var{set1}).
5334 Currently @command{tr} fully supports only single-byte characters.
5335 Eventually it will support multibyte characters; when it does, the
5336 @option{-C} option will cause it to complement the set of characters,
5337 whereas @option{-c} will cause it to complement the set of values.
5338 This distinction will matter only when some values are not characters,
5339 and this is possible only in locales using multibyte encodings when
5340 the input contains encoding errors.
5342 The program accepts the @option{--help} and @option{--version}
5343 options. @xref{Common options}. Options must precede operands.
5348 * Character sets:: Specifying sets of characters.
5349 * Translating:: Changing one set of characters to another.
5350 * Squeezing:: Squeezing repeats and deleting.
5354 @node Character sets
5355 @subsection Specifying sets of characters
5357 @cindex specifying sets of characters
5359 The format of the @var{set1} and @var{set2} arguments resembles
5360 the format of regular expressions; however, they are not regular
5361 expressions, only lists of characters. Most characters simply
5362 represent themselves in these strings, but the strings can contain
5363 the shorthands listed below, for convenience. Some of them can be
5364 used only in @var{set1} or @var{set2}, as noted below.
5368 @item Backslash escapes
5369 @cindex backslash escapes
5371 The following backslash escape sequences are recognized:
5389 The character with the value given by @var{ooo}, which is 1 to 3
5395 While a backslash followed by a character not listed above is
5396 interpreted as that character, the backslash also effectively
5397 removes any special significance, so it is useful to escape
5398 @samp{[}, @samp{]}, @samp{*}, and @samp{-}.
5403 The notation @samp{@var{m}-@var{n}} expands to all of the characters
5404 from @var{m} through @var{n}, in ascending order. @var{m} should
5405 collate before @var{n}; if it doesn't, an error results. As an example,
5406 @samp{0-9} is the same as @samp{0123456789}.
5408 @sc{gnu} @command{tr} does not support the System V syntax that uses square
5409 brackets to enclose ranges. Translations specified in that format
5410 sometimes work as expected, since the brackets are often transliterated
5411 to themselves. However, they should be avoided because they sometimes
5412 behave unexpectedly. For example, @samp{tr -d '[0-9]'} deletes brackets
5415 Many historically common and even accepted uses of ranges are not
5416 portable. For example, on @acronym{EBCDIC} hosts using the @samp{A-Z}
5417 range will not do what most would expect because @samp{A} through @samp{Z}
5418 are not contiguous as they are in @acronym{ASCII}.
5419 If you can rely on a @acronym{POSIX} compliant version of @command{tr}, then
5420 the best way to work around this is to use character classes (see below).
5421 Otherwise, it is most portable (and most ugly) to enumerate the members
5424 @item Repeated characters
5425 @cindex repeated characters
5427 The notation @samp{[@var{c}*@var{n}]} in @var{set2} expands to @var{n}
5428 copies of character @var{c}. Thus, @samp{[y*6]} is the same as
5429 @samp{yyyyyy}. The notation @samp{[@var{c}*]} in @var{string2} expands
5430 to as many copies of @var{c} as are needed to make @var{set2} as long as
5431 @var{set1}. If @var{n} begins with @samp{0}, it is interpreted in
5432 octal, otherwise in decimal.
5434 @item Character classes
5435 @cindex character classes
5437 The notation @samp{[:@var{class}:]} expands to all of the characters in
5438 the (predefined) class @var{class}. The characters expand in no
5439 particular order, except for the @code{upper} and @code{lower} classes,
5440 which expand in ascending order. When the @option{--delete} (@option{-d})
5441 and @option{--squeeze-repeats} (@option{-s}) options are both given, any
5442 character class can be used in @var{set2}. Otherwise, only the
5443 character classes @code{lower} and @code{upper} are accepted in
5444 @var{set2}, and then only if the corresponding character class
5445 (@code{upper} and @code{lower}, respectively) is specified in the same
5446 relative position in @var{set1}. Doing this specifies case conversion.
5447 The class names are given below; an error results when an invalid class
5459 Horizontal whitespace.
5468 Printable characters, not including space.
5474 Printable characters, including space.
5477 Punctuation characters.
5480 Horizontal or vertical whitespace.
5489 @item Equivalence classes
5490 @cindex equivalence classes
5492 The syntax @samp{[=@var{c}=]} expands to all of the characters that are
5493 equivalent to @var{c}, in no particular order. Equivalence classes are
5494 a relatively recent invention intended to support non-English alphabets.
5495 But there seems to be no standard way to define them or determine their
5496 contents. Therefore, they are not fully implemented in @sc{gnu} @command{tr};
5497 each character's equivalence class consists only of that character,
5498 which is of no particular use.
5504 @subsection Translating
5506 @cindex translating characters
5508 @command{tr} performs translation when @var{set1} and @var{set2} are
5509 both given and the @option{--delete} (@option{-d}) option is not given.
5510 @command{tr} translates each character of its input that is in @var{set1}
5511 to the corresponding character in @var{set2}. Characters not in
5512 @var{set1} are passed through unchanged. When a character appears more
5513 than once in @var{set1} and the corresponding characters in @var{set2}
5514 are not all the same, only the final one is used. For example, these
5515 two commands are equivalent:
5522 A common use of @command{tr} is to convert lowercase characters to
5523 uppercase. This can be done in many ways. Here are three of them:
5526 tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
5528 tr '[:lower:]' '[:upper:]'
5532 But note that using ranges like @code{a-z} above is not portable.
5534 When @command{tr} is performing translation, @var{set1} and @var{set2}
5535 typically have the same length. If @var{set1} is shorter than
5536 @var{set2}, the extra characters at the end of @var{set2} are ignored.
5538 On the other hand, making @var{set1} longer than @var{set2} is not
5539 portable; @acronym{POSIX} says that the result is undefined. In this situation,
5540 BSD @command{tr} pads @var{set2} to the length of @var{set1} by repeating
5541 the last character of @var{set2} as many times as necessary. System V
5542 @command{tr} truncates @var{set1} to the length of @var{set2}.
5544 By default, @sc{gnu} @command{tr} handles this case like BSD @command{tr}.
5545 When the @option{--truncate-set1} (@option{-t}) option is given,
5546 @sc{gnu} @command{tr} handles this case like the System V @command{tr}
5547 instead. This option is ignored for operations other than translation.
5549 Acting like System V @command{tr} in this case breaks the relatively common
5553 tr -cs A-Za-z0-9 '\012'
5557 because it converts only zero bytes (the first element in the
5558 complement of @var{set1}), rather than all non-alphanumerics, to
5562 By the way, the above idiom is not portable because it uses ranges, and
5563 it assumes that the octal code for newline is 012.
5564 Assuming a @acronym{POSIX} compliant @command{tr}, here is a better way to write it:
5567 tr -cs '[:alnum:]' '[\n*]'
5572 @subsection Squeezing repeats and deleting
5574 @cindex squeezing repeat characters
5575 @cindex deleting characters
5577 When given just the @option{--delete} (@option{-d}) option, @command{tr}
5578 removes any input characters that are in @var{set1}.
5580 When given just the @option{--squeeze-repeats} (@option{-s}) option,
5581 @command{tr} replaces each input sequence of a repeated character that
5582 is in @var{set1} with a single occurrence of that character.
5584 When given both @option{--delete} and @option{--squeeze-repeats}, @command{tr}
5585 first performs any deletions using @var{set1}, then squeezes repeats
5586 from any remaining characters using @var{set2}.
5588 The @option{--squeeze-repeats} option may also be used when translating,
5589 in which case @command{tr} first performs translation, then squeezes
5590 repeats from any remaining characters using @var{set2}.
5592 Here are some examples to illustrate various combinations of options:
5597 Remove all zero bytes:
5604 Put all words on lines by themselves. This converts all
5605 non-alphanumeric characters to newlines, then squeezes each string
5606 of repeated newlines into a single newline:
5609 tr -cs '[:alnum:]' '[\n*]'
5613 Convert each sequence of repeated newlines to a single newline:
5620 Find doubled occurrences of words in a document.
5621 @c Separate the following two "the"s, so typo checkers don't complain.
5622 For example, people often write ``the @w{}the'' with the repeated words
5623 separated by a newline. The Bourne shell script below works first
5624 by converting each sequence of punctuation and blank characters to a
5625 single newline. That puts each ``word'' on a line by itself.
5626 Next it maps all uppercase characters to lower case, and finally it
5627 runs @command{uniq} with the @option{-d} option to print out only the words
5633 | tr -s '[:punct:][:blank:]' '[\n*]' \
5634 | tr '[:upper:]' '[:lower:]' \
5639 Deleting a small set of characters is usually straightforward. For example,
5640 to remove all @samp{a}s, @samp{x}s, and @samp{M}s you would do this:
5646 However, when @samp{-} is one of those characters, it can be tricky because
5647 @samp{-} has special meanings. Performing the same task as above but also
5648 removing all @samp{-} characters, we might try @code{tr -d -axM}, but
5649 that would fail because @command{tr} would try to interpret @option{-a} as
5650 a command-line option. Alternatively, we could try putting the hyphen
5651 inside the string, @code{tr -d a-xM}, but that wouldn't work either because
5652 it would make @command{tr} interpret @code{a-x} as the range of characters
5653 @samp{a}@dots{}@samp{x} rather than the three.
5654 One way to solve the problem is to put the hyphen at the end of the list
5661 Or you can use @samp{--} to terminate option processing:
5667 More generally, use the character class notation @code{[=c=]}
5668 with @samp{-} (or any other character) in place of the @samp{c}:
5674 Note how single quotes are used in the above example to protect the
5675 square brackets from interpretation by a shell.
5680 @node expand invocation
5681 @section @command{expand}: Convert tabs to spaces
5684 @cindex tabs to spaces, converting
5685 @cindex converting tabs to spaces
5687 @command{expand} writes the contents of each given @var{file}, or standard
5688 input if none are given or for a @var{file} of @samp{-}, to standard
5689 output, with tab characters converted to the appropriate number of
5693 expand [@var{option}]@dots{} [@var{file}]@dots{}
5696 By default, @command{expand} converts all tabs to spaces. It preserves
5697 backspace characters in the output; they decrement the column count for
5698 tab calculations. The default action is equivalent to @option{-t 8} (set
5699 tabs every 8 columns).
5701 The program accepts the following options. Also see @ref{Common options}.
5705 @item -t @var{tab1}[,@var{tab2}]@dots{}
5706 @itemx --tabs=@var{tab1}[,@var{tab2}]@dots{}
5709 @cindex tab stops, setting
5710 If only one tab stop is given, set the tabs @var{tab1} spaces apart
5711 (default is 8). Otherwise, set the tabs at columns @var{tab1},
5712 @var{tab2}, @dots{} (numbered from 0), and replace any tabs beyond the
5713 last tab stop given with single spaces. Tab stops can be separated by
5714 blanks as well as by commas.
5716 For compatibility, GNU @command{expand} also accepts the obsolete
5717 option syntax, @option{-@var{t1}[,@var{t2}]@dots{}}. New scripts
5718 should use @option{-t @var{t1}[,@var{t2}]@dots{}} instead.
5724 @cindex initial tabs, converting
5725 Only convert initial tabs (those that precede all non-space or non-tab
5726 characters) on each line to spaces.
5733 @node unexpand invocation
5734 @section @command{unexpand}: Convert spaces to tabs
5738 @command{unexpand} writes the contents of each given @var{file}, or
5739 standard input if none are given or for a @var{file} of @samp{-}, to
5740 standard output, converting blanks at the beginning of each line into
5741 as many tab characters as needed. In the default @acronym{POSIX}
5742 locale, a @dfn{blank} is a space or a tab; other locales may specify
5743 additional blank characters. Synopsis:
5746 unexpand [@var{option}]@dots{} [@var{file}]@dots{}
5749 By default, @command{unexpand} converts only initial blanks (those
5750 that precede all non-blank characters) on each line. It
5751 preserves backspace characters in the output; they decrement the column
5752 count for tab calculations. By default, tabs are set at every 8th
5755 The program accepts the following options. Also see @ref{Common options}.
5759 @item -t @var{tab1}[,@var{tab2}]@dots{}
5760 @itemx --tabs=@var{tab1}[,@var{tab2}]@dots{}
5763 If only one tab stop is given, set the tabs @var{tab1} columns apart
5764 instead of the default 8. Otherwise, set the tabs at columns
5765 @var{tab1}, @var{tab2}, @dots{} (numbered from 0), and leave blanks
5766 beyond the tab stops given unchanged. Tab stops can be separated by
5767 blanks as well as by commas. This option implies the @option{-a} option.
5769 For compatibility, GNU @command{unexpand} supports the obsolete option syntax,
5770 @option{-@var{tab1}[,@var{tab2}]@dots{}}, where tab stops must be
5771 separated by commas. (Unlike @option{-t}, this obsolete option does
5772 not imply @option{-a}.) New scripts should use @option{--first-only -t
5773 @var{tab1}[,@var{tab2}]@dots{}} instead.
5779 Also convert all sequences of two or more blanks just before a tab stop,
5780 even if they occur after non-blank characters in a line.
5787 @node Directory listing
5788 @chapter Directory listing
5790 This chapter describes the @command{ls} command and its variants @command{dir}
5791 and @command{vdir}, which list information about files.
5794 * ls invocation:: List directory contents.
5795 * dir invocation:: Briefly ls.
5796 * vdir invocation:: Verbosely ls.
5797 * dircolors invocation:: Color setup for ls, etc.
5802 @section @command{ls}: List directory contents
5805 @cindex directory listing
5807 The @command{ls} program lists information about files (of any type,
5808 including directories). Options and file arguments can be intermixed
5809 arbitrarily, as usual.
5811 For non-option command-line arguments that are directories, by default
5812 @command{ls} lists the contents of directories, not recursively, and
5813 omitting files with names beginning with @samp{.}. For other non-option
5814 arguments, by default @command{ls} lists just the file name. If no
5815 non-option argument is specified, @command{ls} operates on the current
5816 directory, acting as if it had been invoked with a single argument of @samp{.}.
5819 By default, the output is sorted alphabetically, according to the locale
5820 settings in effect.@footnote{If you use a non-@acronym{POSIX}
5821 locale (e.g., by setting @env{LC_ALL} to @samp{en_US}), then @command{ls} may
5822 produce output that is sorted differently than you're accustomed to.
5823 In that case, set the @env{LC_ALL} environment variable to @samp{C}.}
5824 If standard output is
5825 a terminal, the output is in columns (sorted vertically) and control
5826 characters are output as question marks; otherwise, the output is listed
5827 one per line and control characters are output as-is.
5829 Because @command{ls} is such a fundamental program, it has accumulated many
5830 options over the years. They are described in the subsections below;
5831 within each section, options are listed alphabetically (ignoring case).
5832 The division of options into the subsections is not absolute, since some
5833 options affect more than one aspect of @command{ls}'s operation.
5835 @cindex exit status of @command{ls}
5840 1 minor problems (e.g., a subdirectory was not found)
5841 2 serious trouble (e.g., memory exhausted)
5844 Also see @ref{Common options}.
5847 * Which files are listed::
5848 * What information is listed::
5849 * Sorting the output::
5850 * More details about version sort::
5851 * General output formatting::
5852 * Formatting file timestamps::
5853 * Formatting the file names::
5857 @node Which files are listed
5858 @subsection Which files are listed
5860 These options determine which files @command{ls} lists information for.
5861 By default, @command{ls} lists files and the contents of any
5862 directories on the command line, except that in directories it ignores
5863 files whose names start with @samp{.}.
5871 In directories, do not ignore file names that start with @samp{.}.
5876 @opindex --almost-all
5877 In directories, do not ignore all file names that start with @samp{.};
5878 ignore only @file{.} and @file{..}. The @option{--all} (@option{-a})
5879 option overrides this option.
5882 @itemx --ignore-backups
5884 @opindex --ignore-backups
5885 @cindex backup files, ignoring
5886 In directories, ignore files that end with @samp{~}. This option is
5887 equivalent to @samp{--ignore='*~' --ignore='.*~'}.
5892 @opindex --directory
5893 List just the names of directories, as with other types of files, rather
5894 than listing their contents.
5895 @c The following sentence is the same as the one for -F.
5896 Do not follow symbolic links listed on the
5897 command line unless the @option{--dereference-command-line} (@option{-H}),
5898 @option{--dereference} (@option{-L}), or
5899 @option{--dereference-command-line-symlink-to-dir} options are specified.
5902 @itemx --dereference-command-line
5904 @opindex --dereference-command-line
5905 @cindex symbolic links, dereferencing
5906 If a command line argument specifies a symbolic link, show information
5907 for the file the link references rather than for the link itself.
5909 @itemx --dereference-command-line-symlink-to-dir
5910 @opindex --dereference-command-line-symlink-to-dir
5911 @cindex symbolic links, dereferencing
5912 Do not dereference symbolic links, with one exception:
5913 if a command line argument specifies a symbolic link that refers to
5914 a directory, show information for that directory rather than for the
5916 This is the default behavior when no other dereferencing-related
5917 option has been specified (@option{--classify} (@option{-F}),
5918 @option{--directory} (@option{-d}),
5920 @option{--dereference} (@option{-L}), or
5921 @option{--dereference-command-line} (@option{-H})).
5923 @item --group-directories-first
5924 @opindex --group-directories-first
5925 Group all the directories before the files and then sort the
5926 directories and the files separately using the selected sort key
5927 (see --sort option).
5928 That is, this option specifies a primary sort key,
5929 and the --sort option specifies a secondary key.
5930 However, any use of @option{--sort=none}
5931 (@option{-U}) disables this option altogether.
5933 @item --hide=PATTERN
5934 @opindex --hide=@var{pattern}
5935 In directories, ignore files whose names match the shell pattern
5936 @var{pattern}, unless the @option{--all} (@option{-a}) or
5937 @option{--almost-all} (@option{-A}) is also given. This
5938 option acts like @option{--ignore=@var{pattern}} except that it has no
5939 effect if @option{--all} (@option{-a}) or @option{--almost-all}
5940 (@option{-A}) is also given.
5942 This option can be useful in shell aliases. For example, if
5943 @command{lx} is an alias for @samp{ls --hide='*~'} and @command{ly} is
5944 an alias for @samp{ls --ignore='*~'}, then the command @samp{lx -A}
5945 lists the file @file{README~} even though @samp{ly -A} would not.
5947 @item -I @var{pattern}
5948 @itemx --ignore=@var{pattern}
5950 @opindex --ignore=@var{pattern}
5951 In directories, ignore files whose names match the shell pattern
5952 (not regular expression) @var{pattern}. As
5953 in the shell, an initial @samp{.} in a file name does not match a
5954 wildcard at the start of @var{pattern}. Sometimes it is useful
5955 to give this option several times. For example,
5958 $ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*'
5961 The first option ignores names of length 3 or more that start with @samp{.},
5962 the second ignores all two-character names that start with @samp{.}
5963 except @samp{..}, and the third ignores names that start with @samp{#}.
5966 @itemx --dereference
5968 @opindex --dereference
5969 @cindex symbolic links, dereferencing
5970 When showing file information for a symbolic link, show information
5971 for the file the link references rather than the link itself.
5972 However, even with this option, @command{ls} still prints the name
5973 of the link itself, not the name of the file that the link points to.
5978 @opindex --recursive
5979 @cindex recursive directory listing
5980 @cindex directory listing, recursive
5981 List the contents of all directories recursively.
5986 @node What information is listed
5987 @subsection What information is listed
5989 These options affect the information that @command{ls} displays. By
5990 default, only file names are shown.
5996 @cindex hurd, author, printing
5997 List each file's author when producing long format directory listings.
5998 In GNU/Hurd, file authors can differ from their owners, but in other
5999 operating systems the two are the same.
6005 @cindex dired Emacs mode support
6006 With the long listing (@option{-l}) format, print an additional line after
6010 //DIRED// @var{beg1} @var{end1} @var{beg2} @var{end2} @dots{}
6014 The @var{begN} and @var{endN} are unsigned integers that record the
6015 byte position of the beginning and end of each file name in the output.
6016 This makes it easy for Emacs to find the names, even when they contain
6017 unusual characters such as space or newline, without fancy searching.
6019 If directories are being listed recursively (@option{-R}), output a similar
6020 line with offsets for each subdirectory name:
6023 //SUBDIRED// @var{beg1} @var{end1} @dots{}
6026 Finally, output a line of the form:
6029 //DIRED-OPTIONS// --quoting-style=@var{word}
6033 where @var{word} is the quoting style (@pxref{Formatting the file names}).
6035 Here is an actual example:
6038 $ mkdir -p a/sub/deeper a/sub2
6040 $ touch a/sub/deeper/file
6041 $ ls -gloRF --dired a
6044 -rw-r--r-- 1 0 Jun 10 12:27 f1
6045 -rw-r--r-- 1 0 Jun 10 12:27 f2
6046 drwxr-xr-x 3 4096 Jun 10 12:27 sub/
6047 drwxr-xr-x 2 4096 Jun 10 12:27 sub2/
6051 drwxr-xr-x 2 4096 Jun 10 12:27 deeper/
6055 -rw-r--r-- 1 0 Jun 10 12:27 file
6059 //DIRED// 48 50 84 86 120 123 158 162 217 223 282 286
6060 //SUBDIRED// 2 3 167 172 228 240 290 296
6061 //DIRED-OPTIONS// --quoting-style=literal
6064 Note that the pairs of offsets on the @samp{//DIRED//} line above delimit
6065 these names: @file{f1}, @file{f2}, @file{sub}, @file{sub2}, @file{deeper},
6067 The offsets on the @samp{//SUBDIRED//} line delimit the following
6068 directory names: @file{a}, @file{a/sub}, @file{a/sub/deeper}, @file{a/sub2}.
6070 Here is an example of how to extract the fifth entry name, @samp{deeper},
6071 corresponding to the pair of offsets, 222 and 228:
6074 $ ls -gloRF --dired a > out
6075 $ dd bs=1 skip=222 count=6 < out 2>/dev/null; echo
6079 Note that although the listing above includes a trailing slash
6080 for the @samp{deeper} entry, the offsets select the name without
6081 the trailing slash. However, if you invoke @command{ls} with @option{--dired}
6082 along with an option like @option{--escape} (aka @option{-b}) and operate
6083 on a file whose name contains special characters, notice that the backslash
6088 $ ls -blog --dired 'a b'
6089 -rw-r--r-- 1 0 Jun 10 12:28 a\ b
6091 //DIRED-OPTIONS// --quoting-style=escape
6094 If you use a quoting style that adds quote marks
6095 (e.g., @option{--quoting-style=c}), then the offsets include the quote marks.
6096 So beware that the user may select the quoting style via the environment
6097 variable @env{QUOTING_STYLE}. Hence, applications using @option{--dired}
6098 should either specify an explicit @option{--quoting-style=literal} option
6099 (aka @option{-N} or @option{--literal}) on the command line, or else be
6100 prepared to parse the escaped names.
6103 @opindex --full-time
6104 Produce long format directory listings, and list times in full. It is
6105 equivalent to using @option{--format=long} with
6106 @option{--time-style=full-iso} (@pxref{Formatting file timestamps}).
6110 Produce long format directory listings, but don't display owner information.
6116 Inhibit display of group information in a long format directory listing.
6117 (This is the default in some non-@sc{gnu} versions of @command{ls}, so we
6118 provide this option for compatibility.)
6126 @cindex inode number, printing
6127 Print the inode number (also called the file serial number and index
6128 number) of each file to the left of the file name. (This number
6129 uniquely identifies each file within a particular file system.)
6132 @itemx --format=long
6133 @itemx --format=verbose
6136 @opindex long ls @r{format}
6137 @opindex verbose ls @r{format}
6138 In addition to the name of each file, print the file type, file mode bits,
6139 number of hard links, owner name, group name, size, and
6140 timestamp (@pxref{Formatting file timestamps}), normally
6141 the modification time. Print question marks for information that
6142 cannot be determined.
6144 Normally the size is printed as a byte count without punctuation, but
6145 this can be overridden (@pxref{Block size}). For example, @option{-h}
6146 prints an abbreviated, human-readable count, and
6147 @samp{--block-size="'1"} prints a byte count with the thousands
6148 separator of the current locale.
6150 For each directory that is listed, preface the files with a line
6151 @samp{total @var{blocks}}, where @var{blocks} is the total disk allocation
6152 for all files in that directory. The block size currently defaults to 1024
6153 bytes, but this can be overridden (@pxref{Block size}).
6154 The @var{blocks} computed counts each hard link separately;
6155 this is arguably a deficiency.
6157 The file type is one of the following characters:
6159 @c The commented-out entries are ones we're not sure about.
6167 character special file
6169 high performance (``contiguous data'') file
6173 door (Solaris 2.5 and up)
6175 @c semaphore, if this is a distinct file type
6179 @c multiplexed file (7th edition Unix; obsolete)
6181 off-line (``migrated'') file (Cray DMF)
6183 network special file (HP-UX)
6187 port (Solaris 10 and up)
6189 @c message queue, if this is a distinct file type
6193 @c shared memory object, if this is a distinct file type
6195 @c typed memory object, if this is a distinct file type
6197 @c whiteout (4.4BSD; not implemented)
6199 some other file type
6202 @cindex permissions, output by @command{ls}
6203 The file mode bits listed are similar to symbolic mode specifications
6204 (@pxref{Symbolic Modes}). But @command{ls} combines multiple bits into the
6205 third character of each set of permissions as follows:
6209 If the set-user-ID or set-group-ID bit and the corresponding executable bit
6213 If the set-user-ID or set-group-ID bit is set but the corresponding
6214 executable bit is not set.
6217 If the restricted deletion flag or sticky bit, and the
6218 other-executable bit, are both set. The restricted deletion flag is
6219 another name for the sticky bit. @xref{Mode Structure}.
6222 If the restricted deletion flag or sticky bit is set but the
6223 other-executable bit is not set.
6226 If the executable bit is set and none of the above apply.
6232 Following the file mode bits is a single character that specifies
6233 whether an alternate access method such as an access control list
6234 applies to the file. When the character following the file mode bits is a
6235 space, there is no alternate access method. When it is a printing
6236 character, then there is such a method.
6238 For a file with an extended access control list, a @samp{+} character is
6239 listed. Basic access control lists are equivalent to the permissions
6240 listed, and are not considered an alternate access method.
6243 @itemx --numeric-uid-gid
6245 @opindex --numeric-uid-gid
6246 @cindex numeric uid and gid
6247 @cindex numeric user and group IDs
6248 Produce long format directory listings, but
6249 display numeric user and group IDs instead of the owner and group names.
6253 Produce long format directory listings, but don't display group information.
6254 It is equivalent to using @option{--format=long} with @option{--no-group} .
6260 @cindex disk allocation
6261 @cindex size of files, reporting
6262 Print the disk allocation of each file to the left of the file name.
6263 This is the amount of disk space used by the file, which is usually a
6264 bit more than the file's size, but it can be less if the file has holes.
6266 Normally the disk allocation is printed in units of
6267 1024 bytes, but this can be overridden (@pxref{Block size}).
6269 @cindex NFS mounts from BSD to HP-UX
6270 For files that are NFS-mounted from an HP-UX system to a BSD system,
6271 this option reports sizes that are half the correct values. On HP-UX
6272 systems, it reports sizes that are twice the correct values for files
6273 that are NFS-mounted from BSD systems. This is due to a flaw in HP-UX;
6274 it also affects the HP-UX @command{ls} program.
6281 @node Sorting the output
6282 @subsection Sorting the output
6284 @cindex sorting @command{ls} output
6285 These options change the order in which @command{ls} sorts the information
6286 it outputs. By default, sorting is done by character code
6287 (e.g., @acronym{ASCII} order).
6293 @itemx --time=status
6296 @opindex ctime@r{, printing or sorting by}
6297 @opindex status time@r{, printing or sorting by}
6298 @opindex use time@r{, printing or sorting files by}
6299 If the long listing format (e.g., @option{-l}, @option{-o}) is being used,
6300 print the status change time (the @samp{ctime} in the inode) instead of
6301 the modification time.
6302 When explicitly sorting by time (@option{--sort=time} or @option{-t})
6303 or when not using a long listing format,
6304 sort according to the status change time.
6308 @cindex unsorted directory listing
6309 @cindex directory order, listing by
6310 Primarily, like @option{-U}---do not sort; list the files in whatever
6311 order they are stored in the directory. But also enable @option{-a} (list
6312 all files) and disable @option{-l}, @option{--color}, and @option{-s} (if they
6313 were specified before the @option{-f}).
6319 @cindex reverse sorting
6320 Reverse whatever the sorting method is---e.g., list files in reverse
6321 alphabetical order, youngest first, smallest first, or whatever.
6327 @opindex size of files@r{, sorting files by}
6328 Sort by file size, largest first.
6334 @opindex modification time@r{, sorting files by}
6335 Sort by modification time (the @samp{mtime} in the inode), newest first.
6339 @itemx --time=access
6343 @opindex use time@r{, printing or sorting files by}
6344 @opindex atime@r{, printing or sorting files by}
6345 @opindex access time@r{, printing or sorting files by}
6346 If the long listing format (e.g., @option{--format=long}) is being used,
6347 print the last access time (the @samp{atime} in the inode).
6348 When explicitly sorting by time (@option{--sort=time} or @option{-t})
6349 or when not using a long listing format, sort according to the access time.
6355 @opindex none@r{, sorting option for @command{ls}}
6356 Do not sort; list the files in whatever order they are
6357 stored in the directory. (Do not do any of the other unrelated things
6358 that @option{-f} does.) This is especially useful when listing very large
6359 directories, since not doing any sorting can be noticeably faster.
6362 @itemx --sort=version
6365 @opindex version@r{, sorting option for @command{ls}}
6366 Sort by version name and number, lowest first. It behaves like a default
6367 sort, except that each sequence of decimal digits is treated numerically
6368 as an index/version number. (@xref{More details about version sort}.)
6371 @itemx --sort=extension
6374 @opindex extension@r{, sorting files by}
6375 Sort directory contents alphabetically by file extension (characters
6376 after the last @samp{.}); files with no extension are sorted first.
6381 @node More details about version sort
6382 @subsection More details about version sort
6384 The version sort takes into account the fact that file names frequently include
6385 indices or version numbers. Standard sorting functions usually do not produce
6386 the ordering that people expect because comparisons are made on a
6387 character-by-character basis. The version
6388 sort addresses this problem, and is especially useful when browsing
6389 directories that contain many files with indices/version numbers in their
6394 foo.zml-1.gz foo.zml-1.gz
6395 foo.zml-100.gz foo.zml-2.gz
6396 foo.zml-12.gz foo.zml-6.gz
6397 foo.zml-13.gz foo.zml-12.gz
6398 foo.zml-2.gz foo.zml-13.gz
6399 foo.zml-25.gz foo.zml-25.gz
6400 foo.zml-6.gz foo.zml-100.gz
6403 Note also that numeric parts with leading zeros are considered as
6408 abc-1.007.tgz abc-1.007.tgz
6409 abc-1.012b.tgz abc-1.01a.tgz
6410 abc-1.01a.tgz abc-1.012b.tgz
6413 This functionality is implemented using the @code{strverscmp} function.
6414 @xref{String/Array Comparison, , , libc, The GNU C Library Reference Manual}.
6415 One result of that implementation decision is that @code{ls -v} does not
6416 use the locale category, @env{LC_COLLATE}. As a result, non-numeric prefixes
6417 are sorted as if @env{LC_COLLATE} were set to @code{C}.
6419 @node General output formatting
6420 @subsection General output formatting
6422 These options affect the appearance of the overall output.
6427 @itemx --format=single-column
6430 @opindex single-column @r{output of files}
6431 List one file per line. This is the default for @command{ls} when standard
6432 output is not a terminal.
6435 @itemx --format=vertical
6438 @opindex vertical @r{sorted files in columns}
6439 List files in columns, sorted vertically. This is the default for
6440 @command{ls} if standard output is a terminal. It is always the default
6441 for the @command{dir} program.
6442 @sc{gnu} @command{ls} uses variable width columns to display as many files as
6443 possible in the fewest lines.
6445 @item --color [=@var{when}]
6447 @cindex color, distinguishing file types with
6448 Specify whether to use color for distinguishing file types. @var{when}
6449 may be omitted, or one of:
6452 @vindex none @r{color option}
6453 - Do not use color at all. This is the default.
6455 @vindex auto @r{color option}
6456 @cindex terminal, using color iff
6457 - Only use color if standard output is a terminal.
6459 @vindex always @r{color option}
6462 Specifying @option{--color} and no @var{when} is equivalent to
6463 @option{--color=always}.
6464 Piping a colorized listing through a pager like @command{more} or
6465 @command{less} usually produces unreadable results. However, using
6466 @code{more -f} does seem to work.
6470 @itemx --indicator-style=classify
6473 @opindex --indicator-style
6474 @cindex file type and executables, marking
6475 @cindex executables and file type, marking
6476 Append a character to each file name indicating the file type. Also,
6477 for regular files that are executable, append @samp{*}. The file type
6478 indicators are @samp{/} for directories, @samp{@@} for symbolic links,
6479 @samp{|} for FIFOs, @samp{=} for sockets, @samp{>} for doors,
6480 and nothing for regular files.
6481 @c The following sentence is the same as the one for -d.
6482 Do not follow symbolic links listed on the
6483 command line unless the @option{--dereference-command-line} (@option{-H}),
6484 @option{--dereference} (@option{-L}), or
6485 @option{--dereference-command-line-symlink-to-dir} options are specified.
6488 @itemx --indicator-style=file-type
6489 @opindex --file-type
6490 @opindex --indicator-style
6491 @cindex file type, marking
6492 Append a character to each file name indicating the file type. This is
6493 like @option{-F}, except that executables are not marked.
6495 @item --indicator-style=@var{word}
6496 @opindex --indicator-style
6497 Append a character indicator with style @var{word} to entry names,
6502 Do not append any character indicator; this is the default.
6504 Append @samp{/} for directories. This is the same as the @option{-p}
6507 Append @samp{/} for directories, @samp{@@} for symbolic links, @samp{|}
6508 for FIFOs, @samp{=} for sockets, and nothing for regular files. This is
6509 the same as the @option{--file-type} option.
6511 Append @samp{*} for executable regular files, otherwise behave as for
6512 @samp{file-type}. This is the same as the @option{-F} or
6513 @option{--classify} option.
6518 Print file sizes in 1024-byte blocks, overriding the default block
6519 size (@pxref{Block size}).
6520 This option is equivalent to @option{--block-size=1K}.
6523 @itemx --format=commas
6526 @opindex commas@r{, outputting between files}
6527 List files horizontally, with as many as will fit on each line,
6528 separated by @samp{, } (a comma and a space).
6531 @itemx --indicator-style=slash
6533 @opindex --indicator-style
6534 @cindex file type, marking
6535 Append a @samp{/} to directory names.
6538 @itemx --format=across
6539 @itemx --format=horizontal
6542 @opindex across@r{, listing files}
6543 @opindex horizontal@r{, listing files}
6544 List the files in columns, sorted horizontally.
6547 @itemx --tabsize=@var{cols}
6550 Assume that each tab stop is @var{cols} columns wide. The default is 8.
6551 @command{ls} uses tabs where possible in the output, for efficiency. If
6552 @var{cols} is zero, do not use tabs at all.
6554 @c FIXME: remove in 2009, if Apple Terminal has been fixed for long enough.
6555 Some terminal emulators (at least Apple Terminal 1.5 (133) from Mac OS X 10.4.8)
6556 do not properly align columns to the right of a TAB following a
6557 non-@acronym{ASCII} byte. If you use such a terminal emulator, use the
6558 @option{-T0} option or put @code{TABSIZE=0} in your environment to tell
6559 @command{ls} to align using spaces, not tabs.
6562 @itemx --width=@var{cols}
6566 Assume the screen is @var{cols} columns wide. The default is taken
6567 from the terminal settings if possible; otherwise the environment
6568 variable @env{COLUMNS} is used if it is set; otherwise the default
6574 @node Formatting file timestamps
6575 @subsection Formatting file timestamps
6577 By default, file timestamps are listed in abbreviated form. Most
6578 locales use a timestamp like @samp{2002-03-30 23:45}. However, the
6579 default @acronym{POSIX} locale uses a date like @samp{Mar 30@ @ 2002}
6580 for non-recent timestamps, and a date-without-year and time like
6581 @samp{Mar 30 23:45} for recent timestamps.
6583 A timestamp is considered to be @dfn{recent} if it is less than six
6584 months old, and is not dated in the future. If a timestamp dated
6585 today is not listed in recent form, the timestamp is in the future,
6586 which means you probably have clock skew problems which may break
6587 programs like @command{make} that rely on file timestamps.
6590 Time stamps are listed according to the time zone rules specified by
6591 the @env{TZ} environment variable, or by the system default rules if
6592 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
6593 with @env{TZ}, libc, The GNU C Library Reference Manual}.
6595 The following option changes how file timestamps are printed.
6598 @item --time-style=@var{style}
6599 @opindex --time-style
6601 List timestamps in style @var{style}. The @var{style} should
6602 be one of the following:
6607 List timestamps using @var{format}, where @var{format} is interpreted
6608 like the format argument of @command{date} (@pxref{date invocation}).
6609 For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes
6610 @command{ls} to list timestamps like @samp{2002-03-30 23:45:56}. As
6611 with @command{date}, @var{format}'s interpretation is affected by the
6612 @env{LC_TIME} locale category.
6614 If @var{format} contains two format strings separated by a newline,
6615 the former is used for non-recent files and the latter for recent
6616 files; if you want output columns to line up, you may need to insert
6617 spaces in one of the two formats.
6620 List timestamps in full using @acronym{ISO} 8601 date, time, and time zone
6621 format with nanosecond precision, e.g., @samp{2002-03-30
6622 23:45:56.477817180 -0700}. This style is equivalent to
6623 @samp{+%Y-%m-%d %H:%M:%S.%N %z}.
6625 This is useful because the time output includes all the information that
6626 is available from the operating system. For example, this can help
6627 explain @command{make}'s behavior, since @acronym{GNU} @command{make}
6628 uses the full timestamp to determine whether a file is out of date.
6631 List @acronym{ISO} 8601 date and time in minutes, e.g.,
6632 @samp{2002-03-30 23:45}. These timestamps are shorter than
6633 @samp{full-iso} timestamps, and are usually good enough for everyday
6634 work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}.
6637 List @acronym{ISO} 8601 dates for non-recent timestamps (e.g.,
6638 @samp{2002-03-30@ }), and @acronym{ISO} 8601 month, day, hour, and
6639 minute for recent timestamps (e.g., @samp{03-30 23:45}). These
6640 timestamps are uglier than @samp{long-iso} timestamps, but they carry
6641 nearly the same information in a smaller space and their brevity helps
6642 @command{ls} output fit within traditional 80-column output lines.
6643 The following two @command{ls} invocations are equivalent:
6648 ls -l --time-style="+%Y-%m-%d $newline%m-%d %H:%M"
6649 ls -l --time-style="iso"
6654 List timestamps in a locale-dependent form. For example, a Finnish
6655 locale might list non-recent timestamps like @samp{maalis 30@ @ 2002}
6656 and recent timestamps like @samp{maalis 30 23:45}. Locale-dependent
6657 timestamps typically consume more space than @samp{iso} timestamps and
6658 are harder for programs to parse because locale conventions vary so
6659 widely, but they are easier for many people to read.
6661 The @env{LC_TIME} locale category specifies the timestamp format. The
6662 default @acronym{POSIX} locale uses timestamps like @samp{Mar 30@
6663 @ 2002} and @samp{Mar 30 23:45}; in this locale, the following two
6664 @command{ls} invocations are equivalent:
6669 ls -l --time-style="+%b %e %Y$newline%b %e %H:%M"
6670 ls -l --time-style="locale"
6673 Other locales behave differently. For example, in a German locale,
6674 @option{--time-style="locale"} might be equivalent to
6675 @option{--time-style="+%e. %b %Y $newline%e. %b %H:%M"}
6676 and might generate timestamps like @samp{30. M@"ar 2002@ } and
6677 @samp{30. M@"ar 23:45}.
6679 @item posix-@var{style}
6681 List @acronym{POSIX}-locale timestamps if the @env{LC_TIME} locale
6682 category is @acronym{POSIX}, @var{style} timestamps otherwise. For
6683 example, the @samp{posix-long-iso} style lists
6684 timestamps like @samp{Mar 30@ @ 2002} and @samp{Mar 30 23:45} when in
6685 the @acronym{POSIX} locale, and like @samp{2002-03-30 23:45} otherwise.
6690 You can specify the default value of the @option{--time-style} option
6691 with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set
6692 the default style is @samp{locale}. @acronym{GNU} Emacs 21.3 and
6693 later use the @option{--dired} option and therefore can parse any date
6694 format, but if you are using Emacs 21.1 or 21.2 and specify a
6695 non-@acronym{POSIX} locale you may need to set
6696 @samp{TIME_STYLE="posix-long-iso"}.
6698 To avoid certain denial-of-service attacks, timestamps that would be
6699 longer than 1000 bytes may be treated as errors.
6702 @node Formatting the file names
6703 @subsection Formatting the file names
6705 These options change how file names themselves are printed.
6711 @itemx --quoting-style=escape
6714 @opindex --quoting-style
6715 @cindex backslash sequences for file names
6716 Quote nongraphic characters in file names using alphabetic and octal
6717 backslash sequences like those used in C.
6721 @itemx --quoting-style=literal
6724 @opindex --quoting-style
6725 Do not quote file names. However, with @command{ls} nongraphic
6726 characters are still printed as question marks if the output is a
6727 terminal and you do not specify the @option{--show-control-chars}
6731 @itemx --hide-control-chars
6733 @opindex --hide-control-chars
6734 Print question marks instead of nongraphic characters in file names.
6735 This is the default if the output is a terminal and the program is
6740 @itemx --quoting-style=c
6742 @opindex --quote-name
6743 @opindex --quoting-style
6744 Enclose file names in double quotes and quote nongraphic characters as
6747 @item --quoting-style=@var{word}
6748 @opindex --quoting-style
6749 @cindex quoting style
6750 Use style @var{word} to quote file names and other strings that may
6751 contain arbitrary characters. The @var{word} should
6752 be one of the following:
6756 Output strings as-is; this is the same as the @option{-N} or
6757 @option{--literal} option.
6759 Quote strings for the shell if they contain shell metacharacters or would
6760 cause ambiguous output.
6761 The quoting is suitable for @acronym{POSIX}-compatible shells like
6762 @command{bash}, but it does not always work for incompatible shells
6765 Quote strings for the shell, even if they would normally not require quoting.
6767 Quote strings as for C character string literals, including the
6768 surrounding double-quote characters; this is the same as the
6769 @option{-Q} or @option{--quote-name} option.
6771 Quote strings as for C character string literals, except omit the
6772 surrounding double-quote
6773 characters; this is the same as the @option{-b} or @option{--escape} option.
6775 Quote strings as for C character string literals, except use
6776 surrounding quotation marks appropriate for the
6779 @c Use @t instead of @samp to avoid duplicate quoting in some output styles.
6780 Quote strings as for C character string literals, except use
6781 surrounding quotation marks appropriate for the locale, and quote
6782 @t{`like this'} instead of @t{"like
6783 this"} in the default C locale. This looks nicer on many displays.
6786 You can specify the default value of the @option{--quoting-style} option
6787 with the environment variable @env{QUOTING_STYLE}. If that environment
6788 variable is not set, the default value is @samp{literal}, but this
6789 default may change to @samp{shell} in a future version of this package.
6791 @item --show-control-chars
6792 @opindex --show-control-chars
6793 Print nongraphic characters as-is in file names.
6794 This is the default unless the output is a terminal and the program is
6800 @node dir invocation
6801 @section @command{dir}: Briefly list directory contents
6804 @cindex directory listing, brief
6806 @command{dir} is equivalent to @code{ls -C
6807 -b}; that is, by default files are listed in columns, sorted vertically,
6808 and special characters are represented by backslash escape sequences.
6810 @xref{ls invocation, @command{ls}}.
6813 @node vdir invocation
6814 @section @command{vdir}: Verbosely list directory contents
6817 @cindex directory listing, verbose
6819 @command{vdir} is equivalent to @code{ls -l
6820 -b}; that is, by default files are listed in long format and special
6821 characters are represented by backslash escape sequences.
6823 @node dircolors invocation
6824 @section @command{dircolors}: Color setup for @command{ls}
6828 @cindex setup for color
6830 @command{dircolors} outputs a sequence of shell commands to set up the
6831 terminal for color output from @command{ls} (and @command{dir}, etc.).
6835 eval "`dircolors [@var{option}]@dots{} [@var{file}]`"
6838 If @var{file} is specified, @command{dircolors} reads it to determine which
6839 colors to use for which file types and extensions. Otherwise, a
6840 precompiled database is used. For details on the format of these files,
6841 run @samp{dircolors --print-database}.
6844 @vindex SHELL @r{environment variable, and color}
6845 The output is a shell command to set the @env{LS_COLORS} environment
6846 variable. You can specify the shell syntax to use on the command line,
6847 or @command{dircolors} will guess it from the value of the @env{SHELL}
6848 environment variable.
6850 The program accepts the following options. Also see @ref{Common options}.
6855 @itemx --bourne-shell
6858 @opindex --bourne-shell
6859 @cindex Bourne shell syntax for color setup
6860 @cindex @command{sh} syntax for color setup
6861 Output Bourne shell commands. This is the default if the @env{SHELL}
6862 environment variable is set and does not end with @samp{csh} or
6871 @cindex C shell syntax for color setup
6872 @cindex @command{csh} syntax for color setup
6873 Output C shell commands. This is the default if @code{SHELL} ends with
6874 @command{csh} or @command{tcsh}.
6877 @itemx --print-database
6879 @opindex --print-database
6880 @cindex color database, printing
6881 @cindex database for color setup, printing
6882 @cindex printing color database
6883 Print the (compiled-in) default color configuration database. This
6884 output is itself a valid configuration file, and is fairly descriptive
6885 of the possibilities.
6892 @node Basic operations
6893 @chapter Basic operations
6895 @cindex manipulating files
6897 This chapter describes the commands for basic file manipulation:
6898 copying, moving (renaming), and deleting (removing).
6901 * cp invocation:: Copy files.
6902 * dd invocation:: Convert and copy a file.
6903 * install invocation:: Copy files and set attributes.
6904 * mv invocation:: Move (rename) files.
6905 * rm invocation:: Remove files or directories.
6906 * shred invocation:: Remove files more securely.
6911 @section @command{cp}: Copy files and directories
6914 @cindex copying files and directories
6915 @cindex files, copying
6916 @cindex directories, copying
6918 @command{cp} copies files (or, optionally, directories). The copy is
6919 completely independent of the original. You can either copy one file to
6920 another, or copy arbitrarily many files to a destination directory.
6924 cp [@var{option}]@dots{} [-T] @var{source} @var{dest}
6925 cp [@var{option}]@dots{} @var{source}@dots{} @var{directory}
6926 cp [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
6931 If two file names are given, @command{cp} copies the first file to the
6935 If the @option{--target-directory} (@option{-t}) option is given, or
6936 failing that if the last file is a directory and the
6937 @option{--no-target-directory} (@option{-T}) option is not given,
6938 @command{cp} copies each @var{source} file to the specified directory,
6939 using the @var{source}s' names.
6942 Generally, files are written just as they are read. For exceptions,
6943 see the @option{--sparse} option below.
6945 By default, @command{cp} does not copy directories. However, the
6946 @option{-R}, @option{-a}, and @option{-r} options cause @command{cp} to
6947 copy recursively by descending into source directories and copying files
6948 to corresponding destination directories.
6950 When copying from a symbolic link, @command{cp} normally follows the
6951 link only when not copying
6952 recursively. This default can be overridden with the
6953 @option{--archive} (@option{-a}), @option{-d}, @option{--dereference}
6954 (@option{-L}), @option{--no-dereference} (@option{-P}), and
6955 @option{-H} options. If more than one of these options is specified,
6956 the last one silently overrides the others.
6958 When copying to a symbolic link, @command{cp} follows the
6959 link only when it refers to an existing regular file.
6960 However, when copying to a dangling symbolic link, @command{cp}
6961 refuses by default, and fails with a diagnostic, since the operation
6962 is inherently dangerous. This behavior is contrary to historical
6963 practice and to @acronym{POSIX}.
6964 Set @env{POSIXLY_CORRECT} to make @command{cp} attempt to create
6965 the target of a dangling destination symlink, in spite of the possible risk.
6966 Also, when an option like
6967 @option{--backup} or @option{--link} acts to rename or remove the
6968 destination before copying, @command{cp} renames or removes the
6969 symbolic link rather than the file it points to.
6971 By default, @command{cp} copies the contents of special files only
6972 when not copying recursively. This default can be overridden with the
6973 @option{--copy-contents} option.
6975 @cindex self-backups
6976 @cindex backups, making only
6977 @command{cp} generally refuses to copy a file onto itself, with the
6978 following exception: if @option{--force --backup} is specified with
6979 @var{source} and @var{dest} identical, and referring to a regular file,
6980 @command{cp} will make a backup file, either regular or numbered, as
6981 specified in the usual ways (@pxref{Backup options}). This is useful when
6982 you simply want to make a backup of an existing file before changing it.
6984 The program accepts the following options. Also see @ref{Common options}.
6991 Preserve as much as possible of the structure and attributes of the
6992 original files in the copy (but do not attempt to preserve internal
6993 directory structure; i.e., @samp{ls -U} may list the entries in a copied
6994 directory in a different order).
6995 Equivalent to @option{-dpR}.
6998 @itemx @w{@kbd{--backup}[=@var{method}]}
7001 @vindex VERSION_CONTROL
7002 @cindex backups, making
7003 @xref{Backup options}.
7004 Make a backup of each file that would otherwise be overwritten or removed.
7005 As a special case, @command{cp} makes a backup of @var{source} when the force
7006 and backup options are given and @var{source} and @var{dest} are the same
7007 name for an existing, regular file. One useful application of this
7008 combination of options is this tiny Bourne shell script:
7012 # Usage: backup FILE...
7013 # Create a @sc{gnu}-style backup of each listed FILE.
7015 cp --backup --force -- "$i" "$i"
7019 @item --copy-contents
7020 @cindex directories, copying recursively
7021 @cindex copying directories recursively
7022 @cindex recursively copying directories
7023 @cindex non-directories, copying as special files
7024 If copying recursively, copy the contents of any special files (e.g.,
7025 FIFOs and device files) as if they were regular files. This means
7026 trying to read the data in each source file and writing it to the
7027 destination. It is usually a mistake to use this option, as it
7028 normally has undesirable effects on special files like FIFOs and the
7029 ones typically found in the @file{/dev} directory. In most cases,
7030 @code{cp -R --copy-contents} will hang indefinitely trying to read
7031 from FIFOs and special files like @file{/dev/console}, and it will
7032 fill up your destination disk if you use it to copy @file{/dev/zero}.
7033 This option has no effect unless copying recursively, and it does not
7034 affect the copying of symbolic links.
7038 @cindex symbolic links, copying
7039 @cindex hard links, preserving
7040 Copy symbolic links as symbolic links rather than copying the files that
7041 they point to, and preserve hard links between source files in the copies.
7042 Equivalent to @option{--no-dereference --preserve=links}.
7048 When copying without this option and an existing destination file cannot
7049 be opened for writing, the copy fails. However, with @option{--force}),
7050 when a destination file cannot be opened, @command{cp} then removes it and
7051 tries to open it again. Contrast this behavior with that enabled by
7052 @option{--link} and @option{--symbolic-link}, whereby the destination file
7053 is never opened but rather is removed unconditionally. Also see the
7054 description of @option{--remove-destination}.
7056 This option is independent of the @option{--interactive} or
7057 @option{-i} option: neither cancels the effect of the other.
7061 If a command line argument specifies a symbolic link, then copy the
7062 file it points to rather than the symbolic link itself. However,
7063 copy (preserving its nature) any symbolic link that is encountered
7064 via recursive traversal.
7067 @itemx --interactive
7069 @opindex --interactive
7070 When copying a file other than a directory, prompt whether to
7071 overwrite an existing destination file.
7077 Make hard links instead of copies of non-directories.
7080 @itemx --dereference
7082 @opindex --dereference
7083 Follow symbolic links when copying from them.
7086 @itemx --no-dereference
7088 @opindex --no-dereference
7089 @cindex symbolic links, copying
7090 Copy symbolic links as symbolic links rather than copying the files that
7091 they point to. This option affects only symbolic links in the source;
7092 symbolic links in the destination are always followed if possible.
7095 @itemx @w{@kbd{--preserve}[=@var{attribute_list}]}
7098 @cindex file information, preserving
7099 Preserve the specified attributes of the original files.
7100 If specified, the @var{attribute_list} must be a comma-separated list
7101 of one or more of the following strings:
7105 Preserve the file mode bits and access control lists.
7107 Preserve the owner and group. On most modern systems,
7108 only users with appropriate privileges may change the owner of a file,
7110 may preserve the group ownership of a file only if they happen to be
7111 a member of the desired group.
7113 Preserve the times of last access and last modification, when possible.
7114 In general, it is not possible to preserve these attributes
7115 when the affected file is a symbolic link.
7116 However, FreeBSD now provides the @code{lutimes} function, which makes
7117 it possible even for symbolic links. However, this implementation does
7118 not yet take advantage of that.
7119 @c FIXME: once we provide lutimes support, update the above.
7121 Preserve in the destination files
7122 any links between corresponding source files.
7123 @c Give examples illustrating how hard links are preserved.
7124 @c Also, show how soft links map to hard links with -L and -H.
7126 Preserve all file attributes.
7127 Equivalent to specifying all of the above.
7130 Using @option{--preserve} with no @var{attribute_list} is equivalent
7131 to @option{--preserve=mode,ownership,timestamps}.
7133 In the absence of this option, each destination file is created with the
7134 mode bits of the corresponding source file, minus the bits set in the
7135 umask and minus the set-user-ID and set-group-ID bits.
7136 @xref{File permissions}.
7138 @itemx @w{@kbd{--no-preserve}=@var{attribute_list}}
7139 @cindex file information, preserving
7140 Do not preserve the specified attributes. The @var{attribute_list}
7141 has the same form as for @option{--preserve}.
7145 @cindex parent directories and @command{cp}
7146 Form the name of each destination file by appending to the target
7147 directory a slash and the specified name of the source file. The last
7148 argument given to @command{cp} must be the name of an existing directory.
7149 For example, the command:
7152 cp --parents a/b/c existing_dir
7156 copies the file @file{a/b/c} to @file{existing_dir/a/b/c}, creating
7157 any missing intermediate directories.
7159 @itemx @w{@kbd{--reply}=@var{how}}
7161 @cindex interactivity
7162 @c FIXME: remove in 2008
7163 @strong{Deprecated: to be removed in 2008.}@*
7164 Using @option{--reply=yes} makes @command{cp} act as if @samp{yes} were
7165 given as a response to every prompt about a destination file. That effectively
7166 cancels any preceding @option{--interactive} or @option{-i} option.
7167 Specify @option{--reply=no} to make @command{cp} act as if @samp{no} were
7168 given as a response to every prompt about a destination file.
7169 Specify @option{--reply=query} to make @command{cp} prompt the user
7170 about each existing destination file.
7177 @opindex --recursive
7178 @cindex directories, copying recursively
7179 @cindex copying directories recursively
7180 @cindex recursively copying directories
7181 @cindex non-directories, copying as special files
7182 Copy directories recursively. By default, do not follow symbolic
7183 links in the source; see the @option{--archive} (@option{-a}), @option{-d},
7184 @option{--dereference} (@option{-L}), @option{--no-dereference}
7185 (@option{-P}), and @option{-H} options. Special files are copied by
7186 creating a destination file of the same type as the source; see the
7187 @option{--copy-contents} option. It is not portable to use
7188 @option{-r} to copy symbolic links or special files. On some
7189 non-@sc{gnu} systems, @option{-r} implies the equivalent of
7190 @option{-L} and @option{--copy-contents} for historical reasons.
7191 Also, it is not portable to use @option{-R} to copy symbolic links
7192 unless you also specify @option{-P}, as @acronym{POSIX} allows
7193 implementations that dereference symbolic links by default.
7195 @item --remove-destination
7196 @opindex --remove-destination
7197 Remove each existing destination file before attempting to open it
7198 (contrast with @option{-f} above).
7200 @item --sparse=@var{when}
7201 @opindex --sparse=@var{when}
7202 @cindex sparse files, copying
7203 @cindex holes, copying files with
7204 @findex read @r{system call, and holes}
7205 A @dfn{sparse file} contains @dfn{holes}---a sequence of zero bytes that
7206 does not occupy any physical disk blocks; the @samp{read} system call
7207 reads these as zeros. This can both save considerable disk space and
7208 increase speed, since many binary files contain lots of consecutive zero
7209 bytes. By default, @command{cp} detects holes in input source files via a crude
7210 heuristic and makes the corresponding output file sparse as well.
7211 Only regular files may be sparse.
7213 The @var{when} value can be one of the following:
7217 The default behavior: if the input file is sparse, attempt to make
7218 the output file sparse, too. However, if an output file exists but
7219 refers to a non-regular file, then do not attempt to make it sparse.
7222 For each sufficiently long sequence of zero bytes in the input file,
7223 attempt to create a corresponding hole in the output file, even if the
7224 input file does not appear to be sparse.
7225 This is useful when the input file resides on a file system
7226 that does not support sparse files
7227 (for example, @samp{efs} file systems in SGI IRIX 5.3 and earlier),
7228 but the output file is on a type of file system that does support them.
7229 Holes may be created only in regular files, so if the destination file
7230 is of some other type, @command{cp} does not even try to make it sparse.
7233 Never make the output file sparse.
7234 This is useful in creating a file for use with the @command{mkswap} command,
7235 since such a file must not have any holes.
7238 @optStripTrailingSlashes
7241 @itemx --symbolic-link
7243 @opindex --symbolic-link
7244 @cindex symbolic links, copying with
7245 Make symbolic links instead of copies of non-directories. All source
7246 file names must be absolute (starting with @samp{/}) unless the
7247 destination files are in the current directory. This option merely
7248 results in an error message on systems that do not support symbolic links.
7254 @optNoTargetDirectory
7260 @cindex newer files, copying only
7261 Do not copy a non-directory that has an existing destination with the
7262 same or newer modification time. If time stamps are being preserved,
7263 the comparison is to the source time stamp truncated to the
7264 resolutions of the destination file system and of the system calls
7265 used to update time stamps; this avoids duplicate work if several
7266 @samp{cp -pu} commands are executed with the same source and
7273 Print the name of each file before copying it.
7276 @itemx --one-file-system
7278 @opindex --one-file-system
7279 @cindex file systems, omitting copying to different
7280 Skip subdirectories that are on different file systems from the one that
7281 the copy started on.
7282 However, mount point directories @emph{are} copied.
7290 @section @command{dd}: Convert and copy a file
7293 @cindex converting while copying a file
7295 @command{dd} copies a file (from standard input to standard output, by
7296 default) with a changeable I/O block size, while optionally performing
7297 conversions on it. Synopses:
7300 dd [@var{operand}]@dots{}
7304 The only options are @option{--help} and @option{--version}.
7305 @xref{Common options}. @command{dd} accepts the following operands.
7311 Read from @var{file} instead of standard input.
7315 Write to @var{file} instead of standard output. Unless
7316 @samp{conv=notrunc} is given, @command{dd} truncates @var{file} to zero
7317 bytes (or the size specified with @samp{seek=}).
7319 @item ibs=@var{bytes}
7321 @cindex block size of input
7322 @cindex input block size
7323 Set the input block size to @var{bytes}.
7324 This makes @command{dd} read @var{bytes} per block.
7326 @item obs=@var{bytes}
7328 @cindex block size of output
7329 @cindex output block size
7330 Set the output block size to @var{bytes}.
7331 This makes @command{dd} write @var{bytes} per block.
7333 @item bs=@var{bytes}
7336 Set both input and output block sizes to @var{bytes}.
7337 This makes @command{dd} read and write @var{bytes} per block,
7338 overriding any @samp{ibs} and @samp{obs} settings.
7340 @item cbs=@var{bytes}
7342 @cindex block size of conversion
7343 @cindex conversion block size
7344 @cindex fixed-length records, converting to variable-length
7345 @cindex variable-length records, converting to fixed-length
7346 Set the conversion block size to @var{bytes}.
7347 When converting variable-length records to fixed-length ones
7348 (@option{conv=block}) or the reverse (@option{conv=unblock}),
7349 use @var{bytes} as the fixed record length.
7351 @item skip=@var{blocks}
7353 Skip @var{blocks} @samp{ibs}-byte blocks in the input file before copying.
7355 @item seek=@var{blocks}
7357 Skip @var{blocks} @samp{obs}-byte blocks in the output file before copying.
7359 @item count=@var{blocks}
7361 Copy @var{blocks} @samp{ibs}-byte blocks from the input file, instead
7362 of everything until the end of the file.
7364 @item conv=@var{conversion}[,@var{conversion}]@dots{}
7366 Convert the file as specified by the @var{conversion} argument(s).
7367 (No spaces around any comma(s).)
7374 @opindex ascii@r{, converting to}
7375 Convert @acronym{EBCDIC} to @acronym{ASCII},
7376 using the conversion table specified by @acronym{POSIX}.
7377 This provides a 1:1 translation for all 256 bytes.
7380 @opindex ebcdic@r{, converting to}
7381 Convert @acronym{ASCII} to @acronym{EBCDIC}.
7382 This is the inverse of the @samp{ascii} conversion.
7385 @opindex alternate ebcdic@r{, converting to}
7386 Convert @acronym{ASCII} to alternate @acronym{EBCDIC},
7387 using the alternate conversion table specified by @acronym{POSIX}.
7388 This is not a 1:1 translation, but reflects common historical practice
7389 for @samp{~}, @samp{[}, and @samp{]}.
7391 The @samp{ascii}, @samp{ebcdic}, and @samp{ibm} conversions are
7395 @opindex block @r{(space-padding)}
7396 For each line in the input, output @samp{cbs} bytes, replacing the
7397 input newline with a space and padding with spaces as necessary.
7401 Replace trailing spaces in each @samp{cbs}-sized input block with a
7404 The @samp{block} and @samp{unblock} conversions are mutually exclusive.
7407 @opindex lcase@r{, converting to}
7408 Change uppercase letters to lowercase.
7411 @opindex ucase@r{, converting to}
7412 Change lowercase letters to uppercase.
7414 The @samp{lcase} and @samp{ucase} conversions are mutually exclusive.
7417 @opindex swab @r{(byte-swapping)}
7418 @cindex byte-swapping
7419 Swap every pair of input bytes. @sc{gnu} @command{dd}, unlike others, works
7420 when an odd number of bytes are read---the last byte is simply copied
7421 (since there is nothing to swap it with).
7425 @cindex read errors, ignoring
7426 Continue after read errors.
7430 @cindex creating output file, avoiding
7431 Do not create the output file; the output file must already exist.
7435 @cindex creating output file, requiring
7436 Fail if the output file already exists; @command{dd} must create the
7439 The @samp{excl} and @samp{nocreat} conversions are mutually exclusive.
7443 @cindex truncating output file, avoiding
7444 Do not truncate the output file.
7447 @opindex sync @r{(padding with nulls)}
7448 Pad every input block to size of @samp{ibs} with trailing zero bytes.
7449 When used with @samp{block} or @samp{unblock}, pad with spaces instead of
7454 @cindex synchronized data writes, before finishing
7455 Synchronize output data just before finishing. This forces a physical
7456 write of output data.
7460 @cindex synchronized data and metadata writes, before finishing
7461 Synchronize output data and metadata just before finishing. This
7462 forces a physical write of output data and metadata.
7466 @item iflag=@var{flag}[,@var{flag}]@dots{}
7468 Access the input file using the flags specified by the @var{flag}
7469 argument(s). (No spaces around any comma(s).)
7471 @item oflag=@var{flag}[,@var{flag}]@dots{}
7473 Access the output file using the flags specified by the @var{flag}
7474 argument(s). (No spaces around any comma(s).)
7476 Here are the flags. Not every flag is supported on every operating
7483 @cindex appending to the output file
7484 Write in append mode, so that even if some other process is writing to
7485 this file, every @command{dd} write will append to the current
7486 contents of the file. This flag makes sense only for output.
7487 If you combine this flag with the @samp{of=@var{file}} operand,
7488 you should also specify @samp{conv=notrunc} unless you want the
7489 output file to be truncated before being appended to.
7494 Use direct I/O for data, avoiding the buffer cache.
7498 @cindex directory I/O
7500 Fail unless the file is a directory. Most operating systems do not
7501 allow I/O to a directory, so this flag has limited utility.
7505 @cindex synchronized data reads
7506 Use synchronized I/O for data. For the output file, this forces a
7507 physical write of output data on each write. For the input file,
7508 this flag can matter when reading from a remote file that has been
7509 written to synchronously by some other process. Metadata (e.g.,
7510 last-access and last-modified time) is not necessarily synchronized.
7514 @cindex synchronized data and metadata I/O
7515 Use synchronized I/O for both data and metadata.
7519 @cindex nonblocking I/O
7520 Use non-blocking I/O.
7525 Do not update the file's access time.
7526 Some older file systems silently ignore this flag, so it is a good
7527 idea to test it on your files before relying on it.
7531 @cindex controlling terminal
7532 Do not assign the file to be a controlling terminal for @command{dd}.
7533 This has no effect when the file is not a terminal.
7534 On many hosts (e.g., @acronym{GNU}/Linux hosts), this option has no effect
7539 @cindex symbolic links, following
7540 Do not follow symbolic links.
7545 Fail if the file has multiple hard links.
7550 Use binary I/O. This option has an effect only on nonstandard
7551 platforms that distinguish binary from text I/O.
7556 Use text I/O. Like @samp{binary}, this option has no effect on
7561 These flags are not supported on all systems, and @samp{dd} rejects
7562 attempts to use them when they are not supported. When reading from
7563 standard input or writing to standard output, the @samp{nofollow} and
7564 @samp{noctty} flags should not be specified, and the other flags
7565 (e.g., @samp{nonblock}) can affect how other processes behave with the
7566 affected file descriptors, even after @command{dd} exits.
7570 @cindex multipliers after numbers
7571 The numeric-valued strings above (@var{bytes} and @var{blocks}) can be
7572 followed by a multiplier: @samp{b}=512, @samp{c}=1,
7573 @samp{w}=2, @samp{x@var{m}}=@var{m}, or any of the
7574 standard block size suffixes like @samp{k}=1024 (@pxref{Block size}).
7576 Use different @command{dd} invocations to use different block sizes for
7577 skipping and I/O@. For example, the following shell commands copy data
7578 in 512 KiB blocks between a disk and a tape, but do not save or restore a
7579 4 KiB label at the start of the disk:
7582 disk=/dev/rdsk/c0t1d0s2
7585 # Copy all but the label from disk to tape.
7586 (dd bs=4k skip=1 count=0 && dd bs=512k) <$disk >$tape
7588 # Copy from tape back to disk, but leave the disk label alone.
7589 (dd bs=4k seek=1 count=0 && dd bs=512k) <$tape >$disk
7592 Sending an @samp{INFO} signal to a running @command{dd}
7593 process makes it print I/O statistics to standard error
7594 and then resume copying. In the example below,
7595 @command{dd} is run in the background to copy 10 million blocks.
7596 The @command{kill} command makes it output intermediate I/O statistics,
7597 and when @command{dd} completes normally or is killed by the
7598 @code{SIGINT} signal, it outputs the final statistics.
7601 $ dd if=/dev/zero of=/dev/null count=10MB & pid=$!
7602 $ kill -s INFO $pid; wait $pid
7603 3385223+0 records in
7604 3385223+0 records out
7605 1733234176 bytes (1.7 GB) copied, 6.42173 seconds, 270 MB/s
7606 10000000+0 records in
7607 10000000+0 records out
7608 5120000000 bytes (5.1 GB) copied, 18.913 seconds, 271 MB/s
7611 @vindex POSIXLY_CORRECT
7612 On systems lacking the @samp{INFO} signal @command{dd} responds to the
7613 @samp{USR1} signal instead, unless the @env{POSIXLY_CORRECT}
7614 environment variable is set.
7619 @node install invocation
7620 @section @command{install}: Copy files and set attributes
7623 @cindex copying files and setting attributes
7625 @command{install} copies files while setting their file mode bits and, if
7626 possible, their owner and group. Synopses:
7629 install [@var{option}]@dots{} [-T] @var{source} @var{dest}
7630 install [@var{option}]@dots{} @var{source}@dots{} @var{directory}
7631 install [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
7632 install [@var{option}]@dots{} -d @var{directory}@dots{}
7637 If two file names are given, @command{install} copies the first file to the
7641 If the @option{--target-directory} (@option{-t}) option is given, or
7642 failing that if the last file is a directory and the
7643 @option{--no-target-directory} (@option{-T}) option is not given,
7644 @command{install} copies each @var{source} file to the specified
7645 directory, using the @var{source}s' names.
7648 If the @option{--directory} (@option{-d}) option is given,
7649 @command{install} creates each @var{directory} and any missing parent
7650 directories. Parent directories are created with mode
7651 @samp{u=rwx,go=rx} (755), regardless of the @option{-m} option or the
7652 current umask. @xref{Directory Setuid and Setgid}, for how the
7653 set-user-ID and set-group-ID bits of parent directories are inherited.
7656 @cindex Makefiles, installing programs in
7657 @command{install} is similar to @command{cp}, but allows you to control the
7658 attributes of destination files. It is typically used in Makefiles to
7659 copy programs into their destination directories. It refuses to copy
7660 files onto themselves.
7662 The program accepts the following options. Also see @ref{Common options}.
7670 Ignored; for compatibility with old Unix versions of @command{install}.
7674 Create any missing parent directories of @var{dest},
7675 then copy @var{source} to @var{dest}.
7676 This option is ignored if a destination directory is specified
7677 via @option{--target-directory=DIR}.
7682 @opindex --directory
7683 @cindex directories, creating with given attributes
7684 @cindex parent directories, creating missing
7685 @cindex leading directories, creating missing
7686 Create any missing parent directories, giving them the default
7687 attributes. Then create each given directory, setting their owner,
7688 group and mode as given on the command line or to the defaults.
7690 @item -g @var{group}
7691 @itemx --group=@var{group}
7694 @cindex group ownership of installed files, setting
7695 Set the group ownership of installed files or directories to
7696 @var{group}. The default is the process's current group. @var{group}
7697 may be either a group name or a numeric group ID.
7700 @itemx --mode=@var{mode}
7703 @cindex permissions of installed files, setting
7704 Set the file mode bits for the installed file or directory to @var{mode},
7705 which can be either an octal number, or a symbolic mode as in
7706 @command{chmod}, with @samp{a=} (no access allowed to anyone) as the
7707 point of departure (@pxref{File permissions}).
7708 The default mode is @samp{u=rwx,go=rx,a-s}---read, write, and
7709 execute for the owner, read and execute for group and other, and with
7710 set-user-ID and set-group-ID disabled.
7711 This default is not quite the same as @samp{755}, since it disables
7712 instead of preserving set-user-ID and set-group-ID on directories.
7713 @xref{Directory Setuid and Setgid}.
7715 @item -o @var{owner}
7716 @itemx --owner=@var{owner}
7719 @cindex ownership of installed files, setting
7720 @cindex appropriate privileges
7721 @vindex root @r{as default owner}
7722 If @command{install} has appropriate privileges (is run as root), set the
7723 ownership of installed files or directories to @var{owner}. The default
7724 is @code{root}. @var{owner} may be either a user name or a numeric user
7728 @itemx --preserve-timestamps
7730 @opindex --preserve-timestamps
7731 @cindex timestamps of installed files, preserving
7732 Set the time of last access and the time of last modification of each
7733 installed file to match those of each corresponding original file.
7734 When a file is installed without this option, its last access and
7735 last modification times are both set to the time of installation.
7736 This option is useful if you want to use the last modification times
7737 of installed files to keep track of when they were last built as opposed
7738 to when they were last installed.
7744 @cindex symbol table information, stripping
7745 @cindex stripping symbol table information
7746 Strip the symbol tables from installed binary executables.
7752 @optNoTargetDirectory
7758 Print the name of each file before copying it.
7766 @section @command{mv}: Move (rename) files
7770 @command{mv} moves or renames files (or directories). Synopses:
7773 mv [@var{option}]@dots{} [-T] @var{source} @var{dest}
7774 mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
7775 mv [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
7780 If two file names are given, @command{mv} moves the first file to the
7784 If the @option{--target-directory} (@option{-t}) option is given, or
7785 failing that if the last file is a directory and the
7786 @option{--no-target-directory} (@option{-T}) option is not given,
7787 @command{mv} moves each @var{source} file to the specified
7788 directory, using the @var{source}s' names.
7791 @command{mv} can move any type of file from one file system to another.
7792 Prior to version @code{4.0} of the fileutils,
7793 @command{mv} could move only regular files between file systems.
7794 For example, now @command{mv} can move an entire directory hierarchy
7795 including special device files from one partition to another. It first
7796 uses some of the same code that's used by @code{cp -a} to copy the
7797 requested directories and files, then (assuming the copy succeeded)
7798 it removes the originals. If the copy fails, then the part that was
7799 copied to the destination partition is removed. If you were to copy
7800 three directories from one partition to another and the copy of the first
7801 directory succeeded, but the second didn't, the first would be left on
7802 the destination partition and the second and third would be left on the
7805 @cindex prompting, and @command{mv}
7806 If a destination file exists but is normally unwritable, standard input
7807 is a terminal, and the @option{-f} or @option{--force} option is not given,
7808 @command{mv} prompts the user for whether to replace the file. (You might
7809 own the file, or have write permission on its directory.) If the
7810 response is not affirmative, the file is skipped.
7812 @emph{Warning}: Avoid specifying a source name with a trailing slash,
7813 when it might be a symlink to a directory.
7814 Otherwise, @command{mv} may do something very surprising, since
7815 its behavior depends on the underlying rename system call.
7816 On modern Linux systems, it fails with @code{errno=ENOTDIR}.
7817 However, on other systems (at least FreeBSD 6.1 and Solaris 10) it silently
7818 renames not the symlink but rather the directory referenced by the symlink.
7819 @xref{Trailing slashes}.
7821 The program accepts the following options. Also see @ref{Common options}.
7831 @cindex prompts, omitting
7832 Do not prompt the user before removing a destination file.
7835 @itemx --interactive
7837 @opindex --interactive
7838 @cindex prompts, forcing
7839 Prompt whether to overwrite each existing destination file, regardless
7841 If the response is not affirmative, the file is skipped.
7843 @itemx @w{@kbd{--reply}=@var{how}}
7845 @cindex interactivity
7846 @c FIXME: remove in 2008
7847 @strong{Deprecated: to be removed in 2008.}@*
7848 Specifying @option{--reply=yes} is equivalent to using @option{--force}.
7849 Specify @option{--reply=no} to make @command{mv} act as if @samp{no} were
7850 given as a response to every prompt about a destination file.
7851 Specify @option{--reply=query} to make @command{mv} prompt the user
7852 about each existing destination file.
7853 Note that @option{--reply=no} has an effect only when @command{mv} would prompt
7854 without @option{-i} or equivalent, i.e., when a destination file exists and is
7855 not writable, standard input is a terminal, and no @option{-f} (or equivalent)
7856 option is specified.
7862 @cindex newer files, moving only
7863 Do not move a non-directory that has an existing destination with the
7864 same or newer modification time.
7865 If the move is across file system boundaries, the comparison is to the
7866 source time stamp truncated to the resolutions of the destination file
7867 system and of the system calls used to update time stamps; this avoids
7868 duplicate work if several @samp{mv -u} commands are executed with the
7869 same source and destination.
7875 Print the name of each file before moving it.
7877 @optStripTrailingSlashes
7883 @optNoTargetDirectory
7891 @section @command{rm}: Remove files or directories
7894 @cindex removing files or directories
7896 @command{rm} removes each given @var{file}. By default, it does not remove
7897 directories. Synopsis:
7900 rm [@var{option}]@dots{} [@var{file}]@dots{}
7903 @cindex prompting, and @command{rm}
7904 If the @option{-I} or @option{--interactive=once} option is given,
7905 and there are more than three files or the @option{-r}, @option{-R},
7906 or @option{--recursive} are given, then @command{rm} prompts the user
7907 for whether to proceed with the entire operation. If the response is
7908 not affirmative, the entire command is aborted.
7910 Otherwise, if a file is unwritable, standard input is a terminal, and
7911 the @option{-f} or @option{--force} option is not given, or the
7912 @option{-i} or @option{--interactive=always} option @emph{is} given,
7913 @command{rm} prompts the user for whether to remove the file.
7914 If the response is not affirmative, the file is skipped.
7916 Any attempt to remove a file whose last file name component is
7917 @file{.} or @file{..} is rejected without any prompting.
7919 @emph{Warning}: If you use @command{rm} to remove a file, it is usually
7920 possible to recover the contents of that file. If you want more assurance
7921 that the contents are truly unrecoverable, consider using @command{shred}.
7923 The program accepts the following options. Also see @ref{Common options}.
7931 Ignore nonexistent files and never prompt the user.
7932 Ignore any previous @option{--interactive} (@option{-i}) option.
7936 Prompt whether to remove each file.
7937 If the response is not affirmative, the file is skipped.
7938 Ignore any previous @option{--force} (@option{-f}) option.
7939 Equivalent to @option{--interactive=always}.
7943 Prompt once whether to proceed with the command, if more than three
7944 files are named or if a recursive removal is requested. Ignore any
7945 previous @option{--force} (@option{-f}) option. Equivalent to
7946 @option{--interactive=once}.
7948 @itemx --interactive [=@var{when}]
7949 @opindex --interactive
7950 Specify when to issue an interactive prompt. @var{when} may be
7954 @vindex never @r{interactive option}
7955 - Do not prompt at all.
7957 @vindex once @r{interactive option}
7958 - Prompt once if more than three files are named or if a recursive
7959 removal is requested. Equivalent to @option{-I}.
7961 @vindex always @r{interactive option}
7962 - Prompt for every file being removed. Equivalent to @option{-i}.
7964 @option{--interactive} with no @var{when} is equivalent to
7965 @option{--interactive=always}.
7967 @itemx --one-file-system
7968 @opindex --one-file-system
7969 @cindex one file system, restricting @command{rm} to
7970 When removing a hierarchy recursively, skip any directory that is on a
7971 file system different from that of the corresponding command line argument.
7973 This option is useful when removing a build ``chroot'' hierarchy,
7974 which normally contains no valuable data. However, it is not uncommon
7975 to bind-mount @file{/home} into such a hierarchy, to make it easier to
7976 use one's start-up file. The catch is that it's easy to forget to
7977 unmount @file{/home}. Then, when you use @command{rm -rf} to remove
7978 your normally throw-away chroot, that command will remove everything
7979 under @file{/home}, too.
7980 Use the @option{--one-file-system} option, and it will
7981 warn about and skip directories on other file systems.
7982 Of course, this will not save your @file{/home} if it and your
7983 chroot happen to be on the same file system.
7985 @itemx --preserve-root
7986 @opindex --preserve-root
7987 @cindex root directory, disallow recursive destruction
7988 Fail upon any attempt to remove the root directory, @file{/},
7989 when used with the @option{--recursive} option.
7990 This is the default behavior.
7991 @xref{Treating / specially}.
7993 @itemx --no-preserve-root
7994 @opindex --no-preserve-root
7995 @cindex root directory, allow recursive destruction
7996 Do not treat @file{/} specially when removing recursively.
7997 This option is not recommended unless you really want to
7998 remove all the files on your computer.
7999 @xref{Treating / specially}.
8006 @opindex --recursive
8007 @cindex directories, removing (recursively)
8008 Remove the listed directories and their contents recursively.
8014 Print the name of each file before removing it.
8018 @cindex files beginning with @samp{-}, removing
8019 @cindex @samp{-}, removing files beginning with
8020 One common question is how to remove files whose names begin with a
8021 @samp{-}. @sc{gnu} @command{rm}, like every program that uses the @code{getopt}
8022 function to parse its arguments, lets you use the @samp{--} option to
8023 indicate that all following arguments are non-options. To remove a file
8024 called @file{-f} in the current directory, you could type either:
8037 @opindex - @r{and Unix @command{rm}}
8038 The Unix @command{rm} program's use of a single @samp{-} for this purpose
8039 predates the development of the getopt standard syntax.
8044 @node shred invocation
8045 @section @command{shred}: Remove files more securely
8048 @cindex data, erasing
8049 @cindex erasing data
8051 @command{shred} overwrites devices or files, to help prevent even
8052 very expensive hardware from recovering the data.
8054 Ordinarily when you remove a file (@pxref{rm invocation}), the data is
8055 not actually destroyed. Only the index listing where the file is
8056 stored is destroyed, and the storage is made available for reuse.
8057 There are undelete utilities that will attempt to reconstruct the index
8058 and can bring the file back if the parts were not reused.
8060 On a busy system with a nearly-full drive, space can get reused in a few
8061 seconds. But there is no way to know for sure. If you have sensitive
8062 data, you may want to be sure that recovery is not possible by actually
8063 overwriting the file with non-sensitive data.
8065 However, even after doing that, it is possible to take the disk back
8066 to a laboratory and use a lot of sensitive (and expensive) equipment
8067 to look for the faint ``echoes'' of the original data underneath the
8068 overwritten data. If the data has only been overwritten once, it's not
8071 The best way to remove something irretrievably is to destroy the media
8072 it's on with acid, melt it down, or the like. For cheap removable media
8073 like floppy disks, this is the preferred method. However, hard drives
8074 are expensive and hard to melt, so the @command{shred} utility tries
8075 to achieve a similar effect non-destructively.
8077 This uses many overwrite passes, with the data patterns chosen to
8078 maximize the damage they do to the old data. While this will work on
8079 floppies, the patterns are designed for best effect on hard drives.
8080 For more details, see the source code and Peter Gutmann's paper
8081 @uref{http://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html,
8082 @cite{Secure Deletion of Data from Magnetic and Solid-State Memory}},
8083 from the proceedings of the Sixth @acronym{USENIX} Security Symposium (San Jose,
8084 California, July 22--25, 1996).
8086 @strong{Please note} that @command{shred} relies on a very important assumption:
8087 that the file system overwrites data in place. This is the traditional
8088 way to do things, but many modern file system designs do not satisfy this
8089 assumption. Exceptions include:
8094 Log-structured or journaled file systems, such as those supplied with
8095 AIX and Solaris, and JFS, ReiserFS, XFS, Ext3 (in @code{data=journal} mode),
8096 BFS, NTFS, etc.@: when they are configured to journal @emph{data}.
8099 File systems that write redundant data and carry on even if some writes
8100 fail, such as RAID-based file systems.
8103 File systems that make snapshots, such as Network Appliance's NFS server.
8106 File systems that cache in temporary locations, such as NFS version 3
8110 Compressed file systems.
8113 In the particular case of ext3 file systems, the above disclaimer applies (and
8114 @command{shred} is thus of limited effectiveness) only in @code{data=journal}
8115 mode, which journals file data in addition to just metadata. In both
8116 the @code{data=ordered} (default) and @code{data=writeback} modes,
8117 @command{shred} works as usual. Ext3 journaling modes can be changed
8118 by adding the @code{data=something} option to the mount options for a
8119 particular file system in the @file{/etc/fstab} file, as documented in
8120 the mount man page (man mount).
8122 If you are not sure how your file system operates, then you should assume
8123 that it does not overwrite data in place, which means that shred cannot
8124 reliably operate on regular files in your file system.
8126 Generally speaking, it is more reliable to shred a device than a file,
8127 since this bypasses the problem of file system design mentioned above.
8128 However, even shredding devices is not always completely reliable. For
8129 example, most disks map out bad sectors invisibly to the application; if
8130 the bad sectors contain sensitive data, @command{shred} won't be able to
8133 @command{shred} makes no attempt to detect or report this problem, just as
8134 it makes no attempt to do anything about backups. However, since it is
8135 more reliable to shred devices than files, @command{shred} by default does
8136 not truncate or remove the output file. This default is more suitable
8137 for devices, which typically cannot be truncated and should not be
8140 Finally, consider the risk of backups and mirrors.
8141 File system backups and remote mirrors may contain copies of the
8142 file that cannot be removed, and that will allow a shredded file
8143 to be recovered later. So if you keep any data you may later want
8144 to destroy using @command{shred}, be sure that it is not backed up or mirrored.
8147 shred [@var{option}]@dots{} @var{file}[@dots{}]
8150 The program accepts the following options. Also see @ref{Common options}.
8158 @cindex force deletion
8159 Override file permissions if necessary to allow overwriting.
8162 @itemx -n @var{NUMBER}
8163 @itemx --iterations=@var{NUMBER}
8164 @opindex -n @var{NUMBER}
8165 @opindex --iterations=@var{NUMBER}
8166 @cindex iterations, selecting the number of
8167 By default, @command{shred} uses 25 passes of overwrite. This is enough
8168 for all of the useful overwrite patterns to be used at least once.
8169 You can reduce this to save time, or increase it if you have a lot of
8172 @item --random-source=@var{file}
8173 @opindex --random-source
8174 @cindex random source for shredding
8175 Use @var{file} as a source of random data used to overwrite and to
8176 choose pass ordering. @xref{Random sources}.
8178 @item -s @var{BYTES}
8179 @itemx --size=@var{BYTES}
8180 @opindex -s @var{BYTES}
8181 @opindex --size=@var{BYTES}
8182 @cindex size of file to shred
8183 Shred the first @var{BYTES} bytes of the file. The default is to shred
8184 the whole file. @var{BYTES} can be followed by a size specification like
8185 @samp{K}, @samp{M}, or @samp{G} to specify a multiple. @xref{Block size}.
8191 @cindex removing files after shredding
8192 After shredding a file, truncate it (if possible) and then remove it.
8193 If a file has multiple links, only the named links will be removed.
8199 Display to standard error all status updates as sterilization proceeds.
8205 By default, @command{shred} rounds the size of a regular file up to the next
8206 multiple of the file system block size to fully erase the last block of the file.
8207 Use @option{--exact} to suppress that behavior.
8208 Thus, by default if you shred a 10-byte regular file on a system with 512-byte
8209 blocks, the resulting file will be 512 bytes long. With this option,
8210 shred does not increase the apparent size of the file.
8216 Normally, the last pass that @command{shred} writes is made up of
8217 random data. If this would be conspicuous on your hard drive (for
8218 example, because it looks like encrypted data), or you just think
8219 it's tidier, the @option{--zero} option adds an additional overwrite pass with
8220 all zero bits. This is in addition to the number of passes specified
8221 by the @option{--iterations} option.
8225 You might use the following command to erase all trace of the
8226 file system you'd created on the floppy disk in your first drive.
8227 That command takes about 20 minutes to erase a ``1.44MB'' (actually
8231 shred --verbose /dev/fd0
8234 Similarly, to erase all data on a selected partition of
8235 your hard disk, you could give a command like this:
8238 shred --verbose /dev/sda5
8241 A @var{file} of @samp{-} denotes standard output.
8242 The intended use of this is to shred a removed temporary file.
8246 i=`tempfile -m 0600`
8249 echo "Hello, world" >&3
8254 However, the command @samp{shred - >file} does not shred the contents
8255 of @var{file}, since the shell truncates @var{file} before invoking
8256 @command{shred}. Use the command @samp{shred file} or (if using a
8257 Bourne-compatible shell) the command @samp{shred - 1<>file} instead.
8262 @node Special file types
8263 @chapter Special file types
8265 @cindex special file types
8266 @cindex file types, special
8268 This chapter describes commands which create special types of files (and
8269 @command{rmdir}, which removes directories, one special file type).
8271 @cindex special file types
8273 Although Unix-like operating systems have markedly fewer special file
8274 types than others, not @emph{everything} can be treated only as the
8275 undifferentiated byte stream of @dfn{normal files}. For example, when a
8276 file is created or removed, the system must record this information,
8277 which it does in a @dfn{directory}---a special type of file. Although
8278 you can read directories as normal files, if you're curious, in order
8279 for the system to do its job it must impose a structure, a certain
8280 order, on the bytes of the file. Thus it is a ``special'' type of file.
8282 Besides directories, other special file types include named pipes
8283 (FIFOs), symbolic links, sockets, and so-called @dfn{special files}.
8286 * link invocation:: Make a hard link via the link syscall
8287 * ln invocation:: Make links between files.
8288 * mkdir invocation:: Make directories.
8289 * mkfifo invocation:: Make FIFOs (named pipes).
8290 * mknod invocation:: Make block or character special files.
8291 * readlink invocation:: Print the referent of a symbolic link.
8292 * rmdir invocation:: Remove empty directories.
8293 * unlink invocation:: Remove files via the unlink syscall
8297 @node link invocation
8298 @section @command{link}: Make a hard link via the link syscall
8301 @cindex links, creating
8302 @cindex hard links, creating
8303 @cindex creating links (hard only)
8305 @command{link} creates a single hard link at a time.
8306 It is a minimalist interface to the system-provided
8307 @code{link} function. @xref{Hard Links, , , libc,
8308 The GNU C Library Reference Manual}.
8309 It avoids the bells and whistles of the more commonly-used
8310 @command{ln} command (@pxref{ln invocation}).
8314 link @var{filename} @var{linkname}
8317 @var{filename} must specify an existing file, and @var{linkname}
8318 must specify a nonexistent entry in an existing directory.
8319 @command{link} simply calls @code{link (@var{filename}, @var{linkname})}
8322 On a @acronym{GNU} system, this command acts like @samp{ln --directory
8323 --no-target-directory @var{filename} @var{linkname}}. However, the
8324 @option{--directory} and @option{--no-target-directory} options are
8325 not specified by @acronym{POSIX}, and the @command{link} command is
8326 more portable in practice.
8332 @section @command{ln}: Make links between files
8335 @cindex links, creating
8336 @cindex hard links, creating
8337 @cindex symbolic (soft) links, creating
8338 @cindex creating links (hard or soft)
8340 @cindex file systems and hard links
8341 @command{ln} makes links between files. By default, it makes hard links;
8342 with the @option{-s} option, it makes symbolic (or @dfn{soft}) links.
8346 ln [@var{option}]@dots{} [-T] @var{target} @var{linkname}
8347 ln [@var{option}]@dots{} @var{target}
8348 ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
8349 ln [@var{option}]@dots{} -t @var{directory} @var{target}@dots{}
8355 If two file names are given, @command{ln} creates a link to the first
8356 file from the second.
8359 If one @var{target} is given, @command{ln} creates a link to that file
8360 in the current directory.
8363 If the @option{--target-directory} (@option{-t}) option is given, or
8364 failing that if the last file is a directory and the
8365 @option{--no-target-directory} (@option{-T}) option is not given,
8366 @command{ln} creates a link to each @var{target} file in the specified
8367 directory, using the @var{target}s' names.
8371 Normally @command{ln} does not remove existing files. Use the
8372 @option{--force} (@option{-f}) option to remove them unconditionally,
8373 the @option{--interactive} (@option{-i}) option to remove them
8374 conditionally, and the @option{--backup} (@option{-b}) option to
8377 @cindex hard link, defined
8378 @cindex inode, and hard links
8379 A @dfn{hard link} is another name for an existing file; the link and the
8380 original are indistinguishable. Technically speaking, they share the
8381 same inode, and the inode contains all the information about a
8382 file---indeed, it is not incorrect to say that the inode @emph{is} the
8383 file. On all existing implementations, you cannot make a hard link to
8384 a directory, and hard links cannot cross file system boundaries. (These
8385 restrictions are not mandated by @acronym{POSIX}, however.)
8387 @cindex dereferencing symbolic links
8388 @cindex symbolic link, defined
8389 @dfn{Symbolic links} (@dfn{symlinks} for short), on the other hand, are
8390 a special file type (which not all kernels support: System V release 3
8391 (and older) systems lack symlinks) in which the link file actually
8392 refers to a different file, by name. When most operations (opening,
8393 reading, writing, and so on) are passed the symbolic link file, the
8394 kernel automatically @dfn{dereferences} the link and operates on the
8395 target of the link. But some operations (e.g., removing) work on the
8396 link file itself, rather than on its target. @xref{Symbolic Links,,,
8397 libc, The GNU C Library Reference Manual}.
8399 The program accepts the following options. Also see @ref{Common options}.
8410 @opindex --directory
8411 @cindex hard links to directories
8412 Allow users with appropriate privileges to attempt to make hard links
8414 However, note that this will probably fail due to
8415 system restrictions, even for the super-user.
8421 Remove existing destination files.
8424 @itemx --interactive
8426 @opindex --interactive
8427 @cindex prompting, and @command{ln}
8428 Prompt whether to remove existing destination files.
8431 @itemx --no-dereference
8433 @opindex --no-dereference
8434 Do not treat the last operand specially when it is a symbolic link to
8435 a directory. Instead, treat it as if it were a normal file.
8437 When the destination is an actual directory (not a symlink to one),
8438 there is no ambiguity. The link is created in that directory.
8439 But when the specified destination is a symlink to a directory,
8440 there are two ways to treat the user's request. @command{ln} can
8441 treat the destination just as it would a normal directory and create
8442 the link in it. On the other hand, the destination can be viewed as a
8443 non-directory---as the symlink itself. In that case, @command{ln}
8444 must delete or backup that symlink before creating the new link.
8445 The default is to treat a destination that is a symlink to a directory
8446 just like a directory.
8448 This option is weaker than the @option{--no-target-directory}
8449 (@option{-T}) option, so it has no effect if both options are given.
8455 Make symbolic links instead of hard links. This option merely produces
8456 an error message on systems that do not support symbolic links.
8462 @optNoTargetDirectory
8468 Print the name of each file after linking it successfully.
8479 # Create link ../a pointing to a in that directory.
8480 # Not really useful because it points to itself.
8485 # Change to the target before creating symlinks to avoid being confused.
8491 # Hard coded file names don't move well.
8492 ln -s $(pwd)/a /some/dir/
8496 # Relative file names survive directory moves and also
8497 # work across networked file systems.
8498 ln -s afile anotherfile
8499 ln -s ../adir/afile yetanotherfile
8503 @node mkdir invocation
8504 @section @command{mkdir}: Make directories
8507 @cindex directories, creating
8508 @cindex creating directories
8510 @command{mkdir} creates directories with the specified names. Synopsis:
8513 mkdir [@var{option}]@dots{} @var{name}@dots{}
8516 @command{mkdir} creates each directory @var{name} in the order given.
8517 It reports an error if @var{name} already exists, unless the
8518 @option{-p} option is given and @var{name} is a directory.
8520 The program accepts the following options. Also see @ref{Common options}.
8525 @itemx --mode=@var{mode}
8528 @cindex modes of created directories, setting
8529 Set the file permission bits of created directories to @var{mode},
8530 which uses the same syntax as
8531 in @command{chmod} and uses @samp{a=rwx} (read, write and execute allowed for
8532 everyone) for the point of the departure. @xref{File permissions}.
8534 Normally the directory has the desired file mode bits at the moment it
8535 is created. As a @acronym{GNU} extension, @var{mode} may also mention
8536 special mode bits, but in this case there may be a temporary window
8537 during which the directory exists but its special mode bits are
8538 incorrect. @xref{Directory Setuid and Setgid}, for how the
8539 set-user-ID and set-group-ID bits of directories are inherited unless
8540 overridden in this way.
8546 @cindex parent directories, creating
8547 Make any missing parent directories for each argument, setting their
8548 file permission bits to the umask modified by @samp{u+wx}. Ignore
8549 existing parent directories, and do not change their file permission
8552 To set the file permission bits of any newly-created parent
8553 directories to a value that includes @samp{u+wx}, you can set the
8554 umask before invoking @command{mkdir}. For example, if the shell
8555 command @samp{(umask u=rwx,go=rx; mkdir -p P/Q)} creates the parent
8556 @file{P} it sets the parent's permission bits to @samp{u=rwx,go=rx}.
8557 To set a parent's special mode bits as well, you can invoke
8558 @command{chmod} after @command{mkdir}. @xref{Directory Setuid and
8559 Setgid}, for how the set-user-ID and set-group-ID bits of
8560 newly-created parent directories are inherited.
8566 Print a message for each created directory. This is most useful with
8573 @node mkfifo invocation
8574 @section @command{mkfifo}: Make FIFOs (named pipes)
8577 @cindex FIFOs, creating
8578 @cindex named pipes, creating
8579 @cindex creating FIFOs (named pipes)
8581 @command{mkfifo} creates FIFOs (also called @dfn{named pipes}) with the
8582 specified names. Synopsis:
8585 mkfifo [@var{option}] @var{name}@dots{}
8588 A @dfn{FIFO} is a special file type that permits independent processes
8589 to communicate. One process opens the FIFO file for writing, and
8590 another for reading, after which data can flow as with the usual
8591 anonymous pipe in shells or elsewhere.
8593 The program accepts the following option. Also see @ref{Common options}.
8598 @itemx --mode=@var{mode}
8601 @cindex modes of created FIFOs, setting
8602 Set the mode of created FIFOs to @var{mode}, which is symbolic as in
8603 @command{chmod} and uses @samp{a=rw} (read and write allowed for everyone)
8604 for the point of departure. @var{mode} should specify only file
8605 permission bits. @xref{File permissions}.
8612 @node mknod invocation
8613 @section @command{mknod}: Make block or character special files
8616 @cindex block special files, creating
8617 @cindex character special files, creating
8619 @command{mknod} creates a FIFO, character special file, or block special
8620 file with the specified name. Synopsis:
8623 mknod [@var{option}]@dots{} @var{name} @var{type} [@var{major} @var{minor}]
8626 @cindex special files
8627 @cindex block special files
8628 @cindex character special files
8629 Unlike the phrase ``special file type'' above, the term @dfn{special
8630 file} has a technical meaning on Unix: something that can generate or
8631 receive data. Usually this corresponds to a physical piece of hardware,
8632 e.g., a printer or a disk. (These files are typically created at
8633 system-configuration time.) The @command{mknod} command is what creates
8634 files of this type. Such devices can be read either a character at a
8635 time or a ``block'' (many characters) at a time, hence we say there are
8636 @dfn{block special} files and @dfn{character special} files.
8638 The arguments after @var{name} specify the type of file to make:
8643 @opindex p @r{for FIFO file}
8647 @opindex b @r{for block special file}
8648 for a block special file
8651 @c Don't document the `u' option -- it's just a synonym for `c'.
8652 @c Do *any* versions of mknod still use it?
8654 @opindex c @r{for character special file}
8655 @c @opindex u @r{for character special file}
8656 for a character special file
8660 When making a block or character special file, the major and minor
8661 device numbers must be given after the file type.
8662 If a major or minor device number begins with @samp{0x} or @samp{0X},
8663 it is interpreted as hexadecimal; otherwise, if it begins with @samp{0},
8664 as octal; otherwise, as decimal.
8666 The program accepts the following option. Also see @ref{Common options}.
8671 @itemx --mode=@var{mode}
8674 Set the mode of created files to @var{mode}, which is symbolic as in
8675 @command{chmod} and uses @samp{a=rw} as the point of departure.
8676 @var{mode} should specify only file permission bits.
8677 @xref{File permissions}.
8684 @node readlink invocation
8685 @section @command{readlink}: Print the referent of a symbolic link
8688 @cindex displaying value of a symbolic link
8690 @command{readlink} may work in one of two supported modes:
8696 @command{readlink} outputs the value of the given symbolic link.
8697 If @command{readlink} is invoked with an argument other than the name
8698 of a symbolic link, it produces no output and exits with a nonzero exit code.
8700 @item Canonicalize mode
8702 @command{readlink} outputs the absolute name of the given file which contains
8703 no @file{.}, @file{..} components nor any repeated separators
8704 (@file{/}) or symbolic links.
8709 readlink [@var{option}] @var{file}
8712 By default, @command{readlink} operates in readlink mode.
8714 The program accepts the following options. Also see @ref{Common options}.
8719 @itemx --canonicalize
8721 @opindex --canonicalize
8722 Activate canonicalize mode.
8723 If any component of the file name except the last one is missing or unavailable,
8724 @command{readlink} produces no output and exits with a nonzero exit code.
8727 @itemx --canonicalize-existing
8729 @opindex --canonicalize-existing
8730 Activate canonicalize mode.
8731 If any component is missing or unavailable, @command{readlink} produces
8732 no output and exits with a nonzero exit code.
8735 @itemx --canonicalize-missing
8737 @opindex --canonicalize-missing
8738 Activate canonicalize mode.
8739 If any component is missing or unavailable, @command{readlink} treats it
8745 @opindex --no-newline
8746 Do not output the trailing newline.
8756 Suppress most error messages.
8762 Report error messages.
8766 The @command{readlink} utility first appeared in OpenBSD 2.1.
8771 @node rmdir invocation
8772 @section @command{rmdir}: Remove empty directories
8775 @cindex removing empty directories
8776 @cindex directories, removing empty
8778 @command{rmdir} removes empty directories. Synopsis:
8781 rmdir [@var{option}]@dots{} @var{directory}@dots{}
8784 If any @var{directory} argument does not refer to an existing empty
8785 directory, it is an error.
8787 The program accepts the following options. Also see @ref{Common options}.
8791 @item --ignore-fail-on-non-empty
8792 @opindex --ignore-fail-on-non-empty
8793 @cindex directory deletion, ignoring failures
8794 Ignore each failure to remove a directory that is solely because
8795 the directory is non-empty.
8801 @cindex parent directories, removing
8802 Remove @var{directory}, then try to remove each component of @var{directory}.
8803 So, for example, @samp{rmdir -p a/b/c} is similar to @samp{rmdir a/b/c a/b a}.
8804 As such, it fails if any of those directories turns out not to be empty.
8805 Use the @option{--ignore-fail-on-non-empty} option to make it so such
8806 a failure does not evoke a diagnostic and does not cause @command{rmdir} to
8807 exit unsuccessfully.
8813 @cindex directory deletion, reporting
8814 Give a diagnostic for each successful removal.
8815 @var{directory} is removed.
8819 @xref{rm invocation}, for how to remove non-empty directories (recursively).
8824 @node unlink invocation
8825 @section @command{unlink}: Remove files via the unlink syscall
8828 @cindex removing files or directories (via the unlink syscall)
8830 @command{unlink} deletes a single specified file name.
8831 It is a minimalist interface to the system-provided
8832 @code{unlink} function. @xref{Deleting Files, , , libc,
8833 The GNU C Library Reference Manual}. Synopsis:
8834 It avoids the bells and whistles of the more commonly-used
8835 @command{rm} command (@pxref{rm invocation}).
8838 unlink @var{filename}
8841 On some systems @code{unlink} can be used to delete the name of a
8842 directory. On others, it can be used that way only by a privileged user.
8843 In the GNU system @code{unlink} can never delete the name of a directory.
8845 The @command{unlink} command honors the @option{--help} and
8846 @option{--version} options. To remove a file whose name begins with
8847 @samp{-}, prefix the name with @samp{./}, e.g., @samp{unlink ./--help}.
8852 @node Changing file attributes
8853 @chapter Changing file attributes
8855 @cindex changing file attributes
8856 @cindex file attributes, changing
8857 @cindex attributes, file
8859 A file is not merely its contents, a name, and a file type
8860 (@pxref{Special file types}). A file also has an owner (a user ID), a
8861 group (a group ID), permissions (what the owner can do with the file,
8862 what people in the group can do, and what everyone else can do), various
8863 timestamps, and other information. Collectively, we call these a file's
8866 These commands change file attributes.
8869 * chgrp invocation:: Change file groups.
8870 * chmod invocation:: Change access permissions.
8871 * chown invocation:: Change file owners and groups.
8872 * touch invocation:: Change file timestamps.
8876 @node chown invocation
8877 @section @command{chown}: Change file owner and group
8880 @cindex file ownership, changing
8881 @cindex group ownership, changing
8882 @cindex changing file ownership
8883 @cindex changing group ownership
8885 @command{chown} changes the user and/or group ownership of each given @var{file}
8886 to @var{new-owner} or to the user and group of an existing reference file.
8890 chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@} @var{file}@dots{}
8893 If used, @var{new-owner} specifies the new owner and/or group as follows
8894 (with no embedded white space):
8897 [@var{owner}] [ : [@var{group}] ]
8904 If only an @var{owner} (a user name or numeric user ID) is given, that
8905 user is made the owner of each given file, and the files' group is not
8908 @item owner@samp{:}group
8909 If the @var{owner} is followed by a colon and a @var{group} (a
8910 group name or numeric group ID), with no spaces between them, the group
8911 ownership of the files is changed as well (to @var{group}).
8914 If a colon but no group name follows @var{owner}, that user is
8915 made the owner of the files and the group of the files is changed to
8916 @var{owner}'s login group.
8919 If the colon and following @var{group} are given, but the owner
8920 is omitted, only the group of the files is changed; in this case,
8921 @command{chown} performs the same function as @command{chgrp}.
8924 If only a colon is given, or if @var{new-owner} is empty, neither the
8925 owner nor the group is changed.
8929 If @var{owner} or @var{group} is intended to represent a numeric user
8930 or group ID, then you may specify it with a leading @samp{+}.
8931 @xref{Disambiguating names and IDs}.
8933 Some older scripts may still use @samp{.} in place of the @samp{:} separator.
8934 @acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not
8935 require support for that, but for backward compatibility @acronym{GNU}
8936 @command{chown} supports @samp{.} so long as no ambiguity results.
8937 New scripts should avoid the use of @samp{.} because it is not
8938 portable, and because it has undesirable results if the entire
8939 @var{owner@samp{.}group} happens to identify a user whose name
8942 The @command{chown} command sometimes clears the set-user-ID or
8943 set-group-ID permission bits. This behavior depends on the policy and
8944 functionality of the underlying @code{chown} system call, which may
8945 make system-dependent file mode modifications outside the control of
8946 the @command{chown} command. For example, the @command{chown} command
8947 might not affect those bits when invoked by a user with appropriate
8948 privileges, or when the
8949 bits signify some function other than executable permission (e.g.,
8951 When in doubt, check the underlying system behavior.
8953 The program accepts the following options. Also see @ref{Common options}.
8961 @cindex changed owners, verbosely describing
8962 Verbosely describe the action for each @var{file} whose ownership
8971 @cindex error messages, omitting
8972 Do not print error messages about files whose ownership cannot be
8975 @itemx @w{@kbd{--from}=@var{old-owner}}
8977 @cindex symbolic links, changing owner
8978 Change a @var{file}'s ownership only if it has current attributes specified
8979 by @var{old-owner}. @var{old-owner} has the same form as @var{new-owner}
8981 This option is useful primarily from a security standpoint in that
8982 it narrows considerably the window of potential abuse.
8983 For example, to reflect a user ID numbering change for one user's files
8984 without an option like this, @code{root} might run
8987 find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER
8990 But that is dangerous because the interval between when the @command{find}
8991 tests the existing file's owner and when the @command{chown} is actually run
8993 One way to narrow the gap would be to invoke chown for each file
8997 find / -owner OLDUSER -exec chown -h NEWUSER @{@} \;
9000 But that is very slow if there are many affected files.
9001 With this option, it is safer (the gap is narrower still)
9002 though still not perfect:
9005 chown -h -R --from=OLDUSER NEWUSER /
9009 @opindex --dereference
9010 @cindex symbolic links, changing owner
9012 Do not act on symbolic links themselves but rather on what they point to.
9013 This is the default.
9016 @itemx --no-dereference
9018 @opindex --no-dereference
9019 @cindex symbolic links, changing owner
9021 Act on symbolic links themselves instead of what they point to.
9022 This mode relies on the @code{lchown} system call.
9023 On systems that do not provide the @code{lchown} system call,
9024 @command{chown} fails when a file specified on the command line
9026 By default, no diagnostic is issued for symbolic links encountered
9027 during a recursive traversal, but see @option{--verbose}.
9029 @itemx --preserve-root
9030 @opindex --preserve-root
9031 @cindex root directory, disallow recursive modification
9032 Fail upon any attempt to recursively change the root directory, @file{/}.
9033 Without @option{--recursive}, this option has no effect.
9034 @xref{Treating / specially}.
9036 @itemx --no-preserve-root
9037 @opindex --no-preserve-root
9038 @cindex root directory, allow recursive modification
9039 Cancel the effect of any preceding @option{--preserve-root} option.
9040 @xref{Treating / specially}.
9042 @item --reference=@var{ref_file}
9043 @opindex --reference
9044 Change the user and group of each @var{file} to be the same as those of
9045 @var{ref_file}. If @var{ref_file} is a symbolic link, do not use the
9046 user and group of the symbolic link, but rather those of the file it
9053 Output a diagnostic for every file processed.
9054 If a symbolic link is encountered during a recursive traversal
9055 on a system without the @code{lchown} system call, and @option{--no-dereference}
9056 is in effect, then issue a diagnostic saying neither the symbolic link nor
9057 its referent is being changed.
9062 @opindex --recursive
9063 @cindex recursively changing file ownership
9064 Recursively change ownership of directories and their contents.
9067 @xref{Traversing symlinks}.
9070 @xref{Traversing symlinks}.
9073 @xref{Traversing symlinks}.
9082 # Change the owner of /u to "root".
9085 # Likewise, but also change its group to "staff".
9088 # Change the owner of /u and subfiles to "root".
9093 @node chgrp invocation
9094 @section @command{chgrp}: Change group ownership
9097 @cindex group ownership, changing
9098 @cindex changing group ownership
9100 @command{chgrp} changes the group ownership of each given @var{file}
9101 to @var{group} (which can be either a group name or a numeric group ID)
9102 or to the group of an existing reference file. Synopsis:
9105 chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@} @var{file}@dots{}
9108 If @var{group} is intended to represent a
9109 numeric group ID, then you may specify it with a leading @samp{+}.
9110 @xref{Disambiguating names and IDs}.
9112 The program accepts the following options. Also see @ref{Common options}.
9120 @cindex changed files, verbosely describing
9121 Verbosely describe the action for each @var{file} whose group actually
9130 @cindex error messages, omitting
9131 Do not print error messages about files whose group cannot be
9135 @opindex --dereference
9136 @cindex symbolic links, changing owner
9138 Do not act on symbolic links themselves but rather on what they point to.
9139 This is the default.
9142 @itemx --no-dereference
9144 @opindex --no-dereference
9145 @cindex symbolic links, changing group
9147 Act on symbolic links themselves instead of what they point to.
9148 This mode relies on the @code{lchown} system call.
9149 On systems that do not provide the @code{lchown} system call,
9150 @command{chgrp} fails when a file specified on the command line
9152 By default, no diagnostic is issued for symbolic links encountered
9153 during a recursive traversal, but see @option{--verbose}.
9155 @itemx --preserve-root
9156 @opindex --preserve-root
9157 @cindex root directory, disallow recursive modification
9158 Fail upon any attempt to recursively change the root directory, @file{/}.
9159 Without @option{--recursive}, this option has no effect.
9160 @xref{Treating / specially}.
9162 @itemx --no-preserve-root
9163 @opindex --no-preserve-root
9164 @cindex root directory, allow recursive modification
9165 Cancel the effect of any preceding @option{--preserve-root} option.
9166 @xref{Treating / specially}.
9168 @item --reference=@var{ref_file}
9169 @opindex --reference
9170 Change the group of each @var{file} to be the same as that of
9171 @var{ref_file}. If @var{ref_file} is a symbolic link, do not use the
9172 group of the symbolic link, but rather that of the file it refers to.
9178 Output a diagnostic for every file processed.
9179 If a symbolic link is encountered during a recursive traversal
9180 on a system without the @code{lchown} system call, and @option{--no-dereference}
9181 is in effect, then issue a diagnostic saying neither the symbolic link nor
9182 its referent is being changed.
9187 @opindex --recursive
9188 @cindex recursively changing group ownership
9189 Recursively change the group ownership of directories and their contents.
9192 @xref{Traversing symlinks}.
9195 @xref{Traversing symlinks}.
9198 @xref{Traversing symlinks}.
9207 # Change the group of /u to "staff".
9210 # Change the group of /u and subfiles to "staff".
9215 @node chmod invocation
9216 @section @command{chmod}: Change access permissions
9219 @cindex changing access permissions
9220 @cindex access permissions, changing
9221 @cindex permissions, changing access
9223 @command{chmod} changes the access permissions of the named files. Synopsis:
9226 chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{ref_file}@} @var{file}@dots{}
9229 @cindex symbolic links, permissions of
9230 @command{chmod} never changes the permissions of symbolic links, since
9231 the @command{chmod} system call cannot change their permissions.
9232 This is not a problem since the permissions of symbolic links are
9233 never used. However, for each symbolic link listed on the command
9234 line, @command{chmod} changes the permissions of the pointed-to file.
9235 In contrast, @command{chmod} ignores symbolic links encountered during
9236 recursive directory traversals.
9238 A successful use of @command{chmod} clears the set-group-ID bit of a
9239 regular file if the file's group ID does not match the user's
9240 effective group ID or one of the user's supplementary group IDs,
9241 unless the user has appropriate privileges. Additional restrictions
9242 may cause the set-user-ID and set-group-ID bits of @var{mode} or
9243 @var{ref_file} to be ignored. This behavior depends on the policy and
9244 functionality of the underlying @code{chmod} system call. When in
9245 doubt, check the underlying system behavior.
9247 If used, @var{mode} specifies the new file mode bits.
9248 For details, see the section on @ref{File permissions}.
9249 If you really want @var{mode} to have a leading @samp{-}, you should
9250 use @option{--} first, e.g., @samp{chmod -- -w file}. Typically,
9251 though, @samp{chmod a-w file} is preferable, and @command{chmod -w
9252 file} (without the @option{--}) complains if it behaves differently
9253 from what @samp{chmod a-w file} would do.
9255 The program accepts the following options. Also see @ref{Common options}.
9263 Verbosely describe the action for each @var{file} whose permissions
9272 @cindex error messages, omitting
9273 Do not print error messages about files whose permissions cannot be
9276 @itemx --preserve-root
9277 @opindex --preserve-root
9278 @cindex root directory, disallow recursive modification
9279 Fail upon any attempt to recursively change the root directory, @file{/}.
9280 Without @option{--recursive}, this option has no effect.
9281 @xref{Treating / specially}.
9283 @itemx --no-preserve-root
9284 @opindex --no-preserve-root
9285 @cindex root directory, allow recursive modification
9286 Cancel the effect of any preceding @option{--preserve-root} option.
9287 @xref{Treating / specially}.
9293 Verbosely describe the action or non-action taken for every @var{file}.
9295 @item --reference=@var{ref_file}
9296 @opindex --reference
9297 Change the mode of each @var{file} to be the same as that of @var{ref_file}.
9298 @xref{File permissions}.
9299 If @var{ref_file} is a symbolic link, do not use the mode
9300 of the symbolic link, but rather that of the file it refers to.
9305 @opindex --recursive
9306 @cindex recursively changing access permissions
9307 Recursively change permissions of directories and their contents.
9314 @node touch invocation
9315 @section @command{touch}: Change file timestamps
9318 @cindex changing file timestamps
9319 @cindex file timestamps, changing
9320 @cindex timestamps, changing file
9322 @command{touch} changes the access and/or modification times of the
9323 specified files. Synopsis:
9326 touch [@var{option}]@dots{} @var{file}@dots{}
9329 @cindex empty files, creating
9330 Any @var{file} argument that does not exist is created empty.
9332 A @var{file} argument string of @samp{-} is handled specially and
9333 causes @command{touch} to change the times of the file associated with
9336 @cindex permissions, for changing file timestamps
9337 If changing both the access and modification times to the current
9338 time, @command{touch} can change the timestamps for files that the user
9339 running it does not own but has write permission for. Otherwise, the
9340 user must own the files.
9342 Although @command{touch} provides options for changing two of the times---the
9343 times of last access and modification---of a file, there is actually
9344 a third one as well: the inode change time. This is often referred to
9345 as a file's @code{ctime}.
9346 The inode change time represents the time when the file's meta-information
9347 last changed. One common example of this is when the permissions of a
9348 file change. Changing the permissions doesn't access the file, so
9349 the atime doesn't change, nor does it modify the file, so the mtime
9350 doesn't change. Yet, something about the file itself has changed,
9351 and this must be noted somewhere. This is the job of the ctime field.
9352 This is necessary, so that, for example, a backup program can make a
9353 fresh copy of the file, including the new permissions value.
9354 Another operation that modifies a file's ctime without affecting
9355 the others is renaming. In any case, it is not possible, in normal
9356 operations, for a user to change the ctime field to a user-specified value.
9359 Time stamps assume the time zone rules specified by the @env{TZ}
9360 environment variable, or by the system default rules if @env{TZ} is
9361 not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ},
9362 libc, The GNU C Library Reference Manual}.
9363 You can avoid ambiguities during
9364 daylight saving transitions by using @sc{utc} time stamps.
9366 The program accepts the following options. Also see @ref{Common options}.
9372 @itemx --time=access
9376 @opindex atime@r{, changing}
9377 @opindex access @r{time, changing}
9378 @opindex use @r{time, changing}
9379 Change the access time only.
9384 @opindex --no-create
9385 Do not create files that do not exist.
9388 @itemx --date=@var{time}
9392 Use @var{time} instead of the current time. It can contain month names,
9393 time zones, @samp{am} and @samp{pm}, @samp{yesterday}, etc. For
9394 example, @option{--date="2004-02-27 14:19:13.489392193 +0530"}
9395 specifies the instant of time that is 489,392,193 nanoseconds after
9396 February 27, 2004 at 2:19:13 PM in a time zone that is 5 hours and 30
9397 minutes east of @acronym{UTC}. @xref{Date input formats}.
9398 File systems that do not support high-resolution time stamps
9399 silently ignore any excess precision here.
9403 @cindex BSD @command{touch} compatibility
9404 Ignored; for compatibility with BSD versions of @command{touch}.
9408 @itemx --time=modify
9411 @opindex mtime@r{, changing}
9412 @opindex modify @r{time, changing}
9413 Change the modification time only.
9416 @itemx --reference=@var{file}
9418 @opindex --reference
9419 Use the times of the reference @var{file} instead of the current time.
9420 If this option is combined with the @option{--date=@var{time}}
9421 (@option{-d @var{time}}) option, the reference @var{file}'s time is
9422 the origin for any relative @var{time}s given, but is otherwise ignored.
9423 For example, @samp{-r foo -d '-5 seconds'} specifies a time stamp
9424 equal to five seconds before the corresponding time stamp for @file{foo}.
9426 @item -t [[@var{CC}]@var{YY}]@var{MMDDhhmm}[.@var{ss}]
9427 Use the argument (optional four-digit or two-digit years, months,
9428 days, hours, minutes, optional seconds) instead of the current time.
9429 If the year is specified with only two digits, then @var{CC}
9430 is 20 for years in the range 0 @dots{} 68, and 19 for years in
9431 69 @dots{} 99. If no digits of the year are specified,
9432 the argument is interpreted as a date in the current year.
9436 @vindex _POSIX2_VERSION
9437 On older systems, @command{touch} supports an obsolete syntax, as follows.
9438 If no timestamp is given with any of the @option{-d}, @option{-r}, or
9439 @option{-t} options, and if there are two or more @var{file}s and the
9440 first @var{file} is of the form @samp{@var{MMDDhhmm}[@var{YY}]} and this
9441 would be a valid argument to the @option{-t} option (if the @var{YY}, if
9442 any, were moved to the front), and if the represented year
9443 is in the range 1969--1999, that argument is interpreted as the time
9444 for the other files instead of as a file name.
9445 This obsolete behavior can be enabled or disabled with the
9446 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
9447 conformance}), but portable scripts should avoid commands whose
9448 behavior depends on this variable.
9449 For example, use @samp{touch ./12312359 main.c} or @samp{touch -t
9450 12312359 main.c} rather than the ambiguous @samp{touch 12312359 main.c}.
9460 No disk can hold an infinite amount of data. These commands report
9461 how much disk storage is in use or available, report other file and
9462 file status information, and write buffers to disk.
9465 * df invocation:: Report file system disk space usage.
9466 * du invocation:: Estimate file space usage.
9467 * stat invocation:: Report file or file system status.
9468 * sync invocation:: Synchronize memory and disk.
9473 @section @command{df}: Report file system disk space usage
9476 @cindex file system disk usage
9477 @cindex disk usage by file system
9479 @command{df} reports the amount of disk space used and available on
9480 file systems. Synopsis:
9483 df [@var{option}]@dots{} [@var{file}]@dots{}
9486 With no arguments, @command{df} reports the space used and available on all
9487 currently mounted file systems (of all types). Otherwise, @command{df}
9488 reports on the file system containing each argument @var{file}.
9490 Normally the disk space is printed in units of
9491 1024 bytes, but this can be overridden (@pxref{Block size}).
9492 Non-integer quantities are rounded up to the next higher unit.
9494 @cindex disk device file
9495 @cindex device file, disk
9496 If an argument @var{file} is a disk device file containing a mounted
9497 file system, @command{df} shows the space available on that file system
9498 rather than on the file system containing the device node (i.e., the root
9499 file system). @sc{gnu} @command{df} does not attempt to determine the disk usage
9500 on unmounted file systems, because on most kinds of systems doing so
9501 requires extremely nonportable intimate knowledge of file system
9504 The program accepts the following options. Also see @ref{Common options}.
9512 @cindex automounter file systems
9513 @cindex ignore file systems
9514 Include in the listing dummy file systems, which
9515 are omitted by default. Such file systems are typically special-purpose
9516 pseudo-file-systems, such as automounter entries.
9519 @itemx --block-size=@var{size}
9521 @opindex --block-size
9522 @cindex file system sizes
9523 Scale sizes by @var{size} before printing them (@pxref{Block size}).
9524 For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes.
9530 Equivalent to @option{--si}.
9537 List inode usage information instead of block usage. An inode (short
9538 for index node) contains information about a file such as its owner,
9539 permissions, timestamps, and location on the disk.
9543 @cindex kibibytes for file system sizes
9544 Print sizes in 1024-byte blocks, overriding the default block size
9545 (@pxref{Block size}).
9546 This option is equivalent to @option{--block-size=1K}.
9552 @cindex file system types, limiting output to certain
9553 Limit the listing to local file systems. By default, remote file systems
9558 @cindex file system space, retrieving old data more quickly
9559 Do not invoke the @code{sync} system call before getting any usage data.
9560 This may make @command{df} run significantly faster on systems with many
9561 disks, but on some systems (notably SunOS) the results may be slightly
9562 out of date. This is the default.
9565 @itemx --portability
9567 @opindex --portability
9568 @cindex one-line output format
9569 @cindex @acronym{POSIX} output format
9570 @cindex portable output format
9571 @cindex output format, portable
9572 Use the @acronym{POSIX} output format. This is like the default format except
9577 The information about each file system is always printed on exactly
9578 one line; a mount device is never put on a line by itself. This means
9579 that if the mount device name is more than 20 characters long (e.g., for
9580 some network mounts), the columns are misaligned.
9583 The labels in the header output line are changed to conform to @acronym{POSIX}.
9586 The default block size and output format are unaffected by the
9587 @env{DF_BLOCK_SIZE}, @env{BLOCK_SIZE} and @env{BLOCKSIZE} environment
9588 variables. However, the default block size is still affected by
9589 @env{POSIXLY_CORRECT}: it is 512 if @env{POSIXLY_CORRECT} is set, 1024
9590 otherwise. @xref{Block size}.
9597 @cindex file system space, retrieving current data more slowly
9598 Invoke the @code{sync} system call before getting any usage data. On
9599 some systems (notably SunOS), doing this yields more up to date results,
9600 but in general this option makes @command{df} much slower, especially when
9601 there are many or very busy file systems.
9603 @item -t @var{fstype}
9604 @itemx --type=@var{fstype}
9607 @cindex file system types, limiting output to certain
9608 Limit the listing to file systems of type @var{fstype}. Multiple
9609 file system types can be specified by giving multiple @option{-t} options.
9610 By default, nothing is omitted.
9615 @opindex --print-type
9616 @cindex file system types, printing
9617 Print each file system's type. The types printed here are the same ones
9618 you can include or exclude with @option{-t} and @option{-x}. The particular
9619 types printed are whatever is supported by the system. Here are some of
9620 the common names (this list is certainly not exhaustive):
9625 @cindex @acronym{NFS} file system type
9626 An @acronym{NFS} file system, i.e., one mounted over a network from another
9627 machine. This is the one type name which seems to be used uniformly by
9630 @item 4.2@r{, }ufs@r{, }efs@dots{}
9631 @cindex Linux file system types
9632 @cindex local file system types
9633 @opindex 4.2 @r{file system type}
9634 @opindex ufs @r{file system type}
9635 @opindex efs @r{file system type}
9636 A file system on a locally-mounted hard disk. (The system might even
9637 support more than one type here; Linux does.)
9639 @item hsfs@r{, }cdfs
9640 @cindex CD-ROM file system type
9641 @cindex High Sierra file system
9642 @opindex hsfs @r{file system type}
9643 @opindex cdfs @r{file system type}
9644 A file system on a CD-ROM drive. HP-UX uses @samp{cdfs}, most other
9645 systems use @samp{hsfs} (@samp{hs} for ``High Sierra'').
9648 @cindex PC file system
9649 @cindex DOS file system
9650 @cindex MS-DOS file system
9651 @cindex diskette file system
9653 An MS-DOS file system, usually on a diskette.
9657 @item -x @var{fstype}
9658 @itemx --exclude-type=@var{fstype}
9660 @opindex --exclude-type
9661 Limit the listing to file systems not of type @var{fstype}.
9662 Multiple file system types can be eliminated by giving multiple
9663 @option{-x} options. By default, no file system types are omitted.
9666 Ignored; for compatibility with System V versions of @command{df}.
9671 Failure includes the case where no output is generated, so you can
9672 inspect the exit status of a command like @samp{df -t ext3 -t reiserfs
9673 @var{dir}} to test whether @var{dir} is on a file system of type
9674 @samp{ext3} or @samp{reiserfs}.
9678 @section @command{du}: Estimate file space usage
9681 @cindex file space usage
9682 @cindex disk usage for files
9684 @command{du} reports the amount of disk space used by the specified files
9685 and for each subdirectory (of directory arguments). Synopsis:
9688 du [@var{option}]@dots{} [@var{file}]@dots{}
9691 With no arguments, @command{du} reports the disk space for the current
9692 directory. Normally the disk space is printed in units of
9693 1024 bytes, but this can be overridden (@pxref{Block size}).
9694 Non-integer quantities are rounded up to the next higher unit.
9696 If two or more hard links point to the same file, only one of the hard
9697 links is counted. The @var{file} argument order affects which links
9698 are counted, and changing the argument order may change the numbers
9699 that @command{du} outputs.
9701 The program accepts the following options. Also see @ref{Common options}.
9709 Show counts for all files, not just directories.
9711 @itemx --apparent-size
9712 @opindex --apparent-size
9713 Print apparent sizes, rather than disk usage. The apparent size of a
9714 file is the number of bytes reported by @code{wc -c} on regular files,
9715 or more generally, @code{ls -l --block-size=1} or @code{stat --format=%s}.
9716 For example, a file containing the word @samp{zoo} with no newline would,
9717 of course, have an apparent size of 3. Such a small file may require
9718 anywhere from 0 to 16 KiB or more of disk space, depending on
9719 the type and configuration of the file system on which the file resides.
9720 However, a sparse file created with this command:
9723 dd bs=1 seek=2GiB if=/dev/null of=big
9727 has an apparent size of 2 GiB, yet on most modern
9728 systems, it actually uses almost no disk space.
9734 Equivalent to @code{--apparent-size --block-size=1}.
9737 @itemx --block-size=@var{size}
9739 @opindex --block-size
9741 Scale sizes by @var{size} before printing them (@pxref{Block size}).
9742 For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes.
9748 @cindex grand total of disk space
9749 Print a grand total of all arguments after all arguments have
9750 been processed. This can be used to find out the total disk usage of
9751 a given set of files or directories.
9754 @itemx --dereference-args
9756 @opindex --dereference-args
9757 Dereference symbolic links that are command line arguments.
9758 Does not affect other symbolic links. This is helpful for finding
9759 out the disk usage of directories, such as @file{/usr/tmp}, which
9760 are often symbolic links.
9762 @c --files0-from=FILE
9763 @filesZeroFromOption{du, with the @option{--total} (@option{-c}) option}
9769 Currently, @option{-H} is the same as @option{--si},
9770 except that @option{-H} evokes a warning.
9771 This option will be changed to be equivalent to
9772 @option{--dereference-args} (@option{-D}).
9776 @cindex kibibytes for file sizes
9777 Print sizes in 1024-byte blocks, overriding the default block size
9778 (@pxref{Block size}).
9779 This option is equivalent to @option{--block-size=1K}.
9782 @itemx --count-links
9784 @opindex --count-links
9785 @cindex hard links, counting in @command{du}
9786 Count the size of all files, even if they have appeared already (as a
9790 @itemx --dereference
9792 @opindex --dereference
9793 @cindex symbolic links, dereferencing in @command{du}
9794 Dereference symbolic links (show the disk space used by the file
9795 or directory that the link points to instead of the space used by
9800 @cindex mebibytes for file sizes
9801 Print sizes in 1,048,576-byte blocks, overriding the default block size
9802 (@pxref{Block size}).
9803 This option is equivalent to @option{--block-size=1M}.
9806 @itemx --no-dereference
9808 @opindex --no-dereference
9809 @cindex symbolic links, dereferencing in @command{du}
9810 For each symbolic links encountered by @command{du},
9811 consider the disk space used by the symbolic link.
9813 @item --max-depth=@var{DEPTH}
9814 @opindex --max-depth=@var{DEPTH}
9815 @cindex limiting output of @command{du}
9816 Show the total for each directory (and file if --all) that is at
9817 most MAX_DEPTH levels down from the root of the hierarchy. The root
9818 is at level 0, so @code{du --max-depth=0} is equivalent to @code{du -s}.
9824 @cindex output null-byte-terminated lines
9825 Output a null byte at the end of each line, rather than a newline.
9826 This option enables other programs to parse the output of @command{du}
9827 even when that output would contain file names with embedded newlines.
9834 @opindex --summarize
9835 Display only a total for each argument.
9838 @itemx --separate-dirs
9840 @opindex --separate-dirs
9841 Report the size of each directory separately, not including the sizes
9846 @cindex last modified dates, displaying in @command{du}
9847 Show time of the most recent modification of any file in the directory,
9848 or any of its subdirectories.
9851 @itemx --time=status
9854 @opindex ctime@r{, show the most recent}
9855 @opindex status time@r{, show the most recent}
9856 @opindex use time@r{, show the most recent}
9857 Show the most recent status change time (the @samp{ctime} in the inode) of
9858 any file in the directory, instead of the modification time.
9861 @itemx --time=access
9863 @opindex atime@r{, show the most recent}
9864 @opindex access time@r{, show the most recent}
9865 Show the most recent access time (the @samp{atime} in the inode) of
9866 any file in the directory, instead of the modification time.
9868 @item --time-style=@var{style}
9869 @opindex --time-style
9871 List timestamps in style @var{style}. This option has an effect only if
9872 the @option{--time} option is also specified. The @var{style} should
9873 be one of the following:
9878 List timestamps using @var{format}, where @var{format} is interpreted
9879 like the format argument of @command{date} (@pxref{date invocation}).
9880 For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes
9881 @command{du} to list timestamps like @samp{2002-03-30 23:45:56}. As
9882 with @command{date}, @var{format}'s interpretation is affected by the
9883 @env{LC_TIME} locale category.
9886 List timestamps in full using @acronym{ISO} 8601 date, time, and time zone
9887 format with nanosecond precision, e.g., @samp{2002-03-30
9888 23:45:56.477817180 -0700}. This style is equivalent to
9889 @samp{+%Y-%m-%d %H:%M:%S.%N %z}.
9892 List @acronym{ISO} 8601 date and time in minutes, e.g.,
9893 @samp{2002-03-30 23:45}. These timestamps are shorter than
9894 @samp{full-iso} timestamps, and are usually good enough for everyday
9895 work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}.
9898 List @acronym{ISO} 8601 dates for timestamps, e.g., @samp{2002-03-30}.
9899 This style is equivalent to @samp{+%Y-%m-%d}.
9903 You can specify the default value of the @option{--time-style} option
9904 with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set
9905 the default style is @samp{long-iso}. For compatibility with @command{ls},
9906 if @env{TIME_STYLE} begins with @samp{+} and contains a newline,
9907 the newline and any later characters are ignored; if @env{TIME_STYLE}
9908 begins with @samp{posix-} the @samp{posix-} is ignored; and if
9909 @env{TIME_STYLE} is @samp{locale} it is ignored.
9912 @itemx --one-file-system
9914 @opindex --one-file-system
9915 @cindex one file system, restricting @command{du} to
9916 Skip directories that are on different file systems from the one that
9917 the argument being processed is on.
9919 @item --exclude=@var{PATTERN}
9920 @opindex --exclude=@var{PATTERN}
9921 @cindex excluding files from @command{du}
9922 When recursing, skip subdirectories or files matching @var{PATTERN}.
9923 For example, @code{du --exclude='*.o'} excludes files whose names
9927 @itemx --exclude-from=@var{FILE}
9928 @opindex -X @var{FILE}
9929 @opindex --exclude-from=@var{FILE}
9930 @cindex excluding files from @command{du}
9931 Like @option{--exclude}, except take the patterns to exclude from @var{FILE},
9932 one per line. If @var{FILE} is @samp{-}, take the patterns from standard
9937 @cindex NFS mounts from BSD to HP-UX
9938 On BSD systems, @command{du} reports sizes that are half the correct
9939 values for files that are NFS-mounted from HP-UX systems. On HP-UX
9940 systems, it reports sizes that are twice the correct values for
9941 files that are NFS-mounted from BSD systems. This is due to a flaw
9942 in HP-UX; it also affects the HP-UX @command{du} program.
9947 @node stat invocation
9948 @section @command{stat}: Report file or file system status
9952 @cindex file system status
9954 @command{stat} displays information about the specified file(s). Synopsis:
9957 stat [@var{option}]@dots{} [@var{file}]@dots{}
9960 With no option, @command{stat} reports all information about the given files.
9961 But it also can be used to report the information of the file systems the
9962 given files are located on. If the files are links, @command{stat} can
9963 also give information about the files the links point to.
9969 @itemx --dereference
9971 @opindex --dereference
9972 @cindex symbolic links, dereferencing in @command{stat}
9973 Change how @command{stat} treats symbolic links.
9974 With this option, @command{stat} acts on the file referenced
9975 by each symbolic link argument.
9976 Without it, @command{stat} acts on any symbolic link argument directly.
9979 @itemx --file-system
9981 @opindex --file-system
9982 @cindex file systems
9983 Report information about the file systems where the given files are located
9984 instead of information about the files themselves.
9987 @itemx --format=@var{format}
9989 @opindex --format=@var{format}
9990 @cindex output format
9991 Use @var{format} rather than the default format.
9992 @var{format} is automatically newline-terminated, so
9993 running a command like the following with two or more @var{file}
9994 operands produces a line of output for each operand:
9996 $ stat --format=%d:%i / /usr
10001 @itemx --printf=@var{format}
10002 @opindex --printf=@var{format}
10003 @cindex output format
10004 Use @var{format} rather than the default format.
10005 Like @option{--format}, but interpret backslash escapes,
10006 and do not output a mandatory trailing newline.
10007 If you want a newline, include @samp{\n} in the @var{format}.
10008 Here's how you would use @option{--printf} to print the device
10009 and inode numbers of @file{/} and @file{/usr}:
10011 $ stat --printf='%d:%i\n' / /usr
10020 @cindex terse output
10021 Print the information in terse form, suitable for parsing by other programs.
10023 The valid format sequences for files are:
10026 @item %a - Access rights in octal
10027 @item %A - Access rights in human readable form
10028 @item %b - Number of blocks allocated (see @samp{%B})
10029 @item %B - The size in bytes of each block reported by @samp{%b}
10030 @item %d - Device number in decimal
10031 @item %D - Device number in hex
10032 @item %f - Raw mode in hex
10033 @item %F - File type
10034 @item %g - Group ID of owner
10035 @item %G - Group name of owner
10036 @item %h - Number of hard links
10037 @item %i - Inode number
10038 @item %n - File name
10039 @item %N - Quoted file name with dereference if symbolic link
10040 @item %o - I/O block size
10041 @item %s - Total size, in bytes
10042 @item %t - Major device type in hex
10043 @item %T - Minor device type in hex
10044 @item %u - User ID of owner
10045 @item %U - User name of owner
10046 @item %x - Time of last access
10047 @item %X - Time of last access as seconds since Epoch
10048 @item %y - Time of last modification
10049 @item %Y - Time of last modification as seconds since Epoch
10050 @item %z - Time of last change
10051 @item %Z - Time of last change as seconds since Epoch
10054 The valid format sequences for file systems are:
10057 @item %a - Free blocks available to non-super-user
10058 @item %b - Total data blocks in file system
10059 @item %c - Total file nodes in file system
10060 @item %d - Free file nodes in file system
10061 @item %f - Free blocks in file system
10062 @item %i - File System ID in hex
10063 @item %l - Maximum length of file names
10064 @item %n - File name
10065 @item %s - Block size (for faster transfers)
10066 @item %S - Fundamental block size (for block counts)
10067 @item %t - Type in hex
10068 @item %T - Type in human readable form
10072 Time stamps are listed according to the time zone rules specified by
10073 the @env{TZ} environment variable, or by the system default rules if
10074 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
10075 with @env{TZ}, libc, The GNU C Library Reference Manual}.
10081 @node sync invocation
10082 @section @command{sync}: Synchronize data on disk with memory
10085 @cindex synchronize disk and memory
10087 @cindex superblock, writing
10088 @cindex inodes, written buffered
10089 @command{sync} writes any data buffered in memory out to disk. This can
10090 include (but is not limited to) modified superblocks, modified inodes,
10091 and delayed reads and writes. This must be implemented by the kernel;
10092 The @command{sync} program does nothing but exercise the @code{sync} system
10095 @cindex crashes and corruption
10096 The kernel keeps data in memory to avoid doing (relatively slow) disk
10097 reads and writes. This improves performance, but if the computer
10098 crashes, data may be lost or the file system corrupted as a
10099 result. The @command{sync} command ensures everything in memory
10100 is written to disk.
10102 Any arguments are ignored, except for a lone @option{--help} or
10103 @option{--version} (@pxref{Common options}).
10108 @node Printing text
10109 @chapter Printing text
10111 @cindex printing text, commands for
10112 @cindex commands for printing text
10114 This section describes commands that display text strings.
10117 * echo invocation:: Print a line of text.
10118 * printf invocation:: Format and print data.
10119 * yes invocation:: Print a string until interrupted.
10123 @node echo invocation
10124 @section @command{echo}: Print a line of text
10127 @cindex displaying text
10128 @cindex printing text
10129 @cindex text, displaying
10130 @cindex arbitrary text, displaying
10132 @command{echo} writes each given @var{string} to standard output, with a
10133 space between each and a newline after the last one. Synopsis:
10136 echo [@var{option}]@dots{} [@var{string}]@dots{}
10139 The program accepts the following options. Also see @ref{Common options}.
10140 Options must precede operands, and the normally-special argument
10141 @samp{--} has no special meaning and is treated like any other
10147 Do not output the trailing newline.
10151 @cindex backslash escapes
10152 Enable interpretation of the following backslash-escaped characters in
10161 suppress trailing newline
10175 the eight-bit value that is the octal number @var{nnn}
10176 (zero to three octal digits)
10178 the eight-bit value that is the octal number @var{nnn}
10179 (one to three octal digits)
10181 the eight-bit value that is the hexadecimal number @var{hh}
10182 (one or two hexadecimal digits)
10187 @cindex backslash escapes
10188 Disable interpretation of backslash escapes in each @var{string}.
10189 This is the default. If @option{-e} and @option{-E} are both
10190 specified, the last one given takes effect.
10194 @vindex POSIXLY_CORRECT
10195 If the @env{POSIXLY_CORRECT} environment variable is set, then when
10196 @command{echo}'s first argument is not @option{-n} it outputs
10197 option-like arguments instead of treating them as options. For
10198 example, @code{echo -ne hello} outputs @samp{-ne hello} instead of
10199 plain @samp{hello}.
10201 @acronym{POSIX} does not require support for any options, and says
10202 that the behavior of @command{echo} is implementation-defined if any
10203 @var{string} contains a backslash or if the first argument is
10204 @option{-n}. Portable programs can use the @command{printf} command
10205 if they need to omit trailing newlines or output control characters or
10206 backslashes. @xref{printf invocation}.
10211 @node printf invocation
10212 @section @command{printf}: Format and print data
10215 @command{printf} does formatted printing of text. Synopsis:
10218 printf @var{format} [@var{argument}]@dots{}
10221 @command{printf} prints the @var{format} string, interpreting @samp{%}
10222 directives and @samp{\} escapes to format numeric and string arguments
10223 in a way that is mostly similar to the C @samp{printf} function.
10224 @xref{Output Conversion Syntax,, @command{printf} format directives,
10225 libc, The GNU C Library Reference Manual}, for details.
10226 The differences are as follows:
10231 The @var{format} argument is reused as necessary to convert all the
10232 given @var{argument}s. For example, the command @samp{printf %s a b}
10236 Missing @var{argument}s are treated as null strings or as zeros,
10237 depending on whether the context expects a string or a number. For
10238 example, the command @samp{printf %sx%d} prints @samp{x0}.
10242 An additional escape, @samp{\c}, causes @command{printf} to produce no
10243 further output. For example, the command @samp{printf 'A%sC\cD%sF' B
10244 E} prints @samp{ABC}.
10247 The hexadecimal escape sequence @samp{\x@var{hh}} has at most two
10248 digits, as opposed to C where it can have an unlimited number of
10249 digits. For example, the command @samp{printf '\x07e'} prints two
10250 bytes, whereas the C statement @samp{printf ("\x07e")} prints just
10255 @command{printf} has an additional directive, @samp{%b}, which prints its
10256 argument string with @samp{\} escapes interpreted in the same way as in
10257 the @var{format} string, except that octal escapes are of the form
10258 @samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits.
10259 If a precision is also given, it limits the number of bytes printed
10260 from the converted string.
10263 Numeric arguments must be single C constants, possibly with leading
10264 @samp{+} or @samp{-}. For example, @samp{printf %.4d -3} outputs
10268 @vindex POSIXLY_CORRECT
10269 If the leading character of a numeric argument is @samp{"} or @samp{'}
10270 then its value is the numeric value of the immediately following
10271 character. Any remaining characters are silently ignored if the
10272 @env{POSIXLY_CORRECT} environment variable is set; otherwise, a
10273 warning is printed. For example, @samp{printf "%d" "'a"} outputs
10274 @samp{97} on hosts that use the @acronym{ASCII} character set, since
10275 @samp{a} has the numeric value 97 in @acronym{ASCII}.
10280 A floating-point argument must use a period before any fractional
10281 digits, but is printed according to the @env{LC_NUMERIC} category of the
10282 current locale. For example, in a locale whose radix character is a
10283 comma, the command @samp{printf %g 3.14} outputs @samp{3,14} whereas
10284 the command @samp{printf %g 3,14} is an error.
10288 @command{printf} interprets @samp{\@var{ooo}} in @var{format} as an octal number
10289 (if @var{ooo} is 1 to 3 octal digits) specifying a character to print,
10290 and @samp{\x@var{hh}} as a hexadecimal number (if @var{hh} is 1 to 2 hex
10291 digits) specifying a character to print.
10296 @cindex ISO/IEC 10646
10298 @command{printf} interprets two character syntaxes introduced in
10299 @acronym{ISO} C 99:
10300 @samp{\u} for 16-bit Unicode (@acronym{ISO}/@acronym{IEC} 10646)
10301 characters, specified as
10302 four hexadecimal digits @var{hhhh}, and @samp{\U} for 32-bit Unicode
10303 characters, specified as eight hexadecimal digits @var{hhhhhhhh}.
10304 @command{printf} outputs the Unicode characters
10305 according to the @env{LC_CTYPE} locale.
10307 The processing of @samp{\u} and @samp{\U} requires a full-featured
10308 @code{iconv} facility. It is activated on systems with glibc 2.2 (or newer),
10309 or when @code{libiconv} is installed prior to this package. Otherwise
10310 @samp{\u} and @samp{\U} will print as-is.
10312 The only options are a lone @option{--help} or
10313 @option{--version}. @xref{Common options}.
10314 Options must precede operands.
10316 The Unicode character syntaxes are useful for writing strings in a locale
10317 independent way. For example, a string containing the Euro currency symbol
10320 $ /usr/local/bin/printf '\u20AC 14.95'
10324 will be output correctly in all locales supporting the Euro symbol
10325 (@acronym{ISO}-8859-15, UTF-8, and others). Similarly, a Chinese string
10328 $ /usr/local/bin/printf '\u4e2d\u6587'
10332 will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8, etc).
10334 Note that in these examples, the full name of @command{printf} has been
10335 given, to distinguish it from the GNU @code{bash} built-in function
10338 For larger strings, you don't need to look up the hexadecimal code
10339 values of each character one by one. @acronym{ASCII} characters mixed with \u
10340 escape sequences is also known as the JAVA source file encoding. You can
10341 use GNU recode 3.5c (or newer) to convert strings to this encoding. Here
10342 is how to convert a piece of text into a shell script which will output
10343 this text in a locale-independent way:
10346 $ LC_CTYPE=zh_CN.big5 /usr/local/bin/printf \
10347 '\u4e2d\u6587\n' > sample.txt
10348 $ recode BIG5..JAVA < sample.txt \
10349 | sed -e "s|^|/usr/local/bin/printf '|" -e "s|$|\\\\n'|" \
10356 @node yes invocation
10357 @section @command{yes}: Print a string until interrupted
10360 @cindex repeated output of a string
10362 @command{yes} prints the command line arguments, separated by spaces and
10363 followed by a newline, forever until it is killed. If no arguments are
10364 given, it prints @samp{y} followed by a newline forever until killed.
10366 Upon a write error, @command{yes} exits with status @samp{1}.
10368 The only options are a lone @option{--help} or @option{--version}.
10369 To output an argument that begins with
10370 @samp{-}, precede it with @option{--}, e.g., @samp{yes -- --help}.
10371 @xref{Common options}.
10375 @chapter Conditions
10378 @cindex commands for exit status
10379 @cindex exit status commands
10381 This section describes commands that are primarily useful for their exit
10382 status, rather than their output. Thus, they are often used as the
10383 condition of shell @code{if} statements, or as the last command in a
10387 * false invocation:: Do nothing, unsuccessfully.
10388 * true invocation:: Do nothing, successfully.
10389 * test invocation:: Check file types and compare values.
10390 * expr invocation:: Evaluate expressions.
10394 @node false invocation
10395 @section @command{false}: Do nothing, unsuccessfully
10398 @cindex do nothing, unsuccessfully
10399 @cindex failure exit status
10400 @cindex exit status of @command{false}
10402 @command{false} does nothing except return an exit status of 1, meaning
10403 @dfn{failure}. It can be used as a place holder in shell scripts
10404 where an unsuccessful command is needed.
10405 In most modern shells, @command{false} is a built-in command, so when
10406 you use @samp{false} in a script, you're probably using the built-in
10407 command, not the one documented here.
10409 @command{false} honors the @option{--help} and @option{--version} options.
10411 This version of @command{false} is implemented as a C program, and is thus
10412 more secure and faster than a shell script implementation, and may safely
10413 be used as a dummy shell for the purpose of disabling accounts.
10415 Note that @command{false} (unlike all other programs documented herein)
10416 exits unsuccessfully, even when invoked with
10417 @option{--help} or @option{--version}.
10419 Portable programs should not assume that the exit status of
10420 @command{false} is 1, as it is greater than 1 on some
10421 non-@acronym{GNU} hosts.
10424 @node true invocation
10425 @section @command{true}: Do nothing, successfully
10428 @cindex do nothing, successfully
10430 @cindex successful exit
10431 @cindex exit status of @command{true}
10433 @command{true} does nothing except return an exit status of 0, meaning
10434 @dfn{success}. It can be used as a place holder in shell scripts
10435 where a successful command is needed, although the shell built-in
10436 command @code{:} (colon) may do the same thing faster.
10437 In most modern shells, @command{true} is a built-in command, so when
10438 you use @samp{true} in a script, you're probably using the built-in
10439 command, not the one documented here.
10441 @command{true} honors the @option{--help} and @option{--version} options.
10443 Note, however, that it is possible to cause @command{true}
10444 to exit with nonzero status: with the @option{--help} or @option{--version}
10445 option, and with standard
10446 output already closed or redirected to a file that evokes an I/O error.
10447 For example, using a Bourne-compatible shell:
10450 $ ./true --version >&-
10451 ./true: write error: Bad file number
10452 $ ./true --version > /dev/full
10453 ./true: write error: No space left on device
10456 This version of @command{true} is implemented as a C program, and is thus
10457 more secure and faster than a shell script implementation, and may safely
10458 be used as a dummy shell for the purpose of disabling accounts.
10460 @node test invocation
10461 @section @command{test}: Check file types and compare values
10464 @cindex check file types
10465 @cindex compare values
10466 @cindex expression evaluation
10468 @command{test} returns a status of 0 (true) or 1 (false) depending on the
10469 evaluation of the conditional expression @var{expr}. Each part of the
10470 expression must be a separate argument.
10472 @command{test} has file status checks, string operators, and numeric
10473 comparison operators.
10475 @command{test} has an alternate form that uses opening and closing
10476 square brackets instead a leading @samp{test}. For example, instead
10477 of @samp{test -d /}, you can write @samp{[ -d / ]}. The square
10478 brackets must be separate arguments; for example, @samp{[-d /]} does
10479 not have the desired effect. Since @samp{test @var{expr}} and @samp{[
10480 @var{expr} ]} have the same meaning, only the former form is discussed
10486 test @var{expression}
10488 [ @var{expression} ]
10493 @cindex conflicts with shell built-ins
10494 @cindex built-in shell commands, conflicts with
10495 Because most shells have a built-in @command{test} command, using an
10496 unadorned @command{test} in a script or interactively may get you
10497 different functionality than that described here.
10499 If @var{expression} is omitted, @command{test} returns false.
10500 If @var{expression} is a single argument,
10501 @command{test} returns false if the argument is null and true otherwise. The argument
10502 can be any string, including strings like @samp{-d}, @samp{-1},
10503 @samp{--}, @samp{--help}, and @samp{--version} that most other
10504 programs would treat as options. To get help and version information,
10505 invoke the commands @samp{[ --help} and @samp{[ --version}, without
10506 the usual closing brackets. @xref{Common options}.
10508 @cindex exit status of @command{test}
10512 0 if the expression is true,
10513 1 if the expression is false,
10514 2 if an error occurred.
10518 * File type tests:: -[bcdfhLpSt]
10519 * Access permission tests:: -[gkruwxOG]
10520 * File characteristic tests:: -e -s -nt -ot -ef
10521 * String tests:: -z -n = !=
10522 * Numeric tests:: -eq -ne -lt -le -gt -ge
10523 * Connectives for test:: ! -a -o
10527 @node File type tests
10528 @subsection File type tests
10530 @cindex file type tests
10532 These options test for particular types of files. (Everything's a file,
10533 but not all files are the same!)
10537 @item -b @var{file}
10539 @cindex block special check
10540 True if @var{file} exists and is a block special device.
10542 @item -c @var{file}
10544 @cindex character special check
10545 True if @var{file} exists and is a character special device.
10547 @item -d @var{file}
10549 @cindex directory check
10550 True if @var{file} exists and is a directory.
10552 @item -f @var{file}
10554 @cindex regular file check
10555 True if @var{file} exists and is a regular file.
10557 @item -h @var{file}
10558 @itemx -L @var{file}
10561 @cindex symbolic link check
10562 True if @var{file} exists and is a symbolic link.
10563 Unlike all other file-related tests, this test does not dereference
10564 @var{file} if it is a symbolic link.
10566 @item -p @var{file}
10568 @cindex named pipe check
10569 True if @var{file} exists and is a named pipe.
10571 @item -S @var{file}
10573 @cindex socket check
10574 True if @var{file} exists and is a socket.
10578 @cindex terminal check
10579 True if @var{fd} is a file descriptor that is associated with a
10585 @node Access permission tests
10586 @subsection Access permission tests
10588 @cindex access permission tests
10589 @cindex permission tests
10591 These options test for particular access permissions.
10595 @item -g @var{file}
10597 @cindex set-group-ID check
10598 True if @var{file} exists and has its set-group-ID bit set.
10600 @item -k @var{file}
10602 @cindex sticky bit check
10603 True if @var{file} exists and has its @dfn{sticky} bit set.
10605 @item -r @var{file}
10607 @cindex readable file check
10608 True if @var{file} exists and read permission is granted.
10610 @item -u @var{file}
10612 @cindex set-user-ID check
10613 True if @var{file} exists and has its set-user-ID bit set.
10615 @item -w @var{file}
10617 @cindex writable file check
10618 True if @var{file} exists and write permission is granted.
10620 @item -x @var{file}
10622 @cindex executable file check
10623 True if @var{file} exists and execute permission is granted
10624 (or search permission, if it is a directory).
10626 @item -O @var{file}
10628 @cindex owned by effective user ID check
10629 True if @var{file} exists and is owned by the current effective user ID.
10631 @item -G @var{file}
10633 @cindex owned by effective group ID check
10634 True if @var{file} exists and is owned by the current effective group ID.
10638 @node File characteristic tests
10639 @subsection File characteristic tests
10641 @cindex file characteristic tests
10643 These options test other file characteristics.
10647 @item -e @var{file}
10649 @cindex existence-of-file check
10650 True if @var{file} exists.
10652 @item -s @var{file}
10654 @cindex nonempty file check
10655 True if @var{file} exists and has a size greater than zero.
10657 @item @var{file1} -nt @var{file2}
10659 @cindex newer-than file check
10660 True if @var{file1} is newer (according to modification date) than
10661 @var{file2}, or if @var{file1} exists and @var{file2} does not.
10663 @item @var{file1} -ot @var{file2}
10665 @cindex older-than file check
10666 True if @var{file1} is older (according to modification date) than
10667 @var{file2}, or if @var{file2} exists and @var{file1} does not.
10669 @item @var{file1} -ef @var{file2}
10671 @cindex same file check
10672 @cindex hard link check
10673 True if @var{file1} and @var{file2} have the same device and inode
10674 numbers, i.e., if they are hard links to each other.
10680 @subsection String tests
10682 @cindex string tests
10684 These options test string characteristics. You may need to quote
10685 @var{string} arguments for the shell. For example:
10691 The quotes here prevent the wrong arguments from being passed to
10692 @command{test} if @samp{$V} is empty or contains special characters.
10696 @item -z @var{string}
10698 @cindex zero-length string check
10699 True if the length of @var{string} is zero.
10701 @item -n @var{string}
10702 @itemx @var{string}
10704 @cindex nonzero-length string check
10705 True if the length of @var{string} is nonzero.
10707 @item @var{string1} = @var{string2}
10709 @cindex equal string check
10710 True if the strings are equal.
10712 @item @var{string1} != @var{string2}
10714 @cindex not-equal string check
10715 True if the strings are not equal.
10720 @node Numeric tests
10721 @subsection Numeric tests
10723 @cindex numeric tests
10724 @cindex arithmetic tests
10726 Numeric relational operators. The arguments must be entirely numeric
10727 (possibly negative), or the special expression @w{@code{-l @var{string}}},
10728 which evaluates to the length of @var{string}.
10732 @item @var{arg1} -eq @var{arg2}
10733 @itemx @var{arg1} -ne @var{arg2}
10734 @itemx @var{arg1} -lt @var{arg2}
10735 @itemx @var{arg1} -le @var{arg2}
10736 @itemx @var{arg1} -gt @var{arg2}
10737 @itemx @var{arg1} -ge @var{arg2}
10744 These arithmetic binary operators return true if @var{arg1} is equal,
10745 not-equal, less-than, less-than-or-equal, greater-than, or
10746 greater-than-or-equal than @var{arg2}, respectively.
10753 test -1 -gt -2 && echo yes
10755 test -l abc -gt 1 && echo yes
10758 @error{} test: integer expression expected before -eq
10762 @node Connectives for test
10763 @subsection Connectives for @command{test}
10765 @cindex logical connectives
10766 @cindex connectives, logical
10768 The usual logical connectives.
10774 True if @var{expr} is false.
10776 @item @var{expr1} -a @var{expr2}
10778 @cindex logical and operator
10779 @cindex and operator
10780 True if both @var{expr1} and @var{expr2} are true.
10782 @item @var{expr1} -o @var{expr2}
10784 @cindex logical or operator
10785 @cindex or operator
10786 True if either @var{expr1} or @var{expr2} is true.
10791 @node expr invocation
10792 @section @command{expr}: Evaluate expressions
10795 @cindex expression evaluation
10796 @cindex evaluation of expressions
10798 @command{expr} evaluates an expression and writes the result on standard
10799 output. Each token of the expression must be a separate argument.
10801 Operands are either integers or strings. Integers consist of one or
10802 more decimal digits, with an optional leading @samp{-}.
10803 @command{expr} converts
10804 anything appearing in an operand position to an integer or a string
10805 depending on the operation being applied to it.
10807 Strings are not quoted for @command{expr} itself, though you may need to
10808 quote them to protect characters with special meaning to the shell,
10809 e.g., spaces. However, regardless of whether it is quoted, a string
10810 operand should not be a parenthesis or any of @command{expr}'s
10811 operators like @code{+}, so you cannot safely pass an arbitrary string
10812 @code{$str} to expr merely by quoting it to the shell. One way to
10813 work around this is to use the @sc{gnu} extension @code{+},
10814 (e.g., @code{+ "$str" = foo}); a more portable way is to use
10815 @code{@w{" $str"}} and to adjust the rest of the expression to take
10816 the leading space into account (e.g., @code{@w{" $str" = " foo"}}).
10818 You should not pass a negative integer or a string with leading
10819 @samp{-} as @command{expr}'s first argument, as it might be
10820 misinterpreted as an option; this can be avoided by parenthesization.
10821 Also, portable scripts should not use a string operand that happens to
10822 take the form of an integer; this can be worked around by inserting
10823 leading spaces as mentioned above.
10825 @cindex parentheses for grouping
10826 Operators may be given as infix symbols or prefix keywords. Parentheses
10827 may be used for grouping in the usual manner. You must quote
10828 parentheses and many operators to avoid the shell evaluating them,
10831 The only options are @option{--help} and @option{--version}. @xref{Common
10832 options}. Options must precede operands.
10834 @cindex exit status of @command{expr}
10838 0 if the expression is neither null nor 0,
10839 1 if the expression is null or 0,
10840 2 if the expression is invalid,
10841 3 if an internal error occurred (e.g., arithmetic overflow).
10845 * String expressions:: + : match substr index length
10846 * Numeric expressions:: + - * / %
10847 * Relations for expr:: | & < <= = == != >= >
10848 * Examples of expr:: Examples.
10852 @node String expressions
10853 @subsection String expressions
10855 @cindex string expressions
10856 @cindex expressions, string
10858 @command{expr} supports pattern matching and other string operators. These
10859 have higher precedence than both the numeric and relational operators (in
10860 the next sections).
10864 @item @var{string} : @var{regex}
10865 @cindex pattern matching
10866 @cindex regular expression matching
10867 @cindex matching patterns
10868 Perform pattern matching. The arguments are converted to strings and the
10869 second is considered to be a (basic, a la GNU @code{grep}) regular
10870 expression, with a @code{^} implicitly prepended. The first argument is
10871 then matched against this regular expression.
10873 If the match succeeds and @var{regex} uses @samp{\(} and @samp{\)}, the
10874 @code{:} expression returns the part of @var{string} that matched the
10875 subexpression; otherwise, it returns the number of characters matched.
10877 If the match fails, the @code{:} operator returns the null string if
10878 @samp{\(} and @samp{\)} are used in @var{regex}, otherwise 0.
10880 @kindex \( @r{regexp operator}
10881 Only the first @samp{\( @dots{} \)} pair is relevant to the return
10882 value; additional pairs are meaningful only for grouping the regular
10883 expression operators.
10885 @kindex \+ @r{regexp operator}
10886 @kindex \? @r{regexp operator}
10887 @kindex \| @r{regexp operator}
10888 In the regular expression, @code{\+}, @code{\?}, and @code{\|} are
10889 operators which respectively match one or more, zero or one, or separate
10890 alternatives. SunOS and other @command{expr}'s treat these as regular
10891 characters. (@acronym{POSIX} allows either behavior.)
10892 @xref{Top, , Regular Expression Library, regex, Regex}, for details of
10893 regular expression syntax. Some examples are in @ref{Examples of expr}.
10895 @item match @var{string} @var{regex}
10897 An alternative way to do pattern matching. This is the same as
10898 @w{@samp{@var{string} : @var{regex}}}.
10900 @item substr @var{string} @var{position} @var{length}
10902 Returns the substring of @var{string} beginning at @var{position}
10903 with length at most @var{length}. If either @var{position} or
10904 @var{length} is negative, zero, or non-numeric, returns the null string.
10906 @item index @var{string} @var{charset}
10908 Returns the first position in @var{string} where the first character in
10909 @var{charset} was found. If no character in @var{charset} is found in
10910 @var{string}, return 0.
10912 @item length @var{string}
10914 Returns the length of @var{string}.
10916 @item + @var{token}
10918 Interpret @var{token} as a string, even if it is a keyword like @var{match}
10919 or an operator like @code{/}.
10920 This makes it possible to test @code{expr length + "$x"} or
10921 @code{expr + "$x" : '.*/\(.\)'} and have it do the right thing even if
10922 the value of @var{$x} happens to be (for example) @code{/} or @code{index}.
10923 This operator is a @acronym{GNU} extension. Portable shell scripts should use
10924 @code{@w{" $token"} : @w{' \(.*\)'}} instead of @code{+ "$token"}.
10928 To make @command{expr} interpret keywords as strings, you must use the
10929 @code{quote} operator.
10932 @node Numeric expressions
10933 @subsection Numeric expressions
10935 @cindex numeric expressions
10936 @cindex expressions, numeric
10938 @command{expr} supports the usual numeric operators, in order of increasing
10939 precedence. These numeric operators have lower precedence than the
10940 string operators described in the previous section, and higher precedence
10941 than the connectives (next section).
10949 @cindex subtraction
10950 Addition and subtraction. Both arguments are converted to integers;
10951 an error occurs if this cannot be done.
10957 @cindex multiplication
10960 Multiplication, division, remainder. Both arguments are converted to
10961 integers; an error occurs if this cannot be done.
10966 @node Relations for expr
10967 @subsection Relations for @command{expr}
10969 @cindex connectives, logical
10970 @cindex logical connectives
10971 @cindex relations, numeric or string
10973 @command{expr} supports the usual logical connectives and relations. These
10974 have lower precedence than the string and numeric operators
10975 (previous sections). Here is the list, lowest-precedence operator first.
10981 @cindex logical or operator
10982 @cindex or operator
10983 Returns its first argument if that is neither null nor zero, otherwise
10984 its second argument if it is neither null nor zero, otherwise 0. It
10985 does not evaluate its second argument if its first argument is neither
10990 @cindex logical and operator
10991 @cindex and operator
10992 Return its first argument if neither argument is null or zero, otherwise
10993 0. It does not evaluate its second argument if its first argument is
10996 @item < <= = == != >= >
11003 @cindex comparison operators
11005 Compare the arguments and return 1 if the relation is true, 0 otherwise.
11006 @code{==} is a synonym for @code{=}. @command{expr} first tries to convert
11007 both arguments to integers and do a numeric comparison; if either
11008 conversion fails, it does a lexicographic comparison using the character
11009 collating sequence specified by the @env{LC_COLLATE} locale.
11014 @node Examples of expr
11015 @subsection Examples of using @command{expr}
11017 @cindex examples of @command{expr}
11018 Here are a few examples, including quoting for shell metacharacters.
11020 To add 1 to the shell variable @code{foo}, in Bourne-compatible shells:
11023 foo=`expr $foo + 1`
11026 To print the non-directory part of the file name stored in
11027 @code{$fname}, which need not contain a @code{/}:
11030 expr $fname : '.*/\(.*\)' '|' $fname
11033 An example showing that @code{\+} is an operator:
11041 expr abc : 'a\(.\)c'
11043 expr index abcdef cz
11046 @error{} expr: syntax error
11047 expr index quote index a
11053 @chapter Redirection
11055 @cindex redirection
11056 @cindex commands for redirection
11058 Unix shells commonly provide several forms of @dfn{redirection}---ways
11059 to change the input source or output destination of a command. But one
11060 useful redirection is performed by a separate command, not by the shell;
11061 it's described here.
11064 * tee invocation:: Redirect output to multiple files or processes.
11068 @node tee invocation
11069 @section @command{tee}: Redirect output to multiple files or processes
11072 @cindex pipe fitting
11073 @cindex destinations, multiple output
11074 @cindex read from stdin and write to stdout and files
11076 The @command{tee} command copies standard input to standard output and also
11077 to any files given as arguments. This is useful when you want not only
11078 to send some data down a pipe, but also to save a copy. Synopsis:
11081 tee [@var{option}]@dots{} [@var{file}]@dots{}
11084 If a file being written to does not already exist, it is created. If a
11085 file being written to already exists, the data it previously contained
11086 is overwritten unless the @option{-a} option is used.
11088 A @var{file} of @samp{-} causes @command{tee} to send another copy of
11089 input to standard output, but this is typically not that useful as the
11090 copies are interleaved.
11092 The program accepts the following options. Also see @ref{Common options}.
11099 Append standard input to the given files rather than overwriting
11103 @itemx --ignore-interrupts
11105 @opindex --ignore-interrupts
11106 Ignore interrupt signals.
11110 The @command{tee} command is useful when you happen to be transferring a large
11111 amount of data and also want to summarize that data without reading
11112 it a second time. For example, when you are downloading a DVD image,
11113 you often want to verify its signature or checksum right away.
11114 The inefficient way to do it is simply:
11117 wget http://example.com/some.iso && sha1sum some.iso
11120 One problem with the above is that it makes you wait for the
11121 download to complete before starting the time-consuming SHA1 computation.
11122 Perhaps even more importantly, the above requires reading
11123 the DVD image a second time (the first was from the network).
11125 The efficient way to do it is to interleave the download
11126 and SHA1 computation. Then, you'll get the checksum for
11127 free, because the entire process parallelizes so well:
11130 # slightly contrived, to demonstrate process substitution
11131 wget -O - http://example.com/dvd.iso \
11132 | tee >(sha1sum > dvd.sha1) > dvd.iso
11135 That makes @command{tee} write not just to the expected output file,
11136 but also to a pipe running @command{sha1sum} and saving the final
11137 checksum in a file named @file{dvd.sha1}.
11139 Note, however, that this example relies on a feature of modern shells
11140 called @dfn{process substitution}
11141 (the @samp{>(command)} syntax, above;
11142 @xref{Process Substitution,,Process Substitution, bashref,
11143 The Bash Reference Manual}.),
11144 so it works with @command{zsh}, @command{bash}, and @command{ksh},
11145 but not with @command{/bin/sh}. So if you write code like this
11146 in a shell script, be sure to start the script with @samp{#!/bin/bash}.
11148 Since the above example writes to one file and one process,
11149 a more conventional and portable use of @command{tee} is even better:
11152 wget -O - http://example.com/dvd.iso \
11153 | tee dvd.iso | sha1sum > dvd.sha1
11156 You can extend this example to make @command{tee} write to two processes,
11157 computing MD5 and SHA1 checksums in parallel. In this case,
11158 process substitution is required:
11161 wget -O - http://example.com/dvd.iso \
11162 | tee >(sha1sum > dvd.sha1) \
11163 >(md5sum > dvd.md5) \
11167 This technique is also useful when you want to make a @emph{compressed}
11168 copy of the contents of a pipe.
11169 Consider a tool to graphically summarize disk usage data from @samp{du -ak}.
11170 For a large hierarchy, @samp{du -ak} can run for a long time,
11171 and can easily produce terabytes of data, so you won't want to
11172 rerun the command unnecessarily. Nor will you want to save
11173 the uncompressed output.
11175 Doing it the inefficient way, you can't even start the GUI
11176 until after you've compressed all of the @command{du} output:
11179 du -ak | gzip -9 > /tmp/du.gz
11180 gzip -d /tmp/du.gz | xdiskusage -a
11183 With @command{tee} and process substitution, you start the GUI
11184 right away and eliminate the decompression completely:
11187 du -ak | tee >(gzip -9 > /tmp/du.gz) | xdiskusage -a
11190 Finally, if you regularly create more than one type of
11191 compressed tarball at once, for example when @code{make dist} creates
11192 both @command{gzip}-compressed and @command{bzip2}-compressed tarballs,
11193 there may be a better way.
11194 Typical @command{automake}-generated @file{Makefile} rules create
11195 the two compressed tar archives with commands in sequence, like this
11196 (slightly simplified):
11199 tardir=your-pkg-M.N
11200 tar chof - "$tardir" | gzip -9 -c > your-pkg-M.N.tar.gz
11201 tar chof - "$tardir" | bzip2 -9 -c > your-pkg-M.N.tar.bz2
11204 However, if the hierarchy you are archiving and compressing is larger
11205 than a couple megabytes, and especially if you are using a multi-processor
11206 system with plenty of memory, then you can do much better by reading the
11207 directory contents only once and running the compression programs in parallel:
11210 tardir=your-pkg-M.N
11211 tar chof - "$tardir" \
11212 | tee >(gzip -9 -c > your-pkg-M.N.tar.gz) \
11213 | bzip2 -9 -c > your-pkg-M.N.tar.bz2
11219 @node File name manipulation
11220 @chapter File name manipulation
11222 @cindex file name manipulation
11223 @cindex manipulation of file names
11224 @cindex commands for file name manipulation
11226 This section describes commands that manipulate file names.
11229 * basename invocation:: Strip directory and suffix from a file name.
11230 * dirname invocation:: Strip non-directory suffix from a file name.
11231 * pathchk invocation:: Check file name portability.
11235 @node basename invocation
11236 @section @command{basename}: Strip directory and suffix from a file name
11239 @cindex strip directory and suffix from file names
11240 @cindex directory, stripping from file names
11241 @cindex suffix, stripping from file names
11242 @cindex file names, stripping directory and suffix
11243 @cindex leading directory components, stripping
11245 @command{basename} removes any leading directory components from
11246 @var{name}. Synopsis:
11249 basename @var{name} [@var{suffix}]
11252 If @var{suffix} is specified and is identical to the end of @var{name},
11253 it is removed from @var{name} as well. Note that since trailing slashes
11254 are removed prior to suffix matching, @var{suffix} will do nothing if it
11255 contains slashes. @command{basename} prints the result on standard
11258 @c This test is used both here and in the section on dirname.
11259 @macro basenameAndDirname
11260 Together, @command{basename} and @command{dirname} are designed such
11261 that if @samp{ls "$name"} succeeds, then the command sequence @samp{cd
11262 "$(dirname "$name")"; ls "$(basename "$name")"} will, too. This works
11263 for everything except file names containing a trailing newline.
11265 @basenameAndDirname
11267 @acronym{POSIX} allows the implementation to define the results if
11268 @var{name} is empty or @samp{//}. In the former case, @acronym{GNU}
11269 @command{basename} returns the empty string. In the latter case, the
11270 result is @samp{//} on platforms where @var{//} is distinct from
11271 @var{/}, and @samp{/} on platforms where there is no difference.
11273 The only options are @option{--help} and @option{--version}. @xref{Common
11274 options}. Options must precede operands.
11282 basename /usr/bin/sort
11285 basename include/stdio.h .h
11289 @node dirname invocation
11290 @section @command{dirname}: Strip non-directory suffix from a file name
11293 @cindex directory components, printing
11294 @cindex stripping non-directory suffix
11295 @cindex non-directory suffix, stripping
11297 @command{dirname} prints all but the final slash-delimited component of
11298 a string (presumably a file name). Synopsis:
11304 If @var{name} is a single component, @command{dirname} prints @samp{.}
11305 (meaning the current directory).
11307 @basenameAndDirname
11309 @acronym{POSIX} allows the implementation to define the results if
11310 @var{name} is @samp{//}. With @acronym{GNU} @command{dirname}, the
11311 result is @samp{//} on platforms where @var{//} is distinct from
11312 @var{/}, and @samp{/} on platforms where there is no difference.
11314 The only options are @option{--help} and @option{--version}. @xref{Common
11322 # Output "/usr/bin".
11323 dirname /usr/bin/sort
11330 @node pathchk invocation
11331 @section @command{pathchk}: Check file name portability
11334 @cindex file names, checking validity and portability
11335 @cindex valid file names, checking for
11336 @cindex portable file names, checking for
11338 @command{pathchk} checks portability of file names. Synopsis:
11341 pathchk [@var{option}]@dots{} @var{name}@dots{}
11344 For each @var{name}, @command{pathchk} prints a message if any of
11345 these conditions is true:
11349 One of the existing directories in @var{name} does not have search
11350 (execute) permission,
11352 The length of @var{name} is larger than the maximum supported by the
11355 The length of one component of @var{name} is longer than
11356 its file system's maximum.
11359 A nonexistent @var{name} is not an error, so long a file with that
11360 name could be created under the above conditions.
11362 The program accepts the following options. Also see @ref{Common options}.
11363 Options must precede operands.
11369 Instead of performing checks based on the underlying file system,
11370 print a message if any of these conditions is true:
11374 A file name is empty.
11377 The length of a file name or one of its components exceeds the
11378 @acronym{POSIX} minimum limits for portability.
11381 A file name contains a character outside the portable file name
11382 character set, namely, the ASCII letters and digits, @samp{-},
11383 @samp{.}, @samp{/}, and @samp{_}.
11388 Print a message if a file name is empty, or if it contains a component
11389 that begins with @samp{-}.
11391 @item --portability
11392 @opindex --portability
11393 Print a message if a file name is not portable to all @acronym{POSIX}
11394 hosts. This option is equivalent to @samp{-p -P}.
11398 @cindex exit status of @command{pathchk}
11402 0 if all specified file names passed all checks,
11407 @node Working context
11408 @chapter Working context
11410 @cindex working context
11411 @cindex commands for printing the working context
11413 This section describes commands that display or alter the context in
11414 which you are working: the current directory, the terminal settings, and
11415 so forth. See also the user-related commands in the next section.
11418 * pwd invocation:: Print working directory.
11419 * stty invocation:: Print or change terminal characteristics.
11420 * printenv invocation:: Print environment variables.
11421 * tty invocation:: Print file name of terminal on standard input.
11425 @node pwd invocation
11426 @section @command{pwd}: Print working directory
11429 @cindex print name of current directory
11430 @cindex current working directory, printing
11431 @cindex working directory, printing
11433 @cindex symbolic links and @command{pwd}
11434 @command{pwd} prints the fully resolved name of the current directory.
11435 That is, all components of the printed name will be actual directory
11436 names---none will be symbolic links.
11438 @cindex conflicts with shell built-ins
11439 @cindex built-in shell commands, conflicts with
11440 Because most shells have a built-in @command{pwd} command, using an
11441 unadorned @command{pwd} in a script or interactively may get you
11442 different functionality than that described here.
11444 The only options are a lone @option{--help} or
11445 @option{--version}. @xref{Common options}.
11450 @node stty invocation
11451 @section @command{stty}: Print or change terminal characteristics
11454 @cindex change or print terminal settings
11455 @cindex terminal settings
11456 @cindex line settings of terminal
11458 @command{stty} prints or changes terminal characteristics, such as baud rate.
11462 stty [@var{option}] [@var{setting}]@dots{}
11463 stty [@var{option}]
11466 If given no line settings, @command{stty} prints the baud rate, line
11467 discipline number (on systems that support it), and line settings
11468 that have been changed from the values set by @samp{stty sane}.
11469 By default, mode reading and setting are performed on the tty line
11470 connected to standard input, although this can be modified by the
11471 @option{--file} option.
11473 @command{stty} accepts many non-option arguments that change aspects of
11474 the terminal line operation, as described below.
11476 The program accepts the following options. Also see @ref{Common options}.
11483 Print all current settings in human-readable form. This option may not
11484 be used in combination with any line settings.
11486 @item -F @var{device}
11487 @itemx --file=@var{device}
11490 Set the line opened by the file name specified in @var{device} instead of
11491 the tty line connected to standard input. This option is necessary
11492 because opening a @acronym{POSIX} tty requires use of the @code{O_NONDELAY} flag to
11493 prevent a @acronym{POSIX} tty from blocking until the carrier detect line is high if
11494 the @code{clocal} flag is not set. Hence, it is not always possible
11495 to allow the shell to open the device in the traditional manner.
11501 @cindex machine-readable @command{stty} output
11502 Print all current settings in a form that can be used as an argument to
11503 another @command{stty} command to restore the current settings. This option
11504 may not be used in combination with any line settings.
11508 Many settings can be turned off by preceding them with a @samp{-}.
11509 Such arguments are marked below with ``May be negated'' in their
11510 description. The descriptions themselves refer to the positive
11511 case, that is, when @emph{not} negated (unless stated otherwise,
11514 Some settings are not available on all @acronym{POSIX} systems, since they use
11515 extensions. Such arguments are marked below with ``Non-@acronym{POSIX}'' in their
11516 description. On non-@acronym{POSIX} systems, those or other settings also may not
11517 be available, but it's not feasible to document all the variations: just
11523 * Control:: Control settings
11524 * Input:: Input settings
11525 * Output:: Output settings
11526 * Local:: Local settings
11527 * Combination:: Combination settings
11528 * Characters:: Special characters
11529 * Special:: Special settings
11534 @subsection Control settings
11536 @cindex control settings
11542 @cindex two-way parity
11543 Generate parity bit in output and expect parity bit in input.
11549 @cindex even parity
11550 Set odd parity (even if negated). May be negated.
11557 @cindex character size
11558 @cindex eight-bit characters
11559 Set character size to 5, 6, 7, or 8 bits.
11564 Send a hangup signal when the last process closes the tty. May be
11570 Use two stop bits per character (one if negated). May be negated.
11574 Allow input to be received. May be negated.
11578 @cindex modem control
11579 Disable modem control signals. May be negated.
11583 @cindex hardware flow control
11584 @cindex flow control, hardware
11585 @cindex RTS/CTS flow control
11586 Enable RTS/CTS flow control. Non-@acronym{POSIX}. May be negated.
11591 @subsection Input settings
11593 @cindex input settings
11598 @cindex breaks, ignoring
11599 Ignore break characters. May be negated.
11603 @cindex breaks, cause interrupts
11604 Make breaks cause an interrupt signal. May be negated.
11608 @cindex parity, ignoring
11609 Ignore characters with parity errors. May be negated.
11613 @cindex parity errors, marking
11614 Mark parity errors (with a 255-0-character sequence). May be negated.
11618 Enable input parity checking. May be negated.
11622 @cindex eight-bit input
11623 Clear high (8th) bit of input characters. May be negated.
11627 @cindex newline, translating to return
11628 Translate newline to carriage return. May be negated.
11632 @cindex return, ignoring
11633 Ignore carriage return. May be negated.
11637 @cindex return, translating to newline
11638 Translate carriage return to newline. May be negated.
11642 @cindex input encoding, UTF-8
11643 Assume input characters are UTF-8 encoded. May be negated.
11647 @kindex C-s/C-q flow control
11648 @cindex XON/XOFF flow control
11649 Enable XON/XOFF flow control (that is, @kbd{CTRL-S}/@kbd{CTRL-Q}). May
11656 @cindex software flow control
11657 @cindex flow control, software
11658 Enable sending of @code{stop} character when the system input buffer
11659 is almost full, and @code{start} character when it becomes almost
11660 empty again. May be negated.
11664 @cindex uppercase, translating to lowercase
11665 Translate uppercase characters to lowercase. Non-@acronym{POSIX}. May be
11670 Allow any character to restart output (only the start character
11671 if negated). Non-@acronym{POSIX}. May be negated.
11675 @cindex beeping at input buffer full
11676 Enable beeping and not flushing input buffer if a character arrives
11677 when the input buffer is full. Non-@acronym{POSIX}. May be negated.
11682 @subsection Output settings
11684 @cindex output settings
11685 These arguments specify output-related operations.
11690 Postprocess output. May be negated.
11694 @cindex lowercase, translating to output
11695 Translate lowercase characters to uppercase. Non-@acronym{POSIX}. May be
11700 @cindex return, translating to newline
11701 Translate carriage return to newline. Non-@acronym{POSIX}. May be negated.
11705 @cindex newline, translating to crlf
11706 Translate newline to carriage return-newline. Non-@acronym{POSIX}. May be
11711 Do not print carriage returns in the first column. Non-@acronym{POSIX}.
11716 Newline performs a carriage return. Non-@acronym{POSIX}. May be negated.
11720 @cindex pad instead of timing for delaying
11721 Use fill (padding) characters instead of timing for delays. Non-@acronym{POSIX}.
11726 @cindex pad character
11727 Use delete characters for fill instead of null characters. Non-@acronym{POSIX}.
11733 Newline delay style. Non-@acronym{POSIX}.
11740 Carriage return delay style. Non-@acronym{POSIX}.
11746 @opindex tab@var{n}
11747 Horizontal tab delay style. Non-@acronym{POSIX}.
11752 Backspace delay style. Non-@acronym{POSIX}.
11757 Vertical tab delay style. Non-@acronym{POSIX}.
11762 Form feed delay style. Non-@acronym{POSIX}.
11767 @subsection Local settings
11769 @cindex local settings
11774 Enable @code{interrupt}, @code{quit}, and @code{suspend} special
11775 characters. May be negated.
11779 Enable @code{erase}, @code{kill}, @code{werase}, and @code{rprnt}
11780 special characters. May be negated.
11784 Enable non-@acronym{POSIX} special characters. May be negated.
11788 Echo input characters. May be negated.
11794 Echo @code{erase} characters as backspace-space-backspace. May be
11799 @cindex newline echoing after @code{kill}
11800 Echo a newline after a @code{kill} character. May be negated.
11804 @cindex newline, echoing
11805 Echo newline even if not echoing other characters. May be negated.
11809 @cindex flushing, disabling
11810 Disable flushing after @code{interrupt} and @code{quit} special
11811 characters. May be negated.
11815 @cindex case translation
11816 Enable input and output of uppercase characters by preceding their
11817 lowercase equivalents with @samp{\}, when @code{icanon} is set.
11818 Non-@acronym{POSIX}. May be negated.
11822 @cindex background jobs, stopping at terminal write
11823 Stop background jobs that try to write to the terminal. Non-@acronym{POSIX}.
11830 Echo erased characters backward, between @samp{\} and @samp{/}.
11831 Non-@acronym{POSIX}. May be negated.
11837 @cindex control characters, using @samp{^@var{c}}
11838 @cindex hat notation for control characters
11839 Echo control characters in hat notation (@samp{^@var{c}}) instead
11840 of literally. Non-@acronym{POSIX}. May be negated.
11846 Echo the @code{kill} special character by erasing each character on
11847 the line as indicated by the @code{echoprt} and @code{echoe} settings,
11848 instead of by the @code{echoctl} and @code{echok} settings. Non-@acronym{POSIX}.
11854 @subsection Combination settings
11856 @cindex combination settings
11857 Combination settings:
11864 Same as @code{parenb -parodd cs7}. May be negated. If negated, same
11865 as @code{-parenb cs8}.
11869 Same as @code{parenb parodd cs7}. May be negated. If negated, same
11870 as @code{-parenb cs8}.
11874 Same as @code{-icrnl -onlcr}. May be negated. If negated, same as
11875 @code{icrnl -inlcr -igncr onlcr -ocrnl -onlret}.
11879 Reset the @code{erase} and @code{kill} special characters to their default
11886 @c This is too long to write inline.
11888 cread -ignbrk brkint -inlcr -igncr icrnl -ixoff
11889 -iuclc -ixany imaxbel opost -olcuc -ocrnl onlcr
11890 -onocr -onlret -ofill -ofdel nl0 cr0 tab0 bs0 vt0
11891 ff0 isig icanon iexten echo echoe echok -echonl
11892 -noflsh -xcase -tostop -echoprt echoctl echoke
11896 and also sets all special characters to their default values.
11900 Same as @code{brkint ignpar istrip icrnl ixon opost isig icanon}, plus
11901 sets the @code{eof} and @code{eol} characters to their default values
11902 if they are the same as the @code{min} and @code{time} characters.
11903 May be negated. If negated, same as @code{raw}.
11910 -ignbrk -brkint -ignpar -parmrk -inpck -istrip
11911 -inlcr -igncr -icrnl -ixon -ixoff -iuclc -ixany
11912 -imaxbel -opost -isig -icanon -xcase min 1 time 0
11916 May be negated. If negated, same as @code{cooked}.
11920 Same as @option{-icanon}. May be negated. If negated, same as
11925 @cindex eight-bit characters
11926 Same as @code{-parenb -istrip cs8}. May be negated. If negated,
11927 same as @code{parenb istrip cs7}.
11931 Same as @option{-parenb -istrip -opost cs8}. May be negated.
11932 If negated, same as @code{parenb istrip opost cs7}.
11936 Same as @option{-ixany}. Non-@acronym{POSIX}. May be negated.
11940 Same as @code{tab0}. Non-@acronym{POSIX}. May be negated. If negated, same
11947 Same as @code{xcase iuclc olcuc}. Non-@acronym{POSIX}. May be negated.
11951 Same as @code{echoe echoctl echoke}.
11955 Same as @code{echoe echoctl echoke -ixany intr ^C erase ^? kill C-u}.
11960 @subsection Special characters
11962 @cindex special characters
11963 @cindex characters, special
11965 The special characters' default values vary from system to system.
11966 They are set with the syntax @samp{name value}, where the names are
11967 listed below and the value can be given either literally, in hat
11968 notation (@samp{^@var{c}}), or as an integer which may start with
11969 @samp{0x} to indicate hexadecimal, @samp{0} to indicate octal, or
11970 any other digit to indicate decimal.
11972 @cindex disabling special characters
11973 @kindex u@r{, and disabling special characters}
11974 For GNU stty, giving a value of @code{^-} or @code{undef} disables that
11975 special character. (This is incompatible with Ultrix @command{stty},
11976 which uses a value of @samp{u} to disable a special character. GNU
11977 @command{stty} treats a value @samp{u} like any other, namely to set that
11978 special character to @key{U}.)
11984 Send an interrupt signal.
11988 Send a quit signal.
11992 Erase the last character typed.
11996 Erase the current line.
12000 Send an end of file (terminate the input).
12008 Alternate character to end the line. Non-@acronym{POSIX}.
12012 Switch to a different shell layer. Non-@acronym{POSIX}.
12016 Restart the output after stopping it.
12024 Send a terminal stop signal.
12028 Send a terminal stop signal after flushing the input. Non-@acronym{POSIX}.
12032 Redraw the current line. Non-@acronym{POSIX}.
12036 Erase the last word typed. Non-@acronym{POSIX}.
12040 Enter the next character typed literally, even if it is a special
12041 character. Non-@acronym{POSIX}.
12046 @subsection Special settings
12048 @cindex special settings
12053 Set the minimum number of characters that will satisfy a read until
12054 the time value has expired, when @option{-icanon} is set.
12058 Set the number of tenths of a second before reads time out if the minimum
12059 number of characters have not been read, when @option{-icanon} is set.
12061 @item ispeed @var{n}
12063 Set the input speed to @var{n}.
12065 @item ospeed @var{n}
12067 Set the output speed to @var{n}.
12071 Tell the tty kernel driver that the terminal has @var{n} rows. Non-@acronym{POSIX}.
12074 @itemx columns @var{n}
12077 Tell the kernel that the terminal has @var{n} columns. Non-@acronym{POSIX}.
12083 Print the number of rows and columns that the kernel thinks the
12084 terminal has. (Systems that don't support rows and columns in the kernel
12085 typically use the environment variables @env{LINES} and @env{COLUMNS}
12086 instead; however, GNU @command{stty} does not know anything about them.)
12087 Non-@acronym{POSIX}.
12091 Use line discipline @var{n}. Non-@acronym{POSIX}.
12095 Print the terminal speed.
12098 @cindex baud rate, setting
12099 @c FIXME: Is this still true that the baud rate can't be set
12100 @c higher than 38400?
12101 Set the input and output speeds to @var{n}. @var{n} can be one
12102 of: 0 50 75 110 134 134.5 150 200 300 600 1200 1800 2400 4800 9600
12103 19200 38400 @code{exta} @code{extb}. @code{exta} is the same as
12104 19200; @code{extb} is the same as 38400. 0 hangs up the line if
12105 @option{-clocal} is set.
12109 @node printenv invocation
12110 @section @command{printenv}: Print all or some environment variables
12113 @cindex printing all or some environment variables
12114 @cindex environment variables, printing
12116 @command{printenv} prints environment variable values. Synopsis:
12119 printenv [@var{option}] [@var{variable}]@dots{}
12122 If no @var{variable}s are specified, @command{printenv} prints the value of
12123 every environment variable. Otherwise, it prints the value of each
12124 @var{variable} that is set, and nothing for those that are not set.
12126 The only options are a lone @option{--help} or @option{--version}.
12127 @xref{Common options}.
12129 @cindex exit status of @command{printenv}
12133 0 if all variables specified were found
12134 1 if at least one specified variable was not found
12135 2 if a write error occurred
12139 @node tty invocation
12140 @section @command{tty}: Print file name of terminal on standard input
12143 @cindex print terminal file name
12144 @cindex terminal file name, printing
12146 @command{tty} prints the file name of the terminal connected to its standard
12147 input. It prints @samp{not a tty} if standard input is not a terminal.
12151 tty [@var{option}]@dots{}
12154 The program accepts the following option. Also see @ref{Common options}.
12164 Print nothing; only return an exit status.
12168 @cindex exit status of @command{tty}
12172 0 if standard input is a terminal
12173 1 if standard input is not a terminal
12174 2 if given incorrect arguments
12175 3 if a write error occurs
12179 @node User information
12180 @chapter User information
12182 @cindex user information, commands for
12183 @cindex commands for printing user information
12185 This section describes commands that print user-related information:
12186 logins, groups, and so forth.
12189 * id invocation:: Print user identity.
12190 * logname invocation:: Print current login name.
12191 * whoami invocation:: Print effective user ID.
12192 * groups invocation:: Print group names a user is in.
12193 * users invocation:: Print login names of users currently logged in.
12194 * who invocation:: Print who is currently logged in.
12198 @node id invocation
12199 @section @command{id}: Print user identity
12202 @cindex real user and group IDs, printing
12203 @cindex effective user and group IDs, printing
12204 @cindex printing real and effective user and group IDs
12206 @command{id} prints information about the given user, or the process
12207 running it if no user is specified. Synopsis:
12210 id [@var{option}]@dots{} [@var{username}]
12213 By default, it prints the real user ID, real group ID, effective user ID
12214 if different from the real user ID, effective group ID if different from
12215 the real group ID, and supplemental group IDs.
12217 Each of these numeric values is preceded by an identifying string and
12218 followed by the corresponding user or group name in parentheses.
12220 The options cause @command{id} to print only part of the above information.
12221 Also see @ref{Common options}.
12228 Print only the group ID.
12234 Print only the group ID and the supplementary groups.
12240 Print the user or group name instead of the ID number. Requires
12241 @option{-u}, @option{-g}, or @option{-G}.
12247 Print the real, instead of effective, user or group ID. Requires
12248 @option{-u}, @option{-g}, or @option{-G}.
12254 Print only the user ID.
12260 @macro primaryAndSupplementaryGroups{cmd,arg}
12261 Primary and supplementary groups for a process are normally inherited
12262 from its parent and are usually unchanged since login. This means
12263 that if you change the group database after logging in, @command{\cmd\}
12264 will not reflect your changes within your existing login session.
12265 Running @command{\cmd\} with a \arg\ causes the user and group
12266 database to be consulted afresh, and so will give a different result.
12268 @primaryAndSupplementaryGroups{id,user argument}
12270 @node logname invocation
12271 @section @command{logname}: Print current login name
12274 @cindex printing user's login name
12275 @cindex login name, printing
12276 @cindex user name, printing
12279 @command{logname} prints the calling user's name, as found in a
12280 system-maintained file (often @file{/var/run/utmp} or
12281 @file{/etc/utmp}), and exits with a status of 0. If there is no entry
12282 for the calling process, @command{logname} prints
12283 an error message and exits with a status of 1.
12285 The only options are @option{--help} and @option{--version}. @xref{Common
12291 @node whoami invocation
12292 @section @command{whoami}: Print effective user ID
12295 @cindex effective user ID, printing
12296 @cindex printing the effective user ID
12298 @command{whoami} prints the user name associated with the current
12299 effective user ID. It is equivalent to the command @samp{id -un}.
12301 The only options are @option{--help} and @option{--version}. @xref{Common
12307 @node groups invocation
12308 @section @command{groups}: Print group names a user is in
12311 @cindex printing groups a user is in
12312 @cindex supplementary groups, printing
12314 @command{groups} prints the names of the primary and any supplementary
12315 groups for each given @var{username}, or the current process if no names
12316 are given. If more than one name is given, the name of each user is
12318 the list of that user's groups and the user name is separated from the
12319 group list by a colon. Synopsis:
12322 groups [@var{username}]@dots{}
12325 The group lists are equivalent to the output of the command @samp{id -Gn}.
12327 @primaryAndSupplementaryGroups{groups,list of users}
12329 The only options are @option{--help} and @option{--version}. @xref{Common
12335 @node users invocation
12336 @section @command{users}: Print login names of users currently logged in
12339 @cindex printing current usernames
12340 @cindex usernames, printing current
12342 @cindex login sessions, printing users with
12343 @command{users} prints on a single line a blank-separated list of user
12344 names of users currently logged in to the current host. Each user name
12345 corresponds to a login session, so if a user has more than one login
12346 session, that user's name will appear the same number of times in the
12355 With no @var{file} argument, @command{users} extracts its information from
12356 a system-maintained file (often @file{/var/run/utmp} or
12357 @file{/etc/utmp}). If a file argument is given, @command{users} uses
12358 that file instead. A common choice is @file{/var/log/wtmp}.
12360 The only options are @option{--help} and @option{--version}. @xref{Common
12366 @node who invocation
12367 @section @command{who}: Print who is currently logged in
12370 @cindex printing current user information
12371 @cindex information, about current users
12373 @command{who} prints information about users who are currently logged on.
12377 @command{who} [@var{option}] [@var{file}] [am i]
12380 @cindex terminal lines, currently used
12382 @cindex remote hostname
12383 If given no non-option arguments, @command{who} prints the following
12384 information for each user currently logged on: login name, terminal
12385 line, login time, and remote hostname or X display.
12389 If given one non-option argument, @command{who} uses that instead of
12390 a default system-maintained file (often @file{/var/run/utmp} or
12391 @file{/etc/utmp}) as the name of the file containing the record of
12392 users logged on. @file{/var/log/wtmp} is commonly given as an argument
12393 to @command{who} to look at who has previously logged on.
12397 If given two non-option arguments, @command{who} prints only the entry
12398 for the user running it (determined from its standard input), preceded
12399 by the hostname. Traditionally, the two arguments given are @samp{am
12400 i}, as in @samp{who am i}.
12403 Time stamps are listed according to the time zone rules specified by
12404 the @env{TZ} environment variable, or by the system default rules if
12405 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
12406 with @env{TZ}, libc, The GNU C Library Reference Manual}.
12408 The program accepts the following options. Also see @ref{Common options}.
12416 Same as @samp{-b -d --login -p -r -t -T -u}.
12422 Print the date and time of last system boot.
12428 Print information corresponding to dead processes.
12434 Print column headings.
12438 Same as @samp{who am i}.
12444 Print only the login names and the number of users logged on.
12445 Overrides all other options.
12449 Ignored; for compatibility with other versions of @command{who}.
12454 After the login time, print the number of hours and minutes that the
12455 user has been idle. @samp{.} means the user was active in the last minute.
12456 @samp{old} means the user has been idle for more than 24 hours.
12462 List only the entries that correspond to processes via which the
12463 system is waiting for a user to login. The user name is always @samp{LOGIN}.
12467 Attempt to canonicalize hostnames found in utmp through a DNS lookup. This
12468 is not the default because it can cause significant delays on systems with
12469 automatic dial-up internet access.
12475 Print a line of column headings.
12486 @opindex --writable
12487 @cindex message status
12488 @pindex write@r{, allowed}
12489 After each login name print a character indicating the user's message status:
12492 @samp{+} allowing @code{write} messages
12493 @samp{-} disallowing @code{write} messages
12494 @samp{?} cannot find terminal device
12502 @node System context
12503 @chapter System context
12505 @cindex system context
12506 @cindex context, system
12507 @cindex commands for system context
12509 This section describes commands that print or change system-wide
12513 * arch invocation:: Print machine hardware name.
12514 * date invocation:: Print or set system date and time.
12515 * uname invocation:: Print system information.
12516 * hostname invocation:: Print or set system name.
12517 * hostid invocation:: Print numeric host identifier.
12521 @node date invocation
12522 @section @command{date}: Print or set system date and time
12525 @cindex time, printing or setting
12526 @cindex printing the current time
12531 date [@var{option}]@dots{} [+@var{format}]
12532 date [-u|--utc|--universal] @c this avoids a newline in the output
12533 [ MMDDhhmm[[CC]YY][.ss] ]
12537 Invoking @command{date} with no @var{format} argument is equivalent to invoking
12538 it with a default format that depends on the @env{LC_TIME} locale category.
12539 In the default C locale, this format is @samp{'+%a %b %e %H:%M:%S %Z %Y'},
12540 so the output looks like @samp{Thu Mar @ 3 13:47:51 PST 2005}.
12543 Normally, @command{date} uses the time zone rules indicated by the
12544 @env{TZ} environment variable, or the system default rules if @env{TZ}
12545 is not set. @xref{TZ Variable,, Specifying the Time Zone with
12546 @env{TZ}, libc, The GNU C Library Reference Manual}.
12548 @findex strftime @r{and @command{date}}
12549 @cindex time formats
12550 @cindex formatting times
12551 If given an argument that starts with a @samp{+}, @command{date} prints the
12552 current date and time (or the date and time specified by the
12553 @option{--date} option, see below) in the format defined by that argument,
12554 which is similar to that of the @code{strftime} function. Except for
12555 conversion specifiers, which start with @samp{%}, characters in the
12556 format string are printed unchanged. The conversion specifiers are
12562 * Time conversion specifiers:: %[HIklMNpPrRsSTXzZ]
12563 * Date conversion specifiers:: %[aAbBcCdDeFgGhjmuUVwWxyY]
12564 * Literal conversion specifiers:: %[%nt]
12565 * Padding and other flags:: Pad with zeros, spaces, etc.
12566 * Setting the time:: Changing the system clock.
12567 * Options for date:: Instead of the current time.
12569 * Date input formats:: Specifying date strings.
12571 * Examples of date:: Examples.
12574 @node Time conversion specifiers
12575 @subsection Time conversion specifiers
12577 @cindex time conversion specifiers
12578 @cindex conversion specifiers, time
12580 @command{date} conversion specifiers related to times.
12584 hour (@samp{00}@dots{}@samp{23})
12586 hour (@samp{01}@dots{}@samp{12})
12588 hour (@samp{ 0}@dots{}@samp{23}).
12589 This is a @acronym{GNU} extension.
12591 hour (@samp{ 1}@dots{}@samp{12}).
12592 This is a @acronym{GNU} extension.
12594 minute (@samp{00}@dots{}@samp{59})
12596 nanoseconds (@samp{000000000}@dots{}@samp{999999999}).
12597 This is a @acronym{GNU} extension.
12599 locale's equivalent of either @samp{AM} or @samp{PM};
12600 blank in many locales.
12601 Noon is treated as @samp{PM} and midnight as @samp{AM}.
12603 like @samp{%p}, except lower case.
12604 This is a @acronym{GNU} extension.
12606 locale's 12-hour clock time (e.g., @samp{11:11:04 PM})
12608 24-hour hour and minute. Same as @samp{%H:%M}.
12609 This is a @acronym{GNU} extension.
12611 @cindex epoch, seconds since
12612 @cindex seconds since the epoch
12613 @cindex beginning of time
12614 seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
12615 Leap seconds are not counted unless leap second support is available.
12616 @xref{%s-examples}, for examples.
12617 This is a @acronym{GNU} extension.
12619 second (@samp{00}@dots{}@samp{60}).
12620 This may be @samp{60} if leap seconds are supported.
12622 24-hour hour, minute, and second. Same as @samp{%H:%M:%S}.
12624 locale's time representation (e.g., @samp{23:13:48})
12626 @w{@acronym{RFC} 2822/@acronym{ISO} 8601} style numeric time zone
12627 (e.g., @samp{-0600} or @samp{+0530}), or nothing if no
12628 time zone is determinable. This value reflects the numeric time zone
12629 appropriate for the current time, using the time zone rules specified
12630 by the @env{TZ} environment variable.
12631 The time (and optionally, the time zone rules) can be overridden
12632 by the @option{--date} option.
12633 This is a @acronym{GNU} extension.
12635 @w{@acronym{RFC} 3339/@acronym{ISO} 8601} style numeric time zone with
12636 @samp{:} (e.g., @samp{-06:00} or @samp{+05:30}), or nothing if no time
12637 zone is determinable.
12638 This is a @acronym{GNU} extension.
12640 Numeric time zone to the nearest second with @samp{:} (e.g.,
12641 @samp{-06:00:00} or @samp{+05:30:00}), or nothing if no time zone is
12643 This is a @acronym{GNU} extension.
12645 Numeric time zone with @samp{:} using the minimum necessary precision
12646 (e.g., @samp{-06}, @samp{+05:30}, or @samp{-04:56:02}), or nothing if
12647 no time zone is determinable.
12648 This is a @acronym{GNU} extension.
12650 alphabetic time zone abbreviation (e.g., @samp{EDT}), or nothing if no
12651 time zone is determinable. See @samp{%z} for how it is determined.
12655 @node Date conversion specifiers
12656 @subsection Date conversion specifiers
12658 @cindex date conversion specifiers
12659 @cindex conversion specifiers, date
12661 @command{date} conversion specifiers related to dates.
12665 locale's abbreviated weekday name (e.g., @samp{Sun})
12667 locale's full weekday name, variable length (e.g., @samp{Sunday})
12669 locale's abbreviated month name (e.g., @samp{Jan})
12671 locale's full month name, variable length (e.g., @samp{January})
12673 locale's date and time (e.g., @samp{Thu Mar @ 3 23:05:25 2005})
12675 century. This is like @samp{%Y}, except the last two digits are omitted.
12676 For example, it is @samp{20} if @samp{%Y} is @samp{2000},
12677 and is @samp{-0} if @samp{%Y} is @samp{-001}.
12678 It is normally at least two characters, but it may be more.
12680 day of month (e.g., @samp{01})
12682 date; same as @samp{%m/%d/%y}
12684 day of month, space padded; same as @samp{%_d}
12686 full date in @acronym{ISO} 8601 format; same as @samp{%Y-%m-%d}.
12687 This is a good choice for a date format, as it is standard and
12688 is easy to sort in the usual case where years are in the range
12690 This is a @acronym{GNU} extension.
12692 year corresponding to the @acronym{ISO} week number, but without the century
12693 (range @samp{00} through @samp{99}). This has the same format and value
12694 as @samp{%y}, except that if the @acronym{ISO} week number (see
12696 to the previous or next year, that year is used instead.
12697 This is a @acronym{GNU} extension.
12699 year corresponding to the @acronym{ISO} week number. This has the
12700 same format and value as @samp{%Y}, except that if the @acronym{ISO}
12702 @samp{%V}) belongs to the previous or next year, that year is used
12704 It is normally useful only if @samp{%V} is also used;
12705 for example, the format @samp{%G-%m-%d} is probably a mistake,
12706 since it combines the ISO week number year with the conventional month and day.
12707 This is a @acronym{GNU} extension.
12711 day of year (@samp{001}@dots{}@samp{366})
12713 month (@samp{01}@dots{}@samp{12})
12715 day of week (@samp{1}@dots{}@samp{7}) with @samp{1} corresponding to Monday
12717 week number of year, with Sunday as the first day of the week
12718 (@samp{00}@dots{}@samp{53}).
12719 Days in a new year preceding the first Sunday are in week zero.
12721 @acronym{ISO} week number, that is, the
12722 week number of year, with Monday as the first day of the week
12723 (@samp{01}@dots{}@samp{53}).
12724 If the week containing January 1 has four or more days in
12725 the new year, then it is considered week 1; otherwise, it is week 53 of
12726 the previous year, and the next week is week 1. (See the @acronym{ISO} 8601
12729 day of week (@samp{0}@dots{}@samp{6}) with 0 corresponding to Sunday
12731 week number of year, with Monday as first day of week
12732 (@samp{00}@dots{}@samp{53}).
12733 Days in a new year preceding the first Monday are in week zero.
12735 locale's date representation (e.g., @samp{12/31/99})
12737 last two digits of year (@samp{00}@dots{}@samp{99})
12739 year. This is normally at least four characters, but it may be more.
12740 Year @samp{0000} precedes year @samp{0001}, and year @samp{-001}
12741 precedes year @samp{0000}.
12745 @node Literal conversion specifiers
12746 @subsection Literal conversion specifiers
12748 @cindex literal conversion specifiers
12749 @cindex conversion specifiers, literal
12751 @command{date} conversion specifiers that produce literal strings.
12763 @node Padding and other flags
12764 @subsection Padding and other flags
12766 @cindex numeric field padding
12767 @cindex padding of numeric fields
12768 @cindex fields, padding numeric
12770 Unless otherwise specified, @command{date} normally pads numeric fields
12771 with zeros, so that, for
12772 example, numeric months are always output as two digits.
12773 Seconds since the epoch are not padded, though,
12774 since there is no natural width for them.
12776 As a @acronym{GNU} extension, @command{date} recognizes any of the
12777 following optional flags after the @samp{%}:
12781 (hyphen) Do not pad the field; useful if the output is intended for
12784 (underscore) Pad with spaces; useful if you need a fixed
12785 number of characters in the output, but zeros are too distracting.
12787 (zero) Pad with zeros even if the conversion specifier
12788 would normally pad with spaces.
12790 Use upper case characters if possible.
12792 Use opposite case characters if possible.
12793 A field that is normally upper case becomes lower case, and vice versa.
12797 Here are some examples of padding:
12800 date +%d/%m -d "Feb 1"
12802 date +%-d/%-m -d "Feb 1"
12804 date +%_d/%_m -d "Feb 1"
12808 As a @acronym{GNU} extension, you can specify the field width
12809 (after any flag, if present) as a decimal number. If the natural size of the
12810 output is of the field has less than the specified number of characters,
12811 the result is written right adjusted and padded to the given
12812 size. For example, @samp{%9B} prints the right adjusted month name in
12813 a field of width 9.
12815 An optional modifier can follow the optional flag and width
12816 specification. The modifiers are:
12820 Use the locale's alternate representation for date and time. This
12821 modifier applies to the @samp{%c}, @samp{%C}, @samp{%x}, @samp{%X},
12822 @samp{%y} and @samp{%Y} conversion specifiers. In a Japanese locale, for
12823 example, @samp{%Ex} might yield a date format based on the Japanese
12827 Use the locale's alternate numeric symbols for numbers. This modifier
12828 applies only to numeric conversion specifiers.
12831 If the format supports the modifier but no alternate representation
12832 is available, it is ignored.
12835 @node Setting the time
12836 @subsection Setting the time
12838 @cindex setting the time
12839 @cindex time setting
12840 @cindex appropriate privileges
12842 If given an argument that does not start with @samp{+}, @command{date} sets
12843 the system clock to the date and time specified by that argument (as
12844 described below). You must have appropriate privileges to set the
12845 system clock. The @option{--date} and @option{--set} options may not be
12846 used with such an argument. The @option{--universal} option may be used
12847 with such an argument to indicate that the specified date and time are
12848 relative to Coordinated Universal Time rather than to the local time
12851 The argument must consist entirely of digits, which have the following
12864 first two digits of year (optional)
12866 last two digits of year (optional)
12871 The @option{--set} option also sets the system clock; see the next section.
12874 @node Options for date
12875 @subsection Options for @command{date}
12877 @cindex @command{date} options
12878 @cindex options for @command{date}
12880 The program accepts the following options. Also see @ref{Common options}.
12884 @item -d @var{datestr}
12885 @itemx --date=@var{datestr}
12888 @cindex parsing date strings
12889 @cindex date strings, parsing
12890 @cindex arbitrary date strings, parsing
12893 @opindex next @var{day}
12894 @opindex last @var{day}
12895 Display the date and time specified in @var{datestr} instead of the
12896 current date and time. @var{datestr} can be in almost any common
12897 format. It can contain month names, time zones, @samp{am} and @samp{pm},
12898 @samp{yesterday}, etc. For example, @option{--date="2004-02-27
12899 14:19:13.489392193 +0530"} specifies the instant of time that is
12900 489,392,193 nanoseconds after February 27, 2004 at 2:19:13 PM in a
12901 time zone that is 5 hours and 30 minutes east of @acronym{UTC}.@*
12902 @xref{Date input formats}.
12904 @item -f @var{datefile}
12905 @itemx --file=@var{datefile}
12908 Parse each line in @var{datefile} as with @option{-d} and display the
12909 resulting date and time. If @var{datefile} is @samp{-}, use standard
12910 input. This is useful when you have many dates to process, because the
12911 system overhead of starting up the @command{date} executable many times can
12914 @item -r @var{file}
12915 @itemx --reference=@var{file}
12917 @opindex --reference
12918 Display the date and time of the last modification of @var{file},
12919 instead of the current date and time.
12926 @opindex --rfc-2822
12927 Display the date and time using the format @samp{%a, %d %b %Y %H:%M:%S
12928 %z}, evaluated in the C locale so abbreviations are always in English.
12932 Fri, 09 Sep 2005 13:51:39 -0700
12935 This format conforms to
12936 @uref{ftp://ftp.rfc-editor.org/in-notes/rfc2822.txt, Internet
12937 @acronym{RFCs} 2822} and
12938 @uref{ftp://ftp.rfc-editor.org/in-notes/rfc822.txt, 822}, the
12939 current and previous standards for Internet email.
12941 @item --rfc-3339=@var{timespec}
12942 @opindex --rfc-3339=@var{timespec}
12943 Display the date using a format specified by
12944 @uref{ftp://ftp.rfc-editor.org/in-notes/rfc3339.txt, Internet
12945 @acronym{RFC} 3339}. This is a subset of the @acronym{ISO} 8601
12946 format, except that it also permits applications to use a space rather
12947 than a @samp{T} to separate dates from times. Unlike the other
12948 standard formats, @acronym{RFC} 3339 format is always suitable as
12949 input for the @option{--date} (@option{-d}) and @option{--file}
12950 (@option{-f}) options, regardless of the current locale.
12952 The argument @var{timespec} specifies how much of the time to include.
12953 It can be one of the following:
12957 Print just the full-date, e.g., @samp{2005-09-14}.
12958 This is equivalent to the format @samp{%Y-%m-%d}.
12961 Print the full-date and full-time separated by a space, e.g.,
12962 @samp{2005-09-14 00:56:06+05:30}. The output ends with a numeric
12963 time-offset; here the @samp{+05:30} means that local time is five
12964 hours and thirty minutes east of @acronym{UTC}. This is equivalent to
12965 the format @samp{%Y-%m-%d %H:%M:%S%:z}.
12968 Like @samp{seconds}, but also print nanoseconds, e.g.,
12969 @samp{2005-09-14 00:56:06.998458565+05:30}.
12970 This is equivalent to the format @samp{%Y-%m-%d %H:%M:%S.%N%:z}.
12974 @item -s @var{datestr}
12975 @itemx --set=@var{datestr}
12978 Set the date and time to @var{datestr}. See @option{-d} above.
12985 @opindex --universal
12986 @cindex Coordinated Universal Time
12988 @cindex Greenwich Mean Time
12991 Use Coordinated Universal Time (@acronym{UTC}) by operating as if the
12992 @env{TZ} environment variable were set to the string @samp{UTC0}.
12994 Universal Time is often called ``Greenwich Mean Time'' (@sc{gmt}) for
12995 historical reasons.
12999 @node Examples of date
13000 @subsection Examples of @command{date}
13002 @cindex examples of @command{date}
13004 Here are a few examples. Also see the documentation for the @option{-d}
13005 option in the previous section.
13010 To print the date of the day before yesterday:
13013 date --date='2 days ago'
13017 To print the date of the day three months and one day hence:
13020 date --date='3 months 1 day'
13024 To print the day of year of Christmas in the current year:
13027 date --date='25 Dec' +%j
13031 To print the current full month name and the day of the month:
13037 But this may not be what you want because for the first nine days of
13038 the month, the @samp{%d} expands to a zero-padded two-digit field,
13039 for example @samp{date -d 1may '+%B %d'} will print @samp{May 01}.
13042 To print a date without the leading zero for one-digit days
13043 of the month, you can use the (@acronym{GNU} extension)
13044 @samp{-} flag to suppress
13045 the padding altogether:
13048 date -d 1may '+%B %-d
13052 To print the current date and time in the format required by many
13053 non-@acronym{GNU} versions of @command{date} when setting the system clock:
13056 date +%m%d%H%M%Y.%S
13060 To set the system clock forward by two minutes:
13063 date --set='+2 minutes'
13067 To print the date in @acronym{RFC} 2822 format,
13068 use @samp{date --rfc-2822}. Here is some example output:
13071 Fri, 09 Sep 2005 13:51:39 -0700
13074 @anchor{%s-examples}
13076 To convert a date string to the number of seconds since the epoch
13077 (which is 1970-01-01 00:00:00 UTC), use the @option{--date} option with
13078 the @samp{%s} format. That can be useful in sorting and/or graphing
13079 and/or comparing data by date. The following command outputs the
13080 number of the seconds since the epoch for the time two minutes after the
13084 date --date='1970-01-01 00:02:00 +0000' +%s
13088 If you do not specify time zone information in the date string,
13089 @command{date} uses your computer's idea of the time zone when
13090 interpreting the string. For example, if your computer's time zone is
13091 that of Cambridge, Massachusetts, which was then 5 hours (i.e., 18,000
13092 seconds) behind UTC:
13095 # local time zone used
13096 date --date='1970-01-01 00:02:00' +%s
13101 If you're sorting or graphing dated data, your raw date values may be
13102 represented as seconds since the epoch. But few people can look at
13103 the date @samp{946684800} and casually note ``Oh, that's the first second
13104 of the year 2000 in Greenwich, England.''
13107 date --date='2000-01-01 UTC' +%s
13111 An alternative is to use the @option{--utc} (@option{-u}) option.
13112 Then you may omit @samp{UTC} from the date string. Although this
13113 produces the same result for @samp{%s} and many other format sequences,
13114 with a time zone offset different from zero, it would give a different
13115 result for zone-dependent formats like @samp{%z}.
13118 date -u --date=2000-01-01 +%s
13122 To convert such an unwieldy number of seconds back to
13123 a more readable form, use a command like this:
13126 # local time zone used
13127 date -d '1970-01-01 UTC 946684800 seconds' +"%Y-%m-%d %T %z"
13128 1999-12-31 19:00:00 -0500
13131 Or if you do not mind depending on the @samp{@@} feature present since
13132 coreutils 5.3.0, you could shorten this to:
13135 date -d @@946684800 +"%F %T %z"
13136 1999-12-31 19:00:00 -0500
13139 Often it is better to output UTC-relative date and time:
13142 date -u -d '1970-01-01 946684800 seconds' +"%Y-%m-%d %T %z"
13143 2000-01-01 00:00:00 +0000
13149 @node arch invocation
13150 @section @command{arch}: Print machine hardware name
13153 @cindex print machine hardware name
13154 @cindex system information, printing
13156 @command{arch} prints the machine hardware name,
13157 and is equivalent to @samp{uname -m}.
13161 arch [@var{option}]
13164 The program accepts the @ref{Common options} only.
13169 @node uname invocation
13170 @section @command{uname}: Print system information
13173 @cindex print system information
13174 @cindex system information, printing
13176 @command{uname} prints information about the machine and operating system
13177 it is run on. If no options are given, @command{uname} acts as if the
13178 @option{-s} option were given. Synopsis:
13181 uname [@var{option}]@dots{}
13184 If multiple options or @option{-a} are given, the selected information is
13185 printed in this order:
13188 @var{kernel-name} @var{nodename} @var{kernel-release} @var{kernel-version}
13189 @var{machine} @var{processor} @var{hardware-platform} @var{operating-system}
13192 The information may contain internal spaces, so such output cannot be
13193 parsed reliably. In the following example, @var{release} is
13194 @samp{2.2.18ss.e820-bda652a #4 SMP Tue Jun 5 11:24:08 PDT 2001}:
13198 @result{} Linux dum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 i686 unknown unknown GNU/Linux
13202 The program accepts the following options. Also see @ref{Common options}.
13210 Print all of the below information, except omit the processor type
13211 and the hardware platform name if they are unknown.
13214 @itemx --hardware-platform
13216 @opindex --hardware-platform
13217 @cindex implementation, hardware
13218 @cindex hardware platform
13219 @cindex platform, hardware
13220 Print the hardware platform name
13221 (sometimes called the hardware implementation).
13222 Print @samp{unknown} if the kernel does not make this information
13223 easily available, as is the case with Linux kernels.
13229 @cindex machine type
13230 @cindex hardware class
13231 @cindex hardware type
13232 Print the machine hardware name (sometimes called the hardware class
13238 @opindex --nodename
13241 @cindex network node name
13242 Print the network node hostname.
13247 @opindex --processor
13248 @cindex host processor type
13249 Print the processor type (sometimes called the instruction set
13250 architecture or ISA).
13251 Print @samp{unknown} if the kernel does not make this information
13252 easily available, as is the case with Linux kernels.
13255 @itemx --operating-system
13257 @opindex --operating-system
13258 @cindex operating system name
13259 Print the name of the operating system.
13262 @itemx --kernel-release
13264 @opindex --kernel-release
13265 @cindex kernel release
13266 @cindex release of kernel
13267 Print the kernel release.
13270 @itemx --kernel-name
13272 @opindex --kernel-name
13273 @cindex kernel name
13274 @cindex name of kernel
13275 Print the kernel name.
13276 @acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) calls this
13277 ``the implementation of the operating system'', because the
13278 @acronym{POSIX} specification itself has no notion of ``kernel''.
13279 The kernel name might be the same as the operating system name printed
13280 by the @option{-o} or @option{--operating-system} option, but it might
13281 differ. Some operating systems (e.g., FreeBSD, HP-UX) have the same
13282 name as their underlying kernels; others (e.g., GNU/Linux, Solaris)
13286 @itemx --kernel-version
13288 @opindex --kernel-version
13289 @cindex kernel version
13290 @cindex version of kernel
13291 Print the kernel version.
13298 @node hostname invocation
13299 @section @command{hostname}: Print or set system name
13302 @cindex setting the hostname
13303 @cindex printing the hostname
13304 @cindex system name, printing
13305 @cindex appropriate privileges
13307 With no arguments, @command{hostname} prints the name of the current host
13308 system. With one argument, it sets the current host name to the
13309 specified string. You must have appropriate privileges to set the host
13313 hostname [@var{name}]
13316 The only options are @option{--help} and @option{--version}. @xref{Common
13322 @node hostid invocation
13323 @section @command{hostid}: Print numeric host identifier.
13326 @cindex printing the host identifier
13328 @command{hostid} prints the numeric identifier of the current host
13329 in hexadecimal. This command accepts no arguments.
13330 The only options are @option{--help} and @option{--version}.
13331 @xref{Common options}.
13333 For example, here's what it prints on one system I use:
13340 On that system, the 32-bit quantity happens to be closely
13341 related to the system's Internet address, but that isn't always
13347 @node Modified command invocation
13348 @chapter Modified command invocation
13350 @cindex modified command invocation
13351 @cindex invocation of commands, modified
13352 @cindex commands for invoking other commands
13354 This section describes commands that run other commands in some context
13355 different than the current one: a modified environment, as a different
13359 * chroot invocation:: Modify the root directory.
13360 * env invocation:: Modify environment variables.
13361 * nice invocation:: Modify niceness.
13362 * nohup invocation:: Immunize to hangups.
13363 * su invocation:: Modify user and group ID.
13367 @node chroot invocation
13368 @section @command{chroot}: Run a command with a different root directory
13371 @cindex running a program in a specified root directory
13372 @cindex root directory, running a program in a specified
13374 @command{chroot} runs a command with a specified root directory.
13375 On many systems, only the super-user can do this.@footnote{However,
13376 some systems (e.g., FreeBSD) can be configured to allow certain regular
13377 users to use the @code{chroot} system call, and hence to run this program.
13378 Also, on Cygwin, anyone can run the @command{chroot} command, because the
13379 underlying function is non-privileged due to lack of support in MS-Windows.}
13383 chroot @var{newroot} [@var{command} [@var{args}]@dots{}]
13384 chroot @var{option}
13387 Ordinarily, file names are looked up starting at the root of the
13388 directory structure, i.e., @file{/}. @command{chroot} changes the root to
13389 the directory @var{newroot} (which must exist) and then runs
13390 @var{command} with optional @var{args}. If @var{command} is not
13391 specified, the default is the value of the @env{SHELL} environment
13392 variable or @command{/bin/sh} if not set, invoked with the @option{-i} option.
13393 @var{command} must not be a special built-in utility
13394 (@pxref{Special built-in utilities}).
13396 The only options are @option{--help} and @option{--version}. @xref{Common
13397 options}. Options must precede operands.
13399 Here are a few tips to help avoid common problems in using chroot.
13400 To start with a simple example, make @var{command} refer to a statically
13401 linked binary. If you were to use a dynamically linked executable, then
13402 you'd have to arrange to have the shared libraries in the right place under
13403 your new root directory.
13405 For example, if you create a statically linked @command{ls} executable,
13406 and put it in @file{/tmp/empty}, you can run this command as root:
13409 $ chroot /tmp/empty /ls -Rl /
13412 Then you'll see output like this:
13417 -rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls
13420 If you want to use a dynamically linked executable, say @command{bash},
13421 then first run @samp{ldd bash} to see what shared objects it needs.
13422 Then, in addition to copying the actual binary, also copy the listed
13423 files to the required positions under your intended new root directory.
13424 Finally, if the executable requires any other files (e.g., data, state,
13425 device files), copy them into place, too.
13427 @cindex exit status of @command{chroot}
13431 1 if @command{chroot} itself fails
13432 126 if @var{command} is found but cannot be invoked
13433 127 if @var{command} cannot be found
13434 the exit status of @var{command} otherwise
13438 @node env invocation
13439 @section @command{env}: Run a command in a modified environment
13442 @cindex environment, running a program in a modified
13443 @cindex modified environment, running a program in a
13444 @cindex running a program in a modified environment
13446 @command{env} runs a command with a modified environment. Synopses:
13449 env [@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c
13450 [@var{command} [@var{args}]@dots{}]
13454 Operands of the form @samp{@var{variable}=@var{value}} set
13455 the environment variable @var{variable} to value @var{value}.
13456 @var{value} may be empty (@samp{@var{variable}=}). Setting a variable
13457 to an empty value is different from unsetting it.
13458 These operands are evaluated left-to-right, so if two operands
13459 mention the same variable the earlier is ignored.
13461 Environment variable names can be empty, and can contain any
13462 characters other than @samp{=} and the null character (@acronym{ASCII}
13463 @sc{nul}). However, it is wise to limit yourself to names that
13464 consist solely of underscores, digits, and @acronym{ASCII} letters,
13465 and that begin with a non-digit, as applications like the shell do not
13466 work well with other names.
13469 The first operand that does not contain the character @samp{=}
13470 specifies the program to invoke; it is
13471 searched for according to the @env{PATH} environment variable. Any
13472 remaining arguments are passed as arguments to that program.
13473 The program should not be a special built-in utility
13474 (@pxref{Special built-in utilities}).
13476 @cindex environment, printing
13478 If no command name is specified following the environment
13479 specifications, the resulting environment is printed. This is like
13480 specifying the @command{printenv} program.
13482 The program accepts the following options. Also see @ref{Common options}.
13483 Options must precede operands.
13487 @item -u @var{name}
13488 @itemx --unset=@var{name}
13491 Remove variable @var{name} from the environment, if it was in the
13496 @itemx --ignore-environment
13499 @opindex --ignore-environment
13500 Start with an empty environment, ignoring the inherited environment.
13504 @cindex exit status of @command{env}
13508 0 if no @var{command} is specified and the environment is output
13509 1 if @command{env} itself fails
13510 126 if @var{command} is found but cannot be invoked
13511 127 if @var{command} cannot be found
13512 the exit status of @var{command} otherwise
13516 @node nice invocation
13517 @section @command{nice}: Run a command with modified niceness
13521 @cindex scheduling, affecting
13522 @cindex appropriate privileges
13524 @command{nice} prints or modifies a process's @dfn{niceness},
13525 a parameter that affects whether the process is scheduled favorably.
13529 nice [@var{option}]@dots{} [@var{command} [@var{arg}]@dots{}]
13532 If no arguments are given, @command{nice} prints the current niceness.
13533 Otherwise, @command{nice} runs the given @var{command} with its
13534 niceness adjusted. By default, its niceness is incremented by 10.
13536 Nicenesses range at least from @minus{}20 (resulting in the most
13537 favorable scheduling) through 19 (the least favorable). Some systems
13538 may have a wider range of nicenesses; conversely, other systems may
13539 enforce more restrictive limits. An attempt to set the niceness
13540 outside the supported range is treated as an attempt to use the
13541 minimum or maximum supported value.
13543 A niceness should not be confused with a scheduling priority, which
13544 lets applications determine the order in which threads are scheduled
13545 to run. Unlike a priority, a niceness is merely advice to the
13546 scheduler, which the scheduler is free to ignore. Also, as a point of
13547 terminology, @acronym{POSIX} defines the behavior of @command{nice} in
13548 terms of a @dfn{nice value}, which is the nonnegative difference
13549 between a niceness and the minimum niceness. Though @command{nice}
13550 conforms to @acronym{POSIX}, its documentation and diagnostics use the
13551 term ``niceness'' for compatibility with historical practice.
13553 @var{command} must not be a special built-in utility (@pxref{Special
13554 built-in utilities}).
13556 @cindex conflicts with shell built-ins
13557 @cindex built-in shell commands, conflicts with
13558 Because many shells have a built-in @command{nice} command, using an
13559 unadorned @command{nice} in a script or interactively may get you
13560 different functionality than that described here.
13562 The program accepts the following option. Also see @ref{Common options}.
13563 Options must precede operands.
13566 @item -n @var{adjustment}
13567 @itemx --adjustment=@var{adjustment}
13569 @opindex --adjustment
13570 Add @var{adjustment} instead of 10 to the command's niceness. If
13571 @var{adjustment} is negative and you lack appropriate privileges,
13572 @command{nice} issues a warning but otherwise acts as if you specified
13575 For compatibility @command{nice} also supports an obsolete
13576 option syntax @option{-@var{adjustment}}. New scripts should use
13577 @option{-n @var{adjustment}} instead.
13581 @cindex exit status of @command{nice}
13585 0 if no @var{command} is specified and the niceness is output
13586 1 if @command{nice} itself fails
13587 126 if @var{command} is found but cannot be invoked
13588 127 if @var{command} cannot be found
13589 the exit status of @var{command} otherwise
13592 It is sometimes useful to run a non-interactive program with reduced niceness.
13595 $ nice factor 4611686018427387903
13598 Since @command{nice} prints the current niceness,
13599 you can invoke it through itself to demonstrate how it works.
13601 The default behavior is to increase the niceness by @samp{10}:
13612 The @var{adjustment} is relative to the current niceness. In the
13613 next example, the first @command{nice} invocation runs the second one
13614 with niceness 10, and it in turn runs the final one with a niceness
13618 $ nice nice -n 3 nice
13622 Specifying a niceness larger than the supported range
13623 is the same as specifying the maximum supported value:
13626 $ nice -n 10000000000 nice
13630 Only a privileged user may run a process with lower niceness:
13634 nice: cannot set niceness: Permission denied
13636 $ sudo nice -n -1 nice
13641 @node nohup invocation
13642 @section @command{nohup}: Run a command immune to hangups
13645 @cindex hangups, immunity to
13646 @cindex immunity to hangups
13647 @cindex logging out and continuing to run
13650 @command{nohup} runs the given @var{command} with hangup signals ignored,
13651 so that the command can continue running in the background after you log
13655 nohup @var{command} [@var{arg}]@dots{}
13658 If standard input is a terminal, it is redirected from
13659 @file{/dev/null} so that terminal sessions do not mistakenly consider
13660 the terminal to be used by the command. This is a @acronym{GNU}
13661 extension; programs intended to be portable to non-@acronym{GNU} hosts
13662 should use @samp{nohup @var{command} [@var{arg}]@dots{} </dev/null}
13666 If standard output is a terminal, the command's standard output is appended
13667 to the file @file{nohup.out}; if that cannot be written to, it is appended
13668 to the file @file{$HOME/nohup.out}; and if that cannot be written to, the
13669 command is not run.
13670 Any @file{nohup.out} or @file{$HOME/nohup.out} file created by
13671 @command{nohup} is made readable and writable only to the user,
13672 regardless of the current umask settings.
13674 If standard error is a terminal, it is normally redirected to the same file
13675 descriptor as the (possibly-redirected) standard output.
13676 However, if standard output is closed, standard error terminal output
13677 is instead appended to the file @file{nohup.out} or
13678 @file{$HOME/nohup.out} as above.
13680 To capture the command's output to a file other than @file{nohup.out}
13681 you can redirect it. For example, to capture the output of
13685 nohup make > make.log
13688 @command{nohup} does not automatically put the command it runs in the
13689 background; you must do that explicitly, by ending the command line
13690 with an @samp{&}. Also, @command{nohup} does not alter the
13691 niceness of @var{command}; use @command{nice} for that,
13692 e.g., @samp{nohup nice @var{command}}.
13694 @var{command} must not be a special built-in utility (@pxref{Special
13695 built-in utilities}).
13697 The only options are @option{--help} and @option{--version}. @xref{Common
13698 options}. Options must precede operands.
13700 @cindex exit status of @command{nohup}
13704 126 if @var{command} is found but cannot be invoked
13705 127 if @command{nohup} itself fails or if @var{command} cannot be found
13706 the exit status of @var{command} otherwise
13710 @node su invocation
13711 @section @command{su}: Run a command with substitute user and group ID
13714 @cindex substitute user and group IDs
13715 @cindex user ID, switching
13716 @cindex super-user, becoming
13717 @cindex root, becoming
13719 @command{su} allows one user to temporarily become another user. It runs a
13720 command (often an interactive shell) with the real and effective user
13721 ID, group ID, and supplemental groups of a given @var{user}. Synopsis:
13724 su [@var{option}]@dots{} [@var{user} [@var{arg}]@dots{}]
13727 @cindex passwd entry, and @command{su} shell
13729 @flindex /etc/passwd
13730 If no @var{user} is given, the default is @code{root}, the super-user.
13731 The shell to use is taken from @var{user}'s @code{passwd} entry, or
13732 @file{/bin/sh} if none is specified there. If @var{user} has a
13733 password, @command{su} prompts for the password unless run by a user with
13734 effective user ID of zero (the super-user).
13740 @cindex login shell
13741 By default, @command{su} does not change the current directory.
13742 It sets the environment variables @env{HOME} and @env{SHELL}
13743 from the password entry for @var{user}, and if @var{user} is not
13744 the super-user, sets @env{USER} and @env{LOGNAME} to @var{user}.
13745 By default, the shell is not a login shell.
13747 Any additional @var{arg}s are passed as additional arguments to the
13750 @cindex @option{-su}
13751 GNU @command{su} does not treat @file{/bin/sh} or any other shells specially
13752 (e.g., by setting @code{argv[0]} to @option{-su}, passing @option{-c} only
13753 to certain shells, etc.).
13756 @command{su} can optionally be compiled to use @code{syslog} to report
13757 failed, and optionally successful, @command{su} attempts. (If the system
13758 supports @code{syslog}.) However, GNU @command{su} does not check if the
13759 user is a member of the @code{wheel} group; see below.
13761 The program accepts the following options. Also see @ref{Common options}.
13764 @item -c @var{command}
13765 @itemx --command=@var{command}
13768 Pass @var{command}, a single command line to run, to the shell with
13769 a @option{-c} option instead of starting an interactive shell.
13776 @cindex file name pattern expansion, disabled
13777 @cindex globbing, disabled
13778 Pass the @option{-f} option to the shell. This probably only makes sense
13779 if the shell run is @command{csh} or @command{tcsh}, for which the @option{-f}
13780 option prevents reading the startup file (@file{.cshrc}). With
13781 Bourne-like shells, the @option{-f} option disables file name pattern
13782 expansion (globbing), which is not likely to be useful.
13790 @c other variables already indexed above
13793 @cindex login shell, creating
13794 Make the shell a login shell. This means the following. Unset all
13795 environment variables except @env{TERM}, @env{HOME}, and @env{SHELL}
13796 (which are set as described above), and @env{USER} and @env{LOGNAME}
13797 (which are set, even for the super-user, as described above), and set
13798 @env{PATH} to a compiled-in default value. Change to @var{user}'s home
13799 directory. Prepend @samp{-} to the shell's name, intended to make it
13800 read its login startup file(s).
13804 @itemx --preserve-environment
13807 @opindex --preserve-environment
13808 @cindex environment, preserving
13809 @flindex /etc/shells
13810 @cindex restricted shell
13811 Do not change the environment variables @env{HOME}, @env{USER},
13812 @env{LOGNAME}, or @env{SHELL}. Run the shell given in the environment
13813 variable @env{SHELL} instead of the shell from @var{user}'s passwd
13814 entry, unless the user running @command{su} is not the super-user and
13815 @var{user}'s shell is restricted. A @dfn{restricted shell} is one that
13816 is not listed in the file @file{/etc/shells}, or in a compiled-in list
13817 if that file does not exist. Parts of what this option does can be
13818 overridden by @option{--login} and @option{--shell}.
13820 @item -s @var{shell}
13821 @itemx --shell=@var{shell}
13824 Run @var{shell} instead of the shell from @var{user}'s passwd entry,
13825 unless the user running @command{su} is not the super-user and @var{user}'s
13826 shell is restricted (see @option{-m} just above).
13830 @cindex exit status of @command{su}
13834 1 if @command{su} itself fails
13835 126 if subshell is found but cannot be invoked
13836 127 if subshell cannot be found
13837 the exit status of the subshell otherwise
13840 @cindex wheel group, not supported
13841 @cindex group wheel, not supported
13843 @subsection Why GNU @command{su} does not support the @samp{wheel} group
13845 (This section is by Richard Stallman.)
13849 Sometimes a few of the users try to hold total power over all the
13850 rest. For example, in 1984, a few users at the MIT AI lab decided to
13851 seize power by changing the operator password on the Twenex system and
13852 keeping it secret from everyone else. (I was able to thwart this coup
13853 and give power back to the users by patching the kernel, but I
13854 wouldn't know how to do that in Unix.)
13856 However, occasionally the rulers do tell someone. Under the usual
13857 @command{su} mechanism, once someone learns the root password who
13858 sympathizes with the ordinary users, he or she can tell the rest. The
13859 ``wheel group'' feature would make this impossible, and thus cement the
13860 power of the rulers.
13862 I'm on the side of the masses, not that of the rulers. If you are
13863 used to supporting the bosses and sysadmins in whatever they do, you
13864 might find this idea strange at first.
13867 @node Process control
13868 @chapter Process control
13870 @cindex processes, commands for controlling
13871 @cindex commands for controlling processes
13874 * kill invocation:: Sending a signal to processes.
13878 @node kill invocation
13879 @section @command{kill}: Send a signal to processes
13882 @cindex send a signal to processes
13884 The @command{kill} command sends a signal to processes, causing them
13885 to terminate or otherwise act upon receiving the signal in some way.
13886 Alternatively, it lists information about signals. Synopses:
13889 kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{}
13890 kill [-l | --list | -t | --table] [@var{signal}]@dots{}
13893 The first form of the @command{kill} command sends a signal to all
13894 @var{pid} arguments. The default signal to send if none is specified
13895 is @samp{TERM}. The special signal number @samp{0} does not denote a
13896 valid signal, but can be used to test whether the @var{pid} arguments
13897 specify processes to which a signal could be sent.
13899 If @var{pid} is positive, the signal is sent to the process with the
13900 process ID @var{pid}. If @var{pid} is zero, the signal is sent to all
13901 processes in the process group of the current process. If @var{pid}
13902 is @minus{}1, the signal is sent to all processes for which the user has
13903 permission to send a signal. If @var{pid} is less than @minus{}1, the signal
13904 is sent to all processes in the process group that equals the absolute
13905 value of @var{pid}.
13907 If @var{pid} is not positive, a system-dependent set of system
13908 processes is excluded from the list of processes to which the signal
13911 If a negative @var{PID} argument is desired as the first one, it
13912 should be preceded by @option{--}. However, as a common extension to
13913 @acronym{POSIX}, @option{--} is not required with @samp{kill
13914 -@var{signal} -@var{pid}}. The following commands are equivalent:
13923 The first form of the @command{kill} command succeeds if every @var{pid}
13924 argument specifies at least one process that the signal was sent to.
13926 The second form of the @command{kill} command lists signal information.
13927 Either the @option{-l} or @option{--list} option, or the @option{-t}
13928 or @option{--table} option must be specified. Without any
13929 @var{signal} argument, all supported signals are listed. The output
13930 of @option{-l} or @option{--list} is a list of the signal names, one
13931 per line; if @var{signal} is already a name, the signal number is
13932 printed instead. The output of @option{-t} or @option{--table} is a
13933 table of signal numbers, names, and descriptions. This form of the
13934 @command{kill} command succeeds if all @var{signal} arguments are valid
13935 and if there is no output error.
13937 The @command{kill} command also supports the @option{--help} and
13938 @option{--version} options. @xref{Common options}.
13940 A @var{signal} may be a signal name like @samp{HUP}, or a signal
13941 number like @samp{1}, or an exit status of a process terminated by the
13942 signal. A signal name can be given in canonical form or prefixed by
13943 @samp{SIG}. The case of the letters is ignored, except for the
13944 @option{-@var{signal}} option which must use upper case to avoid
13945 ambiguity with lower case option letters. The following signal names
13946 and numbers are supported on all @acronym{POSIX} compliant systems:
13952 2. Terminal interrupt.
13958 9. Kill (cannot be caught or ignored).
13966 Other supported signal names have system-dependent corresponding
13967 numbers. All systems conforming to @acronym{POSIX} 1003.1-2001 also
13968 support the following signals:
13972 Access to an undefined portion of a memory object.
13974 Child process terminated, stopped, or continued.
13976 Continue executing, if stopped.
13978 Erroneous arithmetic operation.
13980 Illegal Instruction.
13982 Write on a pipe with no one to read it.
13984 Invalid memory reference.
13986 Stop executing (cannot be caught or ignored).
13990 Background process attempting read.
13992 Background process attempting write.
13994 High bandwidth data is available at a socket.
13996 User-defined signal 1.
13998 User-defined signal 2.
14002 @acronym{POSIX} 1003.1-2001 systems that support the @acronym{XSI} extension
14003 also support the following signals:
14009 Profiling timer expired.
14013 Trace/breakpoint trap.
14015 Virtual timer expired.
14017 CPU time limit exceeded.
14019 File size limit exceeded.
14023 @acronym{POSIX} 1003.1-2001 systems that support the @acronym{XRT} extension
14024 also support at least eight real-time signals called @samp{RTMIN},
14025 @samp{RTMIN+1}, @dots{}, @samp{RTMAX-1}, @samp{RTMAX}.
14031 @cindex delaying commands
14032 @cindex commands for delaying
14034 @c Perhaps @command{wait} or other commands should be described here also?
14037 * sleep invocation:: Delay for a specified time.
14041 @node sleep invocation
14042 @section @command{sleep}: Delay for a specified time
14045 @cindex delay for a specified time
14047 @command{sleep} pauses for an amount of time specified by the sum of
14048 the values of the command line arguments.
14052 sleep @var{number}[smhd]@dots{}
14056 Each argument is a number followed by an optional unit; the default
14057 is seconds. The units are:
14070 Historical implementations of @command{sleep} have required that
14071 @var{number} be an integer, and only accepted a single argument
14072 without a suffix. However, GNU @command{sleep} accepts
14073 arbitrary floating point numbers (using a period before any fractional
14076 The only options are @option{--help} and @option{--version}. @xref{Common
14082 @node Numeric operations
14083 @chapter Numeric operations
14085 @cindex numeric operations
14086 These programs do numerically-related operations.
14089 * factor invocation:: Show factors of numbers.
14090 * seq invocation:: Print sequences of numbers.
14094 @node factor invocation
14095 @section @command{factor}: Print prime factors
14098 @cindex prime factors
14100 @command{factor} prints prime factors. Synopses:
14103 factor [@var{number}]@dots{}
14104 factor @var{option}
14107 If no @var{number} is specified on the command line, @command{factor} reads
14108 numbers from standard input, delimited by newlines, tabs, or spaces.
14110 The only options are @option{--help} and @option{--version}. @xref{Common
14113 The algorithm it uses is not very sophisticated, so for some inputs
14114 @command{factor} runs for a long time. The hardest numbers to factor are
14115 the products of large primes. Factoring the product of the two largest 32-bit
14116 prime numbers takes about 80 seconds of CPU time on a 1.6 GHz Athlon.
14119 $ p=`echo '4294967279 * 4294967291'|bc`
14121 18446743979220271189: 4294967279 4294967291
14124 Similarly, it takes about 80 seconds for GNU factor (from coreutils-5.1.2)
14125 to ``factor'' the largest 64-bit prime:
14128 $ factor 18446744073709551557
14129 18446744073709551557: 18446744073709551557
14132 In contrast, @command{factor} factors the largest 64-bit number in just
14133 over a tenth of a second:
14136 $ factor `echo '2^64-1'|bc`
14137 18446744073709551615: 3 5 17 257 641 65537 6700417
14143 @node seq invocation
14144 @section @command{seq}: Print numeric sequences
14147 @cindex numeric sequences
14148 @cindex sequence of numbers
14150 @command{seq} prints a sequence of numbers to standard output. Synopses:
14153 seq [@var{option}]@dots{} @var{last}
14154 seq [@var{option}]@dots{} @var{first} @var{last}
14155 seq [@var{option}]@dots{} @var{first} @var{increment} @var{last}
14158 @command{seq} prints the numbers from @var{first} to @var{last} by
14159 @var{increment}. By default, each number is printed on a separate line.
14160 When @var{increment} is not specified, it defaults to @samp{1},
14161 even when @var{first} is larger than @var{last}.
14162 @var{first} also defaults to @samp{1}. So @code{seq 1} prints
14163 @samp{1}, but @code{seq 0} and @code{seq 10 5} produce no output.
14164 Floating-point numbers
14165 may be specified (using a period before any fractional digits).
14167 The program accepts the following options. Also see @ref{Common options}.
14168 Options must precede operands.
14171 @item -f @var{format}
14172 @itemx --format=@var{format}
14173 @opindex -f @var{format}
14174 @opindex --format=@var{format}
14175 @cindex formatting of numbers in @command{seq}
14176 Print all numbers using @var{format}.
14177 @var{format} must contain exactly one of the @samp{printf}-style
14178 floating point conversion specifications @samp{%a}, @samp{%e},
14179 @samp{%f}, @samp{%g}, @samp{%A}, @samp{%E}, @samp{%F}, @samp{%G}.
14180 The @samp{%} may be followed by zero or more flags taken from the set
14181 @samp{-+#0 '}, then an optional width containing one or more digits,
14182 then an optional precision consisting of a @samp{.} followed by zero
14183 or more digits. @var{format} may also contain any number of @samp{%%}
14184 conversion specifications. All conversion specifications have the
14185 same meaning as with @samp{printf}.
14187 The default format is derived from @var{first}, @var{step}, and
14188 @var{last}. If these all use a fixed point decimal representation,
14189 the default format is @samp{%.@var{p}f}, where @var{p} is the minimum
14190 precision that can represent the output numbers exactly. Otherwise,
14191 the default format is @samp{%g}.
14193 @item -s @var{string}
14194 @itemx --separator=@var{string}
14195 @cindex separator for numbers in @command{seq}
14196 Separate numbers with @var{string}; default is a newline.
14197 The output always terminates with a newline.
14200 @itemx --equal-width
14201 Print all numbers with the same width, by padding with leading zeros.
14202 @var{first}, @var{step}, and @var{last} should all use a fixed point
14203 decimal representation.
14204 (To have other kinds of padding, use @option{--format}).
14208 You can get finer-grained control over output with @option{-f}:
14211 $ seq -f '(%9.2E)' -9e5 1.1e6 1.3e6
14217 If you want hexadecimal integer output, you can use @command{printf}
14218 to perform the conversion:
14221 $ printf '%x\n' `seq 1048575 1024 1050623`
14227 For very long lists of numbers, use xargs to avoid
14228 system limitations on the length of an argument list:
14231 $ seq 1000000 | xargs printf '%x\n' | tail -n 3
14237 To generate octal output, use the printf @code{%o} format instead
14240 On most systems, seq can produce whole-number output for values up to
14241 at least @math{2^{53}}. Larger integers are approximated. The details
14242 differ depending on your floating-point implementation, but a common
14243 case is that @command{seq} works with integers through @math{2^{64}},
14244 and larger integers may not be numerically correct:
14247 $ seq 18446744073709551616 1 18446744073709551618
14248 18446744073709551616
14249 18446744073709551616
14250 18446744073709551618
14253 Be careful when using @command{seq} with outlandish values: otherwise
14254 you may see surprising results, as @command{seq} uses floating point
14255 internally. For example, on the x86 platform, where the internal
14256 representation uses a 64-bit fraction, the command:
14259 seq 1 0.0000000000000000001 1.0000000000000000009
14262 outputs 1.0000000000000000007 twice and skips 1.0000000000000000008.
14267 @node File permissions
14268 @chapter File permissions
14271 @include getdate.texi
14275 @node Opening the software toolbox
14276 @chapter Opening the Software Toolbox
14278 An earlier version of this chapter appeared in
14279 @uref{http://www.linuxjournal.com/article.php?sid=2762, the
14280 @cite{What's GNU?} column of @cite{Linux Journal}, 2 (June, 1994)}.
14281 It was written by Arnold Robbins.
14284 * Toolbox introduction:: Toolbox introduction
14285 * I/O redirection:: I/O redirection
14286 * The who command:: The @command{who} command
14287 * The cut command:: The @command{cut} command
14288 * The sort command:: The @command{sort} command
14289 * The uniq command:: The @command{uniq} command
14290 * Putting the tools together:: Putting the tools together
14294 @node Toolbox introduction
14295 @unnumberedsec Toolbox Introduction
14297 This month's column is only peripherally related to the GNU Project, in
14298 that it describes a number of the GNU tools on your GNU/Linux system and how they
14299 might be used. What it's really about is the ``Software Tools'' philosophy
14300 of program development and usage.
14302 The software tools philosophy was an important and integral concept
14303 in the initial design and development of Unix (of which Linux and GNU are
14304 essentially clones). Unfortunately, in the modern day press of
14305 Internetworking and flashy GUIs, it seems to have fallen by the
14306 wayside. This is a shame, since it provides a powerful mental model
14307 for solving many kinds of problems.
14309 Many people carry a Swiss Army knife around in their pants pockets (or
14310 purse). A Swiss Army knife is a handy tool to have: it has several knife
14311 blades, a screwdriver, tweezers, toothpick, nail file, corkscrew, and perhaps
14312 a number of other things on it. For the everyday, small miscellaneous jobs
14313 where you need a simple, general purpose tool, it's just the thing.
14315 On the other hand, an experienced carpenter doesn't build a house using
14316 a Swiss Army knife. Instead, he has a toolbox chock full of specialized
14317 tools---a saw, a hammer, a screwdriver, a plane, and so on. And he knows
14318 exactly when and where to use each tool; you won't catch him hammering nails
14319 with the handle of his screwdriver.
14321 The Unix developers at Bell Labs were all professional programmers and trained
14322 computer scientists. They had found that while a one-size-fits-all program
14323 might appeal to a user because there's only one program to use, in practice
14328 difficult to write,
14331 difficult to maintain and
14335 difficult to extend to meet new situations.
14338 Instead, they felt that programs should be specialized tools. In short, each
14339 program ``should do one thing well.'' No more and no less. Such programs are
14340 simpler to design, write, and get right---they only do one thing.
14342 Furthermore, they found that with the right machinery for hooking programs
14343 together, that the whole was greater than the sum of the parts. By combining
14344 several special purpose programs, you could accomplish a specific task
14345 that none of the programs was designed for, and accomplish it much more
14346 quickly and easily than if you had to write a special purpose program.
14347 We will see some (classic) examples of this further on in the column.
14348 (An important additional point was that, if necessary, take a detour
14349 and build any software tools you may need first, if you don't already
14350 have something appropriate in the toolbox.)
14352 @node I/O redirection
14353 @unnumberedsec I/O Redirection
14355 Hopefully, you are familiar with the basics of I/O redirection in the
14356 shell, in particular the concepts of ``standard input,'' ``standard output,''
14357 and ``standard error''. Briefly, ``standard input'' is a data source, where
14358 data comes from. A program should not need to either know or care if the
14359 data source is a disk file, a keyboard, a magnetic tape, or even a punched
14360 card reader. Similarly, ``standard output'' is a data sink, where data goes
14361 to. The program should neither know nor care where this might be.
14362 Programs that only read their standard input, do something to the data,
14363 and then send it on, are called @dfn{filters}, by analogy to filters in a
14366 With the Unix shell, it's very easy to set up data pipelines:
14369 program_to_create_data | filter1 | ... | filterN > final.pretty.data
14372 We start out by creating the raw data; each filter applies some successive
14373 transformation to the data, until by the time it comes out of the pipeline,
14374 it is in the desired form.
14376 This is fine and good for standard input and standard output. Where does the
14377 standard error come in to play? Well, think about @command{filter1} in
14378 the pipeline above. What happens if it encounters an error in the data it
14379 sees? If it writes an error message to standard output, it will just
14380 disappear down the pipeline into @command{filter2}'s input, and the
14381 user will probably never see it. So programs need a place where they can send
14382 error messages so that the user will notice them. This is standard error,
14383 and it is usually connected to your console or window, even if you have
14384 redirected standard output of your program away from your screen.
14386 For filter programs to work together, the format of the data has to be
14387 agreed upon. The most straightforward and easiest format to use is simply
14388 lines of text. Unix data files are generally just streams of bytes, with
14389 lines delimited by the @acronym{ASCII} @sc{lf} (Line Feed) character,
14390 conventionally called a ``newline'' in the Unix literature. (This is
14391 @code{'\n'} if you're a C programmer.) This is the format used by all
14392 the traditional filtering programs. (Many earlier operating systems
14393 had elaborate facilities and special purpose programs for managing
14394 binary data. Unix has always shied away from such things, under the
14395 philosophy that it's easiest to simply be able to view and edit your
14396 data with a text editor.)
14398 OK, enough introduction. Let's take a look at some of the tools, and then
14399 we'll see how to hook them together in interesting ways. In the following
14400 discussion, we will only present those command line options that interest
14401 us. As you should always do, double check your system documentation
14402 for the full story.
14404 @node The who command
14405 @unnumberedsec The @command{who} Command
14407 The first program is the @command{who} command. By itself, it generates a
14408 list of the users who are currently logged in. Although I'm writing
14409 this on a single-user system, we'll pretend that several people are
14414 @print{} arnold console Jan 22 19:57
14415 @print{} miriam ttyp0 Jan 23 14:19(:0.0)
14416 @print{} bill ttyp1 Jan 21 09:32(:0.0)
14417 @print{} arnold ttyp2 Jan 23 20:48(:0.0)
14420 Here, the @samp{$} is the usual shell prompt, at which I typed @samp{who}.
14421 There are three people logged in, and I am logged in twice. On traditional
14422 Unix systems, user names are never more than eight characters long. This
14423 little bit of trivia will be useful later. The output of @command{who} is nice,
14424 but the data is not all that exciting.
14426 @node The cut command
14427 @unnumberedsec The @command{cut} Command
14429 The next program we'll look at is the @command{cut} command. This program
14430 cuts out columns or fields of input data. For example, we can tell it
14431 to print just the login name and full name from the @file{/etc/passwd}
14432 file. The @file{/etc/passwd} file has seven fields, separated by
14436 arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/bash
14439 To get the first and fifth fields, we would use @command{cut} like this:
14442 $ cut -d: -f1,5 /etc/passwd
14443 @print{} root:Operator
14445 @print{} arnold:Arnold D. Robbins
14446 @print{} miriam:Miriam A. Robbins
14450 With the @option{-c} option, @command{cut} will cut out specific characters
14451 (i.e., columns) in the input lines. This is useful for input data
14452 that has fixed width fields, and does not have a field separator. For
14453 example, list the Monday dates for the current month:
14455 @c Is using cal ok? Looked at gcal, but I don't like it.
14466 @node The sort command
14467 @unnumberedsec The @command{sort} Command
14469 Next we'll look at the @command{sort} command. This is one of the most
14470 powerful commands on a Unix-style system; one that you will often find
14471 yourself using when setting up fancy data plumbing.
14474 command reads and sorts each file named on the command line. It then
14475 merges the sorted data and writes it to standard output. It will read
14476 standard input if no files are given on the command line (thus
14477 making it into a filter). The sort is based on the character collating
14478 sequence or based on user-supplied ordering criteria.
14481 @node The uniq command
14482 @unnumberedsec The @command{uniq} Command
14484 Finally (at least for now), we'll look at the @command{uniq} program. When
14485 sorting data, you will often end up with duplicate lines, lines that
14486 are identical. Usually, all you need is one instance of each line.
14487 This is where @command{uniq} comes in. The @command{uniq} program reads its
14488 standard input. It prints only one
14489 copy of each repeated line. It does have several options. Later on,
14490 we'll use the @option{-c} option, which prints each unique line, preceded
14491 by a count of the number of times that line occurred in the input.
14494 @node Putting the tools together
14495 @unnumberedsec Putting the Tools Together
14497 Now, let's suppose this is a large ISP server system with dozens of users
14498 logged in. The management wants the system administrator to write a program that will
14499 generate a sorted list of logged in users. Furthermore, even if a user
14500 is logged in multiple times, his or her name should only show up in the
14503 The administrator could sit down with the system documentation and write a C
14504 program that did this. It would take perhaps a couple of hundred lines
14505 of code and about two hours to write it, test it, and debug it.
14506 However, knowing the software toolbox, the administrator can instead start out
14507 by generating just a list of logged on users:
14517 Next, sort the list:
14520 $ who | cut -c1-8 | sort
14527 Finally, run the sorted list through @command{uniq}, to weed out duplicates:
14530 $ who | cut -c1-8 | sort | uniq
14536 The @command{sort} command actually has a @option{-u} option that does what
14537 @command{uniq} does. However, @command{uniq} has other uses for which one
14538 cannot substitute @samp{sort -u}.
14540 The administrator puts this pipeline into a shell script, and makes it available for
14541 all the users on the system (@samp{#} is the system administrator,
14542 or @code{root}, prompt):
14545 # cat > /usr/local/bin/listusers
14546 who | cut -c1-8 | sort | uniq
14548 # chmod +x /usr/local/bin/listusers
14551 There are four major points to note here. First, with just four
14552 programs, on one command line, the administrator was able to save about two
14553 hours worth of work. Furthermore, the shell pipeline is just about as
14554 efficient as the C program would be, and it is much more efficient in
14555 terms of programmer time. People time is much more expensive than
14556 computer time, and in our modern ``there's never enough time to do
14557 everything'' society, saving two hours of programmer time is no mean
14560 Second, it is also important to emphasize that with the
14561 @emph{combination} of the tools, it is possible to do a special
14562 purpose job never imagined by the authors of the individual programs.
14564 Third, it is also valuable to build up your pipeline in stages, as we did here.
14565 This allows you to view the data at each stage in the pipeline, which helps
14566 you acquire the confidence that you are indeed using these tools correctly.
14568 Finally, by bundling the pipeline in a shell script, other users can use
14569 your command, without having to remember the fancy plumbing you set up for
14570 them. In terms of how you run them, shell scripts and compiled programs are
14573 After the previous warm-up exercise, we'll look at two additional, more
14574 complicated pipelines. For them, we need to introduce two more tools.
14576 The first is the @command{tr} command, which stands for ``transliterate.''
14577 The @command{tr} command works on a character-by-character basis, changing
14578 characters. Normally it is used for things like mapping upper case to
14582 $ echo ThIs ExAmPlE HaS MIXED case! | tr '[:upper:]' '[:lower:]'
14583 @print{} this example has mixed case!
14586 There are several options of interest:
14590 work on the complement of the listed characters, i.e.,
14591 operations apply to characters not in the given set
14594 delete characters in the first set from the output
14597 squeeze repeated characters in the output into just one character.
14600 We will be using all three options in a moment.
14602 The other command we'll look at is @command{comm}. The @command{comm}
14603 command takes two sorted input files as input data, and prints out the
14604 files' lines in three columns. The output columns are the data lines
14605 unique to the first file, the data lines unique to the second file, and
14606 the data lines that are common to both. The @option{-1}, @option{-2}, and
14607 @option{-3} command line options @emph{omit} the respective columns. (This is
14608 non-intuitive and takes a little getting used to.) For example:
14630 The file name @file{-} tells @command{comm} to read standard input
14631 instead of a regular file.
14633 Now we're ready to build a fancy pipeline. The first application is a word
14634 frequency counter. This helps an author determine if he or she is over-using
14637 The first step is to change the case of all the letters in our input file
14638 to one case. ``The'' and ``the'' are the same word when doing counting.
14641 $ tr '[:upper:]' '[:lower:]' < whats.gnu | ...
14644 The next step is to get rid of punctuation. Quoted words and unquoted words
14645 should be treated identically; it's easiest to just get the punctuation out of
14649 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | ...
14652 The second @command{tr} command operates on the complement of the listed
14653 characters, which are all the letters, the digits, the underscore, and
14654 the blank. The @samp{\n} represents the newline character; it has to
14655 be left alone. (The @acronym{ASCII} tab character should also be included for
14656 good measure in a production script.)
14658 At this point, we have data consisting of words separated by blank space.
14659 The words only contain alphanumeric characters (and the underscore). The
14660 next step is break the data apart so that we have one word per line. This
14661 makes the counting operation much easier, as we will see shortly.
14664 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
14665 > tr -s ' ' '\n' | ...
14668 This command turns blanks into newlines. The @option{-s} option squeezes
14669 multiple newline characters in the output into just one. This helps us
14670 avoid blank lines. (The @samp{>} is the shell's ``secondary prompt.''
14671 This is what the shell prints when it notices you haven't finished
14672 typing in all of a command.)
14674 We now have data consisting of one word per line, no punctuation, all one
14675 case. We're ready to count each word:
14678 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
14679 > tr -s ' ' '\n' | sort | uniq -c | ...
14682 At this point, the data might look something like this:
14695 The output is sorted by word, not by count! What we want is the most
14696 frequently used words first. Fortunately, this is easy to accomplish,
14697 with the help of two more @command{sort} options:
14701 do a numeric sort, not a textual one
14704 reverse the order of the sort
14707 The final pipeline looks like this:
14710 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
14711 > tr -s ' ' '\n' | sort | uniq -c | sort -n -r
14720 Whew! That's a lot to digest. Yet, the same principles apply. With six
14721 commands, on two lines (really one long one split for convenience), we've
14722 created a program that does something interesting and useful, in much
14723 less time than we could have written a C program to do the same thing.
14725 A minor modification to the above pipeline can give us a simple spelling
14726 checker! To determine if you've spelled a word correctly, all you have to
14727 do is look it up in a dictionary. If it is not there, then chances are
14728 that your spelling is incorrect. So, we need a dictionary.
14729 The conventional location for a dictionary is @file{/usr/dict/words}.
14730 On my GNU/Linux system,@footnote{Redhat Linux 6.1, for the November 2000
14731 revision of this article.}
14732 this is a is a sorted, 45,402 word dictionary.
14734 Now, how to compare our file with the dictionary? As before, we generate
14735 a sorted list of words, one per line:
14738 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
14739 > tr -s ' ' '\n' | sort -u | ...
14742 Now, all we need is a list of words that are @emph{not} in the
14743 dictionary. Here is where the @command{comm} command comes in.
14746 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
14747 > tr -s ' ' '\n' | sort -u |
14748 > comm -23 - /usr/dict/words
14751 The @option{-2} and @option{-3} options eliminate lines that are only in the
14752 dictionary (the second file), and lines that are in both files. Lines
14753 only in the first file (standard input, our stream of words), are
14754 words that are not in the dictionary. These are likely candidates for
14755 spelling errors. This pipeline was the first cut at a production
14756 spelling checker on Unix.
14758 There are some other tools that deserve brief mention.
14762 search files for text that matches a regular expression
14765 count lines, words, characters
14768 a T-fitting for data pipes, copies data to files and to standard output
14771 the stream editor, an advanced tool
14774 a data manipulation language, another advanced tool
14777 The software tools philosophy also espoused the following bit of
14778 advice: ``Let someone else do the hard part.'' This means, take
14779 something that gives you most of what you need, and then massage it the
14780 rest of the way until it's in the form that you want.
14786 Each program should do one thing well. No more, no less.
14789 Combining programs with appropriate plumbing leads to results where
14790 the whole is greater than the sum of the parts. It also leads to novel
14791 uses of programs that the authors might never have imagined.
14794 Programs should never print extraneous header or trailer data, since these
14795 could get sent on down a pipeline. (A point we didn't mention earlier.)
14798 Let someone else do the hard part.
14801 Know your toolbox! Use each program appropriately. If you don't have an
14802 appropriate tool, build one.
14805 As of this writing, all the programs we've discussed are available via
14806 anonymous @command{ftp} from: @*
14807 @uref{ftp://gnudist.gnu.org/textutils/textutils-1.22.tar.gz}. (There may
14808 be more recent versions available now.)
14810 None of what I have presented in this column is new. The Software Tools
14811 philosophy was first introduced in the book @cite{Software Tools}, by
14812 Brian Kernighan and P.J. Plauger (Addison-Wesley, ISBN 0-201-03669-X).
14813 This book showed how to write and use software tools. It was written in
14814 1976, using a preprocessor for FORTRAN named @command{ratfor} (RATional
14815 FORtran). At the time, C was not as ubiquitous as it is now; FORTRAN
14816 was. The last chapter presented a @command{ratfor} to FORTRAN
14817 processor, written in @command{ratfor}. @command{ratfor} looks an awful
14818 lot like C; if you know C, you won't have any problem following the
14821 In 1981, the book was updated and made available as @cite{Software Tools
14822 in Pascal} (Addison-Wesley, ISBN 0-201-10342-7). Both books are
14823 still in print and are well worth
14824 reading if you're a programmer. They certainly made a major change in
14825 how I view programming.
14827 The programs in both books are available from
14828 @uref{http://cm.bell-labs.com/who/bwk, Brian Kernighan's home page}.
14829 For a number of years, there was an active
14830 Software Tools Users Group, whose members had ported the original
14831 @command{ratfor} programs to essentially every computer system with a
14832 FORTRAN compiler. The popularity of the group waned in the middle 1980s
14833 as Unix began to spread beyond universities.
14835 With the current proliferation of GNU code and other clones of Unix programs,
14836 these programs now receive little attention; modern C versions are
14837 much more efficient and do more than these programs do. Nevertheless, as
14838 exposition of good programming style, and evangelism for a still-valuable
14839 philosophy, these books are unparalleled, and I recommend them highly.
14841 Acknowledgment: I would like to express my gratitude to Brian Kernighan
14842 of Bell Labs, the original Software Toolsmith, for reviewing this column.
14844 @node GNU Free Documentation License
14845 @appendix GNU Free Documentation License
14849 @node Concept index
14858 @c Local variables:
14859 @c texinfo-column-for-description: 32
projects / platform / upstream / coreutils.git / blob