Fixed no stat'ing on -i option -- need to stat.

[unix-history] / usr / src / bin / ls / ls.1

diff --git a/usr/src/bin/ls/ls.1 b/usr/src/bin/ls/ls.1
index 8787348..eb9bed8 100644 (file)
--- a/usr/src/bin/ls/ls.1
+++ b/usr/src/bin/ls/ls.1
@@ -1,218 +1,299 @@
-.\" Copyright (c) 1980 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright 1980, 1990, 1991 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)ls.1        6.4 (Berkeley) %G%
+.\" This code is derived from software contributed to Berkeley by
+.\" the Institute of Electrical and Electronics Engineers, Inc.

 .\"
 .\"

-.TH LS 1 ""
-.UC
-.SH NAME
-ls \- list contents of directory
-.SH SYNOPSIS
-.B ls
-[
-.B \-acdfgilqrstu1ACLFR
-] name ...
-.br
-.SH DESCRIPTION
-For each directory argument,
-.I ls
-lists the contents of the directory;
-for each file argument,
-.I ls
-repeats its name and any other information requested.
-By default, the output is sorted alphabetically.
-When no argument is given, the current directory is listed.
-When several arguments are given,
-the arguments are first sorted appropriately,
-but file arguments are processed
-before directories and their contents.
-.PP
-There are a large number of options:
-.TP
-.B \-l
-List in long format, giving mode, number of links, owner,
-size in bytes, and time of last modification
-for each file.
-(See below.)
-If the file is a special file the size field will instead contain
-the major and minor device numbers.
-If the file is a symbolic link the pathname of
-the linked-to file is printed preceded by ``\->''.
-.TP
-.B \-g
-Include the group ownership of the file in a long output.
-.TP
-.B \-t
-Sort by time modified (latest first) instead of
-by name.
-.TP
-.B \-a
-List all entries; in the absence of this option, entries whose
-names begin with a period
-.RB ( . )
-are
-.I not
-listed.
-.TP
-.B \-s
-Give size in kilobytes of each file.
-.TP
-.B \-d
-If argument is a directory, list only its name;
-often used with \fB\-l\fR to get the status of a directory.
-.TP
-.B \-L
+.\" %sccs.include.redist.roff%
+.\"
+.\"     @(#)ls.1       6.20 (Berkeley) %G%
+.\"
+.Dd 
+.Dt LS 1
+.Os
+.Sh NAME
+.Nm ls
+.Nd list directory contents
+.Sh SYNOPSIS
+.Nm ls
+.Op Fl CFRacdilqrstu1
+.Op Ar file ...
+.Sh DESCRIPTION
+For each operand that names a
+.Ar file
+of a type other than
+directory,
+.Nm ls
+displays its name as well as any requested,
+associated information.
+For each operand that names a
+.Ar file
+of type directory,
+.Nm ls
+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
+List all entries except for
+.Ql \&.
+and
+.Ql \&.. .
+Always set for the super-user.
+.It Fl C
+Force multi-column output; this is the default when output is to a terminal.
+.It Fl F
+Display a slash (/) immediately after each pathname
+that is a directory, an asterisk (*) after each that is
+executable,
+and an at sign (@) after each symbolic link.
+.\"and a vertical bar (|) after
+.\"each that is a
+.\".Tn FIFO . 
+.It Fl L

 If argument is a symbolic link, list the file or directory the link references
 rather than the link itself.
 If argument is a symbolic link, list the file or directory the link references
 rather than the link itself.

