X-Git-Url: https://git.saurik.com/apple/file_cmds.git/blobdiff_plain/6c780a1f93b6cb2162f563ddae2d48867866f44c..b1f94ae5f07547562a35ed5aba901bdca1ae5dd0:/ls/ls.1?ds=inline

diff --git a/ls/ls.1 b/ls/ls.1
index 1672c13..12e8af5 100644
--- a/ls/ls.1
+++ b/ls/ls.1
@@ -42,21 +42,21 @@
 .Nm ls
 .Nd list directory contents
 .Sh SYNOPSIS
-.Nm
-.Op Fl ABCFGHLPRTWZabcdfghiklmnopqrstuwx1
+.Nm ls
+.Op Fl ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1
 .Op Ar
 .Sh DESCRIPTION
 For each operand that names a
 .Ar file
 of a type other than
 directory,
-.Nm
+.Nm ls
 displays its name as well as any requested,
 associated information.
 For each operand that names a
 .Ar file
 of type directory,
-.Nm
+.Nm ls
 displays the names of files contained
 within that directory, as well as any requested, associated
 information.
@@ -70,12 +70,27 @@ lexicographical order.
 .Pp
 The following options are available:
 .Bl -tag -width indent
+.It Fl @
+Display extended attribute keys and sizes in long
+.Pq Fl l
+output.
+.It Fl 1
+(The numeric digit
+.Dq one . )
+Force output to be
+one entry per line.
+This is the default when
+output is not to a terminal.
 .It Fl A
 List all entries except for
 .Pa \&.
 and
 .Pa .. .
 Always set for the super-user.
+.It Fl a
+Include directory entries whose names begin with a
+dot
+.Pq Pa \&. .
 .It Fl B
 Force printing of non-printable characters (as defined by
 .Xr ctype 3
@@ -84,8 +99,25 @@ and current locale settings) in file names as
 where
 .Va xxx
 is the numeric value of the character in octal.
+.It Fl b
+As
+.Fl B ,
+but use
+.Tn C
+escape codes whenever possible.
 .It Fl C
 Force multi-column output; this is the default when output is to a terminal.
+.It Fl c
+Use time when file status was last changed for sorting
+.Pq Fl t
+or long printing
+.Pq Fl l .
+.It Fl d
+Directories are listed as plain files (not searched recursively).
+.It Fl e
+Print the Access Control List (ACL) associated with the file, if present, in long
+.Pq Fl l
+output.
 .It Fl F
 Display a slash
 .Pq Ql /
@@ -106,12 +138,22 @@ and a vertical bar
 .Pq Ql \&|
 after each that is a
 .Tn FIFO .
+.It Fl f
+Output is not sorted.
+This option turns on the
+.Fl a
+option.
 .It Fl G
 Enable colorized output.
 This option is equivalent to defining
 .Ev CLICOLOR
 in the environment.
 (See below.)
+.It Fl g
+This option is only available for compatibility with POSIX;
+it is used to display the group name in the long
+.Pq Fl l
+format output (the owner name is suppressed).
 .It Fl H
 Symbolic links on the command line are followed.
 This option is assumed if
@@ -120,54 +162,6 @@ none of the
 or
 .Fl l
 options are specified.
-.It Fl L
-If argument is a symbolic link, list the file or directory the link references
-rather than the link itself.
-This option cancels the
-.Fl P
-option.
-.It Fl P
-If argument is a symbolic link, list the link itself rather than the
-object the link references.
-This option cancels the
-.Fl H
-and
-.Fl L
-options.
-.It Fl R
-Recursively list subdirectories encountered.
-.It Fl T
-When used with the
-.Fl l
-(lowercase letter
-.Dq ell )
-option, display complete time information for the file, including
-month, day, hour, minute, second, and year.
-.It Fl W
-Display whiteouts when scanning directories.
-.It Fl a
-Include directory entries whose names begin with a
-dot
-.Pq Pa \&. .
-.It Fl b
-As
-.Fl B ,
-but use
-.Tn C
-escape codes whenever possible.
-.It Fl c
-Use time when file status was last changed for sorting or printing.
-.It Fl d
-Directories are listed as plain files (not searched recursively).
-.It Fl f
-Output is not sorted.
-.It Fl g
-This option is deprecated and is only available for compatibility
-with
-.Bx 4.3 ;
-it was used to display the group name in the long
-.Pq Fl l
-format output.
 .It Fl h
 When used with the
 .Fl l
