Module Name: src
Committed By: kre
Date: Wed Jun 22 18:02:43 UTC 2022
Modified Files:
src/usr.bin/stat: Makefile stat.1
Added Files:
src/usr.bin/stat: readlink.1
Log Message:
Divide stat.1 into stat.1 (now only includes stat(1)) and readlink.1
Apologies to cvs commit purists, but making this division required
line by line reading of the man pages, and I simply could not resist
also correcting some errors, addressing some omissions, improving some
wording ... all at the same time.
To generate a diff of this commit:
cvs rdiff -u -r1.11 -r1.12 src/usr.bin/stat/Makefile
cvs rdiff -u -r0 -r1.1 src/usr.bin/stat/readlink.1
cvs rdiff -u -r1.40 -r1.41 src/usr.bin/stat/stat.1
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/usr.bin/stat/Makefile
diff -u src/usr.bin/stat/Makefile:1.11 src/usr.bin/stat/Makefile:1.12
--- src/usr.bin/stat/Makefile:1.11 Sun Sep 29 23:45:01 2019
+++ src/usr.bin/stat/Makefile Wed Jun 22 18:02:43 2022
@@ -1,10 +1,10 @@
-# $NetBSD: Makefile,v 1.11 2019/09/29 23:45:01 mrg Exp $
+# $NetBSD: Makefile,v 1.12 2022/06/22 18:02:43 kre Exp $
PROG= stat
.if !defined(HOSTPROG)
LINKS= ${BINDIR}/stat ${BINDIR}/readlink
-MLINKS= stat.1 readlink.1
+MAN= stat.1 readlink.1
.endif
.include <bsd.own.mk>
Index: src/usr.bin/stat/stat.1
diff -u src/usr.bin/stat/stat.1:1.40 src/usr.bin/stat/stat.1:1.41
--- src/usr.bin/stat/stat.1:1.40 Wed Sep 20 08:57:02 2017
+++ src/usr.bin/stat/stat.1 Wed Jun 22 18:02:43 2022
@@ -1,4 +1,4 @@
-.\" $NetBSD: stat.1,v 1.40 2017/09/20 08:57:02 wiz Exp $
+.\" $NetBSD: stat.1,v 1.41 2022/06/22 18:02:43 kre Exp $
.\"
.\" Copyright (c) 2002-2011 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,12 +27,11 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd September 19, 2017
+.Dd June 22, 2022
.Dt STAT 1
.Os
.Sh NAME
-.Nm stat ,
-.Nm readlink
+.Nm stat
.Nd display file status
.Sh SYNOPSIS
.Nm
@@ -46,42 +45,46 @@
.Oc
.Op Fl t Ar timefmt
.Op Ar
-.Nm readlink
-.Op Fl fnqsv
-.Op Ar
.Sh DESCRIPTION
The
.Nm
-utility displays information about the file pointed to by
+utility displays information about each file given by
.Ar file .
-Read, write, or execute permissions of the named file are not required, but
+Read, write, or execute permissions for the named file are not required, but
all directories listed in the pathname leading to the file must be
searchable.
-If no argument is given,
+.Pp
+If no
+.Ar file
+argument is given,
.Nm
displays information about the file descriptor for standard input.
+In this case the
+.Fl L
+option is ignored, and
+.Nm
+uses
+.Xr fstat 2
+rather than
+.Xr lstat 2
+or
+.Xr stat 2
+to obtain information.
+The
+.Sq file name
+(and also the
+.Sq path name )
+in this case is
+.Dq \&(stdin) .
.Pp
-When invoked as
-.Nm readlink ,
-only the target of the symbolic link is printed.
-If the given argument is not a symbolic link and the
-.Fl f
-option is not specified,
-.Nm readlink
-will print nothing and exit with an error.
-If the
-.Fl f
-option is specified, the output is canonicalized by following every symlink
-in every component of the given path recursively.
-.Nm readlink
-will resolve both absolute and relative paths, and return the absolute pathname
-corresponding to
-.Ar file .
-In this case, the argument does not need to be a symbolic link.
-.Pp
-The information displayed is obtained by calling
+Otherwise the information displayed is obtained by calling
.Xr lstat 2
-with the given argument and evaluating the returned structure.
+(or
+.Xr stat 2
+with
+.Fl L )
+with each given argument in turn and evaluating the returned structure.
+.Pp
The default format displays the
.Fa st_dev ,
.Fa st_ino ,
@@ -138,7 +141,9 @@ The information reported by
.Nm
will refer to the target of
.Ar file ,
-if file is a symbolic link, and not to
+if
+.Ar file
+is a symbolic link, rather than to
.Ar file
itself.
.It Fl l
@@ -149,13 +154,13 @@ format.
Do not force a newline to appear at the end of each piece of output.
.It Fl q
Suppress failure messages if calls to
-.Xr stat 2
+.Xr fstat 2 ,
+.Xr lstat 2 ,
+.Xr readlink 2 ,
+.Xr realpath 3 ,
or
-.Xr lstat 2
+.Xr stat 2
fail.
-When run as
-.Nm readlink ,
-error messages are automatically suppressed.
.It Fl r
Display raw information.
That is, for all the fields in the stat-structure,
@@ -163,42 +168,57 @@ display the raw, numerical value (for ex
epoch, etc.)
.It Fl s
Display information in
-.Dq shell output ,
+.Dq shell command
+output format,
suitable for initializing variables.
-When run as
-.Nm readlink ,
-suppress error messages.
This is equivalent to specifying
.Bd -literal
-FMT="st_dev=%d st_ino=%i st_mode=%#p st_nlink=%l st_uid=%u st_gid=%g"
-FMT="$FMT st_rdev=%r st_size=%z st_atime=%Sa st_mtime=%Sm st_ctime=%Sc"
-FMT="$FMT st_birthtime=%SB st_blksize=%k st_blocks=%b st_flags=%f"
+FMT="st_dev=%d st_ino=%i st_mode=%#p st_nlink=%l"
+FMT="$FMT st_uid=%u st_gid=%g st_rdev=%r st_size=%z"
+FMT="$FMT st_atime=%Sa st_mtime=%Sm st_ctime=%Sc"
+FMT="$FMT st_birthtime=%SB st_blksize=%k st_blocks=%b"
+FMT="$FMT st_flags=%f"
stat -t %s -f "$FMT" .
.Ed
-Note that if you use a timeformat that contains embedded whitespace or shell
-meta-characters you will need to include appropriate quoting so the
+.Pp
+The timefmt may be altered from the default for
.Fl s
-output remains valid.
+.Pq Dq \&%s ,
+by also using the
+.Fl t
+option.
+Note that if you use a timefmt that contains embedded whitespace or shell
+meta-characters, or if the shell's IFS is set to a non-standard value,
+you will need to
+include appropriate quoting in the
+.Fl t
+format, or supply an explicit format
+.Pq Fl f ,
+rather than
+.Fl s ,
+with the format containing appropriate quoting so the output remains valid.
.It Fl t Ar timefmt
-Display timestamps using the specified format.
+Display timestamps, when to be output in string format,
+using the specified format.
This format is
passed directly to
.Xr strftime 3
with the extension that %f prints nanoseconds if available.
-.It Fl v
-Turn off quiet mode.
.It Fl x
-Display information in a more verbose way as known from some Linux
+Display information in a more verbose way as seen from some Linux
distributions.
.El
.Ss FORMATS
Format strings are similar to
.Xr printf 3
-formats in that they start with
+formats in that they contain character data,
+which is simply output,
+interspersed with data conversions which 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.
+a character that selects the datum, the field of the struct stat,
+or other data,
+which is to be formatted.
If the
.Cm %
is immediately followed by one of
@@ -208,17 +228,17 @@ is immediately followed by one of
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:
+or the current file number in the argument list is printed.
+Otherwise the string is examined for the following:
.Pp
-Any of the following optional flags:
+Any of the following optional flags in any order:
.Bl -tag -width Ds
.It Cm #
Selects an alternate output form for string, octal and hexadecimal output.
String output will be encoded in
.Xr vis 3
style.
-Non-zero octal output will have a leading zero.
+Octal output will have a leading zero.
Non-zero hexadecimal output will have
.Dq 0x
prepended to it.
@@ -238,16 +258,22 @@ A
overrides a space if both are used.
.El
.Pp
-Then the following fields:
+Then followed by the following fields in the following order:
.Bl -tag -width Ds
.It Cm size
An optional decimal digit string specifying the minimum field width.
+Note that a leading zero
+.Pq Sq 0
+is treated as the
+.Sq 0
+flag (above), subsequent embedded zeroes are part of the
+.Cm size .
.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.
+output, or the minimum number of digits to appear in other numeric output.
.It Cm fmt
An optional output format specifier which is one of
.Cm D ,
@@ -268,7 +294,7 @@ and
.Cm c
fields).
.Pp
-The special output specifier
+The special output format specifier
.Cm S
may be used to indicate that the output, if
applicable, should be in string format.
@@ -293,12 +319,15 @@ Displays the name of
.It Cm T
Displays the type of
.Ar file .
-.It Cm Y
+.It Cm RY
Insert a `` -> '' into the output.
-Note that the default output format for
+Note that the default output formats for
.Cm Y
-is a string, but if specified explicitly, these four characters are
-prepended.
+and
+.Cm R
+are strings, if
+.Cm S
+is specified explicitly, these four characters are prepended.
.El
.It Cm sub
An optional sub field specifier (high, middle, or low).
@@ -310,7 +339,7 @@ Only applies to the
.Cm N ,
and
.Cm z
-output formats.
+output field specifiers.
It can be one of the following:
.Bl -tag -width Ds
.It Cm H
@@ -382,7 +411,8 @@ File size, rounded to the nearest kiloby
.El
.El
.It Cm datum
-A required field specifier, being one of the following:
+A required field specifier, ending the conversion specification,
+being one of the following:
.Bl -tag -width 11n
.It Cm d
Device upon which
@@ -411,7 +441,7 @@ Device number for character and block de
.It Cm a , m , c , B
The time
.Ar file
-was last accessed or modified, or when the inode was last changed, or
+was last accessed or modified, or when its inode was last changed, or
the birth time of the inode
.Pq Fa st_atime , st_mtime , st_ctime , st_birthtime .
.It Cm z
@@ -453,17 +483,24 @@ The target of a symbolic link.
.It Cm Z
Expands to
.Dq Ar major , Ns Ar minor
-from the rdev field for character or block
-special devices and gives size output for all others.
+from the
+.Fa st_rdev
+field for character or block special devices
+(that is,
+.Dq %Hr,%Lr )
+and gives size output
+.Pq Fa st_size
+.Pq Dq %z
+for all others.
.El
.El
.Pp
Only the
.Cm %
-and the field specifier are required.
+and the datum (field specifier) are required.
Most field specifiers default to
.Cm U
-as an output form, with the
+as an output format, with the
exception of
.Cm p
which defaults to
@@ -474,7 +511,7 @@ and
which default to
.Cm D ;
and
-.Cm Y , T ,
+.Cm Y , T , R ,
and
.Cm N ,
which default to
@@ -482,14 +519,18 @@ which default to
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
-If no options are specified, the default format is
-"%d %i %Sp %l %Su %Sg %r %z \e"%Sa\e" \e"%Sm\e" \e"%Sc\e" \e"%SB\e" %k %b %#Xf %N".
+If no options are specified, the default format is:
.Bd -literal -offset indent
+%d %i %Sp %l %Su %Sg %r %z "%Sa" "%Sm" "%Sc" "%SB" %k %b %#Xf %N
+.Ed
+.Pp
+Thus:
+.Bd -literal -offset indent compact
> stat /tmp/bar
-0 78852 -rw-r--r-- 1 root wheel 0 0 "Jul 8 10:26:03 2004" "Jul 8 10:26:03 2004" "Jul 8 10:28:13 2004" "Jan 1 09:00:00 1970" 16384 0 0 /tmp/bar
+0 78852 -rw-r--r-- 1 root wheel \(mi1 0 "Jul 8 10:26:03 2004" "Jul 8 10:26:03 2004" "Jul 8 10:28:13 2004" "Jan 1 09:00:00 1970" 16384 0 0 /tmp/bar
.Ed
.Pp
-This example produces output very similar to that from
+This next example produces output very similar to that from
.Ic find ... -ls
(except that
.Xr find 1
@@ -567,7 +608,7 @@ $ stat -f "%N: %HT%SY" /tmp/*
.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
+device numbers, formatted with tabs and line breaks, 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/*
@@ -615,10 +656,13 @@ link\eswith\esspaces -> target\eswith\es
.Xr dirname 1 ,
.Xr file 1 ,
.Xr ls 1 ,
+.Xr readlink 1 ,
+.Xr fstat 2 ,
.Xr lstat 2 ,
.Xr readlink 2 ,
.Xr stat 2 ,
.Xr printf 3 ,
+.Xr realpath 3 ,
.Xr strftime 3
.Sh HISTORY
The
Added files:
Index: src/usr.bin/stat/readlink.1
diff -u /dev/null src/usr.bin/stat/readlink.1:1.1
--- /dev/null Wed Jun 22 18:02:43 2022
+++ src/usr.bin/stat/readlink.1 Wed Jun 22 18:02:43 2022
@@ -0,0 +1,113 @@
+.\" $NetBSD: readlink.1,v 1.1 2022/06/22 18:02:43 kre Exp $
+.\"
+.\" Copyright (c) 2002-2011 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.
+.\"
+.\" 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.
+.\"
+.Dd June 22, 2022
+.Dt READLINK 1
+.Os
+.Sh NAME
+.Nm readlink
+.Nd display target of a symbolic link
+.Sh SYNOPSIS
+.Nm
+.Op Fl fnqsv
+.Op Ar
+.Sh DESCRIPTION
+The
+.Nm
+utility displays the target of a symbolic link.
+If a given argument
+.Ar file
+is not a symbolic link and the
+.Fl f
+option is not specified,
+.Nm readlink
+will print nothing to standard output about that
+.Ar file
+and eventually exit with an error status.
+If the
+.Fl f
+option is specified, the output is canonicalized by following every symlink
+in every component of the given path recursively.
+.Nm
+will resolve both absolute and relative paths, and, if possible,
+return the absolute pathname corresponding to
+.Ar file .
+In this case, the argument does not need to be a symbolic link.
+.Pp
+The options are as follows:
+.Bl -tag -width XFXXX
+.It Fl f
+Canonicalize the pathname of
+.Ar file ,
+as described above.
+.It Fl n
+Do not force a newline to appear after the output for each
+.Ar file .
+.It Fl q
+Suppress failure messages if calls to
+.Xr lstat 2
+fail.
+This is the default for
+.Nm readlink .
+.It Fl s
+This is an alternative to
+.Fl q .
+.It Fl v
+Turn off quiet mode.
+.Nm
+will display errors about
+.Ar file Ns s
+for which
+.Xr lstat 2
+fails.
+This is the inverse of
+.Fl q
+and
+.Fl s .
+.Sh SEE ALSO
+.Xr stat 1 ,
+.Xr lstat 2 ,
+.Xr readlink 2 .
+.Sh HISTORY
+The
+.Nm
+utility appeared along with
+.Nm stat ,
+within which it is integrated, in
+.Nx 1.6 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm stat
+utility was written by
+.An Andrew Brown
+.Aq [email protected] .
+The original combined man page was written by
+.An Jan Schaumann
+.Aq [email protected] .
