284 lines
8.0 KiB
Groff
284 lines
8.0 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. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. 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.3 (Berkeley) 4/19/94
|
|
.\" $Id: stat.2,v 1.5 1996/08/29 21:24:17 wosch Exp $
|
|
.\"
|
|
.Dd April 19, 1994
|
|
.Dt STAT 2
|
|
.Os BSD 4
|
|
.Sh NAME
|
|
.Nm stat ,
|
|
.Nm lstat ,
|
|
.Nm fstat
|
|
.Nd get file status
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <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
|
|
.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.
|
|
Unlike other filesystem objects,
|
|
symbolic links do not have an owner, group, access mode, times, etc.
|
|
Instead, these attributes are taken from the directory that
|
|
contains the link.
|
|
The only attributes returned from an
|
|
.Fn lstat
|
|
that refer to the symbolic link itself are the file type (S_IFLNK),
|
|
size, blocks, and link count (always 1).
|
|
.Pp
|
|
The
|
|
.Fn fstat
|
|
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
|
|
.Fn stat
|
|
structure
|
|
as defined by
|
|
.Aq Pa sys/stat.h
|
|
(shown below)
|
|
and into which information is placed concerning the file.
|
|
.Bd -literal
|
|
struct stat {
|
|
dev_t st_dev; /* device inode resides on */
|
|
ino_t st_ino; /* inode's number */
|
|
mode_t st_mode; /* inode protection mode */
|
|
nlink_t st_nlink; /* number or hard links to the file */
|
|
uid_t st_uid; /* user-id of owner */
|
|
gid_t st_gid; /* group-id of owner */
|
|
dev_t st_rdev; /* device type, for special file inode */
|
|
struct timespec st_atimespec; /* time of last access */
|
|
struct timespec st_mtimespec; /* time of last data modification */
|
|
struct timespec st_ctimespec; /* time of last file status change */
|
|
off_t st_size; /* file size, in bytes */
|
|
quad_t st_blocks; /* blocks allocated for file */
|
|
u_long st_blksize;/* optimal file sys I/O ops blocksize */
|
|
u_long st_flags; /* user defined flags for file */
|
|
u_long st_gen; /* file generation number */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The time-related fields of
|
|
.Fa struct stat
|
|
are as follows:
|
|
.Bl -tag -width XXXst_mtime
|
|
.It st_atime
|
|
Time when file data last accessed.
|
|
Changed by the
|
|
.Xr mknod 2 ,
|
|
.Xr utimes 2
|
|
and
|
|
.Xr read 2
|
|
system calls.
|
|
.It st_mtime
|
|
Time when file data last modified.
|
|
Changed by the
|
|
.Xr mknod 2 ,
|
|
.Xr utimes 2
|
|
and
|
|
.Xr write 2
|
|
system calls.
|
|
.It st_ctime
|
|
Time when file status was last changed (inode data modification).
|
|
Changed by the
|
|
.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 XXXst_blksize
|
|
.It st_blksize
|
|
The optimal I/O block size for the file.
|
|
.It 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
|
|
has the following bits:
|
|
.Bd -literal
|
|
#define S_IFMT 0170000 /* type of file */
|
|
#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_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_IRUSR 0000400 /* read permission, owner */
|
|
#define S_IWUSR 0000200 /* write permission, owner */
|
|
#define S_IXUSR 0000100 /* execute/search permission, owner */
|
|
.Ed
|
|
.Pp
|
|
For a list of access modes, see
|
|
.Aq Pa sys/stat.h ,
|
|
.Xr access 2
|
|
and
|
|
.Xr chmod 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 ENAMETOOLONGAA
|
|
.It Bq Er ENOTDIR
|
|
A component of the path prefix is not a directory.
|
|
.It Bq Er EINVAL
|
|
The pathname contains a character with the high-order bit set.
|
|
.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 EACCES
|
|
Search permission is denied for a component of the path prefix.
|
|
.It Bq Er ELOOP
|
|
Too many symbolic links were encountered in translating the pathname.
|
|
.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.
|
|
.El
|
|
.Pp
|
|
.Bl -tag -width [EFAULT]
|
|
.Fn Fstat
|
|
will fail if:
|
|
.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 CAVEAT
|
|
The fields in the stat structure currently marked
|
|
.Fa st_spare1 ,
|
|
.Fa st_spare2 ,
|
|
and
|
|
.Fa st_spare3
|
|
are present in preparation for inode time stamps expanding
|
|
to 64 bits. This, however, can break certain programs that
|
|
depend on the time stamps being contiguous (in calls to
|
|
.Xr utimes 2 ) .
|
|
.Sh SEE ALSO
|
|
.Xr chmod 2 ,
|
|
.Xr chown 2 ,
|
|
.Xr utimes 2 ,
|
|
.Xr symlink 7
|
|
.Sh BUGS
|
|
Applying
|
|
.Fn fstat
|
|
to a socket (and thus to a pipe)
|
|
returns a zeroed buffer,
|
|
except for the blocksize field,
|
|
and a unique device and inode number.
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn stat
|
|
and
|
|
.Fn fstat
|
|
function calls are expected to
|
|
conform to IEEE Std 1003.1-1988
|
|
.Pq Dq Tn POSIX .
|
|
.Sh HISTORY
|
|
A
|
|
.Fn stat
|
|
and a
|
|
.Fn fstat
|
|
function call appeared in
|
|
.At v7 .
|
|
A
|
|
.Fn lstat
|
|
function call appeared in
|
|
.Bx 4.2 .
|