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