-.TP
-.B \-r
-Reverse the order of sort to get reverse alphabetic
-or oldest first as appropriate.
-.TP
-.B \-u
-Use time of last access instead of last
-modification for sorting
-(with the \fB\-t\fP option)
-and/or printing (with the \fB\-l\fP option).
-.TP
-.B \-c
-Use time of file creation for sorting or printing.
-.TP
-.B \-i
-For each file, print the i-number in the first column of the report.
-.TP
-.B \-f
-Force each argument to be interpreted as a directory
-and list the name found in each slot.
-This option turns off
-.B "\-l, \-t, \-s,"
+.It Fl R
+Recursively list subdirectories encountered.
+.It Fl T
+Display complete time information for the file, including
+month, day, hour, minute, second, and year.
+.It Fl a
+Include directory entries whose names begin with a
+dot (.).
+.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) and
+symbolic links in the argument list are not indirected through.
+.It Fl f
+Output is not sorted.
+.It Fl g
+Include the group ownership of the file in a long
+.Pq Fl l
+output
+.Pq Fl lg .
+If the group is not a known group name, the numeric ID
+is printed.
+.It Fl i
+For each file, print the file's file serial number (inode number).
+.It Fl k
+Modifies the
+.Fl s
+option, causing the sizes to be reported in kilobytes.
+.It Fl l
+(The lowercase letter ``ell.'')  List in long format. (See below.)
+If the output is to a terminal, a total sum for all the file
+sizes is output on a line before the long listing.
+.It Fl g
+Include the file flags in a long
+.Pq Fl l
+output
+.It Fl q
+Force printing of non-graphic characters in file names as
+the character `?'; this is the default when output is to a terminal.
+.It Fl r
+Reverse the order of the sort to get reverse
+lexicographical order or the oldest entries first.
+.It Fl s
+Display the number of file system bytes actually
+used by each file, in units of 512, where partial
+units are rounded up to the next integer value.
+If the output is to a terminal, a total sum for all the file
+sizes is output on a line before the listing.
+.It Fl t
+Sort by time modified (most recently modified
+first) before sorting the operands by lexicographical
+order.
+.It Fl u
+Use time of last access,
+instead of last modification
+of the file for sorting
+.Pq Fl t
+or printing
+.Pq Fl l .
+.It Fl \&1
+(The numeric digit ``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 ,
+.Fl C ,

 and
 and

-.B \-r,
+.Fl l
+options all override each other; the last one specified determines
+the format used.
+.Pp
+The
+.Fl c ,

 and
 and

-turns on
-.B \-a;
-the order is the order in which entries
-appear in the directory.
-.TP
-.B \-F
-cause directories to be marked with a trailing `/',
-sockets with a trailing `=',
-symbolic links with a trailing `@', and executable
-files with a trailing `*'.
-.TP
-.B \-R
-recursively list subdirectories encountered.
-.TP
-.B \-1
-force one entry per line output format; this is the default when
-output is not to a terminal.
-.TP
-.B \-C
-force multi-column output; this is the default when output is to a terminal.
-.TP
-.B \-q
-force printing of non-graphic characters in file names as
-the character `?'; this is the default when output is to a terminal.
-.PP
-The mode printed under the
-.B \-l
-option contains 11 characters
-which are interpreted
-as follows:
-the first character is
-.TP 3
-.B d
-if the entry is a directory;
-.br
-.ns
-.TP 3
-.B b
-if the entry is a block-type special file;
-.br
-.ns
-.TP 3
-.B c
-if the entry is a character-type special file;
-.br
-.ns
-.TP 3
-.B l
-if the entry is a symbolic link;
-.br
-.ns
-.TP
-.B s
-if the entry is a socket, or
-.br
-.ns
-.TP 3
-.B  \-
-if the entry is a plain file.
-.PP
-The next 9 characters are interpreted
-as three sets of three bits each.
-The first set refers to owner permissions;
-the next refers to permissions to others in the same user-group;
-and the last to all others.
-Within each set the three characters indicate
-permission respectively to read, to write, or to
-execute the file as a program.
-For a directory, `execute' permission is interpreted
-to mean permission to search the directory.
-The permissions are indicated as follows:
-.TP 3
-.B  r
-if the file is readable;
-.br
-.ns
-.TP 3
-.B  w
-if the file is writable;
-.br
-.ns
-.TP 3
-.B  x
-if the file is executable;
-.br
-.ns
-.TP 3
-.B  \-
-if the indicated permission is not granted.
-.PP
-The group-execute permission character is given
-as
-.B s
-if the file has the set-group-id bit set;
-likewise the user-execute permission character is given
-as
-.B s
-if the file has the set-user-id bit set.
-.PP
-The last character of the mode (normally `x' or `\-') is 
-.B t
-if the 1000 bit of the mode is on.
-See
-.IR  chmod (1)
-for the meaning of this mode.
-.PP
-When the sizes of the files in a directory
-are listed, a total count of blocks,
-including indirect blocks is printed.
-.SH FILES
-/etc/passwd to get user id's for
-`ls \-l'.
-.br
-/etc/group to get group id's for
-`ls \-g'.
-.SH BUGS
-Newline and tab are considered printing characters in file names.
-.PP
-The output device is assumed to be 80 columns wide.
-.PP
-The option setting based on whether the output is a teletype is
-undesirable as ``ls\ \-s'' is much different than ``ls\ \-s\ |\ lpr''.
-On the other hand, not doing this setting would make old shell scripts
-which used
-.I ls
-almost certain losers.
+.Fl u
+options override each other; the last one specified determines
+the file time used.
+.Pp
+By default,
+.Nm ls
+lists one entry per line to standard
+output; the exceptions are to terminals or when the
+.Fl C
+option is specified.
+.Pp
+File information is displayed with one or more
+<blank>s separating the information associated with the
+.Fl i ,
+.Fl s ,
+and
+.Fl l
+options.
+.Ss The Long Format
+If the
+.Fl l
+option is given, the following information
+is be displayed:
+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 owner name is not a known user name
+the numeric ID is displayed.
+.Pp
+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
+.Dq \-> .
+.Pp
+The file mode printed under the -l option consists of the
+the entry type, owner permissions, and group permissions.
+The entry type character describes the type of file, as
+follows:
+.Pp
+.Bl -tag -width 4n -offset indent -compact
+.It Sy b
+Block special file.
+.It Sy c
+Character special file.
+.It Sy d
+Directory.
+.It Sy l
+Symbolic link.
+.It Sy s
+Socket link.
+.\" .It Sy p
+.\" .Tn FIFO .
+.It Sy \-
+Regular file.
+.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, writeable, exectutable,
+or set-user-ID or 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 8 . )
+.It Sy t
+The sticky bit is set (mode
+.Li 1000 ) ,
+and is searcheable or executable.
+(See
+.Xr chmod 1
+or
+.Xr sticky 8 . )
+.El
+.El
+.Pp
+The
+.Nm ls
+utility exits 0 on success, and >0 if an error occurs.
+.Sh ENVIRONMENT
+The following environment variables affect the execution of
+.Nm ls :
+.Bl -tag -width COLUMNS
+.It COLUMNS
+If this variable contains a string representing a
+decimal integer, it is used as the
+column position width for displaying
+multiple-text-column output.
+The
+.Nm ls
+utility calculates how
+many pathname text columns to display
+based on the width provided.
+(See
+.Fl C . )
+.El
+.Sh SEE ALSO
+.Xr chmod 1 ,
+.Xr sticky 8
+.Sh HISTORY
+A
+.Nm ls
+command appeared in
+.At v6 .
+.\" .Sh STANDARDS
+.\" .The
+.\" .Nm ls
+.\" function is expected to be
+.\" .Tn POSIX
+.\" 1003.2 compatible.