Add 'corebinutils/ls/' from commit '06b170dd48138a26fdfe1b822ba9846a26a2fa0f'

git-subtree-dir: corebinutils/ls
git-subtree-mainline: ec6a123cffbe492c576ec1ad545d5296321a86e1
git-subtree-split: 06b170dd48138a26fdfe1b822ba9846a26a2fa0f

1 files changed, 792 insertions, 0 deletions

diff --git a/corebinutils/ls/ls.1 b/corebinutils/ls/ls.1
new file mode 100644
index 0000000000..21ece833dc
--- /dev/null
+++ b/corebinutils/ls/ls.1
@@ -0,0 +1,792 @@
+.\"-
+.\" Copyright (c) 1980, 1990, 1991, 1993, 1994
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Copyright (c) 2026
+.\" Project Tick. All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" the Institute of Electrical and Electronics Engineers, Inc.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd January 16, 2025
+.Dt LS 1
+.Os
+.Sh NAME
+.Nm ls
+.Nd list directory contents
+.Sh SYNOPSIS
+.Nm
+.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuvwxy1\&,
+.Op Fl -color Ns = Ns Ar when
+.Op Fl -group-directories Ns = Ns Ar order
+.Op Fl -group-directories-first
+.Op Fl D Ar format
+.Op Ar
+.Sh DESCRIPTION
+For each operand that names a
+.Ar file
+of a type other than
+directory,
+.Nm
+displays its name as well as any requested,
+associated information.
+For each operand that names a
+.Ar file
+of type directory,
+.Nm
+displays the names of files contained
+within that directory, as well as any requested, associated
+information.
+.Pp
+If no operands are given, the contents of the current
+directory are displayed.
+If more than one operand is given,
+non-directory operands are displayed first; directory
+and non-directory operands are sorted separately and in
+lexicographical order.
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl A
+Include directory entries whose names begin with a
+dot
+.Pq Sq Pa \&.
+except for
+.Pa \&.
+and
+.Pa .. .
+Automatically set for the super-user unless
+.Fl I
+is specified.
+.It Fl B
+Force printing of non-printable characters (as defined by
+.Xr ctype 3
+and current locale settings) in file names as
+.Li \e Ns Va xxx ,
+where
+.Va xxx
+is the numeric value of the character in octal.
+This option is not defined in
+.St -p1003.1-2008 .
+.It Fl C
+Force multi-column output; this is the default when output is to a terminal.
+.It Fl D Ar format
+When printing in the long
+.Pq Fl l
+format, use
+.Ar format
+to format the date and time output.
+The argument
+.Ar format
+is a string used by
+.Xr strftime 3 .
+Depending on the choice of format string, this may result in a
+different number of columns in the output.
+This option overrides the
+.Fl T
+option.
+This option is not defined in
+.St -p1003.1-2008 .
+.It Fl F
+Display a slash
+.Pq Ql /
+immediately after each pathname that is a directory,
+an asterisk
+.Pq Ql *
+after each that is executable,
+an at sign
+.Pq Ql @
+after each symbolic link,
+an equals sign
+.Pq Ql =
+after each socket,
+and a vertical bar
+.Pq Ql \&|
+after each that is a
+.Tn FIFO .
+.It Fl G
+Enable colorized output.
+This option is equivalent to defining
+.Ev CLICOLOR
+or
+.Ev COLORTERM
+in the environment and setting
+.Fl -color Ns = Ns Ar auto .
+(See below.)
+This functionality can be compiled out by removing the definition of
+.Ev COLORLS .
+This option is not defined in
+.St -p1003.1-2008 .
+.It Fl H
+Symbolic links on the command line are followed.
+This option is assumed if
+none of the
+.Fl F , d ,
+or
+.Fl l
+options are specified.
+.It Fl I
+Prevent
+.Fl A
+from being automatically set for the super-user.
+This option is not defined in
+.St -p1003.1-2008 .
+.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 S
+Sort by size (largest file first) before sorting the operands in
+lexicographical order.
+.It Fl T
+When printing in the long
+.Pq Fl l
+format, display complete time information for the file, including
+month, day, hour, minute, second, and year.
+The
+.Fl D
+option gives even more control over the output format.
+This option is not defined in
+.St -p1003.1-2008 .
+.It Fl U
+Use time when file was created for sorting or printing.
+On this Linux port,
+.Nm
+uses
+.Xr statx 2
+when the kernel and backing filesystem expose creation time; otherwise it falls
+back to the file's modification time.
+This option is not defined in
+.St -p1003.1-2008 .
+.It Fl W
+Reserved for FreeBSD compatibility.
+FreeBSD whiteout directory entries are not available through Linux VFS, so this
+port rejects
+.Fl W
+with an error.
+This option is not defined in
+.St -p1003.1-2008 .
+.It Fl Z
+Reserved for FreeBSD compatibility.
+FreeBSD MAC labels do not have a portable Linux userland equivalent in this
+port, so
+.Fl Z
+is rejected with an error.
+This option is not defined in
+.St -p1003.1-2008 .
+.It Fl a
+Include directory entries whose names begin with a
+dot
+.Pq Sq Pa \&. .
+.It Fl b
+As
+.Fl B ,
+but use
+.Tn C
+escape codes whenever possible.
+This option is not defined in
+.St -p1003.1-2008 .
+.It Fl c
+Use time when file status was last changed for sorting or printing.
+.It Fl -color Ns = Ns Ar when
+Output colored escape sequences based on
+.Ar when ,
+which may be set to either
+.Cm always ,
+.Cm auto ,
+or
+.Cm never .
+.Pp
+.Cm always
+will make
+.Nm
+always output
+.Tn ANSI
+color escape sequences.
+.Cm always
+is the default if
+.Fl -color
+is specified without an argument.
+.Pp
+.Cm auto
+will make
+.Nm
+output
+.Tn ANSI
+color escape sequences, but only if
+.Dv stdout
+is a tty and either the
+.Fl G
+flag is specified or one of the environment variables
+.Ev COLORTERM
+or
+.Ev CLICOLOR
+is set and not empty.
+.Pp
+.Cm never
+will disable color regardless of environment variables.
+.Cm never
+is the default when neither
+.Fl -color
+nor
+.Fl G
+is specified.
+.Pp
+For compatibility with GNU coreutils,
+.Nm
+supports
+.Cm yes
+or
+.Cm force
+as equivalent to
+.Cm always ,
+.Cm no
+or
+.Cm none
+as equivalent to
+.Cm never ,
+and
+.Cm tty
+or
+.Cm if-tty
+as equivalent to
+.Cm auto .
+.It Fl d
+Directories are listed as plain files (not searched recursively).
+.It Fl f
+Output is not sorted.
+This option turns on
+.Fl a .
+It also negates the effect of the
+.Fl r ,
+.Fl S
+and
+.Fl t
+options.
+As allowed by
+.St -p1003.1-2008 ,
+this option has no effect on the
+.Fl d ,
+.Fl l ,
+.Fl R
+and
+.Fl s
+options.
+.It Fl g
+Display the long
+.Pq Fl l
+format output without the file owner's name or number.
+.It Fl -group-directories Ns = Ns Ar order
+Within results for each operand,
+group directories together and print them either
+.Cm first
+or
+.Cm last.
+.It Fl -group-directories-first
+Equivalent to
+.Fl -group-directories Ns = Ns Ar first .
+Implemented for compatibility with GNU coreutils.
+.It Fl h
+When used with the
+.Fl l
+option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte
+and Petabyte in order to reduce the number of digits to four or fewer
+using base 2 for sizes.
+This option is not defined in
+.St -p1003.1-2008 .
+.It Fl i
+For each file, print the file's file serial number (inode number).
+.It Fl k
+Use 1024-byte units for block counts.
+This option also nullifies any
+.Fl h
+options to its left.
+.It Fl l
+(The lowercase letter
+.Dq ell . )
+List files in the long format, as described in the
+.Sx The Long Format
+subsection below.
+.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
+.Pq Fl l
+output.
+.It Fl o
+Reserved for FreeBSD compatibility.
+FreeBSD file flags are not exposed through a portable Linux interface, so this
+port rejects
+.Fl o
+with an error instead of emulating filesystem-specific behavior.
+.It Fl p
+Write a slash
+.Pq Ql /
+after each filename if that file is a directory.
+.It Fl q
+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
+Reverse the order of the sort.
+.It Fl s
+Display the number of blocks used in the file system by each file.
+Block sizes and directory totals are handled as described in
+.Sx The Long Format
+subsection below, except (if the long format is not also requested)
+the directory totals are not output when the output is in a
+single column, even if multi-column output is requested.
+.It Fl t
+Sort by descending time modified (most recently modified first).
+If two files have the same modification timestamp, sort their names
+in ascending lexicographical order.
+The
+.Fl r
+option reverses both of these sort orders.
+.Pp
+Note that these sort orders are contradictory: the time sequence is in
+descending order, the lexicographical sort is in ascending order.
+This behavior is mandated by
+.St -p1003.2 .
+This feature can cause problems listing files stored with sequential names on
+FAT file systems, such as from digital cameras, where it is possible to have
+more than one image with the same timestamp.
+In such a case, the photos cannot be listed in the sequence in which
+they were taken.
+To ensure the same sort order for time and for lexicographical sorting, set the
+environment variable
+.Ev LS_SAMESORT
+or use the
+.Fl y
+option.
+This causes
+.Nm
+to reverse the lexicographical sort order when sorting files with the
+same modification timestamp.
+.It Fl u
+Use time of last access,
+instead of time of last modification
+of the file for sorting
+.Pq Fl t
+or printing
+.Pq Fl l .
+.It Fl v
+Sort following a natural ordering, using
+.Xr strverscmp 3
+instead of
+.Xr strcoll 3
+as the comparison function.
+E.g., files lexicographically ordered
+"bloem1", "bloem10", and "bloem9" would instead be ordered
+"bloem1", "bloem9", and "bloem10", as one would perhaps expect.
+.It Fl w
+Force raw printing of non-printable characters.
+This is the default
+when output is not to a terminal.
+This option is not defined in
+.St -p1003.1-2001 .
+.It Fl x
+The same as
+.Fl C ,
+except that the multi-column output is produced with entries sorted
+across, rather than down, the columns.
+.It Fl y
+When the
+.Fl t
+option is set, sort the alphabetical output in the same order as the time output.
+This has the same effect as setting
+.Ev LS_SAMESORT .
+See the description of the
+.Fl t
+option for more details.
+This option is not defined in
+.St -p1003.1-2001 .
+.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 ,
+(Comma) When the
+.Fl l
+or
+.Fl s
+option is set, print file sizes grouped and separated by thousands using the
+non-monetary separator returned by
+.Xr localeconv 3 ,
+typically a comma or period.
+If no locale is set, or the locale does not have a non-monetary separator, this
+option has no effect.
+This option is not defined in
+.St -p1003.1-2001 .
+.El
+.Pp
+The
+.Fl 1 , C , x ,
+and
+.Fl l
+options all override each other; the last one specified determines
+the format used.
+.Pp
+The
+.Fl c , u ,
+and
+.Fl U
+options all override each other; the last one specified determines
+the file time used.
+.Pp
+The
+.Fl S , t
+and
+.Fl v
+options override each other; the last one specified determines
+the sort order used.
+.Pp
+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.
+.Pp
+The
+.Fl H , L
+and
+.Fl P
+options all override each other (either partially or fully); they
+are applied in the order specified.
+.Pp
+By default,
+.Nm
+lists one entry per line to standard
+output; the exceptions are to terminals or when the
+.Fl C
+or
+.Fl x
+options are specified.
+.Pp
+File information is displayed with one or more
+.Ao blank Ac Ns s
+separating the information associated with the
+.Fl i , s ,
+and
+.Fl l
+options.
+.Ss The Long Format
+If the
+.Fl l
+option is given, the following information
+is displayed for each file:
+file mode,
+number of links, owner name, group name,
+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.
+.Pp
+If the modification time of the file is more than 6 months
+in the past or future, and the
+.Fl D
+or
+.Fl T
+are not specified,
+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,
+or the
+.Fl n
+option is given,
+the numeric ID's are displayed.
+.Pp
+If the file is a character special or block special file,
+the device number for the file is displayed in the size field.
+If the file is a symbolic link the pathname of the
+linked-to file is preceded by
+.Dq Li -> .
+.Pp
+The listing of a directory's contents is preceded
+by a labeled total number of blocks used in the file system by the files
+which are listed as the directory's contents
+(which may or may not include
+.Pa \&.
+and
+.Pa ..
+and other files which start with a dot, depending on other options).
+If the
+.Fl h
+option is given,
+the total size is displayed as the number of bytes.
+.Pp
+The default block size is 512 bytes.
+The block size may be set with option
+.Fl k .
+Numbers of blocks in the output will have been rounded up so the
+numbers of bytes is at least as many as used by the corresponding
+file system blocks (which might have a different size).
+.Pp
+The file mode printed under the
+.Fl l
+option consists of the
+entry type and the permissions.
+The entry type character describes the type of file, as
+follows:
+.Pp
+.Bl -tag -width 4n -offset indent -compact
+.It Sy \-
+Regular file.
+.It Sy b
+Block special file.
+.It Sy c
+Character special file.
+.It Sy d
+Directory.
+.It Sy l
+Symbolic link.
+.It Sy p
+.Tn FIFO .
+.It Sy s
+Socket.
+.El
+.Pp
+The next three fields
+are three characters each:
+owner permissions,
+group permissions, and
+other permissions.
+Each field has three character positions:
+.Bl -enum -offset indent
+.It
+If
+.Sy r ,
+the file is readable; if
+.Sy \- ,
+it is not readable.
+.It
+If
+.Sy w ,
+the file is writable; if
+.Sy \- ,
+it is not writable.
+.It
+The first of the following that applies:
+.Bl -tag -width 4n -offset indent
+.It Sy S
+If in the owner permissions, the file is not executable and
+set-user-ID mode is set.
+If in the group permissions, the file is not executable
+and set-group-ID mode is set.
+.It Sy s
+If in the owner permissions, the file is executable
+and set-user-ID mode is set.
+If in the group permissions, the file is executable
+and setgroup-ID mode is set.
+.It Sy x
+The file is executable or the directory is
+searchable.
+.It Sy \-
+The file is neither readable, writable, executable,
+nor set-user-ID nor set-group-ID mode, nor sticky.
+(See below.)
+.El
+.Pp
+These next two apply only to the third character in the last group
+(other permissions).
+.Bl -tag -width 4n -offset indent
+.It Sy T
+The sticky bit is set
+(mode
+.Li 1000 ) ,
+but not execute or search permission.
+(See
+.Xr chmod 1
+or
+.Xr sticky 7 . )
+.It Sy t
+The sticky bit is set (mode
+.Li 1000 ) ,
+and is searchable or executable.
+(See
+.Xr chmod 1
+or
+.Xr sticky 7 . )
+.El
+.El
+.Pp
+This Linux port does not print FreeBSD file flags, MAC labels, or ACL
+markers in long output.
+.Sh ENVIRONMENT
+The following environment variables affect the execution of
+.Nm :
+.Bl -tag -width ".Ev CLICOLOR_FORCE"
+.It Ev CLICOLOR
+Use
+.Tn ANSI
+color sequences to distinguish file types.
+Colorization is automatically disabled unless output is directed to a terminal,
+unless
+.Ev CLICOLOR_FORCE
+is set or
+.Fl -color
+is set to
+.Cm always .
+.It Ev CLICOLOR_FORCE
+Force color sequences even when standard output is not a terminal.
+.It Ev COLORTERM
+Enable the same color behavior as
+.Ev CLICOLOR
+when set and non-empty.
+.It Ev COLUMNS
+If this variable contains a decimal integer, it is used as the width for
+multi-column output.
+.It Ev LANG
+The locale to use when formatting dates and when sorting names with
+.Xr strcoll 3 .
+See
+.Xr environ 7
+for more information.
+.It Ev LS_SAMESORT
+If this variable is set, the
+.Fl t
+option sorts the names of files with the same modification timestamp in the same
+sense as the time sort.
+See the description of the
+.Fl t
+option for more details.
+.It Ev TZ
+The timezone to use when displaying dates.
+See
+.Xr environ 7
+for more information.
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+List the contents of the current working directory in long format:
+.Pp
+.Dl $ ls -l
+.Pp
+In addition to listing the contents of the current working directory in
+long format, show inode numbers, and suffix each filename with a symbol
+representing its file type:
+.Pp
+.Dl $ ls -liF
+.Pp
+List the files in
+.Pa /var/log ,
+sorting the output such that the mostly recently modified entries are
+printed first:
+.Pp
+.Dl $ ls -lt /var/log
+.Sh COMPATIBILITY
+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 SEE ALSO
+.Xr chmod 1 ,
+.Xr sort 1 ,
+.Xr xterm 1 Pq Pa ports/x11/xterm ,
+.Xr localeconv 3 ,
+.Xr statx 2 ,
+.Xr strcoll 3 ,
+.Xr strftime 3 ,
+.Xr strmode 3 ,
+.Xr strverscmp 3 ,
+.Xr sticky 7 ,
+.Xr symlink 7
+.Sh STANDARDS
+With the exception of options
+.Fl g
+and
+.Fl n ,
+the
+.Nm
+utility conforms to
+.St -p1003.1-2001
+and
+.St -p1003.1-2008 .
+The options
+.Fl B , D , G , I , T , U , W , Z , b , h , o , v , w , y
+,
+.Fl ,
+.Fl -color
+and
+.Fl -group-directories Ns =
+(including
+.Fl -group-directories-first )
+are non-standard extensions.
+.Pp
+On this Linux port,
+.Fl o ,
+.Fl W ,
+and
+.Fl Z
+are accepted for command-line compatibility but fail with an error instead of
+providing FreeBSD-only semantics.
+.Sh HISTORY
+An
+.Nm
+command appeared in
+.At v1 .
+.Pp
+The
+.Fl v
+option was added in
+.Fx 13.2 .
+.Sh BUGS
+To maintain backward compatibility, the relationships between the many
+options are quite complex.
+.Pp
+The exception mentioned in the
+.Fl s
+option description might be a feature that was
+based on the fact that single-column output
+usually goes to something other than a terminal.
+It is debatable whether this is a design bug.
+.Pp
+.St -p1003.2
+mandates opposite sort orders for files with the same timestamp when
+sorting with the
+.Fl t
+option.