int
stat(
const char *path
, struct stat *sb
)
int
lstat(
const char *path
, struct stat *sb
)
int
fstat(
int fd
, struct stat *sb
)
)
function obtains information about the file pointed to by
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.
lstat()
is like
stat(
)
except in the case where the named file is a symbolic link,
in which case
lstat(
)
returns information about the link,
while
stat(
)
returns information about the file the link references.
The
fstat()
function obtains the same information about an open file
known by the file descriptor
fd
.
The
sb
argument is a pointer to a
stat
structure
as defined by
<sys/stat.h
>
(shown below)
and into which information is placed concerning the file.
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 */
#if defined(_NETBSD_SOURCE)
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 */
#else
time_t st_atime; /* time of last access */
long st_atimensec; /* nsec of last access */
time_t st_mtime; /* time of last data modification */
long st_mtimensec; /* nsec of last data modification */
time_t st_ctime; /* time of last file status change */
long st_ctimensec; /* nsec of last file status change */
#endif
off_t st_size; /* file size, in bytes */
blkcnt_t st_blocks; /* blocks allocated for file */
blksize_t st_blksize; /* optimal file sys I/O ops blocksize */
uint32_t st_flags; /* user defined flags for file */
uint32_t st_gen; /* file generation number */
#if defined(_NETBSD_SOURCE)
struct timespec st_birthtimespec; /* time of inode creation */
#else
time_t st_birthtime; /* time of inode creation */
long st_birthtimensec; /* nsec of inode creation */
#endif
};
The time-related fields of
struct
stat
are as follows:
If
_NETBSD_SOURCE
is defined, the time-related fields are defined as:
#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
The size-related fields of the
struct
stat
are as follows:
The status information word
st_mode
has the following bits:
#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 */
For a list of access modes, see
<sys/stat.h
>,
access(2)
and
chmod(2).
The status information word
st_flags
has the following bits:
#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 */
For a description of the flags, see chflags(2).
st_dev
,
st_uid
,
st_gid
,
st_rdev
,
st_size
,
st_blksize
and
st_blocks
fields.
)
and
lstat(
)
will fail if:
ENOTDIR
]
ENAMETOOLONG
]
{NAME_MAX}
characters, or an entire path name exceeded
{PATH_MAX}
characters.
ENOENT
]
EACCES
]
ELOOP
]
EFAULT
]
sb
or
name
points to an invalid address.
ENXIO
]
EIO
]
EBADF
]
)
will fail if:
EBADF
]
fd
is not a valid open file descriptor.
EFAULT
]
sb
points to an invalid address.
EIO
]
)
and
fstat(
)
functions conform to
ISO/IEC 9945-1:1990 (``POSIX.1'') .
)
function call appeared in
4.2BSD.
)
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.