@@ -183,6 +177,12 @@ option is specified, print the file size allocation in kilobytes,
 not blocks.
 This option overrides the environment variable
 .Ev BLOCKSIZE .
+.It Fl L
+Follow all symbolic links to final target and list the file or directory the link references
+rather than the link itself.
+This option cancels the
+.Fl P
+option.
 .It Fl l
 (The lowercase letter
 .Dq ell . )
@@ -193,14 +193,27 @@ sizes is output on a line before the long listing.
 .It Fl m
 Stream output format; list files across the page, separated by commas.
 .It Fl n
-Display user and group IDs numerically rather than converting to a user
-or group name in a long
+Display user and group IDs numerically,
+rather than converting to a user or group name in a long
 .Pq Fl l
 output.
-.It Fl o
+This option turns on the
+.Fl l
+option.
+.It Fl O
 Include the file flags in a long
 .Pq Fl l
 output.
+.It Fl o
+List in long format, but omit the group id.
+.It Fl P
+If argument is a symbolic link, list the link itself rather than the
+object the link references.
+This option cancels the
+.Fl H
+and
+.Fl L
+options.
 .It Fl p
 Write a slash
 .Pq Ql /
@@ -210,9 +223,14 @@ Force printing of non-graphic characters in file names as
 the character
 .Ql \&? ;
 this is the default when output is to a terminal.
+.It Fl R
+Recursively list subdirectories encountered.
 .It Fl r
 Reverse the order of the sort to get reverse
-lexicographical order or the oldest entries first.
+lexicographical order or the oldest entries first (or largest files
+last, if combined with sort by size
+.It Fl S
+Sort files by size
 .It Fl s
 Display the number of file system blocks actually used by each file, in units
 of 512 bytes, where partial units are rounded up to the next integer value.
@@ -221,6 +239,13 @@ sizes is output on a line before the listing.
 The environment variable
 .Ev BLOCKSIZE
 overrides the unit size of 512 bytes.
+.It Fl T
+When used with the
+.Fl l
+(lowercase letter
+.Dq ell )
+option, display complete time information for the file, including
+month, day, hour, minute, second, and year.
 .It Fl t
 Sort by time modified (most recently modified
 first) before sorting the operands by lexicographical
@@ -230,8 +255,20 @@ Use time of last access,
 instead of last modification
 of the file for sorting
 .Pq Fl t
-or printing
+or long printing
+.Pq Fl l .
+.It Fl U
+Use time of file creation, instead of last modification for sorting
+.Pq Fl t
+or long output
 .Pq Fl l .
+.It Fl v
+Force unedited printing of non-graphic characters; this is the default when
+output is not to a terminal.
+.It Fl W
+Display whiteouts when scanning directories.
+.Pq Fl S
+flag).
 .It Fl w
 Force raw printing of non-printable characters.
 This is the default
@@ -241,24 +278,14 @@ The same as
 .Fl C ,
 except that the multi-column output is produced with entries sorted
 across, rather than down, the columns.
-.It Fl v
-Force unedited printing of non-graphic characters; this is the default when
-output is not to a terminal.
-.It Fl 1
-(The numeric digit
-.Dq one . )
-Force output to be
-one entry per line.
-This is the default when
-output is not to a terminal.
 .El
 .Pp
 The
 .Fl 1 , C , x ,
 and
 .Fl l
-options all override each other; the last one specified determines
-the format used.
+options all override each other;
+the last one specified determines the format used.
 .Pp
 The
 .Fl c
@@ -271,8 +298,9 @@ The
 .Fl B , b , w ,
 and
 .Fl q
-options all override each other; the last one specified determines
-the format used for non-printable characters.
+options all override each other;
+the last one specified determines the format used
+for non-printable characters.
 .Pp
 The
 .Fl H , L
@@ -282,7 +310,7 @@ options all override each other (either partially or fully); they
 are applied in the order specified.
 .Pp
 By default,
-.Nm
+.Nm ls
 lists one entry per line to standard
 output; the exceptions are to terminals or when the
 .Fl C
