1LS(1P)                     POSIX Programmer's Manual                    LS(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       ls — list directory contents
13

SYNOPSIS

15       ls [-ikqrs] [-glno] [-A|-a] [-C|-m|-x|-1] \
16           [-F|-p] [-H|-L] [-R|-d] [-S|-f|-t] [-c|-u] [file...]
17

DESCRIPTION

19       For each operand that names a file of a type other  than  directory  or
20       symbolic  link  to  a directory, ls shall write the name of the file as
21       well as any requested, associated information. For  each  operand  that
22       names  a file of type directory, ls shall write the names of files con‐
23       tained within the directory as well as any requested, associated infor‐
24       mation.  Filenames  beginning with a <period> ('.')  and any associated
25       information shall not be written out unless explicitly referenced,  the
26       -A  or  -a  option  is supplied, or an implementation-defined condition
27       causes them to be written. If one or more of the -d, -F, or -l  options
28       are  specified,  and neither the -H nor the -L option is specified, for
29       each operand that names a file of type symbolic link to a directory, ls
30       shall  write  the name of the file as well as any requested, associated
31       information. If none of the -d, -F, or -l options are specified, or the
32       -H  or  -L options are specified, for each operand that names a file of
33       type symbolic link to a directory, ls shall write the  names  of  files
34       contained  within  the  directory  as well as any requested, associated
35       information. In each case where the names of files contained  within  a
36       directory  are  written,  if  the directory contains any symbolic links
37       then ls shall evaluate the file information and file type to  be  those
38       of the symbolic link itself, unless the -L option is specified.
39
40       If no operands are specified, ls shall behave as if a single operand of
41       dot ('.')  had been specified. If more than one operand  is  specified,
42       ls  shall  write  non-directory operands first; it shall sort directory
43       and  non-directory  operands  separately  according  to  the  collating
44       sequence in the current locale.
45
46       Whenever  ls  sorts  filenames  or pathnames according to the collating
47       sequence in the current locale, if this  collating  sequence  does  not
48       have  a total ordering of all characters (see the Base Definitions vol‐
49       ume of POSIX.1‐2017, Section 7.3.2, LC_COLLATE), then any filenames  or
50       pathnames  that collate equally should be further compared byte-by-byte
51       using the collating sequence for the POSIX locale.
52
53       The ls utility shall detect infinite loops; that is, entering a  previ‐
54       ously  visited  directory  that is an ancestor of the last file encoun‐
55       tered.  When it detects an infinite loop, ls shall write  a  diagnostic
56       message  to standard error and shall either recover its position in the
57       hierarchy or terminate.
58

OPTIONS

