unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

ls(1)                            User Commands                           ls(1)



NAME
       ls - list contents of directory

SYNOPSIS
       /usr/bin/ls [-aAbcCdeEfFghHilLmnopqrRstux1@] [file...]

       /usr/xpg4/bin/ls [-aAbcCdeEfFghHilLmnopqrRstux1@] [file...]

       /usr/xpg6/bin/ls [-aAbcCdeEfFghHilLmnopqrRstux1@] [file...]

DESCRIPTION
       For  each file that is a directory, ls lists the contents of the direc-
       tory. For each file that is an ordinary file, ls repeats its  name  and
       any other information requested. The output is sorted alphabetically by
       default. When no argument is given, the current  directory  is  listed.
       When several arguments are given, the arguments are first sorted appro-
       priately, but file arguments appear before directories and  their  con-
       tents.

       There  are  three  major listing formats. The default format for output
       directed to a terminal is multi-column with  entries  sorted  down  the
       columns.  The  -1  option  allows  single  column output and -m enables
       stream output format. In order to determine output formats for the  -C,
       -x, and -m options, ls uses an environment variable, COLUMNS, to deter-
       mine the number of character positions available on one output line. If
       this variable is not set, the terminfo(4) database is used to determine
       the number of columns, based on the environment variable, TERM. If this
       information cannot be obtained, 80 columns are assumed.

       The  mode  printed  under the -l option consists of ten characters. The
       first character can be one of the following:

       d        The entry is a directory.



       D        The entry is a door.



       l        The entry is a symbolic link.



       b        The entry is a block special file.



       c        The entry is a character special file.



       p        The entry is a FIFO (or "named pipe") special file.



       P        The entry is an event port.



       s        The entry is an AF_UNIX address family socket.



       -        The entry is an ordinary file.



       The next 9 characters are interpreted as three sets of three bits each.
       The  first  set  refers to the owner's permissions; the next to permis-
       sions of others in the user-group of the file; and the last to all oth-
       ers. Within each set, the three characters indicate permission to read,
       to write, and to execute the file as a  program,  respectively.  For  a
       directory,  ``execute'' permission is interpreted to mean permission to
       search the directory for a specified file. The character after  permis-
       sions  is  ACL  indication. A plus sign is displayed if there is an ACL
       associated with the file. Nothing is displayed if there are  just  per-
       missions.

       ls  -l  (the  long  list)  prints  its  output as follows for the POSIX
       locale:

       -rwxrwxrwx+ 1 smith dev   10876  May 16 9:42 part2

       Reading from right to left, you see that the  current  directory  holds
       one  file,  named  part2. Next, the last time that file's contents were
       modified was 9:42 A.M. on May 16. The file contains 10,876  characters,
       or  bytes. The owner of the file, or the user, belongs to the group dev
       (perhaps indicating ``development''), and his  or  her  login  name  is
       smith.  The  number,  in  this case 1, indicates the number of links to
       file part2 (see cp(1)). The plus sign indicates that there  is  an  ACL
       associated  with  the  file. Note: If the -@ option has been specified,
       the presence of extended attributes supersede the presence  of  an  ACL
       and  the plus sign is replaced with an 'at' sign (@). Finally, the dash
       and letters tell you that user, group, and others have  permissions  to
       read, write, and execute part2.

       The  execute  (x) symbol here occupies the third position of the three-
       character sequence. A - in the third position would  have  indicated  a
       denial of execution permissions.

       The permissions are indicated as follows:

       r        The file is readable.



       w        The file is writable.



       x        The file is executable.



       -        The indicated permission is not granted.



       s        The set-user-ID or set-group-ID bit is on, and the correspond-
                ing user or group execution bit is also on.



       S         Undefined bit-state (the set-user-ID or set-group-id  bit  is
                on and the user or group execution bit is off). For group per-
                missions, this applies only to non-regular files.



       t        The 1000 (octal) bit, or sticky bit, is on (see chmod(1)), and
                execution is on.



       T        The  1000  bit  is  turned on, and execution is off (undefined
                bit-state).



   /usr/bin/ls
       l         Mandatory locking occurs during access (on  a  regular  file,
                the  set-group-ID  bit  is  on  and the group execution bit is
                off).



   /usr/xpg4/bin/ls and /usr/xpg6/bin/ls
       L         Mandatory locking occurs during access (on  a  regular  file,
                the  set-group-ID  bit  is  on  and the group execution bit is
                off).



       For user and group permissions, the third position is  sometimes  occu-
       pied  by  a  character  other  than x or -. s or S also can occupy this
       position, referring to the state of the set-ID bit, whether it  be  the
       user's  or  the  group's. The ability to assume the same ID as the user
       during execution is, for example, used during login when you  begin  as
       root but need to assume the identity of the user you login as.

       In  the  case  of  the  sequence of group permissions, l can occupy the
       third position. l refers to mandatory file  and  record  locking.  This
       permission  describes a file's ability to allow other files to lock its
       reading or writing permissions during access.

       For others permissions, the third position can be occupied by t  or  T.
       These refer to the state of the sticky bit and execution permissions.

