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