60       The ls  utility  shall  conform  to  the  Base  Definitions  volume  of
61       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
62
63       The following options shall be supported:
64
65       -A        Write  out all directory entries, including those whose names
66                 begin with a <period> ('.')  but excluding  the  entries  dot
67                 and dot-dot (if they exist).
68
69       -C        Write  multi-text-column  output with entries sorted down the
70                 columns, according to the collating sequence. The  number  of
71                 text columns and the column separator characters are unspeci‐
72                 fied, but should be adapted  to  the  nature  of  the  output
73                 device. This option disables long format output.
74
75       -F        Do  not follow symbolic links named as operands unless the -H
76                 or -L options are specified. Write a  <slash>  ('/')  immedi‐
77                 ately  after each pathname that is a directory, an <asterisk>
78                 ('*') after each that is executable, a <vertical-line>  ('|')
79                 after  each  that  is a FIFO, and an at-sign ('@') after each
80                 that is a symbolic link. For other file types, other  symbols
81                 may be written.
82
83       -H        Evaluate  the  file  information  and  file type for symbolic
84                 links specified on the command line to be those of  the  file
85                 referenced  by the link, and not the link itself; however, ls
86                 shall write the name of the link itself and not the file ref‐
87                 erenced by the link.
88
89       -L        Evaluate  the file information and file type for all symbolic
90                 links (whether named on the command line or encountered in  a
91                 file  hierarchy)  to  be  those of the file referenced by the
92                 link, and not the link itself; however, ls  shall  write  the
93                 name  of  the  link itself and not the file referenced by the
94                 link. When -L is used with -l, write the contents of symbolic
95                 links in the long format (see the STDOUT section).
96
97       -R        Recursively  list subdirectories encountered. When a symbolic
98                 link to a directory is encountered, the directory  shall  not
99                 be recursively listed unless the -L option is specified.  The
100                 use of -R with -d or -f produces unspecified results.
101
102       -S        Sort with the primary key  being  file  size  (in  decreasing
103                 order)  and the secondary key being filename in the collating
104                 sequence (in increasing order).
105
106       -a        Write out all directory entries, including those whose  names
107                 begin with a <period> ('.').
108
109       -c        Use  time of last modification of the file status information
110                 (see   the   Base   Definitions   volume   of   POSIX.1‐2017,
111                 <sys_stat.h>) instead of last modification of the file itself
112                 for sorting (-t) or writing (-l).
113
114       -d        Do not follow symbolic links named as operands unless the  -H
115                 or -L options are specified. Do not treat directories differ‐
116                 ently than other types of files. The use of -d with -R or  -f
117                 produces unspecified results.
118
119       -f        List  the  entries  in  directory  operands in the order they
120                 appear in the directory. The behavior for non-directory oper‐
121                 ands  is  unspecified. This option shall turn on -a.  When -f
122                 is specified, any occurrences of the -r, -S, and  -t  options
123                 shall  be  ignored and any occurrences of the -A, -g, -l, -n,
124                 -o, and -s options may be ignored. The use of -f with  -R  or
125                 -d produces unspecified results.
126
127       -g        Turn  on  the -l (ell) option, but disable writing the file's
128                 owner name or number.  Disable the -C, -m, and -x options.
129
130       -i        For each file, write  the  file's  file  serial  number  (see
131                 stat() in the System Interfaces volume of POSIX.1‐2017).
132
133       -k        Set  the  block  size for the -s option and the per-directory
134                 block count written for the -l, -n, -s, -g,  and  -o  options
135                 (see the STDOUT section) to 1024 bytes.
136
137       -l        (The letter ell.) Do not follow symbolic links named as oper‐
138                 ands unless the -H or -L options are specified. Write out  in
139                 long format (see the STDOUT section). Disable the -C, -m, and
140                 -x options.
141
142       -m        Stream output format; list pathnames across the  page,  sepa‐
143                 rated by a <comma> character followed by a <space> character.
144                 Use a <newline> character as the list  terminator  and  after
145                 the  separator  sequence when there is not room on a line for
146                 the next list entry. This option disables long format output.
147
148       -n        Turn on the -l (ell) option,  but  when  writing  the  file's
149                 owner  or  group,  write the file's numeric UID or GID rather
150                 than the user or group name, respectively.  Disable  the  -C,
151                 -m, and -x options.
152
153       -o        Turn  on  the -l (ell) option, but disable writing the file's
154                 group name or number.  Disable the -C, -m, and -x options.
155
156       -p        Write a <slash> ('/') after each filename if that file  is  a
157                 directory.
158
159       -q        Force  each instance of non-printable filename characters and
160                 <tab> characters to be written as the  <question-mark>  ('?')
161                 character. Implementations may provide this option by default
162                 if the output is to a terminal device.
163
164       -r        Reverse the order  of  the  sort  to  get  reverse  collating
165                 sequence  oldest first, or smallest file size first depending
166                 on the other options given.
167
168       -s        Indicate the total number of file system blocks  consumed  by
169                 each  file displayed. If the -k option is also specified, the
170                 block size shall be 1024 bytes; otherwise, the block size  is
171                 implementation-defined.
172
173       -t        Sort  with the primary key being time modified (most recently
174                 modified first) and the secondary key being filename  in  the
175                 collating  sequence.   For  a symbolic link, the time used as
176                 the sort key is that of the symbolic link itself,  unless  ls
177                 is  evaluating  its  file  information to be that of the file
178                 referenced by the link (see the -H and -L options).
179
180       -u        Use time of last access (see the Base Definitions  volume  of
181                 POSIX.1‐2017,  <sys_stat.h>)  instead of last modification of
182                 the file for sorting (-t) or writing (-l).
183
184       -x        The same as -C, except that the multi-text-column  output  is
185                 produced  with  entries  sorted across, rather than down, the
186                 columns. This option disables long format output.
187
188       -1        (The numeric digit one.) Force output to  be  one  entry  per
189                 line.  This option does not disable long format output. (Long
190                 format output is enabled by -g, -l (ell),  -n,  and  -o;  and
191                 disabled by -C, -m, and -x.)
192
193       If  an option that enables long format output (-g, -l (ell), -n, and -o
194       is given with an option that disables long format output (-C,  -m,  and
195       -x),  this  shall not be considered an error. The last of these options
196       specified shall determine whether long format output is written.
197
198       If -R, -d, or -f are specified, the results of specifying  these  mutu‐
199       ally-exclusive  options  are  specified  by  the  descriptions of these
200       options above. If more than one of any of the other  options  shown  in
201       the  SYNOPSIS  section in mutually-exclusive sets are given, this shall
202       not be considered an error; the last option specified in each set shall
203       determine the output.
204
205       Note that if -t is specified, -c and -u are not only mutually-exclusive
206       with each other, they are also mutually-exclusive with -S  when  deter‐
207       mining sort order. But even if -S is specified after all occurrences of
208       -c, -t, and -u, the last use of  -c  or  -u  determines  the  timestamp
209       printed when producing long format output.
210

OPERANDS

212       The following operand shall be supported:
213
214       file      A  pathname of a file to be written. If the file specified is
215                 not found, a diagnostic message shall be output  on  standard
216                 error.
217

STDIN

219       Not used.
220

INPUT FILES

222       None.
223

ENVIRONMENT VARIABLES

225       The following environment variables shall affect the execution of ls:
226
227       COLUMNS   Determine  the  user's  preferred  column  position width for
228                 writing multiple text-column output. If  this  variable  con‐
229                 tains a string representing a decimal integer, the ls utility
230                 shall calculate how many pathname text columns to write  (see
231                 -C)  based  on  the  width provided. If COLUMNS is not set or
232                 invalid, an implementation-defined number of column positions
233                 shall  be assumed, based on the implementation's knowledge of
234                 the output device. The column width chosen to write the names
235                 of  files in any given directory shall be constant. Filenames
236                 shall not be truncated to fit into the  multiple  text-column
237                 output.
238
239       LANG      Provide  a  default  value for the internationalization vari‐
240                 ables that are unset or null. (See the Base Definitions  vol‐
241                 ume  of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
242                 ables for the precedence  of  internationalization  variables
243                 used to determine the values of locale categories.)
244
245       LC_ALL    If  set  to  a non-empty string value, override the values of
246                 all the other internationalization variables.
247
248       LC_COLLATE
249                 Determine the locale for character collation  information  in
250                 determining the pathname collation sequence.
251
252       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
253                 bytes of text data as characters (for example, single-byte as
254                 opposed  to  multi-byte  characters  in  arguments) and which
255                 characters are defined as printable (character class print).
256
257       LC_MESSAGES
258                 Determine the locale that should be used to affect the format
259                 and  contents  of  diagnostic  messages  written  to standard
260                 error.
261
262       LC_TIME   Determine the format and contents for date and  time  strings
263                 written by ls.
264
265       NLSPATH   Determine the location of message catalogs for the processing
266                 of LC_MESSAGES.
267
268       TZ        Determine the timezone for date and time strings  written  by
269                 ls.   If TZ is unset or null, an unspecified default timezone
270                 shall be used.
271

ASYNCHRONOUS EVENTS

273       Default.
274

STDOUT

276       The default format shall be to list one entry per line to standard out‐
277       put;  the  exceptions are to terminals or when one of the -C, -m, or -x
278       options is specified. If the output is to a  terminal,  the  format  is
279       implementation-defined.
280
281       When  -m is specified, the format used for the last element of the list
282       shall be:
283
284
285           "%s\n", <filename>
286
287       The format used for each other element of the list shall be:
288
289
290           "%s,%s", <filename>, <separator>
291
292       where, if there is not room for the next element of  the  list  to  fit
293       within  the  current line length, <separator> is a string containing an
294       optional <space> character and a mandatory <newline> character;  other‐
295       wise it is a single <space> character.
296
297       If  the  -i option is specified, the file's file serial number (see the
298       Base Definitions volume of POSIX.1‐2017, <sys_stat.h>) shall be written
299       in  the  following format before any other output for the corresponding
300       entry:
301
302
303           %u ", <file serial number>
304
305       If the -l option is specified, the following information shall be writ‐
306       ten for files other than character special and block special files:
307
308
309           "%s %u %s %s %u %s %s\n", <file mode>, <number of links>,
310               <owner name>, <group name>, <size>, <date and time>,
311               <pathname>
312
313       If the -l option is specified, the following information shall be writ‐
314       ten for character special and block special files:
315
316
317           "%s %u %s %s %s %s %s\n", <file mode>, <number of links>,
318               <owner name>, <group name>, <device info>, <date and time>,
319               <pathname>
320
321       In both cases if the file is a symbolic link and the -L option is  also
322       specified,  this  information  shall  be for the file resolved from the
323       symbolic link, except that the <pathname> field shall contain the path‐
324       name  of  the  symbolic link itself. If the file is a symbolic link and
325       the -L option is not specified, this information  shall  be  about  the
326       link itself and the <pathname> field shall be of the form:
327
328
329           "%s -> %s", <pathname of link>, <contents of link>
330
331       The  -n, -g, and -o options use the same format as -l, but with omitted
332       items and their associated <blank> characters. See the OPTIONS section.
333
334       In both the preceding -l forms, if <owner name> or <group name>  cannot
335       be  determined,  or  if  -n is given, they shall be replaced with their
336       associated numeric values using the format %u.
337
338       The <size> field shall contain the value that would be returned for the
339       file in the st_size field of struct stat (see the Base Definitions vol‐
340       ume of POSIX.1‐2017, <sys_stat.h>).  Note that for some file types this
341       value is unspecified.
342
343       The  <device info>  field shall contain implementation-defined informa‐
344       tion associated with the device in question.
345
346       The <date and time> field shall contain the appropriate date and  time‐
347       stamp  of  when  the  file  was last modified. In the POSIX locale, the
348       field shall be the equivalent of the output of the following date  com‐
349       mand:
350
351
352           date "+%b %e %H:%M"
353
354       if the file has been modified in the last six months, or:
355
356
357           date "+%b %e %Y"
358
359       (where  two  <space> characters are used between %e and %Y) if the file
360       has not been modified in the last six months  or  if  the  modification
361       date  is in the future, except that, in both cases, the final <newline>
362       produced by date shall not be included and the output shall  be  as  if
363       the  date  command  were  executed at the time of the last modification
364       date of the file rather than the current time. When the LC_TIME  locale
365       category  is  not set to the POSIX locale, a different format and order
366       of presentation of this field may be used.
367
368       If the pathname was specified as a file operand, it shall be written as
369       specified.
370
371       The  file  mode written under the -l, -n, -g, and -o options shall con‐
372       sist of the following format:
373
374
375           "%c%s%s%s%s", <entry type>, <owner permissions>,
376               <group permissions>, <other permissions>,
377               <optional alternate access method flag>
378
379       The <optional alternate access method flag> shall be the  empty  string
380       if there is no alternate or additional access control method associated
381       with the file; otherwise, it shall be  a  string  containing  a  single
382       printable character that is not a <blank>.
383
384       The <entry type> character shall describe the type of file, as follows:
385
386       d       Directory.
387
388       b       Block special file.
389
390       c       Character special file.
391
392       l (ell) Symbolic link.
393
394       p       FIFO.
395
396       -       Regular file.
397
398       Implementations  may  add  other  characters  to this list to represent
399       other implementation-defined file types.
400
401       The next three fields shall be three characters each:
402
403       <owner permissions>
404             Permissions for the file owner class (see  the  Base  Definitions
405             volume of POSIX.1‐2017, Section 4.5, File Access Permissions).
406
407       <group permissions>
408             Permissions for the file group class.
409
410       <other permissions>
411             Permissions for the file other class.
412
413       Each field shall have three character positions:
414
415        1. If 'r', the file is readable; if '-', the file is not readable.
416
417        2. If 'w', the file is writable; if '-', the file is not writable.
418
419        3. The first of the following that applies:
420
421           S     If  in  <owner permissions>,  the  file is not executable and
422                 set-user-ID mode is set. If in <group permissions>, the  file
423                 is not executable and set-group-ID mode is set.
424
425           s     If  in  <owner permissions>,  the file is executable and set-
426                 user-ID mode is set. If in <group permissions>, the  file  is
427                 executable and set-group-ID mode is set.
428
429           T     If in <other permissions> and the file is a directory, search
430                 permission is not granted to others, and the restricted dele‐
431                 tion flag is set.
432
433           t     If in <other permissions> and the file is a directory, search
434                 permission is granted to others, and the restricted  deletion
435                 flag is set.
436
437           x     The file is executable or the directory is searchable.
438
439           -     None of the attributes of 'S', 's', 'T', 't', or 'x' applies.
440
441           Implementations may add other characters to this list for the third
442           character position. Such additions shall, however,  be  written  in
443           lowercase if the file is executable or searchable, and in uppercase
444           if it is not.
445
446       If any of the -l, -n, -s, -g, or -o options is specified, each list  of
447       files  within the directory shall be preceded by a status line indicat‐
448       ing the number of file system blocks occupied by files in the directory
449       in 512-byte units if the -k option is not specified, or 1024-byte units
450       if the -k option is specified, rounded up to the next  integral  number
451       of units, if necessary. In the POSIX locale, the format shall be:
452
453
454           "total %u\n", <number of units in the directory>
455
456       If more than one directory, or a combination of non-directory files and
457       directories are written, either as a result of specifying multiple  op‐
458       erands,  or  the -R option, each list of files within a directory shall
459       be preceded by:
460
461
462           "\n%s:\n", <directory name>
463
464       If this string is the first thing to be written,  the  first  <newline>
465       shall  not be written. This output shall precede the number of units in
466       the directory.
467
468       If the -s option is given, each file shall be written with  the  number
469       of  blocks  used  by the file. Along with -C, -1, -m, or -x, the number
470       and a <space> shall precede the filename; with -l, -n, -g, or -o,  they
471       shall precede each line describing a file.
472

