006678fd05
The list of syscalls that modify st_atim, st_mtim, and st_ctim was quite out of date and probably not accurate to begin with. Update it, and make it clear that the list is open-ended. Reviewed by: kib MFC after: 2 weeks Differential Revision: https://reviews.freebsd.org/D18410
505 lines
12 KiB
Groff
505 lines
12 KiB
Groff
.\" 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
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd December 5, 2018
|
|
.Dt STAT 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm stat ,
|
|
.Nm lstat ,
|
|
.Nm fstat ,
|
|
.Nm fstatat
|
|
.Nd get file status
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/stat.h
|
|
.Ft int
|
|
.Fn stat "const char * restrict path" "struct stat * restrict sb"
|
|
.Ft int
|
|
.Fn lstat "const char * restrict path" "struct stat * restrict sb"
|
|
.Ft int
|
|
.Fn fstat "int fd" "struct stat *sb"
|
|
.Ft int
|
|
.Fn fstatat "int fd" "const char *path" "struct stat *buf" "int flag"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn stat
|
|
system call 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
|
|
.Fn lstat
|
|
system call is like
|
|
.Fn stat
|
|
except when 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.
|
|
.Pp
|
|
The
|
|
.Fn fstat
|
|
system call obtains the same information about an open file
|
|
known by the file descriptor
|
|
.Fa fd .
|
|
.Pp
|
|
The
|
|
.Fn fstatat
|
|
system call is equivalent to
|
|
.Fn stat
|
|
and
|
|
.Fn lstat
|
|
except when the
|
|
.Fa path
|
|
specifies a relative path, or the
|
|
.Dv AT_BENEATH
|
|
flag is provided.
|
|
For
|
|
.Fn fstatat
|
|
and relative
|
|
.Fa path ,
|
|
the status is retrieved from a file relative to
|
|
the directory associated with the file descriptor
|
|
.Fa fd
|
|
instead of the current working directory.
|
|
For
|
|
.Dv AT_BENEATH
|
|
and absolute
|
|
.Fa path ,
|
|
the status is retrieved from a file specified by the
|
|
.Fa path ,
|
|
but additional permission checks are performed, see below.
|
|
.Pp
|
|
The values for the
|
|
.Fa flag
|
|
are constructed by a bitwise-inclusive OR of flags from this list,
|
|
defined in
|
|
.In fcntl.h :
|
|
.Bl -tag -width indent
|
|
.It Dv AT_SYMLINK_NOFOLLOW
|
|
If
|
|
.Fa path
|
|
names a symbolic link, the status of the symbolic link is returned.
|
|
.It Dv AT_BENEATH
|
|
Only stat files and directories below the topping directory.
|
|
See the description of the
|
|
.Dv O_BENEATH
|
|
flag in the
|
|
.Xr open 2
|
|
manual page.
|
|
.El
|
|
.Pp
|
|
If
|
|
.Fn fstatat
|
|
is passed the special value
|
|
.Dv AT_FDCWD
|
|
in the
|
|
.Fa fd
|
|
parameter, the current working directory is used and the behavior is
|
|
identical to a call to
|
|
.Fn stat
|
|
or
|
|
.Fn lstat
|
|
respectively, depending on whether or not the
|
|
.Dv AT_SYMLINK_NOFOLLOW
|
|
bit is set in
|
|
.Fa flag .
|
|
.Pp
|
|
When
|
|
.Fn fstatat
|
|
is called with an absolute
|
|
.Fa path
|
|
without the
|
|
.Dv AT_BENEATH
|
|
flag, it ignores the
|
|
.Fa fd
|
|
argument.
|
|
When
|
|
.Dv AT_BENEATH
|
|
is specified with an absolute
|
|
.Fa path ,
|
|
a directory passed by the
|
|
.Fa fd
|
|
argument is used as the topping point for the resolution.
|
|
.Pp
|
|
The
|
|
.Fa sb
|
|
argument is a pointer to a
|
|
.Vt stat
|
|
structure
|
|
as defined by
|
|
.In sys/stat.h
|
|
and into which information is placed concerning the file.
|
|
.Pp
|
|
The fields of
|
|
.Vt "struct stat"
|
|
related to the file system are:
|
|
.Bl -tag -width ".Va st_nlink"
|
|
.It Va st_dev
|
|
Numeric ID of the device containing the file.
|
|
.It Va st_ino
|
|
The file's inode number.
|
|
.It Va st_nlink
|
|
Number of hard links to the file.
|
|
.It Va st_flags
|
|
Flags enabled for the file.
|
|
See
|
|
.Xr chflags 2
|
|
for the list of flags and their description.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Va st_dev
|
|
and
|
|
.Va st_ino
|
|
fields together identify the file uniquely within the system.
|
|
.Pp
|
|
The time-related fields of
|
|
.Vt "struct stat"
|
|
are:
|
|
.Bl -tag -width ".Va st_birthtim"
|
|
.It Va st_atim
|
|
Time when file data was last accessed.
|
|
Changed implicitly by syscalls such as
|
|
.Xr read 2
|
|
and
|
|
.Xr readv 2 ,
|
|
and explicitly by
|
|
.Xr utimes 2 .
|
|
.It Va st_mtim
|
|
Time when file data was last modified.
|
|
Changed implicitly by syscalls such as
|
|
.Xr truncate 2 ,
|
|
.Xr write 2 ,
|
|
and
|
|
.Xr writev 2 ,
|
|
and explicitly by
|
|
.Xr utimes 2 .
|
|
Also, any syscall which modifies directory content changes the
|
|
.Va st_mtim
|
|
for the affected directory.
|
|
For instance,
|
|
.Xr creat 2 ,
|
|
.Xr mkdir 2 ,
|
|
.Xr rename 2 ,
|
|
.Xr link 2 ,
|
|
and
|
|
.Xr unlink 2 .
|
|
.It Va st_ctim
|
|
Time when file status was last changed (inode data modification).
|
|
Changed implicitly by any syscall that affects file metadata, including
|
|
.Va st_mtim ,
|
|
such as
|
|
.Xr chflags 2 ,
|
|
.Xr chmod 2 ,
|
|
.Xr chown 2 ,
|
|
.Xr truncate 2 ,
|
|
.Xr utimes 2 ,
|
|
and
|
|
.Xr write 2 .
|
|
Also, any syscall which modifies directory content changes the
|
|
.Va st_ctim
|
|
for the affected directory.
|
|
For instance,
|
|
.Xr creat 2 ,
|
|
.Xr mkdir 2 ,
|
|
.Xr rename 2 ,
|
|
.Xr link 2 ,
|
|
and
|
|
.Xr unlink 2 .
|
|
.It Va st_birthtim
|
|
Time when the inode was created.
|
|
.El
|
|
.Pp
|
|
These time-related macros are defined for compatibility:
|
|
.Bd -literal
|
|
#define st_atime st_atim.tv_sec
|
|
#define st_mtime st_mtim.tv_sec
|
|
#define st_ctime st_ctim.tv_sec
|
|
#ifndef _POSIX_SOURCE
|
|
#define st_birthtime st_birthtim.tv_sec
|
|
#endif
|
|
|
|
#ifndef _POSIX_SOURCE
|
|
#define st_atimespec st_atim
|
|
#define st_mtimespec st_mtim
|
|
#define st_ctimespec st_ctim
|
|
#define st_birthtimespec st_birthtim
|
|
#endif
|
|
.Ed
|
|
.Pp
|
|
Size-related fields of the
|
|
.Vt "struct stat"
|
|
are:
|
|
.Bl -tag -width ".Va st_blksize"
|
|
.It Va st_size
|
|
File size in bytes.
|
|
.It Va st_blksize
|
|
Optimal I/O block size for the file.
|
|
.It Va st_blocks
|
|
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 access-related fields of
|
|
.Vt "struct stat"
|
|
are:
|
|
.Bl -tag -width ".Va st_mode"
|
|
.It Va st_uid
|
|
User ID of the file's owner.
|
|
.It Va st_gid
|
|
Group ID of the file.
|
|
.It Va st_mode
|
|
Status of the file (see below).
|
|
.El
|
|
.Pp
|
|
The status information word
|
|
.Fa st_mode
|
|
has these bits:
|
|
.Bd -literal
|
|
#define S_IFMT 0170000 /* type of file mask */
|
|
#define S_IFIFO 0010000 /* named pipe (fifo) */
|
|
#define S_IFCHR 0020000 /* character special */
|
|
#define S_IFDIR 0040000 /* directory */
|
|
#define S_IFBLK 0060000 /* block special */
|
|
#define S_IFREG 0100000 /* regular */
|
|
#define S_IFLNK 0120000 /* symbolic link */
|
|
#define S_IFSOCK 0140000 /* socket */
|
|
#define S_IFWHT 0160000 /* whiteout */
|
|
#define S_ISUID 0004000 /* set user id on execution */
|
|
#define S_ISGID 0002000 /* set group id on execution */
|
|
#define S_ISVTX 0001000 /* save swapped text even after use */
|
|
#define S_IRWXU 0000700 /* RWX mask for owner */
|
|
#define S_IRUSR 0000400 /* read permission, owner */
|
|
#define S_IWUSR 0000200 /* write permission, owner */
|
|
#define S_IXUSR 0000100 /* execute/search permission, owner */
|
|
#define S_IRWXG 0000070 /* RWX mask for group */
|
|
#define S_IRGRP 0000040 /* read permission, group */
|
|
#define S_IWGRP 0000020 /* write permission, group */
|
|
#define S_IXGRP 0000010 /* execute/search permission, group */
|
|
#define S_IRWXO 0000007 /* RWX mask for other */
|
|
#define S_IROTH 0000004 /* read permission, other */
|
|
#define S_IWOTH 0000002 /* write permission, other */
|
|
#define S_IXOTH 0000001 /* execute/search permission, other */
|
|
.Ed
|
|
.Pp
|
|
For a list of access modes, see
|
|
.In sys/stat.h ,
|
|
.Xr access 2
|
|
and
|
|
.Xr chmod 2 .
|
|
These macros are available to test whether a
|
|
.Va st_mode
|
|
value passed in the
|
|
.Fa m
|
|
argument corresponds to a file of the specified type:
|
|
.Bl -tag -width ".Fn S_ISFIFO m"
|
|
.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_ISLNK m
|
|
Test for a symbolic link.
|
|
.It Fn S_ISREG m
|
|
Test for a regular file.
|
|
.It Fn S_ISSOCK m
|
|
Test for a socket.
|
|
.It Fn S_ISWHT m
|
|
Test for a whiteout.
|
|
.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.
|
|
.Sh RETURN VALUES
|
|
.Rv -std
|
|
.Sh COMPATIBILITY
|
|
Previous versions of the system used different types for the
|
|
.Va st_dev ,
|
|
.Va st_uid ,
|
|
.Va st_gid ,
|
|
.Va st_rdev ,
|
|
.Va st_size ,
|
|
.Va st_blksize
|
|
and
|
|
.Va st_blocks
|
|
fields.
|
|
.Sh ERRORS
|
|
The
|
|
.Fn stat
|
|
and
|
|
.Fn lstat
|
|
system calls 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 EFAULT
|
|
The
|
|
.Fa sb
|
|
or
|
|
.Fa path
|
|
argument
|
|
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 255 characters,
|
|
or an entire path name exceeded 1023 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 EOVERFLOW
|
|
The file size in bytes cannot be
|
|
represented correctly in the structure pointed to by
|
|
.Fa sb .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn fstat
|
|
system call will fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EBADF
|
|
The
|
|
.Fa fd
|
|
argument
|
|
is not a valid open file descriptor.
|
|
.It Bq Er EFAULT
|
|
The
|
|
.Fa sb
|
|
argument
|
|
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 EOVERFLOW
|
|
The file size in bytes cannot be
|
|
represented correctly in the structure pointed to by
|
|
.Fa sb .
|
|
.El
|
|
.Pp
|
|
In addition to the errors returned by the
|
|
.Fn lstat ,
|
|
the
|
|
.Fn fstatat
|
|
may fail if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EBADF
|
|
The
|
|
.Fa path
|
|
argument does not specify an absolute path and the
|
|
.Fa fd
|
|
argument is neither
|
|
.Dv AT_FDCWD
|
|
nor a valid file descriptor open for searching.
|
|
.It Bq Er EINVAL
|
|
The value of the
|
|
.Fa flag
|
|
argument is not valid.
|
|
.It Bq Er ENOTDIR
|
|
The
|
|
.Fa path
|
|
argument is not an absolute path and
|
|
.Fa fd
|
|
is neither
|
|
.Dv AT_FDCWD
|
|
nor a file descriptor associated with a directory.
|
|
.It Bq Er ENOTCAPABLE
|
|
.Fa path
|
|
is an absolute path,
|
|
or contained a ".." component leading to a
|
|
directory outside of the directory hierarchy specified by
|
|
.Fa fd ,
|
|
and the process is in capability mode.
|
|
.It Bq Er ENOTCAPABLE
|
|
The
|
|
.Dv AT_BENEATH
|
|
flag was provided to
|
|
.Fn fstatat ,
|
|
and the absolute
|
|
.Fa path
|
|
does not have its tail fully contained under the topping directory,
|
|
or the relative
|
|
.Fa path
|
|
escapes it.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr access 2 ,
|
|
.Xr chmod 2 ,
|
|
.Xr chown 2 ,
|
|
.Xr fhstat 2 ,
|
|
.Xr statfs 2 ,
|
|
.Xr utimes 2 ,
|
|
.Xr sticky 7 ,
|
|
.Xr symlink 7
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn stat
|
|
and
|
|
.Fn fstat
|
|
system calls are expected to conform to
|
|
.St -p1003.1-90 .
|
|
The
|
|
.Fn fstatat
|
|
system call follows The Open Group Extended API Set 2 specification.
|
|
.Sh HISTORY
|
|
The
|
|
.Fn stat
|
|
and
|
|
.Fn fstat
|
|
system calls appeared in
|
|
.At v1 .
|
|
The
|
|
.Fn lstat
|
|
system call appeared in
|
|
.Bx 4.2 .
|
|
The
|
|
.Fn fstatat
|
|
system call appeared in
|
|
.Fx 8.0 .
|
|
.Sh BUGS
|
|
Applying
|
|
.Fn fstat
|
|
to a socket
|
|
returns a zeroed buffer,
|
|
except for the blocksize field,
|
|
and a unique device and inode number.
|