@@ -308,13 +336,23 @@ number of bytes in the file, abbreviated
 month, day-of-month file was last modified,
 hour file last modified, minute file last
 modified, and the pathname.
-In addition, for each directory whose contents are displayed, the total
-number of 512-byte blocks used by the files in the directory is displayed
-on a line by itself immediately before the information for the files in the
-directory.
+In addition, for each directory whose contents are displayed,
+the total number of 512-byte blocks used by the files in the directory
+is displayed on a line by itself,
+immediately before the information for the files in the directory.
+If the file or directory has extended attributes,
+the permissions field printed by the
+.Fl l
+option is followed by a '@' character.
+Otherwise, if the file or directory has extended security information
+(such as an access control list),
+the permissions field printed by the 
+.Fl l
+option is followed by a '+' character.
 .Pp
-If the modification time of the file is more than 6 months
-in the past or future, then the year of the last modification
+If the modification time of the file
+is more than 6 months in the past or future,
+then the year of the last modification
 is displayed in place of the hour and minute fields.
 .Pp
 If the owner or group names are not a known user or group name,
@@ -326,16 +364,16 @@ the numeric ID's are displayed.
 If the file is a character special or block special file,
 the major and minor device numbers for the file are displayed
 in the size field.
-If the file is a symbolic link the pathname of the
-linked-to file is preceded by
+If the file is a symbolic link,
+the pathname of the linked-to file is preceded by
 .Dq Li -> .
 .Pp
 The file mode printed under the
 .Fl l
 option consists of the
 entry type, owner permissions, and group permissions.
-The entry type character describes the type of file, as
-follows:
+The entry type character describes the type of file,
+as follows:
 .Pp
 .Bl -tag -width 4n -offset indent -compact
 .It Sy b
@@ -419,24 +457,15 @@ or
 .El
 .Sh EXAMPLES
 The following is how to do an
-.Nm
-listing sorted by size (and shows why
-.Nm
-does not need a separate option for this):
-.Pp
-.Dl "ls -l | sort -n +4"
+.Nm ls
+listing sorted by increasing size 
 .Pp
-Additionally, the
-.Fl r
-flag to
-.Xr sort 1
-may be used
-to get the results sorted from largest to smallest (a reverse sort).
+.Dl "ls -lrS"
 .Sh DIAGNOSTICS
 .Ex -std
 .Sh ENVIRONMENT
 The following environment variables affect the execution of
-.Nm :
+.Nm ls :
 .Bl -tag -width ".Ev CLICOLOR_FORCE"
 .It Ev BLOCKSIZE
 If the environment variable
@@ -489,7 +518,7 @@ decimal integer, it is used as the
 column position width for displaying
 multiple-text-column output.
 The
-.Nm
+.Nm ls
 utility calculates how
 many pathname text columns to display
 based on the width provided.
@@ -618,22 +647,58 @@ The group field is now automatically included in the long listing for
 files in order to be compatible with the
 .St -p1003.2
 specification.
+.Sh LEGACY DESCRIPTION
+In legacy mode, the
+.Fl f
+option does not turn on the
+.Fl a
+option and the
+.Fl g ,
+.Fl n ,
+and
+.Fl o
+options do not turn on the
+.Fl l
+option.
+.Pp
+Also, the
+.Fl o
+option causes the file flags to be included in a long (-l) output;
+there is no
+.Fl O
+option.
+.Pp
+When
+.Fl H
+is specified (and not overridden by
+.Fl L
+or
+.Fl P )
+and a file argument is a symlink
+that resolves to a non-directory file,
+the output will reflect the nature of the link,
+rather than that of the file.
+In legacy operation, the output will describe the file.
+.Pp
+For more information about legacy mode, see
+.Xr compat 5 .
 .Sh SEE ALSO
 .Xr chflags 1 ,
 .Xr chmod 1 ,
 .Xr sort 1 ,
 .Xr xterm 1 ,
+.Xr compat 5 ,
 .Xr termcap 5 ,
 .Xr symlink 7 ,
 .Xr sticky 8
 .Sh STANDARDS
 The
-.Nm
+.Nm ls
 utility conforms to
 .St -p1003.1-2001 .
 .Sh HISTORY
 An
-.Nm
+.Nm ls
 command appeared in
 .At v1 .
 .Sh BUGS