STDERR

474       The standard error shall be used only for diagnostic messages.
475

OUTPUT FILES

477       None.
478

EXTENDED DESCRIPTION

480       None.
481

EXIT STATUS

483       The following exit values shall be returned:
484
485        0    Successful completion.
486
487       >0    An error occurred.
488

CONSEQUENCES OF ERRORS

490       Default.
491
492       The following sections are informative.
493

APPLICATION USAGE

495       Many  implementations  use  the  <equals-sign>  ('=') to denote sockets
496       bound to the file system for the -F option. Similarly, many  historical
497       implementations  use  the  's' character to denote sockets as the entry
498       type characters for the -l option.
499
500       It is difficult for an application to use every part of the file  modes
501       field  of ls -l in a portable manner. Certain file types and executable
502       bits are not guaranteed to be exactly as shown, as implementations  may
503       have  extensions. Applications can use this field to pass directly to a
504       user printout or prompt, but actions based on its contents should  gen‐
505       erally be deferred, instead, to the test utility.
506
507       The output of ls (with the -l and related options) contains information
508       that logically could be used by utilities such as chmod  and  touch  to
509       restore  files to a known state. However, this information is presented
510       in a format that cannot be used directly by those utilities or be  eas‐
511       ily  translated  into  a  format that can be used. A character has been
512       added to the end of the permissions  string  so  that  applications  at
513       least  have  an  indication that they may be working in an area they do
514       not understand instead of assuming that they can translate the  permis‐
515       sions  string  into  something  that  can  be  used. Future versions or
516       related documents may define one or more specific characters to be used
517       based  on  different  standard additional or alternative access control
518       mechanisms.
519
520       As with many of the utilities that deal with filenames, the  output  of
521       ls  for  multiple  files  or in one of the long listing formats must be
522       used carefully on systems where filenames can  contain  embedded  white
523       space.  Systems and system administrators should institute policies and
524       user training to limit the use of such filenames.
525
526       The number of disk blocks occupied by the file that it  reports  varies
527       depending  on  underlying  file system type, block size units reported,
528       and the method of calculating the number of blocks. On some file system
529       types,  the  number is the actual number of blocks occupied by the file
530       (counting indirect blocks and ignoring holes in the file); on others it
531       is  calculated  based on the file size (usually making an allowance for
532       indirect blocks, but ignoring holes).
533

