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
| 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.16 1997/12/25 09:36:39 hoek Exp $
| 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
| 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 ACFLRTWabcdfgikloqrstu1
| 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
| 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.
|
73.It Fl A
74List all entries except for
75.Ql \&.
76and
77.Ql \&.. .
78Always set for the super-user.
| 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.
|
79.It Fl C
80Force multi-column output; this is the default when output is to a terminal.
81.It Fl F
82Display a slash (/) immediately after each pathname
83that is a directory, an asterisk (*) after each that is
84executable,
85an at sign (@) after each symbolic link,
86an equals sign (=) after each socket,
87a percent sign (%) after each whiteout,
88and a vertical bar (|) after each that is a
89.Tn FIFO .
90.It Fl L
91If argument is a symbolic link, list the file or directory the link references
92rather than the link itself.
93.It Fl R
94Recursively list subdirectories encountered.
95.It Fl T
96Display complete time information for the file, including
97month, day, hour, minute, second, and year.
98.It Fl W
99Display whiteouts when scanning directories.
100.It Fl a
101Include directory entries whose names begin with a
102dot (.).
103.It Fl b
| 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
|
104Force printing of non-graphic characters in file names as \\xxx,
105where xxx is the numeric value of the character in octal.
| 109As
110.Fl B ,
111but use C escape codes whenever possible.
|
106.It Fl c
107Use time when file status was last changed for sorting or printing.
108.It Fl d
109Directories are listed as plain files (not searched recursively) and
110symbolic links in the argument list are not indirected through.
111.It Fl f
112Output is not sorted.
113.It Fl g
114This option is deprecated and is only available for compatibility
115with
116.Bx 4.3 ;
117it was used to display the group name in the long
118.Pq Fl l
119format output.
120.It Fl i
121For each file, print the file's file serial number (inode number).
122.It Fl k
123If the
124.Fl s
125option is specified, print the file size allocation in kilobytes,
126not blocks.
127.It Fl l
128(The lowercase letter ``ell.'') List in long format. (See below.)
129If the output is to a terminal, a total sum for all the file
130sizes is output on a line before the long listing.
131.It Fl o
132Include the file flags in a long
133.Pq Fl l
134output.
135.It Fl q
136Force printing of non-graphic characters in file names as
137the character `?'; this is the default when output is to a terminal.
138.It Fl r
139Reverse the order of the sort to get reverse
140lexicographical order or the oldest entries first.
141.It Fl s
142Display the number of file system blocks actually used by each file, in units
143of 512 bytes, where partial units are rounded up to the next integer value.
144If the output is to a terminal, a total sum for all the file
145sizes is output on a line before the listing.
146.It Fl t
147Sort by time modified (most recently modified
148first) before sorting the operands by lexicographical
149order.
150.It Fl u
151Use time of last access,
152instead of last modification
153of the file for sorting
154.Pq Fl t
155or printing
156.Pq Fl l .
157.It Fl \&1
158(The numeric digit ``one.'') Force output to be
159one entry per line.
160This is the default when
161output is not to a terminal.
162.El
163.Pp
164The
165.Fl 1 ,
166.Fl C ,
167and
168.Fl l
169options all override each other; the last one specified determines
170the format used.
171.Pp
172The
173.Fl c ,
174and
175.Fl u
176options override each other; the last one specified determines
177the file time used.
178.Pp
179By default,
180.Nm ls
181lists one entry per line to standard
182output; the exceptions are to terminals or when the
183.Fl C
184option is specified.
185.Pp
186File information is displayed with one or more
187<blank>s separating the information associated with the
188.Fl i ,
189.Fl s ,
190and
191.Fl l
192options.
193.Ss The Long Format
194If the
195.Fl l
196option is given, the following information
197is displayed for each file:
198file mode,
199number of links, owner name, group name,
200number of bytes in the file, abbreviated
201month, day-of-month file was last modified,
202hour file last modified, minute file last
203modified, and the pathname.
204In addition, for each directory whose contents are displayed, the total
205number of 512-byte blocks used by the files in the directory is displayed
206on a line by itself immediately before the information for the files in the
207directory.
208.Pp
209If the modification time of the file is more than 6 months
210in the past or future, then the year of the last modification
211is displayed in place of the hour and minute fields.
212.Pp
213If the owner or group names are not a known user or group name
214the numeric ID's are displayed.
215.Pp
216If the file is a character special or block special file,
217the major and minor device numbers for the file are displayed
218in the size field. If the file is a symbolic link the pathname of the
219linked-to file is preceded by
220.Dq \-> .
221.Pp
222The file mode printed under the
223.Fl l
224option consists of the
225entry type, owner permissions, and group permissions.
226The entry type character describes the type of file, as
227follows:
228.Pp
229.Bl -tag -width 4n -offset indent -compact
230.It Sy b
231Block special file.
232.It Sy c
233Character special file.
234.It Sy d
235Directory.
236.It Sy l
237Symbolic link.
238.It Sy s
239Socket link.
240.It Sy p
241.Tn FIFO .
242.It Sy \-
243Regular file.
244.El
245.Pp
246The next three fields
247are three characters each:
248owner permissions,
249group permissions, and
250other permissions.
251Each field has three character positions:
252.Bl -enum -offset indent
253.It
254If
255.Sy r ,
256the file is readable; if
257.Sy \- ,
258it is not readable.
259.It
260If
261.Sy w ,
262the file is writable; if
263.Sy \- ,
264it is not writable.
265.It
266The first of the following that applies:
267.Bl -tag -width 4n -offset indent
268.It Sy S
269If in the owner permissions, the file is not executable and
270set-user-ID mode is set.
271If in the group permissions, the file is not executable
272and set-group-ID mode is set.
273.It Sy s
274If in the owner permissions, the file is executable
275and set-user-ID mode is set.
276If in the group permissions, the file is executable
277and setgroup-ID mode is set.
278.It Sy x
279The file is executable or the directory is
280searchable.
281.It Sy \-
282The file is neither readable, writable, executable,
283nor set-user-ID nor set-group-ID mode, nor sticky. (See below.)
284.El
285.Pp
286These next two apply only to the third character in the last group
287(other permissions).
288.Bl -tag -width 4n -offset indent
289.It Sy T
290The sticky bit is set
291(mode
292.Li 1000 ) ,
293but not execute or search permission. (See
294.Xr chmod 1
295or
296.Xr sticky 8 . )
297.It Sy t
298The sticky bit is set (mode
299.Li 1000 ) ,
300and is searchable or executable.
301(See
302.Xr chmod 1
303or
304.Xr sticky 8 . )
305.El
306.El
307.Pp
308The
309.Nm ls
310utility exits 0 on success, and >0 if an error occurs.
311.Sh ENVIRONMENT VARIABLES
312The following environment variables affect the execution of
313.Nm ls :
314.Bl -tag -width BLOCKSIZE
315.It Ev BLOCKSIZE
316If the environment variable
317.Ev BLOCKSIZE
318is set, the block counts
319(see
320.Fl s )
321will be displayed in units of that size block.
322.It COLUMNS
323If this variable contains a string representing a
324decimal integer, it is used as the
325column position width for displaying
326multiple-text-column output.
327The
328.Nm ls
329utility calculates how
330many pathname text columns to display
331based on the width provided.
332(See
333.Fl C . )
334.It Ev TZ
335The timezone to use when displaying dates.
336See
337.Xr environ 7
338for more information.
339.El
340.Sh COMPATIBILITY
341The group field is now automatically included in the long listing for
342files in order to be compatible with the
343.St -p1003.2
344specification.
345.Sh SEE ALSO
346.Xr chmod 1 ,
347.Xr symlink 7 ,
348.Xr sticky 8
349.Sh HISTORY
350An
351.Nm ls
352command appeared in
353.At v1 .
354.Sh STANDARDS
355The
356.Nm ls
357function is expected to be a superset of the
358.St -p1003.2
359specification.
| 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.
|