1 files changed, 434 insertions, 0 deletions

diff --git a/usr.bin/stat/stat.1 b/usr.bin/stat/stat.1
new file mode 100644
index 0000000000000..cd238233e1f3c
--- /dev/null
+++ b/usr.bin/stat/stat.1
@@ -0,0 +1,434 @@
+.\"	$NetBSD: stat.1,v 1.4 2002/05/09 17:52:03 atatat Exp $
+.\"
+.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Andrew Brown and Jan Schaumann.
+.\"
+.\" 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. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd April 24, 2002
+.Dt STAT 1
+.Os
+.Sh NAME
+.Nm stat
+.Nd display file status
+.Sh SYNOPSIS
+.Nm
+.Op Fl FLn
+.Oo
+.Fl f Ar format |
+.Fl l |
+.Fl r |
+.Fl s |
+.Fl x
+.Oc
+.Op Fl t Ar timefmt
+.Op Ar
+.Sh DESCRIPTION
+The
+.Nm
+utility displays information about the file pointed to by
+.Ar file .
+Read, write or execute permissions of the named file are not required, but
+all directories listed in the path name leading to the file must be
+searchable.  If no argument is given,
+.Nm
+displays information about the file descriptor for standard input.
+.Pp
+The information displayed is obtained by calling
+.Xr lstat 2
+with the given argument and evaluating the returned structure.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl F
+As in
+.Ic ls ,
+display a slash (/) immediately after each pathname that is a directory, an
+asterisk (*) after each that is executable, an at sign (@) after each symbolic
+link, a percent sign (%) after each whiteout, an equal sign (=) after each
+socket, and a vertical bar (|) after each that is a FIFO.  The use of
+.Fl F
+implies
+.Fl l .
+.It Fl L
+Use
+.Xr stat 2
+instead of
+.Xr lstat 2 .
+The information reported by
+.Nm
+will refer to the target of
+.Ar file ,
+if file is a symbolic link, and not to
+.Ar file
+itself.
+.It Fl n
+Do not force a newline to appear at the end of each piece of output.
+.It Fl f Ar format
+Display information using the specified format.  See the FORMATS section
+for a description of valid formats.
+.It Fl l
+Display output in
+.Ic ls Fl lT
+format.
+.It Fl r
+Display raw information.  That is, for all the fields in the stat-structure,
+display the raw, numerical value (for example, times in seconds since the
+epoch, etc.)
+.It Fl s
+Display information in ``shell output'', suitable for initializing variables.
+.It Fl x
+Display information in a more verbose way as known from some Linux
+distributions.
+.It Fl t Ar timefmt
+Display timestamps using the specified format.  This format is
+passed directly to
+.Xr strftime 3 .
+.El
+.Ss FORMATS
+Format strings are similar to
+.Xr printf 3
+formats in that they start with
+.Cm % ,
+are then followed by a sequence of formatting characters, and end in
+a character that selects the field of the struct stat which is to be
+formatted.  If the
+.Cm %
+is immediately followed by one of
+.Cm n ,
+.Cm t ,
+.Cm % ,
+or
+.Cm @ ,
+then a newline character, a tab character, a percent character,
+or the current file number is printed, otherwise the string is
+examined for the following:
+.Pp
+Any of the following optional flags:
+.Bl -tag -width Ds
+.It Cm #
+Selects an alternate output form for octal and hexadecimal output.
+Non-zero octal output will have a leading zero, and non-zero
+hexadecimal output will have ``0x'' prepended to it.
+.It Cm +
+Asserts that a sign indicating whether a number is positive or negative
+should always be printed.  Non-negative numbers are not usually printed
+with a sign.
+.It Cm -
+Aligns string output to the left of the field, instead of to the right.
+.It Cm 0
+Sets the fill character for left padding to the 0 character, instead of
+a space.
+.It space
+Reserves a space at the front of non-negative signed output fields.  A
+.Sq Cm +
+overrides a space if both are used.
+.El
+.Pp
+Then the following fields:
+.Bl -tag -width Ds
+.It Cm size
+An optional decimal digit string specifying the minimum field width.
+.It Cm prec
+An optional precision composed of a decimal point
+.Sq Cm \&.
+and a decimal digit string that indicates the maximum string length,
+the number of digits to appear after the decimal point in floating point
+output, or the minimum number of digits to appear in numeric output.
+.It Cm fmt
+An optional output format specifier which is one of
+.Cm D ,
+.Cm O ,
+.Cm U ,
+.Cm X ,
+.Cm F ,
+or
+.Cm S .
+These represent signed decimal output, octal output, unsigned decimal
+output, hexadecimal output, floating point output, and string output,
+respectively.  Some output formats do not apply to all fields.
+Floating point output only applies to timespec fields (the
+.Cm a ,
+.Cm m ,
+and
+.Cm c
+fields).
+.Pp
+The special output specifier
+.Cm S
+may be used to indicate that the output, if
+applicable, should be in string format.  May be used in combination with
+.Bl -tag -width Ds
+.It Cm amc
+Display date in strftime(3) format.
+.It Cm dr
+Display actual device name.
+.It Cm gu
+Display group or user name.
+.It Cm p
+Display the mode of
+.Ar file
+as in
+.Ic ls -lTd .
+.It Cm N
+Displays the name of
+.Ar file .
+.It Cm T
+Displays the type of
+.Ar file .
+.It Cm Y
+Insert a `` -\*[Gt] '' into the output.  Note that the default output format
+for
+.Cm Y
+is a string, but if specified explicitly, these four characters are
+prepended.
+.El
+.It Cm sub
+An optional sub field specifier (high, middle, low).  Only applies to
+the
+.Cm p ,
+.Cm d ,
+.Cm r ,
+and
+.Cm T
+output formats.  It can be one of the following:
+.Bl -tag -width Ds
+.It Cm H
+``High'' -- specifies the major number for devices from
+.Cm r
+or
+.Cm d ,
+the ``user'' bits for permissions from the string form of
+.Cm p ,
+the file ``type'' bits from the numeric forms of
+.Cm p ,
+and the long output form of
+.Cm T .
+.It Cm L
+``Low'' -- specifies the minor number for devices from
+.Cm r
+or
+.Cm d ,
+the ``other'' bits for permissions from the string form of
+.Cm p ,
+the ``user'', ``group'', and ``other'' bits from the numeric forms of
+.Cm p ,
+and the
+.Ic ls -F
+style output character for file type when used with
+.Cm T
+(the use of
+.Cm L
+for this is optional).
+.It Cm M
+``Middle'' -- specifies the ``group'' bits for permissions from the
+string output form of
+.Cm p ,
+or the ``suid'', ``sgid'', and ``sticky'' bits for the numeric forms of
+.Cm p .
+.El
+.It Cm datum
+A required field specifier, being one of the following:
+.Bl -tag -width Ds
+.It Cm d
+Device upon which
+.Ar file
+resides.
+.It Cm i
+.Ar file Ap s
+inode number.
+.It Cm p
+File type and permissions.
+.It Cm l
+Number of hard links to
+.Ar file .
+.It Cm u , g
+User-id and group-id of
+.Ar file Ap s
+owner.
+.It Cm r
+Device number for character and block device special files.
+.It Cm a , m , c
+The time
+.Ar file
+was last accessed, modified, or of when the inode was last changed.
+.It Cm z
+The size of
+.Ar file
+in bytes.
+.It Cm b
+Number of blocks allocated for
+.Ar file .
+.It Cm k
+Optimal file system I/O operation block size.
+.It Cm f
+User defined flags for
+.Ar file .
+.It Cm v
+Inode generation number.
+.El
+.Pp
+The following four field specifiers are not drawn directly from the
+data in struct stat, but are
+.Bl -tag -width Ds
+.It Cm N
+The name of the file.
+.It Cm T
+The file type, either as in
+.Ic ls -F
+or in a more descriptive form if the sub field specifier
+.Cm H
+is given.
+.It Cm Y
+The target of a symbolic link.
+.It Cm Z
+Expands to ``major,minor'' from the rdev field for character or block
+special devices and gives size output for all others.
+.El
+.El
+.Pp
+Only the
+.Cm %
+and the field specifier are required.  Most field
+specifiers default to
+.Cm U
+as an output form, with the
+exception of
+.Cm p
+which defaults to
+.Cm O ,
+.Cm a , m ,
+and
+.Cm c
+which default to
+.Cm D ,
+and
+.Cm Y , T ,
+and
+.Cm N ,
+which default to
+.Cm S .
+.Sh EXIT STATUS
+.Nm
+exits 0 on success, and \*[Gt]0 if an error occurred.
+.Sh EXAMPLES
+Given a symbolic link ``foo'' that points from /tmp/foo to /, you would use
+.Nm
+as follows:
+.Bd -literal -offset indent
+\*[Gt] stat -F /tmp/foo
+lrwxrwxrwx 1 jschauma cs 1 Apr 24 16:37:28 2002 /tmp/foo@ -\*[Gt] /
+
+\*[Gt] stat -LF /tmp/foo
+lrwxrwxrwx 16 root wheel 512 Apr 19 10:57:54 2002 /tmp/foo/
+.Ed
+.Pp
+To initialize some shell-variables, you could use the
+.Fl s
+flag as follows:
+.Bd -literal -offset indent
+\*[Gt] csh
+% eval set `stat -s .cshrc`
+% echo $st_size $st_mtimespec
+1148 1015432481
+
+\*[Gt] sh
+$ eval $(stat -s .profile)
+$ echo $st_size $st_mtimespec
+1148 1015432481
+.Ed
+.Pp
+In order to get a list of the kind of files including files pointed to if the
+file is a symbolic link, you could use the following format:
+.Bd -literal -offset indent
+$ stat -f "%N: %HT%SY" /tmp/*
+/tmp/bar: Symbolic Link -\*[Gt] /tmp/foo
+/tmp/output25568: Regular File
+/tmp/blah: Directory
+/tmp/foo: Symbolic Link -\*[Gt] /
+.Ed
+.Pp
+In order to get a list of the devices, their types and the major and minor
+device numbers, formatted with tabs and linebreaks, you could use the
+following format:
+.Bd -literal -offset indent
+stat -f "Name: %N%n%tType: %HT%n%tMajor: %Hr%n%tMinor: %Lr%n%n" /dev/*
+[...]
+Name: /dev/wt8
+        Type: Block Device
+        Major: 3
+        Minor: 8
+
+Name: /dev/zero
+        Type: Character Device
+        Major: 2
+        Minor: 12
+.Ed
+.Pp
+In order to determine the permissions set on a file separately, you could use
+the following format:
+.Bd -literal -offset indent
+\*[Gt] stat -f "%Sp -\*[Gt] owner=%SHp group=%SMp other=%SLp" .
+drwxr-xr-x -\*[Gt] owner=rwx group=r-x other=r-x
+.Ed
+.Pp
+In order to determine the three files that have been modified most recently,
+you could use the following format:
+.Bd -literal -offset indent
+\*[Gt] stat -f "%m%t%Sm %N" /tmp/* | sort -rn | head -3 | cut -f2-
+Apr 25 11:47:00 2002 /tmp/blah
+Apr 25 10:36:34 2002 /tmp/bar
+Apr 24 16:47:35 2002 /tmp/foo
+.Ed
+.Sh SEE ALSO
+.Xr file 1 ,
+.Xr ls 1 ,
+.Xr lstat 2 ,
+.Xr readlink 2 ,
+.Xr stat 2 ,
+.Xr printf 3 ,
+.Xr strftime 3
+.Sh HISTORY
+The
+.Nm
+utility appeared in
+.Nx 1.6 .
+.Sh AUTHORS
+The
+.Nm
+utility was written by Andrew Brown
+.Aq atatat@netbsd.org .
+This man page
+was written by Jan Schaumann
+.Aq jschauma@netbsd.org .