diff options
Diffstat (limited to 'coreutils-5.3.0-bin/man/cat1p/ls.1p.txt')
| -rw-r--r-- | coreutils-5.3.0-bin/man/cat1p/ls.1p.txt | 675 |
1 files changed, 675 insertions, 0 deletions
diff --git a/coreutils-5.3.0-bin/man/cat1p/ls.1p.txt b/coreutils-5.3.0-bin/man/cat1p/ls.1p.txt new file mode 100644 index 0000000..9d42df4 --- /dev/null +++ b/coreutils-5.3.0-bin/man/cat1p/ls.1p.txt @@ -0,0 +1,675 @@ +ls(P) ls(P) + + + + + +NAME + ls - list directory contents + +SYNOPSIS + ls [-CFRacdilqrtu1][-H | -L ][-fgmnopsx][file...] + +DESCRIPTION + For each operand that names a file of a type other than + directory or symbolic link to a directory, ls shall + write the name of the file as well as any requested, + associated information. For each operand that names a + file of type directory, ls shall write the names of + files contained within the directory as well as any + requested, associated information. If one of the -d, -F, + or -l options are specified, and one of the -H or -L + options are not specified, for each operand that names a + file of type symbolic link to a directory, ls shall + write the name of the file as well as any requested, + associated information. If none of the -d, -F, or -l + options are specified, or the -H or -L options are spec- + ified, for each operand that names a file of type sym- + bolic link to a directory, ls shall write the names of + files contained within the directory as well as any + requested, associated information. + + If no operands are specified, ls shall write the con- + tents of the current directory. If more than one operand + is specified, ls shall write non-directory operands + first; it shall sort directory and non-directory oper- + ands separately according to the collating sequence in + the current locale. + + The ls utility shall detect infinite loops; that is, + entering a previously visited directory that is an + ancestor of the last file encountered. When it detects + an infinite loop, ls shall write a diagnostic message to + standard error and shall either recover its position in + the hierarchy or terminate. + +OPTIONS + The ls utility shall conform to the Base Definitions + volume of IEEE Std 1003.1-2001, Section 12.2, Utility + Syntax Guidelines. + + The following options shall be supported: + + -C Write multi-text-column output with entries + sorted down the columns, according to the collat- + ing sequence. The number of text columns and the + column separator characters are unspecified, but + should be adapted to the nature of the output + device. + + -F Do not follow symbolic links named as operands + unless the -H or -L options are specified. Write + a slash ( '/' ) immediately after each pathname + that is a directory, an asterisk ( '*' ) after + each that is executable, a vertical bar ( '|' ) + after each that is a FIFO, and an at sign ( '@' ) + after each that is a symbolic link. For other + file types, other symbols may be written. + + -H If a symbolic link referencing a file of type + directory is specified on the command line, ls + shall evaluate the file information and file type + to be those of the file referenced by the link, + and not the link itself; however, ls shall write + the name of the link itself and not the file ref- + erenced by the link. + + -L Evaluate the file information and file type for + all symbolic links (whether named on the command + line or encountered in a file hierarchy) to be + those of the file referenced by the link, and not + the link itself; however, ls shall write the name + of the link itself and not the file referenced by + the link. When -L is used with -l, write the con- + tents of symbolic links in the long format (see + the STDOUT section). + + -R Recursively list subdirectories encountered. + + -a Write out all directory entries, including those + whose names begin with a period ( '.' ). Entries + beginning with a period shall not be written out + unless explicitly referenced, the -a option is + supplied, or an implementation-defined condition + shall cause them to be written. + + -c Use time of last modification of the file status + information (see <sys/stat.h> in the System + Interfaces volume of IEEE Std 1003.1-2001) + instead of last modification of the file itself + for sorting ( -t) or writing ( -l). + + -d Do not follow symbolic links named as operands + unless the -H or -L options are specified. Do not + treat directories differently than other types of + files. The use of -d with -R produces unspecified + results. + + -f Force each argument to be interpreted as a direc- + tory and list the name found in each slot. This + option shall turn off -l, -t, -s, and -r, and + shall turn on -a; the order is the order in which + entries appear in the directory. + + -g The same as -l, except that the owner shall not + be written. + + -i For each file, write the file's file serial num- + ber (see stat() in the System Interfaces volume + of IEEE Std 1003.1-2001). + + -l (The letter ell.) Do not follow symbolic links + named as operands unless the -H or -L options are + specified. Write out in long format (see the STD- + OUT section). When -l (ell) is specified, -1 + (one) shall be assumed. + + -m Stream output format; list files across the page, + separated by commas. + + -n The same as -l, except that the owner's UID and + GID numbers shall be written, rather than the + associated character strings. + + -o The same as -l, except that the group shall not + be written. + + -p Write a slash ( '/' ) after each filename if that + file is a directory. + + -q Force each instance of non-printable filename + characters and <tab>s to be written as the ques- + tion-mark ( '?' ) character. Implementations may + provide this option by default if the output is + to a terminal device. + + -r Reverse the order of the sort to get reverse col- + lating sequence or oldest first. + + -s Indicate the total number of file system blocks + consumed by each file displayed. The block size + is implementation-defined. <img + src="../images/opt-end.gif" alt="[Option End]" + border="0"> + + -t Sort with the primary key being time modified + (most recently modified first) and the secondary + key being filename in the collating sequence. + + -u Use time of last access (see <sys/stat.h>) + instead of last modification of the file for + sorting ( -t) or writing ( -l). + + -x The same as -C, except that the multi-text-column + output is produced with entries sorted across, + rather than down, the columns. + + -1 (The numeric digit one.) Force output to be one + entry per line. + + + Specifying more than one of the options in the following + mutually-exclusive pairs shall not be considered an + error: -C and -l (ell), -m and -l (ell), -x and -l + (ell), -C and -1 (one), -H and -L, -c and -u. The last + option specified in each pair shall determine the output + format. + +OPERANDS + The following operand shall be supported: + + file A pathname of a file to be written. If the file + specified is not found, a diagnostic message + shall be output on standard error. + + +STDIN + Not used. + +INPUT FILES + None. + +ENVIRONMENT VARIABLES + The following environment variables shall affect the + execution of ls: + + COLUMNS + Determine the user's preferred column position + width for writing multiple text-column output. If + this variable contains a string representing a + decimal integer, the ls utility shall calculate + how many pathname text columns to write (see -C) + based on the width provided. If COLUMNS is not + set or invalid, an implementation-defined number + of column positions shall be assumed, based on + the implementation's knowledge of the output + device. The column width chosen to write the + names of files in any given directory shall be + constant. Filenames shall not be truncated to fit + into the multiple text-column output. + + LANG Provide a default value for the internationaliza- + tion variables that are unset or null. (See the + Base Definitions volume of IEEE Std 1003.1-2001, + Section 8.2, Internationalization Variables for + the precedence of internationalization variables + used to determine the values of locale cate- + gories.) + + LC_ALL If set to a non-empty string value, override the + values of all the other internationalization + variables. + + LC_COLLATE + + Determine the locale for character collation + information in determining the pathname collation + sequence. + + LC_CTYPE + Determine the locale for the interpretation of + sequences of bytes of text data as characters + (for example, single-byte as opposed to multi- + byte characters in arguments) and which charac- + ters are defined as printable (character class + print). + + LC_MESSAGES + Determine the locale that should be used to + affect the format and contents of diagnostic mes- + sages written to standard error. + + LC_TIME + Determine the format and contents for date and + time strings written by ls. + + NLSPATH + Determine the location of message catalogs for + the processing of LC_MESSAGES . + + TZ Determine the timezone for date and time strings + written by ls. If TZ is unset or null, an + unspecified default timezone shall be used. + + +ASYNCHRONOUS EVENTS + Default. + +STDOUT + The default format shall be to list one entry per line + to standard output; the exceptions are to terminals or + when one of the -C, -m, or -x options is specified. + If the output is to a terminal, the format is implemen- + tation-defined. + + When -m is specified, the format used shall be: + + + "%s, %s, ...\n", <filename1>, <filename2> + + where the largest number of filenames shall be written + without exceeding the length of the line. + + If the -i option is specified, the file's file serial + number (see <sys/stat.h>) shall be written in the fol- + lowing format before any other output for the corre- + sponding entry: + + + %u ", <file serial number> + + If the -l option is specified without -L, the following + information shall be written: + + + "%s %u %s %s %u %s %s\n", <file mode>, <number of links>, + <owner name>, <group name>, <number of bytes in the file>, + <date and time>, <pathname> + + If the file is a symbolic link, this information shall + be about the link itself and the <pathname> field shall + be of the form: + + + "%s -> %s", <pathname of link>, <contents of link> + + If both -l and -L are specified, the following informa- + tion shall be written: + + + "%s %u %s %s %u %s %s\n", <file mode>, <number of links>, + <owner name>, <group name>, <number of bytes in the file>, + <date and time>, <pathname of link> + + where all fields except <pathname of link> shall be for + the file resolved from the symbolic link. + + The -g, -n, and -o options use the same format as -l, + but with omitted items and their associated <blank>s. + See the OPTIONS section. + + In both the preceding -l forms, if <owner name> or + <group name> cannot be determined, or if -n is given, + they shall be replaced with their associated numeric + values using the format %u . + + The <date and time> field shall contain the appropriate + date and timestamp of when the file was last modified. + In the POSIX locale, the field shall be the equivalent + of the output of the following date command: + + + date "+%b %e %H:%M" + + if the file has been modified in the last six months, + or: + + + date "+%b %e %Y" + + (where two <space>s are used between %e and %Y ) if the + file has not been modified in the last six months or if + the modification date is in the future, except that, in + both cases, the final <newline> produced by date shall + not be included and the output shall be as if the date + command were executed at the time of the last modifica- + tion date of the file rather than the current time. When + the LC_TIME locale category is not set to the POSIX + locale, a different format and order of presentation of + this field may be used. + + If the file is a character special or block special + file, the size of the file may be replaced with imple- + mentation-defined information associated with the device + in question. + + If the pathname was specified as a file operand, it + shall be written as specified. + + The file mode written under the -l, -g, -n, and -o + options shall consist of the following format: + + + "%c%s%s%s%c", <entry type>, <owner permissions>, + <group permissions>, <other permissions>, + <optional alternate access method flag> + + The <optional alternate access method flag> shall be a + single <space> if there is no alternate or additional + access control method associated with the file; other- + wise, a printable character shall be used. + + The <entry type> character shall describe the type of + file, as follows: + + d Directory. + + b Block special file. + + c Character special file. + + l (ell) + Symbolic link. + + p FIFO. + + - Regular file. + + + Implementations may add other characters to this list to + represent other implementation-defined file types. + + The next three fields shall be three characters each: + + <owner permissions> + + Permissions for the file owner class (see the + Base Definitions volume of IEEE Std 1003.1-2001, + Section 4.4, File Access Permissions). + + <group permissions> + + Permissions for the file group class. + + <other permissions> + + Permissions for the file other class. + + + Each field shall have three character positions: + + If 'r' , the file is readable; if '-' , the file is not + readable. + + If 'w' , the file is writable; if '-' , the file is not + writable. + + The first of the following that applies: + + S If in <owner permissions>, the file is not exe- + cutable and set-user-ID mode is set. If in + <group permissions>, the file is not executable + and set-group-ID mode is set. + + s If in <owner permissions>, the file is executable + and set-user-ID mode is set. If in <group permis- + sions>, the file is executable and set-group-ID + mode is set. + + T If in <other permissions> and the file is a + directory, search permission is not granted to + others, and the restricted deletion flag is set. + + t If in <other permissions> and the file is a + directory, search permission is granted to oth- + ers, and the restricted deletion flag is set. + + x The file is executable or the directory is + searchable. + + - None of the attributes of 'S' , 's' , 'T' , 't' , + or 'x' applies. + + + Implementations may add other characters to this list + for the third character position. Such additions shall, + however, be written in lowercase if the file is exe- + cutable or searchable, and in uppercase if it is not. + + If any of the -l, -g, -n, -o, or -s options is speci- + fied, each list of files within the directory shall be + preceded by a status line indicating the number of file + system blocks occupied by files in the directory in + 512-byte units, rounded up to the next integral number + of units, if necessary. In the POSIX locale, the format + shall be: + + + "total %u\n", <number of units in the directory> + + If more than one directory, or a combination of non- + directory files and directories are written, either as a + result of specifying multiple operands, or the -R + option, each list of files within a directory shall be + preceded by: + + + "\n%s:\n", <directory name> + + If this string is the first thing to be written, the + first <newline> shall not be written. This output shall + precede the number of units in the directory. + + If the -s option is given, each file shall be written + with the number of blocks used by the file. Along with + -C, -1, -m, or -x, the number and a <space> shall pre- + cede the filename; with -g, -l, -n, or -o, they shall + precede each line describing a file. + +STDERR + The standard error shall be used only for diagnostic + messages. + +OUTPUT FILES + None. + +EXTENDED DESCRIPTION + None. + +EXIT STATUS + The following exit values shall be returned: + + 0 Successful completion. + + >0 An error occurred. + + +CONSEQUENCES OF ERRORS + Default. + + The following sections are informative. + +APPLICATION USAGE + Many implementations use the equal sign ( '=' ) to + denote sockets bound to the file system for the -F + option. Similarly, many historical implementations use + the 's' character to denote sockets as the entry type + characters for the -l option. + + It is difficult for an application to use every part of + the file modes field of ls -l in a portable manner. + Certain file types and executable bits are not guaran- + teed to be exactly as shown, as implementations may have + extensions. Applications can use this field to pass + directly to a user printout or prompt, but actions based + on its contents should generally be deferred, instead, + to the test utility. + + The output of ls (with the -l and related options) con- + tains information that logically could be used by utili- + ties such as chmod and touch to restore files to a known + state. However, this information is presented in a for- + mat that cannot be used directly by those utilities or + be easily translated into a format that can be used. A + character has been added to the end of the permissions + string so that applications at least have an indication + that they may be working in an area they do not under- + stand instead of assuming that they can translate the + permissions string into something that can be used. + Future issues or related documents may define one or + more specific characters to be used based on different + standard additional or alternative access control mecha- + nisms. + + As with many of the utilities that deal with filenames, + the output of ls for multiple files or in one of the + long listing formats must be used carefully on systems + where filenames can contain embedded white space. Sys- + tems and system administrators should institute policies + and user training to limit the use of such filenames. + + The number of disk blocks occupied by the file that it + reports varies depending on underlying file system type, + block size units reported, and the method of calculating + the number of blocks. On some file system types, the + number is the actual number of blocks occupied by the + file (counting indirect blocks and ignoring holes in the + file); on others it is calculated based on the file size + (usually making an allowance for indirect blocks, but + ignoring holes). + +EXAMPLES + An example of a small directory tree being fully listed + with ls -laRF a in the POSIX locale: + + + total 11 + drwxr-xr-x 3 hlj prog 64 Jul 4 12:07 ./ + drwxrwxrwx 4 hlj prog 3264 Jul 4 12:09 ../ + drwxr-xr-x 2 hlj prog 48 Jul 4 12:07 b/ + -rwxr--r-- 1 hlj prog 572 Jul 4 12:07 foo* + + + a/b: + total 4 + drwxr-xr-x 2 hlj prog 48 Jul 4 12:07 ./ + drwxr-xr-x 3 hlj prog 64 Jul 4 12:07 ../ + -rw-r--r-- 1 hlj prog 700 Jul 4 12:07 bar + +RATIONALE + Some historical implementations of the ls utility show + all entries in a directory except dot and dot-dot when a + superuser invokes ls without specifying the -a option. + When "normal" users invoke ls without specifying -a, + they should not see information about any files with + names beginning with a period unless they were named as + file operands. + + Implementations are expected to traverse arbitrary + depths when processing the -R option. The only limita- + tion on depth should be based on running out of physical + storage for keeping track of untraversed directories. + + The -1 (one) option was historically found in BSD and + BSD-derived implementations only. It is required in this + volume of IEEE Std 1003.1-2001 so that conforming appli- + cations might ensure that output is one entry per line, + even if the output is to a terminal. + + Generally, this volume of IEEE Std 1003.1-2001 is silent + about what happens when options are given multiple + times. In the cases of -C, -l, and -1, however, it does + specify the results of these overlapping options. Since + ls is one of the most aliased commands, it is important + that the implementation perform intuitively. For exam- + ple, if the alias were: + + + alias ls="ls -C" + + and the user typed ls -1, single-text-column output + should result, not an error. + + The BSD ls provides a -A option (like -a, but dot and + dot-dot are not written out). The small difference from + -a did not seem important enough to require both. + + Implementations may make -q the default for terminals to + prevent trojan horse attacks on terminals with special + escape sequences. This is not required because: + + Some control characters may be useful on some + terminals; for example, a system might write them + as "\001" or "^A" . + + Special behavior for terminals is not relevant to + applications portability. + + An early proposal specified that the optional alternate + access method flag had to be '+' if there was an alter- + nate access method used on the file or <space> if there + was not. This was changed to be <space> if there is not + and a single printable character if there is. This was + done for three reasons: + + There are historical implementations using characters + other than '+' . + + There are implementations that vary this character used + in that position to distinguish between various alter- + nate access methods in use. + + The standard developers did not want to preclude future + specifications that might need a way to specify more + than one alternate access method. + + Nonetheless, implementations providing a single alter- + nate access method are encouraged to use '+' . + + In an early proposal, the units used to specify the num- + ber of blocks occupied by files in a directory in an ls + -l listing were implementation-defined. This was because + BSD systems have historically used 1024-byte units and + System V systems have historically used 512-byte units. + It was pointed out by BSD developers that their system + has used 512-byte units in some places and 1024-byte + units in other places. (System V has consistently used + 512.) Therefore, this volume of IEEE Std 1003.1-2001 + usually specifies 512. Future releases of BSD are + expected to consistently provide 512 bytes as a default + with a way of specifying 1024-byte units where appropri- + ate. + + The <date and time> field in the -l format is specified + only for the POSIX locale. As noted, the format can be + different in other locales. No mechanism for defining + this is present in this volume of IEEE Std 1003.1-2001, + as the appropriate vehicle is a messaging system; that + is, the format should be specified as a "message". + +FUTURE DIRECTIONS + The -s uses implementation-defined units and cannot be + used portably; it may be withdrawn in a future version. + +SEE ALSO + chmod() , find , the System Interfaces volume of + IEEE Std 1003.1-2001, stat(), the Base Definitions vol- + ume of IEEE Std 1003.1-2001, <sys/stat.h> + +COPYRIGHT + Portions of this text are reprinted and reproduced in + electronic form from IEEE Std 1003.1, 2003 Edition, + Standard for Information Technology -- Portable Operat- + ing System Interface (POSIX), The Open Group Base Speci- + fications Issue 6, Copyright (C) 2001-2003 by the Insti- + tute of Electrical and Electronics Engineers, Inc and + The Open Group. In the event of any discrepancy between + this version and the original IEEE and The Open Group + Standard, the original IEEE and The Open Group Standard + is the referee document. The original Standard can be + obtained online at http://www.open- + group.org/unix/online.html . + + + +POSIX 2003 ls(P) |