OPTIONS
       The following options are supported:

   /usr/bin/ls, /usr/xpg4/bin/ls, and /usr/xpg6/bin/ls
       The following options are supported for all three versions:

       -a       Lists  all entries, including those that begin with a dot (.),
                which are normally not listed.



       -A       Lists all entries, including those that begin with a dot  (.),
                with the exception of the working directory (.) and the parent
                directory (..).



       -b       Forces printing of non-printable characters to be in the octal
                \ddd notation.



       -c       Uses  time  of  last modification of the i-node (file created,
                mode changed, and so forth) for sorting (-t) or  printing  (-l
                or -n).



       -C       Multi-column output with entries sorted down the columns. This
                is the default output format.



       -d       If an argument is a directory, lists only its  name  (not  its
                contents).  Often  used  with -l to get the status of a direc-
                tory.



       -e        The same as -l, except displays time to the second, and  with
                one  format  for all files regardless of age: mmm dd hhh:mm:ss
                yyyy.



       -E       The same as -l, except displays time  to  the  nanosecond  and
                with  one  format  for all files regardless of age: yyyy-mm-dd
                hh:mm:ss.nnnnnnnnn (ISO 8601 format).



       -f       Forces each argument to be interpreted as a directory and list
                the name found in each slot. This option turns off -l, -t, -s,
                and -r, and turns on -a. The  order  is  the  order  in  which
                entries appear in the directory.



       -g       The same as -l, except that the owner is not printed.



       -h       All  sizes are scaled to a human readable format, for example,
                14K, 234M, 2.7G, or 3.0T.  Scaling  is  done  by  repetitively
                dividing by 1024.



       -H       If  a  symbolic  link  referencing a file of type directory is
                specified on the command line, this option lists the directory
                that the link references rather than the link itself.



       -i       For each file, prints the i-node number in the first column of
                the report.



       -l       Lists in long format, giving mode, ACL indication,  number  of
                links, owner, group, size in bytes, and time of last modifica-
                tion for each file (see above). If the file is a special file,
                the  size  field  instead  contains the major and minor device
                numbers. If the time of last modification is greater than  six
                months  ago,  it  is shown in the format `month date year' for
                the POSIX locale. When the LC_TIME locale category is not  set
                to  the POSIX locale, a different format of the time field can
                be used. Files modified within six  months  show  `month  date
                time'. If the file is a symbolic link, the filename is printed
                followed by "->>" and the path name of the referenced file.



       -L       If an argument is a symbolic link, this option  evaluates  the
                file  information  and file type of the file or directory that
                the link references, rather than those  of  the  link  itself.
                However,  the  name  of the link is displayed, rather than the
                referenced file or directory.



       -m       Streams output format. Files are listed across the page, sepa-
                rated by commas.



       -n       The  same  as  -l, except that the owner's UID and group's GID
                numbers are printed,  rather  than  the  associated  character
                strings.



       -o       The same as -l, except that the group is not printed.



       -p       Puts  a  slash (/) after each filename if the file is a direc-
                tory.



       -q       Forces printing of non-printable characters in file  names  as
                the character question mark (?).



       -r       Reverses the order of sort to get reverse alphabetic or oldest
                first as appropriate.



       -R       Recursively lists subdirectories encountered.



       -s       Gives size in blocks,  including  indirect  blocks,  for  each
                entry.



       -t       Sorts  by  time  stamp  (latest first) instead of by name. The
                default is the last modification time. (See -u and -c.)



       -u       Uses time of last access  instead  of  last  modification  for
                sorting (with the -t option) or printing (with the -l option).



       -@       The  same  as  -l,  except that extended attribute information
                supersede ACL information. An @ is displayed  after  the  file
                permission bits for files that have extended attributes.



       -x       Multi-column  output  with  entries  sorted across rather than
                down the page.



       -1       Prints one entry per line of output.



   /usr/bin/ls
       -F       Marks directories with a trailing  slash  (/),  doors  with  a
                trailing greater-than sign (>>), executable files with a trail-
                ing asterisk (*), FIFOs with a trailing vertical bar (|), sym-
                bolic links with a trailing "at" sign (@), and AF_UNIX address
                family sockets with a trailing equals sign (=).  Follows  sym-
                links named as operands.



       Specifying  more  than  one  of  the  options in the following mutually
       exclusive pairs is not considered an error: -C and -l (ell), -m and  -l
       (ell),  -x and -l (ell), -@ and -l (ell). The -l (ell) option overrides
       the other option specified in each pair.

       Specifying more than one of  the  options  in  the  following  mutually
       exclusive pairs is not considered an error: -C and -1 (one), -H and -L,
       -c and -u, and -e and -E. The last option specified in  each  of  these
       pairs determines the output format.

   /usr/xpg4/bin/ls
       -F       Marks  directories  with  a  trailing  slash (/), doors with a
                trailing greater-than sign (>>), executable files with a trail-
                ing asterisk (*), FIFOs with a trailing vertical bar (|), sym-
                bolic links with a trailing "at" sign (@), and AF_UNIX address
                family  sockets  with a trailing equals sign (=). Follows sym-
                links named as operands.



       Specifying more than one of  the  options  in  the  following  mutually
       exclusive  pairs is not considered an error: -C and -l (ell), -m and -l
       (ell), -x and -l (ell), -@ and -l (ell), -C and -1 (one), -H and -L, -c
       and  -u,  and  -e and -E. The last option specified in each pair deter-
       mines the output format.

   /usr/xpg6/bin/ls
       -F       Marks directories with a trailing  slash  (/),  doors  with  a
                trailing greater-than sign (>>), executable files with a trail-
                ing asterisk (*), FIFOs with a trailing vertical bar (|), sym-
                bolic links with a trailing "at" sign (@), and AF_UNIX address
                family sockets with a trailing equals sign (=). Does not  fol-
                low  symlinks  named as operands unless the -H or -L option is
                specified.



       Specifying more than one of  the  options  in  the  following  mutually
       exclusive  pairs is not considered an error: -C and -l (ell), -m and -l
       (ell), -x and -l (ell), -@ and -l (ell), -C and -1 (one), -H and -L, -c
       and  -u,  and  -e and -E. The last option specified in each pair deter-
       mines the output format.

