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.
This commit is contained in:
kre
parent
f3e77bbb72
commit
14ef4b89e1
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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 .
|
||||
The original combined man page was written by
|
||||
.An Jan Schaumann
|
||||
.Aq jschauma@NetBSD.org .
|
||||
|
|
@ -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.
|
||||
.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
|
||||
In this case the
|
||||
.Fl L
|
||||
option is ignored, and
|
||||
.Nm
|
||||
uses
|
||||
.Xr fstat 2
|
||||
rather than
|
||||
.Xr lstat 2
|
||||
with the given argument and evaluating the returned structure.
|
||||
or
|
||||
.Xr stat 2
|
||||
to obtain information.
|
||||
The
|
||||
.Sq file name
|
||||
(and also the
|
||||
.Sq path name )
|
||||
in this case is
|
||||
.Dq \&(stdin) .
|
||||
.Pp
|
||||
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 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 example, times in seconds since the
|
|||
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 kilobyte
|
|||
.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 device special files
|
|||
.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
|
||||
> 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
|
||||
%d %i %Sp %l %Su %Sg %r %z "%Sa" "%Sm" "%Sc" "%SB" %k %b %#Xf %N
|
||||
.Ed
|
||||
.Pp
|
||||
This example produces output very similar to that from
|
||||
Thus:
|
||||
.Bd -literal -offset indent compact
|
||||
> stat /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 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\esspaces
|
|||
.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
|
||||
|
|
|
|||
Loading…
Reference in New Issue