diff options
author | Cameron Katri <me@cameronkatri.com> | 2021-05-09 14:20:58 -0400 |
---|---|---|
committer | Cameron Katri <me@cameronkatri.com> | 2021-05-09 14:20:58 -0400 |
commit | 5fd83771641d15c418f747bd343ba6738d3875f7 (patch) | |
tree | 5abf0f78f680d9837dbd93d4d4c3933bb7509599 /file_cmds/stat/stat.1 | |
download | apple_cmds-5fd83771641d15c418f747bd343ba6738d3875f7.tar.gz apple_cmds-5fd83771641d15c418f747bd343ba6738d3875f7.tar.zst apple_cmds-5fd83771641d15c418f747bd343ba6738d3875f7.zip |
Import macOS userland
adv_cmds-176
basic_cmds-55
bootstrap_cmds-116.100.1
developer_cmds-66
diskdev_cmds-667.40.1
doc_cmds-53.60.1
file_cmds-321.40.3
mail_cmds-35
misc_cmds-34
network_cmds-606.40.1
patch_cmds-17
remote_cmds-63
shell_cmds-216.60.1
system_cmds-880.60.2
text_cmds-106
Diffstat (limited to 'file_cmds/stat/stat.1')
-rw-r--r-- | file_cmds/stat/stat.1 | 534 |
1 files changed, 534 insertions, 0 deletions
diff --git a/file_cmds/stat/stat.1 b/file_cmds/stat/stat.1 new file mode 100644 index 0000000..79c774f --- /dev/null +++ b/file_cmds/stat/stat.1 @@ -0,0 +1,534 @@ +.\" $NetBSD: stat.1,v 1.11 2003/05/08 13:07:10 wiz 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: src/usr.bin/stat/stat.1,v 1.8 2005/06/14 11:50:53 ru Exp $ +.\" +.Dd May 8, 2003 +.Dt STAT 1 +.Os +.Sh NAME +.Nm readlink , +.Nm stat +.Nd display file status +.Sh SYNOPSIS +.Nm stat +.Op Fl FLnq +.Op Fl f Ar format | Fl l | r | s | x +.Op Fl t Ar timefmt +.Op Ar +.Nm readlink +.Op Fl n +.Op Ar +.Sh DESCRIPTION +The +.Nm stat +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 stat +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, +.Nm readlink +will print nothing and exit with an error. +.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 indent +.\" ========== +.It Fl F +As in +.Xr ls 1 , +display a slash +.Pq Ql / +immediately after each pathname that is a directory, +an asterisk +.Pq Ql * +after each that is executable, +an at sign +.Pq Ql @ +after each symbolic link, +a percent sign +.Pq Ql % +after each whiteout, +an equal sign +.Pq Ql = +after each socket, +and a vertical bar +.Pq Ql | +after each that is a FIFO. +The use of +.Fl F +implies +.Fl l . +.\" ========== +.It Fl f Ar format +Display information using the specified format. +See the +.Sx FORMATS +section for a description of valid formats. +.\" ========== +.It Fl L +Use +.Xr stat 2 +instead of +.Xr lstat 2 . +The information reported by +.Nm stat +will refer to the target of +.Ar file , +if file is a symbolic link, and not to +.Ar file +itself. +.\" ========== +.It Fl l +Display output in +.Nm ls Fl lT +format. +.\" ========== +.It Fl n +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 +or +.Xr lstat 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 +.Vt stat +structure, +display the raw, numerical value (for example, times in seconds since the +epoch, etc.). +.\" ========== +.It Fl s +Display information in +.Dq "shell output" , +suitable for initializing variables. +.\" ========== +.It Fl t Ar timefmt +Display timestamps using the specified format. +This format is +passed directly to +.Xr strftime 3 . +.\" ========== +.It Fl x +Display information in a more verbose way as known from some +.Tn Linux +distributions. +.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 +.Vt "struct stat" +which is to be formatted. +If the +.Cm % +is immediately followed by one of +.Cm n , t , % , +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 indent +.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 +.Dq Li 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 +.Ql 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 indent +.It Ar size +An optional decimal digit string specifying the minimum field width. +.It Ar 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 Ar fmt +An optional output format specifier which is one of +.Cm D , O , U , X , 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 +.Vt timespec +fields (the +.Cm a , 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 indent +.It Cm amc +Display date in +.Xr 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 +.Nm ls Fl lTd . +.It Cm N +Displays the name of +.Ar file . +.It Cm T +Displays the type of +.Ar file . +.It Cm Y +Insert a +.Dq Li " -\*[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 Ar sub +An optional sub field specifier (high, middle, low). +Only applies to +the +.Cm p , d , r , +and +.Cm T +output formats. +It can be one of the following: +.Bl -tag -width indent +.It Cm H +.Dq High +\[em] +specifies the major number for devices from +.Cm r +or +.Cm d , +the +.Dq user +bits for permissions from the string form of +.Cm p , +the file +.Dq type +bits from the numeric forms of +.Cm p , +and the long output form of +.Cm T . +.It Cm L +.Dq Low +\[em] +specifies the minor number for devices from +.Cm r +or +.Cm d , +the +.Dq other +bits for permissions from the string form of +.Cm p , +the +.Dq user , +.Dq group , +and +.Dq other +bits from the numeric forms of +.Cm p , +and the +.Nm ls Fl F +style output character for file type when used with +.Cm T +(the use of +.Cm L +for this is optional). +.It Cm M +.Dq Middle +\[em] +specifies the +.Dq group +bits for permissions from the +string output form of +.Cm p , +or the +.Dq suid , +.Dq sgid , +and +.Dq sticky +bits for the numeric forms of +.Cm p . +.El +.It Ar datum +A required field specifier, being one of the following: +.Bl -tag -width indent +.It Cm d +Device upon which +.Ar file +resides. +.It Cm i +.Ar file Ns '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 Ns 's +owner. +.It Cm r +Device number for character and block device special files. +.It Cm a , m , c , B +The time +.Ar file +was last accessed or modified, of when the inode was last changed, or +the birth time of the inode. +.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 +.Vt "struct stat" , +but are: +.Bl -tag -width indent +.It Cm N +The name of the file. +.It Cm T +The file type, either as in +.Nm ls Fl F +or in a more descriptive form if the +.Ar sub +field specifier +.Cm H +is given. +.It Cm Y +The target of a symbolic link. +.It Cm Z +Expands to +.Dq major,minor +from the +.Va 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 +.Ex -std stat readlink +.Sh EXAMPLES +Given a symbolic link +.Pa foo +that points from +.Pa /tmp/foo +to +.Pa / , +you would use +.Nm stat +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 +drwxr-xr-x 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 stat +utility appeared in +.Nx 1.6 +and +.Fx 4.10 . +.Sh AUTHORS +.An -nosplit +The +.Nm stat +utility was written by +.An Andrew Brown +.Aq atatat@NetBSD.org . +This man page was written by +.An Jan Schaumann +.Aq jschauma@NetBSD.org . |