stat(2)stat(2)NAME
stat, lstat, fstat - get file status
C SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
int stat(const char *path, struct stat *buf);
int lstat(const char *path, struct stat *buf);
int fstat(int fildes, struct stat *buf);
DESCRIPTION
The only difference between the *stat and the *stat64 calls is that the
*stat64 calls return a stat64 structure, with three fields increased in
size to allow for larger files and filesystems: st_ino, st_size, and
st_blocks are all 64-bit values.
NOTE: All programs compiled either -n32 or -64 get the stat64 versions
of the stat system call, even when calling stat. Only programs compiled
-o32 get the version with the smaller field sizes, for binary
compatibility.
path points to a path name naming a file. 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. stat obtains
information about the named file.
lstat obtains file attributes similar to stat, except when the named file
is a symbolic link; in that case lstat returns information about the
link, while stat returns information about the file the link references.
fstat obtains information about an open file known by the file descriptor
fildes, obtained from a successful creat, open, dup, fcntl, pipe, or
ioctl system call.
buf is a pointer to a stat structure into which information is placed
concerning the file.
The contents of the structure pointed to by buf include the following
members:
mode_t st_mode; /* File mode */
ino_t st_ino; /* Inode number */
dev_t st_dev; /* ID of device containing */
/* a directory entry for this file */
dev_t st_rdev; /* ID of device */
/* This entry is defined only for */
/* char special, block special, */
/* and lofs files */
nlink_t st_nlink; /* Number of links */
Page 1
stat(2)stat(2)
uid_t st_uid; /* User ID of the file's owner */
gid_t st_gid; /* Group ID of the file's group */
off_t st_size; /* File size in bytes */
timespec_t st_atim; /* Time of last access */
timespec_t st_mtim; /* Time of last data modification */
timespec_t st_ctim; /* Time of last file status change */
/* Times measured in seconds and nanoseconds */
/* since 00:00:00 UTC, Jan. 1, 1970 */
long st_blksize; /* Preferred I/O block size */
blkcnt_t st_blocks; /* Number 512 byte blocks allocated */
The fields have the following meanings:
st_mode The mode of the file as described in mknod(2). In addition to
the modes described in mknod(2), the mode of a file may also be
S_IFLNK if the file is a symbolic link. (Note that S_IFLNK may
only be returned by lstat.) The various macros in sys/stat.h
should be used to determine if there is a type match, since the
types are not a bit field. For example, you should use
S_ISDIR(st.st_mode) rather than (st.st_mode&S_IFDIR).
st_ino Except for lofs file systems this field uniquely identifies the
file in a given file system and the pair st_ino and st_dev
uniquely identify regular files and directories. For regular
files and directories accessed via an "lofs" file system, the
value of this field is obtained from the underlying file
system, and the st_rdev field must also be used to identify
uniqueness.
st_dev Except for lofs file systems this field uniquely identifies the
file system that contains the file. Beware that this is still
true for NFS file systems exported using the -nohide option,
which may not appear in /etc/mtab. [See exports(4).] Its value
may be used as input to the ustat system call to determine more
information about this file system. No other meaning is
associated with this value. For regular files and directories
accessed via an "lofs" file system, the value of this field is
obtained from the underlying file system, and the st_rdev field
must also be used to identify uniqueness.
st_rdev This field should be used only by administrative commands. It
is valid only for block special, character special, and files
and directories accessed via "lofs" file systems. It only has
meaning on the system where the file was configured.
st_nlink This field should be used only by administrative commands.
st_uid The user ID of the file's owner.
st_gid The group ID of the file's group.
Page 2
stat(2)stat(2)
st_size For regular files, this is the address of the end of the file.
If the file's size is larger than will fit in the st_size field
(2^31 - 1) then the value (2^31 - 1) is returned there instead.
See also stat64(2). For block special or character special,
this is not defined. See also pipe(2).
st_atim Time when file data was last accessed. Changed by the
following system calls: creat, mknod, pipe, utime, and read.
The seconds portion of st_atim is available as st_atime.
st_mtim Time when data was last modified. Changed by the following
system calls: creat, mknod, pipe, utime, and write. The
seconds portion of st_mtim is available as st_mtime.
st_ctim Time when file status was last changed. Changed by the
following system calls: chmod, chown, creat, link, mknod,
pipe, unlink, utime, and write. The seconds portion of st_ctim
is available as st_ctime.
st_blksize
A hint as to the ``best'' unit size for I/O operations. If the
underlying volume is a stripe volume, then st_blksize is set to
the stripe width. This field is not defined for block-special
or character-special files.
st_blocks The total number of physical blocks of size 512 bytes actually
allocated on disk. This field is not defined for block-special
or character-special files. Holes in files (blocks never
allocated) are not counted in this value; indirect blocks
(those used to store pointers to blocks in the file) are
counted.
stat and lstat fail if one or more of the following are true:
EACCES Search permission is denied for a component of the path prefix.
EFAULT buf or path points to an invalid address.
EINTR A signal was caught during the stat or lstat system call.
ETIMEDOUT The named file is located on a remote file system which is not
available [see intro(2)].
ELOOP Too many symbolic links were encountered in translating path.
EMULTIHOP Components of path require hopping to multiple remote machines
and the file system does not allow it.
ENAMETOOLONG
The length of the path argument exceeds {PATH_MAX}, or the
length of a path component exceeds {NAME_MAX} while
_POSIX_NO_TRUNC is in effect.
Page 3
stat(2)stat(2)
ENOENT The named file does not exist or is the null pathname.
ENOTDIR A component of the path prefix is not a directory.
ENOLINK path points to a remote machine and the link to that machine is
no longer active.
EOVERFLOW A component is too large to store in the structure pointed to
by buf.
fstat fails if one or more of the following are true:
EBADF fildes is not a valid open file descriptor.
EFAULT buf points to an invalid address.
EINTR A signal was caught during the fstat system call.
ETIMEDOUT fildes refers to a file on a remote file system which is not
available [see intro(2)].
ENOLINK fildes refers to a file on a remote machine and the link to
that machine is no longer active.
EOVERFLOW A component is too large to store in the structure pointed to
by buf.
SEE ALSOchmod(2), chown(2), creat(2), exports(4), fattach(3C), link(2), mknod(2),
pipe(2), read(2), stat64(2), realpath(3C), stat(5), stat64(5), time(2),
unlink(2), utime(2), write(2)DIAGNOSTICS
Upon successful completion a value of 0 is returned. Otherwise, a value
of -1 is returned and errno is set to indicate the error.
Page 4
