diff options
Diffstat (limited to 'man1/ls.1')
| -rw-r--r-- | man1/ls.1 | 573 |
1 files changed, 573 insertions, 0 deletions
diff --git a/man1/ls.1 b/man1/ls.1 new file mode 100644 index 000000000..7a4ca35d8 --- /dev/null +++ b/man1/ls.1 @@ -0,0 +1,573 @@ +.\" Copyright Andries Brouwer, Ragnar Hojland Espinosa and A. Wik, 1998. +.\" +.\" This file may be copied under the conditions described +.\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998 +.\" that should have been distributed together with this file. +.\" +.TH LS 1 1998-11 "GNU fileutils 4.0" +.SH NAME +ls, dir, vdir \- list directory contents +.SH SYNOPSIS +.BI "ls [" options "] [" file... ] +.br +.BI "dir [" file... ] +.br +.BI "vdir [" file... ] +.sp +POSIX options: +.BI "[\-CFRacdilqrtu1] [\-\-]" +.sp +GNU options (shortest form): +.B [\-1abcdfghiklmnopqrstuvwxABCDFGHLNQRSUX] +.BI "[\-w " cols ] +.BI "[\-T " cols ] +.BI "[\-I " pattern ] +.B [\-\-full\-time] +.B [\-\-show\-control\-chars] +.BI "[\-\-block\-size=" size ] +.B [\-\-format={long,verbose,commas,across,vertical,single\-column}] +.B [\-\-sort={none,time,size,extension}] +.B [\-\-time={atime,access,use,ctime,status}] +.B [\-\-color[={none,auto,always}]] +.B "[\-\-help] [\-\-version] [\-\-]" +.SH DESCRIPTION +The program +.B ls +lists first its non-directory +.I file +arguments, and then for each directory argument all listable files +contained within that directory. If no non-option arguments are present, +a default argument `.' (the current directory) is assumed. +The \-d option causes directories to be treated as non-directory arguments. +A file is listable when either its name does not start with `.', +or the \-a option is given. +.PP +Each of the lists of files (that of non-directory files, and for +each directory the list of files inside) is sorted separately +according to the collating sequence in the current locale. +When the \-l option is given, each list is preceded by a summary +line giving the total size of all files in the list, measured +in 512-byte or 1024-byte blocks. +.\" POSIX: 512, GNU: 1024 +.\" rumoured: early AIX 3.1: 1024, later AIX: 512 +.PP +The output is to stdout, one entry per line, unless multicolumn +output is requested by the \-C option. However, for output to a +terminal, it is undefined whether the output will be single-column +or multi-column. The options \-1 and \-C can be used to force +single-column and multi-column output, respectively. +.SH "POSIX OPTIONS" +.TP +.B "\-C" +List files in columns, sorted vertically. +.TP +.B "\-F" +Suffix each directory name with `/', each FIFO name with `|', and +each name of an executable with `*'. +.TP +.B "\-R" +Recursively list subdirectories encountered. +.TP +.B "\-a" +Include files with a name starting with `.' in the listing. +.TP +.B "\-c" +Use the status change time instead of the modification time +for sorting (with \-t) or listing (with \-l). +.TP +.B "\-d" +List names of directories like other files, rather than +listing their contents. +.TP +.B "\-i" +Precede the output for the file by the file serial number (i-node number). +.TP +.B "\-l" +Write (in single-column format) the file mode, the number of links +to the file, the owner name, the group name, the size of the file (in bytes), +the timestamp, and the filename. The summary line uses 512-byte units. + +The file types are as follows: +.B \- +for an ordinary file, +.B d +for a directory, +.B b +for a block special device, +.B c +for a character special device, +.B l +for a symbolic link, +.B p +for a fifo, +.B s +for a socket. + +By default, the timestamp shown is that of the last modification; the +options \-c and \-u select the other two timestamps. +For device special files the size field is commonly replaced +by the major and minor device numbers. +.TP +.B "\-q" +Output nonprintable characters in a filename as question marks. +(This is permitted to be the default for output to a terminal.) +.TP +.B "\-r" +Reverse the order of the sort. +.TP +.B "\-t" +Sort by the timestamp shown. +.TP +.B "\-u" +Use the time of last access instead of the modification time +for sorting (with \-t) or listing (with \-l). +.TP +.B "\-1" +For single-column output. +.TP +.B "\-\-" +Terminate option list. +.SH "GNU DETAILS" +If standard output is a terminal, the output is in columns (sorted vertically). +.PP +.B dir +(also installed as +.BR d ) +is equivalent to `ls\ \-C\ \-b'; that is, files are by default listed +in columns, sorted vertically. +.B vdir +(also installed as +.BR v ) +is equivalent to `ls\ \-l\ \-b'; that is, files are by default listed +in long format. +.SH "GNU OPTIONS" +.TP +.B "\-1, \-\-format=single\-column" +List one file per line. This is the default for when standard output is +not a terminal. +.TP +.B "\-a, \-\-all" +List all files in directories, including all files that start with `.'. +.TP +.B "\-b, \-\-escape, \-\-quoting\-style=escape" +Quote nongraphic characters in file names using alphabetic and octal +backslash sequences like those used in C. This option is the same as +.B "\-Q" +except that filenames are not surrounded by double\-quotes. +.TP +.B "\-c, \-\-time=ctime, \-\-time=status" +Sort directory contents according to the files' status change time (the +`ctime' in the inode). If the long listing format is being +.RB "used (" \-l ) +print the status change time instead of the modification time. +.TP +.B "\-d, \-\-directory" +List names of directories like other files, rather than listing their contents. +.TP +.B "\-f" +Do not sort directory contents; list them in whatever order they are +stored on the disk. +Also enables +.B \-a +and +.BR \-U +and disables +.BR \-l , +.BR \-\-color , +.BR \-s , +and +.B \-t +if they were specified before the +.BR \-f . +.TP +.B \-g +Ignored; for Unix compatibility. +.TP +.B "\-h, \-\-human\-readable" +Append a size letter, such as +.B M +for binary megabytes (`mebibytes'), to each size. +(New in file\%utils-4.0.) +.TP +.B "\-i, \-\-inode" +Print the inode number (also called the file serial number and index +number) of each file to the left of the file name. (This number uniquely +identifies each file within a particular filesystem) +.TP +.B "\-k, \-\-kilobytes" +If file sizes are being listed, print them in kilobytes. +.TP +.B "\-l, \-\-format=long, \-\-format=verbose" +In addition to the name of each file, print the file type, +permissions, number of hard links, owner name, group name, size in +bytes, and timestamp (the modification time unless other times are +selected). For files with a time that is more than 6 months old or +more than 1 hour into the future, the timestamp contains the year +instead of the time of day. + +For each directory that is listed, preface the files with a line +`total +.IR blocks "', where " blocks " is the total disk space used by all" +files in that directory. By default, 1024-byte blocks are used; +if the environment variable +.B POSIXLY_CORRECT +is set, 512-byte blocks are used (unless the +.B \-k +.RI "option is given). The " blocks +computed counts each hard link separately; this is arguably a deficiency. + +The permissions listed are similar to symbolic mode specifications but +.B ls +combines multiple bits into the third character of each set of permissions +.RS +.TP +.B s +If the setuid or setgid bit and the corresponding executable bit are +both set. +.TP +.B S +If the setuid or setgid bit is set but the corresponding executable bit +is not set. +.TP +.B t +If the sticky bit and the other-executable bit are both set. +.TP +.B T +If the sticky bit is set but the other-executable bit is not set. +.TP +.B x +If the executable bit is set and none of the above apply. +.TP +.B \- +Otherwise. +.RE +.TP +.B "\-m, \-\-format=commas" +List files horizontally, with as many as will fit on each line, +each separated by a comma and a space. +.TP +.B "\-n, \-\-numeric\-uid\-gid" +List the numeric UID and GID instead of the names. +.TP +.B \-o +Produce long format directory listings, but don't display group +information. It is equivalent to using +.BR "\-\-format=long \-\-no\-group" . +This option is provided for compatibility with other versions of +.BR ls . +.TP +.B "\-p, \-\-file\-type, \-\-indicator\-style=file\-type" +Append a character to each file name indicating the file type. This is like +.B \-F +except that executables aren't marked. +(In fact fileutils-4.0 treats the --file-type option like --classify.) +.TP +.B "\-q, \-\-hide\-control\-chars" +Print question marks instead of nongraphic characters in file names. This +is the default. +.TP +.B "\-r, \-\-reverse" +Sort directory contents in reverse order. +.TP +.B "\-s, \-\-size" +Print the size of each file in 1024-byte blocks to the left of the file name. +If the environment variable +.B POSIXLY_CORRECT +is set, 512-byte blocks are used instead, unless the +.B \-k +option is given. +.TP +.B "\-t, \-\-sort=time" +Sort by modification time (the `mtime' in the inode) instead of +alphabetically, with the newest files listed first. +.TP +.B "\-u, \-\-time=atime, \-\-time=access, \-\-time=use" +Sort directory contents according to the files' last access time +instead of the modification time (the `atime' in the inode). If the long +listing format is being used, print the last access time instead of the +modification time. +.TP +.B "\-v" +Sort directory contents according to the files' version. This takes into +account the fact that filenames frequently include indices or version +numbers. Standard sorting functions usually do not produce the ordering +that people expect because comparisons are made on a +character\-by\-character basis. The version sort addresses this problem, +and is especially useful when browsing directories that contain many +files with indices/version numbers in their names. For example: + +.nf + > ls -1 > ls -1v + foo.zml-1.gz foo.zml-1.gz + foo.zml-100.gz foo.zml-12.gz + foo.zml-12.gz foo.zml-25.gz + foo.zml-25.gz foo.zml-100.gz +.fi + +Note also that numeric parts with leading zeroes are considered as +fractional: + +.nf + > ls -1 > ls -1v + abc-1.007.tgz abc-1.007.tgz + abc-1.012b.tgz abc-1.01a.tgz + abc-1.01a.tgz abc-1.012b.tgz +.fi + +(New in file\%utils-4.0.) +.TP +.BI "\-w, \-\-width " cols +Assume the screen is +.I cols +columns wide. The default is taken from the terminal driver if +possible; otherwise the environment variable +.B COLUMNS +is used if it is set; otherwise the default is 80. +.TP +.B "\-x, \-\-format=across, \-\-format=horizontal" +List the files in columns, sorted horizontally. +.TP +.B "\-A, \-\-almost\-all" +List all files in directories, except for `.' and `..'. +.TP +.B "\-B, \-\-ignore\-backups" +Do not list files that end with `~', unless they are given on the +command line. +.TP +.B "\-C, \-\-format=vertical" +List files in columns, sorted vertically. This is the default if standard +output is a terminal. It is always the default for +.BR dir " and " d . +.TP +.B "\-D, \-\-dired" +With the long listing +.RB ( \-l ) +format, print an additional line after the main output: +.br +.B //DIRED// +.I BEG1 END1 BEG2 END2 ... +.br + +The +.IR BEGn " and " ENDn +are unsigned integers which record the byte position of +the beginning and end of each file name in the output. This makes it easy +for Emacs to find the names, even when they contain unusual characters +such as space or newline, without fancy searching. + +If directories are being listed recursively +.RB ( \-R ), +output a similar line after each subdirectory: +.br +.B //SUBDIRED// +.I BEG1 END1 ... +.TP +.B "\-F, \-\-classify, \-\-indicator\-style=classify" +Append a character to each file name indicating the file type. For +regular files that are executable, append a `*'. The file type +indicators are `/' for directories, `@' for symbolic links, `|' for +FIFOs, `=' for sockets, and nothing for regular files. +.TP +.B "\-G, \-\-no\-group" +Inhibit display of group information in a long format directory listing. +.TP +.B "\-H, \-\-si" +Do the same as for +.BR \-h , +but use the official SI units (with powers of 1000 instead of 1024, +so that M stands for 1000000 instead of 1048576). +(New in fileutils-4.0.) +.TP +.BI "\-I, \-\-ignore=" pattern +Do not list files whose names match the shell pattern +.I pattern +(not regular expression) unless they are given on the command line. As +in the shell, an initial `.' in a filename does not match a wildcard at +the start of +.I pattern. +For simple-minded root-kits: add LS_OPTIONS="$LS_OPTIONS -I mystuff" +in /etc/profile or so, to hide your directories. +.TP +.B "\-L, \-\-dereference" +List the file information corresponding to the referrents of symbolic +links rather for the links themselves. +.TP +.B "\-N, \-\-literal" +Do not quote file names. +.TP +.B "\-Q, \-\-quote\-name, \-\-quoting\-style=c" +Enclose file names in double quotes and quote nongraphic characters as +in C. +.TP +.B "\-R, \-\-recursive" +List the contents of all directories recursively. +.TP +.B "\-S, \-\-sort=size" +Sort directory contents by file size instead of alphabetically, with +the largest files listed first. +.TP +.BI "\-T, \-\-tabsize " cols +Assume that each tabstop is +.I cols +columns wide. The default is 8 and can be overridden by +the environment variable TABSIZE when POSIXLY_CORRECT is not set. +.B ls +uses tabs where possible in the output, for efficiency. If +.I cols +is zero, do not use tabs at all. +.TP +.B "\-U, \-\-sort=none" +Do not sort directory contents; list them in whatever order they are +stored on the disk. (The difference between +.BR \-U " and " \-f +is that the former doesn't disable or enable options.) This is especially +useful when listing very large directories, since not doing any sorting +can be noticeably faster. +.TP +.B "\-X, \-\-sort=extension" +Sort directory contents alphabetically by file extension (characters +after the last `.'); files with no extension are sorted first. +.TP +.BI "\-\-block\-size=" size +Print sizes in blocks of +.I size +bytes. +(New in file\%utils-4.0.) +.TP +.BI "\-\-color[=" when ] +Specify whether to use color for distinguishing file types. +Colors are specified using the LS_COLORS environment variable. +For information on how to set this variable, see +.BR dircolors (1). +.I when +may be omitted, or one of: +.RS +.TP +.B none +Do not use color at all. This is the default. +.TP +.B auto +Only use color if standard output is a terminal. +.TP +.B always +Always use color. Specifying +.B \-\-color +and no +.I when +is equivalent to +.BR "\-\-color=always" . +.RE +.TP +.B "\-\-full\-time" +List times in full, rather than using the standard abbreviation +heuristics. The format is the same as +.BR date (1)'s +default; it's not possible to change this, but you can extract out the +date string with +.BR cut (1) +and then pass the result to `date \-d'. + +This is most useful because the time output includes the seconds. +(Unix filesystems store file timestamps only to the nearest +second, so this option shows all the information there is.) For +example, this can help when you have a Makefile that is not +regenerating files properly. +.TP +.BI "\-\-quoting\-style=" word +Use style +.I word +to quote output names. The +.I word +should be one of the following: +.RS +.TP +.B literal +Output names as\-is. This is the default behavior of +.BR ls . +.TP +.B shell +Quote names for the shell if they contain shell metacharacters or +would cause ambiguous output. +.TP +.B "shell\-always" +Quote names for the shell, even if they would normally not +require quoting. +.TP +.B c +Quote names as for a C language string; this is the same as the +.B "\-Q" +option. +.TP +.B escape +Quote as with +.I c +except omit the surrounding double\-quote characters; this is the same +as the +.B "\-b" +option. +.PD +.PP +A default value for this option can be specified with the environment +variable QUOTING_STYLE. (See +.B ENVIRONMENT +below.) +.RE +.TP +.B "\-\-show\-control\-chars" +Print nongraphic characters as-is in file names. This is the +default unless the output is a terminal and the program is +.BR ls . +.SH "GNU STANDARD OPTIONS" +.TP +.B "\-\-help" +Print a usage message on standard output and exit successfully. +.TP +.B "\-\-version" +Print version information on standard output, then exit successfully. +.TP +.B "\-\-" +Terminate option list. +.SH ENVIRONMENT +The variable POSIXLY_CORRECT determines the choice of unit. +If it is not set, then the variable TABSIZE determines the +number of chars per tab stop. +The variable COLUMNS (when it contains the representation of a decimal +integer) determines the output column width (for use with the \-C option). +Filenames must not be truncated to make them fit a multi-column output. +.PP +The variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES and LC_TIME +have the usual meaning. +The variable TZ gives the time zone for time strings written by +.BR ls . +The variable LS_COLORS is used to specify the colors used. +The variable LS_OPTIONS gives default options. +.\" Since which ls version? +.PP +The variable QUOTING_STYLE is used to specify the default value for the +.B "\-\-quoting\-style" +option. It currently defaults to +.BR literal , +though the authors have warned that this default may change to +.B shell +in some future version of +.BR ls . +.SH BUGS +On BSD systems, the +.B "\-s" +option reports sizes that are half the correct values for files that are +NFS-mounted from HP-UX systems. On HP-UX systems, +.B ls +reports sizes that +are twice the correct values for files that are NFS-mounted from BSD +systems. This is due to a flaw in HP-UX; it also affects the HP-UX +.B ls +program. +.SH "CONFORMING TO" +POSIX 1003.2 +.SH "SEE ALSO" +.BR dircolors (1) +.SH NOTES +This page describes +.B ls +as found in the fileutils-4.0 package; +other versions may differ slightly. |