OPERANDS
       The following operand is supported:

       file     A path name of a file to be written. If the file specified  is
                not found, a diagnostic message is output on standard error.



USAGE
       See largefile(5) for the description of the behavior of ls when encoun-
       tering files greater than or equal to 2 Gbyte ( 2**31 bytes).

EXAMPLES
       Example 1: Viewing File Permissions

       An example of a file's permissions is:

       -rwxr--r--

       This describes a file that is readable, writable, and executable by the
       user and readable by the group and others.

       Another example of a file's permissions is:

       -rwsr-xr-x

       This describes a file that is readable, writable, and executable by the
       user, readable and executable by the group and others, and  allows  its
       user-ID  to be assumed, during execution, by the user presently execut-
       ing it.

       Another example of a file's permissions is:

       -rw-rwl---

       This describes a file that is readable and writable only  by  the  user
       and the group and can be locked during access.

       Example 2: Printing the Names of All Files

       This  command  prints  the names of all files in the current directory,
       including those that begin with a dot (.), which normally do not print:

       example% ls -a

       Example 3: Providing File Information

       Another example of a command line is:

       example% ls -aisn

       This command provides information on all files,  including  those  that
       begin  with  a  dot (a), the i-number--the memory address of the i-node
       associated with the file--printed in the left-hand column (i); the size
       (in  blocks) of the files, printed in the column to the right of the i-
       numbers (s); finally, the report is displayed in the numeric version of
       the long list, printing the UID (instead of user name) and GID (instead
       of group name) numbers associated with the files.

       When the sizes of the files in a directory are listed, a total count of
       blocks, including indirect blocks, is printed.

ENVIRONMENT VARIABLES
       See  environ(5) for descriptions of the following environment variables
       that affect the execution of ls: LANG,  LC_ALL,  LC_COLLATE,  LC_CTYPE,
       LC_TIME, LC_MESSAGES, NLSPATH, and TZ.

       COLUMNS         Determines  the  user's preferred column position width
                       for writing multiple text-column output. If this  vari-
                       able  contains a string representing a decimal integer,
                       the ls utility calculates how many path name text  col-
                       umns  to write (see -C) based on the width provided. If
                       COLUMNS is not set or is invalid, 80 is used. The  col-
                       umn  width  chosen  to  write the names of files in any
                       given directory is constant.  File  names  are  not  be
                       truncated to fit into the multiple text-column output.



EXIT STATUS
       0        All information was written successfully.



       >>0       An error occurred.



FILES
       /etc/group                      group IDs for ls -l and ls -g



       /etc/passwd                     user IDs for ls -l and ls -o



       /usr/share/lib/terminfo/?/*     terminal information database



ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

   /usr/bin/ls
       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE  TYPEATTRIBUTE   VALUE   AvailabilitySUNWcsu
       CSIEnabled Interface StabilityStable


   /usr/xpg4/bin/ls
       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE  TYPEATTRIBUTE  VALUE   AvailabilitySUNWxcu4
       CSIEnabled Interface StabilityStandard


   /usr/xpg6/bin/ls
       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE  TYPEATTRIBUTE  VALUE   AvailabilitySUNWxcu6
       CSIEnabled Interface StabilityStandard


SEE ALSO
       chmod(1),  cp(1),  setfacl(1),  terminfo(4), attributes(5), environ(5),
       fsattr(5), largefile(5), standards(5)

NOTES
       Unprintable characters in file names can confuse  the  columnar  output
       options.

       The  total  block  count is incorrect if there are hard links among the
       files.

       The sort order of ls output is affected by the locale and can be  over-
       ridden  by the LC_COLLATE environment variable. For example, if LC_COL-
       LATE equals C, dot files appear first, followed by names beginning with
       upper-case  letters,  then  followed by names beginning with lower-case
       letters. But if LC_COLLATE equals en_US.ISO8859-1, then leading dots as
       well as case are ignored in determining the sort order.



SunOS 5.10                        31 Aug 2004                            ls(1)