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

FreeBSD Manual Pages

  
 
  

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

NAME
     ls	-- list	directory contents

SYNOPSIS
     ls	[-1AaCcdFfgHhikLlmnopqRrSsTtux]	[file ...]

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

     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
     displayed first; directory	and non-directory operands are sorted sepa-
     rately and	in lexicographical order.  By default, ls lists	one entry per
     line to standard output; the exceptions are to terminals or when the -C,
     -m, or -x options are specified.

     The options are as	follows:

     -1	     (The numeric digit	"one".)	 Force output to be one	entry per
	     line.  This is the	default	when output is not to a	terminal.

     -A	     List all entries except for `.' and `..'.	Always set for the su-
	     peruser.

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

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

     -c	     Use time file's status was	last changed instead of	last modifica-
	     tion time for sorting (-t)	or printing (-g, -l, or	-n).

     -d	     Directories are listed as plain files (not	searched recursively)
	     and symbolic links	in the argument	list are not indirected
	     through.

     -F	     Display a slash (`/') immediately after each pathname that	is a
	     directory,	an asterisk (`*') after	each that is executable, an at
	     sign (`@')	after each symbolic link, an equal sign	(`=') after
	     each socket, and a	vertical bar (`|') after each that is a	FIFO.

     -f	     Output is not sorted.  This option	implies	-a.

     -g	     List in long format as in -l, except that the owner is not
	     printed.

     -H	     Follow symbolic links specified on	the command line.  This	is the
	     default behaviour when none of the	-d, -F,	or -l options are
	     specified.

     -h	     When used with a long format option, use unit suffixes: Byte,
	     Kilobyte, Megabyte, Gigabyte, Terabyte, Petabyte, and Exabyte in
	     order to reduce the number	of digits to four or fewer using pow-
	     ers of 2 for sizes	(K=1024, M=1048576, etc.).

     -i	     For each file, print its inode number.

     -k	     Modifies the -s option, causing the sizes to be reported in kilo-
	     bytes.  Overrides any value specified by the BLOCKSIZE environ-
	     ment variable.

     -L	     If	argument is a symbolic link, evaluate the file information and
	     file type to be those of the file referenced by the link, and not
	     the link itself; however, ls writes the name of the link itself
	     and not the file referenced by the	link.

     -l	     (The lowercase letter "ell".)  List in long format	(see below).
	     A total sum of all	file sizes is output on	a line before the long
	     listing.  Output is one entry per line.

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

     -n	     List in long format as in -l, but retain user and group IDs in a
	     numeric format.  The output of -gn	and -ng	is identical: a	long
	     listing with numerical group ID, and no numerical user ID.	 The
	     output of -ln and -nl is identical: a long	listing	with numerical
	     group and user ID.

     -o	     Include the file flags in a long format (-g, -l, or -n) output.

     -p	     Display a slash (`/') immediately after each pathname that	is a
	     directory.

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

     -R	     Recursively list subdirectories encountered.

     -r	     Reverse the order of the sort to get reverse lexicographical or-
	     der or the	smallest or oldest entries first.

     -S	     Sort by size, largest file	first.

     -s	     Display the number	of file	system blocks actually used by each
	     file, where partial units are rounded up to the next integer
	     value.  Blocks are	512 bytes unless overridden by the -k flag or
	     BLOCKSIZE environment variable.

     -T	     Display complete time information for the file, including month,
	     day, hour,	minute,	second,	and year.  This	option has no effect
	     unless one	of the long format (-g,	-l, or -n) options is also
	     specified.

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

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

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

     It	is not an error	to specify more	than one of the	following mutually ex-
     clusive options: -1, -C, -g, -l, -m, -n, and -x; and -c, -f, -S, -t, and
     -u.  Where	more than one option is	specified from the same	mutually ex-
     clusive group, the	last option given overrides the	others,	except that -l
     always overrides -g; and -f always	overrides -c, -S, -t, and -u.

   The Long Format
     If	the -g,	-l, or -n options are given, the following information is dis-
     played for	each file: mode, number	of links, owner	(though	not for	-g),
     group, size in bytes, time	of last	modification ("mmm dd HH:MM"), and the
     pathname.	In addition, for each directory	whose contents are displayed,
     the first line displayed is the total number of blocks used by the	files
     in	the directory.	Blocks are 512 bytes unless overridden by the -k op-
     tion or BLOCKSIZE environment variable.

     If	the owner or group name	is not a known user or group name, respec-
     tively, or	the -n option is given,	the numeric ID is displayed.

     If	the file is a character	special	or block special file, the major and
     minor device numbers for the file are displayed in	the size field.

     If	the -T option is given,	the time of last modification is displayed us-
     ing the format "mmm dd HH:MM:SS ccyy".

     If	the file is a symbolic link, the pathname of the linked-to file	is
     preceded by "->".

     The file mode printed under the -g, -l, or	-n options consists of the en-
     try type, owner permissions, group	permissions, and other permissions.
     The entry type character describes	the type of file, as follows:

	   -	 regular file
	   b	 block special file
	   c	 character special file
	   d	 directory
	   l	 symbolic link
	   p	 FIFO
	   s	 socket	link

     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 exe-
			    cutable and	set-user-ID mode is set.  If in	the
			    group permissions, the file	is executable and set-
			    group-ID mode is set.

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

		      -	    The	file is	neither	readable, writable, exe-
			    cutable, nor set-user-ID, nor set-group-ID,	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 neither ex-
			    ecutable nor searchable (see chmod(1) or
			    sticky(8)).

		      t	    The	sticky bit is set (mode	1000), and is search-
			    able or executable (see chmod(1) or	sticky(8)).

     In	addition, if the -o option is specified, the file flags	(see
     chflags(1)) are displayed as comma-separated strings in front of the file
     size, abbreviated as follows:

	   -	     no	flags
	   arch	     archived
	   nodump    do	not dump
	   sappnd    system append-only
	   schg	     system immutable
	   uappnd    user append-only
	   uchg	     user immutable

ENVIRONMENT
     BLOCKSIZE	If the environment variable BLOCKSIZE is set, and the -k op-
		tion is	not specified, the block counts	(see -s) will be dis-
		played in units	of that	size block.

     COLUMNS	If set to a positive integer, output is	formatted to the given
		width in columns.  Otherwise, ls defaults to the terminal
		width, or 80 columns if	the output is not a terminal.

     LC_CTYPE	The character encoding locale(1).  It decides which byte se-
		quences	form characters	and what their display width is.  If
		unset or set to	"C", "POSIX", or an unsupported	value, non-
		ASCII bytes are	replaced by question marks.

     TZ		The time zone 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.

EXAMPLES
     List the contents of the current working directory	in long	format:

	   $ ls	-l

     In	addition to listing the	contents of the	current	working	directory in
     long format, show inode numbers, file flags (see chflags(1)), and suffix
     each filename with	a symbol representing its file type:

	   $ ls	-lioF

     List the files in /var/log, sorting the output such that the most re-
     cently modified entries are printed first:

	   $ ls	-lt /var/log

SEE ALSO
     chflags(1), chmod(1), symlink(7), sticky(8)

STANDARDS
     The ls utility is compliant with the IEEE Std 1003.1-2008 ("POSIX.1")
     specification, except behaviour for the -o	flag differs.

     The flags [-hT], as well as the BLOCKSIZE environment variable, are ex-
     tensions to that specification.

     The flags [-go] are marked	by IEEE	Std 1003.1-2008	("POSIX.1") as being
     an	X/Open System Interfaces option.

     Historically, the -g flag was used	to specify that	the group field	be in-
     cluded in long listings.  The group field is now automatically included
     in	the long listing for files and the meaning of the -g flag has been
     changed in	order to be compatible with the	IEEE Std 1003.1-2008
     ("POSIX.1") specification.

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

BSD			       October 24, 2016				   BSD

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | EXIT STATUS | EXAMPLES | SEE ALSO | STANDARDS | HISTORY

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

home | help