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 * mktemp: (coreutils)mktemp 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 * chcon: (coreutils)chcon invocation. Change SELinux CTX of files.
43 * chgrp: (coreutils)chgrp invocation. Change file groups.
44 * chmod: (coreutils)chmod invocation. Change file permissions.
45 * chown: (coreutils)chown invocation. Change file owners/groups.
46 * chroot: (coreutils)chroot invocation. Specify the root directory.
47 * cksum: (coreutils)cksum invocation. Print POSIX CRC checksum.
48 * comm: (coreutils)comm invocation. Compare sorted files by line.
49 * cp: (coreutils)cp invocation. Copy files.
50 * csplit: (coreutils)csplit invocation. Split by context.
51 * cut: (coreutils)cut invocation. Print selected parts of lines.
52 * date: (coreutils)date invocation. Print/set system date and time.
53 * dd: (coreutils)dd invocation. Copy and convert a file.
54 * df: (coreutils)df invocation. Report file system disk usage.
55 * dir: (coreutils)dir invocation. List directories briefly.
56 * dircolors: (coreutils)dircolors invocation. Color setup for ls.
57 * dirname: (coreutils)dirname invocation. Strip non-directory suffix.
58 * du: (coreutils)du invocation. Report on disk usage.
59 * echo: (coreutils)echo invocation. Print a line of text.
60 * env: (coreutils)env invocation. Modify the environment.
61 * expand: (coreutils)expand invocation. Convert tabs to spaces.
62 * expr: (coreutils)expr invocation. Evaluate expressions.
63 * factor: (coreutils)factor invocation. Print prime factors
64 * false: (coreutils)false invocation. Do nothing, unsuccessfully.
65 * fmt: (coreutils)fmt invocation. Reformat paragraph text.
66 * fold: (coreutils)fold invocation. Wrap long input lines.
67 * groups: (coreutils)groups invocation. Print group names a user is in.
68 * head: (coreutils)head invocation. Output the first part of files.
69 * hostid: (coreutils)hostid invocation. Print numeric host identifier.
70 * hostname: (coreutils)hostname invocation. Print or set system name.
71 * id: (coreutils)id invocation. Print user identity.
72 * install: (coreutils)install invocation. Copy and change attributes.
73 * join: (coreutils)join invocation. Join lines on a common field.
74 * kill: (coreutils)kill invocation. Send a signal to processes.
75 * link: (coreutils)link invocation. Make hard links between files.
76 * ln: (coreutils)ln invocation. Make links between files.
77 * logname: (coreutils)logname invocation. Print current login name.
78 * ls: (coreutils)ls invocation. List directory contents.
79 * md5sum: (coreutils)md5sum invocation. Print or check MD5 digests.
80 * mkdir: (coreutils)mkdir invocation. Create directories.
81 * mkfifo: (coreutils)mkfifo invocation. Create FIFOs (named pipes).
82 * mknod: (coreutils)mknod invocation. Create special files.
83 * mv: (coreutils)mv invocation. Rename files.
84 * nice: (coreutils)nice invocation. Modify niceness.
85 * nl: (coreutils)nl invocation. Number lines and write files.
86 * nohup: (coreutils)nohup invocation. Immunize to hangups.
87 * od: (coreutils)od invocation. Dump files in octal, etc.
88 * paste: (coreutils)paste invocation. Merge lines of files.
89 * pathchk: (coreutils)pathchk invocation. Check file name portability.
90 * pr: (coreutils)pr invocation. Paginate or columnate files.
91 * printenv: (coreutils)printenv invocation. Print environment variables.
92 * printf: (coreutils)printf invocation. Format and print data.
93 * ptx: (coreutils)ptx invocation. Produce permuted indexes.
94 * pwd: (coreutils)pwd invocation. Print working directory.
95 * readlink: (coreutils)readlink invocation. Print referent of a symlink.
96 * rm: (coreutils)rm invocation. Remove files.
97 * rmdir: (coreutils)rmdir invocation. Remove empty directories.
98 * runcon: (coreutils)runcon invocation. Run in specified SELinux CTX.
99 * seq: (coreutils)seq invocation. Print numeric sequences
100 * sha1sum: (coreutils)sha1sum invocation. Print or check SHA-1 digests.
101 * sha2: (coreutils)sha2 utilities. Print or check SHA-2 digests.
102 * shred: (coreutils)shred invocation. Remove files more securely.
103 * shuf: (coreutils)shuf invocation. Shuffling text files.
104 * sleep: (coreutils)sleep invocation. Delay for a specified time.
105 * sort: (coreutils)sort invocation. Sort text files.
106 * split: (coreutils)split invocation. Split into fixed-size pieces.
107 * stat: (coreutils)stat invocation. Report file(system) status.
108 * stty: (coreutils)stty invocation. Print/change terminal settings.
109 * su: (coreutils)su invocation. Modify user and group ID.
110 * sum: (coreutils)sum invocation. Print traditional checksum.
111 * sync: (coreutils)sync invocation. Synchronize memory and disk.
112 * tac: (coreutils)tac invocation. Reverse files.
113 * tail: (coreutils)tail invocation. Output the last part of files.
114 * tee: (coreutils)tee invocation. Redirect to multiple files.
115 * test: (coreutils)test invocation. File/string tests.
116 * timeout: (coreutils)timeout invocation. Run with time limit.
117 * touch: (coreutils)touch invocation. Change file timestamps.
118 * tr: (coreutils)tr invocation. Translate characters.
119 * true: (coreutils)true invocation. Do nothing, successfully.
120 * truncate: (coreutils)truncate invocation. Shrink/extend size of a file.
121 * tsort: (coreutils)tsort invocation. Topological sort.
122 * tty: (coreutils)tty invocation. Print terminal name.
123 * uname: (coreutils)uname invocation. Print system information.
124 * unexpand: (coreutils)unexpand invocation. Convert spaces to tabs.
125 * uniq: (coreutils)uniq invocation. Uniquify files.
126 * unlink: (coreutils)unlink invocation. Removal via unlink(2).
127 * uptime: (coreutils)uptime invocation. Print uptime and load.
128 * users: (coreutils)users invocation. Print current user names.
129 * vdir: (coreutils)vdir invocation. List directories verbosely.
130 * wc: (coreutils)wc invocation. Line, word, and byte counts.
131 * who: (coreutils)who invocation. Print who is logged in.
132 * whoami: (coreutils)whoami invocation. Print effective user ID.
133 * yes: (coreutils)yes invocation. Print a string indefinitely.
137 This manual documents version @value{VERSION} of the @sc{gnu} core
138 utilities, including the standard programs for text and file manipulation.
140 Copyright @copyright{} 1994-1996, 2000-2008 Free Software Foundation, Inc.
143 Permission is granted to copy, distribute and/or modify this document
144 under the terms of the GNU Free Documentation License, Version 1.2 or
145 any later version published by the Free Software Foundation; with no
146 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
147 Texts. A copy of the license is included in the section entitled ``GNU
148 Free Documentation License''.
153 @title @sc{gnu} @code{Coreutils}
154 @subtitle Core GNU utilities
155 @subtitle for version @value{VERSION}, @value{UPDATED}
156 @author David MacKenzie et al.
159 @vskip 0pt plus 1filll
171 @cindex core utilities
172 @cindex text utilities
173 @cindex shell utilities
174 @cindex file utilities
177 * Introduction:: Caveats, overview, and authors.
178 * Common options:: Common options.
179 * Output of entire files:: cat tac nl od
180 * Formatting file contents:: fmt pr fold
181 * Output of parts of files:: head tail split csplit
182 * Summarizing files:: wc sum cksum md5sum sha1sum sha2
183 * Operating on sorted files:: sort shuf uniq comm ptx tsort
184 * Operating on fields within a line:: cut paste join
185 * Operating on characters:: tr expand unexpand
186 * Directory listing:: ls dir vdir dircolors
187 * Basic operations:: cp dd install mv rm shred
188 * Special file types:: ln mkdir rmdir mkfifo mknod
189 * Changing file attributes:: chgrp chmod chown touch
190 * Disk usage:: df du stat sync truncate
191 * Printing text:: echo printf yes
192 * Conditions:: false true test expr
194 * File name manipulation:: dirname basename pathchk
195 * Working context:: pwd stty printenv tty
196 * User information:: id logname whoami groups users who
197 * System context:: date uname hostname hostid uptime
198 * SELinux context:: chcon runcon
199 * Modified command invocation:: chroot env nice nohup su timeout
200 * Process control:: kill
202 * Numeric operations:: factor seq
203 * File permissions:: Access modes.
204 * Date input formats:: Specifying date strings.
205 * Opening the software toolbox:: The software tools philosophy.
206 * GNU Free Documentation License:: Copying and sharing this manual.
207 * Concept index:: General index.
210 --- The Detailed Node Listing ---
214 * Exit status:: Indicating program success or failure.
215 * Backup options:: Backup options
216 * Block size:: Block size
217 * Signal specifications:: Specifying signals
218 * Disambiguating names and IDs:: chgrp and chown owner and group syntax
219 * Random sources:: Sources of random data
220 * Target directory:: Target directory
221 * Trailing slashes:: Trailing slashes
222 * Traversing symlinks:: Traversing symlinks to directories
223 * Treating / specially:: Treating / specially
224 * Standards conformance:: Standards conformance
226 Output of entire files
228 * cat invocation:: Concatenate and write files.
229 * tac invocation:: Concatenate and write files in reverse.
230 * nl invocation:: Number lines and write files.
231 * od invocation:: Write files in octal or other formats.
232 * base64 invocation:: Transform data into printable data.
234 Formatting file contents
236 * fmt invocation:: Reformat paragraph text.
237 * pr invocation:: Paginate or columnate files for printing.
238 * fold invocation:: Wrap input lines to fit in specified width.
240 Output of parts of files
242 * head invocation:: Output the first part of files.
243 * tail invocation:: Output the last part of files.
244 * split invocation:: Split a file into fixed-size pieces.
245 * csplit invocation:: Split a file into context-determined pieces.
249 * wc invocation:: Print newline, word, and byte counts.
250 * sum invocation:: Print checksum and block counts.
251 * cksum invocation:: Print CRC checksum and byte counts.
252 * md5sum invocation:: Print or check MD5 digests.
253 * sha1sum invocation:: Print or check SHA-1 digests.
254 * sha2 utilities:: Print or check SHA-2 digests.
256 Operating on sorted files
258 * sort invocation:: Sort text files.
259 * shuf invocation:: Shuffle text files.
260 * uniq invocation:: Uniquify files.
261 * comm invocation:: Compare two sorted files line by line.
262 * ptx invocation:: Produce a permuted index of file contents.
263 * tsort invocation:: Topological sort.
265 @command{ptx}: Produce permuted indexes
267 * General options in ptx:: Options which affect general program behavior.
268 * Charset selection in ptx:: Underlying character set considerations.
269 * Input processing in ptx:: Input fields, contexts, and keyword selection.
270 * Output formatting in ptx:: Types of output format, and sizing the fields.
271 * Compatibility in ptx:: The @acronym{GNU} extensions to @command{ptx}
273 Operating on fields within a line
275 * cut invocation:: Print selected parts of lines.
276 * paste invocation:: Merge lines of files.
277 * join invocation:: Join lines on a common field.
279 Operating on characters
281 * tr invocation:: Translate, squeeze, and/or delete characters.
282 * expand invocation:: Convert tabs to spaces.
283 * unexpand invocation:: Convert spaces to tabs.
285 @command{tr}: Translate, squeeze, and/or delete characters
287 * Character sets:: Specifying sets of characters.
288 * Translating:: Changing one set of characters to another.
289 * Squeezing:: Squeezing repeats and deleting.
293 * ls invocation:: List directory contents
294 * dir invocation:: Briefly list directory contents
295 * vdir invocation:: Verbosely list directory contents
296 * dircolors invocation:: Color setup for @command{ls}
298 @command{ls}: List directory contents
300 * Which files are listed:: Which files are listed
301 * What information is listed:: What information is listed
302 * Sorting the output:: Sorting the output
303 * More details about version sort:: More details about version sort
304 * General output formatting:: General output formatting
305 * Formatting the file names:: Formatting the file names
309 * cp invocation:: Copy files and directories
310 * dd invocation:: Convert and copy a file
311 * install invocation:: Copy files and set attributes
312 * mv invocation:: Move (rename) files
313 * rm invocation:: Remove files or directories
314 * shred invocation:: Remove files more securely
318 * link invocation:: Make a hard link via the link syscall
319 * ln invocation:: Make links between files
320 * mkdir invocation:: Make directories
321 * mkfifo invocation:: Make FIFOs (named pipes)
322 * mknod invocation:: Make block or character special files
323 * readlink invocation:: Print the referent of a symbolic link
324 * rmdir invocation:: Remove empty directories
325 * unlink invocation:: Remove files via unlink syscall
327 Changing file attributes
329 * chown invocation:: Change file owner and group
330 * chgrp invocation:: Change group ownership
331 * chmod invocation:: Change access permissions
332 * touch invocation:: Change file timestamps
336 * df invocation:: Report file system disk space usage
337 * du invocation:: Estimate file space usage
338 * stat invocation:: Report file or file system status
339 * sync invocation:: Synchronize data on disk with memory
340 * truncate invocation:: Shrink or extend the size of a file
344 * echo invocation:: Print a line of text
345 * printf invocation:: Format and print data
346 * yes invocation:: Print a string until interrupted
350 * false invocation:: Do nothing, unsuccessfully
351 * true invocation:: Do nothing, successfully
352 * test invocation:: Check file types and compare values
353 * expr invocation:: Evaluate expressions
355 @command{test}: Check file types and compare values
357 * File type tests:: File type tests
358 * Access permission tests:: Access permission tests
359 * File characteristic tests:: File characteristic tests
360 * String tests:: String tests
361 * Numeric tests:: Numeric tests
363 @command{expr}: Evaluate expression
365 * String expressions:: + : match substr index length
366 * Numeric expressions:: + - * / %
367 * Relations for expr:: | & < <= = == != >= >
368 * Examples of expr:: Examples of using @command{expr}
372 * tee invocation:: Redirect output to multiple files or processes
374 File name manipulation
376 * basename invocation:: Strip directory and suffix from a file name
377 * dirname invocation:: Strip non-directory suffix from a file name
378 * pathchk invocation:: Check file name portability
382 * pwd invocation:: Print working directory
383 * stty invocation:: Print or change terminal characteristics
384 * printenv invocation:: Print all or some environment variables
385 * tty invocation:: Print file name of terminal on standard input
387 @command{stty}: Print or change terminal characteristics
389 * Control:: Control settings
390 * Input:: Input settings
391 * Output:: Output settings
392 * Local:: Local settings
393 * Combination:: Combination settings
394 * Characters:: Special characters
395 * Special:: Special settings
399 * id invocation:: Print user identity
400 * logname invocation:: Print current login name
401 * whoami invocation:: Print effective user ID
402 * groups invocation:: Print group names a user is in
403 * users invocation:: Print login names of users currently logged in
404 * who invocation:: Print who is currently logged in
408 * arch invocation:: Print machine hardware name
409 * date invocation:: Print or set system date and time
410 * uname invocation:: Print system information
411 * hostname invocation:: Print or set system name
412 * hostid invocation:: Print numeric host identifier
413 * uptime invocation:: Print system uptime and load
415 @command{date}: Print or set system date and time
417 * Time conversion specifiers:: %[HIklMNpPrRsSTXzZ]
418 * Date conversion specifiers:: %[aAbBcCdDeFgGhjmuUVwWxyY]
419 * Literal conversion specifiers:: %[%nt]
420 * Padding and other flags:: Pad with zeros, spaces, etc.
421 * Setting the time:: Changing the system clock.
422 * Options for date:: Instead of the current time.
423 * Date input formats:: Specifying date strings.
424 * Examples of date:: Examples.
427 * chcon invocation:: Change SELinux context of file
428 * runcon invocation:: Run a command in specified SELinux context
430 Modified command invocation
432 * chroot invocation:: Run a command with a different root directory
433 * env invocation:: Run a command in a modified environment
434 * nice invocation:: Run a command with modified niceness
435 * nohup invocation:: Run a command immune to hangups
436 * su invocation:: Run a command with substitute user and group ID
437 * timeout invocation:: Run a command with a time limit
441 * kill invocation:: Sending a signal to processes.
445 * sleep invocation:: Delay for a specified time
449 * factor invocation:: Print prime factors
450 * seq invocation:: Print numeric sequences
454 * Mode Structure:: Structure of file mode bits.
455 * Symbolic Modes:: Mnemonic representation of file mode bits.
456 * Numeric Modes:: File mode bits as octal numbers.
457 * Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories.
461 * General date syntax:: Common rules.
462 * Calendar date items:: 19 Dec 1994.
463 * Time of day items:: 9:20pm.
464 * Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
465 * Day of week items:: Monday and others.
466 * Relative items in date strings:: next tuesday, 2 years ago.
467 * Pure numbers in date strings:: 19931219, 1440.
468 * Seconds since the Epoch:: @@1078100502.
469 * Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
470 * Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
472 Opening the software toolbox
474 * Toolbox introduction:: Toolbox introduction
475 * I/O redirection:: I/O redirection
476 * The who command:: The @command{who} command
477 * The cut command:: The @command{cut} command
478 * The sort command:: The @command{sort} command
479 * The uniq command:: The @command{uniq} command
480 * Putting the tools together:: Putting the tools together
484 * GNU Free Documentation License:: Copying and sharing this manual.
491 @chapter Introduction
493 This manual is a work in progress: many sections make no attempt to explain
494 basic concepts in a way suitable for novices. Thus, if you are interested,
495 please get involved in improving this manual. The entire @sc{gnu} community
498 @cindex @acronym{POSIX}
499 The @sc{gnu} utilities documented here are mostly compatible with the
500 @acronym{POSIX} standard.
501 @cindex bugs, reporting
502 Please report bugs to @email{bug-coreutils@@gnu.org}. Remember
503 to include the version number, machine architecture, input files, and
504 any other information needed to reproduce the bug: your input, what you
505 expected, what you got, and why it is wrong. Diffs are welcome, but
506 please include a description of the problem as well, since this is
507 sometimes difficult to infer. @xref{Bugs, , , gcc, Using and Porting GNU CC}.
513 @cindex MacKenzie, D.
516 This manual was originally derived from the Unix man pages in the
517 distributions, which were written by David MacKenzie and updated by Jim
518 Meyering. What you are reading now is the authoritative documentation
519 for these utilities; the man pages are no longer being maintained. The
520 original @command{fmt} man page was written by Ross Paterson. Fran@,{c}ois
521 Pinard did the initial conversion to Texinfo format. Karl Berry did the
522 indexing, some reorganization, and editing of the results. Brian
523 Youmans of the Free Software Foundation office staff combined the
524 manuals for textutils, fileutils, and sh-utils to produce the present
525 omnibus manual. Richard Stallman contributed his usual invaluable
526 insights to the overall process.
529 @chapter Common options
533 @itemx @w{@kbd{--backup}[=@var{method}]}
536 @vindex VERSION_CONTROL
537 @cindex backups, making
538 @xref{Backup options}.
539 Make a backup of each file that would otherwise be overwritten or removed.
542 @macro optBackupSuffix
543 @item -S @var{suffix}
544 @itemx --suffix=@var{suffix}
547 Append @var{suffix} to each backup file made with @option{-b}.
548 @xref{Backup options}.
551 @macro optTargetDirectory
552 @item -t @var{directory}
553 @itemx @w{@kbd{--target-directory}=@var{directory}}
555 @opindex --target-directory
556 @cindex target directory
557 @cindex destination directory
558 Specify the destination @var{directory}.
559 @xref{Target directory}.
562 @macro optNoTargetDirectory
564 @itemx --no-target-directory
566 @opindex --no-target-directory
567 @cindex target directory
568 @cindex destination directory
569 Do not treat the last operand specially when it is a directory or a
570 symbolic link to a directory. @xref{Target directory}.
577 Append an SI-style abbreviation to each size, such as @samp{M} for
578 megabytes. Powers of 1000 are used, not 1024; @samp{M} stands for
579 1,000,000 bytes. This option is equivalent to
580 @option{--block-size=si}. Use the @option{-h} or
581 @option{--human-readable} option if
582 you prefer powers of 1024.
585 @macro optHumanReadable
587 @itemx --human-readable
589 @opindex --human-readable
590 @cindex human-readable output
591 Append a size letter to each size, such as @samp{M} for mebibytes.
592 Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes.
593 This option is equivalent to @option{--block-size=human-readable}.
594 Use the @option{--si} option if you prefer powers of 1000.
597 @macro optStripTrailingSlashes
598 @itemx @w{@kbd{--strip-trailing-slashes}}
599 @opindex --strip-trailing-slashes
600 @cindex stripping trailing slashes
601 Remove any trailing slashes from each @var{source} argument.
602 @xref{Trailing slashes}.
605 @macro mayConflictWithShellBuiltIn{cmd}
606 @cindex conflicts with shell built-ins
607 @cindex built-in shell commands, conflicts with
608 Due to shell aliases and built-in @command{\cmd\} command, using an
609 unadorned @command{\cmd\} interactively or in a script may get you
610 different functionality than that described here. Invoke it via
611 @command{env} (i.e., @code{env \cmd\ @dots{}}) to avoid interference
615 @cindex common options
617 Certain options are available in all of these programs. Rather than
618 writing identical descriptions for each of the programs, they are
619 described here. (In fact, every @sc{gnu} program accepts (or should accept)
622 @vindex POSIXLY_CORRECT
623 Normally options and operands can appear in any order, and programs act
624 as if all the options appear before any operands. For example,
625 @samp{sort -r passwd -t :} acts like @samp{sort -r -t : passwd}, since
626 @samp{:} is an option-argument of @option{-t}. However, if the
627 @env{POSIXLY_CORRECT} environment variable is set, options must appear
628 before operands, unless otherwise specified for a particular command.
630 A few programs can usefully have trailing operands with leading
631 @samp{-}. With such a program, options must precede operands even if
632 @env{POSIXLY_CORRECT} is not set, and this fact is noted in the
633 program description. For example, the @command{env} command's options
634 must appear before its operands, since in some cases the operands
635 specify a command that itself contains options.
637 Some of these programs recognize the @option{--help} and @option{--version}
638 options only when one of them is the sole command line argument.
645 Print a usage message listing all available options, then exit successfully.
649 @cindex version number, finding
650 Print the version number, then exit successfully.
654 @cindex option delimiter
655 Delimit the option list. Later arguments, if any, are treated as
656 operands even if they begin with @samp{-}. For example, @samp{sort --
657 -r} reads from the file named @file{-r}.
661 @cindex standard input
662 @cindex standard output
663 A single @samp{-} operand is not really an option, though it looks like one. It
664 stands for standard input, or for standard output if that is clear from
665 the context. For example, @samp{sort -} reads from standard input,
666 and is equivalent to plain @samp{sort}, and @samp{tee -} writes an
667 extra copy of its input to standard output. Unless otherwise
668 specified, @samp{-} can appear as any operand that requires a file
672 * Exit status:: Indicating program success or failure.
673 * Backup options:: -b -S, in some programs.
674 * Block size:: BLOCK_SIZE and --block-size, in some programs.
675 * Signal specifications:: Specifying signals using the --signal option.
676 * Disambiguating names and IDs:: chgrp and chown owner and group syntax
677 * Random sources:: --random-source, in some programs.
678 * Target directory:: Specifying a target directory, in some programs.
679 * Trailing slashes:: --strip-trailing-slashes, in some programs.
680 * Traversing symlinks:: -H, -L, or -P, in some programs.
681 * Treating / specially:: --preserve-root and --no-preserve-root.
682 * Special built-in utilities:: @command{break}, @command{:}, @command{eval}, @dots{}
683 * Standards conformance:: Conformance to the @acronym{POSIX} standard.
691 An exit status of zero indicates success,
692 and a nonzero value indicates failure.
695 Nearly every command invocation yields an integral @dfn{exit status}
696 that can be used to change how other commands work.
697 For the vast majority of commands, an exit status of zero indicates
698 success. Failure is indicated by a nonzero value---typically
699 @samp{1}, though it may differ on unusual platforms as @acronym{POSIX}
700 requires only that it be nonzero.
702 However, some of the programs documented here do produce
703 other exit status values and a few associate different
704 meanings with the values @samp{0} and @samp{1}.
705 Here are some of the exceptions:
706 @command{chroot}, @command{env}, @command{expr},
707 @command{nice}, @command{nohup}, @command{printenv}, @command{sort},
708 @command{su}, @command{test}, @command{timeout}, @command{tty}.
712 @section Backup options
714 @cindex backup options
716 Some @sc{gnu} programs (at least @command{cp}, @command{install},
717 @command{ln}, and @command{mv}) optionally make backups of files
718 before writing new versions.
719 These options control the details of these backups. The options are also
720 briefly mentioned in the descriptions of the particular programs.
725 @itemx @w{@kbd{--backup}[=@var{method}]}
728 @vindex VERSION_CONTROL
729 @cindex backups, making
730 Make a backup of each file that would otherwise be overwritten or removed.
731 Without this option, the original versions are destroyed.
732 Use @var{method} to determine the type of backups to make.
733 When this option is used but @var{method} is not specified,
734 then the value of the @env{VERSION_CONTROL}
735 environment variable is used. And if @env{VERSION_CONTROL} is not set,
736 the default backup type is @samp{existing}.
738 Note that the short form of this option, @option{-b} does not accept any
739 argument. Using @option{-b} is equivalent to using @option{--backup=existing}.
741 @vindex version-control @r{Emacs variable}
742 This option corresponds to the Emacs variable @samp{version-control};
743 the values for @var{method} are the same as those used in Emacs.
744 This option also accepts more descriptive names.
745 The valid @var{method}s are (unique abbreviations are accepted):
750 @opindex none @r{backup method}
755 @opindex numbered @r{backup method}
756 Always make numbered backups.
760 @opindex existing @r{backup method}
761 Make numbered backups of files that already have them, simple backups
766 @opindex simple @r{backup method}
767 Always make simple backups. Please note @samp{never} is not to be
768 confused with @samp{none}.
772 @item -S @var{suffix}
773 @itemx --suffix=@var{suffix}
776 @cindex backup suffix
777 @vindex SIMPLE_BACKUP_SUFFIX
778 Append @var{suffix} to each backup file made with @option{-b}. If this
779 option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
780 environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
781 set, the default is @samp{~}, just as in Emacs.
790 Some @sc{gnu} programs (at least @command{df}, @command{du}, and
791 @command{ls}) display sizes in ``blocks''. You can adjust the block size
792 and method of display to make sizes easier to read. The block size
793 used for display is independent of any file system block size.
794 Fractional block counts are rounded up to the nearest integer.
796 @opindex --block-size=@var{size}
799 @vindex DF_BLOCK_SIZE
800 @vindex DU_BLOCK_SIZE
801 @vindex LS_BLOCK_SIZE
802 @vindex POSIXLY_CORRECT@r{, and block size}
804 The default block size is chosen by examining the following environment
805 variables in turn; the first one that is set determines the block size.
810 This specifies the default block size for the @command{df} command.
811 Similarly, @env{DU_BLOCK_SIZE} specifies the default for @command{du} and
812 @env{LS_BLOCK_SIZE} for @command{ls}.
815 This specifies the default block size for all three commands, if the
816 above command-specific environment variables are not set.
819 This specifies the default block size for all values that are normally
820 printed as blocks, if neither @env{BLOCK_SIZE} nor the above
821 command-specific environment variables are set. Unlike the other
822 environment variables, @env{BLOCKSIZE} does not affect values that are
823 normally printed as byte counts, e.g., the file sizes contained in
826 @item POSIXLY_CORRECT
827 If neither @env{@var{command}_BLOCK_SIZE}, nor @env{BLOCK_SIZE}, nor
828 @env{BLOCKSIZE} is set, but this variable is set, the block size
833 If none of the above environment variables are set, the block size
834 currently defaults to 1024 bytes in most contexts, but this number may
835 change in the future. For @command{ls} file sizes, the block size
838 @cindex human-readable output
841 A block size specification can be a positive integer specifying the number
842 of bytes per block, or it can be @code{human-readable} or @code{si} to
843 select a human-readable format. Integers may be followed by suffixes
844 that are upward compatible with the
845 @uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI prefixes}
846 for decimal multiples and with the
847 @uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2
848 prefixes for binary multiples}.
850 With human-readable formats, output sizes are followed by a size letter
851 such as @samp{M} for megabytes. @code{BLOCK_SIZE=human-readable} uses
852 powers of 1024; @samp{M} stands for 1,048,576 bytes.
853 @code{BLOCK_SIZE=si} is similar, but uses powers of 1000 and appends
854 @samp{B}; @samp{MB} stands for 1,000,000 bytes.
857 A block size specification preceded by @samp{'} causes output sizes to
858 be displayed with thousands separators. The @env{LC_NUMERIC} locale
859 specifies the thousands separator and grouping. For example, in an
860 American English locale, @samp{--block-size="'1kB"} would cause a size
861 of 1234000 bytes to be displayed as @samp{1,234}. In the default C
862 locale, there is no thousands separator so a leading @samp{'} has no
865 An integer block size can be followed by a suffix to specify a
866 multiple of that size. A bare size letter,
867 or one followed by @samp{iB}, specifies
868 a multiple using powers of 1024. A size letter followed by @samp{B}
869 specifies powers of 1000 instead. For example, @samp{1M} and
870 @samp{1MiB} are equivalent to @samp{1048576}, whereas @samp{1MB} is
871 equivalent to @samp{1000000}.
873 A plain suffix without a preceding integer acts as if @samp{1} were
874 prepended, except that it causes a size indication to be appended to
875 the output. For example, @samp{--block-size="kB"} displays 3000 as
878 The following suffixes are defined. Large sizes like @code{1Y}
879 may be rejected by your computer due to limitations of its arithmetic.
883 @cindex kilobyte, definition of
884 kilobyte: @math{10^3 = 1000}.
888 @cindex kibibyte, definition of
889 kibibyte: @math{2^{10} = 1024}. @samp{K} is special: the SI prefix is
890 @samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and
891 @acronym{POSIX} use @samp{k} to mean @samp{KiB}.
893 @cindex megabyte, definition of
894 megabyte: @math{10^6 = 1,000,000}.
897 @cindex mebibyte, definition of
898 mebibyte: @math{2^{20} = 1,048,576}.
900 @cindex gigabyte, definition of
901 gigabyte: @math{10^9 = 1,000,000,000}.
904 @cindex gibibyte, definition of
905 gibibyte: @math{2^{30} = 1,073,741,824}.
907 @cindex terabyte, definition of
908 terabyte: @math{10^{12} = 1,000,000,000,000}.
911 @cindex tebibyte, definition of
912 tebibyte: @math{2^{40} = 1,099,511,627,776}.
914 @cindex petabyte, definition of
915 petabyte: @math{10^{15} = 1,000,000,000,000,000}.
918 @cindex pebibyte, definition of
919 pebibyte: @math{2^{50} = 1,125,899,906,842,624}.
921 @cindex exabyte, definition of
922 exabyte: @math{10^{18} = 1,000,000,000,000,000,000}.
925 @cindex exbibyte, definition of
926 exbibyte: @math{2^{60} = 1,152,921,504,606,846,976}.
928 @cindex zettabyte, definition of
929 zettabyte: @math{10^{21} = 1,000,000,000,000,000,000,000}
932 @math{2^{70} = 1,180,591,620,717,411,303,424}.
933 (@samp{Zi} is a @acronym{GNU} extension to IEC 60027-2.)
935 @cindex yottabyte, definition of
936 yottabyte: @math{10^{24} = 1,000,000,000,000,000,000,000,000}.
939 @math{2^{80} = 1,208,925,819,614,629,174,706,176}.
940 (@samp{Yi} is a @acronym{GNU} extension to IEC 60027-2.)
945 @opindex --block-size
946 @opindex --human-readable
949 Block size defaults can be overridden by an explicit
950 @option{--block-size=@var{size}} option. The @option{-k}
951 option is equivalent to @option{--block-size=1K}, which
952 is the default unless the @env{POSIXLY_CORRECT} environment variable is
953 set. The @option{-h} or @option{--human-readable} option is equivalent to
954 @option{--block-size=human-readable}. The @option{--si} option is
955 equivalent to @option{--block-size=si}.
957 @node Signal specifications
958 @section Signal specifications
959 @cindex signals, specifying
961 A @var{signal} may be a signal name like @samp{HUP}, or a signal
962 number like @samp{1}, or an exit status of a process terminated by the
963 signal. A signal name can be given in canonical form or prefixed by
964 @samp{SIG}. The case of the letters is ignored. The following signal names
965 and numbers are supported on all @acronym{POSIX} compliant systems:
971 2. Terminal interrupt.
977 9. Kill (cannot be caught or ignored).
985 Other supported signal names have system-dependent corresponding
986 numbers. All systems conforming to @acronym{POSIX} 1003.1-2001 also
987 support the following signals:
991 Access to an undefined portion of a memory object.
993 Child process terminated, stopped, or continued.
995 Continue executing, if stopped.
997 Erroneous arithmetic operation.
1001 Write on a pipe with no one to read it.
1003 Invalid memory reference.
1005 Stop executing (cannot be caught or ignored).
1009 Background process attempting read.
1011 Background process attempting write.
1013 High bandwidth data is available at a socket.
1015 User-defined signal 1.
1017 User-defined signal 2.
1021 @acronym{POSIX} 1003.1-2001 systems that support the @acronym{XSI} extension
1022 also support the following signals:
1028 Profiling timer expired.
1032 Trace/breakpoint trap.
1034 Virtual timer expired.
1036 CPU time limit exceeded.
1038 File size limit exceeded.
1042 @acronym{POSIX} 1003.1-2001 systems that support the @acronym{XRT} extension
1043 also support at least eight real-time signals called @samp{RTMIN},
1044 @samp{RTMIN+1}, @dots{}, @samp{RTMAX-1}, @samp{RTMAX}.
1046 @node Disambiguating names and IDs
1047 @section chown and chgrp: Disambiguating user names and IDs
1048 @cindex user names, disambiguating
1049 @cindex user IDs, disambiguating
1050 @cindex group names, disambiguating
1051 @cindex group IDs, disambiguating
1052 @cindex disambiguating group names and IDs
1054 Since the @var{owner} and @var{group} arguments to @command{chown} and
1055 @command{chgrp} may be specified as names or numeric IDs, there is an
1057 What if a user or group @emph{name} is a string of digits?
1058 @footnote{Using a number as a user name is common in some environments.}
1059 Should the command interpret it as a user name or as an ID?
1060 @acronym{POSIX} requires that @command{chown} and @command{chgrp}
1061 first attempt to resolve the specified string as a name, and
1062 only once that fails, then try to interpret it as an ID.
1063 This is troublesome when you want to specify a numeric ID, say 42,
1064 and it must work even in a pathological situation where
1065 @samp{42} is a user name that maps to some other user ID, say 1000.
1066 Simply invoking @code{chown 42 F}, will set @file{F}s owner ID to
1067 1000---not what you intended.
1069 GNU @command{chown} and @command{chgrp} provide a way to work around this,
1070 that at the same time may result in a significant performance improvement
1071 by eliminating a database look-up.
1072 Simply precede each numeric user ID and/or group ID with a @samp{+},
1073 in order to force its interpretation as an integer:
1077 chgrp +$numeric_group_id another-file
1081 GNU @command{chown} and @command{chgrp}
1082 skip the name look-up process for each @samp{+}-prefixed string,
1083 because a string containing @samp{+} is never a valid user or group name.
1084 This syntax is accepted on most common Unix systems, but not on Solaris 10.
1086 @node Random sources
1087 @section Sources of random data
1089 @cindex random sources
1091 The @command{shuf}, @command{shred}, and @command{sort} commands
1092 sometimes need random data to do their work. For example, @samp{sort
1093 -R} must choose a hash function at random, and it needs random data to
1094 make this selection.
1096 Normally these commands use the device file @file{/dev/urandom} as the
1097 source of random data. Typically, this device gathers environmental
1098 noise from device drivers and other sources into an entropy pool, and
1099 uses the pool to generate random bits. If the pool is short of data,
1100 the device reuses the internal pool to produce more bits, using a
1101 cryptographically secure pseudorandom number generator.
1103 @file{/dev/urandom} suffices for most practical uses, but applications
1104 requiring high-value or long-term protection of private data may
1105 require an alternate data source like @file{/dev/random} or
1106 @file{/dev/arandom}. The set of available sources depends on your
1109 To use such a source, specify the @option{--random-source=@var{file}}
1110 option, e.g., @samp{shuf --random-source=/dev/random}. The contents
1111 of @var{file} should be as random as possible. An error is reported
1112 if @var{file} does not contain enough bytes to randomize the input
1115 To reproduce the results of an earlier invocation of a command, you
1116 can save some random data into a file and then use that file as the
1117 random source in earlier and later invocations of the command.
1119 Some old-fashioned or stripped-down operating systems lack support for
1120 @command{/dev/urandom}. On these systems commands like @command{shuf}
1121 by default fall back on an internal pseudorandom generator initialized
1122 by a small amount of entropy.
1124 @node Target directory
1125 @section Target directory
1127 @cindex target directory
1129 The @command{cp}, @command{install}, @command{ln}, and @command{mv}
1130 commands normally treat the last operand specially when it is a
1131 directory or a symbolic link to a directory. For example, @samp{cp
1132 source dest} is equivalent to @samp{cp source dest/source} if
1133 @file{dest} is a directory. Sometimes this behavior is not exactly
1134 what is wanted, so these commands support the following options to
1135 allow more fine-grained control:
1140 @itemx --no-target-directory
1141 @opindex --no-target-directory
1142 @cindex target directory
1143 @cindex destination directory
1144 Do not treat the last operand specially when it is a directory or a
1145 symbolic link to a directory. This can help avoid race conditions in
1146 programs that operate in a shared area. For example, when the command
1147 @samp{mv /tmp/source /tmp/dest} succeeds, there is no guarantee that
1148 @file{/tmp/source} was renamed to @file{/tmp/dest}: it could have been
1149 renamed to @file{/tmp/dest/source} instead, if some other process
1150 created @file{/tmp/dest} as a directory. However, if @file{mv
1151 -T /tmp/source /tmp/dest} succeeds, there is no
1152 question that @file{/tmp/source} was renamed to @file{/tmp/dest}.
1154 In the opposite situation, where you want the last operand to be
1155 treated as a directory and want a diagnostic otherwise, you can use
1156 the @option{--target-directory} (@option{-t}) option.
1158 @item -t @var{directory}
1159 @itemx @w{@kbd{--target-directory}=@var{directory}}
1160 @opindex --target-directory
1161 @cindex target directory
1162 @cindex destination directory
1163 Use @var{directory} as the directory component of each destination
1166 The interface for most programs is that after processing options and a
1167 finite (possibly zero) number of fixed-position arguments, the remaining
1168 argument list is either expected to be empty, or is a list of items
1169 (usually files) that will all be handled identically. The @command{xargs}
1170 program is designed to work well with this convention.
1172 The commands in the @command{mv}-family are unusual in that they take
1173 a variable number of arguments with a special case at the @emph{end}
1174 (namely, the target directory). This makes it nontrivial to perform some
1175 operations, e.g., ``move all files from here to ../d/'', because
1176 @code{mv * ../d/} might exhaust the argument space, and @code{ls | xargs ...}
1177 doesn't have a clean way to specify an extra final argument for each
1178 invocation of the subject command. (It can be done by going through a
1179 shell command, but that requires more human labor and brain power than
1182 The @w{@kbd{--target-directory}} (@option{-t}) option allows the @command{cp},
1183 @command{install}, @command{ln}, and @command{mv} programs to be used
1184 conveniently with @command{xargs}. For example, you can move the files
1185 from the current directory to a sibling directory, @code{d} like this:
1188 ls | xargs mv -t ../d --
1191 However, this doesn't move files whose names begin with @samp{.}.
1192 If you use the @sc{gnu} @command{find} program, you can move those
1193 files too, with this command:
1196 find . -mindepth 1 -maxdepth 1 \
1200 But both of the above approaches fail if there are no files in the
1201 current directory, or if any file has a name containing a blank or
1202 some other special characters.
1203 The following example removes those limitations and requires both
1204 @sc{gnu} @command{find} and @sc{gnu} @command{xargs}:
1207 find . -mindepth 1 -maxdepth 1 -print0 \
1208 | xargs --null --no-run-if-empty \
1215 The @option{--target-directory} (@option{-t}) and
1216 @option{--no-target-directory} (@option{-T})
1217 options cannot be combined.
1219 @node Trailing slashes
1220 @section Trailing slashes
1222 @cindex trailing slashes
1224 Some @sc{gnu} programs (at least @command{cp} and @command{mv}) allow you to
1225 remove any trailing slashes from each @var{source} argument before
1226 operating on it. The @w{@kbd{--strip-trailing-slashes}} option enables
1229 This is useful when a @var{source} argument may have a trailing slash and
1230 @c FIXME: mv's behavior in this case is system-dependent
1231 specify a symbolic link to a directory. This scenario is in fact rather
1232 common because some shells can automatically append a trailing slash when
1233 performing file name completion on such symbolic links. Without this
1234 option, @command{mv}, for example, (via the system's rename function) must
1235 interpret a trailing slash as a request to dereference the symbolic link
1236 and so must rename the indirectly referenced @emph{directory} and not
1237 the symbolic link. Although it may seem surprising that such behavior
1238 be the default, it is required by @acronym{POSIX} and is consistent with
1239 other parts of that standard.
1241 @node Traversing symlinks
1242 @section Traversing symlinks
1244 @cindex symbolic link to directory, controlling traversal of
1246 The following options modify how @command{chown} and @command{chgrp}
1247 @c FIXME: note that `du' has these options, too, but they have slightly
1248 @c different meaning.
1249 traverse a hierarchy when the @option{--recursive} (@option{-R})
1250 option is also specified.
1251 If more than one of the following options is specified, only the final
1253 These options specify whether processing a symbolic link to a directory
1254 entails operating on just the symbolic link or on all files in the
1255 hierarchy rooted at that directory.
1257 These options are independent of @option{--dereference} and
1258 @option{--no-dereference} (@option{-h}), which control whether to modify
1259 a symlink or its referent.
1266 @cindex symbolic link to directory, traverse each that is specified on the command line
1267 If @option{--recursive} (@option{-R}) is specified and
1268 a command line argument is a symbolic link to a directory, traverse it.
1275 @cindex symbolic link to directory, traverse each that is encountered
1276 In a recursive traversal, traverse every symbolic link to a directory
1277 that is encountered.
1284 @cindex symbolic link to directory, never traverse
1285 Do not traverse any symbolic links.
1286 This is the default if none of @option{-H}, @option{-L},
1287 or @option{-P} is specified.
1294 @node Treating / specially
1295 @section Treating @file{/} specially
1297 Certain commands can operate destructively on entire hierarchies.
1298 For example, if a user with appropriate privileges mistakenly runs
1299 @samp{rm -rf / tmp/junk}, that may remove
1300 all files on the entire system. Since there are so few
1301 legitimate uses for such a command,
1302 @sc{gnu} @command{rm} normally declines to operate on any directory
1303 that resolves to @file{/}. If you really want to try to remove all
1304 the files on your system, you can use the @option{--no-preserve-root}
1305 option, but the default behavior, specified by the
1306 @option{--preserve-option}, is safer for most purposes.
1308 The commands @command{chgrp}, @command{chmod} and @command{chown}
1309 can also operate destructively on entire hierarchies, so they too
1310 support these options. Although, unlike @command{rm}, they don't
1311 actually unlink files, these commands are arguably more dangerous
1312 when operating recursively on @file{/}, since they often work much
1313 more quickly, and hence damage more files before an alert user can
1314 interrupt them. Tradition and @acronym{POSIX} require these commands
1315 to operate recursively on @file{/}, so they default to
1316 @option{--no-preserve-root}, but using the @option{--preserve-root}
1317 option makes them safer for most purposes. For convenience you can
1318 specify @option{--preserve-root} in an alias or in a shell function.
1320 Note that the @option{--preserve-root} option also ensures
1321 that @command{chgrp} and @command{chown} do not modify @file{/}
1322 even when dereferencing a symlink pointing to @file{/}.
1324 @node Special built-in utilities
1325 @section Special built-in utilities
1327 Some programs like @command{nice} can invoke other programs; for
1328 example, the command @samp{nice cat file} invokes the program
1329 @command{cat} by executing the command @samp{cat file}. However,
1330 @dfn{special built-in utilities} like @command{exit} cannot be invoked
1331 this way. For example, the command @samp{nice exit} does not have a
1332 well-defined behavior: it may generate an error message instead of
1335 Here is a list of the special built-in utilities that are standardized
1336 by @acronym{POSIX} 1003.1-2004.
1339 @t{.@: : break continue eval exec exit export readonly
1340 return set shift times trap unset}
1343 For example, because @samp{.}, @samp{:}, and @samp{exec} are special,
1344 the commands @samp{nice . foo.sh}, @samp{nice :}, and @samp{nice exec
1345 pwd} do not work as you might expect.
1347 Many shells extend this list. For example, Bash has several extra
1348 special built-in utilities like @command{history}, and
1349 @command{suspend}, and with Bash the command @samp{nice suspend}
1350 generates an error message instead of suspending.
1352 @node Standards conformance
1353 @section Standards conformance
1355 @vindex POSIXLY_CORRECT
1356 In a few cases, the @sc{gnu} utilities' default behavior is
1357 incompatible with the @acronym{POSIX} standard. To suppress these
1358 incompatibilities, define the @env{POSIXLY_CORRECT} environment
1359 variable. Unless you are checking for @acronym{POSIX} conformance, you
1360 probably do not need to define @env{POSIXLY_CORRECT}.
1362 Newer versions of @acronym{POSIX} are occasionally incompatible with older
1363 versions. For example, older versions of @acronym{POSIX} required the
1364 command @samp{sort +1} to sort based on the second and succeeding
1365 fields in each input line, but starting with @acronym{POSIX} 1003.1-2001
1366 the same command is required to sort the file named @file{+1}, and you
1367 must instead use the command @samp{sort -k 2} to get the field-based
1370 @vindex _POSIX2_VERSION
1371 The @sc{gnu} utilities normally conform to the version of @acronym{POSIX}
1372 that is standard for your system. To cause them to conform to a
1373 different version of @acronym{POSIX}, define the @env{_POSIX2_VERSION}
1374 environment variable to a value of the form @var{yyyymm} specifying
1375 the year and month the standard was adopted. Two values are currently
1376 supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
1377 @acronym{POSIX} 1003.2-1992, and @samp{200112} stands for @acronym{POSIX}
1378 1003.1-2001. For example, if you have a newer system but are running software
1379 that assumes an older version of @acronym{POSIX} and uses @samp{sort +1}
1380 or @samp{tail +10}, you can work around any compatibility problems by setting
1381 @samp{_POSIX2_VERSION=199209} in your environment.
1383 @node Output of entire files
1384 @chapter Output of entire files
1386 @cindex output of entire files
1387 @cindex entire files, output of
1389 These commands read and write entire files, possibly transforming them
1393 * cat invocation:: Concatenate and write files.
1394 * tac invocation:: Concatenate and write files in reverse.
1395 * nl invocation:: Number lines and write files.
1396 * od invocation:: Write files in octal or other formats.
1397 * base64 invocation:: Transform data into printable data.
1400 @node cat invocation
1401 @section @command{cat}: Concatenate and write files
1404 @cindex concatenate and write files
1405 @cindex copying files
1407 @command{cat} copies each @var{file} (@samp{-} means standard input), or
1408 standard input if none are given, to standard output. Synopsis:
1411 cat [@var{option}] [@var{file}]@dots{}
1414 The program accepts the following options. Also see @ref{Common options}.
1422 Equivalent to @option{-vET}.
1425 @itemx --number-nonblank
1427 @opindex --number-nonblank
1428 Number all nonempty output lines, starting with 1.
1432 Equivalent to @option{-vE}.
1437 @opindex --show-ends
1438 Display a @samp{$} after the end of each line.
1444 Number all output lines, starting with 1.
1447 @itemx --squeeze-blank
1449 @opindex --squeeze-blank
1450 @cindex squeezing empty lines
1451 Suppress repeated adjacent empty lines; output just one empty line
1456 Equivalent to @option{-vT}.
1461 @opindex --show-tabs
1462 Display TAB characters as @samp{^I}.
1466 Ignored; for @acronym{POSIX} compatibility.
1469 @itemx --show-nonprinting
1471 @opindex --show-nonprinting
1472 Display control characters except for LFD and TAB using
1473 @samp{^} notation and precede characters that have the high bit set with
1478 On systems like MS-DOS that distinguish between text and binary files,
1479 @command{cat} normally reads and writes in binary mode. However,
1480 @command{cat} reads in text mode if one of the options
1481 @option{-bensAE} is used or if @command{cat} is reading from standard
1482 input and standard input is a terminal. Similarly, @command{cat}
1483 writes in text mode if one of the options @option{-bensAE} is used or
1484 if standard output is a terminal.
1491 # Output f's contents, then standard input, then g's contents.
1494 # Copy standard input to standard output.
1499 @node tac invocation
1500 @section @command{tac}: Concatenate and write files in reverse
1503 @cindex reversing files
1505 @command{tac} copies each @var{file} (@samp{-} means standard input), or
1506 standard input if none are given, to standard output, reversing the
1507 records (lines by default) in each separately. Synopsis:
1510 tac [@var{option}]@dots{} [@var{file}]@dots{}
1513 @dfn{Records} are separated by instances of a string (newline by
1514 default). By default, this separator string is attached to the end of
1515 the record that it follows in the file.
1517 The program accepts the following options. Also see @ref{Common options}.
1525 The separator is attached to the beginning of the record that it
1526 precedes in the file.
1532 Treat the separator string as a regular expression. Users of @command{tac}
1533 on MS-DOS/MS-Windows should note that, since @command{tac} reads files in
1534 binary mode, each line of a text file might end with a CR/LF pair
1535 instead of the Unix-style LF.
1537 @item -s @var{separator}
1538 @itemx --separator=@var{separator}
1540 @opindex --separator
1541 Use @var{separator} as the record separator, instead of newline.
1549 @section @command{nl}: Number lines and write files
1552 @cindex numbering lines
1553 @cindex line numbering
1555 @command{nl} writes each @var{file} (@samp{-} means standard input), or
1556 standard input if none are given, to standard output, with line numbers
1557 added to some or all of the lines. Synopsis:
1560 nl [@var{option}]@dots{} [@var{file}]@dots{}
1563 @cindex logical pages, numbering on
1564 @command{nl} decomposes its input into (logical) pages; by default, the
1565 line number is reset to 1 at the top of each logical page. @command{nl}
1566 treats all of the input files as a single document; it does not reset
1567 line numbers or logical pages between files.
1569 @cindex headers, numbering
1570 @cindex body, numbering
1571 @cindex footers, numbering
1572 A logical page consists of three sections: header, body, and footer.
1573 Any of the sections can be empty. Each can be numbered in a different
1574 style from the others.
1576 The beginnings of the sections of logical pages are indicated in the
1577 input file by a line containing exactly one of these delimiter strings:
1588 The two characters from which these strings are made can be changed from
1589 @samp{\} and @samp{:} via options (see below), but the pattern and
1590 length of each string cannot be changed.
1592 A section delimiter is replaced by an empty line on output. Any text
1593 that comes before the first section delimiter string in the input file
1594 is considered to be part of a body section, so @command{nl} treats a
1595 file that contains no section delimiters as a single body section.
1597 The program accepts the following options. Also see @ref{Common options}.
1601 @item -b @var{style}
1602 @itemx --body-numbering=@var{style}
1604 @opindex --body-numbering
1605 Select the numbering style for lines in the body section of each
1606 logical page. When a line is not numbered, the current line number
1607 is not incremented, but the line number separator character is still
1608 prepended to the line. The styles are:
1614 number only nonempty lines (default for body),
1616 do not number lines (default for header and footer),
1618 number only lines that contain a match for the basic regular
1619 expression @var{bre}.
1620 @xref{Regular Expressions, , Regular Expressions, grep, The GNU Grep Manual}.
1624 @itemx --section-delimiter=@var{cd}
1626 @opindex --section-delimiter
1627 @cindex section delimiters of pages
1628 Set the section delimiter characters to @var{cd}; default is
1629 @samp{\:}. If only @var{c} is given, the second remains @samp{:}.
1630 (Remember to protect @samp{\} or other metacharacters from shell
1631 expansion with quotes or extra backslashes.)
1633 @item -f @var{style}
1634 @itemx --footer-numbering=@var{style}
1636 @opindex --footer-numbering
1637 Analogous to @option{--body-numbering}.
1639 @item -h @var{style}
1640 @itemx --header-numbering=@var{style}
1642 @opindex --header-numbering
1643 Analogous to @option{--body-numbering}.
1645 @item -i @var{number}
1646 @itemx --page-increment=@var{number}
1648 @opindex --page-increment
1649 Increment line numbers by @var{number} (default 1).
1651 @item -l @var{number}
1652 @itemx --join-blank-lines=@var{number}
1654 @opindex --join-blank-lines
1655 @cindex empty lines, numbering
1656 @cindex blank lines, numbering
1657 Consider @var{number} (default 1) consecutive empty lines to be one
1658 logical line for numbering, and only number the last one. Where fewer
1659 than @var{number} consecutive empty lines occur, do not number them.
1660 An empty line is one that contains no characters, not even spaces
1663 @item -n @var{format}
1664 @itemx --number-format=@var{format}
1666 @opindex --number-format
1667 Select the line numbering format (default is @code{rn}):
1671 @opindex ln @r{format for @command{nl}}
1672 left justified, no leading zeros;
1674 @opindex rn @r{format for @command{nl}}
1675 right justified, no leading zeros;
1677 @opindex rz @r{format for @command{nl}}
1678 right justified, leading zeros.
1682 @itemx --no-renumber
1684 @opindex --no-renumber
1685 Do not reset the line number at the start of a logical page.
1687 @item -s @var{string}
1688 @itemx --number-separator=@var{string}
1690 @opindex --number-separator
1691 Separate the line number from the text line in the output with
1692 @var{string} (default is the TAB character).
1694 @item -v @var{number}
1695 @itemx --starting-line-number=@var{number}
1697 @opindex --starting-line-number
1698 Set the initial line number on each logical page to @var{number} (default 1).
1700 @item -w @var{number}
1701 @itemx --number-width=@var{number}
1703 @opindex --number-width
1704 Use @var{number} characters for line numbers (default 6).
1712 @section @command{od}: Write files in octal or other formats
1715 @cindex octal dump of files
1716 @cindex hex dump of files
1717 @cindex ASCII dump of files
1718 @cindex file contents, dumping unambiguously
1720 @command{od} writes an unambiguous representation of each @var{file}
1721 (@samp{-} means standard input), or standard input if none are given.
1725 od [@var{option}]@dots{} [@var{file}]@dots{}
1726 od [-abcdfilosx]@dots{} [@var{file}] [[+]@var{offset}[.][b]]
1727 od [@var{option}]@dots{} --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
1730 Each line of output consists of the offset in the input, followed by
1731 groups of data from the file. By default, @command{od} prints the offset in
1732 octal, and each group of file data is a C @code{short int}'s worth of input
1733 printed as a single octal number.
1735 If @var{offset} is given, it specifies how many input bytes to skip
1736 before formatting and writing. By default, it is interpreted as an
1737 octal number, but the optional trailing decimal point causes it to be
1738 interpreted as decimal. If no decimal is specified and the offset
1739 begins with @samp{0x} or @samp{0X} it is interpreted as a hexadecimal
1740 number. If there is a trailing @samp{b}, the number of bytes skipped
1741 will be @var{offset} multiplied by 512.
1743 If a command is of both the first and second forms, the second form is
1744 assumed if the last operand begins with @samp{+} or (if there are two
1745 operands) a digit. For example, in @samp{od foo 10} and @samp{od +10}
1746 the @samp{10} is an offset, whereas in @samp{od 10} the @samp{10} is a
1749 The program accepts the following options. Also see @ref{Common options}.
1753 @item -A @var{radix}
1754 @itemx --address-radix=@var{radix}
1756 @opindex --address-radix
1757 @cindex radix for file offsets
1758 @cindex file offset radix
1759 Select the base in which file offsets are printed. @var{radix} can
1760 be one of the following:
1770 none (do not print offsets).
1773 The default is octal.
1775 @item -j @var{bytes}
1776 @itemx --skip-bytes=@var{bytes}
1778 @opindex --skip-bytes
1779 Skip @var{bytes} input bytes before formatting and writing. If
1780 @var{bytes} begins with @samp{0x} or @samp{0X}, it is interpreted in
1781 hexadecimal; otherwise, if it begins with @samp{0}, in octal; otherwise,
1782 in decimal. Appending @samp{b} multiplies @var{bytes} by 512,
1783 @samp{kB} by 1000, @samp{K} by 1024,
1784 @samp{MB} by 1000*1000, @samp{M} by 1024*1024,
1785 @samp{GB} by 1000*1000*1000, @samp{G} by 1024*1024*1024,
1786 and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
1788 @item -N @var{bytes}
1789 @itemx --read-bytes=@var{bytes}
1791 @opindex --read-bytes
1792 Output at most @var{bytes} bytes of the input. Prefixes and suffixes on
1793 @code{bytes} are interpreted as for the @option{-j} option.
1795 @item -S @var{bytes}
1796 @itemx --strings[=@var{bytes}]
1799 @cindex string constants, outputting
1800 Instead of the normal output, output only @dfn{string constants}: at
1801 least @var{bytes} consecutive @acronym{ASCII} graphic characters,
1802 followed by a null (zero) byte.
1803 Prefixes and suffixes on @code{bytes} are interpreted as for the
1806 If @var{n} is omitted with @option{--strings}, the default is 3.
1809 @itemx --format=@var{type}
1812 Select the format in which to output the file data. @var{type} is a
1813 string of one or more of the below type indicator characters. If you
1814 include more than one type indicator character in a single @var{type}
1815 string, or use this option more than once, @command{od} writes one copy
1816 of each output line using each of the data types that you specified,
1817 in the order that you specified.
1819 Adding a trailing ``z'' to any type specification appends a display
1820 of the @acronym{ASCII} character representation of the printable characters
1821 to the output line generated by the type specification.
1825 named character, ignoring high-order bit
1827 @acronym{ASCII} character or backslash escape,
1840 The type @code{a} outputs things like @samp{sp} for space, @samp{nl} for
1841 newline, and @samp{nul} for a null (zero) byte. Only the least significant
1842 seven bits of each byte is used; the high-order bit is ignored.
1843 Type @code{c} outputs
1844 @samp{ }, @samp{\n}, and @code{\0}, respectively.
1847 Except for types @samp{a} and @samp{c}, you can specify the number
1848 of bytes to use in interpreting each number in the given data type
1849 by following the type indicator character with a decimal integer.
1850 Alternately, you can specify the size of one of the C compiler's
1851 built-in data types by following the type indicator character with
1852 one of the following characters. For integers (@samp{d}, @samp{o},
1853 @samp{u}, @samp{x}):
1866 For floating point (@code{f}):
1878 @itemx --output-duplicates
1880 @opindex --output-duplicates
1881 Output consecutive lines that are identical. By default, when two or
1882 more consecutive output lines would be identical, @command{od} outputs only
1883 the first line, and puts just an asterisk on the following line to
1884 indicate the elision.
1887 @itemx --width[=@var{n}]
1890 Dump @code{n} input bytes per output line. This must be a multiple of
1891 the least common multiple of the sizes associated with the specified
1894 If this option is not given at all, the default is 16. If @var{n} is
1895 omitted, the default is 32.
1899 The next several options are shorthands for format specifications.
1900 @sc{gnu} @command{od} accepts any combination of shorthands and format
1901 specification options. These options accumulate.
1907 Output as named characters. Equivalent to @samp{-t a}.
1911 Output as octal bytes. Equivalent to @samp{-t o1}.
1915 Output as @acronym{ASCII} characters or backslash escapes. Equivalent to
1920 Output as unsigned decimal two-byte units. Equivalent to @samp{-t u2}.
1924 Output as floats. Equivalent to @samp{-t fF}.
1928 Output as decimal ints. Equivalent to @samp{-t dI}.
1932 Output as decimal long ints. Equivalent to @samp{-t dL}.
1936 Output as octal two-byte units. Equivalent to @option{-t o2}.
1940 Output as decimal two-byte units. Equivalent to @option{-t d2}.
1944 Output as hexadecimal two-byte units. Equivalent to @samp{-t x2}.
1947 @opindex --traditional
1948 Recognize the non-option label argument that traditional @command{od}
1949 accepted. The following syntax:
1952 od --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
1956 can be used to specify at most one file and optional arguments
1957 specifying an offset and a pseudo-start address, @var{label}.
1958 The @var{label} argument is interpreted
1959 just like @var{offset}, but it specifies an initial pseudo-address. The
1960 pseudo-addresses are displayed in parentheses following any normal
1967 @node base64 invocation
1968 @section @command{base64}: Transform data into printable data.
1971 @cindex base64 encoding
1973 @command{base64} transforms data read from a file, or standard input,
1974 into (or from) base64 encoded form. The base64 encoded form uses
1975 printable @acronym{ASCII} characters to represent binary data.
1979 base64 [@var{option}]@dots{} [@var{file}]
1980 base64 --decode [@var{option}]@dots{} [@var{file}]
1983 The base64 encoding expands data to roughly 133% of the original.
1984 The format conforms to
1985 @uref{ftp://ftp.rfc-editor.org/in-notes/rfc4648.txt, RFC 4648}.
1987 The program accepts the following options. Also see @ref{Common options}.
1992 @itemx --wrap=@var{COLS}
1996 @cindex column to wrap data after
1997 During encoding, wrap lines after @var{COLS} characters. This must be
2000 The default is to wrap after 76 characters. Use the value 0 to
2001 disable line wrapping altogether.
2007 @cindex Decode base64 data
2008 @cindex Base64 decoding
2009 Change the mode of operation, from the default of encoding data, to
2010 decoding data. Input is expected to be base64 encoded data, and the
2011 output will be the original data.
2014 @itemx --ignore-garbage
2016 @opindex --ignore-garbage
2017 @cindex Ignore garbage in base64 stream
2018 When decoding, newlines are always accepted.
2019 During decoding, ignore unrecognized bytes,
2020 to permit distorted data to be decoded.
2027 @node Formatting file contents
2028 @chapter Formatting file contents
2030 @cindex formatting file contents
2032 These commands reformat the contents of files.
2035 * fmt invocation:: Reformat paragraph text.
2036 * pr invocation:: Paginate or columnate files for printing.
2037 * fold invocation:: Wrap input lines to fit in specified width.
2041 @node fmt invocation
2042 @section @command{fmt}: Reformat paragraph text
2045 @cindex reformatting paragraph text
2046 @cindex paragraphs, reformatting
2047 @cindex text, reformatting
2049 @command{fmt} fills and joins lines to produce output lines of (at most)
2050 a given number of characters (75 by default). Synopsis:
2053 fmt [@var{option}]@dots{} [@var{file}]@dots{}
2056 @command{fmt} reads from the specified @var{file} arguments (or standard
2057 input if none are given), and writes to standard output.
2059 By default, blank lines, spaces between words, and indentation are
2060 preserved in the output; successive input lines with different
2061 indentation are not joined; tabs are expanded on input and introduced on
2064 @cindex line-breaking
2065 @cindex sentences and line-breaking
2066 @cindex Knuth, Donald E.
2067 @cindex Plass, Michael F.
2068 @command{fmt} prefers breaking lines at the end of a sentence, and tries to
2069 avoid line breaks after the first word of a sentence or before the last
2070 word of a sentence. A @dfn{sentence break} is defined as either the end
2071 of a paragraph or a word ending in any of @samp{.?!}, followed by two
2072 spaces or end of line, ignoring any intervening parentheses or quotes.
2073 Like @TeX{}, @command{fmt} reads entire ``paragraphs'' before choosing line
2074 breaks; the algorithm is a variant of that given by Donald E. Knuth
2075 and Michael F. Plass in ``Breaking Paragraphs Into Lines'',
2076 @cite{Software---Practice & Experience} @b{11}, 11 (November 1981),
2079 The program accepts the following options. Also see @ref{Common options}.
2084 @itemx --crown-margin
2086 @opindex --crown-margin
2087 @cindex crown margin
2088 @dfn{Crown margin} mode: preserve the indentation of the first two
2089 lines within a paragraph, and align the left margin of each subsequent
2090 line with that of the second line.
2093 @itemx --tagged-paragraph
2095 @opindex --tagged-paragraph
2096 @cindex tagged paragraphs
2097 @dfn{Tagged paragraph} mode: like crown margin mode, except that if
2098 indentation of the first line of a paragraph is the same as the
2099 indentation of the second, the first line is treated as a one-line
2105 @opindex --split-only
2106 Split lines only. Do not join short lines to form longer ones. This
2107 prevents sample lines of code, and other such ``formatted'' text from
2108 being unduly combined.
2111 @itemx --uniform-spacing
2113 @opindex --uniform-spacing
2114 Uniform spacing. Reduce spacing between words to one space, and spacing
2115 between sentences to two spaces.
2118 @itemx -w @var{width}
2119 @itemx --width=@var{width}
2120 @opindex -@var{width}
2123 Fill output lines up to @var{width} characters (default 75). @command{fmt}
2124 initially tries to make lines about 7% shorter than this, to give it
2125 room to balance line lengths.
2127 @item -p @var{prefix}
2128 @itemx --prefix=@var{prefix}
2129 Only lines beginning with @var{prefix} (possibly preceded by whitespace)
2130 are subject to formatting. The prefix and any preceding whitespace are
2131 stripped for the formatting and then re-attached to each formatted output
2132 line. One use is to format certain kinds of program comments, while
2133 leaving the code unchanged.
2141 @section @command{pr}: Paginate or columnate files for printing
2144 @cindex printing, preparing files for
2145 @cindex multicolumn output, generating
2146 @cindex merging files in parallel
2148 @command{pr} writes each @var{file} (@samp{-} means standard input), or
2149 standard input if none are given, to standard output, paginating and
2150 optionally outputting in multicolumn format; optionally merges all
2151 @var{file}s, printing all in parallel, one per column. Synopsis:
2154 pr [@var{option}]@dots{} [@var{file}]@dots{}
2158 By default, a 5-line header is printed at each page: two blank lines;
2159 a line with the date, the file name, and the page count; and two more
2160 blank lines. A footer of five blank lines is also printed.
2161 The default @var{page_length} is 66
2162 lines. The default number of text lines is therefore 56.
2163 The text line of the header takes the form
2164 @samp{@var{date} @var{string} @var{page}}, with spaces inserted around
2165 @var{string} so that the line takes up the full @var{page_width}. Here,
2166 @var{date} is the date (see the @option{-D} or @option{--date-format}
2167 option for details), @var{string} is the centered header string, and
2168 @var{page} identifies the page number. The @env{LC_MESSAGES} locale
2169 category affects the spelling of @var{page}; in the default C locale, it
2170 is @samp{Page @var{number}} where @var{number} is the decimal page
2173 Form feeds in the input cause page breaks in the output. Multiple form
2174 feeds produce empty pages.
2176 Columns are of equal width, separated by an optional string (default
2177 is @samp{space}). For multicolumn output, lines will always be truncated to
2178 @var{page_width} (default 72), unless you use the @option{-J} option.
2180 column output no line truncation occurs by default. Use @option{-W} option to
2181 truncate lines in that case.
2183 The following changes were made in version 1.22i and apply to later
2184 versions of @command{pr}:
2185 @c FIXME: this whole section here sounds very awkward to me. I
2186 @c made a few small changes, but really it all needs to be redone. - Brian
2187 @c OK, I fixed another sentence or two, but some of it I just don't understand.
2192 Some small @var{letter options} (@option{-s}, @option{-w}) have been
2193 redefined for better @acronym{POSIX} compliance. The output of some further
2194 cases has been adapted to other Unix systems. These changes are not
2195 compatible with earlier versions of the program.
2198 Some @var{new capital letter} options (@option{-J}, @option{-S}, @option{-W})
2199 have been introduced to turn off unexpected interferences of small letter
2200 options. The @option{-N} option and the second argument @var{last_page}
2201 of @samp{+FIRST_PAGE} offer more flexibility. The detailed handling of
2202 form feeds set in the input files requires the @option{-T} option.
2205 Capital letter options override small letter ones.
2208 Some of the option-arguments (compare @option{-s}, @option{-e},
2209 @option{-i}, @option{-n}) cannot be specified as separate arguments from the
2210 preceding option letter (already stated in the @acronym{POSIX} specification).
2213 The program accepts the following options. Also see @ref{Common options}.
2217 @item +@var{first_page}[:@var{last_page}]
2218 @itemx --pages=@var{first_page}[:@var{last_page}]
2219 @c The two following @opindex lines evoke warnings because they contain `:'
2220 @c The `info' spec does not permit that. If we use those lines, we end
2221 @c up with truncated index entries that don't work.
2222 @c @opindex +@var{first_page}[:@var{last_page}]
2223 @c @opindex --pages=@var{first_page}[:@var{last_page}]
2224 @opindex +@var{page_range}
2225 @opindex --pages=@var{page_range}
2226 Begin printing with page @var{first_page} and stop with @var{last_page}.
2227 Missing @samp{:@var{last_page}} implies end of file. While estimating
2228 the number of skipped pages each form feed in the input file results
2229 in a new page. Page counting with and without @samp{+@var{first_page}}
2230 is identical. By default, counting starts with the first page of input
2231 file (not first page printed). Line numbering may be altered by @option{-N}
2235 @itemx --columns=@var{column}
2236 @opindex -@var{column}
2238 @cindex down columns
2239 With each single @var{file}, produce @var{column} columns of output
2240 (default is 1) and print columns down, unless @option{-a} is used. The
2241 column width is automatically decreased as @var{column} increases; unless
2242 you use the @option{-W/-w} option to increase @var{page_width} as well.
2243 This option might well cause some lines to be truncated. The number of
2244 lines in the columns on each page are balanced. The options @option{-e}
2245 and @option{-i} are on for multiple text-column output. Together with
2246 @option{-J} option column alignment and line truncation is turned off.
2247 Lines of full length are joined in a free field format and @option{-S}
2248 option may set field separators. @option{-@var{column}} may not be used
2249 with @option{-m} option.
2255 @cindex across columns
2256 With each single @var{file}, print columns across rather than down. The
2257 @option{-@var{column}} option must be given with @var{column} greater than one.
2258 If a line is too long to fit in a column, it is truncated.
2261 @itemx --show-control-chars
2263 @opindex --show-control-chars
2264 Print control characters using hat notation (e.g., @samp{^G}); print
2265 other nonprinting characters in octal backslash notation. By default,
2266 nonprinting characters are not changed.
2269 @itemx --double-space
2271 @opindex --double-space
2272 @cindex double spacing
2273 Double space the output.
2275 @item -D @var{format}
2276 @itemx --date-format=@var{format}
2277 @cindex time formats
2278 @cindex formatting times
2279 Format header dates using @var{format}, using the same conventions as
2280 for the command @samp{date +@var{format}}; @xref{date invocation}.
2281 Except for directives, which start with
2282 @samp{%}, characters in @var{format} are printed unchanged. You can use
2283 this option to specify an arbitrary string in place of the header date,
2284 e.g., @option{--date-format="Monday morning"}.
2286 @vindex POSIXLY_CORRECT
2288 The default date format is @samp{%Y-%m-%d %H:%M} (for example,
2289 @samp{2001-12-04 23:59});
2290 but if the @env{POSIXLY_CORRECT} environment variable is set
2291 and the @env{LC_TIME} locale category specifies the @acronym{POSIX}
2292 locale, the default is @samp{%b %e %H:%M %Y} (for example,
2293 @samp{Dec@ @ 4 23:59 2001}.
2296 Time stamps are listed according to the time zone rules specified by
2297 the @env{TZ} environment variable, or by the system default rules if
2298 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
2299 with @env{TZ}, libc, The GNU C Library Reference Manual}.
2301 @item -e[@var{in-tabchar}[@var{in-tabwidth}]]
2302 @itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]]
2304 @opindex --expand-tabs
2306 Expand @var{tab}s to spaces on input. Optional argument @var{in-tabchar} is
2307 the input tab character (default is the TAB character). Second optional
2308 argument @var{in-tabwidth} is the input tab character's width (default
2316 @opindex --form-feed
2317 Use a form feed instead of newlines to separate output pages. This does
2318 not alter the default page length of 66 lines.
2320 @item -h @var{HEADER}
2321 @itemx --header=@var{HEADER}
2324 Replace the file name in the header with the centered string @var{header}.
2325 When using the shell, @var{header} should be quoted and should be
2326 separated from @option{-h} by a space.
2328 @item -i[@var{out-tabchar}[@var{out-tabwidth}]]
2329 @itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]]
2331 @opindex --output-tabs
2333 Replace spaces with @var{tab}s on output. Optional argument @var{out-tabchar}
2334 is the output tab character (default is the TAB character). Second optional
2335 argument @var{out-tabwidth} is the output tab character's width (default
2341 @opindex --join-lines
2342 Merge lines of full length. Used together with the column options
2343 @option{-@var{column}}, @option{-a -@var{column}} or @option{-m}. Turns off
2344 @option{-W/-w} line truncation;
2345 no column alignment used; may be used with
2346 @option{--sep-string[=@var{string}]}. @option{-J} has been introduced
2347 (together with @option{-W} and @option{--sep-string})
2348 to disentangle the old (@acronym{POSIX}-compliant) options @option{-w} and
2349 @option{-s} along with the three column options.
2352 @item -l @var{page_length}
2353 @itemx --length=@var{page_length}
2356 Set the page length to @var{page_length} (default 66) lines, including
2357 the lines of the header [and the footer]. If @var{page_length} is less
2358 than or equal to 10, the header and footer are omitted, as if the
2359 @option{-t} option had been given.
2365 Merge and print all @var{file}s in parallel, one in each column. If a
2366 line is too long to fit in a column, it is truncated, unless the @option{-J}
2367 option is used. @option{--sep-string[=@var{string}]} may be used.
2369 some @var{file}s (form feeds set) produce empty columns, still marked
2370 by @var{string}. The result is a continuous line numbering and column
2371 marking throughout the whole merged file. Completely empty merged pages
2372 show no separators or line numbers. The default header becomes
2373 @samp{@var{date} @var{page}} with spaces inserted in the middle; this
2374 may be used with the @option{-h} or @option{--header} option to fill up
2375 the middle blank part.
2377 @item -n[@var{number-separator}[@var{digits}]]
2378 @itemx --number-lines[=@var{number-separator}[@var{digits}]]
2380 @opindex --number-lines
2381 Provide @var{digits} digit line numbering (default for @var{digits} is
2382 5). With multicolumn output the number occupies the first @var{digits}
2383 column positions of each text column or only each line of @option{-m}
2384 output. With single column output the number precedes each line just as
2385 @option{-m} does. Default counting of the line numbers starts with the
2386 first line of the input file (not the first line printed, compare the
2387 @option{--page} option and @option{-N} option).
2388 Optional argument @var{number-separator} is the character appended to
2389 the line number to separate it from the text followed. The default
2390 separator is the TAB character. In a strict sense a TAB is always
2391 printed with single column output only. The @var{TAB}-width varies
2392 with the @var{TAB}-position, e.g., with the left @var{margin} specified
2393 by @option{-o} option. With multicolumn output priority is given to
2394 @samp{equal width of output columns} (a @acronym{POSIX} specification).
2395 The @var{TAB}-width is fixed to the value of the first column and does
2396 not change with different values of left @var{margin}. That means a
2397 fixed number of spaces is always printed in the place of the
2398 @var{number-separator tab}. The tabification depends upon the output
2401 @item -N @var{line_number}
2402 @itemx --first-line-number=@var{line_number}
2404 @opindex --first-line-number
2405 Start line counting with the number @var{line_number} at first line of
2406 first page printed (in most cases not the first line of the input file).
2408 @item -o @var{margin}
2409 @itemx --indent=@var{margin}
2412 @cindex indenting lines
2414 Indent each line with a margin @var{margin} spaces wide (default is zero).
2415 The total page width is the size of the margin plus the @var{page_width}
2416 set with the @option{-W/-w} option. A limited overflow may occur with
2417 numbered single column output (compare @option{-n} option).
2420 @itemx --no-file-warnings
2422 @opindex --no-file-warnings
2423 Do not print a warning message when an argument @var{file} cannot be
2424 opened. (The exit status will still be nonzero, however.)
2426 @item -s[@var{char}]
2427 @itemx --separator[=@var{char}]
2429 @opindex --separator
2430 Separate columns by a single character @var{char}. The default for
2431 @var{char} is the TAB character without @option{-w} and @samp{no
2432 character} with @option{-w}. Without @option{-s} the default separator
2433 @samp{space} is set. @option{-s[char]} turns off line truncation of all
2434 three column options (@option{-COLUMN}|@option{-a -COLUMN}|@option{-m}) unless
2435 @option{-w} is set. This is a @acronym{POSIX}-compliant formulation.
2438 @item -S@var{string}
2439 @itemx --sep-string[=@var{string}]
2441 @opindex --sep-string
2442 Use @var{string} to separate output columns. The @option{-S} option doesn't
2443 affect the @option{-W/-w} option, unlike the @option{-s} option which does. It
2444 does not affect line truncation or column alignment.
2445 Without @option{-S}, and with @option{-J}, @command{pr} uses the default output
2447 Without @option{-S} or @option{-J}, @command{pr} uses a @samp{space}
2448 (same as @option{-S"@w{ }"}). @option{--sep-string} with no
2449 @samp{=@var{string}} is equivalent to @option{--sep-string=""}.
2452 @itemx --omit-header
2454 @opindex --omit-header
2455 Do not print the usual header [and footer] on each page, and do not fill
2456 out the bottom of pages (with blank lines or a form feed). No page
2457 structure is produced, but form feeds set in the input files are retained.
2458 The predefined pagination is not changed. @option{-t} or @option{-T} may be
2459 useful together with other options; e.g.: @option{-t -e4}, expand TAB characters
2460 in the input file to 4 spaces but don't make any other changes. Use of
2461 @option{-t} overrides @option{-h}.
2464 @itemx --omit-pagination
2466 @opindex --omit-pagination
2467 Do not print header [and footer]. In addition eliminate all form feeds
2468 set in the input files.
2471 @itemx --show-nonprinting
2473 @opindex --show-nonprinting
2474 Print nonprinting characters in octal backslash notation.
2476 @item -w @var{page_width}
2477 @itemx --width=@var{page_width}
2480 Set page width to @var{page_width} characters for multiple text-column
2481 output only (default for @var{page_width} is 72). @option{-s[CHAR]} turns
2482 off the default page width and any line truncation and column alignment.
2483 Lines of full length are merged, regardless of the column options
2484 set. No @var{page_width} setting is possible with single column output.
2485 A @acronym{POSIX}-compliant formulation.
2487 @item -W @var{page_width}
2488 @itemx --page_width=@var{page_width}
2490 @opindex --page_width
2491 Set the page width to @var{page_width} characters. That's valid with and
2492 without a column option. Text lines are truncated, unless @option{-J}
2493 is used. Together with one of the three column options
2494 (@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}) column
2495 alignment is always used. The separator options @option{-S} or @option{-s}
2496 don't affect the @option{-W} option. Default is 72 characters. Without
2497 @option{-W @var{page_width}} and without any of the column options NO line
2498 truncation is used (defined to keep downward compatibility and to meet
2499 most frequent tasks). That's equivalent to @option{-W 72 -J}. The header
2500 line is never truncated.
2507 @node fold invocation
2508 @section @command{fold}: Wrap input lines to fit in specified width
2511 @cindex wrapping long input lines
2512 @cindex folding long input lines
2514 @command{fold} writes each @var{file} (@option{-} means standard input), or
2515 standard input if none are given, to standard output, breaking long
2519 fold [@var{option}]@dots{} [@var{file}]@dots{}
2522 By default, @command{fold} breaks lines wider than 80 columns. The output
2523 is split into as many lines as necessary.
2525 @cindex screen columns
2526 @command{fold} counts screen columns by default; thus, a tab may count more
2527 than one column, backspace decreases the column count, and carriage
2528 return sets the column to zero.
2530 The program accepts the following options. Also see @ref{Common options}.
2538 Count bytes rather than columns, so that tabs, backspaces, and carriage
2539 returns are each counted as taking up one column, just like other
2546 Break at word boundaries: the line is broken after the last blank before
2547 the maximum line length. If the line contains no such blanks, the line
2548 is broken at the maximum line length as usual.
2550 @item -w @var{width}
2551 @itemx --width=@var{width}
2554 Use a maximum line length of @var{width} columns instead of 80.
2556 For compatibility @command{fold} supports an obsolete option syntax
2557 @option{-@var{width}}. New scripts should use @option{-w @var{width}}
2565 @node Output of parts of files
2566 @chapter Output of parts of files
2568 @cindex output of parts of files
2569 @cindex parts of files, output of
2571 These commands output pieces of the input.
2574 * head invocation:: Output the first part of files.
2575 * tail invocation:: Output the last part of files.
2576 * split invocation:: Split a file into fixed-size pieces.
2577 * csplit invocation:: Split a file into context-determined pieces.
2580 @node head invocation
2581 @section @command{head}: Output the first part of files
2584 @cindex initial part of files, outputting
2585 @cindex first part of files, outputting
2587 @command{head} prints the first part (10 lines by default) of each
2588 @var{file}; it reads from standard input if no files are given or
2589 when given a @var{file} of @option{-}. Synopsis:
2592 head [@var{option}]@dots{} [@var{file}]@dots{}
2595 If more than one @var{file} is specified, @command{head} prints a
2596 one-line header consisting of:
2599 ==> @var{file name} <==
2603 before the output for each @var{file}.
2605 The program accepts the following options. Also see @ref{Common options}.
2610 @itemx --bytes=@var{n}
2613 Print the first @var{n} bytes, instead of initial lines.
2614 However, if @var{n} starts with a @samp{-},
2615 print all but the last @var{n} bytes of each file.
2616 Appending @samp{b} multiplies @var{n} by 512,
2617 @samp{kB} by 1000, @samp{K} by 1024,
2618 @samp{MB} by 1000*1000, @samp{M} by 1024*1024,
2619 @samp{GB} by 1000*1000*1000, @samp{G} by 1024*1024*1024,
2620 and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
2623 @itemx --lines=@var{n}
2626 Output the first @var{n} lines.
2627 However, if @var{n} starts with a @samp{-},
2628 print all but the last @var{n} lines of each file.
2629 Size multiplier suffixes are the same as with the @option{-c} option.
2637 Never print file name headers.
2643 Always print file name headers.
2647 For compatibility @command{head} also supports an obsolete option syntax
2648 @option{-@var{count}@var{options}}, which is recognized only if it is
2649 specified first. @var{count} is a decimal number optionally followed
2650 by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @option{-c}, or
2651 @samp{l} to mean count by lines, or other option letters (@samp{cqv}).
2652 Scripts intended for standard hosts should use @option{-c @var{count}}
2653 or @option{-n @var{count}} instead. If your script must also run on
2654 hosts that support only the obsolete syntax, it is usually simpler to
2655 avoid @command{head}, e.g., by using @samp{sed 5q} instead of
2661 @node tail invocation
2662 @section @command{tail}: Output the last part of files
2665 @cindex last part of files, outputting
2667 @command{tail} prints the last part (10 lines by default) of each
2668 @var{file}; it reads from standard input if no files are given or
2669 when given a @var{file} of @samp{-}. Synopsis:
2672 tail [@var{option}]@dots{} [@var{file}]@dots{}
2675 If more than one @var{file} is specified, @command{tail} prints a
2676 one-line header consisting of:
2679 ==> @var{file name} <==
2683 before the output for each @var{file}.
2685 @cindex BSD @command{tail}
2686 @sc{gnu} @command{tail} can output any amount of data (some other versions of
2687 @command{tail} cannot). It also has no @option{-r} option (print in
2688 reverse), since reversing a file is really a different job from printing
2689 the end of a file; BSD @command{tail} (which is the one with @option{-r}) can
2690 only reverse files that are at most as large as its buffer, which is
2691 typically 32 KiB@. A more reliable and versatile way to reverse files is
2692 the @sc{gnu} @command{tac} command.
2694 The program accepts the following options. Also see @ref{Common options}.
2698 @item -c @var{bytes}
2699 @itemx --bytes=@var{bytes}
2702 Output the last @var{bytes} bytes, instead of final lines.
2703 However, if @var{n} starts with a @samp{+}, start printing with the
2704 @var{n}th byte from the start of each file, instead of from the end.
2705 Appending @samp{b} multiplies @var{bytes} by 512,
2706 @samp{kB} by 1000, @samp{K} by 1024,
2707 @samp{MB} by 1000*1000, @samp{M} by 1024*1024,
2708 @samp{GB} by 1000*1000*1000, @samp{G} by 1024*1024*1024,
2709 and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
2712 @itemx --follow[=@var{how}]
2715 @cindex growing files
2716 @vindex name @r{follow option}
2717 @vindex descriptor @r{follow option}
2718 Loop forever trying to read more characters at the end of the file,
2719 presumably because the file is growing.
2720 If more than one file is given, @command{tail} prints a header whenever it
2721 gets output from a different file, to indicate which file that output is
2724 There are two ways to specify how you'd like to track files with this option,
2725 but that difference is noticeable only when a followed file is removed or
2727 If you'd like to continue to track the end of a growing file even after
2728 it has been unlinked, use @option{--follow=descriptor}. This is the default
2729 behavior, but it is not useful if you're tracking a log file that may be
2730 rotated (removed or renamed, then reopened). In that case, use
2731 @option{--follow=name} to track the named file by reopening it periodically
2732 to see if it has been removed and recreated by some other program.
2734 No matter which method you use, if the tracked file is determined to have
2735 shrunk, @command{tail} prints a message saying the file has been truncated
2736 and resumes tracking the end of the file from the newly-determined endpoint.
2738 When a file is removed, @command{tail}'s behavior depends on whether it is
2739 following the name or the descriptor. When following by name, tail can
2740 detect that a file has been removed and gives a message to that effect,
2741 and if @option{--retry} has been specified it will continue checking
2742 periodically to see if the file reappears.
2743 When following a descriptor, tail does not detect that the file has
2744 been unlinked or renamed and issues no message; even though the file
2745 may no longer be accessible via its original name, it may still be
2748 The option values @samp{descriptor} and @samp{name} may be specified only
2749 with the long form of the option, not with @option{-f}.
2751 @vindex POSIXLY_CORRECT
2752 If @env{POSIXLY_CORRECT} is set, the @option{-f} option is ignored if
2753 no @var{file} operand is specified and standard input is a FIFO or a pipe.
2757 This option is the same as @option{--follow=name --retry}. That is, tail
2758 will attempt to reopen a file when it is removed. Should this fail, tail
2759 will keep trying until it becomes accessible again.
2763 This option is useful mainly when following by name (i.e., with
2764 @option{--follow=name}).
2765 Without this option, when tail encounters a file that doesn't
2766 exist or is otherwise inaccessible, it reports that fact and
2767 never checks it again.
2769 @itemx --sleep-interval=@var{number}
2770 @opindex --sleep-interval
2771 Change the number of seconds to wait between iterations (the default is 1.0).
2772 During one iteration, every specified file is checked to see if it has
2774 Historical implementations of @command{tail} have required that
2775 @var{number} be an integer. However, GNU @command{tail} accepts
2776 an arbitrary floating point number (using a period before any
2779 @itemx --pid=@var{pid}
2781 When following by name or by descriptor, you may specify the process ID,
2782 @var{pid}, of the sole writer of all @var{file} arguments. Then, shortly
2783 after that process terminates, tail will also terminate. This will
2784 work properly only if the writer and the tailing process are running on
2785 the same machine. For example, to save the output of a build in a file
2786 and to watch the file grow, if you invoke @command{make} and @command{tail}
2787 like this then the tail process will stop when your build completes.
2788 Without this option, you would have had to kill the @code{tail -f}
2792 $ make >& makerr & tail --pid=$! -f makerr
2795 If you specify a @var{pid} that is not in use or that does not correspond
2796 to the process that is writing to the tailed files, then @command{tail}
2797 may terminate long before any @var{file}s stop growing or it may not
2798 terminate until long after the real writer has terminated.
2799 Note that @option{--pid} cannot be supported on some systems; @command{tail}
2800 will print a warning if this is the case.
2802 @itemx --max-unchanged-stats=@var{n}
2803 @opindex --max-unchanged-stats
2804 When tailing a file by name, if there have been @var{n} (default
2805 n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive
2806 iterations for which the file has not changed, then
2807 @code{open}/@code{fstat} the file to determine if that file name is
2808 still associated with the same device/inode-number pair as before.
2809 When following a log file that is rotated, this is approximately the
2810 number of seconds between when tail prints the last pre-rotation lines
2811 and when it prints the lines that have accumulated in the new log file.
2812 This option is meaningful only when following by name.
2815 @itemx --lines=@var{n}
2818 Output the last @var{n} lines.
2819 However, if @var{n} starts with a @samp{+}, start printing with the
2820 @var{n}th line from the start of each file, instead of from the end.
2821 Size multiplier suffixes are the same as with the @option{-c} option.
2829 Never print file name headers.
2835 Always print file name headers.
2839 For compatibility @command{tail} also supports an obsolete usage
2840 @samp{tail -[@var{count}][bcl][f] [@var{file}]}, which is recognized
2841 only if it does not conflict with the usage described
2842 above. This obsolete form uses exactly one option and at most one
2843 file. In the option, @var{count} is an optional decimal number optionally
2844 followed by a size letter (@samp{b}, @samp{c}, @samp{l}) to mean count
2845 by 512-byte blocks, bytes, or lines, optionally followed by @samp{f}
2846 which has the same meaning as @option{-f}.
2848 @vindex _POSIX2_VERSION
2849 On older systems, the leading @samp{-} can be replaced by @samp{+} in
2850 the obsolete option syntax with the same meaning as in counts, and
2851 obsolete usage overrides normal usage when the two conflict.
2852 This obsolete behavior can be enabled or disabled with the
2853 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
2856 Scripts intended for use on standard hosts should avoid obsolete
2857 syntax and should use @option{-c @var{count}[b]}, @option{-n
2858 @var{count}}, and/or @option{-f} instead. If your script must also
2859 run on hosts that support only the obsolete syntax, you can often
2860 rewrite it to avoid problematic usages, e.g., by using @samp{sed -n
2861 '$p'} rather than @samp{tail -1}. If that's not possible, the script
2862 can use a test like @samp{if tail -c +1 </dev/null >/dev/null 2>&1;
2863 then @dots{}} to decide which syntax to use.
2865 Even if your script assumes the standard behavior, you should still
2866 beware usages whose behaviors differ depending on the @acronym{POSIX}
2867 version. For example, avoid @samp{tail - main.c}, since it might be
2868 interpreted as either @samp{tail main.c} or as @samp{tail -- -
2869 main.c}; avoid @samp{tail -c 4}, since it might mean either @samp{tail
2870 -c4} or @samp{tail -c 10 4}; and avoid @samp{tail +4}, since it might
2871 mean either @samp{tail ./+4} or @samp{tail -n +4}.
2876 @node split invocation
2877 @section @command{split}: Split a file into fixed-size pieces
2880 @cindex splitting a file into pieces
2881 @cindex pieces, splitting a file into
2883 @command{split} creates output files containing consecutive sections of
2884 @var{input} (standard input if none is given or @var{input} is
2885 @samp{-}). Synopsis:
2888 split [@var{option}] [@var{input} [@var{prefix}]]
2891 By default, @command{split} puts 1000 lines of @var{input} (or whatever is
2892 left over for the last section), into each output file.
2894 @cindex output file name prefix
2895 The output files' names consist of @var{prefix} (@samp{x} by default)
2896 followed by a group of characters (@samp{aa}, @samp{ab}, @dots{} by
2897 default), such that concatenating the output files in traditional
2898 sorted order by file name produces
2899 the original input file. If the output file names are exhausted,
2900 @command{split} reports an error without deleting the output files
2903 The program accepts the following options. Also see @ref{Common options}.
2907 @item -l @var{lines}
2908 @itemx --lines=@var{lines}
2911 Put @var{lines} lines of @var{input} into each output file.
2913 For compatibility @command{split} also supports an obsolete
2914 option syntax @option{-@var{lines}}. New scripts should use @option{-l
2915 @var{lines}} instead.
2918 @itemx --bytes=@var{size}
2921 Put @var{size} bytes of @var{input} into each output file.
2922 @var{size} is a number which may be followed by one of these
2923 multiplicative suffixes:
2925 @samp{b} => 512 ("blocks")
2926 @samp{KB} => 1000 (KiloBytes)
2927 @samp{K} => 1024 (KibiBytes)
2928 @samp{MB} => 1000*1000 (MegaBytes)
2929 @samp{M} => 1024*1024 (MebiBytes)
2931 and so on for @samp{G}, @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
2934 @itemx --line-bytes=@var{size}
2936 @opindex --line-bytes
2937 Put into each output file as many complete lines of @var{input} as
2938 possible without exceeding @var{size} bytes. Individual lines longer than
2939 @var{size} bytes are broken into multiple files.
2940 @var{size} has the same format as for the @option{--bytes} option.
2942 @item -a @var{length}
2943 @itemx --suffix-length=@var{length}
2945 @opindex --suffix-length
2946 Use suffixes of length @var{length}. The default @var{length} is 2.
2949 @itemx --numeric-suffixes
2951 @opindex --numeric-suffixes
2952 Use digits in suffixes rather than lower-case letters.
2956 Write a diagnostic just before each output file is opened.
2963 @node csplit invocation
2964 @section @command{csplit}: Split a file into context-determined pieces
2967 @cindex context splitting
2968 @cindex splitting a file into pieces by context
2970 @command{csplit} creates zero or more output files containing sections of
2971 @var{input} (standard input if @var{input} is @samp{-}). Synopsis:
2974 csplit [@var{option}]@dots{} @var{input} @var{pattern}@dots{}
2977 The contents of the output files are determined by the @var{pattern}
2978 arguments, as detailed below. An error occurs if a @var{pattern}
2979 argument refers to a nonexistent line of the input file (e.g., if no
2980 remaining line matches a given regular expression). After every
2981 @var{pattern} has been matched, any remaining input is copied into one
2984 By default, @command{csplit} prints the number of bytes written to each
2985 output file after it has been created.
2987 The types of pattern arguments are:
2992 Create an output file containing the input up to but not including line
2993 @var{n} (a positive integer). If followed by a repeat count, also
2994 create an output file containing the next @var{n} lines of the input
2995 file once for each repeat.
2997 @item /@var{regexp}/[@var{offset}]
2998 Create an output file containing the current line up to (but not
2999 including) the next line of the input file that contains a match for
3000 @var{regexp}. The optional @var{offset} is an integer.
3001 If it is given, the input up to (but not including) the
3002 matching line plus or minus @var{offset} is put into the output file,
3003 and the line after that begins the next section of input.
3005 @item %@var{regexp}%[@var{offset}]
3006 Like the previous type, except that it does not create an output
3007 file, so that section of the input file is effectively ignored.
3009 @item @{@var{repeat-count}@}
3010 Repeat the previous pattern @var{repeat-count} additional
3011 times. The @var{repeat-count} can either be a positive integer or an
3012 asterisk, meaning repeat as many times as necessary until the input is
3017 The output files' names consist of a prefix (@samp{xx} by default)
3018 followed by a suffix. By default, the suffix is an ascending sequence
3019 of two-digit decimal numbers from @samp{00} to @samp{99}. In any case,
3020 concatenating the output files in sorted order by file name produces the
3021 original input file.
3023 By default, if @command{csplit} encounters an error or receives a hangup,
3024 interrupt, quit, or terminate signal, it removes any output files
3025 that it has created so far before it exits.
3027 The program accepts the following options. Also see @ref{Common options}.
3031 @item -f @var{prefix}
3032 @itemx --prefix=@var{prefix}
3035 @cindex output file name prefix
3036 Use @var{prefix} as the output file name prefix.
3038 @item -b @var{suffix}
3039 @itemx --suffix=@var{suffix}
3042 @cindex output file name suffix
3043 Use @var{suffix} as the output file name suffix. When this option is
3044 specified, the suffix string must include exactly one
3045 @code{printf(3)}-style conversion specification, possibly including
3046 format specification flags, a field width, a precision specifications,
3047 or all of these kinds of modifiers. The format letter must convert a
3048 binary integer argument to readable form; thus, only @samp{d}, @samp{i},
3049 @samp{u}, @samp{o}, @samp{x}, and @samp{X} conversions are allowed. The
3050 entire @var{suffix} is given (with the current output file number) to
3051 @code{sprintf(3)} to form the file name suffixes for each of the
3052 individual output files in turn. If this option is used, the
3053 @option{--digits} option is ignored.
3055 @item -n @var{digits}
3056 @itemx --digits=@var{digits}
3059 Use output file names containing numbers that are @var{digits} digits
3060 long instead of the default 2.
3065 @opindex --keep-files
3066 Do not remove output files when errors are encountered.
3069 @itemx --elide-empty-files
3071 @opindex --elide-empty-files
3072 Suppress the generation of zero-length output files. (In cases where
3073 the section delimiters of the input file are supposed to mark the first
3074 lines of each of the sections, the first output file will generally be a
3075 zero-length file unless you use this option.) The output file sequence
3076 numbers always run consecutively starting from 0, even when this option
3087 Do not print counts of output file sizes.
3093 Here is an example of its usage.
3094 First, create an empty directory for the exercise,
3101 Now, split the sequence of 1..14 on lines that end with 0 or 5:
3104 $ seq 14 | csplit - '/[05]$/' '@{*@}'
3110 Each number printed above is the size of an output
3111 file that csplit has just created.
3112 List the names of those output files:
3119 Use @command{head} to show their contents:
3144 @node Summarizing files
3145 @chapter Summarizing files
3147 @cindex summarizing files
3149 These commands generate just a few numbers representing entire
3153 * wc invocation:: Print newline, word, and byte counts.
3154 * sum invocation:: Print checksum and block counts.
3155 * cksum invocation:: Print CRC checksum and byte counts.
3156 * md5sum invocation:: Print or check MD5 digests.
3157 * sha1sum invocation:: Print or check SHA-1 digests.
3158 * sha2 utilities:: Print or check SHA-2 digests.
3163 @section @command{wc}: Print newline, word, and byte counts
3167 @cindex character count
3171 @command{wc} counts the number of bytes, characters, whitespace-separated
3172 words, and newlines in each given @var{file}, or standard input if none
3173 are given or for a @var{file} of @samp{-}. Synopsis:
3176 wc [@var{option}]@dots{} [@var{file}]@dots{}
3179 @cindex total counts
3180 @command{wc} prints one line of counts for each file, and if the file was
3181 given as an argument, it prints the file name following the counts. If
3182 more than one @var{file} is given, @command{wc} prints a final line
3183 containing the cumulative counts, with the file name @file{total}. The
3184 counts are printed in this order: newlines, words, characters, bytes,
3185 maximum line length.
3186 Each count is printed right-justified in a field with at least one
3187 space between fields so that the numbers and file names normally line
3188 up nicely in columns. The width of the count fields varies depending
3189 on the inputs, so you should not depend on a particular field width.
3190 However, as a @acronym{GNU} extension, if only one count is printed,
3191 it is guaranteed to be printed without leading spaces.
3193 By default, @command{wc} prints three counts: the newline, words, and byte
3194 counts. Options can specify that only certain counts be printed.
3195 Options do not undo others previously given, so
3202 prints both the byte counts and the word counts.
3204 With the @option{--max-line-length} option, @command{wc} prints the length
3205 of the longest line per file, and if there is more than one file it
3206 prints the maximum (not the sum) of those lengths. The line lengths here
3207 are measured in screen columns, according to the current locale and
3208 assuming tab positions in every 8th column.
3210 The program accepts the following options. Also see @ref{Common options}.
3218 Print only the byte counts.
3224 Print only the character counts.
3230 Print only the word counts.
3236 Print only the newline counts.
3239 @itemx --max-line-length
3241 @opindex --max-line-length
3242 Print only the maximum line lengths.
3244 @macro filesZeroFromOption{cmd,withTotalOption,subListOutput}
3245 @itemx --files0-from=@var{FILE}
3246 @opindex --files0-from=@var{FILE}
3247 @c This is commented out to avoid a texi2dvi failure.
3248 @c texi2dvi (GNU Texinfo 4.11) 1.104
3249 @c @cindex including files from @command{\cmd\}
3250 Rather than processing files named on the command line, process those
3251 named in file @var{FILE}; each name is terminated by a null byte.
3252 This is useful \withTotalOption\
3253 when the list of file names is so long that it may exceed a command line
3255 In such cases, running @command{\cmd\} via @command{xargs} is undesirable
3256 because it splits the list into pieces and makes @command{\cmd\} print
3257 \subListOutput\ for each sublist rather than for the entire list.
3258 One way to produce a list of null-byte-terminated file names is with @sc{gnu}
3259 @command{find}, using its @option{-print0} predicate.
3260 Do not specify any @var{FILE} on the command line when using this option.
3262 @filesZeroFromOption{wc,,a total}
3264 For example, to find the length of the longest line in any @file{.c} or
3265 @file{.h} file in the current hierarchy, do this:
3268 find . -name '*.[ch]' -print0 |
3269 wc -L --files0-from=- | tail -n1
3277 @node sum invocation
3278 @section @command{sum}: Print checksum and block counts
3281 @cindex 16-bit checksum
3282 @cindex checksum, 16-bit
3284 @command{sum} computes a 16-bit checksum for each given @var{file}, or
3285 standard input if none are given or for a @var{file} of @samp{-}. Synopsis:
3288 sum [@var{option}]@dots{} [@var{file}]@dots{}
3291 @command{sum} prints the checksum for each @var{file} followed by the
3292 number of blocks in the file (rounded up). If more than one @var{file}
3293 is given, file names are also printed (by default). (With the
3294 @option{--sysv} option, corresponding file names are printed when there is
3295 at least one file argument.)
3297 By default, @sc{gnu} @command{sum} computes checksums using an algorithm
3298 compatible with BSD @command{sum} and prints file sizes in units of
3301 The program accepts the following options. Also see @ref{Common options}.
3307 @cindex BSD @command{sum}
3308 Use the default (BSD compatible) algorithm. This option is included for
3309 compatibility with the System V @command{sum}. Unless @option{-s} was also
3310 given, it has no effect.
3316 @cindex System V @command{sum}
3317 Compute checksums using an algorithm compatible with System V
3318 @command{sum}'s default, and print file sizes in units of 512-byte blocks.
3322 @command{sum} is provided for compatibility; the @command{cksum} program (see
3323 next section) is preferable in new applications.
3328 @node cksum invocation
3329 @section @command{cksum}: Print CRC checksum and byte counts
3332 @cindex cyclic redundancy check
3333 @cindex CRC checksum
3335 @command{cksum} computes a cyclic redundancy check (CRC) checksum for each
3336 given @var{file}, or standard input if none are given or for a
3337 @var{file} of @samp{-}. Synopsis:
3340 cksum [@var{option}]@dots{} [@var{file}]@dots{}
3343 @command{cksum} prints the CRC checksum for each file along with the number
3344 of bytes in the file, and the file name unless no arguments were given.
3346 @command{cksum} is typically used to ensure that files
3347 transferred by unreliable means (e.g., netnews) have not been corrupted,
3348 by comparing the @command{cksum} output for the received files with the
3349 @command{cksum} output for the original files (typically given in the
3352 The CRC algorithm is specified by the @acronym{POSIX} standard. It is not
3353 compatible with the BSD or System V @command{sum} algorithms (see the
3354 previous section); it is more robust.
3356 The only options are @option{--help} and @option{--version}. @xref{Common
3362 @node md5sum invocation
3363 @section @command{md5sum}: Print or check MD5 digests
3367 @cindex 128-bit checksum
3368 @cindex checksum, 128-bit
3369 @cindex fingerprint, 128-bit
3370 @cindex message-digest, 128-bit
3372 @command{md5sum} computes a 128-bit checksum (or @dfn{fingerprint} or
3373 @dfn{message-digest}) for each specified @var{file}.
3375 Note: The MD5 digest is more reliable than a simple CRC (provided by
3376 the @command{cksum} command) for detecting accidental file corruption,
3377 as the chances of accidentally having two files with identical MD5
3378 are vanishingly small. However, it should not be considered truly
3379 secure against malicious tampering: although finding a file with a
3380 given MD5 fingerprint, or modifying a file so as to retain its MD5 are
3381 considered infeasible at the moment, it is known how to produce
3382 different files with identical MD5 (a ``collision''), something which
3383 can be a security issue in certain contexts. For more secure hashes,
3384 consider using SHA-1 or SHA-2. @xref{sha1sum invocation}, and
3385 @ref{sha2 utilities}.
3387 If a @var{file} is specified as @samp{-} or if no files are given
3388 @command{md5sum} computes the checksum for the standard input.
3389 @command{md5sum} can also determine whether a file and checksum are
3390 consistent. Synopsis:
3393 md5sum [@var{option}]@dots{} [@var{file}]@dots{}
3396 For each @var{file}, @samp{md5sum} outputs the MD5 checksum, a flag
3397 indicating a binary or text input file, and the file name.
3398 If @var{file} contains a backslash or newline, the
3399 line is started with a backslash, and each problematic character in
3400 the file name is escaped with a backslash, making the output
3401 unambiguous even in the presence of arbitrary file names.
3402 If @var{file} is omitted or specified as @samp{-}, standard input is read.
3404 The program accepts the following options. Also see @ref{Common options}.
3412 @cindex binary input files
3413 Treat each input file as binary, by reading it in binary mode and
3414 outputting a @samp{*} flag. This is the inverse of @option{--text}.
3415 On systems like @acronym{GNU} that do not distinguish between binary
3416 and text files, this option merely flags each input file as binary:
3417 the MD5 checksum is unaffected. This option is the default on systems
3418 like MS-DOS that distinguish between binary and text files, except
3419 for reading standard input when standard input is a terminal.
3423 Read file names and checksum information (not data) from each
3424 @var{file} (or from stdin if no @var{file} was specified) and report
3425 whether the checksums match the contents of the named files.
3426 The input to this mode of @command{md5sum} is usually the output of
3427 a prior, checksum-generating run of @samp{md5sum}.
3428 Each valid line of input consists of an MD5 checksum, a binary/text
3429 flag, and then a file name.
3430 Binary files are marked with @samp{*}, text with @samp{ }.
3431 For each such line, @command{md5sum} reads the named file and computes its
3432 MD5 checksum. Then, if the computed message digest does not match the
3433 one on the line with the file name, the file is noted as having
3434 failed the test. Otherwise, the file passes the test.
3435 By default, for each valid line, one line is written to standard
3436 output indicating whether the named file passed the test.
3437 After all checks have been performed, if there were any failures,
3438 a warning is issued to standard error.
3439 Use the @option{--status} option to inhibit that output.
3440 If any listed file cannot be opened or read, if any valid line has
3441 an MD5 checksum inconsistent with the associated file, or if no valid
3442 line is found, @command{md5sum} exits with nonzero status. Otherwise,
3443 it exits successfully.
3447 @cindex verifying MD5 checksums
3448 This option is useful only when verifying checksums.
3449 When verifying checksums, don't generate an 'OK' message per successfully
3450 checked file. Files that fail the verification are reported in the
3451 default one-line-per-file format. If there is any checksum mismatch,
3452 print a warning summarizing the failures to standard error.
3456 @cindex verifying MD5 checksums
3457 This option is useful only when verifying checksums.
3458 When verifying checksums, don't generate the default one-line-per-file
3459 diagnostic and don't output the warning summarizing any failures.
3460 Failures to open or read a file still evoke individual diagnostics to
3462 If all listed files are readable and are consistent with the associated
3463 MD5 checksums, exit successfully. Otherwise exit with a status code
3464 indicating there was a failure.
3470 @cindex text input files
3471 Treat each input file as text, by reading it in text mode and
3472 outputting a @samp{ } flag. This is the inverse of @option{--binary}.
3473 This option is the default on systems like @acronym{GNU} that do not
3474 distinguish between binary and text files. On other systems, it is
3475 the default for reading standard input when standard input is a
3482 @cindex verifying MD5 checksums
3483 When verifying checksums, warn about improperly formatted MD5 checksum lines.
3484 This option is useful only if all but a few lines in the checked input
3492 @node sha1sum invocation
3493 @section @command{sha1sum}: Print or check SHA-1 digests
3497 @cindex 160-bit checksum
3498 @cindex checksum, 160-bit
3499 @cindex fingerprint, 160-bit
3500 @cindex message-digest, 160-bit
3502 @command{sha1sum} computes a 160-bit checksum for each specified
3503 @var{file}. The usage and options of this command are precisely the
3504 same as for @command{md5sum}. @xref{md5sum invocation}.
3506 Note: The SHA-1 digest is more secure than MD5, and no collisions of
3507 it are known (different files having the same fingerprint). However,
3508 it is known that they can be produced with considerable, but not
3509 unreasonable, resources. For this reason, it is generally considered
3510 that SHA-1 should be gradually phased out in favor of the more secure
3511 SHA-2 hash algorithms. @xref{sha2 utilities}.
3514 @node sha2 utilities
3515 @section sha2 utilities: Print or check SHA-2 digests
3522 @cindex 224-bit checksum
3523 @cindex 256-bit checksum
3524 @cindex 384-bit checksum
3525 @cindex 512-bit checksum
3526 @cindex checksum, 224-bit
3527 @cindex checksum, 256-bit
3528 @cindex checksum, 384-bit
3529 @cindex checksum, 512-bit
3530 @cindex fingerprint, 224-bit
3531 @cindex fingerprint, 256-bit
3532 @cindex fingerprint, 384-bit
3533 @cindex fingerprint, 512-bit
3534 @cindex message-digest, 224-bit
3535 @cindex message-digest, 256-bit
3536 @cindex message-digest, 384-bit
3537 @cindex message-digest, 512-bit
3539 The commands @command{sha224sum}, @command{sha256sum},
3540 @command{sha384sum} and @command{sha512sum} compute checksums of
3541 various lengths (respectively 224, 256, 384 and 512 bits),
3542 collectively known as the SHA-2 hashes. The usage and options of
3543 these commands are precisely the same as for @command{md5sum}.
3544 @xref{md5sum invocation}.
3546 Note: The SHA384 and SHA512 digests are considerably slower to
3547 compute, especially on 32-bit computers, than SHA224 or SHA256.
3550 @node Operating on sorted files
3551 @chapter Operating on sorted files
3553 @cindex operating on sorted files
3554 @cindex sorted files, operations on
3556 These commands work with (or produce) sorted files.
3559 * sort invocation:: Sort text files.
3560 * shuf invocation:: Shuffle text files.
3561 * uniq invocation:: Uniquify files.
3562 * comm invocation:: Compare two sorted files line by line.
3563 * ptx invocation:: Produce a permuted index of file contents.
3564 * tsort invocation:: Topological sort.
3568 @node sort invocation
3569 @section @command{sort}: Sort text files
3572 @cindex sorting files
3574 @command{sort} sorts, merges, or compares all the lines from the given
3575 files, or standard input if none are given or for a @var{file} of
3576 @samp{-}. By default, @command{sort} writes the results to standard
3580 sort [@var{option}]@dots{} [@var{file}]@dots{}
3583 @command{sort} has three modes of operation: sort (the default), merge,
3584 and check for sortedness. The following options change the operation
3591 @itemx --check=diagnose-first
3594 @cindex checking for sortedness
3595 Check whether the given file is already sorted: if it is not all
3596 sorted, print a diagnostic containing the first out-of-order line and
3597 exit with a status of 1.
3598 Otherwise, exit successfully.
3599 At most one input file can be given.
3602 @itemx --check=quiet
3603 @itemx --check=silent
3606 @cindex checking for sortedness
3607 Exit successfully if the given file is already sorted, and
3608 exit with status 1 otherwise.
3609 At most one input file can be given.
3610 This is like @option{-c}, except it does not print a diagnostic.
3616 @cindex merging sorted files
3617 Merge the given files by sorting them as a group. Each input file must
3618 always be individually sorted. It always works to sort instead of
3619 merge; merging is provided because it is faster, in the case where it
3624 @cindex sort stability
3625 @cindex sort's last-resort comparison
3626 A pair of lines is compared as follows:
3627 @command{sort} compares each pair of fields, in the
3628 order specified on the command line, according to the associated
3629 ordering options, until a difference is found or no fields are left.
3630 If no key fields are specified, @command{sort} uses a default key of
3631 the entire line. Finally, as a last resort when all keys compare
3632 equal, @command{sort} compares entire lines as if no ordering options
3633 other than @option{--reverse} (@option{-r}) were specified. The
3634 @option{--stable} (@option{-s}) option disables this @dfn{last-resort
3635 comparison} so that lines in which all fields compare equal are left
3636 in their original relative order. The @option{--unique}
3637 (@option{-u}) option also disables the last-resort comparison.
3641 Unless otherwise specified, all comparisons use the character collating
3642 sequence specified by the @env{LC_COLLATE} locale.@footnote{If you
3643 use a non-@acronym{POSIX} locale (e.g., by setting @env{LC_ALL}
3644 to @samp{en_US}), then @command{sort} may produce output that is sorted
3645 differently than you're accustomed to. In that case, set the @env{LC_ALL}
3646 environment variable to @samp{C}. Note that setting only @env{LC_COLLATE}
3647 has two problems. First, it is ineffective if @env{LC_ALL} is also set.
3648 Second, it has undefined behavior if @env{LC_CTYPE} (or @env{LANG}, if
3649 @env{LC_CTYPE} is unset) is set to an incompatible value. For example,
3650 you get undefined behavior if @env{LC_CTYPE} is @code{ja_JP.PCK} but
3651 @env{LC_COLLATE} is @code{en_US.UTF-8}.}
3653 @sc{gnu} @command{sort} (as specified for all @sc{gnu} utilities) has no
3654 limit on input line length or restrictions on bytes allowed within lines.
3655 In addition, if the final byte of an input file is not a newline, @sc{gnu}
3656 @command{sort} silently supplies one. A line's trailing newline is not
3657 part of the line for comparison purposes.
3659 @cindex exit status of @command{sort}
3663 0 if no error occurred
3664 1 if invoked with @option{-c} or @option{-C} and the input is not sorted
3665 2 if an error occurred
3669 If the environment variable @env{TMPDIR} is set, @command{sort} uses its
3670 value as the directory for temporary files instead of @file{/tmp}. The
3671 @option{--temporary-directory} (@option{-T}) option in turn overrides
3672 the environment variable.
3674 The following options affect the ordering of output lines. They may be
3675 specified globally or as part of a specific key field. If no key
3676 fields are specified, global options apply to comparison of entire
3677 lines; otherwise the global options are inherited by key fields that do
3678 not specify any special options of their own. In pre-@acronym{POSIX}
3679 versions of @command{sort}, global options affect only later key fields,
3680 so portable shell scripts should specify global options first.
3685 @itemx --ignore-leading-blanks
3687 @opindex --ignore-leading-blanks
3688 @cindex blanks, ignoring leading
3690 Ignore leading blanks when finding sort keys in each line.
3691 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
3695 @itemx --dictionary-order
3697 @opindex --dictionary-order
3698 @cindex dictionary order
3699 @cindex phone directory order
3700 @cindex telephone directory order
3702 Sort in @dfn{phone directory} order: ignore all characters except
3703 letters, digits and blanks when sorting.
3704 By default letters and digits are those of @acronym{ASCII} and a blank
3705 is a space or a tab, but the @env{LC_CTYPE} locale can change this.
3708 @itemx --ignore-case
3710 @opindex --ignore-case
3711 @cindex ignoring case
3712 @cindex case folding
3714 Fold lowercase characters into the equivalent uppercase characters when
3715 comparing so that, for example, @samp{b} and @samp{B} sort as equal.
3716 The @env{LC_CTYPE} locale determines character types.
3719 @itemx --general-numeric-sort
3720 @itemx --sort=general-numeric
3722 @opindex --general-numeric-sort
3724 @cindex general numeric sort
3726 Sort numerically, using the standard C function @code{strtod} to convert
3727 a prefix of each line to a double-precision floating point number.
3728 This allows floating point numbers to be specified in scientific notation,
3729 like @code{1.0e-34} and @code{10e100}.
3730 The @env{LC_NUMERIC} locale determines the decimal-point character.
3731 Do not report overflow, underflow, or conversion errors.
3732 Use the following collating sequence:
3736 Lines that do not start with numbers (all considered to be equal).
3738 NaNs (``Not a Number'' values, in IEEE floating point arithmetic)
3739 in a consistent but machine-dependent order.
3743 Finite numbers in ascending numeric order (with @math{-0} and @math{+0} equal).
3748 Use this option only if there is no alternative; it is much slower than
3749 @option{--numeric-sort} (@option{-n}) and it can lose information when
3750 converting to floating point.
3753 @itemx --ignore-nonprinting
3755 @opindex --ignore-nonprinting
3756 @cindex nonprinting characters, ignoring
3757 @cindex unprintable characters, ignoring
3759 Ignore nonprinting characters.
3760 The @env{LC_CTYPE} locale determines character types.
3761 This option has no effect if the stronger @option{--dictionary-order}
3762 (@option{-d}) option is also given.
3768 @opindex --month-sort
3770 @cindex months, sorting by
3772 An initial string, consisting of any amount of blanks, followed
3773 by a month name abbreviation, is folded to UPPER case and
3774 compared in the order @samp{JAN} < @samp{FEB} < @dots{} < @samp{DEC}.
3775 Invalid names compare low to valid names. The @env{LC_TIME} locale
3776 category determines the month spellings.
3777 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
3781 @itemx --numeric-sort
3782 @itemx --sort=numeric
3784 @opindex --numeric-sort
3786 @cindex numeric sort
3788 Sort numerically. The number begins each line and consists
3789 of optional blanks, an optional @samp{-} sign, and zero or more
3790 digits possibly separated by thousands separators, optionally followed
3791 by a decimal-point character and zero or more digits. An empty
3792 number is treated as @samp{0}. The @env{LC_NUMERIC}
3793 locale specifies the decimal-point character and thousands separator.
3794 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
3797 Comparison is exact; there is no rounding error.
3799 Neither a leading @samp{+} nor exponential notation is recognized.
3800 To compare such strings numerically, use the
3801 @option{--general-numeric-sort} (@option{-g}) option.
3804 @itemx --version-sort
3806 @opindex --version-sort
3807 @cindex version number sort
3809 Sort per @code{strverscmp(3)}. This is a normal string comparison, except
3810 that embedded decimal numbers are sorted by numeric value
3811 (see @option{--numeric-sort} above).
3817 @cindex reverse sorting
3818 Reverse the result of comparison, so that lines with greater key values
3819 appear earlier in the output instead of later.
3822 @itemx --random-sort
3823 @itemx --sort=random
3825 @opindex --random-sort
3828 Sort by hashing the input keys and then sorting the hash values.
3829 Choose the hash function at random, ensuring that it is free of
3830 collisions so that differing keys have differing hash values. This is
3831 like a random permutation of the inputs (@pxref{shuf invocation}),
3832 except that keys with the same value sort together.
3834 If multiple random sort fields are specified, the same random hash
3835 function is used for all fields. To use different random hash
3836 functions for different fields, you can invoke @command{sort} more
3839 The choice of hash function is affected by the
3840 @option{--random-source} option.
3848 @item --compress-program=@var{prog}
3849 Compress any temporary files with the program @var{prog}.
3851 With no arguments, @var{prog} must compress standard input to standard
3852 output, and when given the @option{-d} option it must decompress
3853 standard input to standard output.
3855 Terminate with an error if @var{prog} exits with nonzero status.
3857 White space and the backslash character should not appear in
3858 @var{prog}; they are reserved for future use.
3860 @filesZeroFromOption{sort,,sorted output}
3862 @item -k @var{pos1}[,@var{pos2}]
3863 @itemx --key=@var{pos1}[,@var{pos2}]
3867 Specify a sort field that consists of the part of the line between
3868 @var{pos1} and @var{pos2} (or the end of the line, if @var{pos2} is
3869 omitted), @emph{inclusive}.
3871 Each @var{pos} has the form @samp{@var{f}[.@var{c}][@var{opts}]},
3872 where @var{f} is the number of the field to use, and @var{c} is the number
3873 of the first character from the beginning of the field. Fields and character
3874 positions are numbered starting with 1; a character position of zero in
3875 @var{pos2} indicates the field's last character. If @samp{.@var{c}} is
3876 omitted from @var{pos1}, it defaults to 1 (the beginning of the field);
3877 if omitted from @var{pos2}, it defaults to 0 (the end of the field).
3878 @var{opts} are ordering options, allowing individual keys to be sorted
3879 according to different rules; see below for details. Keys can span
3882 Example: To sort on the second field, use @option{--key=2,2}
3883 (@option{-k 2,2}). See below for more examples.
3885 @item --batch-size=@var{nmerge}
3886 @opindex --batch-size
3887 @cindex number of inputs to merge, nmerge
3888 Merge at most @var{nmerge} inputs at once.
3890 When @command{sort} has to merge more than @var{nmerge} inputs,
3891 it merges them in groups of @var{nmerge}, saving the result in
3892 a temporary file, which is then used as an input in a subsequent merge.
3894 A large value of @var{nmerge} may improve merge performance and decrease
3895 temporary storage utilization at the expense of increased memory usage
3896 and I/0. Conversely a small value of @var{nmerge} may reduce memory
3897 requirements and I/0 at the expense of temporary storage consumption and
3900 The value of @var{nmerge} must be at least 2.
3902 The value of @var{nmerge} may be bounded by a resource limit for open
3903 file descriptors. Try @samp{ulimit -n} or @samp{getconf OPEN_MAX} to
3904 to display the limit for a particular system.
3905 If the value of @var{nmerge} exceeds this limit, then @command{sort} will
3906 issue a warning to standard error and exit with a nonzero status.
3908 @item -o @var{output-file}
3909 @itemx --output=@var{output-file}
3912 @cindex overwriting of input, allowed
3913 Write output to @var{output-file} instead of standard output.
3914 Normally, @command{sort} reads all input before opening
3915 @var{output-file}, so you can safely sort a file in place by using
3916 commands like @code{sort -o F F} and @code{cat F | sort -o F}.
3917 However, @command{sort} with @option{--merge} (@option{-m}) can open
3918 the output file before reading all input, so a command like @code{cat
3919 F | sort -m -o F - G} is not safe as @command{sort} might start
3920 writing @file{F} before @command{cat} is done reading it.
3922 @vindex POSIXLY_CORRECT
3923 On newer systems, @option{-o} cannot appear after an input file if
3924 @env{POSIXLY_CORRECT} is set, e.g., @samp{sort F -o F}. Portable
3925 scripts should specify @option{-o @var{output-file}} before any input
3928 @item --random-source=@var{file}
3929 @opindex --random-source
3930 @cindex random source for sorting
3931 Use @var{file} as a source of random data used to determine which
3932 random hash function to use with the @option{-R} option. @xref{Random
3939 @cindex sort stability
3940 @cindex sort's last-resort comparison
3942 Make @command{sort} stable by disabling its last-resort comparison.
3943 This option has no effect if no fields or global ordering options
3944 other than @option{--reverse} (@option{-r}) are specified.
3947 @itemx --buffer-size=@var{size}
3949 @opindex --buffer-size
3950 @cindex size for main memory sorting
3951 Use a main-memory sort buffer of the given @var{size}. By default,
3952 @var{size} is in units of 1024 bytes. Appending @samp{%} causes
3953 @var{size} to be interpreted as a percentage of physical memory.
3954 Appending @samp{K} multiplies @var{size} by 1024 (the default),
3955 @samp{M} by 1,048,576, @samp{G} by 1,073,741,824, and so on for
3956 @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}. Appending
3957 @samp{b} causes @var{size} to be interpreted as a byte count, with no
3960 This option can improve the performance of @command{sort} by causing it
3961 to start with a larger or smaller sort buffer than the default.
3962 However, this option affects only the initial buffer size. The buffer
3963 grows beyond @var{size} if @command{sort} encounters input lines larger
3966 @item -t @var{separator}
3967 @itemx --field-separator=@var{separator}
3969 @opindex --field-separator
3970 @cindex field separator character
3971 Use character @var{separator} as the field separator when finding the
3972 sort keys in each line. By default, fields are separated by the empty
3973 string between a non-blank character and a blank character.
3974 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
3977 That is, given the input line @w{@samp{ foo bar}}, @command{sort} breaks it
3978 into fields @w{@samp{ foo}} and @w{@samp{ bar}}. The field separator is
3979 not considered to be part of either the field preceding or the field
3980 following, so with @samp{sort @w{-t " "}} the same input line has
3981 three fields: an empty field, @samp{foo}, and @samp{bar}.
3982 However, fields that extend to the end of the line,
3983 as @option{-k 2}, or fields consisting of a range, as @option{-k 2,3},
3984 retain the field separators present between the endpoints of the range.
3986 To specify a null character (@acronym{ASCII} @sc{nul}) as
3987 the field separator, use the two-character string @samp{\0}, e.g.,
3988 @samp{sort -t '\0'}.
3990 @item -T @var{tempdir}
3991 @itemx --temporary-directory=@var{tempdir}
3993 @opindex --temporary-directory
3994 @cindex temporary directory
3996 Use directory @var{tempdir} to store temporary files, overriding the
3997 @env{TMPDIR} environment variable. If this option is given more than
3998 once, temporary files are stored in all the directories given. If you
3999 have a large sort or merge that is I/O-bound, you can often improve
4000 performance by using this option to specify directories on different
4001 disks and controllers.
4007 @cindex uniquifying output
4009 Normally, output only the first of a sequence of lines that compare
4010 equal. For the @option{--check} (@option{-c} or @option{-C}) option,
4011 check that no pair of consecutive lines compares equal.
4013 This option also disables the default last-resort comparison.
4015 The commands @code{sort -u} and @code{sort | uniq} are equivalent, but
4016 this equivalence does not extend to arbitrary @command{sort} options.
4017 For example, @code{sort -n -u} inspects only the value of the initial
4018 numeric string when checking for uniqueness, whereas @code{sort -n |
4019 uniq} inspects the entire line. @xref{uniq invocation}.
4022 @itemx --zero-terminated
4024 @opindex --zero-terminated
4025 @cindex sort zero-terminated lines
4026 Treat the input as a set of lines, each terminated by a null character
4027 (@acronym{ASCII} @sc{nul}) instead of a line feed
4028 (@acronym{ASCII} @sc{lf}).
4029 This option can be useful in conjunction with @samp{perl -0} or
4030 @samp{find -print0} and @samp{xargs -0} which do the same in order to
4031 reliably handle arbitrary file names (even those containing blanks
4032 or other special characters).
4036 Historical (BSD and System V) implementations of @command{sort} have
4037 differed in their interpretation of some options, particularly
4038 @option{-b}, @option{-f}, and @option{-n}. @sc{gnu} sort follows the @acronym{POSIX}
4039 behavior, which is usually (but not always!) like the System V behavior.
4040 According to @acronym{POSIX}, @option{-n} no longer implies @option{-b}. For
4041 consistency, @option{-M} has been changed in the same way. This may
4042 affect the meaning of character positions in field specifications in
4043 obscure cases. The only fix is to add an explicit @option{-b}.
4045 A position in a sort field specified with @option{-k} may have any
4046 of the option letters @samp{Mbdfinr} appended to it, in which case the
4047 global ordering options are not used for that particular field. The
4048 @option{-b} option may be independently attached to either or both of
4049 the start and end positions of a field specification, and if it is
4050 inherited from the global options it will be attached to both.
4051 If input lines can contain leading or adjacent blanks and @option{-t}
4052 is not used, then @option{-k} is typically combined with @option{-b},
4053 @option{-g}, @option{-M}, or @option{-n}; otherwise the varying
4054 numbers of leading blanks in fields can cause confusing results.
4056 If the start position in a sort field specifier falls after the end of
4057 the line or after the end field, the field is empty. If the @option{-b}
4058 option was specified, the @samp{.@var{c}} part of a field specification
4059 is counted from the first nonblank character of the field.
4061 @vindex _POSIX2_VERSION
4062 @vindex POSIXLY_CORRECT
4063 On older systems, @command{sort} supports an obsolete origin-zero
4064 syntax @samp{+@var{pos1} [-@var{pos2}]} for specifying sort keys.
4065 This obsolete behavior can be enabled or disabled with the
4066 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
4067 conformance}); it can also be enabled when @env{POSIXLY_CORRECT} is
4068 not set by using the obsolete syntax with @samp{-@var{pos2}} present.
4070 Scripts intended for use on standard hosts should avoid obsolete
4071 syntax and should use @option{-k} instead. For example, avoid
4072 @samp{sort +2}, since it might be interpreted as either @samp{sort
4073 ./+2} or @samp{sort -k 3}. If your script must also run on hosts that
4074 support only the obsolete syntax, it can use a test like @samp{if sort
4075 -k 1 </dev/null >/dev/null 2>&1; then @dots{}} to decide which syntax
4078 Here are some examples to illustrate various combinations of options.
4083 Sort in descending (reverse) numeric order.
4090 Sort alphabetically, omitting the first and second fields
4091 and the blanks at the start of the third field.
4092 This uses a single key composed of the characters beginning
4093 at the start of the first nonblank character in field three
4094 and extending to the end of each line.
4101 Sort numerically on the second field and resolve ties by sorting
4102 alphabetically on the third and fourth characters of field five.
4103 Use @samp{:} as the field delimiter.
4106 sort -t : -k 2,2n -k 5.3,5.4
4109 Note that if you had written @option{-k 2n} instead of @option{-k 2,2n}
4110 @command{sort} would have used all characters beginning in the second field
4111 and extending to the end of the line as the primary @emph{numeric}
4112 key. For the large majority of applications, treating keys spanning
4113 more than one field as numeric will not do what you expect.
4115 Also note that the @samp{n} modifier was applied to the field-end
4116 specifier for the first key. It would have been equivalent to
4117 specify @option{-k 2n,2} or @option{-k 2n,2n}. All modifiers except
4118 @samp{b} apply to the associated @emph{field}, regardless of whether
4119 the modifier character is attached to the field-start and/or the
4120 field-end part of the key specifier.
4123 Sort the password file on the fifth field and ignore any
4124 leading blanks. Sort lines with equal values in field five
4125 on the numeric user ID in field three. Fields are separated
4129 sort -t : -k 5b,5 -k 3,3n /etc/passwd
4130 sort -t : -n -k 5b,5 -k 3,3 /etc/passwd
4131 sort -t : -b -k 5,5 -k 3,3n /etc/passwd
4134 These three commands have equivalent effect. The first specifies that
4135 the first key's start position ignores leading blanks and the second
4136 key is sorted numerically. The other two commands rely on global
4137 options being inherited by sort keys that lack modifiers. The inheritance
4138 works in this case because @option{-k 5b,5b} and @option{-k 5b,5} are
4139 equivalent, as the location of a field-end lacking a @samp{.@var{c}}
4140 character position is not affected by whether initial blanks are
4144 Sort a set of log files, primarily by IPv4 address and secondarily by
4145 time stamp. If two lines' primary and secondary keys are identical,
4146 output the lines in the same order that they were input. The log
4147 files contain lines that look like this:
4150 4.150.156.3 - - [01/Apr/2004:06:31:51 +0000] message 1
4151 211.24.3.231 - - [24/Apr/2004:20:17:39 +0000] message 2
4154 Fields are separated by exactly one space. Sort IPv4 addresses
4155 lexicographically, e.g., 212.61.52.2 sorts before 212.129.233.201
4156 because 61 is less than 129.
4159 sort -s -t ' ' -k 4.9n -k 4.5M -k 4.2n -k 4.14,4.21 file*.log |
4160 sort -s -t '.' -k 1,1n -k 2,2n -k 3,3n -k 4,4n
4163 This example cannot be done with a single @command{sort} invocation,
4164 since IPv4 address components are separated by @samp{.} while dates
4165 come just after a space. So it is broken down into two invocations of
4166 @command{sort}: the first sorts by time stamp and the second by IPv4
4167 address. The time stamp is sorted by year, then month, then day, and
4168 finally by hour-minute-second field, using @option{-k} to isolate each
4169 field. Except for hour-minute-second there's no need to specify the
4170 end of each key field, since the @samp{n} and @samp{M} modifiers sort
4171 based on leading prefixes that cannot cross field boundaries. The
4172 IPv4 addresses are sorted lexicographically. The second sort uses
4173 @samp{-s} so that ties in the primary key are broken by the secondary
4174 key; the first sort uses @samp{-s} so that the combination of the two
4178 Generate a tags file in case-insensitive sorted order.
4181 find src -type f -print0 | sort -z -f | xargs -0 etags --append
4184 The use of @option{-print0}, @option{-z}, and @option{-0} in this case means
4185 that file names that contain blanks or other special characters are
4187 by the sort operation.
4189 @c This example is a bit contrived and needs more explanation.
4191 @c Sort records separated by an arbitrary string by using a pipe to convert
4192 @c each record delimiter string to @samp{\0}, then using sort's -z option,
4193 @c and converting each @samp{\0} back to the original record delimiter.
4196 @c printf 'c\n\nb\n\na\n'|perl -0pe 's/\n\n/\n\0/g'|sort -z|perl -0pe 's/\0/\n/g'
4200 Shuffle a list of directories, but preserve the order of files within
4201 each directory. For instance, one could use this to generate a music
4202 playlist in which albums are shuffled but the songs of each album are
4206 ls */* | sort -t / -k 1,1R -k 2,2
4212 @node shuf invocation
4213 @section @command{shuf}: Shuffling text
4216 @cindex shuffling files
4218 @command{shuf} shuffles its input by outputting a random permutation
4219 of its input lines. Each output permutation is equally likely.
4223 shuf [@var{option}]@dots{} [@var{file}]
4224 shuf -e [@var{option}]@dots{} [@var{arg}]@dots{}
4225 shuf -i @var{lo}-@var{hi} [@var{option}]@dots{}
4228 @command{shuf} has three modes of operation that affect where it
4229 obtains its input lines. By default, it reads lines from standard
4230 input. The following options change the operation mode:
4238 @cindex command-line operands to shuffle
4239 Treat each command-line operand as an input line.
4241 @item -i @var{lo}-@var{hi}
4242 @itemx --input-range=@var{lo}-@var{hi}
4244 @opindex --input-range
4245 @cindex input range to shuffle
4246 Act as if input came from a file containing the range of unsigned
4247 decimal integers @var{lo}@dots{}@var{hi}, one per line.
4251 @command{shuf}'s other options can affect its behavior in all
4256 @item -n @var{lines}
4257 @itemx --head-count=@var{count}
4259 @opindex --head-count
4260 @cindex head of output
4261 Output at most @var{count} lines. By default, all input lines are
4264 @item -o @var{output-file}
4265 @itemx --output=@var{output-file}
4268 @cindex overwriting of input, allowed
4269 Write output to @var{output-file} instead of standard output.
4270 @command{shuf} reads all input before opening
4271 @var{output-file}, so you can safely shuffle a file in place by using
4272 commands like @code{shuf -o F <F} and @code{cat F | shuf -o F}.
4274 @item --random-source=@var{file}
4275 @opindex --random-source
4276 @cindex random source for shuffling
4277 Use @var{file} as a source of random data used to determine which
4278 permutation to generate. @xref{Random sources}.
4281 @itemx --zero-terminated
4283 @opindex --zero-terminated
4284 @cindex sort zero-terminated lines
4285 Treat the input and output as a set of lines, each terminated by a zero byte
4286 (@acronym{ASCII} @sc{nul} (Null) character) instead of an
4287 @acronym{ASCII} @sc{lf} (Line Feed).
4288 This option can be useful in conjunction with @samp{perl -0} or
4289 @samp{find -print0} and @samp{xargs -0} which do the same in order to
4290 reliably handle arbitrary file names (even those containing blanks
4291 or other special characters).
4307 might produce the output
4317 Similarly, the command:
4320 shuf -e clubs hearts diamonds spades
4334 and the command @samp{shuf -i 1-4} might output:
4344 These examples all have four input lines, so @command{shuf} might
4345 produce any of the twenty-four possible permutations of the input. In
4346 general, if there are @var{N} input lines, there are @var{N}! (i.e.,
4347 @var{N} factorial, or @var{N} * (@var{N} - 1) * @dots{} * 1) possible
4348 output permutations.
4353 @node uniq invocation
4354 @section @command{uniq}: Uniquify files
4357 @cindex uniquify files
4359 @command{uniq} writes the unique lines in the given @file{input}, or
4360 standard input if nothing is given or for an @var{input} name of
4364 uniq [@var{option}]@dots{} [@var{input} [@var{output}]]
4367 By default, @command{uniq} prints its input lines, except that
4368 it discards all but the first of adjacent repeated lines, so that
4369 no output lines are repeated. Optionally, it can instead discard
4370 lines that are not repeated, or all repeated lines.
4372 The input need not be sorted, but repeated input lines are detected
4373 only if they are adjacent. If you want to discard non-adjacent
4374 duplicate lines, perhaps you want to use @code{sort -u}.
4375 @xref{sort invocation}.
4378 Comparisons use the character collating sequence specified by the
4379 @env{LC_COLLATE} locale category.
4381 If no @var{output} file is specified, @command{uniq} writes to standard
4384 The program accepts the following options. Also see @ref{Common options}.
4389 @itemx --skip-fields=@var{n}
4391 @opindex --skip-fields
4392 Skip @var{n} fields on each line before checking for uniqueness. Use
4393 a null string for comparison if a line has fewer than @var{n} fields. Fields
4394 are sequences of non-space non-tab characters that are separated from
4395 each other by at least one space or tab.
4397 For compatibility @command{uniq} supports an obsolete option syntax
4398 @option{-@var{n}}. New scripts should use @option{-f @var{n}} instead.
4401 @itemx --skip-chars=@var{n}
4403 @opindex --skip-chars
4404 Skip @var{n} characters before checking for uniqueness. Use a null string
4405 for comparison if a line has fewer than @var{n} characters. If you use both
4406 the field and character skipping options, fields are skipped over first.
4408 @vindex _POSIX2_VERSION
4409 On older systems, @command{uniq} supports an obsolete option syntax
4411 This obsolete behavior can be enabled or disabled with the
4412 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
4413 conformance}), but portable scripts should avoid commands whose
4414 behavior depends on this variable.
4415 For example, use @samp{uniq ./+10} or @samp{uniq -s 10} rather than
4416 the ambiguous @samp{uniq +10}.
4422 Print the number of times each line occurred along with the line.
4425 @itemx --ignore-case
4427 @opindex --ignore-case
4428 Ignore differences in case when comparing lines.
4434 @cindex repeated lines, outputting
4435 Discard lines that are not repeated. When used by itself, this option
4436 causes @command{uniq} to print the first copy of each repeated line,
4440 @itemx --all-repeated[=@var{delimit-method}]
4442 @opindex --all-repeated
4443 @cindex all repeated lines, outputting
4444 Do not discard the second and subsequent repeated input lines,
4445 but discard lines that are not repeated.
4446 This option is useful mainly in conjunction with other options e.g.,
4447 to ignore case or to compare only selected fields.
4448 The optional @var{delimit-method} tells how to delimit
4449 groups of repeated lines, and must be one of the following:
4454 Do not delimit groups of repeated lines.
4455 This is equivalent to @option{--all-repeated} (@option{-D}).
4458 Output a newline before each group of repeated lines.
4459 With @option{--zero-terminated} (@option{-z}), use
4460 an @acronym{ASCII} @sc{nul} (zero) byte instead of a newline.
4463 Separate groups of repeated lines with a single newline.
4464 With @option{--zero-terminated} (@option{-z}), use
4465 an @acronym{ASCII} @sc{nul} (zero) byte instead of a newline.
4466 This is the same as using @samp{prepend}, except that
4467 no delimiter is inserted before the first group, and hence
4468 may be better suited for output direct to users.
4471 Note that when groups are delimited and the input stream contains
4472 two or more consecutive blank lines, then the output is ambiguous.
4473 To avoid that, filter the input through @samp{tr -s '\n'} to replace
4474 each sequence of consecutive newlines with a single newline.
4476 This is a @sc{gnu} extension.
4477 @c FIXME: give an example showing *how* it's useful
4483 @cindex unique lines, outputting
4484 Discard the first repeated line. When used by itself, this option
4485 causes @command{uniq} to print unique lines, and nothing else.
4488 @itemx --check-chars=@var{n}
4490 @opindex --check-chars
4491 Compare at most @var{n} characters on each line (after skipping any specified
4492 fields and characters). By default the entire rest of the lines are
4496 @itemx --zero-terminated
4498 @opindex --zero-terminated
4499 @cindex sort zero-terminated lines
4500 Treat the input as a set of lines, each terminated by a null character
4501 (@acronym{ASCII} @sc{nul}) instead of a line feed
4502 (@acronym{ASCII} @sc{lf}).
4503 This option can be useful in conjunction with @samp{sort -z}, @samp{perl -0} or
4504 @samp{find -print0} and @samp{xargs -0} which do the same in order to
4505 reliably handle arbitrary file names (even those containing blanks
4506 or other special characters).
4513 @node comm invocation
4514 @section @command{comm}: Compare two sorted files line by line
4517 @cindex line-by-line comparison
4518 @cindex comparing sorted files
4520 @command{comm} writes to standard output lines that are common, and lines
4521 that are unique, to two input files; a file name of @samp{-} means
4522 standard input. Synopsis:
4525 comm [@var{option}]@dots{} @var{file1} @var{file2}
4529 Before @command{comm} can be used, the input files must be sorted using the
4530 collating sequence specified by the @env{LC_COLLATE} locale.
4531 If an input file ends in a non-newline
4532 character, a newline is silently appended. The @command{sort} command with
4533 no options always outputs a file that is suitable input to @command{comm}.
4535 @cindex differing lines
4536 @cindex common lines
4537 With no options, @command{comm} produces three-column output. Column one
4538 contains lines unique to @var{file1}, column two contains lines unique
4539 to @var{file2}, and column three contains lines common to both files.
4540 Columns are separated by a single TAB character.
4541 @c FIXME: when there's an option to supply an alternative separator
4542 @c string, append `by default' to the above sentence.
4547 The options @option{-1}, @option{-2}, and @option{-3} suppress printing of
4548 the corresponding columns. Also see @ref{Common options}.
4550 Unlike some other comparison utilities, @command{comm} has an exit
4551 status that does not depend on the result of the comparison.
4552 Upon normal completion @command{comm} produces an exit code of zero.
4553 If there is an error it exits with nonzero status.
4555 @macro checkOrderOption{cmd}
4556 If the @option{--check-order} option is given, unsorted inputs will
4557 cause a fatal error message. If the option @option{--nocheck-order}
4558 is given, unsorted inputs will never cause an error message. If
4559 neither of these options is given, wrongly sorted inputs are diagnosed
4560 only if an input file is found to contain unpairable lines. If an
4561 input file is diagnosed as being unsorted, the @command{\cmd\} command
4562 will exit with a nonzero status (and the output should not be used).
4564 Forcing @command{\cmd\} to process wrongly sorted input files
4565 containing unpairable lines by specifying @option{--nocheck-order} is
4566 not guaranteed to produce any particular output. The output will
4567 probably not correspond with whatever you hoped it would be.
4569 @checkOrderOption{comm}
4574 Fail with an error message if either input file is wrongly ordered.
4576 @item --nocheck-order
4577 Do not check that both input files are in sorted order.
4581 @item --output-delimiter=@var{str}
4582 Print @var{str} between adjacent output columns,
4583 rather than the default of a single TAB character.
4585 The delimiter @var{str} may not be empty.
4589 @node ptx invocation
4590 @section @command{ptx}: Produce permuted indexes
4594 @command{ptx} reads a text file and essentially produces a permuted index, with
4595 each keyword in its context. The calling sketch is either one of:
4598 ptx [@var{option} @dots{}] [@var{file} @dots{}]
4599 ptx -G [@var{option} @dots{}] [@var{input} [@var{output}]]
4602 The @option{-G} (or its equivalent: @option{--traditional}) option disables
4603 all @sc{gnu} extensions and reverts to traditional mode, thus introducing some
4604 limitations and changing several of the program's default option values.
4605 When @option{-G} is not specified, @sc{gnu} extensions are always enabled.
4606 @sc{gnu} extensions to @command{ptx} are documented wherever appropriate in this
4607 document. For the full list, see @xref{Compatibility in ptx}.
4609 Individual options are explained in the following sections.
4611 When @sc{gnu} extensions are enabled, there may be zero, one or several
4612 @var{file}s after the options. If there is no @var{file}, the program
4613 reads the standard input. If there is one or several @var{file}s, they
4614 give the name of input files which are all read in turn, as if all the
4615 input files were concatenated. However, there is a full contextual
4616 break between each file and, when automatic referencing is requested,
4617 file names and line numbers refer to individual text input files. In
4618 all cases, the program outputs the permuted index to the standard
4621 When @sc{gnu} extensions are @emph{not} enabled, that is, when the program
4622 operates in traditional mode, there may be zero, one or two parameters
4623 besides the options. If there are no parameters, the program reads the
4624 standard input and outputs the permuted index to the standard output.
4625 If there is only one parameter, it names the text @var{input} to be read
4626 instead of the standard input. If two parameters are given, they give
4627 respectively the name of the @var{input} file to read and the name of
4628 the @var{output} file to produce. @emph{Be very careful} to note that,
4629 in this case, the contents of file given by the second parameter is
4630 destroyed. This behavior is dictated by System V @command{ptx}
4631 compatibility; @sc{gnu} Standards normally discourage output parameters not
4632 introduced by an option.
4634 Note that for @emph{any} file named as the value of an option or as an
4635 input text file, a single dash @kbd{-} may be used, in which case
4636 standard input is assumed. However, it would not make sense to use this
4637 convention more than once per program invocation.
4640 * General options in ptx:: Options which affect general program behavior.
4641 * Charset selection in ptx:: Underlying character set considerations.
4642 * Input processing in ptx:: Input fields, contexts, and keyword selection.
4643 * Output formatting in ptx:: Types of output format, and sizing the fields.
4644 * Compatibility in ptx::
4648 @node General options in ptx
4649 @subsection General options
4654 @itemx --traditional
4655 As already explained, this option disables all @sc{gnu} extensions to
4656 @command{ptx} and switches to traditional mode.
4659 Print a short help on standard output, then exit without further
4663 Print the program version on standard output, then exit without further
4671 @node Charset selection in ptx
4672 @subsection Charset selection
4674 @c FIXME: People don't necessarily know what an IBM-PC was these days.
4675 As it is set up now, the program assumes that the input file is coded
4676 using 8-bit @acronym{ISO} 8859-1 code, also known as Latin-1 character set,
4677 @emph{unless} it is compiled for MS-DOS, in which case it uses the
4678 character set of the IBM-PC@. (@sc{gnu} @command{ptx} is not known to work on
4679 smaller MS-DOS machines anymore.) Compared to 7-bit @acronym{ASCII}, the set
4680 of characters which are letters is different; this alters the behavior
4681 of regular expression matching. Thus, the default regular expression
4682 for a keyword allows foreign or diacriticized letters. Keyword sorting,
4683 however, is still crude; it obeys the underlying character set ordering
4689 @itemx --ignore-case
4690 Fold lower case letters to upper case for sorting.
4695 @node Input processing in ptx
4696 @subsection Word selection and input processing
4701 @itemx --break-file=@var{file}
4703 This option provides an alternative (to @option{-W}) method of describing
4704 which characters make up words. It introduces the name of a
4705 file which contains a list of characters which can@emph{not} be part of
4706 one word; this file is called the @dfn{Break file}. Any character which
4707 is not part of the Break file is a word constituent. If both options
4708 @option{-b} and @option{-W} are specified, then @option{-W} has precedence and
4709 @option{-b} is ignored.
4711 When @sc{gnu} extensions are enabled, the only way to avoid newline as a
4712 break character is to write all the break characters in the file with no
4713 newline at all, not even at the end of the file. When @sc{gnu} extensions
4714 are disabled, spaces, tabs and newlines are always considered as break
4715 characters even if not included in the Break file.
4718 @itemx --ignore-file=@var{file}
4720 The file associated with this option contains a list of words which will
4721 never be taken as keywords in concordance output. It is called the
4722 @dfn{Ignore file}. The file contains exactly one word in each line; the
4723 end of line separation of words is not subject to the value of the
4727 @itemx --only-file=@var{file}
4729 The file associated with this option contains a list of words which will
4730 be retained in concordance output; any word not mentioned in this file
4731 is ignored. The file is called the @dfn{Only file}. The file contains
4732 exactly one word in each line; the end of line separation of words is
4733 not subject to the value of the @option{-S} option.
4735 There is no default for the Only file. When both an Only file and an
4736 Ignore file are specified, a word is considered a keyword only
4737 if it is listed in the Only file and not in the Ignore file.
4742 On each input line, the leading sequence of non-white space characters will be
4743 taken to be a reference that has the purpose of identifying this input
4744 line in the resulting permuted index. For more information about reference
4745 production, see @xref{Output formatting in ptx}.
4746 Using this option changes the default value for option @option{-S}.
4748 Using this option, the program does not try very hard to remove
4749 references from contexts in output, but it succeeds in doing so
4750 @emph{when} the context ends exactly at the newline. If option
4751 @option{-r} is used with @option{-S} default value, or when @sc{gnu} extensions
4752 are disabled, this condition is always met and references are completely
4753 excluded from the output contexts.
4755 @item -S @var{regexp}
4756 @itemx --sentence-regexp=@var{regexp}
4758 This option selects which regular expression will describe the end of a
4759 line or the end of a sentence. In fact, this regular expression is not
4760 the only distinction between end of lines or end of sentences, and input
4761 line boundaries have no special significance outside this option. By
4762 default, when @sc{gnu} extensions are enabled and if @option{-r} option is not
4763 used, end of sentences are used. In this case, this @var{regex} is
4764 imported from @sc{gnu} Emacs:
4767 [.?!][]\"')@}]*\\($\\|\t\\| \\)[ \t\n]*
4770 Whenever @sc{gnu} extensions are disabled or if @option{-r} option is used, end
4771 of lines are used; in this case, the default @var{regexp} is just:
4777 Using an empty @var{regexp} is equivalent to completely disabling end of
4778 line or end of sentence recognition. In this case, the whole file is
4779 considered to be a single big line or sentence. The user might want to
4780 disallow all truncation flag generation as well, through option @option{-F
4781 ""}. @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
4784 When the keywords happen to be near the beginning of the input line or
4785 sentence, this often creates an unused area at the beginning of the
4786 output context line; when the keywords happen to be near the end of the
4787 input line or sentence, this often creates an unused area at the end of
4788 the output context line. The program tries to fill those unused areas
4789 by wrapping around context in them; the tail of the input line or
4790 sentence is used to fill the unused area on the left of the output line;
4791 the head of the input line or sentence is used to fill the unused area
4792 on the right of the output line.
4794 As a matter of convenience to the user, many usual backslashed escape
4795 sequences from the C language are recognized and converted to the
4796 corresponding characters by @command{ptx} itself.
4798 @item -W @var{regexp}
4799 @itemx --word-regexp=@var{regexp}
4801 This option selects which regular expression will describe each keyword.
4802 By default, if @sc{gnu} extensions are enabled, a word is a sequence of
4803 letters; the @var{regexp} used is @samp{\w+}. When @sc{gnu} extensions are
4804 disabled, a word is by default anything which ends with a space, a tab
4805 or a newline; the @var{regexp} used is @samp{[^ \t\n]+}.
4807 An empty @var{regexp} is equivalent to not using this option.
4808 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
4811 As a matter of convenience to the user, many usual backslashed escape
4812 sequences, as found in the C language, are recognized and converted to
4813 the corresponding characters by @command{ptx} itself.
4818 @node Output formatting in ptx
4819 @subsection Output formatting
4821 Output format is mainly controlled by the @option{-O} and @option{-T} options
4822 described in the table below. When neither @option{-O} nor @option{-T} are
4823 selected, and if @sc{gnu} extensions are enabled, the program chooses an
4824 output format suitable for a dumb terminal. Each keyword occurrence is
4825 output to the center of one line, surrounded by its left and right
4826 contexts. Each field is properly justified, so the concordance output
4827 can be readily observed. As a special feature, if automatic
4828 references are selected by option @option{-A} and are output before the
4829 left context, that is, if option @option{-R} is @emph{not} selected, then
4830 a colon is added after the reference; this nicely interfaces with @sc{gnu}
4831 Emacs @code{next-error} processing. In this default output format, each
4832 white space character, like newline and tab, is merely changed to
4833 exactly one space, with no special attempt to compress consecutive
4834 spaces. This might change in the future. Except for those white space
4835 characters, every other character of the underlying set of 256
4836 characters is transmitted verbatim.
4838 Output format is further controlled by the following options.
4842 @item -g @var{number}
4843 @itemx --gap-size=@var{number}
4845 Select the size of the minimum white space gap between the fields on the
4848 @item -w @var{number}
4849 @itemx --width=@var{number}
4851 Select the maximum output width of each final line. If references are
4852 used, they are included or excluded from the maximum output width
4853 depending on the value of option @option{-R}. If this option is not
4854 selected, that is, when references are output before the left context,
4855 the maximum output width takes into account the maximum length of all
4856 references. If this option is selected, that is, when references are
4857 output after the right context, the maximum output width does not take
4858 into account the space taken by references, nor the gap that precedes
4862 @itemx --auto-reference
4864 Select automatic references. Each input line will have an automatic
4865 reference made up of the file name and the line ordinal, with a single
4866 colon between them. However, the file name will be empty when standard
4867 input is being read. If both @option{-A} and @option{-r} are selected, then
4868 the input reference is still read and skipped, but the automatic
4869 reference is used at output time, overriding the input reference.
4872 @itemx --right-side-refs
4874 In the default output format, when option @option{-R} is not used, any
4875 references produced by the effect of options @option{-r} or @option{-A} are
4876 placed to the far right of output lines, after the right context. With
4877 default output format, when the @option{-R} option is specified, references
4878 are rather placed at the beginning of each output line, before the left
4879 context. For any other output format, option @option{-R} is
4880 ignored, with one exception: with @option{-R} the width of references
4881 is @emph{not} taken into account in total output width given by @option{-w}.
4883 This option is automatically selected whenever @sc{gnu} extensions are
4886 @item -F @var{string}
4887 @itemx --flac-truncation=@var{string}
4889 This option will request that any truncation in the output be reported
4890 using the string @var{string}. Most output fields theoretically extend
4891 towards the beginning or the end of the current line, or current
4892 sentence, as selected with option @option{-S}. But there is a maximum
4893 allowed output line width, changeable through option @option{-w}, which is
4894 further divided into space for various output fields. When a field has
4895 to be truncated because it cannot extend beyond the beginning or the end of
4896 the current line to fit in, then a truncation occurs. By default,
4897 the string used is a single slash, as in @option{-F /}.
4899 @var{string} may have more than one character, as in @option{-F ...}.
4900 Also, in the particular case when @var{string} is empty (@option{-F ""}),
4901 truncation flagging is disabled, and no truncation marks are appended in
4904 As a matter of convenience to the user, many usual backslashed escape
4905 sequences, as found in the C language, are recognized and converted to
4906 the corresponding characters by @command{ptx} itself.
4908 @item -M @var{string}
4909 @itemx --macro-name=@var{string}
4911 Select another @var{string} to be used instead of @samp{xx}, while
4912 generating output suitable for @command{nroff}, @command{troff} or @TeX{}.
4915 @itemx --format=roff
4917 Choose an output format suitable for @command{nroff} or @command{troff}
4918 processing. Each output line will look like:
4921 .xx "@var{tail}" "@var{before}" "@var{keyword_and_after}" "@var{head}" "@var{ref}"
4924 so it will be possible to write a @samp{.xx} roff macro to take care of
4925 the output typesetting. This is the default output format when @sc{gnu}
4926 extensions are disabled. Option @option{-M} can be used to change
4927 @samp{xx} to another macro name.
4929 In this output format, each non-graphical character, like newline and
4930 tab, is merely changed to exactly one space, with no special attempt to
4931 compress consecutive spaces. Each quote character: @kbd{"} is doubled
4932 so it will be correctly processed by @command{nroff} or @command{troff}.
4937 Choose an output format suitable for @TeX{} processing. Each output
4938 line will look like:
4941 \xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@{@var{after}@}@{@var{head}@}@{@var{ref}@}
4945 so it will be possible to write a @code{\xx} definition to take care of
4946 the output typesetting. Note that when references are not being
4947 produced, that is, neither option @option{-A} nor option @option{-r} is
4948 selected, the last parameter of each @code{\xx} call is inhibited.
4949 Option @option{-M} can be used to change @samp{xx} to another macro
4952 In this output format, some special characters, like @kbd{$}, @kbd{%},
4953 @kbd{&}, @kbd{#} and @kbd{_} are automatically protected with a
4954 backslash. Curly brackets @kbd{@{}, @kbd{@}} are protected with a
4955 backslash and a pair of dollar signs (to force mathematical mode). The
4956 backslash itself produces the sequence @code{\backslash@{@}}.
4957 Circumflex and tilde diacritical marks produce the sequence @code{^\@{ @}} and
4958 @code{~\@{ @}} respectively. Other diacriticized characters of the
4959 underlying character set produce an appropriate @TeX{} sequence as far
4960 as possible. The other non-graphical characters, like newline and tab,
4961 and all other characters which are not part of @acronym{ASCII}, are merely
4962 changed to exactly one space, with no special attempt to compress
4963 consecutive spaces. Let me know how to improve this special character
4964 processing for @TeX{}.
4969 @node Compatibility in ptx
4970 @subsection The @sc{gnu} extensions to @command{ptx}
4972 This version of @command{ptx} contains a few features which do not exist in
4973 System V @command{ptx}. These extra features are suppressed by using the
4974 @option{-G} command line option, unless overridden by other command line
4975 options. Some @sc{gnu} extensions cannot be recovered by overriding, so the
4976 simple rule is to avoid @option{-G} if you care about @sc{gnu} extensions.
4977 Here are the differences between this program and System V @command{ptx}.
4982 This program can read many input files at once, it always writes the
4983 resulting concordance on standard output. On the other hand, System V
4984 @command{ptx} reads only one file and sends the result to standard output
4985 or, if a second @var{file} parameter is given on the command, to that
4988 Having output parameters not introduced by options is a dangerous
4989 practice which @sc{gnu} avoids as far as possible. So, for using @command{ptx}
4990 portably between @sc{gnu} and System V, you should always use it with a
4991 single input file, and always expect the result on standard output. You
4992 might also want to automatically configure in a @option{-G} option to
4993 @command{ptx} calls in products using @command{ptx}, if the configurator finds
4994 that the installed @command{ptx} accepts @option{-G}.
4997 The only options available in System V @command{ptx} are options @option{-b},
4998 @option{-f}, @option{-g}, @option{-i}, @option{-o}, @option{-r}, @option{-t} and
4999 @option{-w}. All other options are @sc{gnu} extensions and are not repeated in
5000 this enumeration. Moreover, some options have a slightly different
5001 meaning when @sc{gnu} extensions are enabled, as explained below.
5004 By default, concordance output is not formatted for @command{troff} or
5005 @command{nroff}. It is rather formatted for a dumb terminal. @command{troff}
5006 or @command{nroff} output may still be selected through option @option{-O}.
5009 Unless @option{-R} option is used, the maximum reference width is
5010 subtracted from the total output line width. With @sc{gnu} extensions
5011 disabled, width of references is not taken into account in the output
5012 line width computations.
5015 All 256 bytes, even null bytes, are always read and processed from
5016 input file with no adverse effect, even if @sc{gnu} extensions are disabled.
5017 However, System V @command{ptx} does not accept 8-bit characters, a few
5018 control characters are rejected, and the tilde @kbd{~} is also rejected.
5021 Input line length is only limited by available memory, even if @sc{gnu}
5022 extensions are disabled. However, System V @command{ptx} processes only
5023 the first 200 characters in each line.
5026 The break (non-word) characters default to be every character except all
5027 letters of the underlying character set, diacriticized or not. When @sc{gnu}
5028 extensions are disabled, the break characters default to space, tab and
5032 The program makes better use of output line width. If @sc{gnu} extensions
5033 are disabled, the program rather tries to imitate System V @command{ptx},
5034 but still, there are some slight disposition glitches this program does
5035 not completely reproduce.
5038 The user can specify both an Ignore file and an Only file. This is not
5039 allowed with System V @command{ptx}.
5044 @node tsort invocation
5045 @section @command{tsort}: Topological sort
5048 @cindex topological sort
5050 @command{tsort} performs a topological sort on the given @var{file}, or
5051 standard input if no input file is given or for a @var{file} of
5052 @samp{-}. For more details and some history, see @ref{tsort background}.
5056 tsort [@var{option}] [@var{file}]
5059 @command{tsort} reads its input as pairs of strings, separated by blanks,
5060 indicating a partial ordering. The output is a total ordering that
5061 corresponds to the given partial ordering.
5075 will produce the output
5086 Consider a more realistic example.
5087 You have a large set of functions all in one file, and they may all be
5088 declared static except one. Currently that one (say @code{main}) is the
5089 first function defined in the file, and the ones it calls directly follow
5090 it, followed by those they call, etc. Let's say that you are determined
5091 to take advantage of prototypes, so you have to choose between declaring
5092 all of those functions (which means duplicating a lot of information from
5093 the definitions) and rearranging the functions so that as many as possible
5094 are defined before they are used. One way to automate the latter process
5095 is to get a list for each function of the functions it calls directly.
5096 Many programs can generate such lists. They describe a call graph.
5097 Consider the following list, in which a given line indicates that the
5098 function on the left calls the one on the right directly.
5104 tail_file pretty_name
5105 tail_file write_header
5107 tail_forever recheck
5108 tail_forever pretty_name
5109 tail_forever write_header
5110 tail_forever dump_remainder
5113 tail_lines start_lines
5114 tail_lines dump_remainder
5115 tail_lines file_lines
5116 tail_lines pipe_lines
5118 tail_bytes start_bytes
5119 tail_bytes dump_remainder
5120 tail_bytes pipe_bytes
5121 file_lines dump_remainder
5125 then you can use @command{tsort} to produce an ordering of those
5126 functions that satisfies your requirement.
5129 example$ tsort call-graph | tac
5149 @command{tsort} detects any cycles in the input and writes the first cycle
5150 encountered to standard error.
5152 Note that for a given partial ordering, generally there is no unique
5153 total ordering. In the context of the call graph above, the function
5154 @code{parse_options} may be placed anywhere in the list as long as it
5155 precedes @code{main}.
5157 The only options are @option{--help} and @option{--version}. @xref{Common
5163 * tsort background:: Where tsort came from.
5166 @node tsort background
5167 @subsection @command{tsort}: Background
5169 @command{tsort} exists because very early versions of the Unix linker processed
5170 an archive file exactly once, and in order. As @command{ld} read each object
5171 in the archive, it decided whether it was needed in the program based on
5172 whether it defined any symbols which were undefined at that point in
5175 This meant that dependencies within the archive had to be handled
5176 specially. For example, @code{scanf} probably calls @code{read}. That means
5177 that in a single pass through an archive, it was important for @code{scanf.o}
5178 to appear before read.o, because otherwise a program which calls
5179 @code{scanf} but not @code{read} might end up with an unexpected unresolved
5180 reference to @code{read}.
5182 The way to address this problem was to first generate a set of
5183 dependencies of one object file on another. This was done by a shell
5184 script called @command{lorder}. The GNU tools don't provide a version of
5185 lorder, as far as I know, but you can still find it in BSD
5188 Then you ran @command{tsort} over the @command{lorder} output, and you used the
5189 resulting sort to define the order in which you added objects to the archive.
5191 This whole procedure has been obsolete since about 1980, because
5192 Unix archives now contain a symbol table (traditionally built by
5193 @command{ranlib}, now generally built by @command{ar} itself), and the Unix
5194 linker uses the symbol table to effectively make multiple passes over
5197 Anyhow, that's where tsort came from. To solve an old problem with
5198 the way the linker handled archive files, which has since been solved
5202 @node Operating on fields within a line
5203 @chapter Operating on fields within a line
5206 * cut invocation:: Print selected parts of lines.
5207 * paste invocation:: Merge lines of files.
5208 * join invocation:: Join lines on a common field.
5212 @node cut invocation
5213 @section @command{cut}: Print selected parts of lines
5216 @command{cut} writes to standard output selected parts of each line of each
5217 input file, or standard input if no files are given or for a file name of
5221 cut @var{option}@dots{} [@var{file}]@dots{}
5224 In the table which follows, the @var{byte-list}, @var{character-list},
5225 and @var{field-list} are one or more numbers or ranges (two numbers
5226 separated by a dash) separated by commas. Bytes, characters, and
5227 fields are numbered starting at 1. Incomplete ranges may be
5228 given: @option{-@var{m}} means @samp{1-@var{m}}; @samp{@var{n}-} means
5229 @samp{@var{n}} through end of line or last field. The list elements
5230 can be repeated, can overlap, and can be specified in any order; but
5231 the selected input is written in the same order that it is read, and
5232 is written exactly once.
5234 The program accepts the following options. Also see @ref{Common
5239 @item -b @var{byte-list}
5240 @itemx --bytes=@var{byte-list}
5243 Select for printing only the bytes in positions listed in
5244 @var{byte-list}. Tabs and backspaces are treated like any other
5245 character; they take up 1 byte. If an output delimiter is specified,
5246 (see the description of @option{--output-delimiter}), then output that
5247 string between ranges of selected bytes.
5249 @item -c @var{character-list}
5250 @itemx --characters=@var{character-list}
5252 @opindex --characters
5253 Select for printing only the characters in positions listed in
5254 @var{character-list}. The same as @option{-b} for now, but
5255 internationalization will change that. Tabs and backspaces are
5256 treated like any other character; they take up 1 character. If an
5257 output delimiter is specified, (see the description of
5258 @option{--output-delimiter}), then output that string between ranges
5261 @item -f @var{field-list}
5262 @itemx --fields=@var{field-list}
5265 Select for printing only the fields listed in @var{field-list}.
5266 Fields are separated by a TAB character by default. Also print any
5267 line that contains no delimiter character, unless the
5268 @option{--only-delimited} (@option{-s}) option is specified
5270 @item -d @var{input_delim_byte}
5271 @itemx --delimiter=@var{input_delim_byte}
5273 @opindex --delimiter
5274 With @option{-f}, use the first byte of @var{input_delim_byte} as
5275 the input fields separator (default is TAB).
5279 Do not split multi-byte characters (no-op for now).
5282 @itemx --only-delimited
5284 @opindex --only-delimited
5285 For @option{-f}, do not print lines that do not contain the field separator
5286 character. Normally, any line without a field separator is printed verbatim.
5288 @item --output-delimiter=@var{output_delim_string}
5289 @opindex --output-delimiter
5290 With @option{-f}, output fields are separated by @var{output_delim_string}.
5291 The default with @option{-f} is to use the input delimiter.
5292 When using @option{-b} or @option{-c} to select ranges of byte or
5293 character offsets (as opposed to ranges of fields),
5294 output @var{output_delim_string} between non-overlapping
5295 ranges of selected bytes.
5298 @opindex --complement
5299 This option is a @acronym{GNU} extension.
5300 Select for printing the complement of the bytes, characters or fields
5301 selected with the @option{-b}, @option{-c} or @option{-f} options.
5302 In other words, do @emph{not} print the bytes, characters or fields
5303 specified via those options. This option is useful when you have
5304 many fields and want to print all but a few of them.
5311 @node paste invocation
5312 @section @command{paste}: Merge lines of files
5315 @cindex merging files
5317 @command{paste} writes to standard output lines consisting of sequentially
5318 corresponding lines of each given file, separated by a TAB character.
5319 Standard input is used for a file name of @samp{-} or if no input files
5341 paste [@var{option}]@dots{} [@var{file}]@dots{}
5344 The program accepts the following options. Also see @ref{Common options}.
5352 Paste the lines of one file at a time rather than one line from each
5353 file. Using the above example data:
5356 $ paste -s num2 let3
5361 @item -d @var{delim-list}
5362 @itemx --delimiters=@var{delim-list}
5364 @opindex --delimiters
5365 Consecutively use the characters in @var{delim-list} instead of
5366 TAB to separate merged lines. When @var{delim-list} is
5367 exhausted, start again at its beginning. Using the above example data:
5370 $ paste -d '%_' num2 let3 num2
5381 @node join invocation
5382 @section @command{join}: Join lines on a common field
5385 @cindex common field, joining on
5387 @command{join} writes to standard output a line for each pair of input
5388 lines that have identical join fields. Synopsis:
5391 join [@var{option}]@dots{} @var{file1} @var{file2}
5394 Either @var{file1} or @var{file2} (but not both) can be @samp{-},
5395 meaning standard input. @var{file1} and @var{file2} should be
5396 sorted on the join fields.
5399 Normally, the sort order is that of the
5400 collating sequence specified by the @env{LC_COLLATE} locale. Unless
5401 the @option{-t} option is given, the sort comparison ignores blanks at
5402 the start of the join field, as in @code{sort -b}. If the
5403 @option{--ignore-case} option is given, the sort comparison ignores
5404 the case of characters in the join field, as in @code{sort -f}.
5406 The @command{sort} and @command{join} commands should use consistent
5407 locales and options if the output of @command{sort} is fed to
5408 @command{join}. You can use a command like @samp{sort -k 1b,1} to
5409 sort a file on its default join field, but if you select a non-default
5410 locale, join field, separator, or comparison options, then you should
5411 do so consistently between @command{join} and @command{sort}.
5413 If the input has no unpairable lines, a @acronym{GNU} extension is
5414 available; the sort order can be any order that considers two fields
5415 to be equal if and only if the sort comparison described above
5416 considers them to be equal. For example:
5433 @checkOrderOption{join}
5437 @item the join field is the first field in each line;
5438 @item fields in the input are separated by one or more blanks, with leading
5439 blanks on the line ignored;
5440 @item fields in the output are separated by a space;
5441 @item each output line consists of the join field, the remaining
5442 fields from @var{file1}, then the remaining fields from @var{file2}.
5445 The program accepts the following options. Also see @ref{Common options}.
5449 @item -a @var{file-number}
5451 Print a line for each unpairable line in file @var{file-number} (either
5452 @samp{1} or @samp{2}), in addition to the normal output.
5455 Fail with an error message if either input file is wrongly ordered.
5457 @item --nocheck-order
5458 Do not check that both input files are in sorted order. This is the default.
5460 @item -e @var{string}
5462 Replace those output fields that are missing in the input with
5466 @itemx --ignore-case
5468 @opindex --ignore-case
5469 Ignore differences in case when comparing keys.
5470 With this option, the lines of the input files must be ordered in the same way.
5471 Use @samp{sort -f} to produce this ordering.
5473 @item -1 @var{field}
5475 Join on field @var{field} (a positive integer) of file 1.
5477 @item -2 @var{field}
5479 Join on field @var{field} (a positive integer) of file 2.
5481 @item -j @var{field}
5482 Equivalent to @option{-1 @var{field} -2 @var{field}}.
5484 @item -o @var{field-list}
5485 Construct each output line according to the format in @var{field-list}.
5486 Each element in @var{field-list} is either the single character @samp{0} or
5487 has the form @var{m.n} where the file number, @var{m}, is @samp{1} or
5488 @samp{2} and @var{n} is a positive field number.
5490 A field specification of @samp{0} denotes the join field.
5491 In most cases, the functionality of the @samp{0} field spec
5492 may be reproduced using the explicit @var{m.n} that corresponds
5493 to the join field. However, when printing unpairable lines
5494 (using either of the @option{-a} or @option{-v} options), there is no way
5495 to specify the join field using @var{m.n} in @var{field-list}
5496 if there are unpairable lines in both files.
5497 To give @command{join} that functionality, @acronym{POSIX} invented the @samp{0}
5498 field specification notation.
5500 The elements in @var{field-list}
5501 are separated by commas or blanks.
5502 Blank separators typically need to be quoted for the shell. For
5503 example, the commands @samp{join -o 1.2,2.2} and @samp{join -o '1.2
5504 2.2'} are equivalent.
5506 All output lines---including those printed because of any -a or -v
5507 option---are subject to the specified @var{field-list}.
5510 Use character @var{char} as the input and output field separator.
5511 Treat as significant each occurrence of @var{char} in the input file.
5512 Use @samp{sort -t @var{char}}, without the @option{-b} option of
5513 @samp{sort}, to produce this ordering.
5515 @item -v @var{file-number}
5516 Print a line for each unpairable line in file @var{file-number}
5517 (either @samp{1} or @samp{2}), instead of the normal output.
5524 @node Operating on characters
5525 @chapter Operating on characters
5527 @cindex operating on characters
5529 This commands operate on individual characters.
5532 * tr invocation:: Translate, squeeze, and/or delete characters.
5533 * expand invocation:: Convert tabs to spaces.
5534 * unexpand invocation:: Convert spaces to tabs.
5539 @section @command{tr}: Translate, squeeze, and/or delete characters
5546 tr [@var{option}]@dots{} @var{set1} [@var{set2}]
5549 @command{tr} copies standard input to standard output, performing
5550 one of the following operations:
5554 translate, and optionally squeeze repeated characters in the result,
5556 squeeze repeated characters,
5560 delete characters, then squeeze repeated characters from the result.
5563 The @var{set1} and (if given) @var{set2} arguments define ordered
5564 sets of characters, referred to below as @var{set1} and @var{set2}. These
5565 sets are the characters of the input that @command{tr} operates on.
5566 The @option{--complement} (@option{-c}, @option{-C}) option replaces
5568 complement (all of the characters that are not in @var{set1}).
5570 Currently @command{tr} fully supports only single-byte characters.
5571 Eventually it will support multibyte characters; when it does, the
5572 @option{-C} option will cause it to complement the set of characters,
5573 whereas @option{-c} will cause it to complement the set of values.
5574 This distinction will matter only when some values are not characters,
5575 and this is possible only in locales using multibyte encodings when
5576 the input contains encoding errors.
5578 The program accepts the @option{--help} and @option{--version}
5579 options. @xref{Common options}. Options must precede operands.
5584 * Character sets:: Specifying sets of characters.
5585 * Translating:: Changing one set of characters to another.
5586 * Squeezing:: Squeezing repeats and deleting.
5590 @node Character sets
5591 @subsection Specifying sets of characters
5593 @cindex specifying sets of characters
5595 The format of the @var{set1} and @var{set2} arguments resembles
5596 the format of regular expressions; however, they are not regular
5597 expressions, only lists of characters. Most characters simply
5598 represent themselves in these strings, but the strings can contain
5599 the shorthands listed below, for convenience. Some of them can be
5600 used only in @var{set1} or @var{set2}, as noted below.
5604 @item Backslash escapes
5605 @cindex backslash escapes
5607 The following backslash escape sequences are recognized:
5625 The character with the value given by @var{ooo}, which is 1 to 3
5631 While a backslash followed by a character not listed above is
5632 interpreted as that character, the backslash also effectively
5633 removes any special significance, so it is useful to escape
5634 @samp{[}, @samp{]}, @samp{*}, and @samp{-}.
5639 The notation @samp{@var{m}-@var{n}} expands to all of the characters
5640 from @var{m} through @var{n}, in ascending order. @var{m} should
5641 collate before @var{n}; if it doesn't, an error results. As an example,
5642 @samp{0-9} is the same as @samp{0123456789}.
5644 @sc{gnu} @command{tr} does not support the System V syntax that uses square
5645 brackets to enclose ranges. Translations specified in that format
5646 sometimes work as expected, since the brackets are often transliterated
5647 to themselves. However, they should be avoided because they sometimes
5648 behave unexpectedly. For example, @samp{tr -d '[0-9]'} deletes brackets
5651 Many historically common and even accepted uses of ranges are not
5652 portable. For example, on @acronym{EBCDIC} hosts using the @samp{A-Z}
5653 range will not do what most would expect because @samp{A} through @samp{Z}
5654 are not contiguous as they are in @acronym{ASCII}.
5655 If you can rely on a @acronym{POSIX} compliant version of @command{tr}, then
5656 the best way to work around this is to use character classes (see below).
5657 Otherwise, it is most portable (and most ugly) to enumerate the members
5660 @item Repeated characters
5661 @cindex repeated characters
5663 The notation @samp{[@var{c}*@var{n}]} in @var{set2} expands to @var{n}
5664 copies of character @var{c}. Thus, @samp{[y*6]} is the same as
5665 @samp{yyyyyy}. The notation @samp{[@var{c}*]} in @var{string2} expands
5666 to as many copies of @var{c} as are needed to make @var{set2} as long as
5667 @var{set1}. If @var{n} begins with @samp{0}, it is interpreted in
5668 octal, otherwise in decimal.
5670 @item Character classes
5671 @cindex character classes
5673 The notation @samp{[:@var{class}:]} expands to all of the characters in
5674 the (predefined) class @var{class}. The characters expand in no
5675 particular order, except for the @code{upper} and @code{lower} classes,
5676 which expand in ascending order. When the @option{--delete} (@option{-d})
5677 and @option{--squeeze-repeats} (@option{-s}) options are both given, any
5678 character class can be used in @var{set2}. Otherwise, only the
5679 character classes @code{lower} and @code{upper} are accepted in
5680 @var{set2}, and then only if the corresponding character class
5681 (@code{upper} and @code{lower}, respectively) is specified in the same
5682 relative position in @var{set1}. Doing this specifies case conversion.
5683 The class names are given below; an error results when an invalid class
5695 Horizontal whitespace.
5704 Printable characters, not including space.
5710 Printable characters, including space.
5713 Punctuation characters.
5716 Horizontal or vertical whitespace.
5725 @item Equivalence classes
5726 @cindex equivalence classes
5728 The syntax @samp{[=@var{c}=]} expands to all of the characters that are
5729 equivalent to @var{c}, in no particular order. Equivalence classes are
5730 a relatively recent invention intended to support non-English alphabets.
5731 But there seems to be no standard way to define them or determine their
5732 contents. Therefore, they are not fully implemented in @sc{gnu} @command{tr};
5733 each character's equivalence class consists only of that character,
5734 which is of no particular use.
5740 @subsection Translating
5742 @cindex translating characters
5744 @command{tr} performs translation when @var{set1} and @var{set2} are
5745 both given and the @option{--delete} (@option{-d}) option is not given.
5746 @command{tr} translates each character of its input that is in @var{set1}
5747 to the corresponding character in @var{set2}. Characters not in
5748 @var{set1} are passed through unchanged. When a character appears more
5749 than once in @var{set1} and the corresponding characters in @var{set2}
5750 are not all the same, only the final one is used. For example, these
5751 two commands are equivalent:
5758 A common use of @command{tr} is to convert lowercase characters to
5759 uppercase. This can be done in many ways. Here are three of them:
5762 tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
5764 tr '[:lower:]' '[:upper:]'
5768 But note that using ranges like @code{a-z} above is not portable.
5770 When @command{tr} is performing translation, @var{set1} and @var{set2}
5771 typically have the same length. If @var{set1} is shorter than
5772 @var{set2}, the extra characters at the end of @var{set2} are ignored.
5774 On the other hand, making @var{set1} longer than @var{set2} is not
5775 portable; @acronym{POSIX} says that the result is undefined. In this situation,
5776 BSD @command{tr} pads @var{set2} to the length of @var{set1} by repeating
5777 the last character of @var{set2} as many times as necessary. System V
5778 @command{tr} truncates @var{set1} to the length of @var{set2}.
5780 By default, @sc{gnu} @command{tr} handles this case like BSD @command{tr}.
5781 When the @option{--truncate-set1} (@option{-t}) option is given,
5782 @sc{gnu} @command{tr} handles this case like the System V @command{tr}
5783 instead. This option is ignored for operations other than translation.
5785 Acting like System V @command{tr} in this case breaks the relatively common
5789 tr -cs A-Za-z0-9 '\012'
5793 because it converts only zero bytes (the first element in the
5794 complement of @var{set1}), rather than all non-alphanumerics, to
5798 By the way, the above idiom is not portable because it uses ranges, and
5799 it assumes that the octal code for newline is 012.
5800 Assuming a @acronym{POSIX} compliant @command{tr}, here is a better way to write it:
5803 tr -cs '[:alnum:]' '[\n*]'
5808 @subsection Squeezing repeats and deleting
5810 @cindex squeezing repeat characters
5811 @cindex deleting characters
5813 When given just the @option{--delete} (@option{-d}) option, @command{tr}
5814 removes any input characters that are in @var{set1}.
5816 When given just the @option{--squeeze-repeats} (@option{-s}) option,
5817 @command{tr} replaces each input sequence of a repeated character that
5818 is in @var{set1} with a single occurrence of that character.
5820 When given both @option{--delete} and @option{--squeeze-repeats}, @command{tr}
5821 first performs any deletions using @var{set1}, then squeezes repeats
5822 from any remaining characters using @var{set2}.
5824 The @option{--squeeze-repeats} option may also be used when translating,
5825 in which case @command{tr} first performs translation, then squeezes
5826 repeats from any remaining characters using @var{set2}.
5828 Here are some examples to illustrate various combinations of options:
5833 Remove all zero bytes:
5840 Put all words on lines by themselves. This converts all
5841 non-alphanumeric characters to newlines, then squeezes each string
5842 of repeated newlines into a single newline:
5845 tr -cs '[:alnum:]' '[\n*]'
5849 Convert each sequence of repeated newlines to a single newline:
5856 Find doubled occurrences of words in a document.
5857 @c Separate the following two "the"s, so typo checkers don't complain.
5858 For example, people often write ``the @w{}the'' with the repeated words
5859 separated by a newline. The Bourne shell script below works first
5860 by converting each sequence of punctuation and blank characters to a
5861 single newline. That puts each ``word'' on a line by itself.
5862 Next it maps all uppercase characters to lower case, and finally it
5863 runs @command{uniq} with the @option{-d} option to print out only the words
5869 | tr -s '[:punct:][:blank:]' '[\n*]' \
5870 | tr '[:upper:]' '[:lower:]' \
5875 Deleting a small set of characters is usually straightforward. For example,
5876 to remove all @samp{a}s, @samp{x}s, and @samp{M}s you would do this:
5882 However, when @samp{-} is one of those characters, it can be tricky because
5883 @samp{-} has special meanings. Performing the same task as above but also
5884 removing all @samp{-} characters, we might try @code{tr -d -axM}, but
5885 that would fail because @command{tr} would try to interpret @option{-a} as
5886 a command-line option. Alternatively, we could try putting the hyphen
5887 inside the string, @code{tr -d a-xM}, but that wouldn't work either because
5888 it would make @command{tr} interpret @code{a-x} as the range of characters
5889 @samp{a}@dots{}@samp{x} rather than the three.
5890 One way to solve the problem is to put the hyphen at the end of the list
5897 Or you can use @samp{--} to terminate option processing:
5903 More generally, use the character class notation @code{[=c=]}
5904 with @samp{-} (or any other character) in place of the @samp{c}:
5910 Note how single quotes are used in the above example to protect the
5911 square brackets from interpretation by a shell.
5916 @node expand invocation
5917 @section @command{expand}: Convert tabs to spaces
5920 @cindex tabs to spaces, converting
5921 @cindex converting tabs to spaces
5923 @command{expand} writes the contents of each given @var{file}, or standard
5924 input if none are given or for a @var{file} of @samp{-}, to standard
5925 output, with tab characters converted to the appropriate number of
5929 expand [@var{option}]@dots{} [@var{file}]@dots{}
5932 By default, @command{expand} converts all tabs to spaces. It preserves
5933 backspace characters in the output; they decrement the column count for
5934 tab calculations. The default action is equivalent to @option{-t 8} (set
5935 tabs every 8 columns).
5937 The program accepts the following options. Also see @ref{Common options}.
5941 @item -t @var{tab1}[,@var{tab2}]@dots{}
5942 @itemx --tabs=@var{tab1}[,@var{tab2}]@dots{}
5945 @cindex tab stops, setting
5946 If only one tab stop is given, set the tabs @var{tab1} spaces apart
5947 (default is 8). Otherwise, set the tabs at columns @var{tab1},
5948 @var{tab2}, @dots{} (numbered from 0), and replace any tabs beyond the
5949 last tab stop given with single spaces. Tab stops can be separated by
5950 blanks as well as by commas.
5952 For compatibility, GNU @command{expand} also accepts the obsolete
5953 option syntax, @option{-@var{t1}[,@var{t2}]@dots{}}. New scripts
5954 should use @option{-t @var{t1}[,@var{t2}]@dots{}} instead.
5960 @cindex initial tabs, converting
5961 Only convert initial tabs (those that precede all non-space or non-tab
5962 characters) on each line to spaces.
5969 @node unexpand invocation
5970 @section @command{unexpand}: Convert spaces to tabs
5974 @command{unexpand} writes the contents of each given @var{file}, or
5975 standard input if none are given or for a @var{file} of @samp{-}, to
5976 standard output, converting blanks at the beginning of each line into
5977 as many tab characters as needed. In the default @acronym{POSIX}
5978 locale, a @dfn{blank} is a space or a tab; other locales may specify
5979 additional blank characters. Synopsis:
5982 unexpand [@var{option}]@dots{} [@var{file}]@dots{}
5985 By default, @command{unexpand} converts only initial blanks (those
5986 that precede all non-blank characters) on each line. It
5987 preserves backspace characters in the output; they decrement the column
5988 count for tab calculations. By default, tabs are set at every 8th
5991 The program accepts the following options. Also see @ref{Common options}.
5995 @item -t @var{tab1}[,@var{tab2}]@dots{}
5996 @itemx --tabs=@var{tab1}[,@var{tab2}]@dots{}
5999 If only one tab stop is given, set the tabs @var{tab1} columns apart
6000 instead of the default 8. Otherwise, set the tabs at columns
6001 @var{tab1}, @var{tab2}, @dots{} (numbered from 0), and leave blanks
6002 beyond the tab stops given unchanged. Tab stops can be separated by
6003 blanks as well as by commas. This option implies the @option{-a} option.
6005 For compatibility, GNU @command{unexpand} supports the obsolete option syntax,
6006 @option{-@var{tab1}[,@var{tab2}]@dots{}}, where tab stops must be
6007 separated by commas. (Unlike @option{-t}, this obsolete option does
6008 not imply @option{-a}.) New scripts should use @option{--first-only -t
6009 @var{tab1}[,@var{tab2}]@dots{}} instead.
6015 Also convert all sequences of two or more blanks just before a tab stop,
6016 even if they occur after non-blank characters in a line.
6023 @node Directory listing
6024 @chapter Directory listing
6026 This chapter describes the @command{ls} command and its variants @command{dir}
6027 and @command{vdir}, which list information about files.
6030 * ls invocation:: List directory contents.
6031 * dir invocation:: Briefly ls.
6032 * vdir invocation:: Verbosely ls.
6033 * dircolors invocation:: Color setup for ls, etc.
6038 @section @command{ls}: List directory contents
6041 @cindex directory listing
6043 The @command{ls} program lists information about files (of any type,
6044 including directories). Options and file arguments can be intermixed
6045 arbitrarily, as usual.
6047 For non-option command-line arguments that are directories, by default
6048 @command{ls} lists the contents of directories, not recursively, and
6049 omitting files with names beginning with @samp{.}. For other non-option
6050 arguments, by default @command{ls} lists just the file name. If no
6051 non-option argument is specified, @command{ls} operates on the current
6052 directory, acting as if it had been invoked with a single argument of @samp{.}.
6055 By default, the output is sorted alphabetically, according to the locale
6056 settings in effect.@footnote{If you use a non-@acronym{POSIX}
6057 locale (e.g., by setting @env{LC_ALL} to @samp{en_US}), then @command{ls} may
6058 produce output that is sorted differently than you're accustomed to.
6059 In that case, set the @env{LC_ALL} environment variable to @samp{C}.}
6060 If standard output is
6061 a terminal, the output is in columns (sorted vertically) and control
6062 characters are output as question marks; otherwise, the output is listed
6063 one per line and control characters are output as-is.
6065 Because @command{ls} is such a fundamental program, it has accumulated many
6066 options over the years. They are described in the subsections below;
6067 within each section, options are listed alphabetically (ignoring case).
6068 The division of options into the subsections is not absolute, since some
6069 options affect more than one aspect of @command{ls}'s operation.
6071 @cindex exit status of @command{ls}
6076 1 minor problems (e.g., failure to access a file or directory not
6077 specified as a command line argument. This happens when listing a
6078 directory in which entries are actively being removed or renamed.)
6079 2 serious trouble (e.g., memory exhausted, invalid option or failure
6080 to access file or directory specified as a command line argument)
6083 Also see @ref{Common options}.
6086 * Which files are listed::
6087 * What information is listed::
6088 * Sorting the output::
6089 * More details about version sort::
6090 * General output formatting::
6091 * Formatting file timestamps::
6092 * Formatting the file names::
6096 @node Which files are listed
6097 @subsection Which files are listed
6099 These options determine which files @command{ls} lists information for.
6100 By default, @command{ls} lists files and the contents of any
6101 directories on the command line, except that in directories it ignores
6102 files whose names start with @samp{.}.
6110 In directories, do not ignore file names that start with @samp{.}.
6115 @opindex --almost-all
6116 In directories, do not ignore all file names that start with @samp{.};
6117 ignore only @file{.} and @file{..}. The @option{--all} (@option{-a})
6118 option overrides this option.
6121 @itemx --ignore-backups
6123 @opindex --ignore-backups
6124 @cindex backup files, ignoring
6125 In directories, ignore files that end with @samp{~}. This option is
6126 equivalent to @samp{--ignore='*~' --ignore='.*~'}.
6131 @opindex --directory
6132 List just the names of directories, as with other types of files, rather
6133 than listing their contents.
6134 @c The following sentence is the same as the one for -F.
6135 Do not follow symbolic links listed on the
6136 command line unless the @option{--dereference-command-line} (@option{-H}),
6137 @option{--dereference} (@option{-L}), or
6138 @option{--dereference-command-line-symlink-to-dir} options are specified.
6141 @itemx --dereference-command-line
6143 @opindex --dereference-command-line
6144 @cindex symbolic links, dereferencing
6145 If a command line argument specifies a symbolic link, show information
6146 for the file the link references rather than for the link itself.
6148 @itemx --dereference-command-line-symlink-to-dir
6149 @opindex --dereference-command-line-symlink-to-dir
6150 @cindex symbolic links, dereferencing
6151 Do not dereference symbolic links, with one exception:
6152 if a command line argument specifies a symbolic link that refers to
6153 a directory, show information for that directory rather than for the
6155 This is the default behavior when no other dereferencing-related
6156 option has been specified (@option{--classify} (@option{-F}),
6157 @option{--directory} (@option{-d}),
6159 @option{--dereference} (@option{-L}), or
6160 @option{--dereference-command-line} (@option{-H})).
6162 @item --group-directories-first
6163 @opindex --group-directories-first
6164 Group all the directories before the files and then sort the
6165 directories and the files separately using the selected sort key
6166 (see --sort option).
6167 That is, this option specifies a primary sort key,
6168 and the --sort option specifies a secondary key.
6169 However, any use of @option{--sort=none}
6170 (@option{-U}) disables this option altogether.
6172 @item --hide=PATTERN
6173 @opindex --hide=@var{pattern}
6174 In directories, ignore files whose names match the shell pattern
6175 @var{pattern}, unless the @option{--all} (@option{-a}) or
6176 @option{--almost-all} (@option{-A}) is also given. This
6177 option acts like @option{--ignore=@var{pattern}} except that it has no
6178 effect if @option{--all} (@option{-a}) or @option{--almost-all}
6179 (@option{-A}) is also given.
6181 This option can be useful in shell aliases. For example, if
6182 @command{lx} is an alias for @samp{ls --hide='*~'} and @command{ly} is
6183 an alias for @samp{ls --ignore='*~'}, then the command @samp{lx -A}
6184 lists the file @file{README~} even though @samp{ly -A} would not.
6186 @item -I @var{pattern}
6187 @itemx --ignore=@var{pattern}
6189 @opindex --ignore=@var{pattern}
6190 In directories, ignore files whose names match the shell pattern
6191 (not regular expression) @var{pattern}. As
6192 in the shell, an initial @samp{.} in a file name does not match a
6193 wildcard at the start of @var{pattern}. Sometimes it is useful
6194 to give this option several times. For example,
6197 $ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*'
6200 The first option ignores names of length 3 or more that start with @samp{.},
6201 the second ignores all two-character names that start with @samp{.}
6202 except @samp{..}, and the third ignores names that start with @samp{#}.
6205 @itemx --dereference
6207 @opindex --dereference
6208 @cindex symbolic links, dereferencing
6209 When showing file information for a symbolic link, show information
6210 for the file the link references rather than the link itself.
6211 However, even with this option, @command{ls} still prints the name
6212 of the link itself, not the name of the file that the link points to.
6217 @opindex --recursive
6218 @cindex recursive directory listing
6219 @cindex directory listing, recursive
6220 List the contents of all directories recursively.
6225 @node What information is listed
6226 @subsection What information is listed
6228 These options affect the information that @command{ls} displays. By
6229 default, only file names are shown.
6235 @cindex hurd, author, printing
6236 List each file's author when producing long format directory listings.
6237 In GNU/Hurd, file authors can differ from their owners, but in other
6238 operating systems the two are the same.
6244 @cindex dired Emacs mode support
6245 With the long listing (@option{-l}) format, print an additional line after
6249 //DIRED// @var{beg1} @var{end1} @var{beg2} @var{end2} @dots{}
6253 The @var{begN} and @var{endN} are unsigned integers that record the
6254 byte position of the beginning and end of each file name in the output.
6255 This makes it easy for Emacs to find the names, even when they contain
6256 unusual characters such as space or newline, without fancy searching.
6258 If directories are being listed recursively (@option{-R}), output a similar
6259 line with offsets for each subdirectory name:
6262 //SUBDIRED// @var{beg1} @var{end1} @dots{}
6265 Finally, output a line of the form:
6268 //DIRED-OPTIONS// --quoting-style=@var{word}
6272 where @var{word} is the quoting style (@pxref{Formatting the file names}).
6274 Here is an actual example:
6277 $ mkdir -p a/sub/deeper a/sub2
6279 $ touch a/sub/deeper/file
6280 $ ls -gloRF --dired a
6283 -rw-r--r-- 1 0 Jun 10 12:27 f1
6284 -rw-r--r-- 1 0 Jun 10 12:27 f2
6285 drwxr-xr-x 3 4096 Jun 10 12:27 sub/
6286 drwxr-xr-x 2 4096 Jun 10 12:27 sub2/
6290 drwxr-xr-x 2 4096 Jun 10 12:27 deeper/
6294 -rw-r--r-- 1 0 Jun 10 12:27 file
6298 //DIRED// 48 50 84 86 120 123 158 162 217 223 282 286
6299 //SUBDIRED// 2 3 167 172 228 240 290 296
6300 //DIRED-OPTIONS// --quoting-style=literal
6303 Note that the pairs of offsets on the @samp{//DIRED//} line above delimit
6304 these names: @file{f1}, @file{f2}, @file{sub}, @file{sub2}, @file{deeper},
6306 The offsets on the @samp{//SUBDIRED//} line delimit the following
6307 directory names: @file{a}, @file{a/sub}, @file{a/sub/deeper}, @file{a/sub2}.
6309 Here is an example of how to extract the fifth entry name, @samp{deeper},
6310 corresponding to the pair of offsets, 222 and 228:
6313 $ ls -gloRF --dired a > out
6314 $ dd bs=1 skip=222 count=6 < out 2>/dev/null; echo
6318 Note that although the listing above includes a trailing slash
6319 for the @samp{deeper} entry, the offsets select the name without
6320 the trailing slash. However, if you invoke @command{ls} with @option{--dired}
6321 along with an option like @option{--escape} (aka @option{-b}) and operate
6322 on a file whose name contains special characters, notice that the backslash
6327 $ ls -blog --dired 'a b'
6328 -rw-r--r-- 1 0 Jun 10 12:28 a\ b
6330 //DIRED-OPTIONS// --quoting-style=escape
6333 If you use a quoting style that adds quote marks
6334 (e.g., @option{--quoting-style=c}), then the offsets include the quote marks.
6335 So beware that the user may select the quoting style via the environment
6336 variable @env{QUOTING_STYLE}. Hence, applications using @option{--dired}
6337 should either specify an explicit @option{--quoting-style=literal} option
6338 (aka @option{-N} or @option{--literal}) on the command line, or else be
6339 prepared to parse the escaped names.
6342 @opindex --full-time
6343 Produce long format directory listings, and list times in full. It is
6344 equivalent to using @option{--format=long} with
6345 @option{--time-style=full-iso} (@pxref{Formatting file timestamps}).
6349 Produce long format directory listings, but don't display owner information.
6355 Inhibit display of group information in a long format directory listing.
6356 (This is the default in some non-@sc{gnu} versions of @command{ls}, so we
6357 provide this option for compatibility.)
6365 @cindex inode number, printing
6366 Print the inode number (also called the file serial number and index
6367 number) of each file to the left of the file name. (This number
6368 uniquely identifies each file within a particular file system.)
6371 @itemx --format=long
6372 @itemx --format=verbose
6375 @opindex long ls @r{format}
6376 @opindex verbose ls @r{format}
6377 In addition to the name of each file, print the file type, file mode bits,
6378 number of hard links, owner name, group name, size, and
6379 timestamp (@pxref{Formatting file timestamps}), normally
6380 the modification time. Print question marks for information that
6381 cannot be determined.
6383 Normally the size is printed as a byte count without punctuation, but
6384 this can be overridden (@pxref{Block size}). For example, @option{-h}
6385 prints an abbreviated, human-readable count, and
6386 @samp{--block-size="'1"} prints a byte count with the thousands
6387 separator of the current locale.
6389 For each directory that is listed, preface the files with a line
6390 @samp{total @var{blocks}}, where @var{blocks} is the total disk allocation
6391 for all files in that directory. The block size currently defaults to 1024
6392 bytes, but this can be overridden (@pxref{Block size}).
6393 The @var{blocks} computed counts each hard link separately;
6394 this is arguably a deficiency.
6396 The file type is one of the following characters:
6398 @c The commented-out entries are ones we're not sure about.
6406 character special file
6408 high performance (``contiguous data'') file
6412 door (Solaris 2.5 and up)
6414 @c semaphore, if this is a distinct file type
6418 @c multiplexed file (7th edition Unix; obsolete)
6420 off-line (``migrated'') file (Cray DMF)
6422 network special file (HP-UX)
6426 port (Solaris 10 and up)
6428 @c message queue, if this is a distinct file type
6432 @c shared memory object, if this is a distinct file type
6434 @c typed memory object, if this is a distinct file type
6436 @c whiteout (4.4BSD; not implemented)
6438 some other file type
6441 @cindex permissions, output by @command{ls}
6442 The file mode bits listed are similar to symbolic mode specifications
6443 (@pxref{Symbolic Modes}). But @command{ls} combines multiple bits into the
6444 third character of each set of permissions as follows:
6448 If the set-user-ID or set-group-ID bit and the corresponding executable bit
6452 If the set-user-ID or set-group-ID bit is set but the corresponding
6453 executable bit is not set.
6456 If the restricted deletion flag or sticky bit, and the
6457 other-executable bit, are both set. The restricted deletion flag is
6458 another name for the sticky bit. @xref{Mode Structure}.
6461 If the restricted deletion flag or sticky bit is set but the
6462 other-executable bit is not set.
6465 If the executable bit is set and none of the above apply.
6471 Following the file mode bits is a single character that specifies
6472 whether an alternate access method such as an access control list
6473 applies to the file. When the character following the file mode bits is a
6474 space, there is no alternate access method. When it is a printing
6475 character, then there is such a method.
6477 GNU @command{ls} uses a @samp{.} character to indicate a file
6478 with an SELinux security context, but no other alternate access method.
6480 A file with any other combination of alternate access methods
6481 is marked with a @samp{+} character.
6484 @itemx --numeric-uid-gid
6486 @opindex --numeric-uid-gid
6487 @cindex numeric uid and gid
6488 @cindex numeric user and group IDs
6489 Produce long format directory listings, but
6490 display numeric user and group IDs instead of the owner and group names.
6494 Produce long format directory listings, but don't display group information.
6495 It is equivalent to using @option{--format=long} with @option{--no-group} .
6501 @cindex disk allocation
6502 @cindex size of files, reporting
6503 Print the disk allocation of each file to the left of the file name.
6504 This is the amount of disk space used by the file, which is usually a
6505 bit more than the file's size, but it can be less if the file has holes.
6507 Normally the disk allocation is printed in units of
6508 1024 bytes, but this can be overridden (@pxref{Block size}).
6510 @cindex NFS mounts from BSD to HP-UX
6511 For files that are NFS-mounted from an HP-UX system to a BSD system,
6512 this option reports sizes that are half the correct values. On HP-UX
6513 systems, it reports sizes that are twice the correct values for files
6514 that are NFS-mounted from BSD systems. This is due to a flaw in HP-UX;
6515 it also affects the HP-UX @command{ls} program.
6522 @node Sorting the output
6523 @subsection Sorting the output
6525 @cindex sorting @command{ls} output
6526 These options change the order in which @command{ls} sorts the information
6527 it outputs. By default, sorting is done by character code
6528 (e.g., @acronym{ASCII} order).
6534 @itemx --time=status
6537 @opindex ctime@r{, printing or sorting by}
6538 @opindex status time@r{, printing or sorting by}
6539 @opindex use time@r{, printing or sorting files by}
6540 If the long listing format (e.g., @option{-l}, @option{-o}) is being used,
6541 print the status change time (the @samp{ctime} in the inode) instead of
6542 the modification time.
6543 When explicitly sorting by time (@option{--sort=time} or @option{-t})
6544 or when not using a long listing format,
6545 sort according to the status change time.
6549 @cindex unsorted directory listing
6550 @cindex directory order, listing by
6551 Primarily, like @option{-U}---do not sort; list the files in whatever
6552 order they are stored in the directory. But also enable @option{-a} (list
6553 all files) and disable @option{-l}, @option{--color}, and @option{-s} (if they
6554 were specified before the @option{-f}).
6560 @cindex reverse sorting
6561 Reverse whatever the sorting method is---e.g., list files in reverse
6562 alphabetical order, youngest first, smallest first, or whatever.
6568 @opindex size of files@r{, sorting files by}
6569 Sort by file size, largest first.
6575 @opindex modification time@r{, sorting files by}
6576 Sort by modification time (the @samp{mtime} in the inode), newest first.
6580 @itemx --time=access
6584 @opindex use time@r{, printing or sorting files by}
6585 @opindex atime@r{, printing or sorting files by}
6586 @opindex access time@r{, printing or sorting files by}
6587 If the long listing format (e.g., @option{--format=long}) is being used,
6588 print the last access time (the @samp{atime} in the inode).
6589 When explicitly sorting by time (@option{--sort=time} or @option{-t})
6590 or when not using a long listing format, sort according to the access time.
6596 @opindex none@r{, sorting option for @command{ls}}
6597 Do not sort; list the files in whatever order they are
6598 stored in the directory. (Do not do any of the other unrelated things
6599 that @option{-f} does.) This is especially useful when listing very large
6600 directories, since not doing any sorting can be noticeably faster.
6603 @itemx --sort=version
6606 @opindex version@r{, sorting option for @command{ls}}
6607 Sort by version name and number, lowest first. It behaves like a default
6608 sort, except that each sequence of decimal digits is treated numerically
6609 as an index/version number. (@xref{More details about version sort}.)
6612 @itemx --sort=extension
6615 @opindex extension@r{, sorting files by}
6616 Sort directory contents alphabetically by file extension (characters
6617 after the last @samp{.}); files with no extension are sorted first.
6622 @node More details about version sort
6623 @subsection More details about version sort
6625 The version sort takes into account the fact that file names frequently include
6626 indices or version numbers. Standard sorting functions usually do not produce
6627 the ordering that people expect because comparisons are made on a
6628 character-by-character basis. The version
6629 sort addresses this problem, and is especially useful when browsing
6630 directories that contain many files with indices/version numbers in their
6635 foo.zml-1.gz foo.zml-1.gz
6636 foo.zml-100.gz foo.zml-2.gz
6637 foo.zml-12.gz foo.zml-6.gz
6638 foo.zml-13.gz foo.zml-12.gz
6639 foo.zml-2.gz foo.zml-13.gz
6640 foo.zml-25.gz foo.zml-25.gz
6641 foo.zml-6.gz foo.zml-100.gz
6644 Note also that numeric parts with leading zeros are considered as
6649 abc-1.007.tgz abc-1.007.tgz
6650 abc-1.012b.tgz abc-1.01a.tgz
6651 abc-1.01a.tgz abc-1.012b.tgz
6654 This functionality is implemented using the @code{strverscmp} function.
6655 @xref{String/Array Comparison, , , libc, The GNU C Library Reference Manual}.
6656 One result of that implementation decision is that @code{ls -v} does not
6657 use the locale category, @env{LC_COLLATE}. As a result, non-numeric prefixes
6658 are sorted as if @env{LC_COLLATE} were set to @code{C}.
6660 @node General output formatting
6661 @subsection General output formatting
6663 These options affect the appearance of the overall output.
6668 @itemx --format=single-column
6671 @opindex single-column @r{output of files}
6672 List one file per line. This is the default for @command{ls} when standard
6673 output is not a terminal.
6676 @itemx --format=vertical
6679 @opindex vertical @r{sorted files in columns}
6680 List files in columns, sorted vertically. This is the default for
6681 @command{ls} if standard output is a terminal. It is always the default
6682 for the @command{dir} program.
6683 @sc{gnu} @command{ls} uses variable width columns to display as many files as
6684 possible in the fewest lines.
6686 @item --color [=@var{when}]
6688 @cindex color, distinguishing file types with
6689 Specify whether to use color for distinguishing file types. @var{when}
6690 may be omitted, or one of:
6693 @vindex none @r{color option}
6694 - Do not use color at all. This is the default.
6696 @vindex auto @r{color option}
6697 @cindex terminal, using color iff
6698 - Only use color if standard output is a terminal.
6700 @vindex always @r{color option}
6703 Specifying @option{--color} and no @var{when} is equivalent to
6704 @option{--color=always}.
6705 Piping a colorized listing through a pager like @command{more} or
6706 @command{less} usually produces unreadable results. However, using
6707 @code{more -f} does seem to work.
6711 @itemx --indicator-style=classify
6714 @opindex --indicator-style
6715 @cindex file type and executables, marking
6716 @cindex executables and file type, marking
6717 Append a character to each file name indicating the file type. Also,
6718 for regular files that are executable, append @samp{*}. The file type
6719 indicators are @samp{/} for directories, @samp{@@} for symbolic links,
6720 @samp{|} for FIFOs, @samp{=} for sockets, @samp{>} for doors,
6721 and nothing for regular files.
6722 @c The following sentence is the same as the one for -d.
6723 Do not follow symbolic links listed on the
6724 command line unless the @option{--dereference-command-line} (@option{-H}),
6725 @option{--dereference} (@option{-L}), or
6726 @option{--dereference-command-line-symlink-to-dir} options are specified.
6729 @itemx --indicator-style=file-type
6730 @opindex --file-type
6731 @opindex --indicator-style
6732 @cindex file type, marking
6733 Append a character to each file name indicating the file type. This is
6734 like @option{-F}, except that executables are not marked.
6736 @item --indicator-style=@var{word}
6737 @opindex --indicator-style
6738 Append a character indicator with style @var{word} to entry names,
6743 Do not append any character indicator; this is the default.
6745 Append @samp{/} for directories. This is the same as the @option{-p}
6748 Append @samp{/} for directories, @samp{@@} for symbolic links, @samp{|}
6749 for FIFOs, @samp{=} for sockets, and nothing for regular files. This is
6750 the same as the @option{--file-type} option.
6752 Append @samp{*} for executable regular files, otherwise behave as for
6753 @samp{file-type}. This is the same as the @option{-F} or
6754 @option{--classify} option.
6759 Print file sizes in 1024-byte blocks, overriding the default block
6760 size (@pxref{Block size}).
6761 This option is equivalent to @option{--block-size=1K}.
6764 @itemx --format=commas
6767 @opindex commas@r{, outputting between files}
6768 List files horizontally, with as many as will fit on each line,
6769 separated by @samp{, } (a comma and a space).
6772 @itemx --indicator-style=slash
6774 @opindex --indicator-style
6775 @cindex file type, marking
6776 Append a @samp{/} to directory names.
6779 @itemx --format=across
6780 @itemx --format=horizontal
6783 @opindex across@r{, listing files}
6784 @opindex horizontal@r{, listing files}
6785 List the files in columns, sorted horizontally.
6788 @itemx --tabsize=@var{cols}
6791 Assume that each tab stop is @var{cols} columns wide. The default is 8.
6792 @command{ls} uses tabs where possible in the output, for efficiency. If
6793 @var{cols} is zero, do not use tabs at all.
6795 @c FIXME: remove in 2009, if Apple Terminal has been fixed for long enough.
6796 Some terminal emulators (at least Apple Terminal 1.5 (133) from Mac OS X 10.4.8)
6797 do not properly align columns to the right of a TAB following a
6798 non-@acronym{ASCII} byte. If you use such a terminal emulator, use the
6799 @option{-T0} option or put @code{TABSIZE=0} in your environment to tell
6800 @command{ls} to align using spaces, not tabs.
6803 @itemx --width=@var{cols}
6807 Assume the screen is @var{cols} columns wide. The default is taken
6808 from the terminal settings if possible; otherwise the environment
6809 variable @env{COLUMNS} is used if it is set; otherwise the default
6815 @node Formatting file timestamps
6816 @subsection Formatting file timestamps
6818 By default, file timestamps are listed in abbreviated form. Most
6819 locales use a timestamp like @samp{2002-03-30 23:45}. However, the
6820 default @acronym{POSIX} locale uses a date like @samp{Mar 30@ @ 2002}
6821 for non-recent timestamps, and a date-without-year and time like
6822 @samp{Mar 30 23:45} for recent timestamps.
6824 A timestamp is considered to be @dfn{recent} if it is less than six
6825 months old, and is not dated in the future. If a timestamp dated
6826 today is not listed in recent form, the timestamp is in the future,
6827 which means you probably have clock skew problems which may break
6828 programs like @command{make} that rely on file timestamps.
6831 Time stamps are listed according to the time zone rules specified by
6832 the @env{TZ} environment variable, or by the system default rules if
6833 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
6834 with @env{TZ}, libc, The GNU C Library Reference Manual}.
6836 The following option changes how file timestamps are printed.
6839 @item --time-style=@var{style}
6840 @opindex --time-style
6842 List timestamps in style @var{style}. The @var{style} should
6843 be one of the following:
6848 List timestamps using @var{format}, where @var{format} is interpreted
6849 like the format argument of @command{date} (@pxref{date invocation}).
6850 For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes
6851 @command{ls} to list timestamps like @samp{2002-03-30 23:45:56}. As
6852 with @command{date}, @var{format}'s interpretation is affected by the
6853 @env{LC_TIME} locale category.
6855 If @var{format} contains two format strings separated by a newline,
6856 the former is used for non-recent files and the latter for recent
6857 files; if you want output columns to line up, you may need to insert
6858 spaces in one of the two formats.
6861 List timestamps in full using @acronym{ISO} 8601 date, time, and time zone
6862 format with nanosecond precision, e.g., @samp{2002-03-30
6863 23:45:56.477817180 -0700}. This style is equivalent to
6864 @samp{+%Y-%m-%d %H:%M:%S.%N %z}.
6866 This is useful because the time output includes all the information that
6867 is available from the operating system. For example, this can help
6868 explain @command{make}'s behavior, since @acronym{GNU} @command{make}
6869 uses the full timestamp to determine whether a file is out of date.
6872 List @acronym{ISO} 8601 date and time in minutes, e.g.,
6873 @samp{2002-03-30 23:45}. These timestamps are shorter than
6874 @samp{full-iso} timestamps, and are usually good enough for everyday
6875 work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}.
6878 List @acronym{ISO} 8601 dates for non-recent timestamps (e.g.,
6879 @samp{2002-03-30@ }), and @acronym{ISO} 8601 month, day, hour, and
6880 minute for recent timestamps (e.g., @samp{03-30 23:45}). These
6881 timestamps are uglier than @samp{long-iso} timestamps, but they carry
6882 nearly the same information in a smaller space and their brevity helps
6883 @command{ls} output fit within traditional 80-column output lines.
6884 The following two @command{ls} invocations are equivalent:
6889 ls -l --time-style="+%Y-%m-%d $newline%m-%d %H:%M"
6890 ls -l --time-style="iso"
6895 List timestamps in a locale-dependent form. For example, a Finnish
6896 locale might list non-recent timestamps like @samp{maalis 30@ @ 2002}
6897 and recent timestamps like @samp{maalis 30 23:45}. Locale-dependent
6898 timestamps typically consume more space than @samp{iso} timestamps and
6899 are harder for programs to parse because locale conventions vary so
6900 widely, but they are easier for many people to read.
6902 The @env{LC_TIME} locale category specifies the timestamp format. The
6903 default @acronym{POSIX} locale uses timestamps like @samp{Mar 30@
6904 @ 2002} and @samp{Mar 30 23:45}; in this locale, the following two
6905 @command{ls} invocations are equivalent:
6910 ls -l --time-style="+%b %e %Y$newline%b %e %H:%M"
6911 ls -l --time-style="locale"
6914 Other locales behave differently. For example, in a German locale,
6915 @option{--time-style="locale"} might be equivalent to
6916 @option{--time-style="+%e. %b %Y $newline%e. %b %H:%M"}
6917 and might generate timestamps like @samp{30. M@"ar 2002@ } and
6918 @samp{30. M@"ar 23:45}.
6920 @item posix-@var{style}
6922 List @acronym{POSIX}-locale timestamps if the @env{LC_TIME} locale
6923 category is @acronym{POSIX}, @var{style} timestamps otherwise. For
6924 example, the @samp{posix-long-iso} style lists
6925 timestamps like @samp{Mar 30@ @ 2002} and @samp{Mar 30 23:45} when in
6926 the @acronym{POSIX} locale, and like @samp{2002-03-30 23:45} otherwise.
6931 You can specify the default value of the @option{--time-style} option
6932 with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set
6933 the default style is @samp{locale}. @acronym{GNU} Emacs 21.3 and
6934 later use the @option{--dired} option and therefore can parse any date
6935 format, but if you are using Emacs 21.1 or 21.2 and specify a
6936 non-@acronym{POSIX} locale you may need to set
6937 @samp{TIME_STYLE="posix-long-iso"}.
6939 To avoid certain denial-of-service attacks, timestamps that would be
6940 longer than 1000 bytes may be treated as errors.
6943 @node Formatting the file names
6944 @subsection Formatting the file names
6946 These options change how file names themselves are printed.
6952 @itemx --quoting-style=escape
6955 @opindex --quoting-style
6956 @cindex backslash sequences for file names
6957 Quote nongraphic characters in file names using alphabetic and octal
6958 backslash sequences like those used in C.
6962 @itemx --quoting-style=literal
6965 @opindex --quoting-style
6966 Do not quote file names. However, with @command{ls} nongraphic
6967 characters are still printed as question marks if the output is a
6968 terminal and you do not specify the @option{--show-control-chars}
6972 @itemx --hide-control-chars
6974 @opindex --hide-control-chars
6975 Print question marks instead of nongraphic characters in file names.
6976 This is the default if the output is a terminal and the program is
6981 @itemx --quoting-style=c
6983 @opindex --quote-name
6984 @opindex --quoting-style
6985 Enclose file names in double quotes and quote nongraphic characters as
6988 @item --quoting-style=@var{word}
6989 @opindex --quoting-style
6990 @cindex quoting style
6991 Use style @var{word} to quote file names and other strings that may
6992 contain arbitrary characters. The @var{word} should
6993 be one of the following:
6997 Output strings as-is; this is the same as the @option{-N} or
6998 @option{--literal} option.
7000 Quote strings for the shell if they contain shell metacharacters or would
7001 cause ambiguous output.
7002 The quoting is suitable for @acronym{POSIX}-compatible shells like
7003 @command{bash}, but it does not always work for incompatible shells
7006 Quote strings for the shell, even if they would normally not require quoting.
7008 Quote strings as for C character string literals, including the
7009 surrounding double-quote characters; this is the same as the
7010 @option{-Q} or @option{--quote-name} option.
7012 Quote strings as for C character string literals, except omit the
7013 surrounding double-quote
7014 characters; this is the same as the @option{-b} or @option{--escape} option.
7016 Quote strings as for C character string literals, except use
7017 surrounding quotation marks appropriate for the
7020 @c Use @t instead of @samp to avoid duplicate quoting in some output styles.
7021 Quote strings as for C character string literals, except use
7022 surrounding quotation marks appropriate for the locale, and quote
7023 @t{`like this'} instead of @t{"like
7024 this"} in the default C locale. This looks nicer on many displays.
7027 You can specify the default value of the @option{--quoting-style} option
7028 with the environment variable @env{QUOTING_STYLE}. If that environment
7029 variable is not set, the default value is @samp{literal}, but this
7030 default may change to @samp{shell} in a future version of this package.
7032 @item --show-control-chars
7033 @opindex --show-control-chars
7034 Print nongraphic characters as-is in file names.
7035 This is the default unless the output is a terminal and the program is
7041 @node dir invocation
7042 @section @command{dir}: Briefly list directory contents
7045 @cindex directory listing, brief
7047 @command{dir} is equivalent to @code{ls -C
7048 -b}; that is, by default files are listed in columns, sorted vertically,
7049 and special characters are represented by backslash escape sequences.
7051 @xref{ls invocation, @command{ls}}.
7054 @node vdir invocation
7055 @section @command{vdir}: Verbosely list directory contents
7058 @cindex directory listing, verbose
7060 @command{vdir} is equivalent to @code{ls -l
7061 -b}; that is, by default files are listed in long format and special
7062 characters are represented by backslash escape sequences.
7064 @node dircolors invocation
7065 @section @command{dircolors}: Color setup for @command{ls}
7069 @cindex setup for color
7071 @command{dircolors} outputs a sequence of shell commands to set up the
7072 terminal for color output from @command{ls} (and @command{dir}, etc.).
7076 eval "`dircolors [@var{option}]@dots{} [@var{file}]`"
7079 If @var{file} is specified, @command{dircolors} reads it to determine which
7080 colors to use for which file types and extensions. Otherwise, a
7081 precompiled database is used. For details on the format of these files,
7082 run @samp{dircolors --print-database}.
7084 To make @command{dircolors} read a @file{~/.dircolors} file if it
7085 exists, you can put the following lines in your @file{~/.bashrc} (or
7086 adapt them to your favorite shell):
7090 test -r $d && eval "$(dircolors $d)"
7094 @vindex SHELL @r{environment variable, and color}
7095 The output is a shell command to set the @env{LS_COLORS} environment
7096 variable. You can specify the shell syntax to use on the command line,
7097 or @command{dircolors} will guess it from the value of the @env{SHELL}
7098 environment variable.
7100 The program accepts the following options. Also see @ref{Common options}.
7105 @itemx --bourne-shell
7108 @opindex --bourne-shell
7109 @cindex Bourne shell syntax for color setup
7110 @cindex @command{sh} syntax for color setup
7111 Output Bourne shell commands. This is the default if the @env{SHELL}
7112 environment variable is set and does not end with @samp{csh} or
7121 @cindex C shell syntax for color setup
7122 @cindex @command{csh} syntax for color setup
7123 Output C shell commands. This is the default if @code{SHELL} ends with
7124 @command{csh} or @command{tcsh}.
7127 @itemx --print-database
7129 @opindex --print-database
7130 @cindex color database, printing
7131 @cindex database for color setup, printing
7132 @cindex printing color database
7133 Print the (compiled-in) default color configuration database. This
7134 output is itself a valid configuration file, and is fairly descriptive
7135 of the possibilities.
7142 @node Basic operations
7143 @chapter Basic operations
7145 @cindex manipulating files
7147 This chapter describes the commands for basic file manipulation:
7148 copying, moving (renaming), and deleting (removing).
7151 * cp invocation:: Copy files.
7152 * dd invocation:: Convert and copy a file.
7153 * install invocation:: Copy files and set attributes.
7154 * mv invocation:: Move (rename) files.
7155 * rm invocation:: Remove files or directories.
7156 * shred invocation:: Remove files more securely.
7161 @section @command{cp}: Copy files and directories
7164 @cindex copying files and directories
7165 @cindex files, copying
7166 @cindex directories, copying
7168 @command{cp} copies files (or, optionally, directories). The copy is
7169 completely independent of the original. You can either copy one file to
7170 another, or copy arbitrarily many files to a destination directory.
7174 cp [@var{option}]@dots{} [-T] @var{source} @var{dest}
7175 cp [@var{option}]@dots{} @var{source}@dots{} @var{directory}
7176 cp [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
7181 If two file names are given, @command{cp} copies the first file to the
7185 If the @option{--target-directory} (@option{-t}) option is given, or
7186 failing that if the last file is a directory and the
7187 @option{--no-target-directory} (@option{-T}) option is not given,
7188 @command{cp} copies each @var{source} file to the specified directory,
7189 using the @var{source}s' names.
7192 Generally, files are written just as they are read. For exceptions,
7193 see the @option{--sparse} option below.
7195 By default, @command{cp} does not copy directories. However, the
7196 @option{-R}, @option{-a}, and @option{-r} options cause @command{cp} to
7197 copy recursively by descending into source directories and copying files
7198 to corresponding destination directories.
7200 When copying from a symbolic link, @command{cp} normally follows the
7201 link only when not copying
7202 recursively. This default can be overridden with the
7203 @option{--archive} (@option{-a}), @option{-d}, @option{--dereference}
7204 (@option{-L}), @option{--no-dereference} (@option{-P}), and
7205 @option{-H} options. If more than one of these options is specified,
7206 the last one silently overrides the others.
7208 When copying to a symbolic link, @command{cp} follows the
7209 link only when it refers to an existing regular file.
7210 However, when copying to a dangling symbolic link, @command{cp}
7211 refuses by default, and fails with a diagnostic, since the operation
7212 is inherently dangerous. This behavior is contrary to historical
7213 practice and to @acronym{POSIX}.
7214 Set @env{POSIXLY_CORRECT} to make @command{cp} attempt to create
7215 the target of a dangling destination symlink, in spite of the possible risk.
7216 Also, when an option like
7217 @option{--backup} or @option{--link} acts to rename or remove the
7218 destination before copying, @command{cp} renames or removes the
7219 symbolic link rather than the file it points to.
7221 By default, @command{cp} copies the contents of special files only
7222 when not copying recursively. This default can be overridden with the
7223 @option{--copy-contents} option.
7225 @cindex self-backups
7226 @cindex backups, making only
7227 @command{cp} generally refuses to copy a file onto itself, with the
7228 following exception: if @option{--force --backup} is specified with
7229 @var{source} and @var{dest} identical, and referring to a regular file,
7230 @command{cp} will make a backup file, either regular or numbered, as
7231 specified in the usual ways (@pxref{Backup options}). This is useful when
7232 you simply want to make a backup of an existing file before changing it.
7234 The program accepts the following options. Also see @ref{Common options}.
7241 Preserve as much as possible of the structure and attributes of the
7242 original files in the copy (but do not attempt to preserve internal
7243 directory structure; i.e., @samp{ls -U} may list the entries in a copied
7244 directory in a different order).
7245 Equivalent to @option{-dpR}.
7248 @itemx @w{@kbd{--backup}[=@var{method}]}
7251 @vindex VERSION_CONTROL
7252 @cindex backups, making
7253 @xref{Backup options}.
7254 Make a backup of each file that would otherwise be overwritten or removed.
7255 As a special case, @command{cp} makes a backup of @var{source} when the force
7256 and backup options are given and @var{source} and @var{dest} are the same
7257 name for an existing, regular file. One useful application of this
7258 combination of options is this tiny Bourne shell script:
7262 # Usage: backup FILE...
7263 # Create a @sc{gnu}-style backup of each listed FILE.
7265 cp --backup --force -- "$i" "$i"
7269 @item --copy-contents
7270 @cindex directories, copying recursively
7271 @cindex copying directories recursively
7272 @cindex recursively copying directories
7273 @cindex non-directories, copying as special files
7274 If copying recursively, copy the contents of any special files (e.g.,
7275 FIFOs and device files) as if they were regular files. This means
7276 trying to read the data in each source file and writing it to the
7277 destination. It is usually a mistake to use this option, as it
7278 normally has undesirable effects on special files like FIFOs and the
7279 ones typically found in the @file{/dev} directory. In most cases,
7280 @code{cp -R --copy-contents} will hang indefinitely trying to read
7281 from FIFOs and special files like @file{/dev/console}, and it will
7282 fill up your destination disk if you use it to copy @file{/dev/zero}.
7283 This option has no effect unless copying recursively, and it does not
7284 affect the copying of symbolic links.
7288 @cindex symbolic links, copying
7289 @cindex hard links, preserving
7290 Copy symbolic links as symbolic links rather than copying the files that
7291 they point to, and preserve hard links between source files in the copies.
7292 Equivalent to @option{--no-dereference --preserve=links}.
7298 When copying without this option and an existing destination file cannot
7299 be opened for writing, the copy fails. However, with @option{--force}),
7300 when a destination file cannot be opened, @command{cp} then removes it and
7301 tries to open it again. Contrast this behavior with that enabled by
7302 @option{--link} and @option{--symbolic-link}, whereby the destination file
7303 is never opened but rather is removed unconditionally. Also see the
7304 description of @option{--remove-destination}.
7306 This option is independent of the @option{--interactive} or
7307 @option{-i} option: neither cancels the effect of the other.
7311 If a command line argument specifies a symbolic link, then copy the
7312 file it points to rather than the symbolic link itself. However,
7313 copy (preserving its nature) any symbolic link that is encountered
7314 via recursive traversal.
7317 @itemx --interactive
7319 @opindex --interactive
7320 When copying a file other than a directory, prompt whether to
7321 overwrite an existing destination file.
7327 Make hard links instead of copies of non-directories.
7330 @itemx --dereference
7332 @opindex --dereference
7333 Follow symbolic links when copying from them.
7336 @itemx --no-dereference
7338 @opindex --no-dereference
7339 @cindex symbolic links, copying
7340 Copy symbolic links as symbolic links rather than copying the files that
7341 they point to. This option affects only symbolic links in the source;
7342 symbolic links in the destination are always followed if possible.
7345 @itemx @w{@kbd{--preserve}[=@var{attribute_list}]}
7348 @cindex file information, preserving
7349 Preserve the specified attributes of the original files.
7350 If specified, the @var{attribute_list} must be a comma-separated list
7351 of one or more of the following strings:
7355 Preserve the file mode bits and access control lists.
7357 Preserve the owner and group. On most modern systems,
7358 only users with appropriate privileges may change the owner of a file,
7360 may preserve the group ownership of a file only if they happen to be
7361 a member of the desired group.
7363 Preserve the times of last access and last modification, when possible.
7364 In general, it is not possible to preserve these attributes
7365 when the affected file is a symbolic link.
7366 However, FreeBSD now provides the @code{lutimes} function, which makes
7367 it possible even for symbolic links. However, this implementation does
7368 not yet take advantage of that.
7369 @c FIXME: once we provide lutimes support, update the above.
7371 Preserve in the destination files
7372 any links between corresponding source files.
7373 @c Give examples illustrating how hard links are preserved.
7374 @c Also, show how soft links map to hard links with -L and -H.
7376 Preserve all file attributes.
7377 Equivalent to specifying all of the above.
7380 Using @option{--preserve} with no @var{attribute_list} is equivalent
7381 to @option{--preserve=mode,ownership,timestamps}.
7383 In the absence of this option, each destination file is created with the
7384 mode bits of the corresponding source file, minus the bits set in the
7385 umask and minus the set-user-ID and set-group-ID bits.
7386 @xref{File permissions}.
7388 @itemx @w{@kbd{--no-preserve}=@var{attribute_list}}
7389 @cindex file information, preserving
7390 Do not preserve the specified attributes. The @var{attribute_list}
7391 has the same form as for @option{--preserve}.
7395 @cindex parent directories and @command{cp}
7396 Form the name of each destination file by appending to the target
7397 directory a slash and the specified name of the source file. The last
7398 argument given to @command{cp} must be the name of an existing directory.
7399 For example, the command:
7402 cp --parents a/b/c existing_dir
7406 copies the file @file{a/b/c} to @file{existing_dir/a/b/c}, creating
7407 any missing intermediate directories.
7414 @opindex --recursive
7415 @cindex directories, copying recursively
7416 @cindex copying directories recursively
7417 @cindex recursively copying directories
7418 @cindex non-directories, copying as special files
7419 Copy directories recursively. By default, do not follow symbolic
7420 links in the source; see the @option{--archive} (@option{-a}), @option{-d},
7421 @option{--dereference} (@option{-L}), @option{--no-dereference}
7422 (@option{-P}), and @option{-H} options. Special files are copied by
7423 creating a destination file of the same type as the source; see the
7424 @option{--copy-contents} option. It is not portable to use
7425 @option{-r} to copy symbolic links or special files. On some
7426 non-@sc{gnu} systems, @option{-r} implies the equivalent of
7427 @option{-L} and @option{--copy-contents} for historical reasons.
7428 Also, it is not portable to use @option{-R} to copy symbolic links
7429 unless you also specify @option{-P}, as @acronym{POSIX} allows
7430 implementations that dereference symbolic links by default.
7432 @item --remove-destination
7433 @opindex --remove-destination
7434 Remove each existing destination file before attempting to open it
7435 (contrast with @option{-f} above).
7437 @item --sparse=@var{when}
7438 @opindex --sparse=@var{when}
7439 @cindex sparse files, copying
7440 @cindex holes, copying files with
7441 @findex read @r{system call, and holes}
7442 A @dfn{sparse file} contains @dfn{holes}---a sequence of zero bytes that
7443 does not occupy any physical disk blocks; the @samp{read} system call
7444 reads these as zeros. This can both save considerable disk space and
7445 increase speed, since many binary files contain lots of consecutive zero
7446 bytes. By default, @command{cp} detects holes in input source files via a crude
7447 heuristic and makes the corresponding output file sparse as well.
7448 Only regular files may be sparse.
7450 The @var{when} value can be one of the following:
7454 The default behavior: if the input file is sparse, attempt to make
7455 the output file sparse, too. However, if an output file exists but
7456 refers to a non-regular file, then do not attempt to make it sparse.
7459 For each sufficiently long sequence of zero bytes in the input file,
7460 attempt to create a corresponding hole in the output file, even if the
7461 input file does not appear to be sparse.
7462 This is useful when the input file resides on a file system
7463 that does not support sparse files
7464 (for example, @samp{efs} file systems in SGI IRIX 5.3 and earlier),
7465 but the output file is on a type of file system that does support them.
7466 Holes may be created only in regular files, so if the destination file
7467 is of some other type, @command{cp} does not even try to make it sparse.
7470 Never make the output file sparse.
7471 This is useful in creating a file for use with the @command{mkswap} command,
7472 since such a file must not have any holes.
7475 @optStripTrailingSlashes
7478 @itemx --symbolic-link
7480 @opindex --symbolic-link
7481 @cindex symbolic links, copying with
7482 Make symbolic links instead of copies of non-directories. All source
7483 file names must be absolute (starting with @samp{/}) unless the
7484 destination files are in the current directory. This option merely
7485 results in an error message on systems that do not support symbolic links.
7491 @optNoTargetDirectory
7497 @cindex newer files, copying only
7498 Do not copy a non-directory that has an existing destination with the
7499 same or newer modification time. If time stamps are being preserved,
7500 the comparison is to the source time stamp truncated to the
7501 resolutions of the destination file system and of the system calls
7502 used to update time stamps; this avoids duplicate work if several
7503 @samp{cp -pu} commands are executed with the same source and
7510 Print the name of each file before copying it.
7513 @itemx --one-file-system
7515 @opindex --one-file-system
7516 @cindex file systems, omitting copying to different
7517 Skip subdirectories that are on different file systems from the one that
7518 the copy started on.
7519 However, mount point directories @emph{are} copied.
7527 @section @command{dd}: Convert and copy a file
7530 @cindex converting while copying a file
7532 @command{dd} copies a file (from standard input to standard output, by
7533 default) with a changeable I/O block size, while optionally performing
7534 conversions on it. Synopses:
7537 dd [@var{operand}]@dots{}
7541 The only options are @option{--help} and @option{--version}.
7542 @xref{Common options}. @command{dd} accepts the following operands.
7548 Read from @var{file} instead of standard input.
7552 Write to @var{file} instead of standard output. Unless
7553 @samp{conv=notrunc} is given, @command{dd} truncates @var{file} to zero
7554 bytes (or the size specified with @samp{seek=}).
7556 @item ibs=@var{bytes}
7558 @cindex block size of input
7559 @cindex input block size
7560 Set the input block size to @var{bytes}.
7561 This makes @command{dd} read @var{bytes} per block.
7563 @item obs=@var{bytes}
7565 @cindex block size of output
7566 @cindex output block size
7567 Set the output block size to @var{bytes}.
7568 This makes @command{dd} write @var{bytes} per block.
7570 @item bs=@var{bytes}
7573 Set both input and output block sizes to @var{bytes}.
7574 This makes @command{dd} read and write @var{bytes} per block,
7575 overriding any @samp{ibs} and @samp{obs} settings.
7577 @item cbs=@var{bytes}
7579 @cindex block size of conversion
7580 @cindex conversion block size
7581 @cindex fixed-length records, converting to variable-length
7582 @cindex variable-length records, converting to fixed-length
7583 Set the conversion block size to @var{bytes}.
7584 When converting variable-length records to fixed-length ones
7585 (@option{conv=block}) or the reverse (@option{conv=unblock}),
7586 use @var{bytes} as the fixed record length.
7588 @item skip=@var{blocks}
7590 Skip @var{blocks} @samp{ibs}-byte blocks in the input file before copying.
7592 @item seek=@var{blocks}
7594 Skip @var{blocks} @samp{obs}-byte blocks in the output file before copying.
7596 @item count=@var{blocks}
7598 Copy @var{blocks} @samp{ibs}-byte blocks from the input file, instead
7599 of everything until the end of the file.
7601 @item conv=@var{conversion}[,@var{conversion}]@dots{}
7603 Convert the file as specified by the @var{conversion} argument(s).
7604 (No spaces around any comma(s).)
7611 @opindex ascii@r{, converting to}
7612 Convert @acronym{EBCDIC} to @acronym{ASCII},
7613 using the conversion table specified by @acronym{POSIX}.
7614 This provides a 1:1 translation for all 256 bytes.
7617 @opindex ebcdic@r{, converting to}
7618 Convert @acronym{ASCII} to @acronym{EBCDIC}.
7619 This is the inverse of the @samp{ascii} conversion.
7622 @opindex alternate ebcdic@r{, converting to}
7623 Convert @acronym{ASCII} to alternate @acronym{EBCDIC},
7624 using the alternate conversion table specified by @acronym{POSIX}.
7625 This is not a 1:1 translation, but reflects common historical practice
7626 for @samp{~}, @samp{[}, and @samp{]}.
7628 The @samp{ascii}, @samp{ebcdic}, and @samp{ibm} conversions are
7632 @opindex block @r{(space-padding)}
7633 For each line in the input, output @samp{cbs} bytes, replacing the
7634 input newline with a space and padding with spaces as necessary.
7638 Replace trailing spaces in each @samp{cbs}-sized input block with a
7641 The @samp{block} and @samp{unblock} conversions are mutually exclusive.
7644 @opindex lcase@r{, converting to}
7645 Change uppercase letters to lowercase.
7648 @opindex ucase@r{, converting to}
7649 Change lowercase letters to uppercase.
7651 The @samp{lcase} and @samp{ucase} conversions are mutually exclusive.
7654 @opindex swab @r{(byte-swapping)}
7655 @cindex byte-swapping
7656 Swap every pair of input bytes. @sc{gnu} @command{dd}, unlike others, works
7657 when an odd number of bytes are read---the last byte is simply copied
7658 (since there is nothing to swap it with).
7662 @cindex read errors, ignoring
7663 Continue after read errors.
7667 @cindex creating output file, avoiding
7668 Do not create the output file; the output file must already exist.
7672 @cindex creating output file, requiring
7673 Fail if the output file already exists; @command{dd} must create the
7676 The @samp{excl} and @samp{nocreat} conversions are mutually exclusive.
7680 @cindex truncating output file, avoiding
7681 Do not truncate the output file.
7684 @opindex sync @r{(padding with nulls)}
7685 Pad every input block to size of @samp{ibs} with trailing zero bytes.
7686 When used with @samp{block} or @samp{unblock}, pad with spaces instead of
7691 @cindex synchronized data writes, before finishing
7692 Synchronize output data just before finishing. This forces a physical
7693 write of output data.
7697 @cindex synchronized data and metadata writes, before finishing
7698 Synchronize output data and metadata just before finishing. This
7699 forces a physical write of output data and metadata.
7703 @item iflag=@var{flag}[,@var{flag}]@dots{}
7705 Access the input file using the flags specified by the @var{flag}
7706 argument(s). (No spaces around any comma(s).)
7708 @item oflag=@var{flag}[,@var{flag}]@dots{}
7710 Access the output file using the flags specified by the @var{flag}
7711 argument(s). (No spaces around any comma(s).)
7713 Here are the flags. Not every flag is supported on every operating
7720 @cindex appending to the output file
7721 Write in append mode, so that even if some other process is writing to
7722 this file, every @command{dd} write will append to the current
7723 contents of the file. This flag makes sense only for output.
7724 If you combine this flag with the @samp{of=@var{file}} operand,
7725 you should also specify @samp{conv=notrunc} unless you want the
7726 output file to be truncated before being appended to.
7731 Use direct I/O for data, avoiding the buffer cache.
7735 @cindex directory I/O
7737 Fail unless the file is a directory. Most operating systems do not
7738 allow I/O to a directory, so this flag has limited utility.
7742 @cindex synchronized data reads
7743 Use synchronized I/O for data. For the output file, this forces a
7744 physical write of output data on each write. For the input file,
7745 this flag can matter when reading from a remote file that has been
7746 written to synchronously by some other process. Metadata (e.g.,
7747 last-access and last-modified time) is not necessarily synchronized.
7751 @cindex synchronized data and metadata I/O
7752 Use synchronized I/O for both data and metadata.
7756 @cindex nonblocking I/O
7757 Use non-blocking I/O.
7762 Do not update the file's access time.
7763 Some older file systems silently ignore this flag, so it is a good
7764 idea to test it on your files before relying on it.
7768 @cindex controlling terminal
7769 Do not assign the file to be a controlling terminal for @command{dd}.
7770 This has no effect when the file is not a terminal.
7771 On many hosts (e.g., @acronym{GNU}/Linux hosts), this option has no effect
7776 @cindex symbolic links, following
7777 Do not follow symbolic links.
7782 Fail if the file has multiple hard links.
7787 Use binary I/O. This option has an effect only on nonstandard
7788 platforms that distinguish binary from text I/O.
7793 Use text I/O. Like @samp{binary}, this option has no effect on
7798 Accumulate full blocks from input. The @code{read} system call
7799 may return early if a full block is not available.
7800 When that happens, continue calling @code{read} to fill the remainder
7802 This flag can be used only with @code{iflag}.
7806 These flags are not supported on all systems, and @samp{dd} rejects
7807 attempts to use them when they are not supported. When reading from
7808 standard input or writing to standard output, the @samp{nofollow} and
7809 @samp{noctty} flags should not be specified, and the other flags
7810 (e.g., @samp{nonblock}) can affect how other processes behave with the
7811 affected file descriptors, even after @command{dd} exits.
7815 @cindex multipliers after numbers
7816 The numeric-valued strings above (@var{bytes} and @var{blocks}) can be
7817 followed by a multiplier: @samp{b}=512, @samp{c}=1,
7818 @samp{w}=2, @samp{x@var{m}}=@var{m}, or any of the
7819 standard block size suffixes like @samp{k}=1024 (@pxref{Block size}).
7821 Use different @command{dd} invocations to use different block sizes for
7822 skipping and I/O@. For example, the following shell commands copy data
7823 in 512 KiB blocks between a disk and a tape, but do not save or restore a
7824 4 KiB label at the start of the disk:
7827 disk=/dev/rdsk/c0t1d0s2
7830 # Copy all but the label from disk to tape.
7831 (dd bs=4k skip=1 count=0 && dd bs=512k) <$disk >$tape
7833 # Copy from tape back to disk, but leave the disk label alone.
7834 (dd bs=4k seek=1 count=0 && dd bs=512k) <$tape >$disk
7837 Sending an @samp{INFO} signal to a running @command{dd}
7838 process makes it print I/O statistics to standard error
7839 and then resume copying. In the example below,
7840 @command{dd} is run in the background to copy 10 million blocks.
7841 The @command{kill} command makes it output intermediate I/O statistics,
7842 and when @command{dd} completes normally or is killed by the
7843 @code{SIGINT} signal, it outputs the final statistics.
7846 $ dd if=/dev/zero of=/dev/null count=10MB & pid=$!
7847 $ kill -s INFO $pid; wait $pid
7848 3385223+0 records in
7849 3385223+0 records out
7850 1733234176 bytes (1.7 GB) copied, 6.42173 seconds, 270 MB/s
7851 10000000+0 records in
7852 10000000+0 records out
7853 5120000000 bytes (5.1 GB) copied, 18.913 seconds, 271 MB/s
7856 @vindex POSIXLY_CORRECT
7857 On systems lacking the @samp{INFO} signal @command{dd} responds to the
7858 @samp{USR1} signal instead, unless the @env{POSIXLY_CORRECT}
7859 environment variable is set.
7864 @node install invocation
7865 @section @command{install}: Copy files and set attributes
7868 @cindex copying files and setting attributes
7870 @command{install} copies files while setting their file mode bits and, if
7871 possible, their owner and group. Synopses:
7874 install [@var{option}]@dots{} [-T] @var{source} @var{dest}
7875 install [@var{option}]@dots{} @var{source}@dots{} @var{directory}
7876 install [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
7877 install [@var{option}]@dots{} -d @var{directory}@dots{}
7882 If two file names are given, @command{install} copies the first file to the
7886 If the @option{--target-directory} (@option{-t}) option is given, or
7887 failing that if the last file is a directory and the
7888 @option{--no-target-directory} (@option{-T}) option is not given,
7889 @command{install} copies each @var{source} file to the specified
7890 directory, using the @var{source}s' names.
7893 If the @option{--directory} (@option{-d}) option is given,
7894 @command{install} creates each @var{directory} and any missing parent
7895 directories. Parent directories are created with mode
7896 @samp{u=rwx,go=rx} (755), regardless of the @option{-m} option or the
7897 current umask. @xref{Directory Setuid and Setgid}, for how the
7898 set-user-ID and set-group-ID bits of parent directories are inherited.
7901 @cindex Makefiles, installing programs in
7902 @command{install} is similar to @command{cp}, but allows you to control the
7903 attributes of destination files. It is typically used in Makefiles to
7904 copy programs into their destination directories. It refuses to copy
7905 files onto themselves.
7907 The program accepts the following options. Also see @ref{Common options}.
7915 Ignored; for compatibility with old Unix versions of @command{install}.
7919 Create any missing parent directories of @var{dest},
7920 then copy @var{source} to @var{dest}.
7921 This option is ignored if a destination directory is specified
7922 via @option{--target-directory=DIR}.
7927 @opindex --directory
7928 @cindex directories, creating with given attributes
7929 @cindex parent directories, creating missing
7930 @cindex leading directories, creating missing
7931 Create any missing parent directories, giving them the default
7932 attributes. Then create each given directory, setting their owner,
7933 group and mode as given on the command line or to the defaults.
7935 @item -g @var{group}
7936 @itemx --group=@var{group}
7939 @cindex group ownership of installed files, setting
7940 Set the group ownership of installed files or directories to
7941 @var{group}. The default is the process's current group. @var{group}
7942 may be either a group name or a numeric group ID.
7945 @itemx --mode=@var{mode}
7948 @cindex permissions of installed files, setting
7949 Set the file mode bits for the installed file or directory to @var{mode},
7950 which can be either an octal number, or a symbolic mode as in
7951 @command{chmod}, with @samp{a=} (no access allowed to anyone) as the
7952 point of departure (@pxref{File permissions}).
7953 The default mode is @samp{u=rwx,go=rx,a-s}---read, write, and
7954 execute for the owner, read and execute for group and other, and with
7955 set-user-ID and set-group-ID disabled.
7956 This default is not quite the same as @samp{755}, since it disables
7957 instead of preserving set-user-ID and set-group-ID on directories.
7958 @xref{Directory Setuid and Setgid}.
7960 @item -o @var{owner}
7961 @itemx --owner=@var{owner}
7964 @cindex ownership of installed files, setting
7965 @cindex appropriate privileges
7966 @vindex root @r{as default owner}
7967 If @command{install} has appropriate privileges (is run as root), set the
7968 ownership of installed files or directories to @var{owner}. The default
7969 is @code{root}. @var{owner} may be either a user name or a numeric user
7973 @itemx --preserve-timestamps
7975 @opindex --preserve-timestamps
7976 @cindex timestamps of installed files, preserving
7977 Set the time of last access and the time of last modification of each
7978 installed file to match those of each corresponding original file.
7979 When a file is installed without this option, its last access and
7980 last modification times are both set to the time of installation.
7981 This option is useful if you want to use the last modification times
7982 of installed files to keep track of when they were last built as opposed
7983 to when they were last installed.
7989 @cindex symbol table information, stripping
7990 @cindex stripping symbol table information
7991 Strip the symbol tables from installed binary executables.
7993 @itemx --strip-program=@var{program}
7994 @opindex --strip-program
7995 @cindex symbol table information, stripping, program
7996 Program used to strip binaries.
8002 @optNoTargetDirectory
8008 Print the name of each file before copying it.
8016 @section @command{mv}: Move (rename) files
8020 @command{mv} moves or renames files (or directories). Synopses:
8023 mv [@var{option}]@dots{} [-T] @var{source} @var{dest}
8024 mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
8025 mv [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
8030 If two file names are given, @command{mv} moves the first file to the
8034 If the @option{--target-directory} (@option{-t}) option is given, or
8035 failing that if the last file is a directory and the
8036 @option{--no-target-directory} (@option{-T}) option is not given,
8037 @command{mv} moves each @var{source} file to the specified
8038 directory, using the @var{source}s' names.
8041 @command{mv} can move any type of file from one file system to another.
8042 Prior to version @code{4.0} of the fileutils,
8043 @command{mv} could move only regular files between file systems.
8044 For example, now @command{mv} can move an entire directory hierarchy
8045 including special device files from one partition to another. It first
8046 uses some of the same code that's used by @code{cp -a} to copy the
8047 requested directories and files, then (assuming the copy succeeded)
8048 it removes the originals. If the copy fails, then the part that was
8049 copied to the destination partition is removed. If you were to copy
8050 three directories from one partition to another and the copy of the first
8051 directory succeeded, but the second didn't, the first would be left on
8052 the destination partition and the second and third would be left on the
8055 @cindex prompting, and @command{mv}
8056 If a destination file exists but is normally unwritable, standard input
8057 is a terminal, and the @option{-f} or @option{--force} option is not given,
8058 @command{mv} prompts the user for whether to replace the file. (You might
8059 own the file, or have write permission on its directory.) If the
8060 response is not affirmative, the file is skipped.
8062 @emph{Warning}: Avoid specifying a source name with a trailing slash,
8063 when it might be a symlink to a directory.
8064 Otherwise, @command{mv} may do something very surprising, since
8065 its behavior depends on the underlying rename system call.
8066 On a system with a modern Linux-based kernel, it fails with @code{errno=ENOTDIR}.
8067 However, on other systems (at least FreeBSD 6.1 and Solaris 10) it silently
8068 renames not the symlink but rather the directory referenced by the symlink.
8069 @xref{Trailing slashes}.
8071 The program accepts the following options. Also see @ref{Common options}.
8081 @cindex prompts, omitting
8082 Do not prompt the user before removing a destination file.
8085 @itemx --interactive
8087 @opindex --interactive
8088 @cindex prompts, forcing
8089 Prompt whether to overwrite each existing destination file, regardless
8091 If the response is not affirmative, the file is skipped.
8097 @cindex newer files, moving only
8098 Do not move a non-directory that has an existing destination with the
8099 same or newer modification time.
8100 If the move is across file system boundaries, the comparison is to the
8101 source time stamp truncated to the resolutions of the destination file
8102 system and of the system calls used to update time stamps; this avoids
8103 duplicate work if several @samp{mv -u} commands are executed with the
8104 same source and destination.
8110 Print the name of each file before moving it.
8112 @optStripTrailingSlashes
8118 @optNoTargetDirectory
8126 @section @command{rm}: Remove files or directories
8129 @cindex removing files or directories
8131 @command{rm} removes each given @var{file}. By default, it does not remove
8132 directories. Synopsis:
8135 rm [@var{option}]@dots{} [@var{file}]@dots{}
8138 @cindex prompting, and @command{rm}
8139 If the @option{-I} or @option{--interactive=once} option is given,
8140 and there are more than three files or the @option{-r}, @option{-R},
8141 or @option{--recursive} are given, then @command{rm} prompts the user
8142 for whether to proceed with the entire operation. If the response is
8143 not affirmative, the entire command is aborted.
8145 Otherwise, if a file is unwritable, standard input is a terminal, and
8146 the @option{-f} or @option{--force} option is not given, or the
8147 @option{-i} or @option{--interactive=always} option @emph{is} given,
8148 @command{rm} prompts the user for whether to remove the file.
8149 If the response is not affirmative, the file is skipped.
8151 Any attempt to remove a file whose last file name component is
8152 @file{.} or @file{..} is rejected without any prompting.
8154 @emph{Warning}: If you use @command{rm} to remove a file, it is usually
8155 possible to recover the contents of that file. If you want more assurance
8156 that the contents are truly unrecoverable, consider using @command{shred}.
8158 The program accepts the following options. Also see @ref{Common options}.
8166 Ignore nonexistent files and never prompt the user.
8167 Ignore any previous @option{--interactive} (@option{-i}) option.
8171 Prompt whether to remove each file.
8172 If the response is not affirmative, the file is skipped.
8173 Ignore any previous @option{--force} (@option{-f}) option.
8174 Equivalent to @option{--interactive=always}.
8178 Prompt once whether to proceed with the command, if more than three
8179 files are named or if a recursive removal is requested. Ignore any
8180 previous @option{--force} (@option{-f}) option. Equivalent to
8181 @option{--interactive=once}.
8183 @itemx --interactive [=@var{when}]
8184 @opindex --interactive
8185 Specify when to issue an interactive prompt. @var{when} may be
8189 @vindex never @r{interactive option}
8190 - Do not prompt at all.
8192 @vindex once @r{interactive option}
8193 - Prompt once if more than three files are named or if a recursive
8194 removal is requested. Equivalent to @option{-I}.
8196 @vindex always @r{interactive option}
8197 - Prompt for every file being removed. Equivalent to @option{-i}.
8199 @option{--interactive} with no @var{when} is equivalent to
8200 @option{--interactive=always}.
8202 @itemx --one-file-system
8203 @opindex --one-file-system
8204 @cindex one file system, restricting @command{rm} to
8205 When removing a hierarchy recursively, skip any directory that is on a
8206 file system different from that of the corresponding command line argument.
8208 This option is useful when removing a build ``chroot'' hierarchy,
8209 which normally contains no valuable data. However, it is not uncommon
8210 to bind-mount @file{/home} into such a hierarchy, to make it easier to
8211 use one's start-up file. The catch is that it's easy to forget to
8212 unmount @file{/home}. Then, when you use @command{rm -rf} to remove
8213 your normally throw-away chroot, that command will remove everything
8214 under @file{/home}, too.
8215 Use the @option{--one-file-system} option, and it will
8216 warn about and skip directories on other file systems.
8217 Of course, this will not save your @file{/home} if it and your
8218 chroot happen to be on the same file system.
8220 @itemx --preserve-root
8221 @opindex --preserve-root
8222 @cindex root directory, disallow recursive destruction
8223 Fail upon any attempt to remove the root directory, @file{/},
8224 when used with the @option{--recursive} option.
8225 This is the default behavior.
8226 @xref{Treating / specially}.
8228 @itemx --no-preserve-root
8229 @opindex --no-preserve-root
8230 @cindex root directory, allow recursive destruction
8231 Do not treat @file{/} specially when removing recursively.
8232 This option is not recommended unless you really want to
8233 remove all the files on your computer.
8234 @xref{Treating / specially}.
8241 @opindex --recursive
8242 @cindex directories, removing (recursively)
8243 Remove the listed directories and their contents recursively.
8249 Print the name of each file before removing it.
8253 @cindex files beginning with @samp{-}, removing
8254 @cindex @samp{-}, removing files beginning with
8255 One common question is how to remove files whose names begin with a
8256 @samp{-}. @sc{gnu} @command{rm}, like every program that uses the @code{getopt}
8257 function to parse its arguments, lets you use the @samp{--} option to
8258 indicate that all following arguments are non-options. To remove a file
8259 called @file{-f} in the current directory, you could type either:
8272 @opindex - @r{and Unix @command{rm}}
8273 The Unix @command{rm} program's use of a single @samp{-} for this purpose
8274 predates the development of the getopt standard syntax.
8279 @node shred invocation
8280 @section @command{shred}: Remove files more securely
8283 @cindex data, erasing
8284 @cindex erasing data
8286 @command{shred} overwrites devices or files, to help prevent even
8287 very expensive hardware from recovering the data.
8289 Ordinarily when you remove a file (@pxref{rm invocation}), the data is
8290 not actually destroyed. Only the index listing where the file is
8291 stored is destroyed, and the storage is made available for reuse.
8292 There are undelete utilities that will attempt to reconstruct the index
8293 and can bring the file back if the parts were not reused.
8295 On a busy system with a nearly-full drive, space can get reused in a few
8296 seconds. But there is no way to know for sure. If you have sensitive
8297 data, you may want to be sure that recovery is not possible by actually
8298 overwriting the file with non-sensitive data.
8300 However, even after doing that, it is possible to take the disk back
8301 to a laboratory and use a lot of sensitive (and expensive) equipment
8302 to look for the faint ``echoes'' of the original data underneath the
8303 overwritten data. If the data has only been overwritten once, it's not
8306 The best way to remove something irretrievably is to destroy the media
8307 it's on with acid, melt it down, or the like. For cheap removable media
8308 like floppy disks, this is the preferred method. However, hard drives
8309 are expensive and hard to melt, so the @command{shred} utility tries
8310 to achieve a similar effect non-destructively.
8312 This uses many overwrite passes, with the data patterns chosen to
8313 maximize the damage they do to the old data. While this will work on
8314 floppies, the patterns are designed for best effect on hard drives.
8315 For more details, see the source code and Peter Gutmann's paper
8316 @uref{http://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html,
8317 @cite{Secure Deletion of Data from Magnetic and Solid-State Memory}},
8318 from the proceedings of the Sixth @acronym{USENIX} Security Symposium (San Jose,
8319 California, July 22--25, 1996).
8321 @strong{Please note} that @command{shred} relies on a very important assumption:
8322 that the file system overwrites data in place. This is the traditional
8323 way to do things, but many modern file system designs do not satisfy this
8324 assumption. Exceptions include:
8329 Log-structured or journaled file systems, such as those supplied with
8330 AIX and Solaris, and JFS, ReiserFS, XFS, Ext3 (in @code{data=journal} mode),
8331 BFS, NTFS, etc.@: when they are configured to journal @emph{data}.
8334 File systems that write redundant data and carry on even if some writes
8335 fail, such as RAID-based file systems.
8338 File systems that make snapshots, such as Network Appliance's NFS server.
8341 File systems that cache in temporary locations, such as NFS version 3
8345 Compressed file systems.
8348 In the particular case of ext3 file systems, the above disclaimer applies (and
8349 @command{shred} is thus of limited effectiveness) only in @code{data=journal}
8350 mode, which journals file data in addition to just metadata. In both
8351 the @code{data=ordered} (default) and @code{data=writeback} modes,
8352 @command{shred} works as usual. Ext3 journaling modes can be changed
8353 by adding the @code{data=something} option to the mount options for a
8354 particular file system in the @file{/etc/fstab} file, as documented in
8355 the mount man page (man mount).
8357 If you are not sure how your file system operates, then you should assume
8358 that it does not overwrite data in place, which means that shred cannot
8359 reliably operate on regular files in your file system.
8361 Generally speaking, it is more reliable to shred a device than a file,
8362 since this bypasses the problem of file system design mentioned above.
8363 However, even shredding devices is not always completely reliable. For
8364 example, most disks map out bad sectors invisibly to the application; if
8365 the bad sectors contain sensitive data, @command{shred} won't be able to
8368 @command{shred} makes no attempt to detect or report this problem, just as
8369 it makes no attempt to do anything about backups. However, since it is
8370 more reliable to shred devices than files, @command{shred} by default does
8371 not truncate or remove the output file. This default is more suitable
8372 for devices, which typically cannot be truncated and should not be
8375 Finally, consider the risk of backups and mirrors.
8376 File system backups and remote mirrors may contain copies of the
8377 file that cannot be removed, and that will allow a shredded file
8378 to be recovered later. So if you keep any data you may later want
8379 to destroy using @command{shred}, be sure that it is not backed up or mirrored.
8382 shred [@var{option}]@dots{} @var{file}[@dots{}]
8385 The program accepts the following options. Also see @ref{Common options}.
8393 @cindex force deletion
8394 Override file permissions if necessary to allow overwriting.
8397 @itemx -n @var{NUMBER}
8398 @itemx --iterations=@var{NUMBER}
8399 @opindex -n @var{NUMBER}
8400 @opindex --iterations=@var{NUMBER}
8401 @cindex iterations, selecting the number of
8402 By default, @command{shred} uses 25 passes of overwrite. This is enough
8403 for all of the useful overwrite patterns to be used at least once.
8404 You can reduce this to save time, or increase it if you have a lot of
8407 @item --random-source=@var{file}
8408 @opindex --random-source
8409 @cindex random source for shredding
8410 Use @var{file} as a source of random data used to overwrite and to
8411 choose pass ordering. @xref{Random sources}.
8413 @item -s @var{BYTES}
8414 @itemx --size=@var{BYTES}
8415 @opindex -s @var{BYTES}
8416 @opindex --size=@var{BYTES}
8417 @cindex size of file to shred
8418 Shred the first @var{BYTES} bytes of the file. The default is to shred
8419 the whole file. @var{BYTES} can be followed by a size specification like
8420 @samp{K}, @samp{M}, or @samp{G} to specify a multiple. @xref{Block size}.
8426 @cindex removing files after shredding
8427 After shredding a file, truncate it (if possible) and then remove it.
8428 If a file has multiple links, only the named links will be removed.
8434 Display to standard error all status updates as sterilization proceeds.
8440 By default, @command{shred} rounds the size of a regular file up to the next
8441 multiple of the file system block size to fully erase the last block of the file.
8442 Use @option{--exact} to suppress that behavior.
8443 Thus, by default if you shred a 10-byte regular file on a system with 512-byte
8444 blocks, the resulting file will be 512 bytes long. With this option,
8445 shred does not increase the apparent size of the file.
8451 Normally, the last pass that @command{shred} writes is made up of
8452 random data. If this would be conspicuous on your hard drive (for
8453 example, because it looks like encrypted data), or you just think
8454 it's tidier, the @option{--zero} option adds an additional overwrite pass with
8455 all zero bits. This is in addition to the number of passes specified
8456 by the @option{--iterations} option.
8460 You might use the following command to erase all trace of the
8461 file system you'd created on the floppy disk in your first drive.
8462 That command takes about 20 minutes to erase a ``1.44MB'' (actually
8466 shred --verbose /dev/fd0
8469 Similarly, to erase all data on a selected partition of
8470 your hard disk, you could give a command like this:
8473 shred --verbose /dev/sda5
8476 A @var{file} of @samp{-} denotes standard output.
8477 The intended use of this is to shred a removed temporary file.
8481 i=`tempfile -m 0600`
8484 echo "Hello, world" >&3
8489 However, the command @samp{shred - >file} does not shred the contents
8490 of @var{file}, since the shell truncates @var{file} before invoking
8491 @command{shred}. Use the command @samp{shred file} or (if using a
8492 Bourne-compatible shell) the command @samp{shred - 1<>file} instead.
8497 @node Special file types
8498 @chapter Special file types
8500 @cindex special file types
8501 @cindex file types, special
8503 This chapter describes commands which create special types of files (and
8504 @command{rmdir}, which removes directories, one special file type).
8506 @cindex special file types
8508 Although Unix-like operating systems have markedly fewer special file
8509 types than others, not @emph{everything} can be treated only as the
8510 undifferentiated byte stream of @dfn{normal files}. For example, when a
8511 file is created or removed, the system must record this information,
8512 which it does in a @dfn{directory}---a special type of file. Although
8513 you can read directories as normal files, if you're curious, in order
8514 for the system to do its job it must impose a structure, a certain
8515 order, on the bytes of the file. Thus it is a ``special'' type of file.
8517 Besides directories, other special file types include named pipes
8518 (FIFOs), symbolic links, sockets, and so-called @dfn{special files}.
8521 * link invocation:: Make a hard link via the link syscall
8522 * ln invocation:: Make links between files.
8523 * mkdir invocation:: Make directories.
8524 * mkfifo invocation:: Make FIFOs (named pipes).
8525 * mknod invocation:: Make block or character special files.
8526 * readlink invocation:: Print the referent of a symbolic link.
8527 * rmdir invocation:: Remove empty directories.
8528 * unlink invocation:: Remove files via the unlink syscall
8532 @node link invocation
8533 @section @command{link}: Make a hard link via the link syscall
8536 @cindex links, creating
8537 @cindex hard links, creating
8538 @cindex creating links (hard only)
8540 @command{link} creates a single hard link at a time.
8541 It is a minimalist interface to the system-provided
8542 @code{link} function. @xref{Hard Links, , , libc,
8543 The GNU C Library Reference Manual}.
8544 It avoids the bells and whistles of the more commonly-used
8545 @command{ln} command (@pxref{ln invocation}).
8549 link @var{filename} @var{linkname}
8552 @var{filename} must specify an existing file, and @var{linkname}
8553 must specify a nonexistent entry in an existing directory.
8554 @command{link} simply calls @code{link (@var{filename}, @var{linkname})}
8557 On a @acronym{GNU} system, this command acts like @samp{ln --directory
8558 --no-target-directory @var{filename} @var{linkname}}. However, the
8559 @option{--directory} and @option{--no-target-directory} options are
8560 not specified by @acronym{POSIX}, and the @command{link} command is
8561 more portable in practice.
8567 @section @command{ln}: Make links between files
8570 @cindex links, creating
8571 @cindex hard links, creating
8572 @cindex symbolic (soft) links, creating
8573 @cindex creating links (hard or soft)
8575 @cindex file systems and hard links
8576 @command{ln} makes links between files. By default, it makes hard links;
8577 with the @option{-s} option, it makes symbolic (or @dfn{soft}) links.
8581 ln [@var{option}]@dots{} [-T] @var{target} @var{linkname}
8582 ln [@var{option}]@dots{} @var{target}
8583 ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
8584 ln [@var{option}]@dots{} -t @var{directory} @var{target}@dots{}
8590 If two file names are given, @command{ln} creates a link to the first
8591 file from the second.
8594 If one @var{target} is given, @command{ln} creates a link to that file
8595 in the current directory.
8598 If the @option{--target-directory} (@option{-t}) option is given, or
8599 failing that if the last file is a directory and the
8600 @option{--no-target-directory} (@option{-T}) option is not given,
8601 @command{ln} creates a link to each @var{target} file in the specified
8602 directory, using the @var{target}s' names.
8606 Normally @command{ln} does not remove existing files. Use the
8607 @option{--force} (@option{-f}) option to remove them unconditionally,
8608 the @option{--interactive} (@option{-i}) option to remove them
8609 conditionally, and the @option{--backup} (@option{-b}) option to
8612 @cindex hard link, defined
8613 @cindex inode, and hard links
8614 A @dfn{hard link} is another name for an existing file; the link and the
8615 original are indistinguishable. Technically speaking, they share the
8616 same inode, and the inode contains all the information about a
8617 file---indeed, it is not incorrect to say that the inode @emph{is} the
8618 file. On all existing implementations, you cannot make a hard link to
8619 a directory, and hard links cannot cross file system boundaries. (These
8620 restrictions are not mandated by @acronym{POSIX}, however.)
8622 @cindex dereferencing symbolic links
8623 @cindex symbolic link, defined
8624 @dfn{Symbolic links} (@dfn{symlinks} for short), on the other hand, are
8625 a special file type (which not all kernels support: System V release 3
8626 (and older) systems lack symlinks) in which the link file actually
8627 refers to a different file, by name. When most operations (opening,
8628 reading, writing, and so on) are passed the symbolic link file, the
8629 kernel automatically @dfn{dereferences} the link and operates on the
8630 target of the link. But some operations (e.g., removing) work on the
8631 link file itself, rather than on its target. @xref{Symbolic Links,,,
8632 libc, The GNU C Library Reference Manual}.
8634 The program accepts the following options. Also see @ref{Common options}.
8645 @opindex --directory
8646 @cindex hard links to directories
8647 Allow users with appropriate privileges to attempt to make hard links
8649 However, note that this will probably fail due to
8650 system restrictions, even for the super-user.
8656 Remove existing destination files.
8659 @itemx --interactive
8661 @opindex --interactive
8662 @cindex prompting, and @command{ln}
8663 Prompt whether to remove existing destination files.
8666 @itemx --no-dereference
8668 @opindex --no-dereference
8669 Do not treat the last operand specially when it is a symbolic link to
8670 a directory. Instead, treat it as if it were a normal file.
8672 When the destination is an actual directory (not a symlink to one),
8673 there is no ambiguity. The link is created in that directory.
8674 But when the specified destination is a symlink to a directory,
8675 there are two ways to treat the user's request. @command{ln} can
8676 treat the destination just as it would a normal directory and create
8677 the link in it. On the other hand, the destination can be viewed as a
8678 non-directory---as the symlink itself. In that case, @command{ln}
8679 must delete or backup that symlink before creating the new link.
8680 The default is to treat a destination that is a symlink to a directory
8681 just like a directory.
8683 This option is weaker than the @option{--no-target-directory}
8684 (@option{-T}) option, so it has no effect if both options are given.
8690 Make symbolic links instead of hard links. This option merely produces
8691 an error message on systems that do not support symbolic links.
8697 @optNoTargetDirectory
8703 Print the name of each file after linking it successfully.
8714 # Create link ../a pointing to a in that directory.
8715 # Not really useful because it points to itself.
8720 # Change to the target before creating symlinks to avoid being confused.
8726 # Hard coded file names don't move well.
8727 ln -s $(pwd)/a /some/dir/
8731 # Relative file names survive directory moves and also
8732 # work across networked file systems.
8733 ln -s afile anotherfile
8734 ln -s ../adir/afile yetanotherfile
8738 @node mkdir invocation
8739 @section @command{mkdir}: Make directories
8742 @cindex directories, creating
8743 @cindex creating directories
8745 @command{mkdir} creates directories with the specified names. Synopsis:
8748 mkdir [@var{option}]@dots{} @var{name}@dots{}
8751 @command{mkdir} creates each directory @var{name} in the order given.
8752 It reports an error if @var{name} already exists, unless the
8753 @option{-p} option is given and @var{name} is a directory.
8755 The program accepts the following options. Also see @ref{Common options}.
8760 @itemx --mode=@var{mode}
8763 @cindex modes of created directories, setting
8764 Set the file permission bits of created directories to @var{mode},
8765 which uses the same syntax as
8766 in @command{chmod} and uses @samp{a=rwx} (read, write and execute allowed for
8767 everyone) for the point of the departure. @xref{File permissions}.
8769 Normally the directory has the desired file mode bits at the moment it
8770 is created. As a @acronym{GNU} extension, @var{mode} may also mention
8771 special mode bits, but in this case there may be a temporary window
8772 during which the directory exists but its special mode bits are
8773 incorrect. @xref{Directory Setuid and Setgid}, for how the
8774 set-user-ID and set-group-ID bits of directories are inherited unless
8775 overridden in this way.
8781 @cindex parent directories, creating
8782 Make any missing parent directories for each argument, setting their
8783 file permission bits to the umask modified by @samp{u+wx}. Ignore
8784 existing parent directories, and do not change their file permission
8787 To set the file permission bits of any newly-created parent
8788 directories to a value that includes @samp{u+wx}, you can set the
8789 umask before invoking @command{mkdir}. For example, if the shell
8790 command @samp{(umask u=rwx,go=rx; mkdir -p P/Q)} creates the parent
8791 @file{P} it sets the parent's permission bits to @samp{u=rwx,go=rx}.
8792 To set a parent's special mode bits as well, you can invoke
8793 @command{chmod} after @command{mkdir}. @xref{Directory Setuid and
8794 Setgid}, for how the set-user-ID and set-group-ID bits of
8795 newly-created parent directories are inherited.
8801 Print a message for each created directory. This is most useful with
8808 @node mkfifo invocation
8809 @section @command{mkfifo}: Make FIFOs (named pipes)
8812 @cindex FIFOs, creating
8813 @cindex named pipes, creating
8814 @cindex creating FIFOs (named pipes)
8816 @command{mkfifo} creates FIFOs (also called @dfn{named pipes}) with the
8817 specified names. Synopsis:
8820 mkfifo [@var{option}] @var{name}@dots{}
8823 A @dfn{FIFO} is a special file type that permits independent processes
8824 to communicate. One process opens the FIFO file for writing, and
8825 another for reading, after which data can flow as with the usual
8826 anonymous pipe in shells or elsewhere.
8828 The program accepts the following option. Also see @ref{Common options}.
8833 @itemx --mode=@var{mode}
8836 @cindex modes of created FIFOs, setting
8837 Set the mode of created FIFOs to @var{mode}, which is symbolic as in
8838 @command{chmod} and uses @samp{a=rw} (read and write allowed for everyone)
8839 for the point of departure. @var{mode} should specify only file
8840 permission bits. @xref{File permissions}.
8847 @node mknod invocation
8848 @section @command{mknod}: Make block or character special files
8851 @cindex block special files, creating
8852 @cindex character special files, creating
8854 @command{mknod} creates a FIFO, character special file, or block special
8855 file with the specified name. Synopsis:
8858 mknod [@var{option}]@dots{} @var{name} @var{type} [@var{major} @var{minor}]
8861 @cindex special files
8862 @cindex block special files
8863 @cindex character special files
8864 Unlike the phrase ``special file type'' above, the term @dfn{special
8865 file} has a technical meaning on Unix: something that can generate or
8866 receive data. Usually this corresponds to a physical piece of hardware,
8867 e.g., a printer or a disk. (These files are typically created at
8868 system-configuration time.) The @command{mknod} command is what creates
8869 files of this type. Such devices can be read either a character at a
8870 time or a ``block'' (many characters) at a time, hence we say there are
8871 @dfn{block special} files and @dfn{character special} files.
8873 @c mknod is a shell built-in at least with OpenBSD's /bin/sh
8874 @mayConflictWithShellBuiltIn{mknod}
8876 The arguments after @var{name} specify the type of file to make:
8881 @opindex p @r{for FIFO file}
8885 @opindex b @r{for block special file}
8886 for a block special file
8889 @c Don't document the `u' option -- it's just a synonym for `c'.
8890 @c Do *any* versions of mknod still use it?
8892 @opindex c @r{for character special file}
8893 @c @opindex u @r{for character special file}
8894 for a character special file
8898 When making a block or character special file, the major and minor
8899 device numbers must be given after the file type.
8900 If a major or minor device number begins with @samp{0x} or @samp{0X},
8901 it is interpreted as hexadecimal; otherwise, if it begins with @samp{0},
8902 as octal; otherwise, as decimal.
8904 The program accepts the following option. Also see @ref{Common options}.
8909 @itemx --mode=@var{mode}
8912 Set the mode of created files to @var{mode}, which is symbolic as in
8913 @command{chmod} and uses @samp{a=rw} as the point of departure.
8914 @var{mode} should specify only file permission bits.
8915 @xref{File permissions}.
8922 @node readlink invocation
8923 @section @command{readlink}: Print the referent of a symbolic link
8926 @cindex displaying value of a symbolic link
8928 @command{readlink} may work in one of two supported modes:
8934 @command{readlink} outputs the value of the given symbolic link.
8935 If @command{readlink} is invoked with an argument other than the name
8936 of a symbolic link, it produces no output and exits with a nonzero exit code.
8938 @item Canonicalize mode
8940 @command{readlink} outputs the absolute name of the given file which contains
8941 no @file{.}, @file{..} components nor any repeated separators
8942 (@file{/}) or symbolic links.
8947 readlink [@var{option}] @var{file}
8950 By default, @command{readlink} operates in readlink mode.
8952 The program accepts the following options. Also see @ref{Common options}.
8957 @itemx --canonicalize
8959 @opindex --canonicalize
8960 Activate canonicalize mode.
8961 If any component of the file name except the last one is missing or unavailable,
8962 @command{readlink} produces no output and exits with a nonzero exit code.
8965 @itemx --canonicalize-existing
8967 @opindex --canonicalize-existing
8968 Activate canonicalize mode.
8969 If any component is missing or unavailable, @command{readlink} produces
8970 no output and exits with a nonzero exit code.
8973 @itemx --canonicalize-missing
8975 @opindex --canonicalize-missing
8976 Activate canonicalize mode.
8977 If any component is missing or unavailable, @command{readlink} treats it
8983 @opindex --no-newline
8984 Do not output the trailing newline.
8994 Suppress most error messages.
9000 Report error messages.
9004 The @command{readlink} utility first appeared in OpenBSD 2.1.
9009 @node rmdir invocation
9010 @section @command{rmdir}: Remove empty directories
9013 @cindex removing empty directories
9014 @cindex directories, removing empty
9016 @command{rmdir} removes empty directories. Synopsis:
9019 rmdir [@var{option}]@dots{} @var{directory}@dots{}
9022 If any @var{directory} argument does not refer to an existing empty
9023 directory, it is an error.
9025 The program accepts the following options. Also see @ref{Common options}.
9029 @item --ignore-fail-on-non-empty
9030 @opindex --ignore-fail-on-non-empty
9031 @cindex directory deletion, ignoring failures
9032 Ignore each failure to remove a directory that is solely because
9033 the directory is non-empty.
9039 @cindex parent directories, removing
9040 Remove @var{directory}, then try to remove each component of @var{directory}.
9041 So, for example, @samp{rmdir -p a/b/c} is similar to @samp{rmdir a/b/c a/b a}.
9042 As such, it fails if any of those directories turns out not to be empty.
9043 Use the @option{--ignore-fail-on-non-empty} option to make it so such
9044 a failure does not evoke a diagnostic and does not cause @command{rmdir} to
9045 exit unsuccessfully.
9051 @cindex directory deletion, reporting
9052 Give a diagnostic for each successful removal.
9053 @var{directory} is removed.
9057 @xref{rm invocation}, for how to remove non-empty directories (recursively).
9062 @node unlink invocation
9063 @section @command{unlink}: Remove files via the unlink syscall
9066 @cindex removing files or directories (via the unlink syscall)
9068 @command{unlink} deletes a single specified file name.
9069 It is a minimalist interface to the system-provided
9070 @code{unlink} function. @xref{Deleting Files, , , libc,
9071 The GNU C Library Reference Manual}. Synopsis:
9072 It avoids the bells and whistles of the more commonly-used
9073 @command{rm} command (@pxref{rm invocation}).
9076 unlink @var{filename}
9079 On some systems @code{unlink} can be used to delete the name of a
9080 directory. On others, it can be used that way only by a privileged user.
9081 In the GNU system @code{unlink} can never delete the name of a directory.
9083 The @command{unlink} command honors the @option{--help} and
9084 @option{--version} options. To remove a file whose name begins with
9085 @samp{-}, prefix the name with @samp{./}, e.g., @samp{unlink ./--help}.
9090 @node Changing file attributes
9091 @chapter Changing file attributes
9093 @cindex changing file attributes
9094 @cindex file attributes, changing
9095 @cindex attributes, file
9097 A file is not merely its contents, a name, and a file type
9098 (@pxref{Special file types}). A file also has an owner (a user ID), a
9099 group (a group ID), permissions (what the owner can do with the file,
9100 what people in the group can do, and what everyone else can do), various
9101 timestamps, and other information. Collectively, we call these a file's
9104 These commands change file attributes.
9107 * chgrp invocation:: Change file groups.
9108 * chmod invocation:: Change access permissions.
9109 * chown invocation:: Change file owners and groups.
9110 * touch invocation:: Change file timestamps.
9114 @node chown invocation
9115 @section @command{chown}: Change file owner and group
9118 @cindex file ownership, changing
9119 @cindex group ownership, changing
9120 @cindex changing file ownership
9121 @cindex changing group ownership
9123 @command{chown} changes the user and/or group ownership of each given @var{file}
9124 to @var{new-owner} or to the user and group of an existing reference file.
9128 chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@} @var{file}@dots{}
9131 If used, @var{new-owner} specifies the new owner and/or group as follows
9132 (with no embedded white space):
9135 [@var{owner}] [ : [@var{group}] ]
9142 If only an @var{owner} (a user name or numeric user ID) is given, that
9143 user is made the owner of each given file, and the files' group is not
9146 @item owner@samp{:}group
9147 If the @var{owner} is followed by a colon and a @var{group} (a
9148 group name or numeric group ID), with no spaces between them, the group
9149 ownership of the files is changed as well (to @var{group}).
9152 If a colon but no group name follows @var{owner}, that user is
9153 made the owner of the files and the group of the files is changed to
9154 @var{owner}'s login group.
9157 If the colon and following @var{group} are given, but the owner
9158 is omitted, only the group of the files is changed; in this case,
9159 @command{chown} performs the same function as @command{chgrp}.
9162 If only a colon is given, or if @var{new-owner} is empty, neither the
9163 owner nor the group is changed.
9167 If @var{owner} or @var{group} is intended to represent a numeric user
9168 or group ID, then you may specify it with a leading @samp{+}.
9169 @xref{Disambiguating names and IDs}.
9171 Some older scripts may still use @samp{.} in place of the @samp{:} separator.
9172 @acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not
9173 require support for that, but for backward compatibility @acronym{GNU}
9174 @command{chown} supports @samp{.} so long as no ambiguity results.
9175 New scripts should avoid the use of @samp{.} because it is not
9176 portable, and because it has undesirable results if the entire
9177 @var{owner@samp{.}group} happens to identify a user whose name
9180 The @command{chown} command sometimes clears the set-user-ID or
9181 set-group-ID permission bits. This behavior depends on the policy and
9182 functionality of the underlying @code{chown} system call, which may
9183 make system-dependent file mode modifications outside the control of
9184 the @command{chown} command. For example, the @command{chown} command
9185 might not affect those bits when invoked by a user with appropriate
9186 privileges, or when the
9187 bits signify some function other than executable permission (e.g.,
9189 When in doubt, check the underlying system behavior.
9191 The program accepts the following options. Also see @ref{Common options}.
9199 @cindex changed owners, verbosely describing
9200 Verbosely describe the action for each @var{file} whose ownership
9209 @cindex error messages, omitting
9210 Do not print error messages about files whose ownership cannot be
9213 @itemx @w{@kbd{--from}=@var{old-owner}}
9215 @cindex symbolic links, changing owner
9216 Change a @var{file}'s ownership only if it has current attributes specified
9217 by @var{old-owner}. @var{old-owner} has the same form as @var{new-owner}
9219 This option is useful primarily from a security standpoint in that
9220 it narrows considerably the window of potential abuse.
9221 For example, to reflect a user ID numbering change for one user's files
9222 without an option like this, @code{root} might run
9225 find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER
9228 But that is dangerous because the interval between when the @command{find}
9229 tests the existing file's owner and when the @command{chown} is actually run
9231 One way to narrow the gap would be to invoke chown for each file
9235 find / -owner OLDUSER -exec chown -h NEWUSER @{@} \;
9238 But that is very slow if there are many affected files.
9239 With this option, it is safer (the gap is narrower still)
9240 though still not perfect:
9243 chown -h -R --from=OLDUSER NEWUSER /
9247 @opindex --dereference
9248 @cindex symbolic links, changing owner
9250 Do not act on symbolic links themselves but rather on what they point to.
9251 This is the default.
9254 @itemx --no-dereference
9256 @opindex --no-dereference
9257 @cindex symbolic links, changing owner
9259 Act on symbolic links themselves instead of what they point to.
9260 This mode relies on the @code{lchown} system call.
9261 On systems that do not provide the @code{lchown} system call,
9262 @command{chown} fails when a file specified on the command line
9264 By default, no diagnostic is issued for symbolic links encountered
9265 during a recursive traversal, but see @option{--verbose}.
9267 @itemx --preserve-root
9268 @opindex --preserve-root
9269 @cindex root directory, disallow recursive modification
9270 Fail upon any attempt to recursively change the root directory, @file{/}.
9271 Without @option{--recursive}, this option has no effect.
9272 @xref{Treating / specially}.
9274 @itemx --no-preserve-root
9275 @opindex --no-preserve-root
9276 @cindex root directory, allow recursive modification
9277 Cancel the effect of any preceding @option{--preserve-root} option.
9278 @xref{Treating / specially}.
9280 @item --reference=@var{ref_file}
9281 @opindex --reference
9282 Change the user and group of each @var{file} to be the same as those of
9283 @var{ref_file}. If @var{ref_file} is a symbolic link, do not use the
9284 user and group of the symbolic link, but rather those of the file it
9291 Output a diagnostic for every file processed.
9292 If a symbolic link is encountered during a recursive traversal
9293 on a system without the @code{lchown} system call, and @option{--no-dereference}
9294 is in effect, then issue a diagnostic saying neither the symbolic link nor
9295 its referent is being changed.
9300 @opindex --recursive
9301 @cindex recursively changing file ownership
9302 Recursively change ownership of directories and their contents.
9305 @xref{Traversing symlinks}.
9308 @xref{Traversing symlinks}.
9311 @xref{Traversing symlinks}.
9320 # Change the owner of /u to "root".
9323 # Likewise, but also change its group to "staff".
9326 # Change the owner of /u and subfiles to "root".
9331 @node chgrp invocation
9332 @section @command{chgrp}: Change group ownership
9335 @cindex group ownership, changing
9336 @cindex changing group ownership
9338 @command{chgrp} changes the group ownership of each given @var{file}
9339 to @var{group} (which can be either a group name or a numeric group ID)
9340 or to the group of an existing reference file. Synopsis:
9343 chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@} @var{file}@dots{}
9346 If @var{group} is intended to represent a
9347 numeric group ID, then you may specify it with a leading @samp{+}.
9348 @xref{Disambiguating names and IDs}.
9350 The program accepts the following options. Also see @ref{Common options}.
9358 @cindex changed files, verbosely describing
9359 Verbosely describe the action for each @var{file} whose group actually
9368 @cindex error messages, omitting
9369 Do not print error messages about files whose group cannot be
9373 @opindex --dereference
9374 @cindex symbolic links, changing owner
9376 Do not act on symbolic links themselves but rather on what they point to.
9377 This is the default.
9380 @itemx --no-dereference
9382 @opindex --no-dereference
9383 @cindex symbolic links, changing group
9385 Act on symbolic links themselves instead of what they point to.
9386 This mode relies on the @code{lchown} system call.
9387 On systems that do not provide the @code{lchown} system call,
9388 @command{chgrp} fails when a file specified on the command line
9390 By default, no diagnostic is issued for symbolic links encountered
9391 during a recursive traversal, but see @option{--verbose}.
9393 @itemx --preserve-root
9394 @opindex --preserve-root
9395 @cindex root directory, disallow recursive modification
9396 Fail upon any attempt to recursively change the root directory, @file{/}.
9397 Without @option{--recursive}, this option has no effect.
9398 @xref{Treating / specially}.
9400 @itemx --no-preserve-root
9401 @opindex --no-preserve-root
9402 @cindex root directory, allow recursive modification
9403 Cancel the effect of any preceding @option{--preserve-root} option.
9404 @xref{Treating / specially}.
9406 @item --reference=@var{ref_file}
9407 @opindex --reference
9408 Change the group of each @var{file} to be the same as that of
9409 @var{ref_file}. If @var{ref_file} is a symbolic link, do not use the
9410 group of the symbolic link, but rather that of the file it refers to.
9416 Output a diagnostic for every file processed.
9417 If a symbolic link is encountered during a recursive traversal
9418 on a system without the @code{lchown} system call, and @option{--no-dereference}
9419 is in effect, then issue a diagnostic saying neither the symbolic link nor
9420 its referent is being changed.
9425 @opindex --recursive
9426 @cindex recursively changing group ownership
9427 Recursively change the group ownership of directories and their contents.
9430 @xref{Traversing symlinks}.
9433 @xref{Traversing symlinks}.
9436 @xref{Traversing symlinks}.
9445 # Change the group of /u to "staff".
9448 # Change the group of /u and subfiles to "staff".
9453 @node chmod invocation
9454 @section @command{chmod}: Change access permissions
9457 @cindex changing access permissions
9458 @cindex access permissions, changing
9459 @cindex permissions, changing access
9461 @command{chmod} changes the access permissions of the named files. Synopsis:
9464 chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{ref_file}@} @var{file}@dots{}
9467 @cindex symbolic links, permissions of
9468 @command{chmod} never changes the permissions of symbolic links, since
9469 the @command{chmod} system call cannot change their permissions.
9470 This is not a problem since the permissions of symbolic links are
9471 never used. However, for each symbolic link listed on the command
9472 line, @command{chmod} changes the permissions of the pointed-to file.
9473 In contrast, @command{chmod} ignores symbolic links encountered during
9474 recursive directory traversals.
9476 A successful use of @command{chmod} clears the set-group-ID bit of a
9477 regular file if the file's group ID does not match the user's
9478 effective group ID or one of the user's supplementary group IDs,
9479 unless the user has appropriate privileges. Additional restrictions
9480 may cause the set-user-ID and set-group-ID bits of @var{mode} or
9481 @var{ref_file} to be ignored. This behavior depends on the policy and
9482 functionality of the underlying @code{chmod} system call. When in
9483 doubt, check the underlying system behavior.
9485 If used, @var{mode} specifies the new file mode bits.
9486 For details, see the section on @ref{File permissions}.
9487 If you really want @var{mode} to have a leading @samp{-}, you should
9488 use @option{--} first, e.g., @samp{chmod -- -w file}. Typically,
9489 though, @samp{chmod a-w file} is preferable, and @command{chmod -w
9490 file} (without the @option{--}) complains if it behaves differently
9491 from what @samp{chmod a-w file} would do.
9493 The program accepts the following options. Also see @ref{Common options}.
9501 Verbosely describe the action for each @var{file} whose permissions
9510 @cindex error messages, omitting
9511 Do not print error messages about files whose permissions cannot be
9514 @itemx --preserve-root
9515 @opindex --preserve-root
9516 @cindex root directory, disallow recursive modification
9517 Fail upon any attempt to recursively change the root directory, @file{/}.
9518 Without @option{--recursive}, this option has no effect.
9519 @xref{Treating / specially}.
9521 @itemx --no-preserve-root
9522 @opindex --no-preserve-root
9523 @cindex root directory, allow recursive modification
9524 Cancel the effect of any preceding @option{--preserve-root} option.
9525 @xref{Treating / specially}.
9531 Verbosely describe the action or non-action taken for every @var{file}.
9533 @item --reference=@var{ref_file}
9534 @opindex --reference
9535 Change the mode of each @var{file} to be the same as that of @var{ref_file}.
9536 @xref{File permissions}.
9537 If @var{ref_file} is a symbolic link, do not use the mode
9538 of the symbolic link, but rather that of the file it refers to.
9543 @opindex --recursive
9544 @cindex recursively changing access permissions
9545 Recursively change permissions of directories and their contents.
9552 @node touch invocation
9553 @section @command{touch}: Change file timestamps
9556 @cindex changing file timestamps
9557 @cindex file timestamps, changing
9558 @cindex timestamps, changing file
9560 @command{touch} changes the access and/or modification times of the
9561 specified files. Synopsis:
9564 touch [@var{option}]@dots{} @var{file}@dots{}
9567 @cindex empty files, creating
9568 Any @var{file} argument that does not exist is created empty.
9570 A @var{file} argument string of @samp{-} is handled specially and
9571 causes @command{touch} to change the times of the file associated with
9574 @cindex permissions, for changing file timestamps
9575 If changing both the access and modification times to the current
9576 time, @command{touch} can change the timestamps for files that the user
9577 running it does not own but has write permission for. Otherwise, the
9578 user must own the files.
9580 Although @command{touch} provides options for changing two of the times---the
9581 times of last access and modification---of a file, there is actually
9582 a third one as well: the inode change time. This is often referred to
9583 as a file's @code{ctime}.
9584 The inode change time represents the time when the file's meta-information
9585 last changed. One common example of this is when the permissions of a
9586 file change. Changing the permissions doesn't access the file, so
9587 the atime doesn't change, nor does it modify the file, so the mtime
9588 doesn't change. Yet, something about the file itself has changed,
9589 and this must be noted somewhere. This is the job of the ctime field.
9590 This is necessary, so that, for example, a backup program can make a
9591 fresh copy of the file, including the new permissions value.
9592 Another operation that modifies a file's ctime without affecting
9593 the others is renaming. In any case, it is not possible, in normal
9594 operations, for a user to change the ctime field to a user-specified value.
9597 Time stamps assume the time zone rules specified by the @env{TZ}
9598 environment variable, or by the system default rules if @env{TZ} is
9599 not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ},
9600 libc, The GNU C Library Reference Manual}.
9601 You can avoid ambiguities during
9602 daylight saving transitions by using @sc{utc} time stamps.
9604 The program accepts the following options. Also see @ref{Common options}.
9610 @itemx --time=access
9614 @opindex atime@r{, changing}
9615 @opindex access @r{time, changing}
9616 @opindex use @r{time, changing}
9617 Change the access time only.
9622 @opindex --no-create
9623 Do not create files that do not exist.
9626 @itemx --date=@var{time}
9630 Use @var{time} instead of the current time. It can contain month names,
9631 time zones, @samp{am} and @samp{pm}, @samp{yesterday}, etc. For
9632 example, @option{--date="2004-02-27 14:19:13.489392193 +0530"}
9633 specifies the instant of time that is 489,392,193 nanoseconds after
9634 February 27, 2004 at 2:19:13 PM in a time zone that is 5 hours and 30
9635 minutes east of @acronym{UTC}. @xref{Date input formats}.
9636 File systems that do not support high-resolution time stamps
9637 silently ignore any excess precision here.
9641 @cindex BSD @command{touch} compatibility
9642 Ignored; for compatibility with BSD versions of @command{touch}.
9646 @itemx --time=modify
9649 @opindex mtime@r{, changing}
9650 @opindex modify @r{time, changing}
9651 Change the modification time only.
9654 @itemx --reference=@var{file}
9656 @opindex --reference
9657 Use the times of the reference @var{file} instead of the current time.
9658 If this option is combined with the @option{--date=@var{time}}
9659 (@option{-d @var{time}}) option, the reference @var{file}'s time is
9660 the origin for any relative @var{time}s given, but is otherwise ignored.
9661 For example, @samp{-r foo -d '-5 seconds'} specifies a time stamp
9662 equal to five seconds before the corresponding time stamp for @file{foo}.
9664 @item -t [[@var{CC}]@var{YY}]@var{MMDDhhmm}[.@var{ss}]
9665 Use the argument (optional four-digit or two-digit years, months,
9666 days, hours, minutes, optional seconds) instead of the current time.
9667 If the year is specified with only two digits, then @var{CC}
9668 is 20 for years in the range 0 @dots{} 68, and 19 for years in
9669 69 @dots{} 99. If no digits of the year are specified,
9670 the argument is interpreted as a date in the current year.
9674 @vindex _POSIX2_VERSION
9675 On older systems, @command{touch} supports an obsolete syntax, as follows.
9676 If no timestamp is given with any of the @option{-d}, @option{-r}, or
9677 @option{-t} options, and if there are two or more @var{file}s and the
9678 first @var{file} is of the form @samp{@var{MMDDhhmm}[@var{YY}]} and this
9679 would be a valid argument to the @option{-t} option (if the @var{YY}, if
9680 any, were moved to the front), and if the represented year
9681 is in the range 1969--1999, that argument is interpreted as the time
9682 for the other files instead of as a file name.
9683 This obsolete behavior can be enabled or disabled with the
9684 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
9685 conformance}), but portable scripts should avoid commands whose
9686 behavior depends on this variable.
9687 For example, use @samp{touch ./12312359 main.c} or @samp{touch -t
9688 12312359 main.c} rather than the ambiguous @samp{touch 12312359 main.c}.
9698 No disk can hold an infinite amount of data. These commands report
9699 how much disk storage is in use or available, report other file and
9700 file status information, and write buffers to disk.
9703 * df invocation:: Report file system disk space usage.
9704 * du invocation:: Estimate file space usage.
9705 * stat invocation:: Report file or file system status.
9706 * sync invocation:: Synchronize memory and disk.
9707 * truncate invocation:: Shrink or extend the size of a file.
9712 @section @command{df}: Report file system disk space usage
9715 @cindex file system disk usage
9716 @cindex disk usage by file system
9718 @command{df} reports the amount of disk space used and available on
9719 file systems. Synopsis:
9722 df [@var{option}]@dots{} [@var{file}]@dots{}
9725 With no arguments, @command{df} reports the space used and available on all
9726 currently mounted file systems (of all types). Otherwise, @command{df}
9727 reports on the file system containing each argument @var{file}.
9729 Normally the disk space is printed in units of
9730 1024 bytes, but this can be overridden (@pxref{Block size}).
9731 Non-integer quantities are rounded up to the next higher unit.
9733 @cindex disk device file
9734 @cindex device file, disk
9735 If an argument @var{file} is a disk device file containing a mounted
9736 file system, @command{df} shows the space available on that file system
9737 rather than on the file system containing the device node (i.e., the root
9738 file system). @sc{gnu} @command{df} does not attempt to determine the disk usage
9739 on unmounted file systems, because on most kinds of systems doing so
9740 requires extremely nonportable intimate knowledge of file system
9743 The program accepts the following options. Also see @ref{Common options}.
9751 @cindex automounter file systems
9752 @cindex ignore file systems
9753 Include in the listing dummy file systems, which
9754 are omitted by default. Such file systems are typically special-purpose
9755 pseudo-file-systems, such as automounter entries.
9758 @itemx --block-size=@var{size}
9760 @opindex --block-size
9761 @cindex file system sizes
9762 Scale sizes by @var{size} before printing them (@pxref{Block size}).
9763 For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes.
9767 @cindex grand total of disk size, usage and available space
9768 Print a grand total of all arguments after all arguments have
9769 been processed. This can be used to find out the total disk size, usage
9770 and available space of all listed devices.
9776 Equivalent to @option{--si}.
9783 List inode usage information instead of block usage. An inode (short
9784 for index node) contains information about a file such as its owner,
9785 permissions, timestamps, and location on the disk.
9789 @cindex kibibytes for file system sizes
9790 Print sizes in 1024-byte blocks, overriding the default block size
9791 (@pxref{Block size}).
9792 This option is equivalent to @option{--block-size=1K}.
9798 @cindex file system types, limiting output to certain
9799 Limit the listing to local file systems. By default, remote file systems
9804 @cindex file system space, retrieving old data more quickly
9805 Do not invoke the @code{sync} system call before getting any usage data.
9806 This may make @command{df} run significantly faster on systems with many
9807 disks, but on some systems (notably SunOS) the results may be slightly
9808 out of date. This is the default.
9811 @itemx --portability
9813 @opindex --portability
9814 @cindex one-line output format
9815 @cindex @acronym{POSIX} output format
9816 @cindex portable output format
9817 @cindex output format, portable
9818 Use the @acronym{POSIX} output format. This is like the default format except
9823 The information about each file system is always printed on exactly
9824 one line; a mount device is never put on a line by itself. This means
9825 that if the mount device name is more than 20 characters long (e.g., for
9826 some network mounts), the columns are misaligned.
9829 The labels in the header output line are changed to conform to @acronym{POSIX}.
9832 The default block size and output format are unaffected by the
9833 @env{DF_BLOCK_SIZE}, @env{BLOCK_SIZE} and @env{BLOCKSIZE} environment
9834 variables. However, the default block size is still affected by
9835 @env{POSIXLY_CORRECT}: it is 512 if @env{POSIXLY_CORRECT} is set, 1024
9836 otherwise. @xref{Block size}.
9843 @cindex file system space, retrieving current data more slowly
9844 Invoke the @code{sync} system call before getting any usage data. On
9845 some systems (notably SunOS), doing this yields more up to date results,
9846 but in general this option makes @command{df} much slower, especially when
9847 there are many or very busy file systems.
9849 @item -t @var{fstype}
9850 @itemx --type=@var{fstype}
9853 @cindex file system types, limiting output to certain
9854 Limit the listing to file systems of type @var{fstype}. Multiple
9855 file system types can be specified by giving multiple @option{-t} options.
9856 By default, nothing is omitted.
9861 @opindex --print-type
9862 @cindex file system types, printing
9863 Print each file system's type. The types printed here are the same ones
9864 you can include or exclude with @option{-t} and @option{-x}. The particular
9865 types printed are whatever is supported by the system. Here are some of
9866 the common names (this list is certainly not exhaustive):
9871 @cindex @acronym{NFS} file system type
9872 An @acronym{NFS} file system, i.e., one mounted over a network from another
9873 machine. This is the one type name which seems to be used uniformly by
9876 @item 4.2@r{, }ufs@r{, }efs@dots{}
9877 @cindex Linux file system types
9878 @cindex local file system types
9879 @opindex 4.2 @r{file system type}
9880 @opindex ufs @r{file system type}
9881 @opindex efs @r{file system type}
9882 A file system on a locally-mounted hard disk. (The system might even
9883 support more than one type here; Linux does.)
9885 @item hsfs@r{, }cdfs
9886 @cindex CD-ROM file system type
9887 @cindex High Sierra file system
9888 @opindex hsfs @r{file system type}
9889 @opindex cdfs @r{file system type}
9890 A file system on a CD-ROM drive. HP-UX uses @samp{cdfs}, most other
9891 systems use @samp{hsfs} (@samp{hs} for ``High Sierra'').
9894 @cindex PC file system
9895 @cindex DOS file system
9896 @cindex MS-DOS file system
9897 @cindex diskette file system
9899 An MS-DOS file system, usually on a diskette.
9903 @item -x @var{fstype}
9904 @itemx --exclude-type=@var{fstype}
9906 @opindex --exclude-type
9907 Limit the listing to file systems not of type @var{fstype}.
9908 Multiple file system types can be eliminated by giving multiple
9909 @option{-x} options. By default, no file system types are omitted.
9912 Ignored; for compatibility with System V versions of @command{df}.
9917 Failure includes the case where no output is generated, so you can
9918 inspect the exit status of a command like @samp{df -t ext3 -t reiserfs
9919 @var{dir}} to test whether @var{dir} is on a file system of type
9920 @samp{ext3} or @samp{reiserfs}.
9924 @section @command{du}: Estimate file space usage
9927 @cindex file space usage
9928 @cindex disk usage for files
9930 @command{du} reports the amount of disk space used by the specified files
9931 and for each subdirectory (of directory arguments). Synopsis:
9934 du [@var{option}]@dots{} [@var{file}]@dots{}
9937 With no arguments, @command{du} reports the disk space for the current
9938 directory. Normally the disk space is printed in units of
9939 1024 bytes, but this can be overridden (@pxref{Block size}).
9940 Non-integer quantities are rounded up to the next higher unit.
9942 If two or more hard links point to the same file, only one of the hard
9943 links is counted. The @var{file} argument order affects which links
9944 are counted, and changing the argument order may change the numbers
9945 that @command{du} outputs.
9947 The program accepts the following options. Also see @ref{Common options}.
9955 Show counts for all files, not just directories.
9957 @itemx --apparent-size
9958 @opindex --apparent-size
9959 Print apparent sizes, rather than disk usage. The apparent size of a
9960 file is the number of bytes reported by @code{wc -c} on regular files,
9961 or more generally, @code{ls -l --block-size=1} or @code{stat --format=%s}.
9962 For example, a file containing the word @samp{zoo} with no newline would,
9963 of course, have an apparent size of 3. Such a small file may require
9964 anywhere from 0 to 16 KiB or more of disk space, depending on
9965 the type and configuration of the file system on which the file resides.
9966 However, a sparse file created with this command:
9969 dd bs=1 seek=2GiB if=/dev/null of=big
9973 has an apparent size of 2 GiB, yet on most modern
9974 systems, it actually uses almost no disk space.
9980 Equivalent to @code{--apparent-size --block-size=1}.
9983 @itemx --block-size=@var{size}
9985 @opindex --block-size
9987 Scale sizes by @var{size} before printing them (@pxref{Block size}).
9988 For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes.
9994 @cindex grand total of disk space
9995 Print a grand total of all arguments after all arguments have
9996 been processed. This can be used to find out the total disk usage of
9997 a given set of files or directories.
10000 @itemx --dereference-args
10002 @opindex --dereference-args
10003 Dereference symbolic links that are command line arguments.
10004 Does not affect other symbolic links. This is helpful for finding
10005 out the disk usage of directories, such as @file{/usr/tmp}, which
10006 are often symbolic links.
10008 @c --files0-from=FILE
10009 @filesZeroFromOption{du,, with the @option{--total} (@option{-c}) option}
10015 Currently, @option{-H} is the same as @option{--si},
10016 except that @option{-H} evokes a warning.
10017 This option will be changed to be equivalent to
10018 @option{--dereference-args} (@option{-D}).
10022 @cindex kibibytes for file sizes
10023 Print sizes in 1024-byte blocks, overriding the default block size
10024 (@pxref{Block size}).
10025 This option is equivalent to @option{--block-size=1K}.
10028 @itemx --count-links
10030 @opindex --count-links
10031 @cindex hard links, counting in @command{du}
10032 Count the size of all files, even if they have appeared already (as a
10036 @itemx --dereference
10038 @opindex --dereference
10039 @cindex symbolic links, dereferencing in @command{du}
10040 Dereference symbolic links (show the disk space used by the file
10041 or directory that the link points to instead of the space used by
10046 @cindex mebibytes for file sizes
10047 Print sizes in 1,048,576-byte blocks, overriding the default block size
10048 (@pxref{Block size}).
10049 This option is equivalent to @option{--block-size=1M}.
10052 @itemx --no-dereference
10054 @opindex --no-dereference
10055 @cindex symbolic links, dereferencing in @command{du}
10056 For each symbolic links encountered by @command{du},
10057 consider the disk space used by the symbolic link.
10059 @item --max-depth=@var{DEPTH}
10060 @opindex --max-depth=@var{DEPTH}
10061 @cindex limiting output of @command{du}
10062 Show the total for each directory (and file if --all) that is at
10063 most MAX_DEPTH levels down from the root of the hierarchy. The root
10064 is at level 0, so @code{du --max-depth=0} is equivalent to @code{du -s}.
10070 @cindex output null-byte-terminated lines
10071 Output a null byte at the end of each line, rather than a newline.
10072 This option enables other programs to parse the output of @command{du}
10073 even when that output would contain file names with embedded newlines.
10080 @opindex --summarize
10081 Display only a total for each argument.
10084 @itemx --separate-dirs
10086 @opindex --separate-dirs
10087 Normally, in the output of @command{du} (when not using @option{--summarize}),
10088 the size listed next to a directory name, @var{d}, represents the sum
10089 of sizes of all entries beneath @var{d} as well as the size of @var{d} itself.
10090 With @option{--separate-dirs}, the size reported for a directory name,
10091 @var{d}, is merely the @code{stat.st_size}-derived size of the directory
10096 @cindex last modified dates, displaying in @command{du}
10097 Show time of the most recent modification of any file in the directory,
10098 or any of its subdirectories.
10100 @itemx --time=ctime
10101 @itemx --time=status
10104 @opindex ctime@r{, show the most recent}
10105 @opindex status time@r{, show the most recent}
10106 @opindex use time@r{, show the most recent}
10107 Show the most recent status change time (the @samp{ctime} in the inode) of
10108 any file in the directory, instead of the modification time.
10110 @itemx --time=atime
10111 @itemx --time=access
10113 @opindex atime@r{, show the most recent}
10114 @opindex access time@r{, show the most recent}
10115 Show the most recent access time (the @samp{atime} in the inode) of
10116 any file in the directory, instead of the modification time.
10118 @item --time-style=@var{style}
10119 @opindex --time-style
10121 List timestamps in style @var{style}. This option has an effect only if
10122 the @option{--time} option is also specified. The @var{style} should
10123 be one of the following:
10126 @item +@var{format}
10128 List timestamps using @var{format}, where @var{format} is interpreted
10129 like the format argument of @command{date} (@pxref{date invocation}).
10130 For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes
10131 @command{du} to list timestamps like @samp{2002-03-30 23:45:56}. As
10132 with @command{date}, @var{format}'s interpretation is affected by the
10133 @env{LC_TIME} locale category.
10136 List timestamps in full using @acronym{ISO} 8601 date, time, and time zone
10137 format with nanosecond precision, e.g., @samp{2002-03-30
10138 23:45:56.477817180 -0700}. This style is equivalent to
10139 @samp{+%Y-%m-%d %H:%M:%S.%N %z}.
10142 List @acronym{ISO} 8601 date and time in minutes, e.g.,
10143 @samp{2002-03-30 23:45}. These timestamps are shorter than
10144 @samp{full-iso} timestamps, and are usually good enough for everyday
10145 work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}.
10148 List @acronym{ISO} 8601 dates for timestamps, e.g., @samp{2002-03-30}.
10149 This style is equivalent to @samp{+%Y-%m-%d}.
10153 You can specify the default value of the @option{--time-style} option
10154 with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set
10155 the default style is @samp{long-iso}. For compatibility with @command{ls},
10156 if @env{TIME_STYLE} begins with @samp{+} and contains a newline,
10157 the newline and any later characters are ignored; if @env{TIME_STYLE}
10158 begins with @samp{posix-} the @samp{posix-} is ignored; and if
10159 @env{TIME_STYLE} is @samp{locale} it is ignored.
10162 @itemx --one-file-system
10164 @opindex --one-file-system
10165 @cindex one file system, restricting @command{du} to
10166 Skip directories that are on different file systems from the one that
10167 the argument being processed is on.
10169 @item --exclude=@var{PATTERN}
10170 @opindex --exclude=@var{PATTERN}
10171 @cindex excluding files from @command{du}
10172 When recursing, skip subdirectories or files matching @var{PATTERN}.
10173 For example, @code{du --exclude='*.o'} excludes files whose names
10176 @item -X @var{FILE}
10177 @itemx --exclude-from=@var{FILE}
10178 @opindex -X @var{FILE}
10179 @opindex --exclude-from=@var{FILE}
10180 @cindex excluding files from @command{du}
10181 Like @option{--exclude}, except take the patterns to exclude from @var{FILE},
10182 one per line. If @var{FILE} is @samp{-}, take the patterns from standard
10187 @cindex NFS mounts from BSD to HP-UX
10188 On BSD systems, @command{du} reports sizes that are half the correct
10189 values for files that are NFS-mounted from HP-UX systems. On HP-UX
10190 systems, it reports sizes that are twice the correct values for
10191 files that are NFS-mounted from BSD systems. This is due to a flaw
10192 in HP-UX; it also affects the HP-UX @command{du} program.
10197 @node stat invocation
10198 @section @command{stat}: Report file or file system status
10201 @cindex file status
10202 @cindex file system status
10204 @command{stat} displays information about the specified file(s). Synopsis:
10207 stat [@var{option}]@dots{} [@var{file}]@dots{}
10210 With no option, @command{stat} reports all information about the given files.
10211 But it also can be used to report the information of the file systems the
10212 given files are located on. If the files are links, @command{stat} can
10213 also give information about the files the links point to.
10215 @mayConflictWithShellBuiltIn{stat}
10220 @itemx --dereference
10222 @opindex --dereference
10223 @cindex symbolic links, dereferencing in @command{stat}
10224 Change how @command{stat} treats symbolic links.
10225 With this option, @command{stat} acts on the file referenced
10226 by each symbolic link argument.
10227 Without it, @command{stat} acts on any symbolic link argument directly.
10230 @itemx --file-system
10232 @opindex --file-system
10233 @cindex file systems
10234 Report information about the file systems where the given files are located
10235 instead of information about the files themselves.
10238 @itemx --format=@var{format}
10240 @opindex --format=@var{format}
10241 @cindex output format
10242 Use @var{format} rather than the default format.
10243 @var{format} is automatically newline-terminated, so
10244 running a command like the following with two or more @var{file}
10245 operands produces a line of output for each operand:
10247 $ stat --format=%d:%i / /usr
10252 @itemx --printf=@var{format}
10253 @opindex --printf=@var{format}
10254 @cindex output format
10255 Use @var{format} rather than the default format.
10256 Like @option{--format}, but interpret backslash escapes,
10257 and do not output a mandatory trailing newline.
10258 If you want a newline, include @samp{\n} in the @var{format}.
10259 Here's how you would use @option{--printf} to print the device
10260 and inode numbers of @file{/} and @file{/usr}:
10262 $ stat --printf='%d:%i\n' / /usr
10271 @cindex terse output
10272 Print the information in terse form, suitable for parsing by other programs.
10274 The valid format sequences for files are:
10277 @item %a - Access rights in octal
10278 @item %A - Access rights in human readable form
10279 @item %b - Number of blocks allocated (see @samp{%B})
10280 @item %B - The size in bytes of each block reported by @samp{%b}
10281 @item %d - Device number in decimal
10282 @item %D - Device number in hex
10283 @item %f - Raw mode in hex
10284 @item %F - File type
10285 @item %g - Group ID of owner
10286 @item %G - Group name of owner
10287 @item %h - Number of hard links
10288 @item %i - Inode number
10289 @item %n - File name
10290 @item %N - Quoted file name with dereference if symbolic link
10291 @item %o - I/O block size
10292 @item %s - Total size, in bytes
10293 @item %t - Major device type in hex
10294 @item %T - Minor device type in hex
10295 @item %u - User ID of owner
10296 @item %U - User name of owner
10297 @item %x - Time of last access
10298 @item %X - Time of last access as seconds since Epoch
10299 @item %y - Time of last modification
10300 @item %Y - Time of last modification as seconds since Epoch
10301 @item %z - Time of last change
10302 @item %Z - Time of last change as seconds since Epoch
10305 The valid format sequences for file systems are:
10308 @item %a - Free blocks available to non-super-user
10309 @item %b - Total data blocks in file system
10310 @item %c - Total file nodes in file system
10311 @item %d - Free file nodes in file system
10312 @item %f - Free blocks in file system
10313 @item %i - File System ID in hex
10314 @item %l - Maximum length of file names
10315 @item %n - File name
10316 @item %s - Block size (for faster transfers)
10317 @item %S - Fundamental block size (for block counts)
10318 @item %t - Type in hex
10319 @item %T - Type in human readable form
10323 Time stamps are listed according to the time zone rules specified by
10324 the @env{TZ} environment variable, or by the system default rules if
10325 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
10326 with @env{TZ}, libc, The GNU C Library Reference Manual}.
10332 @node sync invocation
10333 @section @command{sync}: Synchronize data on disk with memory
10336 @cindex synchronize disk and memory
10338 @cindex superblock, writing
10339 @cindex inodes, written buffered
10340 @command{sync} writes any data buffered in memory out to disk. This can
10341 include (but is not limited to) modified superblocks, modified inodes,
10342 and delayed reads and writes. This must be implemented by the kernel;
10343 The @command{sync} program does nothing but exercise the @code{sync} system
10346 @cindex crashes and corruption
10347 The kernel keeps data in memory to avoid doing (relatively slow) disk
10348 reads and writes. This improves performance, but if the computer
10349 crashes, data may be lost or the file system corrupted as a
10350 result. The @command{sync} command ensures everything in memory
10351 is written to disk.
10353 Any arguments are ignored, except for a lone @option{--help} or
10354 @option{--version} (@pxref{Common options}).
10359 @node truncate invocation
10360 @section @command{truncate}: Shrink or extend the size of a file
10363 @cindex truncating, file sizes
10365 @command{truncate} shrinks or extends the size of each @var{file} to the
10366 specified size. Synopsis:
10369 truncate @var{option}@dots{} @var{file}@dots{}
10372 @cindex files, creating
10373 Any @var{file} that does not exist is created.
10375 @cindex sparse files, creating
10376 @cindex holes, creating files with
10377 If a @var{file} is larger than the specified size, the extra data is lost.
10378 If a @var{file} is shorter, it is extended and the extended part (or hole)
10379 reads as zero bytes.
10381 The program accepts the following options. Also see @ref{Common options}.
10388 @opindex --no-create
10389 Do not create files that do not exist.
10394 @opindex --io-blocks
10395 Treat @var{size} as number of I/O blocks of the @var{FILE} rather than bytes.
10397 @item -r @var{rfile}
10398 @itemx --reference=@var{rfile}
10400 @opindex --reference
10401 Set the size of each @var{file} to the same size as @var{rfile}.
10403 @item -s @var{size}
10404 @itemx --size=@var{size}
10407 Set the size of each @var{file} to this @var{size}.
10408 @var{size} is a number which may be followed by one of these
10409 multiplicative suffixes:
10411 @samp{KB} => 1000 (KiloBytes)
10412 @samp{K} => 1024 (KibiBytes)
10413 @samp{MB} => 1000*1000 (MegaBytes)
10414 @samp{M} => 1024*1024 (MebiBytes)
10416 and so on for @samp{G}, @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
10418 @var{size} may also be prefixed by one of the following to adjust
10419 the size of each @var{file} based on their current size:
10421 @samp{+} => extend by
10422 @samp{-} => reduce by
10423 @samp{<} => at most
10424 @samp{>} => at least
10425 @samp{/} => round down to multiple of
10426 @samp{%} => round up to multiple of
10434 @node Printing text
10435 @chapter Printing text
10437 @cindex printing text, commands for
10438 @cindex commands for printing text
10440 This section describes commands that display text strings.
10443 * echo invocation:: Print a line of text.
10444 * printf invocation:: Format and print data.
10445 * yes invocation:: Print a string until interrupted.
10449 @node echo invocation
10450 @section @command{echo}: Print a line of text
10453 @cindex displaying text
10454 @cindex printing text
10455 @cindex text, displaying
10456 @cindex arbitrary text, displaying
10458 @command{echo} writes each given @var{string} to standard output, with a
10459 space between each and a newline after the last one. Synopsis:
10462 echo [@var{option}]@dots{} [@var{string}]@dots{}
10465 @mayConflictWithShellBuiltIn{echo}
10467 The program accepts the following options. Also see @ref{Common options}.
10468 Options must precede operands, and the normally-special argument
10469 @samp{--} has no special meaning and is treated like any other
10475 Do not output the trailing newline.
10479 @cindex backslash escapes
10480 Enable interpretation of the following backslash-escaped characters in
10489 produce no further output
10503 the eight-bit value that is the octal number @var{nnn}
10504 (zero to three octal digits)
10506 the eight-bit value that is the octal number @var{nnn}
10507 (one to three octal digits)
10509 the eight-bit value that is the hexadecimal number @var{hh}
10510 (one or two hexadecimal digits)
10515 @cindex backslash escapes
10516 Disable interpretation of backslash escapes in each @var{string}.
10517 This is the default. If @option{-e} and @option{-E} are both
10518 specified, the last one given takes effect.
10522 @vindex POSIXLY_CORRECT
10523 If the @env{POSIXLY_CORRECT} environment variable is set, then when
10524 @command{echo}'s first argument is not @option{-n} it outputs
10525 option-like arguments instead of treating them as options. For
10526 example, @code{echo -ne hello} outputs @samp{-ne hello} instead of
10527 plain @samp{hello}.
10529 @acronym{POSIX} does not require support for any options, and says
10530 that the behavior of @command{echo} is implementation-defined if any
10531 @var{string} contains a backslash or if the first argument is
10532 @option{-n}. Portable programs can use the @command{printf} command
10533 if they need to omit trailing newlines or output control characters or
10534 backslashes. @xref{printf invocation}.
10539 @node printf invocation
10540 @section @command{printf}: Format and print data
10543 @command{printf} does formatted printing of text. Synopsis:
10546 printf @var{format} [@var{argument}]@dots{}
10549 @command{printf} prints the @var{format} string, interpreting @samp{%}
10550 directives and @samp{\} escapes to format numeric and string arguments
10551 in a way that is mostly similar to the C @samp{printf} function.
10552 @xref{Output Conversion Syntax,, @command{printf} format directives,
10553 libc, The GNU C Library Reference Manual}, for details.
10554 The differences are listed below.
10556 @mayConflictWithShellBuiltIn{printf}
10561 The @var{format} argument is reused as necessary to convert all the
10562 given @var{argument}s. For example, the command @samp{printf %s a b}
10566 Missing @var{argument}s are treated as null strings or as zeros,
10567 depending on whether the context expects a string or a number. For
10568 example, the command @samp{printf %sx%d} prints @samp{x0}.
10572 An additional escape, @samp{\c}, causes @command{printf} to produce no
10573 further output. For example, the command @samp{printf 'A%sC\cD%sF' B
10574 E} prints @samp{ABC}.
10577 The hexadecimal escape sequence @samp{\x@var{hh}} has at most two
10578 digits, as opposed to C where it can have an unlimited number of
10579 digits. For example, the command @samp{printf '\x07e'} prints two
10580 bytes, whereas the C statement @samp{printf ("\x07e")} prints just
10585 @command{printf} has an additional directive, @samp{%b}, which prints its
10586 argument string with @samp{\} escapes interpreted in the same way as in
10587 the @var{format} string, except that octal escapes are of the form
10588 @samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits.
10589 If a precision is also given, it limits the number of bytes printed
10590 from the converted string.
10593 Numeric arguments must be single C constants, possibly with leading
10594 @samp{+} or @samp{-}. For example, @samp{printf %.4d -3} outputs
10598 @vindex POSIXLY_CORRECT
10599 If the leading character of a numeric argument is @samp{"} or @samp{'}
10600 then its value is the numeric value of the immediately following
10601 character. Any remaining characters are silently ignored if the
10602 @env{POSIXLY_CORRECT} environment variable is set; otherwise, a
10603 warning is printed. For example, @samp{printf "%d" "'a"} outputs
10604 @samp{97} on hosts that use the @acronym{ASCII} character set, since
10605 @samp{a} has the numeric value 97 in @acronym{ASCII}.
10610 A floating-point argument must use a period before any fractional
10611 digits, but is printed according to the @env{LC_NUMERIC} category of the
10612 current locale. For example, in a locale whose radix character is a
10613 comma, the command @samp{printf %g 3.14} outputs @samp{3,14} whereas
10614 the command @samp{printf %g 3,14} is an error.
10618 @command{printf} interprets @samp{\@var{ooo}} in @var{format} as an octal number
10619 (if @var{ooo} is 1 to 3 octal digits) specifying a character to print,
10620 and @samp{\x@var{hh}} as a hexadecimal number (if @var{hh} is 1 to 2 hex
10621 digits) specifying a character to print.
10626 @cindex ISO/IEC 10646
10628 @command{printf} interprets two character syntaxes introduced in
10629 @acronym{ISO} C 99:
10630 @samp{\u} for 16-bit Unicode (@acronym{ISO}/@acronym{IEC} 10646)
10631 characters, specified as
10632 four hexadecimal digits @var{hhhh}, and @samp{\U} for 32-bit Unicode
10633 characters, specified as eight hexadecimal digits @var{hhhhhhhh}.
10634 @command{printf} outputs the Unicode characters
10635 according to the @env{LC_CTYPE} locale. Unicode characters in the ranges
10636 U+0000...U+009F, U+D800...U+DFFF cannot be specified by this syntax, except
10637 for U+0024 ($), U+0040 (@@), and U+0060 (@`).
10639 The processing of @samp{\u} and @samp{\U} requires a full-featured
10640 @code{iconv} facility. It is activated on systems with glibc 2.2 (or newer),
10641 or when @code{libiconv} is installed prior to this package. Otherwise
10642 @samp{\u} and @samp{\U} will print as-is.
10644 The only options are a lone @option{--help} or
10645 @option{--version}. @xref{Common options}.
10646 Options must precede operands.
10648 The Unicode character syntaxes are useful for writing strings in a locale
10649 independent way. For example, a string containing the Euro currency symbol
10652 $ env printf '\u20AC 14.95'
10656 will be output correctly in all locales supporting the Euro symbol
10657 (@acronym{ISO}-8859-15, UTF-8, and others). Similarly, a Chinese string
10660 $ env printf '\u4e2d\u6587'
10664 will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8, etc).
10666 Note that in these examples, the @command{printf} command has been
10667 invoked via @command{env} to ensure that we run the program found via
10668 your shell's search path, and not a shell alias or a built-in function.
10670 For larger strings, you don't need to look up the hexadecimal code
10671 values of each character one by one. @acronym{ASCII} characters mixed with \u
10672 escape sequences is also known as the JAVA source file encoding. You can
10673 use GNU recode 3.5c (or newer) to convert strings to this encoding. Here
10674 is how to convert a piece of text into a shell script which will output
10675 this text in a locale-independent way:
10678 $ LC_CTYPE=zh_CN.big5 /usr/local/bin/printf \
10679 '\u4e2d\u6587\n' > sample.txt
10680 $ recode BIG5..JAVA < sample.txt \
10681 | sed -e "s|^|/usr/local/bin/printf '|" -e "s|$|\\\\n'|" \
10688 @node yes invocation
10689 @section @command{yes}: Print a string until interrupted
10692 @cindex repeated output of a string
10694 @command{yes} prints the command line arguments, separated by spaces and
10695 followed by a newline, forever until it is killed. If no arguments are
10696 given, it prints @samp{y} followed by a newline forever until killed.
10698 Upon a write error, @command{yes} exits with status @samp{1}.
10700 The only options are a lone @option{--help} or @option{--version}.
10701 To output an argument that begins with
10702 @samp{-}, precede it with @option{--}, e.g., @samp{yes -- --help}.
10703 @xref{Common options}.
10707 @chapter Conditions
10710 @cindex commands for exit status
10711 @cindex exit status commands
10713 This section describes commands that are primarily useful for their exit
10714 status, rather than their output. Thus, they are often used as the
10715 condition of shell @code{if} statements, or as the last command in a
10719 * false invocation:: Do nothing, unsuccessfully.
10720 * true invocation:: Do nothing, successfully.
10721 * test invocation:: Check file types and compare values.
10722 * expr invocation:: Evaluate expressions.
10726 @node false invocation
10727 @section @command{false}: Do nothing, unsuccessfully
10730 @cindex do nothing, unsuccessfully
10731 @cindex failure exit status
10732 @cindex exit status of @command{false}
10734 @command{false} does nothing except return an exit status of 1, meaning
10735 @dfn{failure}. It can be used as a place holder in shell scripts
10736 where an unsuccessful command is needed.
10737 In most modern shells, @command{false} is a built-in command, so when
10738 you use @samp{false} in a script, you're probably using the built-in
10739 command, not the one documented here.
10741 @command{false} honors the @option{--help} and @option{--version} options.
10743 This version of @command{false} is implemented as a C program, and is thus
10744 more secure and faster than a shell script implementation, and may safely
10745 be used as a dummy shell for the purpose of disabling accounts.
10747 Note that @command{false} (unlike all other programs documented herein)
10748 exits unsuccessfully, even when invoked with
10749 @option{--help} or @option{--version}.
10751 Portable programs should not assume that the exit status of
10752 @command{false} is 1, as it is greater than 1 on some
10753 non-@acronym{GNU} hosts.
10756 @node true invocation
10757 @section @command{true}: Do nothing, successfully
10760 @cindex do nothing, successfully
10762 @cindex successful exit
10763 @cindex exit status of @command{true}
10765 @command{true} does nothing except return an exit status of 0, meaning
10766 @dfn{success}. It can be used as a place holder in shell scripts
10767 where a successful command is needed, although the shell built-in
10768 command @code{:} (colon) may do the same thing faster.
10769 In most modern shells, @command{true} is a built-in command, so when
10770 you use @samp{true} in a script, you're probably using the built-in
10771 command, not the one documented here.
10773 @command{true} honors the @option{--help} and @option{--version} options.
10775 Note, however, that it is possible to cause @command{true}
10776 to exit with nonzero status: with the @option{--help} or @option{--version}
10777 option, and with standard
10778 output already closed or redirected to a file that evokes an I/O error.
10779 For example, using a Bourne-compatible shell:
10782 $ ./true --version >&-
10783 ./true: write error: Bad file number
10784 $ ./true --version > /dev/full
10785 ./true: write error: No space left on device
10788 This version of @command{true} is implemented as a C program, and is thus
10789 more secure and faster than a shell script implementation, and may safely
10790 be used as a dummy shell for the purpose of disabling accounts.
10792 @node test invocation
10793 @section @command{test}: Check file types and compare values
10796 @cindex check file types
10797 @cindex compare values
10798 @cindex expression evaluation
10800 @command{test} returns a status of 0 (true) or 1 (false) depending on the
10801 evaluation of the conditional expression @var{expr}. Each part of the
10802 expression must be a separate argument.
10804 @command{test} has file status checks, string operators, and numeric
10805 comparison operators.
10807 @command{test} has an alternate form that uses opening and closing
10808 square brackets instead a leading @samp{test}. For example, instead
10809 of @samp{test -d /}, you can write @samp{[ -d / ]}. The square
10810 brackets must be separate arguments; for example, @samp{[-d /]} does
10811 not have the desired effect. Since @samp{test @var{expr}} and @samp{[
10812 @var{expr} ]} have the same meaning, only the former form is discussed
10818 test @var{expression}
10820 [ @var{expression} ]
10825 @mayConflictWithShellBuiltIn{test}
10827 If @var{expression} is omitted, @command{test} returns false.
10828 If @var{expression} is a single argument,
10829 @command{test} returns false if the argument is null and true otherwise. The argument
10830 can be any string, including strings like @samp{-d}, @samp{-1},
10831 @samp{--}, @samp{--help}, and @samp{--version} that most other
10832 programs would treat as options. To get help and version information,
10833 invoke the commands @samp{[ --help} and @samp{[ --version}, without
10834 the usual closing brackets. @xref{Common options}.
10836 @cindex exit status of @command{test}
10840 0 if the expression is true,
10841 1 if the expression is false,
10842 2 if an error occurred.
10846 * File type tests:: -[bcdfhLpSt]
10847 * Access permission tests:: -[gkruwxOG]
10848 * File characteristic tests:: -e -s -nt -ot -ef
10849 * String tests:: -z -n = !=
10850 * Numeric tests:: -eq -ne -lt -le -gt -ge
10851 * Connectives for test:: ! -a -o
10855 @node File type tests
10856 @subsection File type tests
10858 @cindex file type tests
10860 These options test for particular types of files. (Everything's a file,
10861 but not all files are the same!)
10865 @item -b @var{file}
10867 @cindex block special check
10868 True if @var{file} exists and is a block special device.
10870 @item -c @var{file}
10872 @cindex character special check
10873 True if @var{file} exists and is a character special device.
10875 @item -d @var{file}
10877 @cindex directory check
10878 True if @var{file} exists and is a directory.
10880 @item -f @var{file}
10882 @cindex regular file check
10883 True if @var{file} exists and is a regular file.
10885 @item -h @var{file}
10886 @itemx -L @var{file}
10889 @cindex symbolic link check
10890 True if @var{file} exists and is a symbolic link.
10891 Unlike all other file-related tests, this test does not dereference
10892 @var{file} if it is a symbolic link.
10894 @item -p @var{file}
10896 @cindex named pipe check
10897 True if @var{file} exists and is a named pipe.
10899 @item -S @var{file}
10901 @cindex socket check
10902 True if @var{file} exists and is a socket.
10906 @cindex terminal check
10907 True if @var{fd} is a file descriptor that is associated with a
10913 @node Access permission tests
10914 @subsection Access permission tests
10916 @cindex access permission tests
10917 @cindex permission tests
10919 These options test for particular access permissions.
10923 @item -g @var{file}
10925 @cindex set-group-ID check
10926 True if @var{file} exists and has its set-group-ID bit set.
10928 @item -k @var{file}
10930 @cindex sticky bit check
10931 True if @var{file} exists and has its @dfn{sticky} bit set.
10933 @item -r @var{file}
10935 @cindex readable file check
10936 True if @var{file} exists and read permission is granted.
10938 @item -u @var{file}
10940 @cindex set-user-ID check
10941 True if @var{file} exists and has its set-user-ID bit set.
10943 @item -w @var{file}
10945 @cindex writable file check
10946 True if @var{file} exists and write permission is granted.
10948 @item -x @var{file}
10950 @cindex executable file check
10951 True if @var{file} exists and execute permission is granted
10952 (or search permission, if it is a directory).
10954 @item -O @var{file}
10956 @cindex owned by effective user ID check
10957 True if @var{file} exists and is owned by the current effective user ID.
10959 @item -G @var{file}
10961 @cindex owned by effective group ID check
10962 True if @var{file} exists and is owned by the current effective group ID.
10966 @node File characteristic tests
10967 @subsection File characteristic tests
10969 @cindex file characteristic tests
10971 These options test other file characteristics.
10975 @item -e @var{file}
10977 @cindex existence-of-file check
10978 True if @var{file} exists.
10980 @item -s @var{file}
10982 @cindex nonempty file check
10983 True if @var{file} exists and has a size greater than zero.
10985 @item @var{file1} -nt @var{file2}
10987 @cindex newer-than file check
10988 True if @var{file1} is newer (according to modification date) than
10989 @var{file2}, or if @var{file1} exists and @var{file2} does not.
10991 @item @var{file1} -ot @var{file2}
10993 @cindex older-than file check
10994 True if @var{file1} is older (according to modification date) than
10995 @var{file2}, or if @var{file2} exists and @var{file1} does not.
10997 @item @var{file1} -ef @var{file2}
10999 @cindex same file check
11000 @cindex hard link check
11001 True if @var{file1} and @var{file2} have the same device and inode
11002 numbers, i.e., if they are hard links to each other.
11008 @subsection String tests
11010 @cindex string tests
11012 These options test string characteristics. You may need to quote
11013 @var{string} arguments for the shell. For example:
11019 The quotes here prevent the wrong arguments from being passed to
11020 @command{test} if @samp{$V} is empty or contains special characters.
11024 @item -z @var{string}
11026 @cindex zero-length string check
11027 True if the length of @var{string} is zero.
11029 @item -n @var{string}
11030 @itemx @var{string}
11032 @cindex nonzero-length string check
11033 True if the length of @var{string} is nonzero.
11035 @item @var{string1} = @var{string2}
11037 @cindex equal string check
11038 True if the strings are equal.
11040 @item @var{string1} != @var{string2}
11042 @cindex not-equal string check
11043 True if the strings are not equal.
11048 @node Numeric tests
11049 @subsection Numeric tests
11051 @cindex numeric tests
11052 @cindex arithmetic tests
11054 Numeric relational operators. The arguments must be entirely numeric
11055 (possibly negative), or the special expression @w{@code{-l @var{string}}},
11056 which evaluates to the length of @var{string}.
11060 @item @var{arg1} -eq @var{arg2}
11061 @itemx @var{arg1} -ne @var{arg2}
11062 @itemx @var{arg1} -lt @var{arg2}
11063 @itemx @var{arg1} -le @var{arg2}
11064 @itemx @var{arg1} -gt @var{arg2}
11065 @itemx @var{arg1} -ge @var{arg2}
11072 These arithmetic binary operators return true if @var{arg1} is equal,
11073 not-equal, less-than, less-than-or-equal, greater-than, or
11074 greater-than-or-equal than @var{arg2}, respectively.
11081 test -1 -gt -2 && echo yes
11083 test -l abc -gt 1 && echo yes
11086 @error{} test: integer expression expected before -eq
11090 @node Connectives for test
11091 @subsection Connectives for @command{test}
11093 @cindex logical connectives
11094 @cindex connectives, logical
11096 The usual logical connectives.
11102 True if @var{expr} is false.
11104 @item @var{expr1} -a @var{expr2}
11106 @cindex logical and operator
11107 @cindex and operator
11108 True if both @var{expr1} and @var{expr2} are true.
11110 @item @var{expr1} -o @var{expr2}
11112 @cindex logical or operator
11113 @cindex or operator
11114 True if either @var{expr1} or @var{expr2} is true.
11119 @node expr invocation
11120 @section @command{expr}: Evaluate expressions
11123 @cindex expression evaluation
11124 @cindex evaluation of expressions
11126 @command{expr} evaluates an expression and writes the result on standard
11127 output. Each token of the expression must be a separate argument.
11129 Operands are either integers or strings. Integers consist of one or
11130 more decimal digits, with an optional leading @samp{-}.
11131 @command{expr} converts
11132 anything appearing in an operand position to an integer or a string
11133 depending on the operation being applied to it.
11135 Strings are not quoted for @command{expr} itself, though you may need to
11136 quote them to protect characters with special meaning to the shell,
11137 e.g., spaces. However, regardless of whether it is quoted, a string
11138 operand should not be a parenthesis or any of @command{expr}'s
11139 operators like @code{+}, so you cannot safely pass an arbitrary string
11140 @code{$str} to expr merely by quoting it to the shell. One way to
11141 work around this is to use the @sc{gnu} extension @code{+},
11142 (e.g., @code{+ "$str" = foo}); a more portable way is to use
11143 @code{@w{" $str"}} and to adjust the rest of the expression to take
11144 the leading space into account (e.g., @code{@w{" $str" = " foo"}}).
11146 You should not pass a negative integer or a string with leading
11147 @samp{-} as @command{expr}'s first argument, as it might be
11148 misinterpreted as an option; this can be avoided by parenthesization.
11149 Also, portable scripts should not use a string operand that happens to
11150 take the form of an integer; this can be worked around by inserting
11151 leading spaces as mentioned above.
11153 @cindex parentheses for grouping
11154 Operators may be given as infix symbols or prefix keywords. Parentheses
11155 may be used for grouping in the usual manner. You must quote
11156 parentheses and many operators to avoid the shell evaluating them,
11159 When built with support for the GNU MP library, @command{expr} uses
11160 arbitrary-precision arithmetic; otherwise, it uses native arithmetic
11161 types and may fail due to arithmetic overflow.
11163 The only options are @option{--help} and @option{--version}. @xref{Common
11164 options}. Options must precede operands.
11166 @cindex exit status of @command{expr}
11170 0 if the expression is neither null nor 0,
11171 1 if the expression is null or 0,
11172 2 if the expression is invalid,
11173 3 if an internal error occurred (e.g., arithmetic overflow).
11177 * String expressions:: + : match substr index length
11178 * Numeric expressions:: + - * / %
11179 * Relations for expr:: | & < <= = == != >= >
11180 * Examples of expr:: Examples.
11184 @node String expressions
11185 @subsection String expressions
11187 @cindex string expressions
11188 @cindex expressions, string
11190 @command{expr} supports pattern matching and other string operators. These
11191 have higher precedence than both the numeric and relational operators (in
11192 the next sections).
11196 @item @var{string} : @var{regex}
11197 @cindex pattern matching
11198 @cindex regular expression matching
11199 @cindex matching patterns
11200 Perform pattern matching. The arguments are converted to strings and the
11201 second is considered to be a (basic, a la GNU @code{grep}) regular
11202 expression, with a @code{^} implicitly prepended. The first argument is
11203 then matched against this regular expression.
11205 If the match succeeds and @var{regex} uses @samp{\(} and @samp{\)}, the
11206 @code{:} expression returns the part of @var{string} that matched the
11207 subexpression; otherwise, it returns the number of characters matched.
11209 If the match fails, the @code{:} operator returns the null string if
11210 @samp{\(} and @samp{\)} are used in @var{regex}, otherwise 0.
11212 @kindex \( @r{regexp operator}
11213 Only the first @samp{\( @dots{} \)} pair is relevant to the return
11214 value; additional pairs are meaningful only for grouping the regular
11215 expression operators.
11217 @kindex \+ @r{regexp operator}
11218 @kindex \? @r{regexp operator}
11219 @kindex \| @r{regexp operator}
11220 In the regular expression, @code{\+}, @code{\?}, and @code{\|} are
11221 operators which respectively match one or more, zero or one, or separate
11222 alternatives. SunOS and other @command{expr}'s treat these as regular
11223 characters. (@acronym{POSIX} allows either behavior.)
11224 @xref{Top, , Regular Expression Library, regex, Regex}, for details of
11225 regular expression syntax. Some examples are in @ref{Examples of expr}.
11227 @item match @var{string} @var{regex}
11229 An alternative way to do pattern matching. This is the same as
11230 @w{@samp{@var{string} : @var{regex}}}.
11232 @item substr @var{string} @var{position} @var{length}
11234 Returns the substring of @var{string} beginning at @var{position}
11235 with length at most @var{length}. If either @var{position} or
11236 @var{length} is negative, zero, or non-numeric, returns the null string.
11238 @item index @var{string} @var{charset}
11240 Returns the first position in @var{string} where the first character in
11241 @var{charset} was found. If no character in @var{charset} is found in
11242 @var{string}, return 0.
11244 @item length @var{string}
11246 Returns the length of @var{string}.
11248 @item + @var{token}
11250 Interpret @var{token} as a string, even if it is a keyword like @var{match}
11251 or an operator like @code{/}.
11252 This makes it possible to test @code{expr length + "$x"} or
11253 @code{expr + "$x" : '.*/\(.\)'} and have it do the right thing even if
11254 the value of @var{$x} happens to be (for example) @code{/} or @code{index}.
11255 This operator is a @acronym{GNU} extension. Portable shell scripts should use
11256 @code{@w{" $token"} : @w{' \(.*\)'}} instead of @code{+ "$token"}.
11260 To make @command{expr} interpret keywords as strings, you must use the
11261 @code{quote} operator.
11264 @node Numeric expressions
11265 @subsection Numeric expressions
11267 @cindex numeric expressions
11268 @cindex expressions, numeric
11270 @command{expr} supports the usual numeric operators, in order of increasing
11271 precedence. These numeric operators have lower precedence than the
11272 string operators described in the previous section, and higher precedence
11273 than the connectives (next section).
11281 @cindex subtraction
11282 Addition and subtraction. Both arguments are converted to integers;
11283 an error occurs if this cannot be done.
11289 @cindex multiplication
11292 Multiplication, division, remainder. Both arguments are converted to
11293 integers; an error occurs if this cannot be done.
11298 @node Relations for expr
11299 @subsection Relations for @command{expr}
11301 @cindex connectives, logical
11302 @cindex logical connectives
11303 @cindex relations, numeric or string
11305 @command{expr} supports the usual logical connectives and relations. These
11306 have lower precedence than the string and numeric operators
11307 (previous sections). Here is the list, lowest-precedence operator first.
11313 @cindex logical or operator
11314 @cindex or operator
11315 Returns its first argument if that is neither null nor zero, otherwise
11316 its second argument if it is neither null nor zero, otherwise 0. It
11317 does not evaluate its second argument if its first argument is neither
11322 @cindex logical and operator
11323 @cindex and operator
11324 Return its first argument if neither argument is null or zero, otherwise
11325 0. It does not evaluate its second argument if its first argument is
11328 @item < <= = == != >= >
11335 @cindex comparison operators
11337 Compare the arguments and return 1 if the relation is true, 0 otherwise.
11338 @code{==} is a synonym for @code{=}. @command{expr} first tries to convert
11339 both arguments to integers and do a numeric comparison; if either
11340 conversion fails, it does a lexicographic comparison using the character
11341 collating sequence specified by the @env{LC_COLLATE} locale.
11346 @node Examples of expr
11347 @subsection Examples of using @command{expr}
11349 @cindex examples of @command{expr}
11350 Here are a few examples, including quoting for shell metacharacters.
11352 To add 1 to the shell variable @code{foo}, in Bourne-compatible shells:
11355 foo=`expr $foo + 1`
11358 To print the non-directory part of the file name stored in
11359 @code{$fname}, which need not contain a @code{/}:
11362 expr $fname : '.*/\(.*\)' '|' $fname
11365 An example showing that @code{\+} is an operator:
11373 expr abc : 'a\(.\)c'
11375 expr index abcdef cz
11378 @error{} expr: syntax error
11379 expr index + index a
11385 @chapter Redirection
11387 @cindex redirection
11388 @cindex commands for redirection
11390 Unix shells commonly provide several forms of @dfn{redirection}---ways
11391 to change the input source or output destination of a command. But one
11392 useful redirection is performed by a separate command, not by the shell;
11393 it's described here.
11396 * tee invocation:: Redirect output to multiple files or processes.
11400 @node tee invocation
11401 @section @command{tee}: Redirect output to multiple files or processes
11404 @cindex pipe fitting
11405 @cindex destinations, multiple output
11406 @cindex read from stdin and write to stdout and files
11408 The @command{tee} command copies standard input to standard output and also
11409 to any files given as arguments. This is useful when you want not only
11410 to send some data down a pipe, but also to save a copy. Synopsis:
11413 tee [@var{option}]@dots{} [@var{file}]@dots{}
11416 If a file being written to does not already exist, it is created. If a
11417 file being written to already exists, the data it previously contained
11418 is overwritten unless the @option{-a} option is used.
11420 A @var{file} of @samp{-} causes @command{tee} to send another copy of
11421 input to standard output, but this is typically not that useful as the
11422 copies are interleaved.
11424 The program accepts the following options. Also see @ref{Common options}.
11431 Append standard input to the given files rather than overwriting
11435 @itemx --ignore-interrupts
11437 @opindex --ignore-interrupts
11438 Ignore interrupt signals.
11442 The @command{tee} command is useful when you happen to be transferring a large
11443 amount of data and also want to summarize that data without reading
11444 it a second time. For example, when you are downloading a DVD image,
11445 you often want to verify its signature or checksum right away.
11446 The inefficient way to do it is simply:
11449 wget http://example.com/some.iso && sha1sum some.iso
11452 One problem with the above is that it makes you wait for the
11453 download to complete before starting the time-consuming SHA1 computation.
11454 Perhaps even more importantly, the above requires reading
11455 the DVD image a second time (the first was from the network).
11457 The efficient way to do it is to interleave the download
11458 and SHA1 computation. Then, you'll get the checksum for
11459 free, because the entire process parallelizes so well:
11462 # slightly contrived, to demonstrate process substitution
11463 wget -O - http://example.com/dvd.iso \
11464 | tee >(sha1sum > dvd.sha1) > dvd.iso
11467 That makes @command{tee} write not just to the expected output file,
11468 but also to a pipe running @command{sha1sum} and saving the final
11469 checksum in a file named @file{dvd.sha1}.
11471 Note, however, that this example relies on a feature of modern shells
11472 called @dfn{process substitution}
11473 (the @samp{>(command)} syntax, above;
11474 @xref{Process Substitution,,Process Substitution, bashref,
11475 The Bash Reference Manual}.),
11476 so it works with @command{zsh}, @command{bash}, and @command{ksh},
11477 but not with @command{/bin/sh}. So if you write code like this
11478 in a shell script, be sure to start the script with @samp{#!/bin/bash}.
11480 Since the above example writes to one file and one process,
11481 a more conventional and portable use of @command{tee} is even better:
11484 wget -O - http://example.com/dvd.iso \
11485 | tee dvd.iso | sha1sum > dvd.sha1
11488 You can extend this example to make @command{tee} write to two processes,
11489 computing MD5 and SHA1 checksums in parallel. In this case,
11490 process substitution is required:
11493 wget -O - http://example.com/dvd.iso \
11494 | tee >(sha1sum > dvd.sha1) \
11495 >(md5sum > dvd.md5) \
11499 This technique is also useful when you want to make a @emph{compressed}
11500 copy of the contents of a pipe.
11501 Consider a tool to graphically summarize disk usage data from @samp{du -ak}.
11502 For a large hierarchy, @samp{du -ak} can run for a long time,
11503 and can easily produce terabytes of data, so you won't want to
11504 rerun the command unnecessarily. Nor will you want to save
11505 the uncompressed output.
11507 Doing it the inefficient way, you can't even start the GUI
11508 until after you've compressed all of the @command{du} output:
11511 du -ak | gzip -9 > /tmp/du.gz
11512 gzip -d /tmp/du.gz | xdiskusage -a
11515 With @command{tee} and process substitution, you start the GUI
11516 right away and eliminate the decompression completely:
11519 du -ak | tee >(gzip -9 > /tmp/du.gz) | xdiskusage -a
11522 Finally, if you regularly create more than one type of
11523 compressed tarball at once, for example when @code{make dist} creates
11524 both @command{gzip}-compressed and @command{bzip2}-compressed tarballs,
11525 there may be a better way.
11526 Typical @command{automake}-generated @file{Makefile} rules create
11527 the two compressed tar archives with commands in sequence, like this
11528 (slightly simplified):
11531 tardir=your-pkg-M.N
11532 tar chof - "$tardir" | gzip -9 -c > your-pkg-M.N.tar.gz
11533 tar chof - "$tardir" | bzip2 -9 -c > your-pkg-M.N.tar.bz2
11536 However, if the hierarchy you are archiving and compressing is larger
11537 than a couple megabytes, and especially if you are using a multi-processor
11538 system with plenty of memory, then you can do much better by reading the
11539 directory contents only once and running the compression programs in parallel:
11542 tardir=your-pkg-M.N
11543 tar chof - "$tardir" \
11544 | tee >(gzip -9 -c > your-pkg-M.N.tar.gz) \
11545 | bzip2 -9 -c > your-pkg-M.N.tar.bz2
11551 @node File name manipulation
11552 @chapter File name manipulation
11554 @cindex file name manipulation
11555 @cindex manipulation of file names
11556 @cindex commands for file name manipulation
11558 This section describes commands that manipulate file names.
11561 * basename invocation:: Strip directory and suffix from a file name.
11562 * dirname invocation:: Strip non-directory suffix from a file name.
11563 * pathchk invocation:: Check file name portability.
11567 @node basename invocation
11568 @section @command{basename}: Strip directory and suffix from a file name
11571 @cindex strip directory and suffix from file names
11572 @cindex directory, stripping from file names
11573 @cindex suffix, stripping from file names
11574 @cindex file names, stripping directory and suffix
11575 @cindex leading directory components, stripping
11577 @command{basename} removes any leading directory components from
11578 @var{name}. Synopsis:
11581 basename @var{name} [@var{suffix}]
11584 If @var{suffix} is specified and is identical to the end of @var{name},
11585 it is removed from @var{name} as well. Note that since trailing slashes
11586 are removed prior to suffix matching, @var{suffix} will do nothing if it
11587 contains slashes. @command{basename} prints the result on standard
11590 @c This test is used both here and in the section on dirname.
11591 @macro basenameAndDirname
11592 Together, @command{basename} and @command{dirname} are designed such
11593 that if @samp{ls "$name"} succeeds, then the command sequence @samp{cd
11594 "$(dirname "$name")"; ls "$(basename "$name")"} will, too. This works
11595 for everything except file names containing a trailing newline.
11597 @basenameAndDirname
11599 @acronym{POSIX} allows the implementation to define the results if
11600 @var{name} is empty or @samp{//}. In the former case, @acronym{GNU}
11601 @command{basename} returns the empty string. In the latter case, the
11602 result is @samp{//} on platforms where @var{//} is distinct from
11603 @var{/}, and @samp{/} on platforms where there is no difference.
11605 The only options are @option{--help} and @option{--version}. @xref{Common
11606 options}. Options must precede operands.
11614 basename /usr/bin/sort
11617 basename include/stdio.h .h
11621 @node dirname invocation
11622 @section @command{dirname}: Strip non-directory suffix from a file name
11625 @cindex directory components, printing
11626 @cindex stripping non-directory suffix
11627 @cindex non-directory suffix, stripping
11629 @command{dirname} prints all but the final slash-delimited component of
11630 a string (presumably a file name). Synopsis:
11636 If @var{name} is a single component, @command{dirname} prints @samp{.}
11637 (meaning the current directory).
11639 @basenameAndDirname
11641 @acronym{POSIX} allows the implementation to define the results if
11642 @var{name} is @samp{//}. With @acronym{GNU} @command{dirname}, the
11643 result is @samp{//} on platforms where @var{//} is distinct from
11644 @var{/}, and @samp{/} on platforms where there is no difference.
11646 The only options are @option{--help} and @option{--version}. @xref{Common
11654 # Output "/usr/bin".
11655 dirname /usr/bin/sort
11662 @node pathchk invocation
11663 @section @command{pathchk}: Check file name portability
11666 @cindex file names, checking validity and portability
11667 @cindex valid file names, checking for
11668 @cindex portable file names, checking for
11670 @command{pathchk} checks portability of file names. Synopsis:
11673 pathchk [@var{option}]@dots{} @var{name}@dots{}
11676 For each @var{name}, @command{pathchk} prints a message if any of
11677 these conditions is true:
11681 One of the existing directories in @var{name} does not have search
11682 (execute) permission,
11684 The length of @var{name} is larger than the maximum supported by the
11687 The length of one component of @var{name} is longer than
11688 its file system's maximum.
11691 A nonexistent @var{name} is not an error, so long a file with that
11692 name could be created under the above conditions.
11694 The program accepts the following options. Also see @ref{Common options}.
11695 Options must precede operands.
11701 Instead of performing checks based on the underlying file system,
11702 print a message if any of these conditions is true:
11706 A file name is empty.
11709 The length of a file name or one of its components exceeds the
11710 @acronym{POSIX} minimum limits for portability.
11713 A file name contains a character outside the portable file name
11714 character set, namely, the ASCII letters and digits, @samp{-},
11715 @samp{.}, @samp{/}, and @samp{_}.
11720 Print a message if a file name is empty, or if it contains a component
11721 that begins with @samp{-}.
11723 @item --portability
11724 @opindex --portability
11725 Print a message if a file name is not portable to all @acronym{POSIX}
11726 hosts. This option is equivalent to @samp{-p -P}.
11730 @cindex exit status of @command{pathchk}
11734 0 if all specified file names passed all checks,
11739 @node Working context
11740 @chapter Working context
11742 @cindex working context
11743 @cindex commands for printing the working context
11745 This section describes commands that display or alter the context in
11746 which you are working: the current directory, the terminal settings, and
11747 so forth. See also the user-related commands in the next section.
11750 * pwd invocation:: Print working directory.
11751 * stty invocation:: Print or change terminal characteristics.
11752 * printenv invocation:: Print environment variables.
11753 * tty invocation:: Print file name of terminal on standard input.
11757 @node pwd invocation
11758 @section @command{pwd}: Print working directory
11761 @cindex print name of current directory
11762 @cindex current working directory, printing
11763 @cindex working directory, printing
11765 @cindex symbolic links and @command{pwd}
11766 @command{pwd} prints the fully resolved name of the current directory.
11767 That is, all components of the printed name will be actual directory
11768 names---none will be symbolic links.
11770 The only options are a lone @option{--help} or
11771 @option{--version}. @xref{Common options}.
11773 @mayConflictWithShellBuiltIn{pwd}
11778 @node stty invocation
11779 @section @command{stty}: Print or change terminal characteristics
11782 @cindex change or print terminal settings
11783 @cindex terminal settings
11784 @cindex line settings of terminal
11786 @command{stty} prints or changes terminal characteristics, such as baud rate.
11790 stty [@var{option}] [@var{setting}]@dots{}
11791 stty [@var{option}]
11794 If given no line settings, @command{stty} prints the baud rate, line
11795 discipline number (on systems that support it), and line settings
11796 that have been changed from the values set by @samp{stty sane}.
11797 By default, mode reading and setting are performed on the tty line
11798 connected to standard input, although this can be modified by the
11799 @option{--file} option.
11801 @command{stty} accepts many non-option arguments that change aspects of
11802 the terminal line operation, as described below.
11804 The program accepts the following options. Also see @ref{Common options}.
11811 Print all current settings in human-readable form. This option may not
11812 be used in combination with any line settings.
11814 @item -F @var{device}
11815 @itemx --file=@var{device}
11818 Set the line opened by the file name specified in @var{device} instead of
11819 the tty line connected to standard input. This option is necessary
11820 because opening a @acronym{POSIX} tty requires use of the @code{O_NONDELAY} flag to
11821 prevent a @acronym{POSIX} tty from blocking until the carrier detect line is high if
11822 the @code{clocal} flag is not set. Hence, it is not always possible
11823 to allow the shell to open the device in the traditional manner.
11829 @cindex machine-readable @command{stty} output
11830 Print all current settings in a form that can be used as an argument to
11831 another @command{stty} command to restore the current settings. This option
11832 may not be used in combination with any line settings.
11836 Many settings can be turned off by preceding them with a @samp{-}.
11837 Such arguments are marked below with ``May be negated'' in their
11838 description. The descriptions themselves refer to the positive
11839 case, that is, when @emph{not} negated (unless stated otherwise,
11842 Some settings are not available on all @acronym{POSIX} systems, since they use
11843 extensions. Such arguments are marked below with ``Non-@acronym{POSIX}'' in their
11844 description. On non-@acronym{POSIX} systems, those or other settings also may not
11845 be available, but it's not feasible to document all the variations: just
11851 * Control:: Control settings
11852 * Input:: Input settings
11853 * Output:: Output settings
11854 * Local:: Local settings
11855 * Combination:: Combination settings
11856 * Characters:: Special characters
11857 * Special:: Special settings
11862 @subsection Control settings
11864 @cindex control settings
11870 @cindex two-way parity
11871 Generate parity bit in output and expect parity bit in input.
11877 @cindex even parity
11878 Set odd parity (even if negated). May be negated.
11885 @cindex character size
11886 @cindex eight-bit characters
11887 Set character size to 5, 6, 7, or 8 bits.
11892 Send a hangup signal when the last process closes the tty. May be
11898 Use two stop bits per character (one if negated). May be negated.
11902 Allow input to be received. May be negated.
11906 @cindex modem control
11907 Disable modem control signals. May be negated.
11911 @cindex hardware flow control
11912 @cindex flow control, hardware
11913 @cindex RTS/CTS flow control
11914 Enable RTS/CTS flow control. Non-@acronym{POSIX}. May be negated.
11919 @subsection Input settings
11921 @cindex input settings
11926 @cindex breaks, ignoring
11927 Ignore break characters. May be negated.
11931 @cindex breaks, cause interrupts
11932 Make breaks cause an interrupt signal. May be negated.
11936 @cindex parity, ignoring
11937 Ignore characters with parity errors. May be negated.
11941 @cindex parity errors, marking
11942 Mark parity errors (with a 255-0-character sequence). May be negated.
11946 Enable input parity checking. May be negated.
11950 @cindex eight-bit input
11951 Clear high (8th) bit of input characters. May be negated.
11955 @cindex newline, translating to return
11956 Translate newline to carriage return. May be negated.
11960 @cindex return, ignoring
11961 Ignore carriage return. May be negated.
11965 @cindex return, translating to newline
11966 Translate carriage return to newline. May be negated.
11970 @cindex input encoding, UTF-8
11971 Assume input characters are UTF-8 encoded. May be negated.
11975 @kindex C-s/C-q flow control
11976 @cindex XON/XOFF flow control
11977 Enable XON/XOFF flow control (that is, @kbd{CTRL-S}/@kbd{CTRL-Q}). May
11984 @cindex software flow control
11985 @cindex flow control, software
11986 Enable sending of @code{stop} character when the system input buffer
11987 is almost full, and @code{start} character when it becomes almost
11988 empty again. May be negated.
11992 @cindex uppercase, translating to lowercase
11993 Translate uppercase characters to lowercase. Non-@acronym{POSIX}. May be
11998 Allow any character to restart output (only the start character
11999 if negated). Non-@acronym{POSIX}. May be negated.
12003 @cindex beeping at input buffer full
12004 Enable beeping and not flushing input buffer if a character arrives
12005 when the input buffer is full. Non-@acronym{POSIX}. May be negated.
12010 @subsection Output settings
12012 @cindex output settings
12013 These arguments specify output-related operations.
12018 Postprocess output. May be negated.
12022 @cindex lowercase, translating to output
12023 Translate lowercase characters to uppercase. Non-@acronym{POSIX}. May be
12028 @cindex return, translating to newline
12029 Translate carriage return to newline. Non-@acronym{POSIX}. May be negated.
12033 @cindex newline, translating to crlf
12034 Translate newline to carriage return-newline. Non-@acronym{POSIX}. May be
12039 Do not print carriage returns in the first column. Non-@acronym{POSIX}.
12044 Newline performs a carriage return. Non-@acronym{POSIX}. May be negated.
12048 @cindex pad instead of timing for delaying
12049 Use fill (padding) characters instead of timing for delays. Non-@acronym{POSIX}.
12054 @cindex pad character
12055 Use delete characters for fill instead of null characters. Non-@acronym{POSIX}.
12061 Newline delay style. Non-@acronym{POSIX}.
12068 Carriage return delay style. Non-@acronym{POSIX}.
12074 @opindex tab@var{n}
12075 Horizontal tab delay style. Non-@acronym{POSIX}.
12080 Backspace delay style. Non-@acronym{POSIX}.
12085 Vertical tab delay style. Non-@acronym{POSIX}.
12090 Form feed delay style. Non-@acronym{POSIX}.
12095 @subsection Local settings
12097 @cindex local settings
12102 Enable @code{interrupt}, @code{quit}, and @code{suspend} special
12103 characters. May be negated.
12107 Enable @code{erase}, @code{kill}, @code{werase}, and @code{rprnt}
12108 special characters. May be negated.
12112 Enable non-@acronym{POSIX} special characters. May be negated.
12116 Echo input characters. May be negated.
12122 Echo @code{erase} characters as backspace-space-backspace. May be
12127 @cindex newline echoing after @code{kill}
12128 Echo a newline after a @code{kill} character. May be negated.
12132 @cindex newline, echoing
12133 Echo newline even if not echoing other characters. May be negated.
12137 @cindex flushing, disabling
12138 Disable flushing after @code{interrupt} and @code{quit} special
12139 characters. May be negated.
12143 @cindex case translation
12144 Enable input and output of uppercase characters by preceding their
12145 lowercase equivalents with @samp{\}, when @code{icanon} is set.
12146 Non-@acronym{POSIX}. May be negated.
12150 @cindex background jobs, stopping at terminal write
12151 Stop background jobs that try to write to the terminal. Non-@acronym{POSIX}.
12158 Echo erased characters backward, between @samp{\} and @samp{/}.
12159 Non-@acronym{POSIX}. May be negated.
12165 @cindex control characters, using @samp{^@var{c}}
12166 @cindex hat notation for control characters
12167 Echo control characters in hat notation (@samp{^@var{c}}) instead
12168 of literally. Non-@acronym{POSIX}. May be negated.
12174 Echo the @code{kill} special character by erasing each character on
12175 the line as indicated by the @code{echoprt} and @code{echoe} settings,
12176 instead of by the @code{echoctl} and @code{echok} settings. Non-@acronym{POSIX}.
12182 @subsection Combination settings
12184 @cindex combination settings
12185 Combination settings:
12192 Same as @code{parenb -parodd cs7}. May be negated. If negated, same
12193 as @code{-parenb cs8}.
12197 Same as @code{parenb parodd cs7}. May be negated. If negated, same
12198 as @code{-parenb cs8}.
12202 Same as @code{-icrnl -onlcr}. May be negated. If negated, same as
12203 @code{icrnl -inlcr -igncr onlcr -ocrnl -onlret}.
12207 Reset the @code{erase} and @code{kill} special characters to their default
12214 @c This is too long to write inline.
12216 cread -ignbrk brkint -inlcr -igncr icrnl -ixoff
12217 -iuclc -ixany imaxbel opost -olcuc -ocrnl onlcr
12218 -onocr -onlret -ofill -ofdel nl0 cr0 tab0 bs0 vt0
12219 ff0 isig icanon iexten echo echoe echok -echonl
12220 -noflsh -xcase -tostop -echoprt echoctl echoke
12224 and also sets all special characters to their default values.
12228 Same as @code{brkint ignpar istrip icrnl ixon opost isig icanon}, plus
12229 sets the @code{eof} and @code{eol} characters to their default values
12230 if they are the same as the @code{min} and @code{time} characters.
12231 May be negated. If negated, same as @code{raw}.
12238 -ignbrk -brkint -ignpar -parmrk -inpck -istrip
12239 -inlcr -igncr -icrnl -ixon -ixoff -iuclc -ixany
12240 -imaxbel -opost -isig -icanon -xcase min 1 time 0
12244 May be negated. If negated, same as @code{cooked}.
12248 Same as @option{-icanon}. May be negated. If negated, same as
12253 @cindex eight-bit characters
12254 Same as @code{-parenb -istrip cs8}. May be negated. If negated,
12255 same as @code{parenb istrip cs7}.
12259 Same as @option{-parenb -istrip -opost cs8}. May be negated.
12260 If negated, same as @code{parenb istrip opost cs7}.
12264 Same as @option{-ixany}. Non-@acronym{POSIX}. May be negated.
12268 Same as @code{tab0}. Non-@acronym{POSIX}. May be negated. If negated, same
12275 Same as @code{xcase iuclc olcuc}. Non-@acronym{POSIX}. May be negated.
12279 Same as @code{echoe echoctl echoke}.
12283 Same as @code{echoe echoctl echoke -ixany intr ^C erase ^? kill C-u}.
12288 @subsection Special characters
12290 @cindex special characters
12291 @cindex characters, special
12293 The special characters' default values vary from system to system.
12294 They are set with the syntax @samp{name value}, where the names are
12295 listed below and the value can be given either literally, in hat
12296 notation (@samp{^@var{c}}), or as an integer which may start with
12297 @samp{0x} to indicate hexadecimal, @samp{0} to indicate octal, or
12298 any other digit to indicate decimal.
12300 @cindex disabling special characters
12301 @kindex u@r{, and disabling special characters}
12302 For GNU stty, giving a value of @code{^-} or @code{undef} disables that
12303 special character. (This is incompatible with Ultrix @command{stty},
12304 which uses a value of @samp{u} to disable a special character. GNU
12305 @command{stty} treats a value @samp{u} like any other, namely to set that
12306 special character to @key{U}.)
12312 Send an interrupt signal.
12316 Send a quit signal.
12320 Erase the last character typed.
12324 Erase the current line.
12328 Send an end of file (terminate the input).
12336 Alternate character to end the line. Non-@acronym{POSIX}.
12340 Switch to a different shell layer. Non-@acronym{POSIX}.
12344 Restart the output after stopping it.
12352 Send a terminal stop signal.
12356 Send a terminal stop signal after flushing the input. Non-@acronym{POSIX}.
12360 Redraw the current line. Non-@acronym{POSIX}.
12364 Erase the last word typed. Non-@acronym{POSIX}.
12368 Enter the next character typed literally, even if it is a special
12369 character. Non-@acronym{POSIX}.
12374 @subsection Special settings
12376 @cindex special settings
12381 Set the minimum number of characters that will satisfy a read until
12382 the time value has expired, when @option{-icanon} is set.
12386 Set the number of tenths of a second before reads time out if the minimum
12387 number of characters have not been read, when @option{-icanon} is set.
12389 @item ispeed @var{n}
12391 Set the input speed to @var{n}.
12393 @item ospeed @var{n}
12395 Set the output speed to @var{n}.
12399 Tell the tty kernel driver that the terminal has @var{n} rows. Non-@acronym{POSIX}.
12402 @itemx columns @var{n}
12405 Tell the kernel that the terminal has @var{n} columns. Non-@acronym{POSIX}.
12411 Print the number of rows and columns that the kernel thinks the
12412 terminal has. (Systems that don't support rows and columns in the kernel
12413 typically use the environment variables @env{LINES} and @env{COLUMNS}
12414 instead; however, GNU @command{stty} does not know anything about them.)
12415 Non-@acronym{POSIX}.
12419 Use line discipline @var{n}. Non-@acronym{POSIX}.
12423 Print the terminal speed.
12426 @cindex baud rate, setting
12427 Set the input and output speeds to @var{n}. @var{n} can be one of: 0
12428 50 75 110 134 134.5 150 200 300 600 1200 1800 2400 4800 9600 19200
12429 38400 @code{exta} @code{extb}. @code{exta} is the same as 19200;
12430 @code{extb} is the same as 38400. Many systems, including GNU/Linux,
12431 support higher speeds. The @command{stty} command includes support
12448 4000000 where the system supports these.
12449 0 hangs up the line if @option{-clocal} is set.
12453 @node printenv invocation
12454 @section @command{printenv}: Print all or some environment variables
12457 @cindex printing all or some environment variables
12458 @cindex environment variables, printing
12460 @command{printenv} prints environment variable values. Synopsis:
12463 printenv [@var{option}] [@var{variable}]@dots{}
12466 If no @var{variable}s are specified, @command{printenv} prints the value of
12467 every environment variable. Otherwise, it prints the value of each
12468 @var{variable} that is set, and nothing for those that are not set.
12470 The only options are a lone @option{--help} or @option{--version}.
12471 @xref{Common options}.
12473 @cindex exit status of @command{printenv}
12477 0 if all variables specified were found
12478 1 if at least one specified variable was not found
12479 2 if a write error occurred
12483 @node tty invocation
12484 @section @command{tty}: Print file name of terminal on standard input
12487 @cindex print terminal file name
12488 @cindex terminal file name, printing
12490 @command{tty} prints the file name of the terminal connected to its standard
12491 input. It prints @samp{not a tty} if standard input is not a terminal.
12495 tty [@var{option}]@dots{}
12498 The program accepts the following option. Also see @ref{Common options}.
12508 Print nothing; only return an exit status.
12512 @cindex exit status of @command{tty}
12516 0 if standard input is a terminal
12517 1 if standard input is not a terminal
12518 2 if given incorrect arguments
12519 3 if a write error occurs
12523 @node User information
12524 @chapter User information
12526 @cindex user information, commands for
12527 @cindex commands for printing user information
12529 This section describes commands that print user-related information:
12530 logins, groups, and so forth.
12533 * id invocation:: Print user identity.
12534 * logname invocation:: Print current login name.
12535 * whoami invocation:: Print effective user ID.
12536 * groups invocation:: Print group names a user is in.
12537 * users invocation:: Print login names of users currently logged in.
12538 * who invocation:: Print who is currently logged in.
12542 @node id invocation
12543 @section @command{id}: Print user identity
12546 @cindex real user and group IDs, printing
12547 @cindex effective user and group IDs, printing
12548 @cindex printing real and effective user and group IDs
12550 @command{id} prints information about the given user, or the process
12551 running it if no user is specified. Synopsis:
12554 id [@var{option}]@dots{} [@var{username}]
12557 By default, it prints the real user ID, real group ID, effective user ID
12558 if different from the real user ID, effective group ID if different from
12559 the real group ID, and supplemental group IDs.
12561 Each of these numeric values is preceded by an identifying string and
12562 followed by the corresponding user or group name in parentheses.
12564 The options cause @command{id} to print only part of the above information.
12565 Also see @ref{Common options}.
12572 Print only the group ID.
12578 Print only the group ID and the supplementary groups.
12584 Print the user or group name instead of the ID number. Requires
12585 @option{-u}, @option{-g}, or @option{-G}.
12591 Print the real, instead of effective, user or group ID. Requires
12592 @option{-u}, @option{-g}, or @option{-G}.
12598 Print only the user ID.
12604 @macro primaryAndSupplementaryGroups{cmd,arg}
12605 Primary and supplementary groups for a process are normally inherited
12606 from its parent and are usually unchanged since login. This means
12607 that if you change the group database after logging in, @command{\cmd\}
12608 will not reflect your changes within your existing login session.
12609 Running @command{\cmd\} with a \arg\ causes the user and group
12610 database to be consulted afresh, and so will give a different result.
12612 @primaryAndSupplementaryGroups{id,user argument}
12614 @node logname invocation
12615 @section @command{logname}: Print current login name
12618 @cindex printing user's login name
12619 @cindex login name, printing
12620 @cindex user name, printing
12623 @command{logname} prints the calling user's name, as found in a
12624 system-maintained file (often @file{/var/run/utmp} or
12625 @file{/etc/utmp}), and exits with a status of 0. If there is no entry
12626 for the calling process, @command{logname} prints
12627 an error message and exits with a status of 1.
12629 The only options are @option{--help} and @option{--version}. @xref{Common
12635 @node whoami invocation
12636 @section @command{whoami}: Print effective user ID
12639 @cindex effective user ID, printing
12640 @cindex printing the effective user ID
12642 @command{whoami} prints the user name associated with the current
12643 effective user ID. It is equivalent to the command @samp{id -un}.
12645 The only options are @option{--help} and @option{--version}. @xref{Common
12651 @node groups invocation
12652 @section @command{groups}: Print group names a user is in
12655 @cindex printing groups a user is in
12656 @cindex supplementary groups, printing
12658 @command{groups} prints the names of the primary and any supplementary
12659 groups for each given @var{username}, or the current process if no names
12660 are given. If more than one name is given, the name of each user is
12662 the list of that user's groups and the user name is separated from the
12663 group list by a colon. Synopsis:
12666 groups [@var{username}]@dots{}
12669 The group lists are equivalent to the output of the command @samp{id -Gn}.
12671 @primaryAndSupplementaryGroups{groups,list of users}
12673 The only options are @option{--help} and @option{--version}. @xref{Common
12679 @node users invocation
12680 @section @command{users}: Print login names of users currently logged in
12683 @cindex printing current usernames
12684 @cindex usernames, printing current
12686 @cindex login sessions, printing users with
12687 @command{users} prints on a single line a blank-separated list of user
12688 names of users currently logged in to the current host. Each user name
12689 corresponds to a login session, so if a user has more than one login
12690 session, that user's name will appear the same number of times in the
12699 With no @var{file} argument, @command{users} extracts its information from
12700 a system-maintained file (often @file{/var/run/utmp} or
12701 @file{/etc/utmp}). If a file argument is given, @command{users} uses
12702 that file instead. A common choice is @file{/var/log/wtmp}.
12704 The only options are @option{--help} and @option{--version}. @xref{Common
12710 @node who invocation
12711 @section @command{who}: Print who is currently logged in
12714 @cindex printing current user information
12715 @cindex information, about current users
12717 @command{who} prints information about users who are currently logged on.
12721 @command{who} [@var{option}] [@var{file}] [am i]
12724 @cindex terminal lines, currently used
12726 @cindex remote hostname
12727 If given no non-option arguments, @command{who} prints the following
12728 information for each user currently logged on: login name, terminal
12729 line, login time, and remote hostname or X display.
12733 If given one non-option argument, @command{who} uses that instead of
12734 a default system-maintained file (often @file{/var/run/utmp} or
12735 @file{/etc/utmp}) as the name of the file containing the record of
12736 users logged on. @file{/var/log/wtmp} is commonly given as an argument
12737 to @command{who} to look at who has previously logged on.
12741 If given two non-option arguments, @command{who} prints only the entry
12742 for the user running it (determined from its standard input), preceded
12743 by the hostname. Traditionally, the two arguments given are @samp{am
12744 i}, as in @samp{who am i}.
12747 Time stamps are listed according to the time zone rules specified by
12748 the @env{TZ} environment variable, or by the system default rules if
12749 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
12750 with @env{TZ}, libc, The GNU C Library Reference Manual}.
12752 The program accepts the following options. Also see @ref{Common options}.
12760 Same as @samp{-b -d --login -p -r -t -T -u}.
12766 Print the date and time of last system boot.
12772 Print information corresponding to dead processes.
12778 Print a line of column headings.
12784 List only the entries that correspond to processes via which the
12785 system is waiting for a user to login. The user name is always @samp{LOGIN}.
12789 Attempt to canonicalize hostnames found in utmp through a DNS lookup. This
12790 is not the default because it can cause significant delays on systems with
12791 automatic dial-up internet access.
12795 Same as @samp{who am i}.
12801 List active processes spawned by init.
12807 Print only the login names and the number of users logged on.
12808 Overrides all other options.
12813 @opindex --runlevel
12814 Print the current (and maybe previous) run-level of the init process.
12818 Ignored; for compatibility with other versions of @command{who}.
12824 Print last system clock change.
12829 After the login time, print the number of hours and minutes that the
12830 user has been idle. @samp{.} means the user was active in the last minute.
12831 @samp{old} means the user has been idle for more than 24 hours.
12842 @opindex --writable
12843 @cindex message status
12844 @pindex write@r{, allowed}
12845 After each login name print a character indicating the user's message status:
12848 @samp{+} allowing @code{write} messages
12849 @samp{-} disallowing @code{write} messages
12850 @samp{?} cannot find terminal device
12858 @node System context
12859 @chapter System context
12861 @cindex system context
12862 @cindex context, system
12863 @cindex commands for system context
12865 This section describes commands that print or change system-wide
12869 * arch invocation:: Print machine hardware name.
12870 * date invocation:: Print or set system date and time.
12871 * uname invocation:: Print system information.
12872 * hostname invocation:: Print or set system name.
12873 * hostid invocation:: Print numeric host identifier.
12874 * uptime invocation:: Print system uptime and load
12877 @node SELinux context
12878 @chapter SELinux context
12880 @cindex SELinux context
12881 @cindex SELinux, context
12882 @cindex commands for SELinux context
12884 This section describes commands for operations with SELinux
12888 * chcon invocation:: Change SELinux context of file
12889 * runcon invocation:: Run a command in specified SELinux context
12892 @node chcon invocation
12893 @section @command{chcon}: Change SELinux context of file.
12896 @cindex changing security context
12897 @cindex change SELinux context
12899 @command{chcon} changes the SELinux security context of the selected files.
12903 chcon [@var{option}]@dots{} @var{context} @var{file}@dots{}
12904 chcon [@var{option}]@dots{} [-u @var{user}] [-r @var{role}] [-l @var{range}] [-t @var{type}] @var{file}@dots{}
12905 chcon [@var{option}]@dots{} --reference=@var{rfile} @var{file}@dots{}
12908 Change the SELinux security context of each @var{file} to @var{context}.
12909 With @option{--reference}, change the security context of each @var{file}
12910 to that of @var{rfile}.
12912 The program accepts the following options. Also see @ref{Common options}.
12917 @itemx --no-dereference
12919 @opindex --no-dereference
12920 @cindex no dereference
12921 Affect symbolic links instead of any referenced file.
12923 @item --reference=@var{rfile}
12924 @opindex --reference
12925 @cindex reference file
12926 Use @var{rfile}'s security context rather than specifying a @var{context} value.
12931 @opindex --recursive
12932 Operate on files and directories recursively.
12935 @xref{Traversing symlinks}.
12938 @xref{Traversing symlinks}.
12941 @xref{Traversing symlinks}.
12948 Output a diagnostic for every file processed.
12950 @item -u @var{user}
12951 @itemx --user=@var{user}
12954 Set user @var{user} in the target security context.
12956 @item -r @var{role}
12957 @itemx --role=@var{role}
12960 Set role @var{role} in the target security context.
12962 @item -t @var{type}
12963 @itemx --type=@var{type}
12966 Set type @var{type} in the target security context.
12968 @item -l @var{range}
12969 @itemx --range=@var{range}
12972 Set range @var{range} in the target security context.
12978 @node runcon invocation
12979 @section @command{runcon}: Run a command in specified SELinux context
12982 @cindex run with security context
12985 @command{runcon} runs file in specified SELinux security context.
12989 runcon @var{context} @var{command} [@var{args}]
12990 runcon [ -c ] [-u @var{user}] [-r @var{role}] [-t @var{type}] [-l @var{range}] @var{command} [@var{args}]
12993 Run @var{command} with completely-specified @var{context}, or with
12994 current or transitioned security context modified by one or more of @var{level},
12995 @var{role}, @var{type} and @var{user}.
12997 If none of @option{-c}, @option{-t}, @option{-u}, @option{-r}, or @option{-l}
12998 is specified, the first argument is used as the complete context.
12999 Any additional arguments after @var{command}
13000 are interpreted as arguments to the command.
13002 With neither @var{context} nor @var{command}, print the current security context.
13004 The program accepts the following options. Also see @ref{Common options}.
13012 Compute process transition context before modifying.
13014 @item -u @var{user}
13015 @itemx --user=@var{user}
13018 Set user @var{user} in the target security context.
13020 @item -r @var{role}
13021 @itemx --role=@var{role}
13024 Set role @var{role} in the target security context.
13026 @item -t @var{type}
13027 @itemx --type=@var{type}
13030 Set type @var{type} in the target security context.
13032 @item -l @var{range}
13033 @itemx --range=@var{range}
13036 Set range @var{range} in the target security context.
13040 @cindex exit status of @command{runcon}
13044 126 if @var{command} is found but cannot be invoked
13045 127 if @command{runcon} itself fails or if @var{command} cannot be found
13046 the exit status of @var{command} otherwise
13049 @node date invocation
13050 @section @command{date}: Print or set system date and time
13053 @cindex time, printing or setting
13054 @cindex printing the current time
13059 date [@var{option}]@dots{} [+@var{format}]
13060 date [-u|--utc|--universal] @c this avoids a newline in the output
13061 [ MMDDhhmm[[CC]YY][.ss] ]
13065 Invoking @command{date} with no @var{format} argument is equivalent to invoking
13066 it with a default format that depends on the @env{LC_TIME} locale category.
13067 In the default C locale, this format is @samp{'+%a %b %e %H:%M:%S %Z %Y'},
13068 so the output looks like @samp{Thu Mar @ 3 13:47:51 PST 2005}.
13071 Normally, @command{date} uses the time zone rules indicated by the
13072 @env{TZ} environment variable, or the system default rules if @env{TZ}
13073 is not set. @xref{TZ Variable,, Specifying the Time Zone with
13074 @env{TZ}, libc, The GNU C Library Reference Manual}.
13076 @findex strftime @r{and @command{date}}
13077 @cindex time formats
13078 @cindex formatting times
13079 If given an argument that starts with a @samp{+}, @command{date} prints the
13080 current date and time (or the date and time specified by the
13081 @option{--date} option, see below) in the format defined by that argument,
13082 which is similar to that of the @code{strftime} function. Except for
13083 conversion specifiers, which start with @samp{%}, characters in the
13084 format string are printed unchanged. The conversion specifiers are
13090 * Time conversion specifiers:: %[HIklMNpPrRsSTXzZ]
13091 * Date conversion specifiers:: %[aAbBcCdDeFgGhjmuUVwWxyY]
13092 * Literal conversion specifiers:: %[%nt]
13093 * Padding and other flags:: Pad with zeros, spaces, etc.
13094 * Setting the time:: Changing the system clock.
13095 * Options for date:: Instead of the current time.
13097 * Date input formats:: Specifying date strings.
13099 * Examples of date:: Examples.
13102 @node Time conversion specifiers
13103 @subsection Time conversion specifiers
13105 @cindex time conversion specifiers
13106 @cindex conversion specifiers, time
13108 @command{date} conversion specifiers related to times.
13112 hour (@samp{00}@dots{}@samp{23})
13114 hour (@samp{01}@dots{}@samp{12})
13116 hour (@samp{ 0}@dots{}@samp{23}).
13117 This is a @acronym{GNU} extension.
13119 hour (@samp{ 1}@dots{}@samp{12}).
13120 This is a @acronym{GNU} extension.
13122 minute (@samp{00}@dots{}@samp{59})
13124 nanoseconds (@samp{000000000}@dots{}@samp{999999999}).
13125 This is a @acronym{GNU} extension.
13127 locale's equivalent of either @samp{AM} or @samp{PM};
13128 blank in many locales.
13129 Noon is treated as @samp{PM} and midnight as @samp{AM}.
13131 like @samp{%p}, except lower case.
13132 This is a @acronym{GNU} extension.
13134 locale's 12-hour clock time (e.g., @samp{11:11:04 PM})
13136 24-hour hour and minute. Same as @samp{%H:%M}.
13137 This is a @acronym{GNU} extension.
13139 @cindex epoch, seconds since
13140 @cindex seconds since the epoch
13141 @cindex beginning of time
13142 seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
13143 Leap seconds are not counted unless leap second support is available.
13144 @xref{%s-examples}, for examples.
13145 This is a @acronym{GNU} extension.
13147 second (@samp{00}@dots{}@samp{60}).
13148 This may be @samp{60} if leap seconds are supported.
13150 24-hour hour, minute, and second. Same as @samp{%H:%M:%S}.
13152 locale's time representation (e.g., @samp{23:13:48})
13154 @w{@acronym{RFC} 2822/@acronym{ISO} 8601} style numeric time zone
13155 (e.g., @samp{-0600} or @samp{+0530}), or nothing if no
13156 time zone is determinable. This value reflects the numeric time zone
13157 appropriate for the current time, using the time zone rules specified
13158 by the @env{TZ} environment variable.
13159 The time (and optionally, the time zone rules) can be overridden
13160 by the @option{--date} option.
13161 This is a @acronym{GNU} extension.
13163 @w{@acronym{RFC} 3339/@acronym{ISO} 8601} style numeric time zone with
13164 @samp{:} (e.g., @samp{-06:00} or @samp{+05:30}), or nothing if no time
13165 zone is determinable.
13166 This is a @acronym{GNU} extension.
13168 Numeric time zone to the nearest second with @samp{:} (e.g.,
13169 @samp{-06:00:00} or @samp{+05:30:00}), or nothing if no time zone is
13171 This is a @acronym{GNU} extension.
13173 Numeric time zone with @samp{:} using the minimum necessary precision
13174 (e.g., @samp{-06}, @samp{+05:30}, or @samp{-04:56:02}), or nothing if
13175 no time zone is determinable.
13176 This is a @acronym{GNU} extension.
13178 alphabetic time zone abbreviation (e.g., @samp{EDT}), or nothing if no
13179 time zone is determinable. See @samp{%z} for how it is determined.
13183 @node Date conversion specifiers
13184 @subsection Date conversion specifiers
13186 @cindex date conversion specifiers
13187 @cindex conversion specifiers, date
13189 @command{date} conversion specifiers related to dates.
13193 locale's abbreviated weekday name (e.g., @samp{Sun})
13195 locale's full weekday name, variable length (e.g., @samp{Sunday})
13197 locale's abbreviated month name (e.g., @samp{Jan})
13199 locale's full month name, variable length (e.g., @samp{January})
13201 locale's date and time (e.g., @samp{Thu Mar @ 3 23:05:25 2005})
13203 century. This is like @samp{%Y}, except the last two digits are omitted.
13204 For example, it is @samp{20} if @samp{%Y} is @samp{2000},
13205 and is @samp{-0} if @samp{%Y} is @samp{-001}.
13206 It is normally at least two characters, but it may be more.
13208 day of month (e.g., @samp{01})
13210 date; same as @samp{%m/%d/%y}
13212 day of month, space padded; same as @samp{%_d}
13214 full date in @acronym{ISO} 8601 format; same as @samp{%Y-%m-%d}.
13215 This is a good choice for a date format, as it is standard and
13216 is easy to sort in the usual case where years are in the range
13218 This is a @acronym{GNU} extension.
13220 year corresponding to the @acronym{ISO} week number, but without the century
13221 (range @samp{00} through @samp{99}). This has the same format and value
13222 as @samp{%y}, except that if the @acronym{ISO} week number (see
13224 to the previous or next year, that year is used instead.
13225 This is a @acronym{GNU} extension.
13227 year corresponding to the @acronym{ISO} week number. This has the
13228 same format and value as @samp{%Y}, except that if the @acronym{ISO}
13230 @samp{%V}) belongs to the previous or next year, that year is used
13232 It is normally useful only if @samp{%V} is also used;
13233 for example, the format @samp{%G-%m-%d} is probably a mistake,
13234 since it combines the ISO week number year with the conventional month and day.
13235 This is a @acronym{GNU} extension.
13239 day of year (@samp{001}@dots{}@samp{366})
13241 month (@samp{01}@dots{}@samp{12})
13243 day of week (@samp{1}@dots{}@samp{7}) with @samp{1} corresponding to Monday
13245 week number of year, with Sunday as the first day of the week
13246 (@samp{00}@dots{}@samp{53}).
13247 Days in a new year preceding the first Sunday are in week zero.
13249 @acronym{ISO} week number, that is, the
13250 week number of year, with Monday as the first day of the week
13251 (@samp{01}@dots{}@samp{53}).
13252 If the week containing January 1 has four or more days in
13253 the new year, then it is considered week 1; otherwise, it is week 53 of
13254 the previous year, and the next week is week 1. (See the @acronym{ISO} 8601
13257 day of week (@samp{0}@dots{}@samp{6}) with 0 corresponding to Sunday
13259 week number of year, with Monday as first day of week
13260 (@samp{00}@dots{}@samp{53}).
13261 Days in a new year preceding the first Monday are in week zero.
13263 locale's date representation (e.g., @samp{12/31/99})
13265 last two digits of year (@samp{00}@dots{}@samp{99})
13267 year. This is normally at least four characters, but it may be more.
13268 Year @samp{0000} precedes year @samp{0001}, and year @samp{-001}
13269 precedes year @samp{0000}.
13273 @node Literal conversion specifiers
13274 @subsection Literal conversion specifiers
13276 @cindex literal conversion specifiers
13277 @cindex conversion specifiers, literal
13279 @command{date} conversion specifiers that produce literal strings.
13291 @node Padding and other flags
13292 @subsection Padding and other flags
13294 @cindex numeric field padding
13295 @cindex padding of numeric fields
13296 @cindex fields, padding numeric
13298 Unless otherwise specified, @command{date} normally pads numeric fields
13299 with zeros, so that, for
13300 example, numeric months are always output as two digits.
13301 Seconds since the epoch are not padded, though,
13302 since there is no natural width for them.
13304 As a @acronym{GNU} extension, @command{date} recognizes any of the
13305 following optional flags after the @samp{%}:
13309 (hyphen) Do not pad the field; useful if the output is intended for
13312 (underscore) Pad with spaces; useful if you need a fixed
13313 number of characters in the output, but zeros are too distracting.
13315 (zero) Pad with zeros even if the conversion specifier
13316 would normally pad with spaces.
13318 Use upper case characters if possible.
13320 Use opposite case characters if possible.
13321 A field that is normally upper case becomes lower case, and vice versa.
13325 Here are some examples of padding:
13328 date +%d/%m -d "Feb 1"
13330 date +%-d/%-m -d "Feb 1"
13332 date +%_d/%_m -d "Feb 1"
13336 As a @acronym{GNU} extension, you can specify the field width
13337 (after any flag, if present) as a decimal number. If the natural size of the
13338 output of the field has less than the specified number of characters,
13339 the result is written right adjusted and padded to the given
13340 size. For example, @samp{%9B} prints the right adjusted month name in
13341 a field of width 9.
13343 An optional modifier can follow the optional flag and width
13344 specification. The modifiers are:
13348 Use the locale's alternate representation for date and time. This
13349 modifier applies to the @samp{%c}, @samp{%C}, @samp{%x}, @samp{%X},
13350 @samp{%y} and @samp{%Y} conversion specifiers. In a Japanese locale, for
13351 example, @samp{%Ex} might yield a date format based on the Japanese
13355 Use the locale's alternate numeric symbols for numbers. This modifier
13356 applies only to numeric conversion specifiers.
13359 If the format supports the modifier but no alternate representation
13360 is available, it is ignored.
13363 @node Setting the time
13364 @subsection Setting the time
13366 @cindex setting the time
13367 @cindex time setting
13368 @cindex appropriate privileges
13370 If given an argument that does not start with @samp{+}, @command{date} sets
13371 the system clock to the date and time specified by that argument (as
13372 described below). You must have appropriate privileges to set the
13373 system clock. The @option{--date} and @option{--set} options may not be
13374 used with such an argument. The @option{--universal} option may be used
13375 with such an argument to indicate that the specified date and time are
13376 relative to Coordinated Universal Time rather than to the local time
13379 The argument must consist entirely of digits, which have the following
13392 first two digits of year (optional)
13394 last two digits of year (optional)
13399 The @option{--set} option also sets the system clock; see the next section.
13402 @node Options for date
13403 @subsection Options for @command{date}
13405 @cindex @command{date} options
13406 @cindex options for @command{date}
13408 The program accepts the following options. Also see @ref{Common options}.
13412 @item -d @var{datestr}
13413 @itemx --date=@var{datestr}
13416 @cindex parsing date strings
13417 @cindex date strings, parsing
13418 @cindex arbitrary date strings, parsing
13421 @opindex next @var{day}
13422 @opindex last @var{day}
13423 Display the date and time specified in @var{datestr} instead of the
13424 current date and time. @var{datestr} can be in almost any common
13425 format. It can contain month names, time zones, @samp{am} and @samp{pm},
13426 @samp{yesterday}, etc. For example, @option{--date="2004-02-27
13427 14:19:13.489392193 +0530"} specifies the instant of time that is
13428 489,392,193 nanoseconds after February 27, 2004 at 2:19:13 PM in a
13429 time zone that is 5 hours and 30 minutes east of @acronym{UTC}.@*
13430 @xref{Date input formats}.
13432 @item -f @var{datefile}
13433 @itemx --file=@var{datefile}
13436 Parse each line in @var{datefile} as with @option{-d} and display the
13437 resulting date and time. If @var{datefile} is @samp{-}, use standard
13438 input. This is useful when you have many dates to process, because the
13439 system overhead of starting up the @command{date} executable many times can
13442 @item -r @var{file}
13443 @itemx --reference=@var{file}
13445 @opindex --reference
13446 Display the date and time of the last modification of @var{file},
13447 instead of the current date and time.
13454 @opindex --rfc-2822
13455 Display the date and time using the format @samp{%a, %d %b %Y %H:%M:%S
13456 %z}, evaluated in the C locale so abbreviations are always in English.
13460 Fri, 09 Sep 2005 13:51:39 -0700
13463 This format conforms to
13464 @uref{ftp://ftp.rfc-editor.org/in-notes/rfc2822.txt, Internet
13465 @acronym{RFCs} 2822} and
13466 @uref{ftp://ftp.rfc-editor.org/in-notes/rfc822.txt, 822}, the
13467 current and previous standards for Internet email.
13469 @item --rfc-3339=@var{timespec}
13470 @opindex --rfc-3339=@var{timespec}
13471 Display the date using a format specified by
13472 @uref{ftp://ftp.rfc-editor.org/in-notes/rfc3339.txt, Internet
13473 @acronym{RFC} 3339}. This is a subset of the @acronym{ISO} 8601
13474 format, except that it also permits applications to use a space rather
13475 than a @samp{T} to separate dates from times. Unlike the other
13476 standard formats, @acronym{RFC} 3339 format is always suitable as
13477 input for the @option{--date} (@option{-d}) and @option{--file}
13478 (@option{-f}) options, regardless of the current locale.
13480 The argument @var{timespec} specifies how much of the time to include.
13481 It can be one of the following:
13485 Print just the full-date, e.g., @samp{2005-09-14}.
13486 This is equivalent to the format @samp{%Y-%m-%d}.
13489 Print the full-date and full-time separated by a space, e.g.,
13490 @samp{2005-09-14 00:56:06+05:30}. The output ends with a numeric
13491 time-offset; here the @samp{+05:30} means that local time is five
13492 hours and thirty minutes east of @acronym{UTC}. This is equivalent to
13493 the format @samp{%Y-%m-%d %H:%M:%S%:z}.
13496 Like @samp{seconds}, but also print nanoseconds, e.g.,
13497 @samp{2005-09-14 00:56:06.998458565+05:30}.
13498 This is equivalent to the format @samp{%Y-%m-%d %H:%M:%S.%N%:z}.
13502 @item -s @var{datestr}
13503 @itemx --set=@var{datestr}
13506 Set the date and time to @var{datestr}. See @option{-d} above.
13513 @opindex --universal
13514 @cindex Coordinated Universal Time
13516 @cindex Greenwich Mean Time
13519 Use Coordinated Universal Time (@acronym{UTC}) by operating as if the
13520 @env{TZ} environment variable were set to the string @samp{UTC0}.
13522 Universal Time is often called ``Greenwich Mean Time'' (@sc{gmt}) for
13523 historical reasons.
13527 @node Examples of date
13528 @subsection Examples of @command{date}
13530 @cindex examples of @command{date}
13532 Here are a few examples. Also see the documentation for the @option{-d}
13533 option in the previous section.
13538 To print the date of the day before yesterday:
13541 date --date='2 days ago'
13545 To print the date of the day three months and one day hence:
13548 date --date='3 months 1 day'
13552 To print the day of year of Christmas in the current year:
13555 date --date='25 Dec' +%j
13559 To print the current full month name and the day of the month:
13565 But this may not be what you want because for the first nine days of
13566 the month, the @samp{%d} expands to a zero-padded two-digit field,
13567 for example @samp{date -d 1may '+%B %d'} will print @samp{May 01}.
13570 To print a date without the leading zero for one-digit days
13571 of the month, you can use the (@acronym{GNU} extension)
13572 @samp{-} flag to suppress
13573 the padding altogether:
13576 date -d 1may '+%B %-d
13580 To print the current date and time in the format required by many
13581 non-@acronym{GNU} versions of @command{date} when setting the system clock:
13584 date +%m%d%H%M%Y.%S
13588 To set the system clock forward by two minutes:
13591 date --set='+2 minutes'
13595 To print the date in @acronym{RFC} 2822 format,
13596 use @samp{date --rfc-2822}. Here is some example output:
13599 Fri, 09 Sep 2005 13:51:39 -0700
13602 @anchor{%s-examples}
13604 To convert a date string to the number of seconds since the epoch
13605 (which is 1970-01-01 00:00:00 UTC), use the @option{--date} option with
13606 the @samp{%s} format. That can be useful in sorting and/or graphing
13607 and/or comparing data by date. The following command outputs the
13608 number of the seconds since the epoch for the time two minutes after the
13612 date --date='1970-01-01 00:02:00 +0000' +%s
13616 If you do not specify time zone information in the date string,
13617 @command{date} uses your computer's idea of the time zone when
13618 interpreting the string. For example, if your computer's time zone is
13619 that of Cambridge, Massachusetts, which was then 5 hours (i.e., 18,000
13620 seconds) behind UTC:
13623 # local time zone used
13624 date --date='1970-01-01 00:02:00' +%s
13629 If you're sorting or graphing dated data, your raw date values may be
13630 represented as seconds since the epoch. But few people can look at
13631 the date @samp{946684800} and casually note ``Oh, that's the first second
13632 of the year 2000 in Greenwich, England.''
13635 date --date='2000-01-01 UTC' +%s
13639 An alternative is to use the @option{--utc} (@option{-u}) option.
13640 Then you may omit @samp{UTC} from the date string. Although this
13641 produces the same result for @samp{%s} and many other format sequences,
13642 with a time zone offset different from zero, it would give a different
13643 result for zone-dependent formats like @samp{%z}.
13646 date -u --date=2000-01-01 +%s
13650 To convert such an unwieldy number of seconds back to
13651 a more readable form, use a command like this:
13654 # local time zone used
13655 date -d '1970-01-01 UTC 946684800 seconds' +"%Y-%m-%d %T %z"
13656 1999-12-31 19:00:00 -0500
13659 Or if you do not mind depending on the @samp{@@} feature present since
13660 coreutils 5.3.0, you could shorten this to:
13663 date -d @@946684800 +"%F %T %z"
13664 1999-12-31 19:00:00 -0500
13667 Often it is better to output UTC-relative date and time:
13670 date -u -d '1970-01-01 946684800 seconds' +"%Y-%m-%d %T %z"
13671 2000-01-01 00:00:00 +0000
13677 @node arch invocation
13678 @section @command{arch}: Print machine hardware name
13681 @cindex print machine hardware name
13682 @cindex system information, printing
13684 @command{arch} prints the machine hardware name,
13685 and is equivalent to @samp{uname -m}.
13689 arch [@var{option}]
13692 The program accepts the @ref{Common options} only.
13697 @node uname invocation
13698 @section @command{uname}: Print system information
13701 @cindex print system information
13702 @cindex system information, printing
13704 @command{uname} prints information about the machine and operating system
13705 it is run on. If no options are given, @command{uname} acts as if the
13706 @option{-s} option were given. Synopsis:
13709 uname [@var{option}]@dots{}
13712 If multiple options or @option{-a} are given, the selected information is
13713 printed in this order:
13716 @var{kernel-name} @var{nodename} @var{kernel-release} @var{kernel-version}
13717 @var{machine} @var{processor} @var{hardware-platform} @var{operating-system}
13720 The information may contain internal spaces, so such output cannot be
13721 parsed reliably. In the following example, @var{release} is
13722 @samp{2.2.18ss.e820-bda652a #4 SMP Tue Jun 5 11:24:08 PDT 2001}:
13726 @result{} Linux dum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 i686 unknown unknown GNU/Linux
13730 The program accepts the following options. Also see @ref{Common options}.
13738 Print all of the below information, except omit the processor type
13739 and the hardware platform name if they are unknown.
13742 @itemx --hardware-platform
13744 @opindex --hardware-platform
13745 @cindex implementation, hardware
13746 @cindex hardware platform
13747 @cindex platform, hardware
13748 Print the hardware platform name
13749 (sometimes called the hardware implementation).
13750 Print @samp{unknown} if the kernel does not make this information
13751 easily available, as is the case with Linux kernels.
13757 @cindex machine type
13758 @cindex hardware class
13759 @cindex hardware type
13760 Print the machine hardware name (sometimes called the hardware class
13766 @opindex --nodename
13769 @cindex network node name
13770 Print the network node hostname.
13775 @opindex --processor
13776 @cindex host processor type
13777 Print the processor type (sometimes called the instruction set
13778 architecture or ISA).
13779 Print @samp{unknown} if the kernel does not make this information
13780 easily available, as is the case with Linux kernels.
13783 @itemx --operating-system
13785 @opindex --operating-system
13786 @cindex operating system name
13787 Print the name of the operating system.
13790 @itemx --kernel-release
13792 @opindex --kernel-release
13793 @cindex kernel release
13794 @cindex release of kernel
13795 Print the kernel release.
13798 @itemx --kernel-name
13800 @opindex --kernel-name
13801 @cindex kernel name
13802 @cindex name of kernel
13803 Print the kernel name.
13804 @acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) calls this
13805 ``the implementation of the operating system'', because the
13806 @acronym{POSIX} specification itself has no notion of ``kernel''.
13807 The kernel name might be the same as the operating system name printed
13808 by the @option{-o} or @option{--operating-system} option, but it might
13809 differ. Some operating systems (e.g., FreeBSD, HP-UX) have the same
13810 name as their underlying kernels; others (e.g., GNU/Linux, Solaris)
13814 @itemx --kernel-version
13816 @opindex --kernel-version
13817 @cindex kernel version
13818 @cindex version of kernel
13819 Print the kernel version.
13826 @node hostname invocation
13827 @section @command{hostname}: Print or set system name
13830 @cindex setting the hostname
13831 @cindex printing the hostname
13832 @cindex system name, printing
13833 @cindex appropriate privileges
13835 With no arguments, @command{hostname} prints the name of the current host
13836 system. With one argument, it sets the current host name to the
13837 specified string. You must have appropriate privileges to set the host
13841 hostname [@var{name}]
13844 The only options are @option{--help} and @option{--version}. @xref{Common
13850 @node hostid invocation
13851 @section @command{hostid}: Print numeric host identifier.
13854 @cindex printing the host identifier
13856 @command{hostid} prints the numeric identifier of the current host
13857 in hexadecimal. This command accepts no arguments.
13858 The only options are @option{--help} and @option{--version}.
13859 @xref{Common options}.
13861 For example, here's what it prints on one system I use:
13868 On that system, the 32-bit quantity happens to be closely
13869 related to the system's Internet address, but that isn't always
13874 @node uptime invocation
13875 @section @command{uptime}: Print system uptime and load
13878 @cindex printing the system uptime and load
13880 @command{uptime} prints the current time, the system's uptime, the
13881 number of logged-in users and the current load average.
13883 If an argument is specified, it is used as the file to be read
13884 to discover how many users are logged in. If no argument is
13885 specified, a system default is used (@command{uptime --help} indicates
13886 the default setting).
13888 The only options are @option{--help} and @option{--version}.
13889 @xref{Common options}.
13891 For example, here's what it prints right now on one system I use:
13895 14:07 up 3:35, 3 users, load average: 1.39, 1.15, 1.04
13898 The precise method of calculation of load average varies somewhat
13899 between systems. Some systems calculate it as the average number of
13900 runnable processes over the last 1, 5 and 15 minutes, but some systems
13901 also include processes in the uninterruptible sleep state (that is,
13902 those processes which are waiting for disk I/O). The Linux kernel
13903 includes uninterruptible processes.
13905 @node Modified command invocation
13906 @chapter Modified command invocation
13908 @cindex modified command invocation
13909 @cindex invocation of commands, modified
13910 @cindex commands for invoking other commands
13912 This section describes commands that run other commands in some context
13913 different than the current one: a modified environment, as a different
13917 * chroot invocation:: Modify the root directory.
13918 * env invocation:: Modify environment variables.
13919 * nice invocation:: Modify niceness.
13920 * nohup invocation:: Immunize to hangups.
13921 * su invocation:: Modify user and group ID.
13922 * timeout invocation:: Run with time limit.
13926 @node chroot invocation
13927 @section @command{chroot}: Run a command with a different root directory
13930 @cindex running a program in a specified root directory
13931 @cindex root directory, running a program in a specified
13933 @command{chroot} runs a command with a specified root directory.
13934 On many systems, only the super-user can do this.@footnote{However,
13935 some systems (e.g., FreeBSD) can be configured to allow certain regular
13936 users to use the @code{chroot} system call, and hence to run this program.
13937 Also, on Cygwin, anyone can run the @command{chroot} command, because the
13938 underlying function is non-privileged due to lack of support in MS-Windows.}
13942 chroot @var{newroot} [@var{command} [@var{args}]@dots{}]
13943 chroot @var{option}
13946 Ordinarily, file names are looked up starting at the root of the
13947 directory structure, i.e., @file{/}. @command{chroot} changes the root to
13948 the directory @var{newroot} (which must exist) and then runs
13949 @var{command} with optional @var{args}. If @var{command} is not
13950 specified, the default is the value of the @env{SHELL} environment
13951 variable or @command{/bin/sh} if not set, invoked with the @option{-i} option.
13952 @var{command} must not be a special built-in utility
13953 (@pxref{Special built-in utilities}).
13955 The only options are @option{--help} and @option{--version}. @xref{Common
13956 options}. Options must precede operands.
13958 Here are a few tips to help avoid common problems in using chroot.
13959 To start with a simple example, make @var{command} refer to a statically
13960 linked binary. If you were to use a dynamically linked executable, then
13961 you'd have to arrange to have the shared libraries in the right place under
13962 your new root directory.
13964 For example, if you create a statically linked @command{ls} executable,
13965 and put it in @file{/tmp/empty}, you can run this command as root:
13968 $ chroot /tmp/empty /ls -Rl /
13971 Then you'll see output like this:
13976 -rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls
13979 If you want to use a dynamically linked executable, say @command{bash},
13980 then first run @samp{ldd bash} to see what shared objects it needs.
13981 Then, in addition to copying the actual binary, also copy the listed
13982 files to the required positions under your intended new root directory.
13983 Finally, if the executable requires any other files (e.g., data, state,
13984 device files), copy them into place, too.
13986 @cindex exit status of @command{chroot}
13990 1 if @command{chroot} itself fails
13991 126 if @var{command} is found but cannot be invoked
13992 127 if @var{command} cannot be found
13993 the exit status of @var{command} otherwise
13997 @node env invocation
13998 @section @command{env}: Run a command in a modified environment
14001 @cindex environment, running a program in a modified
14002 @cindex modified environment, running a program in a
14003 @cindex running a program in a modified environment
14005 @command{env} runs a command with a modified environment. Synopses:
14008 env [@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c
14009 [@var{command} [@var{args}]@dots{}]
14013 Operands of the form @samp{@var{variable}=@var{value}} set
14014 the environment variable @var{variable} to value @var{value}.
14015 @var{value} may be empty (@samp{@var{variable}=}). Setting a variable
14016 to an empty value is different from unsetting it.
14017 These operands are evaluated left-to-right, so if two operands
14018 mention the same variable the earlier is ignored.
14020 Environment variable names can be empty, and can contain any
14021 characters other than @samp{=} and the null character (@acronym{ASCII}
14022 @sc{nul}). However, it is wise to limit yourself to names that
14023 consist solely of underscores, digits, and @acronym{ASCII} letters,
14024 and that begin with a non-digit, as applications like the shell do not
14025 work well with other names.
14028 The first operand that does not contain the character @samp{=}
14029 specifies the program to invoke; it is
14030 searched for according to the @env{PATH} environment variable. Any
14031 remaining arguments are passed as arguments to that program.
14032 The program should not be a special built-in utility
14033 (@pxref{Special built-in utilities}).
14035 @cindex environment, printing
14037 If no command name is specified following the environment
14038 specifications, the resulting environment is printed. This is like
14039 specifying the @command{printenv} program.
14041 The program accepts the following options. Also see @ref{Common options}.
14042 Options must precede operands.
14046 @item -u @var{name}
14047 @itemx --unset=@var{name}
14050 Remove variable @var{name} from the environment, if it was in the
14055 @itemx --ignore-environment
14058 @opindex --ignore-environment
14059 Start with an empty environment, ignoring the inherited environment.
14063 @cindex exit status of @command{env}
14067 0 if no @var{command} is specified and the environment is output
14068 1 if @command{env} itself fails
14069 126 if @var{command} is found but cannot be invoked
14070 127 if @var{command} cannot be found
14071 the exit status of @var{command} otherwise
14075 @node nice invocation
14076 @section @command{nice}: Run a command with modified niceness
14080 @cindex scheduling, affecting
14081 @cindex appropriate privileges
14083 @command{nice} prints or modifies a process's @dfn{niceness},
14084 a parameter that affects whether the process is scheduled favorably.
14088 nice [@var{option}]@dots{} [@var{command} [@var{arg}]@dots{}]
14091 If no arguments are given, @command{nice} prints the current niceness.
14092 Otherwise, @command{nice} runs the given @var{command} with its
14093 niceness adjusted. By default, its niceness is incremented by 10.
14095 Niceness values range at least from @minus{}20 (process has high priority
14096 and gets more resources, thus slowing down other processes) through 19
14097 (process has lower priority and runs slowly itself, but has less impact
14098 on the speed of other running processes). Some systems
14099 may have a wider range of nicenesses; conversely, other systems may
14100 enforce more restrictive limits. An attempt to set the niceness
14101 outside the supported range is treated as an attempt to use the
14102 minimum or maximum supported value.
14104 A niceness should not be confused with a scheduling priority, which
14105 lets applications determine the order in which threads are scheduled
14106 to run. Unlike a priority, a niceness is merely advice to the
14107 scheduler, which the scheduler is free to ignore. Also, as a point of
14108 terminology, @acronym{POSIX} defines the behavior of @command{nice} in
14109 terms of a @dfn{nice value}, which is the nonnegative difference
14110 between a niceness and the minimum niceness. Though @command{nice}
14111 conforms to @acronym{POSIX}, its documentation and diagnostics use the
14112 term ``niceness'' for compatibility with historical practice.
14114 @var{command} must not be a special built-in utility (@pxref{Special
14115 built-in utilities}).
14117 @mayConflictWithShellBuiltIn{nice}
14119 The program accepts the following option. Also see @ref{Common options}.
14120 Options must precede operands.
14123 @item -n @var{adjustment}
14124 @itemx --adjustment=@var{adjustment}
14126 @opindex --adjustment
14127 Add @var{adjustment} instead of 10 to the command's niceness. If
14128 @var{adjustment} is negative and you lack appropriate privileges,
14129 @command{nice} issues a warning but otherwise acts as if you specified
14132 For compatibility @command{nice} also supports an obsolete
14133 option syntax @option{-@var{adjustment}}. New scripts should use
14134 @option{-n @var{adjustment}} instead.
14138 @cindex exit status of @command{nice}
14142 0 if no @var{command} is specified and the niceness is output
14143 1 if @command{nice} itself fails
14144 126 if @var{command} is found but cannot be invoked
14145 127 if @var{command} cannot be found
14146 the exit status of @var{command} otherwise
14149 It is sometimes useful to run a non-interactive program with reduced niceness.
14152 $ nice factor 4611686018427387903
14155 Since @command{nice} prints the current niceness,
14156 you can invoke it through itself to demonstrate how it works.
14158 The default behavior is to increase the niceness by @samp{10}:
14169 The @var{adjustment} is relative to the current niceness. In the
14170 next example, the first @command{nice} invocation runs the second one
14171 with niceness 10, and it in turn runs the final one with a niceness
14175 $ nice nice -n 3 nice
14179 Specifying a niceness larger than the supported range
14180 is the same as specifying the maximum supported value:
14183 $ nice -n 10000000000 nice
14187 Only a privileged user may run a process with lower niceness:
14191 nice: cannot set niceness: Permission denied
14193 $ sudo nice -n -1 nice
14198 @node nohup invocation
14199 @section @command{nohup}: Run a command immune to hangups
14202 @cindex hangups, immunity to
14203 @cindex immunity to hangups
14204 @cindex logging out and continuing to run
14207 @command{nohup} runs the given @var{command} with hangup signals ignored,
14208 so that the command can continue running in the background after you log
14212 nohup @var{command} [@var{arg}]@dots{}
14215 If standard input is a terminal, it is redirected from
14216 @file{/dev/null} so that terminal sessions do not mistakenly consider
14217 the terminal to be used by the command. This is a @acronym{GNU}
14218 extension; programs intended to be portable to non-@acronym{GNU} hosts
14219 should use @samp{nohup @var{command} [@var{arg}]@dots{} </dev/null}
14223 If standard output is a terminal, the command's standard output is appended
14224 to the file @file{nohup.out}; if that cannot be written to, it is appended
14225 to the file @file{$HOME/nohup.out}; and if that cannot be written to, the
14226 command is not run.
14227 Any @file{nohup.out} or @file{$HOME/nohup.out} file created by
14228 @command{nohup} is made readable and writable only to the user,
14229 regardless of the current umask settings.
14231 If standard error is a terminal, it is normally redirected to the same file
14232 descriptor as the (possibly-redirected) standard output.
14233 However, if standard output is closed, standard error terminal output
14234 is instead appended to the file @file{nohup.out} or
14235 @file{$HOME/nohup.out} as above.
14237 To capture the command's output to a file other than @file{nohup.out}
14238 you can redirect it. For example, to capture the output of
14242 nohup make > make.log
14245 @command{nohup} does not automatically put the command it runs in the
14246 background; you must do that explicitly, by ending the command line
14247 with an @samp{&}. Also, @command{nohup} does not alter the
14248 niceness of @var{command}; use @command{nice} for that,
14249 e.g., @samp{nohup nice @var{command}}.
14251 @var{command} must not be a special built-in utility (@pxref{Special
14252 built-in utilities}).
14254 The only options are @option{--help} and @option{--version}. @xref{Common
14255 options}. Options must precede operands.
14257 @cindex exit status of @command{nohup}
14261 126 if @var{command} is found but cannot be invoked
14262 127 if @command{nohup} itself fails or if @var{command} cannot be found
14263 the exit status of @var{command} otherwise
14267 @node su invocation
14268 @section @command{su}: Run a command with substitute user and group ID
14271 @cindex substitute user and group IDs
14272 @cindex user ID, switching
14273 @cindex super-user, becoming
14274 @cindex root, becoming
14276 @command{su} allows one user to temporarily become another user. It runs a
14277 command (often an interactive shell) with the real and effective user
14278 ID, group ID, and supplemental groups of a given @var{user}. Synopsis:
14281 su [@var{option}]@dots{} [@var{user} [@var{arg}]@dots{}]
14284 @cindex passwd entry, and @command{su} shell
14286 @flindex /etc/passwd
14287 If no @var{user} is given, the default is @code{root}, the super-user.
14288 The shell to use is taken from @var{user}'s @code{passwd} entry, or
14289 @file{/bin/sh} if none is specified there. If @var{user} has a
14290 password, @command{su} prompts for the password unless run by a user with
14291 effective user ID of zero (the super-user).
14297 @cindex login shell
14298 By default, @command{su} does not change the current directory.
14299 It sets the environment variables @env{HOME} and @env{SHELL}
14300 from the password entry for @var{user}, and if @var{user} is not
14301 the super-user, sets @env{USER} and @env{LOGNAME} to @var{user}.
14302 By default, the shell is not a login shell.
14304 Any additional @var{arg}s are passed as additional arguments to the
14307 @cindex @option{-su}
14308 GNU @command{su} does not treat @file{/bin/sh} or any other shells specially
14309 (e.g., by setting @code{argv[0]} to @option{-su}, passing @option{-c} only
14310 to certain shells, etc.).
14313 @command{su} can optionally be compiled to use @code{syslog} to report
14314 failed, and optionally successful, @command{su} attempts. (If the system
14315 supports @code{syslog}.) However, GNU @command{su} does not check if the
14316 user is a member of the @code{wheel} group; see below.
14318 The program accepts the following options. Also see @ref{Common options}.
14321 @item -c @var{command}
14322 @itemx --command=@var{command}
14325 Pass @var{command}, a single command line to run, to the shell with
14326 a @option{-c} option instead of starting an interactive shell.
14333 @cindex file name pattern expansion, disabled
14334 @cindex globbing, disabled
14335 Pass the @option{-f} option to the shell. This probably only makes sense
14336 if the shell run is @command{csh} or @command{tcsh}, for which the @option{-f}
14337 option prevents reading the startup file (@file{.cshrc}). With
14338 Bourne-like shells, the @option{-f} option disables file name pattern
14339 expansion (globbing), which is not likely to be useful.
14347 @c other variables already indexed above
14350 @cindex login shell, creating
14351 Make the shell a login shell. This means the following. Unset all
14352 environment variables except @env{TERM}, @env{HOME}, and @env{SHELL}
14353 (which are set as described above), and @env{USER} and @env{LOGNAME}
14354 (which are set, even for the super-user, as described above), and set
14355 @env{PATH} to a compiled-in default value. Change to @var{user}'s home
14356 directory. Prepend @samp{-} to the shell's name, intended to make it
14357 read its login startup file(s).
14361 @itemx --preserve-environment
14364 @opindex --preserve-environment
14365 @cindex environment, preserving
14366 @flindex /etc/shells
14367 @cindex restricted shell
14368 Do not change the environment variables @env{HOME}, @env{USER},
14369 @env{LOGNAME}, or @env{SHELL}. Run the shell given in the environment
14370 variable @env{SHELL} instead of the shell from @var{user}'s passwd
14371 entry, unless the user running @command{su} is not the super-user and
14372 @var{user}'s shell is restricted. A @dfn{restricted shell} is one that
14373 is not listed in the file @file{/etc/shells}, or in a compiled-in list
14374 if that file does not exist. Parts of what this option does can be
14375 overridden by @option{--login} and @option{--shell}.
14377 @item -s @var{shell}
14378 @itemx --shell=@var{shell}
14381 Run @var{shell} instead of the shell from @var{user}'s passwd entry,
14382 unless the user running @command{su} is not the super-user and @var{user}'s
14383 shell is restricted (see @option{-m} just above).
14387 @cindex exit status of @command{su}
14391 1 if @command{su} itself fails
14392 126 if subshell is found but cannot be invoked
14393 127 if subshell cannot be found
14394 the exit status of the subshell otherwise
14397 @cindex wheel group, not supported
14398 @cindex group wheel, not supported
14400 @subsection Why GNU @command{su} does not support the @samp{wheel} group
14402 (This section is by Richard Stallman.)
14406 Sometimes a few of the users try to hold total power over all the
14407 rest. For example, in 1984, a few users at the MIT AI lab decided to
14408 seize power by changing the operator password on the Twenex system and
14409 keeping it secret from everyone else. (I was able to thwart this coup
14410 and give power back to the users by patching the kernel, but I
14411 wouldn't know how to do that in Unix.)
14413 However, occasionally the rulers do tell someone. Under the usual
14414 @command{su} mechanism, once someone learns the root password who
14415 sympathizes with the ordinary users, he or she can tell the rest. The
14416 ``wheel group'' feature would make this impossible, and thus cement the
14417 power of the rulers.
14419 I'm on the side of the masses, not that of the rulers. If you are
14420 used to supporting the bosses and sysadmins in whatever they do, you
14421 might find this idea strange at first.
14424 @node timeout invocation
14425 @section @command{timeout}: Run a command with a time limit
14429 @cindex run commands with bounded time
14431 @command{timeout} runs the given @var{command} and kills it if it is
14432 still running after the specified time interval. Synopsis:
14435 timeout [@var{option}] @var{number}[smhd] @var{command} [@var{arg}]@dots{}
14439 @var{number} is an integer followed by an optional unit; the default
14440 is seconds. The units are:
14453 @var{command} must not be a special built-in utility (@pxref{Special
14454 built-in utilities}).
14456 The program accepts the following option. Also see @ref{Common options}.
14457 Options must precede operands.
14460 @item -s @var{signal}
14461 @itemx --signal=@var{signal}
14464 Send this @var{signal} to @var{command} on timeout, rather than the
14465 default @samp{TERM} signal. @var{signal} may be a name like @samp{HUP}
14466 or a number. Also see @xref{Signal specifications}.
14470 @cindex exit status of @command{timeout}
14474 124 if @var{command} times out
14475 125 if @command{timeout} itself fails
14476 126 if @var{command} is found but cannot be invoked
14477 127 if @var{command} cannot be found
14478 the exit status of @var{command} otherwise
14482 @node Process control
14483 @chapter Process control
14485 @cindex processes, commands for controlling
14486 @cindex commands for controlling processes
14489 * kill invocation:: Sending a signal to processes.
14493 @node kill invocation
14494 @section @command{kill}: Send a signal to processes
14497 @cindex send a signal to processes
14499 The @command{kill} command sends a signal to processes, causing them
14500 to terminate or otherwise act upon receiving the signal in some way.
14501 Alternatively, it lists information about signals. Synopses:
14504 kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{}
14505 kill [-l | --list | -t | --table] [@var{signal}]@dots{}
14508 @mayConflictWithShellBuiltIn{kill}
14510 The first form of the @command{kill} command sends a signal to all
14511 @var{pid} arguments. The default signal to send if none is specified
14512 is @samp{TERM}. The special signal number @samp{0} does not denote a
14513 valid signal, but can be used to test whether the @var{pid} arguments
14514 specify processes to which a signal could be sent.
14516 If @var{pid} is positive, the signal is sent to the process with the
14517 process ID @var{pid}. If @var{pid} is zero, the signal is sent to all
14518 processes in the process group of the current process. If @var{pid}
14519 is @minus{}1, the signal is sent to all processes for which the user has
14520 permission to send a signal. If @var{pid} is less than @minus{}1, the signal
14521 is sent to all processes in the process group that equals the absolute
14522 value of @var{pid}.
14524 If @var{pid} is not positive, a system-dependent set of system
14525 processes is excluded from the list of processes to which the signal
14528 If a negative @var{PID} argument is desired as the first one, it
14529 should be preceded by @option{--}. However, as a common extension to
14530 @acronym{POSIX}, @option{--} is not required with @samp{kill
14531 -@var{signal} -@var{pid}}. The following commands are equivalent:
14540 The first form of the @command{kill} command succeeds if every @var{pid}
14541 argument specifies at least one process that the signal was sent to.
14543 The second form of the @command{kill} command lists signal information.
14544 Either the @option{-l} or @option{--list} option, or the @option{-t}
14545 or @option{--table} option must be specified. Without any
14546 @var{signal} argument, all supported signals are listed. The output
14547 of @option{-l} or @option{--list} is a list of the signal names, one
14548 per line; if @var{signal} is already a name, the signal number is
14549 printed instead. The output of @option{-t} or @option{--table} is a
14550 table of signal numbers, names, and descriptions. This form of the
14551 @command{kill} command succeeds if all @var{signal} arguments are valid
14552 and if there is no output error.
14554 The @command{kill} command also supports the @option{--help} and
14555 @option{--version} options. @xref{Common options}.
14557 A @var{signal} may be a signal name like @samp{HUP}, or a signal
14558 number like @samp{1}, or an exit status of a process terminated by the
14559 signal. A signal name can be given in canonical form or prefixed by
14560 @samp{SIG}. The case of the letters is ignored, except for the
14561 @option{-@var{signal}} option which must use upper case to avoid
14562 ambiguity with lower case option letters. For a list of supported
14563 signal names and numbers see @xref{Signal specifications}.
14568 @cindex delaying commands
14569 @cindex commands for delaying
14571 @c Perhaps @command{wait} or other commands should be described here also?
14574 * sleep invocation:: Delay for a specified time.
14578 @node sleep invocation
14579 @section @command{sleep}: Delay for a specified time
14582 @cindex delay for a specified time
14584 @command{sleep} pauses for an amount of time specified by the sum of
14585 the values of the command line arguments.
14589 sleep @var{number}[smhd]@dots{}
14593 Each argument is a number followed by an optional unit; the default
14594 is seconds. The units are:
14607 Historical implementations of @command{sleep} have required that
14608 @var{number} be an integer, and only accepted a single argument
14609 without a suffix. However, GNU @command{sleep} accepts
14610 arbitrary floating point numbers (using a period before any fractional
14613 The only options are @option{--help} and @option{--version}. @xref{Common
14616 @c sleep is a shell built-in at least with Solaris 11's /bin/sh
14617 @mayConflictWithShellBuiltIn{sleep}
14622 @node Numeric operations
14623 @chapter Numeric operations
14625 @cindex numeric operations
14626 These programs do numerically-related operations.
14629 * factor invocation:: Show factors of numbers.
14630 * seq invocation:: Print sequences of numbers.
14634 @node factor invocation
14635 @section @command{factor}: Print prime factors
14638 @cindex prime factors
14640 @command{factor} prints prime factors. Synopses:
14643 factor [@var{number}]@dots{}
14644 factor @var{option}
14647 If no @var{number} is specified on the command line, @command{factor} reads
14648 numbers from standard input, delimited by newlines, tabs, or spaces.
14650 The @command{factor} command supports only a small number of options:
14654 Print a short help on standard output, then exit without further
14658 Always use unlimited precision arithmetic via the GNU MP library.
14659 By default, @command{factor} selects between using GNU MP and using
14660 native operations on the basis of the length of the number to be factored.
14663 Always use limited-precision native operations, not GNU MP.
14664 This causes @command{factor} to fail for larger inputs.
14667 Print the program version on standard output, then exit without further
14671 Factoring the product of the eighth and ninth Mersenne primes
14672 takes about 30 milliseconds of CPU time on a 2.2 GHz Athlon.
14675 M8=`echo 2^31-1|bc` ; M9=`echo 2^61-1|bc`
14676 /usr/bin/time -f '%U' factor $(echo "$M8 * $M9" | bc)
14677 4951760154835678088235319297: 2147483647 2305843009213693951
14681 Similarly, factoring the eighth Fermat number @math{2^{256}+1} takes
14682 about 20 seconds on the same machine.
14684 Factoring large prime numbers is, in general, hard. The Pollard Rho
14685 algorithm used by @command{factor} is particularly effective for
14686 numbers with relatively small factors. If you wish to factor large
14687 numbers which do not have small factors (for example, numbers which
14688 are the product of two large primes), other methods are far better.
14690 If @command{factor} is built without using GNU MP, only
14691 single-precision arithmetic is available, and so large numbers
14692 (typically @math{2^{64}} and above) will not be supported. The single-precision
14693 code uses an algorithm which is designed for factoring smaller
14699 @node seq invocation
14700 @section @command{seq}: Print numeric sequences
14703 @cindex numeric sequences
14704 @cindex sequence of numbers
14706 @command{seq} prints a sequence of numbers to standard output. Synopses:
14709 seq [@var{option}]@dots{} @var{last}
14710 seq [@var{option}]@dots{} @var{first} @var{last}
14711 seq [@var{option}]@dots{} @var{first} @var{increment} @var{last}
14714 @command{seq} prints the numbers from @var{first} to @var{last} by
14715 @var{increment}. By default, each number is printed on a separate line.
14716 When @var{increment} is not specified, it defaults to @samp{1},
14717 even when @var{first} is larger than @var{last}.
14718 @var{first} also defaults to @samp{1}. So @code{seq 1} prints
14719 @samp{1}, but @code{seq 0} and @code{seq 10 5} produce no output.
14720 Floating-point numbers
14721 may be specified (using a period before any fractional digits).
14723 The program accepts the following options. Also see @ref{Common options}.
14724 Options must precede operands.
14727 @item -f @var{format}
14728 @itemx --format=@var{format}
14729 @opindex -f @var{format}
14730 @opindex --format=@var{format}
14731 @cindex formatting of numbers in @command{seq}
14732 Print all numbers using @var{format}.
14733 @var{format} must contain exactly one of the @samp{printf}-style
14734 floating point conversion specifications @samp{%a}, @samp{%e},
14735 @samp{%f}, @samp{%g}, @samp{%A}, @samp{%E}, @samp{%F}, @samp{%G}.
14736 The @samp{%} may be followed by zero or more flags taken from the set
14737 @samp{-+#0 '}, then an optional width containing one or more digits,
14738 then an optional precision consisting of a @samp{.} followed by zero
14739 or more digits. @var{format} may also contain any number of @samp{%%}
14740 conversion specifications. All conversion specifications have the
14741 same meaning as with @samp{printf}.
14743 The default format is derived from @var{first}, @var{step}, and
14744 @var{last}. If these all use a fixed point decimal representation,
14745 the default format is @samp{%.@var{p}f}, where @var{p} is the minimum
14746 precision that can represent the output numbers exactly. Otherwise,
14747 the default format is @samp{%g}.
14749 @item -s @var{string}
14750 @itemx --separator=@var{string}
14751 @cindex separator for numbers in @command{seq}
14752 Separate numbers with @var{string}; default is a newline.
14753 The output always terminates with a newline.
14756 @itemx --equal-width
14757 Print all numbers with the same width, by padding with leading zeros.
14758 @var{first}, @var{step}, and @var{last} should all use a fixed point
14759 decimal representation.
14760 (To have other kinds of padding, use @option{--format}).
14764 You can get finer-grained control over output with @option{-f}:
14767 $ seq -f '(%9.2E)' -9e5 1.1e6 1.3e6
14773 If you want hexadecimal integer output, you can use @command{printf}
14774 to perform the conversion:
14777 $ printf '%x\n' `seq 1048575 1024 1050623`
14783 For very long lists of numbers, use xargs to avoid
14784 system limitations on the length of an argument list:
14787 $ seq 1000000 | xargs printf '%x\n' | tail -n 3
14793 To generate octal output, use the printf @code{%o} format instead
14796 On most systems, seq can produce whole-number output for values up to
14797 at least @math{2^{53}}. Larger integers are approximated. The details
14798 differ depending on your floating-point implementation, but a common
14799 case is that @command{seq} works with integers through @math{2^{64}},
14800 and larger integers may not be numerically correct:
14803 $ seq 18446744073709551616 1 18446744073709551618
14804 18446744073709551616
14805 18446744073709551616
14806 18446744073709551618
14809 Be careful when using @command{seq} with outlandish values: otherwise
14810 you may see surprising results, as @command{seq} uses floating point
14811 internally. For example, on the x86 platform, where the internal
14812 representation uses a 64-bit fraction, the command:
14815 seq 1 0.0000000000000000001 1.0000000000000000009
14818 outputs 1.0000000000000000007 twice and skips 1.0000000000000000008.
14823 @node File permissions
14824 @chapter File permissions
14827 @include getdate.texi
14831 @node Opening the software toolbox
14832 @chapter Opening the Software Toolbox
14834 An earlier version of this chapter appeared in
14835 @uref{http://www.linuxjournal.com/article.php?sid=2762, the
14836 @cite{What's GNU?} column of @cite{Linux Journal}, 2 (June, 1994)}.
14837 It was written by Arnold Robbins.
14840 * Toolbox introduction:: Toolbox introduction
14841 * I/O redirection:: I/O redirection
14842 * The who command:: The @command{who} command
14843 * The cut command:: The @command{cut} command
14844 * The sort command:: The @command{sort} command
14845 * The uniq command:: The @command{uniq} command
14846 * Putting the tools together:: Putting the tools together
14850 @node Toolbox introduction
14851 @unnumberedsec Toolbox Introduction
14853 This month's column is only peripherally related to the GNU Project, in
14854 that it describes a number of the GNU tools on your GNU/Linux system and how they
14855 might be used. What it's really about is the ``Software Tools'' philosophy
14856 of program development and usage.
14858 The software tools philosophy was an important and integral concept
14859 in the initial design and development of Unix (of which Linux and GNU are
14860 essentially clones). Unfortunately, in the modern day press of
14861 Internetworking and flashy GUIs, it seems to have fallen by the
14862 wayside. This is a shame, since it provides a powerful mental model
14863 for solving many kinds of problems.
14865 Many people carry a Swiss Army knife around in their pants pockets (or
14866 purse). A Swiss Army knife is a handy tool to have: it has several knife
14867 blades, a screwdriver, tweezers, toothpick, nail file, corkscrew, and perhaps
14868 a number of other things on it. For the everyday, small miscellaneous jobs
14869 where you need a simple, general purpose tool, it's just the thing.
14871 On the other hand, an experienced carpenter doesn't build a house using
14872 a Swiss Army knife. Instead, he has a toolbox chock full of specialized
14873 tools---a saw, a hammer, a screwdriver, a plane, and so on. And he knows
14874 exactly when and where to use each tool; you won't catch him hammering nails
14875 with the handle of his screwdriver.
14877 The Unix developers at Bell Labs were all professional programmers and trained
14878 computer scientists. They had found that while a one-size-fits-all program
14879 might appeal to a user because there's only one program to use, in practice
14884 difficult to write,
14887 difficult to maintain and
14891 difficult to extend to meet new situations.
14894 Instead, they felt that programs should be specialized tools. In short, each
14895 program ``should do one thing well.'' No more and no less. Such programs are
14896 simpler to design, write, and get right---they only do one thing.
14898 Furthermore, they found that with the right machinery for hooking programs
14899 together, that the whole was greater than the sum of the parts. By combining
14900 several special purpose programs, you could accomplish a specific task
14901 that none of the programs was designed for, and accomplish it much more
14902 quickly and easily than if you had to write a special purpose program.
14903 We will see some (classic) examples of this further on in the column.
14904 (An important additional point was that, if necessary, take a detour
14905 and build any software tools you may need first, if you don't already
14906 have something appropriate in the toolbox.)
14908 @node I/O redirection
14909 @unnumberedsec I/O Redirection
14911 Hopefully, you are familiar with the basics of I/O redirection in the
14912 shell, in particular the concepts of ``standard input,'' ``standard output,''
14913 and ``standard error''. Briefly, ``standard input'' is a data source, where
14914 data comes from. A program should not need to either know or care if the
14915 data source is a disk file, a keyboard, a magnetic tape, or even a punched
14916 card reader. Similarly, ``standard output'' is a data sink, where data goes
14917 to. The program should neither know nor care where this might be.
14918 Programs that only read their standard input, do something to the data,
14919 and then send it on, are called @dfn{filters}, by analogy to filters in a
14922 With the Unix shell, it's very easy to set up data pipelines:
14925 program_to_create_data | filter1 | ... | filterN > final.pretty.data
14928 We start out by creating the raw data; each filter applies some successive
14929 transformation to the data, until by the time it comes out of the pipeline,
14930 it is in the desired form.
14932 This is fine and good for standard input and standard output. Where does the
14933 standard error come in to play? Well, think about @command{filter1} in
14934 the pipeline above. What happens if it encounters an error in the data it
14935 sees? If it writes an error message to standard output, it will just
14936 disappear down the pipeline into @command{filter2}'s input, and the
14937 user will probably never see it. So programs need a place where they can send
14938 error messages so that the user will notice them. This is standard error,
14939 and it is usually connected to your console or window, even if you have
14940 redirected standard output of your program away from your screen.
14942 For filter programs to work together, the format of the data has to be
14943 agreed upon. The most straightforward and easiest format to use is simply
14944 lines of text. Unix data files are generally just streams of bytes, with
14945 lines delimited by the @acronym{ASCII} @sc{lf} (Line Feed) character,
14946 conventionally called a ``newline'' in the Unix literature. (This is
14947 @code{'\n'} if you're a C programmer.) This is the format used by all
14948 the traditional filtering programs. (Many earlier operating systems
14949 had elaborate facilities and special purpose programs for managing
14950 binary data. Unix has always shied away from such things, under the
14951 philosophy that it's easiest to simply be able to view and edit your
14952 data with a text editor.)
14954 OK, enough introduction. Let's take a look at some of the tools, and then
14955 we'll see how to hook them together in interesting ways. In the following
14956 discussion, we will only present those command line options that interest
14957 us. As you should always do, double check your system documentation
14958 for the full story.
14960 @node The who command
14961 @unnumberedsec The @command{who} Command
14963 The first program is the @command{who} command. By itself, it generates a
14964 list of the users who are currently logged in. Although I'm writing
14965 this on a single-user system, we'll pretend that several people are
14970 @print{} arnold console Jan 22 19:57
14971 @print{} miriam ttyp0 Jan 23 14:19(:0.0)
14972 @print{} bill ttyp1 Jan 21 09:32(:0.0)
14973 @print{} arnold ttyp2 Jan 23 20:48(:0.0)
14976 Here, the @samp{$} is the usual shell prompt, at which I typed @samp{who}.
14977 There are three people logged in, and I am logged in twice. On traditional
14978 Unix systems, user names are never more than eight characters long. This
14979 little bit of trivia will be useful later. The output of @command{who} is nice,
14980 but the data is not all that exciting.
14982 @node The cut command
14983 @unnumberedsec The @command{cut} Command
14985 The next program we'll look at is the @command{cut} command. This program
14986 cuts out columns or fields of input data. For example, we can tell it
14987 to print just the login name and full name from the @file{/etc/passwd}
14988 file. The @file{/etc/passwd} file has seven fields, separated by
14992 arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/bash
14995 To get the first and fifth fields, we would use @command{cut} like this:
14998 $ cut -d: -f1,5 /etc/passwd
14999 @print{} root:Operator
15001 @print{} arnold:Arnold D. Robbins
15002 @print{} miriam:Miriam A. Robbins
15006 With the @option{-c} option, @command{cut} will cut out specific characters
15007 (i.e., columns) in the input lines. This is useful for input data
15008 that has fixed width fields, and does not have a field separator. For
15009 example, list the Monday dates for the current month:
15011 @c Is using cal ok? Looked at gcal, but I don't like it.
15022 @node The sort command
15023 @unnumberedsec The @command{sort} Command
15025 Next we'll look at the @command{sort} command. This is one of the most
15026 powerful commands on a Unix-style system; one that you will often find
15027 yourself using when setting up fancy data plumbing.
15030 command reads and sorts each file named on the command line. It then
15031 merges the sorted data and writes it to standard output. It will read
15032 standard input if no files are given on the command line (thus
15033 making it into a filter). The sort is based on the character collating
15034 sequence or based on user-supplied ordering criteria.
15037 @node The uniq command
15038 @unnumberedsec The @command{uniq} Command
15040 Finally (at least for now), we'll look at the @command{uniq} program. When
15041 sorting data, you will often end up with duplicate lines, lines that
15042 are identical. Usually, all you need is one instance of each line.
15043 This is where @command{uniq} comes in. The @command{uniq} program reads its
15044 standard input. It prints only one
15045 copy of each repeated line. It does have several options. Later on,
15046 we'll use the @option{-c} option, which prints each unique line, preceded
15047 by a count of the number of times that line occurred in the input.
15050 @node Putting the tools together
15051 @unnumberedsec Putting the Tools Together
15053 Now, let's suppose this is a large ISP server system with dozens of users
15054 logged in. The management wants the system administrator to write a program that will
15055 generate a sorted list of logged in users. Furthermore, even if a user
15056 is logged in multiple times, his or her name should only show up in the
15059 The administrator could sit down with the system documentation and write a C
15060 program that did this. It would take perhaps a couple of hundred lines
15061 of code and about two hours to write it, test it, and debug it.
15062 However, knowing the software toolbox, the administrator can instead start out
15063 by generating just a list of logged on users:
15073 Next, sort the list:
15076 $ who | cut -c1-8 | sort
15083 Finally, run the sorted list through @command{uniq}, to weed out duplicates:
15086 $ who | cut -c1-8 | sort | uniq
15092 The @command{sort} command actually has a @option{-u} option that does what
15093 @command{uniq} does. However, @command{uniq} has other uses for which one
15094 cannot substitute @samp{sort -u}.
15096 The administrator puts this pipeline into a shell script, and makes it available for
15097 all the users on the system (@samp{#} is the system administrator,
15098 or @code{root}, prompt):
15101 # cat > /usr/local/bin/listusers
15102 who | cut -c1-8 | sort | uniq
15104 # chmod +x /usr/local/bin/listusers
15107 There are four major points to note here. First, with just four
15108 programs, on one command line, the administrator was able to save about two
15109 hours worth of work. Furthermore, the shell pipeline is just about as
15110 efficient as the C program would be, and it is much more efficient in
15111 terms of programmer time. People time is much more expensive than
15112 computer time, and in our modern ``there's never enough time to do
15113 everything'' society, saving two hours of programmer time is no mean
15116 Second, it is also important to emphasize that with the
15117 @emph{combination} of the tools, it is possible to do a special
15118 purpose job never imagined by the authors of the individual programs.
15120 Third, it is also valuable to build up your pipeline in stages, as we did here.
15121 This allows you to view the data at each stage in the pipeline, which helps
15122 you acquire the confidence that you are indeed using these tools correctly.
15124 Finally, by bundling the pipeline in a shell script, other users can use
15125 your command, without having to remember the fancy plumbing you set up for
15126 them. In terms of how you run them, shell scripts and compiled programs are
15129 After the previous warm-up exercise, we'll look at two additional, more
15130 complicated pipelines. For them, we need to introduce two more tools.
15132 The first is the @command{tr} command, which stands for ``transliterate.''
15133 The @command{tr} command works on a character-by-character basis, changing
15134 characters. Normally it is used for things like mapping upper case to
15138 $ echo ThIs ExAmPlE HaS MIXED case! | tr '[:upper:]' '[:lower:]'
15139 @print{} this example has mixed case!
15142 There are several options of interest:
15146 work on the complement of the listed characters, i.e.,
15147 operations apply to characters not in the given set
15150 delete characters in the first set from the output
15153 squeeze repeated characters in the output into just one character.
15156 We will be using all three options in a moment.
15158 The other command we'll look at is @command{comm}. The @command{comm}
15159 command takes two sorted input files as input data, and prints out the
15160 files' lines in three columns. The output columns are the data lines
15161 unique to the first file, the data lines unique to the second file, and
15162 the data lines that are common to both. The @option{-1}, @option{-2}, and
15163 @option{-3} command line options @emph{omit} the respective columns. (This is
15164 non-intuitive and takes a little getting used to.) For example:
15186 The file name @file{-} tells @command{comm} to read standard input
15187 instead of a regular file.
15189 Now we're ready to build a fancy pipeline. The first application is a word
15190 frequency counter. This helps an author determine if he or she is over-using
15193 The first step is to change the case of all the letters in our input file
15194 to one case. ``The'' and ``the'' are the same word when doing counting.
15197 $ tr '[:upper:]' '[:lower:]' < whats.gnu | ...
15200 The next step is to get rid of punctuation. Quoted words and unquoted words
15201 should be treated identically; it's easiest to just get the punctuation out of
15205 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | ...
15208 The second @command{tr} command operates on the complement of the listed
15209 characters, which are all the letters, the digits, the underscore, and
15210 the blank. The @samp{\n} represents the newline character; it has to
15211 be left alone. (The @acronym{ASCII} tab character should also be included for
15212 good measure in a production script.)
15214 At this point, we have data consisting of words separated by blank space.
15215 The words only contain alphanumeric characters (and the underscore). The
15216 next step is break the data apart so that we have one word per line. This
15217 makes the counting operation much easier, as we will see shortly.
15220 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
15221 > tr -s ' ' '\n' | ...
15224 This command turns blanks into newlines. The @option{-s} option squeezes
15225 multiple newline characters in the output into just one. This helps us
15226 avoid blank lines. (The @samp{>} is the shell's ``secondary prompt.''
15227 This is what the shell prints when it notices you haven't finished
15228 typing in all of a command.)
15230 We now have data consisting of one word per line, no punctuation, all one
15231 case. We're ready to count each word:
15234 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
15235 > tr -s ' ' '\n' | sort | uniq -c | ...
15238 At this point, the data might look something like this:
15251 The output is sorted by word, not by count! What we want is the most
15252 frequently used words first. Fortunately, this is easy to accomplish,
15253 with the help of two more @command{sort} options:
15257 do a numeric sort, not a textual one
15260 reverse the order of the sort
15263 The final pipeline looks like this:
15266 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
15267 > tr -s ' ' '\n' | sort | uniq -c | sort -n -r
15276 Whew! That's a lot to digest. Yet, the same principles apply. With six
15277 commands, on two lines (really one long one split for convenience), we've
15278 created a program that does something interesting and useful, in much
15279 less time than we could have written a C program to do the same thing.
15281 A minor modification to the above pipeline can give us a simple spelling
15282 checker! To determine if you've spelled a word correctly, all you have to
15283 do is look it up in a dictionary. If it is not there, then chances are
15284 that your spelling is incorrect. So, we need a dictionary.
15285 The conventional location for a dictionary is @file{/usr/dict/words}.
15286 On my GNU/Linux system,@footnote{Redhat Linux 6.1, for the November 2000
15287 revision of this article.}
15288 this is a is a sorted, 45,402 word dictionary.
15290 Now, how to compare our file with the dictionary? As before, we generate
15291 a sorted list of words, one per line:
15294 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
15295 > tr -s ' ' '\n' | sort -u | ...
15298 Now, all we need is a list of words that are @emph{not} in the
15299 dictionary. Here is where the @command{comm} command comes in.
15302 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
15303 > tr -s ' ' '\n' | sort -u |
15304 > comm -23 - /usr/dict/words
15307 The @option{-2} and @option{-3} options eliminate lines that are only in the
15308 dictionary (the second file), and lines that are in both files. Lines
15309 only in the first file (standard input, our stream of words), are
15310 words that are not in the dictionary. These are likely candidates for
15311 spelling errors. This pipeline was the first cut at a production
15312 spelling checker on Unix.
15314 There are some other tools that deserve brief mention.
15318 search files for text that matches a regular expression
15321 count lines, words, characters
15324 a T-fitting for data pipes, copies data to files and to standard output
15327 the stream editor, an advanced tool
15330 a data manipulation language, another advanced tool
15333 The software tools philosophy also espoused the following bit of
15334 advice: ``Let someone else do the hard part.'' This means, take
15335 something that gives you most of what you need, and then massage it the
15336 rest of the way until it's in the form that you want.
15342 Each program should do one thing well. No more, no less.
15345 Combining programs with appropriate plumbing leads to results where
15346 the whole is greater than the sum of the parts. It also leads to novel
15347 uses of programs that the authors might never have imagined.
15350 Programs should never print extraneous header or trailer data, since these
15351 could get sent on down a pipeline. (A point we didn't mention earlier.)
15354 Let someone else do the hard part.
15357 Know your toolbox! Use each program appropriately. If you don't have an
15358 appropriate tool, build one.
15361 As of this writing, all the programs we've discussed are available via
15362 anonymous @command{ftp} from: @*
15363 @uref{ftp://gnudist.gnu.org/textutils/textutils-1.22.tar.gz}. (There may
15364 be more recent versions available now.)
15366 None of what I have presented in this column is new. The Software Tools
15367 philosophy was first introduced in the book @cite{Software Tools}, by
15368 Brian Kernighan and P.J. Plauger (Addison-Wesley, ISBN 0-201-03669-X).
15369 This book showed how to write and use software tools. It was written in
15370 1976, using a preprocessor for FORTRAN named @command{ratfor} (RATional
15371 FORtran). At the time, C was not as ubiquitous as it is now; FORTRAN
15372 was. The last chapter presented a @command{ratfor} to FORTRAN
15373 processor, written in @command{ratfor}. @command{ratfor} looks an awful
15374 lot like C; if you know C, you won't have any problem following the
15377 In 1981, the book was updated and made available as @cite{Software Tools
15378 in Pascal} (Addison-Wesley, ISBN 0-201-10342-7). Both books are
15379 still in print and are well worth
15380 reading if you're a programmer. They certainly made a major change in
15381 how I view programming.
15383 The programs in both books are available from
15384 @uref{http://cm.bell-labs.com/who/bwk, Brian Kernighan's home page}.
15385 For a number of years, there was an active
15386 Software Tools Users Group, whose members had ported the original
15387 @command{ratfor} programs to essentially every computer system with a
15388 FORTRAN compiler. The popularity of the group waned in the middle 1980s
15389 as Unix began to spread beyond universities.
15391 With the current proliferation of GNU code and other clones of Unix programs,
15392 these programs now receive little attention; modern C versions are
15393 much more efficient and do more than these programs do. Nevertheless, as
15394 exposition of good programming style, and evangelism for a still-valuable
15395 philosophy, these books are unparalleled, and I recommend them highly.
15397 Acknowledgment: I would like to express my gratitude to Brian Kernighan
15398 of Bell Labs, the original Software Toolsmith, for reviewing this column.
15400 @node GNU Free Documentation License
15401 @appendix GNU Free Documentation License
15405 @node Concept index
15414 @c Local variables:
15415 @c texinfo-column-for-description: 32