👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for ls (linux section 1posix)

LS(P)				    POSIX Programmer's Manual				    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 infor-
       mation.	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  specified,  for
       each  operand  that  names a file of type symbolic link to a directory, ls shall write the
       names of files contained within the directory as well as any requested, associated  infor-
       mation.

       If  no  operands  are  specified, ls shall write the contents 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 operands separately according to the collating sequence
       in the current locale.

       The ls utility shall detect infinite loops; that is, entering a previously visited  direc-
       tory  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  posi-
       tion in the hierarchy or terminate.

OPTIONS
       The  ls utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, Sec-
       tion 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 collating sequence. The number of text columns and the column separator charac-
	      ters 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 direc-
	      tory, 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 referenced 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  contents of symbolic links in the long format (see the STDOUT sec-
	      tion).

       -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 directory 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 number (see stat() in the System Inter-
	      faces 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 STDOUT 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 question-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 collating sequence or oldest first.

       -s     Indicate	the  total  number of file system blocks consumed by each file displayed.
	      The block size is implementation-defined.

       -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  diagnos-
	      tic 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-col-
	      umn 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 knowl-
	      edge 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 internationalization variables that  are	unset  or
	      null. (See the Base Definitions volume of IEEE Std 1003.1-2001, Section 8.2, Inter-
	      nationalization Variables for the precedence of internationalization variables used
	      to determine the values of locale categories.)

       LC_ALL If  set  to a non-empty string value, override the values of all the other interna-
	      tionalization variables.

       LC_COLLATE

	      Determine the locale for character collation information in determining  the  path-
	      name 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  argu-
	      ments) and which characters are defined as printable (character class print).

       LC_MESSAGES
	      Determine the locale that should be used to affect the format and contents of diag-
	      nostic messages 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 implementation-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 following format before any other output for the corresponding 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 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 of link>

       where all fields except <pathname of link> shall be for the file resolved  from	the  sym-
       bolic 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 out-
       put 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 modification 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 implementation-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 follow-
       ing 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;  otherwise,	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:

	1. If 'r' , the file is readable; if '-' , the file is not readable.

	2. If 'w' , the file is writable; if '-' , the file is not writable.

	3. The first of the following that applies:

       S
	      If  in <owner permissions>, the file is not executable 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 permissions>, 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 others, 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  executable  or
       searchable, and in uppercase if it is not.

       If  any of the -l,   -g, -n, -o, or -s options is specified, 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 num-
       ber 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 precede  the  file-
       name; 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 guaranteed 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) contains information that logically
       could be used by utilities such as chmod and touch to restore files to a known state. How-
       ever,  this  information  is  presented	in a format 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 indica-
       tion that they may be working in an area they do not understand 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  dif-
       ferent standard additional or alternative access control mechanisms.

       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  file-
       names can contain embedded white space. Systems 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  under-
       lying  file system type, block size units reported, and the method of calculating the num-
       ber of blocks. On some file system types, the number is the actual number of blocks  occu-
       pied  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 "nor-
       mal" 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 limitation on depth should be based on running out of physical storage for  keep-
       ing 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  applications  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 example, 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 alternate 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:

	1. There are historical implementations using characters other than '+' .

	2. There are implementations that vary this character used in that  position  to  distin-
	   guish between various alternate access methods in use.

	3. 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 alternate access method are encouraged  to
       use '+' .

       In  an early proposal, the units used to specify the number 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 appropriate.

       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 volume 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	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					    LS(P)


All times are GMT -4. The time now is 01:24 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password