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 ata...@netbsd.org . +The original combined man page was written by +.An Jan Schaumann +.Aq jscha...@netbsd.org .