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

FreeBSD Manual Pages

  
 
  

home | help
ls(1)									 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...]

       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.

       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 hh: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:2000 format).

		In addition, this option displays the offset from UTC  in  ISO
		8601:2000 standard format (+hhmm or -hhmm) or no characters if
		the offset is indeterminable. The offset reflects  the	appro-
		priate	standard  or  alternate	 offset	in force at the	file's
		displayed date and time, under the current timezone.

       -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	Indicate the total number of file system  blocks  consumed  by
		each file displayed.

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

       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.

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

       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.

       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.

       0	All information	was written successfully.

       >0	An error occurred.

       /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

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

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

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

       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.

				  6 May	2005				 ls(1)

NAME | SYNOPSIS

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

home | help