1.\" Copyright (c) 1980, 1990, 1991, 1993, 1994
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the Institute of Electrical and Electronics Engineers, Inc.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\" must display the following acknowledgement:
17.\" This product includes software developed by the University of
18.\" California, Berkeley and its contributors.
19.\" 4. Neither the name of the University nor the names of its contributors
20.\" may be used to endorse or promote products derived from this software
21.\" without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\" @(#)ls.1 8.7 (Berkeley) 7/29/94
36.\" $Id: ls.1,v 1.17 1998/04/21 22:01:58 des Exp $
37.\"
38.Dd July 29, 1994
39.Dt LS 1
40.Os
41.Sh NAME
42.Nm ls
43.Nd list directory contents
44.Sh SYNOPSIS
45.Nm ls
46.Op Fl ?ABCFLRTWabcdfgikloqrstu1
47.Op Ar file ...
48.Sh DESCRIPTION
49For each operand that names a
50.Ar file
51of a type other than
52directory,
53.Nm ls
54displays its name as well as any requested,
55associated information.
56For each operand that names a
57.Ar file
58of type directory,
59.Nm ls
60displays the names of files contained
61within that directory, as well as any requested, associated
62information.
63.Pp
64If no operands are given, the contents of the current
65directory are displayed.
66If more than one operand is given,
67non-directory operands are displayed first; directory
68and non-directory operands are sorted separately and in
69lexicographical order.
70.Pp
71The following options are available:
72.Bl -tag -width indent
73.It Fl ?
74Displays a short list of valid options.
75.It Fl A
76List all entries except for
77.Ql \&.
78and
79.Ql \&.. .
80Always set for the super-user.
81.It Fl B
82Force printing of non-graphic characters in file names as \\xxx,
83where xxx is the numeric value of the character in octal.
84.It Fl C
85Force multi-column output; this is the default when output is to a terminal.
86.It Fl F
87Display a slash (/) immediately after each pathname
88that is a directory, an asterisk (*) after each that is
89executable,
90an at sign (@) after each symbolic link,
91an equals sign (=) after each socket,
92a percent sign (%) after each whiteout,
93and a vertical bar (|) after each that is a
94.Tn FIFO .
95.It Fl L
96If argument is a symbolic link, list the file or directory the link references
97rather than the link itself.
98.It Fl R
99Recursively list subdirectories encountered.
100.It Fl T
101Display complete time information for the file, including
102month, day, hour, minute, second, and year.
103.It Fl W
104Display whiteouts when scanning directories.
105.It Fl a
106Include directory entries whose names begin with a
107dot (.).
108.It Fl b
109As
110.Fl B ,
111but use C escape codes whenever possible.
112.It Fl c
113Use time when file status was last changed for sorting or printing.
114.It Fl d
115Directories are listed as plain files (not searched recursively) and
116symbolic links in the argument list are not indirected through.
117.It Fl f
118Output is not sorted.
119.It Fl g
120This option is deprecated and is only available for compatibility
121with
122.Bx 4.3 ;
123it was used to display the group name in the long
124.Pq Fl l
125format output.
126.It Fl i
127For each file, print the file's file serial number (inode number).
128.It Fl k
129If the
130.Fl s
131option is specified, print the file size allocation in kilobytes,
132not blocks.
133.It Fl l
134(The lowercase letter ``ell.'') List in long format. (See below.)
135If the output is to a terminal, a total sum for all the file
136sizes is output on a line before the long listing.
137.It Fl o
138Include the file flags in a long
139.Pq Fl l
140output.
141.It Fl q
142Force printing of non-graphic characters in file names as
143the character `?'; this is the default when output is to a terminal.
144.It Fl r
145Reverse the order of the sort to get reverse
146lexicographical order or the oldest entries first.
147.It Fl s
148Display the number of file system blocks actually used by each file, in units
149of 512 bytes, where partial units are rounded up to the next integer value.
150If the output is to a terminal, a total sum for all the file
151sizes is output on a line before the listing.
152.It Fl t
153Sort by time modified (most recently modified
154first) before sorting the operands by lexicographical
155order.
156.It Fl u
157Use time of last access,
158instead of last modification
159of the file for sorting
160.Pq Fl t
161or printing
162.Pq Fl l .
163.It Fl \&1
164(The numeric digit ``one.'') Force output to be
165one entry per line.
166This is the default when
167output is not to a terminal.
168.El
169.Pp
170The
171.Fl 1 ,
172.Fl C ,
173and
174.Fl l
175options all override each other; the last one specified determines
176the format used.
177.Pp
178The
179.Fl c ,
180and
181.Fl u
182options override each other; the last one specified determines
183the file time used.
184.Pp
185By default,
186.Nm ls
187lists one entry per line to standard
188output; the exceptions are to terminals or when the
189.Fl C
190option is specified.
191.Pp
192File information is displayed with one or more
193<blank>s separating the information associated with the
194.Fl i ,
195.Fl s ,
196and
197.Fl l
198options.
199.Ss The Long Format
200If the
201.Fl l
202option is given, the following information
203is displayed for each file:
204file mode,
205number of links, owner name, group name,
206number of bytes in the file, abbreviated
207month, day-of-month file was last modified,
208hour file last modified, minute file last
209modified, and the pathname.
210In addition, for each directory whose contents are displayed, the total
211number of 512-byte blocks used by the files in the directory is displayed
212on a line by itself immediately before the information for the files in the
213directory.
214.Pp
215If the modification time of the file is more than 6 months
216in the past or future, then the year of the last modification
217is displayed in place of the hour and minute fields.
218.Pp
219If the owner or group names are not a known user or group name
220the numeric ID's are displayed.
221.Pp
222If the file is a character special or block special file,
223the major and minor device numbers for the file are displayed
224in the size field. If the file is a symbolic link the pathname of the
225linked-to file is preceded by
226.Dq \-> .
227.Pp
228The file mode printed under the
229.Fl l
230option consists of the
231entry type, owner permissions, and group permissions.
232The entry type character describes the type of file, as
233follows:
234.Pp
235.Bl -tag -width 4n -offset indent -compact
236.It Sy b
237Block special file.
238.It Sy c
239Character special file.
240.It Sy d
241Directory.
242.It Sy l
243Symbolic link.
244.It Sy s
245Socket link.
246.It Sy p
247.Tn FIFO .
248.It Sy \-
249Regular file.
250.El
251.Pp
252The next three fields
253are three characters each:
254owner permissions,
255group permissions, and
256other permissions.
257Each field has three character positions:
258.Bl -enum -offset indent
259.It
260If
261.Sy r ,
262the file is readable; if
263.Sy \- ,
264it is not readable.
265.It
266If
267.Sy w ,
268the file is writable; if
269.Sy \- ,
270it is not writable.
271.It
272The first of the following that applies:
273.Bl -tag -width 4n -offset indent
274.It Sy S
275If in the owner permissions, the file is not executable and
276set-user-ID mode is set.
277If in the group permissions, the file is not executable
278and set-group-ID mode is set.
279.It Sy s
280If in the owner permissions, the file is executable
281and set-user-ID mode is set.
282If in the group permissions, the file is executable
283and setgroup-ID mode is set.
284.It Sy x
285The file is executable or the directory is
286searchable.
287.It Sy \-
288The file is neither readable, writable, executable,
289nor set-user-ID nor set-group-ID mode, nor sticky. (See below.)
290.El
291.Pp
292These next two apply only to the third character in the last group
293(other permissions).
294.Bl -tag -width 4n -offset indent
295.It Sy T
296The sticky bit is set
297(mode
298.Li 1000 ) ,
299but not execute or search permission. (See
300.Xr chmod 1
301or
302.Xr sticky 8 . )
303.It Sy t
304The sticky bit is set (mode
305.Li 1000 ) ,
306and is searchable or executable.
307(See
308.Xr chmod 1
309or
310.Xr sticky 8 . )
311.El
312.El
313.Pp
314The
315.Nm ls
316utility exits 0 on success, and >0 if an error occurs.
317.Sh ENVIRONMENT VARIABLES
318The following environment variables affect the execution of
319.Nm ls :
320.Bl -tag -width BLOCKSIZE
321.It Ev BLOCKSIZE
322If the environment variable
323.Ev BLOCKSIZE
324is set, the block counts
325(see
326.Fl s )
327will be displayed in units of that size block.
328.It COLUMNS
329If this variable contains a string representing a
330decimal integer, it is used as the
331column position width for displaying
332multiple-text-column output.
333The
334.Nm ls
335utility calculates how
336many pathname text columns to display
337based on the width provided.
338(See
339.Fl C . )
340.It Ev TZ
341The timezone to use when displaying dates.
342See
343.Xr environ 7
344for more information.
345.El
346.Sh COMPATIBILITY
347The group field is now automatically included in the long listing for
348files in order to be compatible with the
349.St -p1003.2
350specification.
351.Sh SEE ALSO
352.Xr chmod 1 ,
353.Xr symlink 7 ,
354.Xr sticky 8
355.Sh HISTORY
356An
357.Nm ls
358command appeared in
359.At v1 .
360.Sh STANDARDS
361The
362.Nm ls
363function is expected to be a superset of the
364.St -p1003.2
365specification.
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the Institute of Electrical and Electronics Engineers, Inc.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\" must display the following acknowledgement:
17.\" This product includes software developed by the University of
18.\" California, Berkeley and its contributors.
19.\" 4. Neither the name of the University nor the names of its contributors
20.\" may be used to endorse or promote products derived from this software
21.\" without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\" @(#)ls.1 8.7 (Berkeley) 7/29/94
36.\" $Id: ls.1,v 1.17 1998/04/21 22:01:58 des Exp $
37.\"
38.Dd July 29, 1994
39.Dt LS 1
40.Os
41.Sh NAME
42.Nm ls
43.Nd list directory contents
44.Sh SYNOPSIS
45.Nm ls
46.Op Fl ?ABCFLRTWabcdfgikloqrstu1
47.Op Ar file ...
48.Sh DESCRIPTION
49For each operand that names a
50.Ar file
51of a type other than
52directory,
53.Nm ls
54displays its name as well as any requested,
55associated information.
56For each operand that names a
57.Ar file
58of type directory,
59.Nm ls
60displays the names of files contained
61within that directory, as well as any requested, associated
62information.
63.Pp
64If no operands are given, the contents of the current
65directory are displayed.
66If more than one operand is given,
67non-directory operands are displayed first; directory
68and non-directory operands are sorted separately and in
69lexicographical order.
70.Pp
71The following options are available:
72.Bl -tag -width indent
73.It Fl ?
74Displays a short list of valid options.
75.It Fl A
76List all entries except for
77.Ql \&.
78and
79.Ql \&.. .
80Always set for the super-user.
81.It Fl B
82Force printing of non-graphic characters in file names as \\xxx,
83where xxx is the numeric value of the character in octal.
84.It Fl C
85Force multi-column output; this is the default when output is to a terminal.
86.It Fl F
87Display a slash (/) immediately after each pathname
88that is a directory, an asterisk (*) after each that is
89executable,
90an at sign (@) after each symbolic link,
91an equals sign (=) after each socket,
92a percent sign (%) after each whiteout,
93and a vertical bar (|) after each that is a
94.Tn FIFO .
95.It Fl L
96If argument is a symbolic link, list the file or directory the link references
97rather than the link itself.
98.It Fl R
99Recursively list subdirectories encountered.
100.It Fl T
101Display complete time information for the file, including
102month, day, hour, minute, second, and year.
103.It Fl W
104Display whiteouts when scanning directories.
105.It Fl a
106Include directory entries whose names begin with a
107dot (.).
108.It Fl b
109As
110.Fl B ,
111but use C escape codes whenever possible.
112.It Fl c
113Use time when file status was last changed for sorting or printing.
114.It Fl d
115Directories are listed as plain files (not searched recursively) and
116symbolic links in the argument list are not indirected through.
117.It Fl f
118Output is not sorted.
119.It Fl g
120This option is deprecated and is only available for compatibility
121with
122.Bx 4.3 ;
123it was used to display the group name in the long
124.Pq Fl l
125format output.
126.It Fl i
127For each file, print the file's file serial number (inode number).
128.It Fl k
129If the
130.Fl s
131option is specified, print the file size allocation in kilobytes,
132not blocks.
133.It Fl l
134(The lowercase letter ``ell.'') List in long format. (See below.)
135If the output is to a terminal, a total sum for all the file
136sizes is output on a line before the long listing.
137.It Fl o
138Include the file flags in a long
139.Pq Fl l
140output.
141.It Fl q
142Force printing of non-graphic characters in file names as
143the character `?'; this is the default when output is to a terminal.
144.It Fl r
145Reverse the order of the sort to get reverse
146lexicographical order or the oldest entries first.
147.It Fl s
148Display the number of file system blocks actually used by each file, in units
149of 512 bytes, where partial units are rounded up to the next integer value.
150If the output is to a terminal, a total sum for all the file
151sizes is output on a line before the listing.
152.It Fl t
153Sort by time modified (most recently modified
154first) before sorting the operands by lexicographical
155order.
156.It Fl u
157Use time of last access,
158instead of last modification
159of the file for sorting
160.Pq Fl t
161or printing
162.Pq Fl l .
163.It Fl \&1
164(The numeric digit ``one.'') Force output to be
165one entry per line.
166This is the default when
167output is not to a terminal.
168.El
169.Pp
170The
171.Fl 1 ,
172.Fl C ,
173and
174.Fl l
175options all override each other; the last one specified determines
176the format used.
177.Pp
178The
179.Fl c ,
180and
181.Fl u
182options override each other; the last one specified determines
183the file time used.
184.Pp
185By default,
186.Nm ls
187lists one entry per line to standard
188output; the exceptions are to terminals or when the
189.Fl C
190option is specified.
191.Pp
192File information is displayed with one or more
193<blank>s separating the information associated with the
194.Fl i ,
195.Fl s ,
196and
197.Fl l
198options.
199.Ss The Long Format
200If the
201.Fl l
202option is given, the following information
203is displayed for each file:
204file mode,
205number of links, owner name, group name,
206number of bytes in the file, abbreviated
207month, day-of-month file was last modified,
208hour file last modified, minute file last
209modified, and the pathname.
210In addition, for each directory whose contents are displayed, the total
211number of 512-byte blocks used by the files in the directory is displayed
212on a line by itself immediately before the information for the files in the
213directory.
214.Pp
215If the modification time of the file is more than 6 months
216in the past or future, then the year of the last modification
217is displayed in place of the hour and minute fields.
218.Pp
219If the owner or group names are not a known user or group name
220the numeric ID's are displayed.
221.Pp
222If the file is a character special or block special file,
223the major and minor device numbers for the file are displayed
224in the size field. If the file is a symbolic link the pathname of the
225linked-to file is preceded by
226.Dq \-> .
227.Pp
228The file mode printed under the
229.Fl l
230option consists of the
231entry type, owner permissions, and group permissions.
232The entry type character describes the type of file, as
233follows:
234.Pp
235.Bl -tag -width 4n -offset indent -compact
236.It Sy b
237Block special file.
238.It Sy c
239Character special file.
240.It Sy d
241Directory.
242.It Sy l
243Symbolic link.
244.It Sy s
245Socket link.
246.It Sy p
247.Tn FIFO .
248.It Sy \-
249Regular file.
250.El
251.Pp
252The next three fields
253are three characters each:
254owner permissions,
255group permissions, and
256other permissions.
257Each field has three character positions:
258.Bl -enum -offset indent
259.It
260If
261.Sy r ,
262the file is readable; if
263.Sy \- ,
264it is not readable.
265.It
266If
267.Sy w ,
268the file is writable; if
269.Sy \- ,
270it is not writable.
271.It
272The first of the following that applies:
273.Bl -tag -width 4n -offset indent
274.It Sy S
275If in the owner permissions, the file is not executable and
276set-user-ID mode is set.
277If in the group permissions, the file is not executable
278and set-group-ID mode is set.
279.It Sy s
280If in the owner permissions, the file is executable
281and set-user-ID mode is set.
282If in the group permissions, the file is executable
283and setgroup-ID mode is set.
284.It Sy x
285The file is executable or the directory is
286searchable.
287.It Sy \-
288The file is neither readable, writable, executable,
289nor set-user-ID nor set-group-ID mode, nor sticky. (See below.)
290.El
291.Pp
292These next two apply only to the third character in the last group
293(other permissions).
294.Bl -tag -width 4n -offset indent
295.It Sy T
296The sticky bit is set
297(mode
298.Li 1000 ) ,
299but not execute or search permission. (See
300.Xr chmod 1
301or
302.Xr sticky 8 . )
303.It Sy t
304The sticky bit is set (mode
305.Li 1000 ) ,
306and is searchable or executable.
307(See
308.Xr chmod 1
309or
310.Xr sticky 8 . )
311.El
312.El
313.Pp
314The
315.Nm ls
316utility exits 0 on success, and >0 if an error occurs.
317.Sh ENVIRONMENT VARIABLES
318The following environment variables affect the execution of
319.Nm ls :
320.Bl -tag -width BLOCKSIZE
321.It Ev BLOCKSIZE
322If the environment variable
323.Ev BLOCKSIZE
324is set, the block counts
325(see
326.Fl s )
327will be displayed in units of that size block.
328.It COLUMNS
329If this variable contains a string representing a
330decimal integer, it is used as the
331column position width for displaying
332multiple-text-column output.
333The
334.Nm ls
335utility calculates how
336many pathname text columns to display
337based on the width provided.
338(See
339.Fl C . )
340.It Ev TZ
341The timezone to use when displaying dates.
342See
343.Xr environ 7
344for more information.
345.El
346.Sh COMPATIBILITY
347The group field is now automatically included in the long listing for
348files in order to be compatible with the
349.St -p1003.2
350specification.
351.Sh SEE ALSO
352.Xr chmod 1 ,
353.Xr symlink 7 ,
354.Xr sticky 8
355.Sh HISTORY
356An
357.Nm ls
358command appeared in
359.At v1 .
360.Sh STANDARDS
361The
362.Nm ls
363function is expected to be a superset of the
364.St -p1003.2
365specification.