b6cbf7203b
This patch imports the unmodified current version of NetBSD libc. The NetBSD includes are in /nbsd_include, while the libc code itself is split between lib/nbsd_libc and common/lib/libc.
361 lines
10 KiB
Groff
361 lines
10 KiB
Groff
.\" $NetBSD: stat.2,v 1.47 2010/11/25 20:53:23 dholland Exp $
|
|
.\"
|
|
.\" Copyright (c) 1980, 1991, 1993, 1994
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" 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. Neither the name of the University 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 REGENTS 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 REGENTS 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.
|
|
.\"
|
|
.\" @(#)stat.2 8.4 (Berkeley) 5/1/95
|
|
.\"
|
|
.Dd November 25, 2010
|
|
.Dt STAT 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm stat ,
|
|
.Nm lstat ,
|
|
.Nm fstat
|
|
.Nd get file status
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/stat.h
|
|
.Ft int
|
|
.Fn stat "const char *path" "struct stat *sb"
|
|
.Ft int
|
|
.Fn lstat "const char *path" "struct stat *sb"
|
|
.Ft int
|
|
.Fn fstat "int fd" "struct stat *sb"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn stat
|
|
function obtains information about the file pointed to by
|
|
.Fa path .
|
|
Read, write or execute
|
|
permission of the named file is not required, but all directories
|
|
listed in the path name leading to the file must be searchable.
|
|
.Pp
|
|
The function
|
|
.Fn lstat
|
|
is like
|
|
.Fn stat
|
|
except in the case where the named file is a symbolic link,
|
|
in which case
|
|
.Fn lstat
|
|
returns information about the link,
|
|
while
|
|
.Fn stat
|
|
returns information about the file the link references.
|
|
The
|
|
.Fn fstat
|
|
function obtains the same information about an open file
|
|
known by the file descriptor
|
|
.Fa fd .
|
|
.Pp
|
|
The
|
|
.Fa sb
|
|
argument is a pointer to a
|
|
.Fa stat
|
|
structure
|
|
as defined by
|
|
.In sys/stat.h
|
|
and into which information is placed concerning the file.
|
|
.Ss The Standard Structure
|
|
The following standards-compliant fields are defined in the structure:
|
|
.Bl -column -offset indent \
|
|
"nlink_t " "st_nlink " "Description"
|
|
.It Sy Type Ta Sy Entry Ta Sy Description
|
|
.It Vt dev_t Ta st_dev Ta device ID containing the file
|
|
.It Vt ino_t Ta st_ino Ta serial number of the file
|
|
.It Vt mode_t Ta st_mode Ta mode of the file
|
|
.It Vt nlink_t Ta st_nlink Ta number of hard links to the file
|
|
.It Vt uid_t Ta st_uid Ta user ID of the owner
|
|
.It Vt gid_t Ta st_gid Ta group ID of the owner
|
|
.It Vt dev_t Ta st_rdev Ta device type (character or block special)
|
|
.It Vt off_t Ta st_size Ta size of the file in bytes
|
|
.It Vt time_t Ta st_atime Ta time of last access
|
|
.It Vt time_t Ta st_mtime Ta time of last data modification
|
|
.It Vt time_t Ta st_ctime Ta time of last file status change
|
|
.It Vt blksize_t Ta st_blksize Ta preferred I/O block size (fs-specific)
|
|
.It Vt blkcnt_t Ta st_block Ta blocks allocated for the file
|
|
.El
|
|
.Pp
|
|
These are specified in the
|
|
.St -p1003.1-2004
|
|
standard.
|
|
The
|
|
.Va st_ino
|
|
and
|
|
.Va st_dev
|
|
fields taken together to uniquely identify the file within the system.
|
|
Most of the types are defined in
|
|
.Xr types 3 .
|
|
.Pp
|
|
The time-related fields are:
|
|
.Bl -tag -width st_blksize -offset indent
|
|
.It Va st_atime
|
|
Time when file data was last accessed.
|
|
Changed by the
|
|
.Xr mknod 2 ,
|
|
.Xr utimes 2 ,
|
|
and
|
|
.Xr read 2
|
|
system calls.
|
|
.It Va st_mtime
|
|
Time when file data was last modified.
|
|
Changed by the
|
|
.Xr mknod 2 ,
|
|
.Xr utimes 2 ,
|
|
and
|
|
.Xr write 2
|
|
system calls.
|
|
.It Va st_ctime
|
|
Time when file status was last changed (file metadata modification).
|
|
Changed by the
|
|
.Xr chflags 2 ,
|
|
.Xr chmod 2 ,
|
|
.Xr chown 2 ,
|
|
.Xr link 2 ,
|
|
.Xr mknod 2 ,
|
|
.Xr rename 2 ,
|
|
.Xr unlink 2 ,
|
|
.Xr utimes 2 ,
|
|
and
|
|
.Xr write 2
|
|
system calls.
|
|
.El
|
|
.Pp
|
|
The size-related fields of the
|
|
.Fa struct stat
|
|
are as follows:
|
|
.Bl -tag -width st_blksize -offset indent
|
|
.It Va st_size
|
|
The size of the file in bytes.
|
|
The meaning of the size reported for a directory is file system
|
|
dependent.
|
|
Some file systems (e.g. FFS) return the total size used for the
|
|
directory metadata, possibly including free slots; others (notably
|
|
ZFS) return the number of entries in the directory.
|
|
Some may also return other things or always report zero.
|
|
.It Va st_blksize
|
|
The optimal I/O block size for the file.
|
|
.It Va st_blocks
|
|
The actual number of blocks allocated for the file in 512-byte units.
|
|
As short symbolic links are stored in the inode, this number may
|
|
be zero.
|
|
.El
|
|
.Pp
|
|
The status information word
|
|
.Fa st_mode
|
|
contains bits that define the access mode (see
|
|
.Xr chmod 2 )
|
|
and the type (see
|
|
.Xr dirent 3 )
|
|
of the file.
|
|
The following macros can be used to test
|
|
whether a file is of the specified type.
|
|
The value
|
|
.Fa m
|
|
supplied to the macros is the value of
|
|
.Va st_mode .
|
|
.Bl -tag -width "S_ISSOCK(m)" -offset indent
|
|
.It Fn S_ISBLK "m"
|
|
Test for a block special file.
|
|
.It Fn S_ISCHR "m"
|
|
Test for a character special file.
|
|
.It Fn S_ISDIR "m"
|
|
Test for a directory.
|
|
.It Fn S_ISFIFO "m"
|
|
Test for a pipe or FIFO special file.
|
|
.It Fn S_ISREG "m"
|
|
Test for a regular file.
|
|
.It Fn S_ISLNK "m"
|
|
Test for a symbolic link.
|
|
.It Fn S_ISSOCK "m"
|
|
Test for a socket.
|
|
.El
|
|
.Pp
|
|
The macros evaluate to a non-zero value if the test
|
|
is true or to the value 0 if the test is false.
|
|
.Ss NetBSD Extensions
|
|
The following additional
|
|
.Nx
|
|
specific fields are present:
|
|
.Bl -column -offset indent \
|
|
"uint32_t" "st_birthtimensec" "Description"
|
|
.It Sy Type Ta Sy Entry Ta Sy Description
|
|
.It Vt long Ta st_atimensec Ta last access (nanoseconds)
|
|
.It Vt long Ta st_mtimensec Ta last modification (nanoseconds)
|
|
.It Vt long Ta st_ctimensec Ta last status change (nanoseconds)
|
|
.It Vt time_t Ta st_birthtime Ta time of inode creation
|
|
.It Vt long Ta st_birthtimensec Ta inode creation (nanoseconds)
|
|
.It Vt uint32_t Ta st_flags Ta user defined flags for the file
|
|
.It Vt uint32_t Ta st_gen Ta file generation number
|
|
.\"
|
|
.\" XXX: What is this?
|
|
.\"
|
|
.It Vt uint32_t Ta st_spare[2] Ta implementation detail
|
|
.El
|
|
.Pp
|
|
However, if
|
|
_NETBSD_SOURCE
|
|
is furthermore defined, instead of the above,
|
|
the following are present in the structure:
|
|
.Bl -column -offset indent \
|
|
"struct timespec " "st_birthtimensec" "Description"
|
|
.It Sy Type Ta Sy Entry Ta Sy Description
|
|
.It Vt struct timespec Ta st_atimespec Ta time of last access
|
|
.It Vt struct timespec Ta st_mtimespec Ta time of last modification
|
|
.It Vt struct timespec Ta st_birthtimespec Ta time of creation
|
|
.It Vt uint32_t Ta st_flags Ta user defined flags
|
|
.It Vt uint32_t Ta st_gen Ta file generation number
|
|
.\"
|
|
.\" XXX: What is this?
|
|
.\"
|
|
.It Vt uint32_t Ta st_spare[2] Ta implementation detail
|
|
.El
|
|
.Pp
|
|
In this case the following macros are provided for convenience:
|
|
.Bd -literal -offset indent
|
|
#if defined(_NETBSD_SOURCE)
|
|
#define st_atime st_atimespec.tv_sec
|
|
#define st_atimensec st_atimespec.tv_nsec
|
|
#define st_mtime st_mtimespec.tv_sec
|
|
#define st_mtimensec st_mtimespec.tv_nsec
|
|
#define st_ctime st_ctimespec.tv_sec
|
|
#define st_ctimensec st_ctimespec.tv_nsec
|
|
#define st_birthtime st_birthtimespec.tv_sec
|
|
#define st_birthtimensec st_birthtimespec.tv_nsec
|
|
#endif
|
|
.Ed
|
|
.Pp
|
|
The status information word
|
|
.Fa st_flags
|
|
has the following bits:
|
|
.Bl -column -offset indent \
|
|
"struct timespec " "st_birthtimensec"
|
|
.It Sy Constant Ta Sy Description
|
|
.It Dv UF_NODUMP Ta do not dump a file
|
|
.It Dv UF_IMMUTABLE Ta file may not be changed
|
|
.It Dv UF_APPEND Ta writes to file may only append
|
|
.It Dv UF_OPAQUE Ta directory is opaque wrt. union
|
|
.It Dv SF_ARCHIVED Ta file is archived
|
|
.It Dv SF_IMMUTABLE Ta file may not be changed
|
|
.It Dv SF_APPEND Ta writes to file may only append
|
|
.El
|
|
.Pp
|
|
For a description of the flags, see
|
|
.Xr chflags 2 .
|
|
.Sh RETURN VALUES
|
|
Upon successful completion a value of 0 is returned.
|
|
Otherwise, a value of \-1 is returned and
|
|
.Va errno
|
|
is set to indicate the error.
|
|
.Sh COMPATIBILITY
|
|
Previous versions of the system used different types for the
|
|
.Li st_dev ,
|
|
.Li st_uid ,
|
|
.Li st_gid ,
|
|
.Li st_rdev ,
|
|
.Li st_size ,
|
|
.Li st_blksize
|
|
and
|
|
.Li st_blocks
|
|
fields.
|
|
.Sh ERRORS
|
|
.Fn stat
|
|
and
|
|
.Fn lstat
|
|
will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EACCES
|
|
Search permission is denied for a component of the path prefix.
|
|
.It Bq Er EBADF
|
|
A badly formed v-node was encountered.
|
|
This can happen if a file system information node is incorrect.
|
|
.It Bq Er EFAULT
|
|
.Fa sb
|
|
or
|
|
.Em name
|
|
points to an invalid address.
|
|
.It Bq Er EIO
|
|
An I/O error occurred while reading from or writing to the file system.
|
|
.It Bq Er ELOOP
|
|
Too many symbolic links were encountered in translating the pathname.
|
|
.It Bq Er ENAMETOOLONG
|
|
A component of a pathname exceeded
|
|
.Brq Dv NAME_MAX
|
|
characters, or an entire path name exceeded
|
|
.Brq Dv PATH_MAX
|
|
characters.
|
|
.It Bq Er ENOENT
|
|
The named file does not exist.
|
|
.It Bq Er ENOTDIR
|
|
A component of the path prefix is not a directory.
|
|
.It Bq Er ENXIO
|
|
The named file is a character special or block
|
|
special file, and the device associated with this special file
|
|
does not exist.
|
|
.El
|
|
.Pp
|
|
.Fn fstat
|
|
will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EBADF
|
|
.Fa fd
|
|
is not a valid open file descriptor.
|
|
.It Bq Er EFAULT
|
|
.Fa sb
|
|
points to an invalid address.
|
|
.It Bq Er EIO
|
|
An I/O error occurred while reading from or writing to the file system.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr chflags 2 ,
|
|
.Xr chmod 2 ,
|
|
.Xr chown 2 ,
|
|
.Xr utimes 2 ,
|
|
.Xr dirent 3 ,
|
|
.Xr types 3 ,
|
|
.Xr symlink 7
|
|
.Sh STANDARDS
|
|
The described functions conform to
|
|
.St -p1003.1-2004 .
|
|
.Sh HISTORY
|
|
A
|
|
.Fn stat
|
|
function call appeared in
|
|
.At v2 .
|
|
A
|
|
.Fn lstat
|
|
function call appeared in
|
|
.Bx 4.2 .
|
|
.Sh BUGS
|
|
Applying
|
|
.Fn fstat
|
|
to a socket (and thus to a pipe)
|
|
returns a zero'd buffer,
|
|
except for the blocksize field,
|
|
and a unique device and file serial number.
|