stat(2) stat(2)
NAME
stat, lstat, fstat - get file status
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
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.
Note that in a Remote File Sharing environment, the information
returned by stat depends on the user/group mapping set up between the
local and remote computers.
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 open, creat, dup,
fcntl, or pipe 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:
modet stmode; /* File mode [see mknod(2)] */
inot stino; /* Inode number */
devt stdev; /* ID of device containing */
/* a directory entry for this file */
devt strdev; /* ID of device */
/* This entry is defined only for */
/* char special or block special files */
nlinkt stnlink; /* Number of links */
uidt stuid; /* User ID of the file's owner */
gidt stgid; /* Group ID of the file's group */
offt stsize; /* File size in bytes */
timestructt statime;/* Time of last access */
timestructt stmtime;/* Time of last data modification */
8/91 Page 1
stat(2) stat(2)
timestructt stctime;/* Time of last file status change */
/* Times measured in seconds since */
/* 00:00:00 UTC, Jan. 1, 1970 */
long stblksize; /* Preferred I/O block size */
long stblocks; /* Number stblksize blocks allocated */
stmode 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.)
stino This field uniquely identifies the file in a given file
system. The pair stino and stdev uniquely identifies
regular files.
stdev This field uniquely identifies the file system that
contains the file. 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.
strdev This field should be used only by administrative commands.
It is valid only for block special or character special
files and only has meaning on the system where the file was
configured.
stnlink This field should be used only by administrative commands.
stuid The user ID of the file's owner.
stgid The group ID of the file's group.
stsize For regular files, this is the address of the end of the
file. For block special or character special, this is not
defined. See also pipe(2).
statime Time when file data was last accessed. Changed by the
following system calls: creat, mknod, pipe, utime, and
read.
stmtime Time when data was last modified. Changed by the following
system calls: creat, mknod, pipe, utime, and write.
stctime Time when file status was last changed. Changed by the
following system calls: chmod, chown, creat, link, mknod,
pipe, unlink, utime, and write.
stblksize
A hint as to the "best" unit size for I/O operations. This
field is not defined for block-special or character-special
files.
Page 2 8/91
stat(2) stat(2)
stblocks 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.
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.
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
{PATHMAX}, or the length of a path component
exceeds {NAMEMAX} while POSIXNOTRUNC is in
effect.
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.
ENOLINK fildes points to a remote machine and the link to
that machine is no longer active.
8/91 Page 3
stat(2) stat(2)
EOVERFLOW A component is too large to store in the
structure pointed to by buf.
SEE ALSO
chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2), read(2),
time(2), unlink(2), utime(2), write(2), fattach(3C), stat(5).
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 8/91