home | help
LS(1)			     General Commands Manual			   LS(1)

NAME
     ls -- list directory contents

SYNOPSIS
     ls [-ABCFGHILPRSTWZabcdfghiklmnopqrstuwx1] [file ...]

DESCRIPTION
     For  each operand that names a file of a type other than directory, ls dis-
     plays its name as well as any requested, associated information.  For  each
     operand that names a file of type directory, ls displays the names of files
     contained	within	that directory, as well as any requested, associated in-
     formation.

     If no operands are given, the contents of the current  directory  are  dis-
     played.  If more than one operand is given, non-directory operands are dis-
     played  first;  directory	and non-directory operands are sorted separately
     and in lexicographical order.

     The following options are available:

     -A      List all entries except for . and ...  Automatically  set	for  the
	     super-user unless -I is specified.

     -B      Force  printing of non-printable characters (as defined by ctype(3)
	     and current locale settings) in file names as \xxx,  where  xxx  is
	     the numeric value of the character in octal.

     -C      Force  multi-column output; this is the default when output is to a
	     terminal.

     -F      Display a slash (`/') immediately after each pathname that is a di-
	     rectory, an asterisk (`*') after each that  is  executable,  an  at
	     sign  (`@')  after  each  symbolic link, an equals sign (`=') after
	     each socket, a percent sign (`%') after each whiteout, and a verti-
	     cal bar (`|') after each that is a FIFO.

     -G      Enable colorized output.  This option  is	equivalent  to	defining
	     CLICOLOR in the environment.  (See below.)

     -H      Symbolic  links  on  the command line are followed.  This option is
	     assumed if none of the -F, -d, or -l options are specified.

     -I      Prevent -A from being automatically set for the super-user.

     -L      If argument is a symbolic link, list the file or directory the link
	     references rather than the link itself.  This option cancels the -P
	     option.

     -P      If argument is a symbolic link, list the link  itself  rather  than
	     the  object the link references.  This option cancels the -H and -L
	     options.

     -R      Recursively list subdirectories encountered.

     -S      Sort by size (largest file first) before sorting  the  operands  in
	     lexicographical order.

     -T      When used with the -l (lowercase letter "ell") option, display com-
	     plete  time  information  for the file, including month, day, hour,
	     minute, second, and year.

     -W      Display whiteouts when scanning directories.

     -Z      Display each file's MAC label; see maclabel(7).

     -a      Include directory entries whose names begin with a dot (.).

     -b      As -B, but use C escape codes whenever possible.

     -c      Use time when file status was last changed for sorting or printing.

     -d      Directories are listed as plain files (not searched recursively).

     -f      Output is not sorted.

     -g      This option is deprecated and is only available  for  compatibility
	     with 4.3BSD; it was used to display the group name in the long (-l)
	     format output.

     -h      When  used  with  the -l option, use unit suffixes: Byte, Kilobyte,
	     Megabyte, Gigabyte, Terabyte and Petabyte in order  to  reduce  the
	     number of digits to four or fewer using base 2 for sizes.

     -i      For each file, print the file's file serial number (inode number).

     -k      This  has the same effect as setting environment variable BLOCKSIZE
	     to 1024, except that it also nullifies any -h options to its left.

     -l      (The lowercase letter "ell".)  List files in the  long  format,  as
	     described in the "The Long Format" subsection below.

     -m      Stream output format; list files across the page, separated by com-
	     mas.

     -n      Display  user and group IDs numerically rather than converting to a
	     user or group name in a long (-l) output.

     -o      Include the file flags in a long (-l) output.

     -p      Write a slash (`/') after each filename if that file  is  a  direc-
	     tory.

     -q      Force printing of non-graphic characters in file names as the char-
	     acter `?'; this is the default when output is to a terminal.

     -r      Reverse the order of the sort.

     -s      Display  the number of blocks used in the file system by each file.
	     Block sizes and directory totals are handled as described	in  "The
	     Long  Format"  subsection	below, except (if the long format is not
	     also requested) the directory totals are not output when the output
	     is in a single column, even if multi-column output is requested.

     -t      Sort by time modified (most recently modified first) before sorting
	     the operands in lexicographical order.

     -u      Use time of last access, instead of last modification of  the  file
	     for sorting (-t) or printing (-l).

     -w      Force  raw  printing  of non-printable characters.  This is the de-
	     fault when output is not to a terminal.

     -x      The same as -C, except that the  multi-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.
	     This is the default when output is not to a terminal.

     The -1, -C, -x, and -l options all override each other; the last one speci-
     fied determines the format used.

     The -c and -u options override each other; the last  one  specified  deter-
     mines the file time used.

     The -B, -b, -w, and -q options all override each other; the last one speci-
     fied determines the format used for non-printable characters.

     The  -H,  -L  and	-P  options all override each other (either partially or
     fully); they are applied in the order specified.

     By default, ls lists one entry per line to standard output; the  exceptions
     are to terminals or when the -C or -x options are specified.

     File  information is displayed with one or more <blank>s separating the in-
     formation associated with the -i, -s, and -l options.

   The Long Format
     If the -l option is given, the following information is displayed for  each
     file: file mode, number of links, owner name, group name, MAC label, number
     of  bytes	in the file, abbreviated month, day-of-month file was last modi-
     fied, hour file last modified, minute file last modified, and the pathname.

     If the modification time of the file is more than 6 months in the	past  or
     future, then the year of the last modification is displayed in place of the
     hour and minute fields.

     If  the  owner or group names are not a known user or group name, or the -n
     option is given, the numeric ID's are displayed.

     If the file is a character special or block special file, the major and mi-
     nor device numbers for the file are displayed in the size	field.	 If  the
     file  is  a symbolic link the pathname of the linked-to file is preceded by
     "->".

     The listing of a directory's contents is preceded by a labeled total number
     of blocks used in the file system by the files which are listed as the  di-
     rectory's	contents  (which may or may not include . and .. and other files
     which start with a dot, depending on other options).

     The default block size is 512 bytes.  The block size may be set with option
     -k or environment variable BLOCKSIZE.  Numbers of blocks in the output will
     have been rounded up so the numbers of bytes is at least as many as used by
     the corresponding file system blocks (which might have a different size).

     The file mode printed under the -l option consists of the	entry  type  and
     the  permissions.	 The entry type character describes the type of file, as
     follows:

	   b	 Block special file.
	   c	 Character special file.
	   d	 Directory.
	   l	 Symbolic link.
	   s	 Socket link.
	   p	 FIFO.
	   -	 Regular file.

     The next three fields are three characters each: owner  permissions,  group
     permissions,  and	other permissions.  Each field has three character posi-
     tions:

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

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

	   3.	The first of the following that applies:

		      S     If in the owner permissions, the file  is  not  exe-
			    cutable  and  set-user-ID  mode  is  set.  If in the
			    group permissions, the file is  not  executable  and
			    set-group-ID mode is set.

		      s     If	in the owner permissions, the file is executable
			    and set-user-ID mode is set.  If in the  group  per-
			    missions,  the  file  is  executable and setgroup-ID
			    mode is set.

		      x     The file is executable or the directory  is  search-
			    able.

		      -     The  file is neither readable, writable, executable,
			    nor set-user-ID nor set-group-ID mode,  nor  sticky.
			    (See below.)

		These  next  two  apply  only to the third character in the last
		group (other permissions).

		      T     The sticky bit is set (mode 1000), but  not  execute
			    or search permission.  (See chmod(1) or sticky(8).)

		      t     The sticky bit is set (mode 1000), and is searchable
			    or executable.  (See chmod(1) or sticky(8).)

     The next field contains a plus (`+') character if the file has an ACL, or a
     space  (`	') if it does not.  The ls utility does not show the actual ACL;
     use getfacl(1) to do this.

ENVIRONMENT
     The following environment variables affect the execution of ls:

     BLOCKSIZE	     If this is set, its value, rounded up to 512 or down  to  a
		     multiple of 512, will be used as the block size in bytes by
		     the  -l  and  -s options.	See "The Long Format" subsection
		     for more information.

     CLICOLOR	     Use ANSI color sequences to distinguish  file  types.   See
		     LSCOLORS below.  In addition to the file types mentioned in
		     the  -F option some extra attributes (setuid bit set, etc.)
		     are also displayed.  The colorization  is	dependent  on  a
		     terminal type with the proper termcap(5) capabilities.  The
		     default  "cons25"	console has the proper capabilities, but
		     to display the colors in an xterm(1), for example, the TERM
		     variable must be  set  to	"xterm-color".	 Other	terminal
		     types  may  require  similar  adjustments.  Colorization is
		     silently disabled if the output is not directed to a termi-
		     nal unless the CLICOLOR_FORCE variable is defined.

     CLICOLOR_FORCE  Color sequences are normally disabled if the output is  not
		     directed  to a terminal.  This can be overridden by setting
		     this flag.  The TERM variable still needs	to  reference  a
		     color capable terminal however otherwise it is not possible
		     to determine which color sequences to use.

     COLUMNS	     If  this  variable contains a string representing a decimal
		     integer, it is used as the column position width  for  dis-
		     playing multiple-text-column output.  The ls utility calcu-
		     lates  how  many  pathname text columns to display based on
		     the width provided.  (See -C and -x.)

     LANG	     The locale to use when determining the  order  of	day  and
		     month  in	the  long  -l format output.  See environ(7) for
		     more information.

     LSCOLORS	     The value of this variable describes what color to use  for
		     which  attribute  when  colors  are  enabled with CLICOLOR.
		     This string is a concatenation of pairs of the  format  fb,
		     where  f  is  the	foreground color and b is the background
		     color.

		     The color designators are as follows:

			   a	 black
			   b	 red
			   c	 green
			   d	 brown
			   e	 blue
			   f	 magenta
			   g	 cyan
			   h	 light grey
			   A	 bold black, usually shows up as dark grey
			   B	 bold red
			   C	 bold green
			   D	 bold brown, usually shows up as yellow
			   E	 bold blue
			   F	 bold magenta
			   G	 bold cyan
			   H	 bold light grey; looks like bright white
			   x	 default foreground or background

		     Note that the above are standard ANSI colors.   The  actual
		     display  may  differ depending on the color capabilities of
		     the terminal in use.

		     The order of the attributes are as follows:

			   1.	directory
			   2.	symbolic link
			   3.	socket
			   4.	pipe
			   5.	executable
			   6.	block special
			   7.	character special
			   8.	executable with setuid bit set
			   9.	executable with setgid bit set
			   10.	directory writable to others, with sticky bit
			   11.	directory writable to others, without sticky bit

		     The default is "exfxcxdxbxegedabagacad", i.e.,  blue  fore-
		     ground  and  default  background  for  regular directories,
		     black foreground and red background for setuid executables,
		     etc.

     LS_COLWIDTHS    If this variable is set, it is considered to be a colon-de-
		     limited list of minimum column  widths.   Unreasonable  and
		     insufficient  widths are ignored (thus zero signifies a dy-
		     namically sized column).  Not all columns	have  changeable
		     widths.  The fields are, in order: inode, block count, num-
		     ber of links, user name, group name, flags, file size, file
		     name.

     TERM	     The  CLICOLOR functionality depends on a terminal type with
		     color capabilities.

     TZ 	     The timezone to use when displaying dates.  See  environ(7)
		     for more information.

EXIT STATUS
     The ls utility exits 0 on success, and >0 if an error occurs.

COMPATIBILITY
     The group field is now automatically included in the long listing for files
     in  order	to be compatible with the IEEE Std 1003.2 ("POSIX.2") specifica-
     tion.

SEE ALSO
     chflags(1), chmod(1), getfacl(1),	sort(1),  xterm(1),  termcap(5),  macla-
     bel(7), symlink(7), getfmac(8), sticky(8)

STANDARDS
     With the exception of options -I, -g, -n and -o, the ls utility conforms to
     IEEE Std 1003.1-2001 ("POSIX.1").

     The  ACL  support is compatible with IEEE Std 1003.2c ("POSIX.2c") Draft 17
     (withdrawn).

HISTORY
     An ls command appeared in Version 1 AT&T UNIX.

BUGS
     To maintain backward compatibility, the relationships between the many  op-
     tions are quite complex.

     The  exception  mentioned	in  the -s option description might be a feature
     that was based on the fact that single-column output usually goes to  some-
     thing other than a terminal.  It is debatable whether this is a design bug.

FreeBSD 6.1			November 16, 2005			   LS(1)

home | help