EXAMPLES

535       An example of a small directory tree being fully listed with ls -laRF a
536       in the POSIX locale:
537
538
539           total 11
540           drwxr-xr-x   3 fox      prog          64 Jul  4 12:07 ./
541           drwxrwxrwx   4 fox      prog        3264 Jul  4 12:09 ../
542           drwxr-xr-x   2 fox      prog          48 Jul  4 12:07 b/
543           -rwxr--r--   1 fox      prog         572 Jul  4 12:07 foo*
544
545           a/b:
546           total 4
547           drwxr-xr-x   2 fox      prog          48 Jul  4 12:07 ./
548           drwxr-xr-x   3 fox      prog          64 Jul  4 12:07 ../
549           -rw-r--r--   1 fox      prog         700 Jul  4 12:07 bar
550

RATIONALE

552       Some historical implementations of the ls utility show all entries in a
553       directory except dot and dot-dot when a superuser  invokes  ls  without
554       specifying the -a option. When ``normal'' users invoke ls without spec‐
555       ifying -a, they should not see information about any files  with  names
556       beginning with a <period> unless they were named as file operands.
557
558       Implementations are expected to traverse arbitrary depths when process‐
559       ing the -R option. The only limitation on depth should be based on run‐
560       ning  out of physical storage for keeping track of untraversed directo‐
561       ries.
562
563       The -1 (one) option was  historically  found  in  BSD  and  BSD-derived
564       implementations  only. It is required in this volume of POSIX.1‐2017 so
565       that conforming applications might ensure that output is one entry  per
566       line, even if the output is to a terminal.
567
568       The  -S  option  was added in Issue 7, but had been provided by several
569       implementations for many years. The description given in  the  standard
570       documents  historic practice, but does not match much of the documenta‐
571       tion that described its behavior.  Historical  documentation  typically
572       described it as something like:
573
574       -S        Sort by size (largest size first) instead of by name. Special
575                 character devices (listed last) are sorted by name.
576
577       even though the file type was never considered when sorting the output.
578       Character  special files do typically sort close to the end of the list
579       because their file size on most implementations is zero. But  they  are
580       sorted alphabetically with any other files that happen to have the same
581       file size (zero), not sorted separately and added to the end.
582
583       This volume of POSIX.1‐2017 is frequently  silent  about  what  happens
584       when  mutually-exclusive  options are specified. Except for -R, -d, and
585       -f, the ls utility is required to accept  multiple  options  from  each
586       mutually-exclusive  option  set  without treating them as errors and to
587       use the behavior specified by the last option given in  each  mutually-
588       exclusive  set.  Since  ls  is  one of the most aliased commands, it is
589       important that the implementation perform intuitively. For example,  if
590       the alias were:
591
592
593           alias ls="ls -C"
594
595       and  the  user  typed  ls  -1  (one),  single-text-column output should
596       result, not an error.
597
598       The -g, -l  (ell),  -n,  and  -o  options  are  not  mutually-exclusive
599       options.  They  all  enable  long  format output. They work together to
600       determine whether the file's owner is written (no if  -g  is  present),
601       file's  group is written (no if -o is present), and if the file's group
602       or owner is written whether it is written as the name  (default)  or  a
603       string  representation of the UID or GID number (if -n is present). The
604       -C, -m, -x, and -1 (one) are mutually-exclusive options and  the  first
605       three of these disable long format output. The -1 (one) option does not
606       directly change whether or not long format output is  enabled,  but  by
607       overriding -C, -m, and -x, it can re-enable long format output that had
608       been disabled by one of these options.
609
610       Earlier versions of this standard did not describe the  BSD  -A  option
611       (like  -a,  but dot and dot-dot are not written out). It has been added
612       due to widespread implementation.
613
614       Implementations may make -q the default for terminals to prevent trojan
615       horse  attacks on terminals with special escape sequences.  This is not
616       required because:
617
618        *  Some control characters may be useful on some terminals; for  exam‐
619           ple, a system might write them as "\001" or "^A".
620
621        *  Special  behavior  for  terminals  is  not relevant to applications
622           portability.
623
624       An    early    proposal    specified    that    the    <optional alter‐
625       nate access method flag> had to be '+' if there was an alternate access
626       method used on the file or <space> if there was not. This  was  changed
627       to be <space> if there is not and a single printable character if there
628       is. This was done for three reasons:
629
630        1. There are historical implementations using  characters  other  than
631           '+'.
632
633        2. There  are  implementations  that  vary this character used in that
634           position to distinguish between various alternate access methods in
635           use.
636
637        3. The  standard developers did not want to preclude future specifica‐
638           tions that might need a way to  specify  more  than  one  alternate
639           access method.
640
641       Nonetheless, implementations providing a single alternate access method
642       are encouraged to use '+'.
643
644       Earlier versions of this standard did not have  the  -k  option,  which
645       meant  that  the -s option could not be used portably as its block size
646       was implementation-defined, and the units used to specify the number of
647       blocks  occupied by files in a directory in an ls -l listing were fixed
648       as 512-byte units. The -k option has been added to provide  a  way  for
649       the  -s option to be used portably, and for consistency it also changes
650       the aforementioned units from 512-byte to 1024-byte.
651
652       The <date and time> field in the -l format is specified  only  for  the
653       POSIX  locale.  As noted, the format can be different in other locales.
654       No  mechanism  for  defining  this  is  present  in  this   volume   of
655       POSIX.1‐2017,  as  the  appropriate vehicle is a messaging system; that
656       is, the format should be specified as a ``message''.
657

