Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ls(1)				 User Commands				 ls(1)

NAME
       ls - list contents of directory

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

       /usr/xpg4/bin/ls	[-aAbcCdfFghilLmnopqrRstux1@] [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 may 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.

       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 di-
       rectory,	 ``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 lo-
       cale:

       -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 will	supersede the presence	of  an
       ACL  and	the plus sign will be replaced with an 'at' sign (@). Finally,
       the dash	and letters tell you that user,	group, and others have permis-
       sions 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 corresponding
	     user or group execution bit is also on.

       S     Undefined bit-state (the set-user-ID bit is on and	the user  exe-
	     cution bit	is off).

       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 (the set-group-ID	bit is
	     on	and the	group execution	bit is off).

   /usr/xpg4/bin/ls
       L     Mandatory locking occurs during access (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	also may 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  exe-
       cution  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  may  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 may	be occupied by t or T.
       These refer to the state	of the sticky bit and execution	permissions.

OPTIONS
       The following options are supported:

       -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  con-
	     tents). Often used	with -l	to get the status of a directory.

       -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.

       -F    Marks directories with a trailing slash (/), doors	with a	trail-
	     ing  greater-than	sign (>), executable files with	a trailing as-
	     terisk (*), FIFOs with a  trailing	 vertical  bar	(|),  symbolic
	     links  with  a trailing 'at' sign (@), and	AF_UNIX	address	family
	     sockets with a trailing equals sign (=).

       -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	divid-
	     ing by 1024.

       -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 modification
	     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 may be used. Files  modified
	     within  six  months show `month date time'. If the	file is	a sym-
	     bolic link, the filename is printed followed by "->" and the path
	     name of the referenced file.

       -L    If	 an  argument  is a symbolic link, lists the file or directory
	     the link references rather	than the link itself.

       -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 num-
	     bers 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 directory.

       -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  de-
	     fault 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  will
	     supersede	ACL information. An @ is displayed after the file per-
	     mission 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
       Specifying  more	 than one of the options in the	following mutually ex-
       clusive pairs is	not considered an error: -C and	-l (ell),  -m  and  -l
       (ell),  -x  and	-l (ell), -@ and -l (ell). The -l option overrides the
       other option specified in each pair.

   /usr/xpg4/bin/ls
       Specifying more than one	of the options in the following	 mutually  ex-
       clusive	pairs  is  not considered an error: -C and -l (ell), -m	and -l
       (ell), -x and -l	(ell), -@ and -l (ell).	The last option	 specified  in
       each pair determines 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 will be 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: 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:	LC_COLLATE, LC_CTYPE, LC_TIME, LC_MES-
       SAGES, NLSPATH, and TZ.

       COLUMNS
	     Determines	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  calculates  how
	     many  path	name text columns to write (see	-C) based on the width
	     provided. If COLUMNS is not set or	is invalid, 80	is  used.  The
	     column  width chosen to write the names of	files in any given di-
	     rectory will be constant. File names will 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
       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Stable			   |
       +-----------------------------+-----------------------------+

   /usr/xpg4/bin/ls
       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWxcu4			   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+

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

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

       The  total  block count will be 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.9			  19 Nov 2001				 ls(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | USAGE | EXAMPLES | ENVIRONMENT VARIABLES | EXIT STATUS | FILES | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ls&sektion=1&manpath=SunOS+5.9>

home | help