300 lines
8.6 KiB
Groff
300 lines
8.6 KiB
Groff
.\" $NetBSD: stat.2,v 1.31 2003/04/16 13:34:57 wiz 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. 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.4 (Berkeley) 5/1/95
|
|
.\"
|
|
.Dd May 1, 1995
|
|
.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
|
|
.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.
|
|
.Pp
|
|
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
|
|
.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 containing the file */
|
|
ino_t st_ino; /* file's serial number */
|
|
mode_t st_mode; /* file's mode (protection and type) */
|
|
nlink_t st_nlink; /* number of 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 device special file */
|
|
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 */
|
|
int64_t st_blocks; /* blocks allocated for file */
|
|
u_int32_t st_blksize; /* optimal file sys I/O ops blocksize */
|
|
u_int32_t st_flags; /* user defined flags for file */
|
|
u_int32_t 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 was last accessed.
|
|
Changed by the
|
|
.Xr mknod 2 ,
|
|
.Xr utimes 2
|
|
and
|
|
.Xr read 2
|
|
system calls.
|
|
.It 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 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 XXXst_blksize
|
|
.It st_size
|
|
The size of the file in bytes.
|
|
A directory will be a multiple of the size of the
|
|
.Xr dirent 5
|
|
structure.
|
|
.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_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_IRUSR 0000400 /* read permission, owner */
|
|
#define S_IWUSR 0000200 /* write permission, owner */
|
|
#define S_IXUSR 0000100 /* execute/search permission, owner */
|
|
#define S_IRGRP 0000040 /* read permission, group */
|
|
#define S_IWGRP 0000020 /* write permission, group */
|
|
#define S_IXGRP 0000010 /* execute/search permission, group */
|
|
#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
|
|
.Aq Pa sys/stat.h ,
|
|
.Xr access 2
|
|
and
|
|
.Xr chmod 2 .
|
|
.Pp
|
|
The status information word
|
|
.Fa st_flags
|
|
has the following bits:
|
|
.Bd -literal
|
|
#define UF_NODUMP 0x00000001 /* do not dump file */
|
|
#define UF_IMMUTABLE 0x00000002 /* file may not be changed */
|
|
#define UF_APPEND 0x00000004 /* writes to file may only append */
|
|
#define UF_OPAQUE 0x00000008 /* directory is opaque wrt. union */
|
|
#define SF_ARCHIVED 0x00010000 /* file is archived */
|
|
#define SF_IMMUTABLE 0x00020000 /* file may not be changed */
|
|
#define SF_APPEND 0x00040000 /* writes to file may only append */
|
|
.Ed
|
|
.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 ENOTDIR
|
|
A component of the path prefix is not a directory.
|
|
.It Bq Er ENAMETOOLONG
|
|
A component of a pathname exceeded
|
|
.Dv {NAME_MAX}
|
|
characters, or an entire path name exceeded
|
|
.Dv {PATH_MAX}
|
|
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 ENXIO
|
|
The named file is a character special or block
|
|
special file, and the device associated with this special file
|
|
does not exist.
|
|
.It Bq Er EIO
|
|
An I/O error occurred while reading from or writing to the file system.
|
|
.It Bq Er EBADF
|
|
A badly formed v-node was encountered.
|
|
This can happen if a file system information node is incorrect.
|
|
.El
|
|
.Pp
|
|
.Bl -tag -width Er
|
|
.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 SEE ALSO
|
|
.Xr chflags 2 ,
|
|
.Xr chmod 2 ,
|
|
.Xr chown 2 ,
|
|
.Xr utimes 2 ,
|
|
.Xr dir 5 ,
|
|
.Xr symlink 7
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn stat
|
|
and
|
|
.Fn fstat
|
|
functions conform to
|
|
.St -p1003.1-90 .
|
|
.Sh HISTORY
|
|
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.
|