FUTURE DIRECTIONS

659       Allowing -f to ignore the -A, -g, -l, -n, -o, and  -s  options  may  be
660       removed in a future version.
661
662       A  future  version  of  this standard may require that if the collating
663       sequence for the current locale does not have a total ordering  of  all
664       characters, any filenames or pathnames that collate equally are further
665       compared byte-by-byte  using  the  collating  sequence  for  the  POSIX
666       locale.
667

SEE ALSO

669       chmod, find
670
671       The Base Definitions volume of POSIX.1‐2017, Section 7.3.2, LC_COLLATE,
672       Section 4.5, File Access Permissions, Chapter 8, Environment Variables,
673       Section 12.2, Utility Syntax Guidelines, <sys_stat.h>
674
675       The System Interfaces volume of POSIX.1‐2017, fstatat()
676
678       Portions  of  this text are reprinted and reproduced in electronic form
679       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
680       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
681       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
682       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
683       event of any discrepancy between this version and the original IEEE and
684       The  Open Group Standard, the original IEEE and The Open Group Standard
685       is the referee document. The original Standard can be  obtained  online
686       at http://www.opengroup.org/unix/online.html .
687
688       Any  typographical  or  formatting  errors that appear in this page are
689       most likely to have been introduced during the conversion of the source
690       files  to  man page format. To report such errors, see https://www.ker
691       nel.org/doc/man-pages/reporting_bugs.html .
692
693
694
695IEEE/The Open Group                  2017                               LS(1P)
Impressum