Commit | Line | Data |
---|---|---|
a93cea6a | 1 | .\" Copyright 1980, 1990, 1991 The Regents of the University of California. |
356242cc | 2 | .\" All rights reserved. |
a10206cc | 3 | .\" |
cf136d2c KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" the Institute of Electrical and Electronics Engineers, Inc. | |
6 | .\" | |
a93cea6a | 7 | .\" %sccs.include.redist.roff% |
356242cc | 8 | .\" |
9b71b6c1 | 9 | .\" @(#)ls.1 6.23 (Berkeley) %G% |
a10206cc | 10 | .\" |
a93cea6a CL |
11 | .Dd |
12 | .Dt LS 1 | |
13 | .Os | |
14 | .Sh NAME | |
15 | .Nm ls | |
16 | .Nd list directory contents | |
17 | .Sh SYNOPSIS | |
18 | .Nm ls | |
19 | .Op Fl CFRacdilqrstu1 | |
20 | .Op Ar file ... | |
21 | .Sh DESCRIPTION | |
22 | For each operand that names a | |
23 | .Ar file | |
24 | of a type other than | |
25 | directory, | |
26 | .Nm ls | |
27 | displays its name as well as any requested, | |
28 | associated information. | |
29 | For each operand that names a | |
30 | .Ar file | |
31 | of type directory, | |
32 | .Nm ls | |
33 | displays the names of files contained | |
34 | within that directory, as well as any requested, associated | |
35 | information. | |
36 | .Pp | |
37 | If no operands are given, the contents of the current | |
38 | directory are displayed. | |
39 | If more than one operand is given, | |
40 | non-directory operands are displayed first; directory | |
41 | and non-directory operands are sorted separately and in | |
42 | lexicographical order. | |
43 | .Pp | |
44 | The following options are available: | |
45 | .Bl -tag -width indent | |
46 | .It Fl A | |
47 | List all entries except for | |
48 | .Ql \&. | |
49 | and | |
50 | .Ql \&.. . | |
c699b55c | 51 | Always set for the super-user. |
a93cea6a CL |
52 | .It Fl C |
53 | Force multi-column output; this is the default when output is to a terminal. | |
54 | .It Fl F | |
55 | Display a slash (/) immediately after each pathname | |
56 | that is a directory, an asterisk (*) after each that is | |
57 | executable, | |
58 | and an at sign (@) after each symbolic link. | |
4933888a KB |
59 | .\" and a vertical bar (|) after each that is a |
60 | .\" .Tn FIFO . | |
a93cea6a | 61 | .It Fl L |
30149789 KM |
62 | If argument is a symbolic link, list the file or directory the link references |
63 | rather than the link itself. | |
a93cea6a CL |
64 | .It Fl R |
65 | Recursively list subdirectories encountered. | |
66 | .It Fl T | |
e05a6377 KB |
67 | Display complete time information for the file, including |
68 | month, day, hour, minute, second, and year. | |
a93cea6a CL |
69 | .It Fl a |
70 | Include directory entries whose names begin with a | |
71 | dot (.). | |
72 | .It Fl c | |
73 | Use time when file status was last changed for sorting or printing. | |
74 | .It Fl d | |
8b5f57b4 KB |
75 | Directories are listed as plain files (not searched recursively) and |
76 | symbolic links in the argument list are not indirected through. | |
a93cea6a CL |
77 | .It Fl f |
78 | Output is not sorted. | |
a93cea6a CL |
79 | .It Fl i |
80 | For each file, print the file's file serial number (inode number). | |
a93cea6a CL |
81 | .It Fl l |
82 | (The lowercase letter ``ell.'') List in long format. (See below.) | |
83 | If the output is to a terminal, a total sum for all the file | |
84 | sizes is output on a line before the long listing. | |
9b71b6c1 | 85 | .It Fl o |
32980675 KM |
86 | Include the file flags in a long |
87 | .Pq Fl l | |
88 | output | |
a93cea6a CL |
89 | .It Fl q |
90 | Force printing of non-graphic characters in file names as | |
91 | the character `?'; this is the default when output is to a terminal. | |
92 | .It Fl r | |
93 | Reverse the order of the sort to get reverse | |
94 | lexicographical order or the oldest entries first. | |
95 | .It Fl s | |
4933888a KB |
96 | Display the number of file system blocks actually used by each file, in units |
97 | of 512 bytes, where partial units are rounded up to the next integer value. | |
a93cea6a CL |
98 | If the output is to a terminal, a total sum for all the file |
99 | sizes is output on a line before the listing. | |
100 | .It Fl t | |
101 | Sort by time modified (most recently modified | |
102 | first) before sorting the operands by lexicographical | |
103 | order. | |
104 | .It Fl u | |
105 | Use time of last access, | |
106 | instead of last modification | |
107 | of the file for sorting | |
108 | .Pq Fl t | |
109 | or printing | |
110 | .Pq Fl l . | |
111 | .It Fl \&1 | |
112 | (The numeric digit ``one.'') Force output to be | |
113 | one entry per line. | |
114 | This is the default when | |
115 | output is not to a terminal. | |
116 | .El | |
117 | .Pp | |
c699b55c | 118 | The |
a93cea6a CL |
119 | .Fl 1 , |
120 | .Fl C , | |
c699b55c | 121 | and |
a93cea6a | 122 | .Fl l |
c699b55c KB |
123 | options all override each other; the last one specified determines |
124 | the format used. | |
a93cea6a | 125 | .Pp |
c699b55c | 126 | The |
a93cea6a | 127 | .Fl c , |
c699b55c | 128 | and |
a93cea6a | 129 | .Fl u |
c699b55c KB |
130 | options override each other; the last one specified determines |
131 | the file time used. | |
a93cea6a CL |
132 | .Pp |
133 | By default, | |
134 | .Nm ls | |
135 | lists one entry per line to standard | |
136 | output; the exceptions are to terminals or when the | |
137 | .Fl C | |
138 | option is specified. | |
139 | .Pp | |
140 | File information is displayed with one or more | |
141 | <blank>s separating the information associated with the | |
142 | .Fl i , | |
143 | .Fl s , | |
144 | and | |
145 | .Fl l | |
146 | options. | |
147 | .Ss The Long Format | |
148 | If the | |
149 | .Fl l | |
150 | option is given, the following information | |
4933888a | 151 | is displayed for each file: |
a93cea6a | 152 | file mode, |
63cf650d | 153 | number of links, owner name, group name, |
a93cea6a CL |
154 | number of bytes in the file, abbreviated |
155 | month, day-of-month file was last modified, | |
156 | hour file last modified, minute file last | |
157 | modified, and the pathname. | |
4933888a KB |
158 | In addition, for each directory whose contents are displayed, the total |
159 | number of 512-byte blocks used by the files in the directory is displayed | |
160 | on a line by itself immediately before the information for the files in the | |
161 | directory. | |
a93cea6a | 162 | .Pp |
63cf650d KB |
163 | If the owner or group names are not a known user or group name |
164 | the numeric ID's are displayed. | |
a93cea6a CL |
165 | .Pp |
166 | If the file is a character special or block special file, | |
167 | the major and minor device numbers for the file are displayed | |
168 | in the size field. If the file is a symbolic link the pathname of the | |
169 | linked-to file is preceded by | |
170 | .Dq \-> . | |
171 | .Pp | |
172 | The file mode printed under the -l option consists of the | |
173 | the entry type, owner permissions, and group permissions. | |
174 | The entry type character describes the type of file, as | |
175 | follows: | |
176 | .Pp | |
177 | .Bl -tag -width 4n -offset indent -compact | |
178 | .It Sy b | |
179 | Block special file. | |
180 | .It Sy c | |
181 | Character special file. | |
182 | .It Sy d | |
183 | Directory. | |
184 | .It Sy l | |
185 | Symbolic link. | |
186 | .It Sy s | |
187 | Socket link. | |
188 | .\" .It Sy p | |
189 | .\" .Tn FIFO . | |
190 | .It Sy \- | |
191 | Regular file. | |
192 | .El | |
193 | .Pp | |
194 | The next three fields | |
195 | are three characters each: | |
196 | owner permissions, | |
197 | group permissions, and | |
198 | other permissions. | |
199 | Each field has three character positions: | |
200 | .Bl -enum -offset indent | |
201 | .It | |
202 | If | |
203 | .Sy r , | |
204 | the file is readable; if | |
205 | .Sy \- , | |
206 | it is not readable. | |
207 | .It | |
208 | If | |
209 | .Sy w , | |
210 | the file is writable; if | |
211 | .Sy \- , | |
212 | it is not writable. | |
213 | .It | |
214 | The first of the following that applies: | |
215 | .Bl -tag -width 4n -offset indent | |
216 | .It Sy S | |
217 | If in the owner permissions, the file is not executable and | |
218 | set-user-ID mode is set. | |
219 | If in the group permissions, the file is not executable | |
220 | and set-group-ID mode is set. | |
221 | .It Sy s | |
222 | If in the owner permissions, the file is executable | |
223 | and set-user-ID mode is set. | |
224 | If in the group permissions, the file is executable | |
225 | and setgroup-ID mode is set. | |
226 | .It Sy x | |
227 | The file is executable or the directory is | |
228 | searchable. | |
229 | .It Sy \- | |
230 | The file is neither readable, writeable, exectutable, | |
231 | or set-user-ID or set-group-ID mode nor sticky. (See below.) | |
232 | .El | |
233 | .Pp | |
234 | These next two apply only to the third character in the last group | |
235 | (other permissions). | |
236 | .Bl -tag -width 4n -offset indent | |
237 | .It Sy T | |
238 | The sticky bit is set | |
239 | (mode | |
240 | .Li 1000 ) , | |
241 | but not execute or search permission. (See | |
242 | .Xr chmod 1 | |
243 | or | |
244 | .Xr sticky 8 . ) | |
245 | .It Sy t | |
246 | The sticky bit is set (mode | |
247 | .Li 1000 ) , | |
248 | and is searcheable or executable. | |
249 | (See | |
250 | .Xr chmod 1 | |
251 | or | |
252 | .Xr sticky 8 . ) | |
253 | .El | |
254 | .El | |
255 | .Pp | |
256 | The | |
257 | .Nm ls | |
258 | utility exits 0 on success, and >0 if an error occurs. | |
4933888a | 259 | .Sh ENVIRONMENTAL VARIABLES |
a93cea6a CL |
260 | The following environment variables affect the execution of |
261 | .Nm ls : | |
4933888a KB |
262 | .Bl -tag -width BLOCKSIZE |
263 | .It Ev BLOCKSIZE | |
264 | If the environmental variable | |
265 | .Ev BLOCKSIZE | |
266 | is set, the block counts | |
267 | (see | |
268 | .Fl s ) | |
269 | will be displayed in units of that size block. | |
a93cea6a CL |
270 | .It COLUMNS |
271 | If this variable contains a string representing a | |
272 | decimal integer, it is used as the | |
273 | column position width for displaying | |
274 | multiple-text-column output. | |
275 | The | |
276 | .Nm ls | |
277 | utility calculates how | |
278 | many pathname text columns to display | |
279 | based on the width provided. | |
280 | (See | |
281 | .Fl C . ) | |
282 | .El | |
63cf650d KB |
283 | .Sh COMPATIBILITY |
284 | The group field is now automatically included in the long listing for | |
285 | files in order to be compatible with the | |
286 | .St -p1003.2 | |
287 | specification. | |
a93cea6a CL |
288 | .Sh SEE ALSO |
289 | .Xr chmod 1 , | |
290 | .Xr sticky 8 | |
291 | .Sh HISTORY | |
292 | A | |
293 | .Nm ls | |
294 | command appeared in | |
295 | .At v6 . | |
4933888a KB |
296 | .Sh STANDARDS |
297 | The | |
298 | .Nm ls | |
299 | function is expected to be a superset of the | |
300 | .St -p1003.2 | |
301 | specification. |