[src/trunk]: src/usr.bin/stat Divide stat.1 into stat.1 (now only includes st...

[kre <kre%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/c72b2de059f0
branches:  trunk
changeset: 367687:c72b2de059f0
user:      kre <kre%NetBSD.org@localhost>
date:      Wed Jun 22 18:02:43 2022 +0000

description:
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.

diffstat:

 usr.bin/stat/Makefile   |    4 +-
 usr.bin/stat/readlink.1 |  113 +++++++++++++++++++++++++++
 usr.bin/stat/stat.1     |  200 +++++++++++++++++++++++++++++------------------
 3 files changed, 237 insertions(+), 80 deletions(-)

diffs (truncated from 524 to 300 lines):

diff -r 6e40b180af1d -r c72b2de059f0 usr.bin/stat/Makefile
--- a/usr.bin/stat/Makefile     Wed Jun 22 14:29:11 2022 +0000
+++ b/usr.bin/stat/Makefile     Wed Jun 22 18:02:43 2022 +0000
@@ -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>
diff -r 6e40b180af1d -r c72b2de059f0 usr.bin/stat/readlink.1
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/usr.bin/stat/readlink.1   Wed Jun 22 18:02:43 2022 +0000
@@ -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 atatat%NetBSD.org@localhost .
+The original combined man page was written by
+.An Jan Schaumann
+.Aq jschauma%NetBSD.org@localhost .
diff -r 6e40b180af1d -r c72b2de059f0 usr.bin/stat/stat.1
--- a/usr.bin/stat/stat.1       Wed Jun 22 14:29:11 2022 +0000
+++ b/usr.bin/stat/stat.1       Wed Jun 22 18:02:43 2022 +0000
@@ -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.
+Otherwise the information displayed is obtained by calling
+.Xr lstat 2
+(or
+.Xr stat 2
+with
+.Fl L )
+with each given argument in turn and evaluating the returned structure.
 .Pp
-The information displayed is obtained by calling
-.Xr lstat 2
-with the given argument and evaluating the returned structure.
 The default format displays the
 .Fa st_dev ,
 .Fa st_ino ,
@@ -138,7 +141,9 @@
 .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 @@
 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 @@
 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 ,