stat(2) stat(2)
NAME
stat, lstat, fstat, stat64, lstat64, fstat64 - 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);
int fstat64(int fildes, struct stat64 *buf);
int lstat64(const char *, struct stat64 *buf);
int stat64(const char *, struct stat64 *buf);
DESCRIPTION
The stat() function obtains information about the named file and
writes it to the structure pointed to by buf. 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 pathname lead-
ing to the file must be searchable.
lstat() obtains file attributes similar to stat(), except when the
named file is a symbolic link; in that case lstat() returns informa-
tion 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.
There is no functional difference between stat()/lstat()/fstat() and
stat64()/lstat64()/fstat64(), except for the interpretation of
stat/stat64 [see stat(5)].
The contents of the stat structure pointed to by buf include the fol-
lowing 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 */
Page 1 Reliant UNIX 5.44 Printed 11/98
stat(2) stat(2)
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 */
timet statime; /* Time of last access */
timet stmtime; /* Time of last data modification */
timet 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 */
blkcntt stblocks; /* Number 512 bytes blocks allocated */
The stat64 structure is defined in the same way as the stat structure
with the exception of the following members:
ino64t stino File serial number.
off64t stsize File size in bytes.
blkcnt64t stblocks Number of blocks allocated for this object.
stmode The mode of the file as described in mknod(2). In addi-
tion to the modes described in mknod(2), the mode of a
file may also be SIFLNK if the file is a symbolic link.
(Note that SIFLNK may only be returned by lstat().)
stino Uniquely identifies the file in a given file system. The
pair stino and stdev uniquely identifies regular
files.
stdev Uniquely identifies the file system that contains the
file. Its value may be used as input to the ustat(2)
system call to determine more information about this
file system.
strdev 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 May 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).
Page 2 Reliant UNIX 5.44 Printed 11/98
stat(2) stat(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 follow-
ing 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.
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.
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
stat() and lstat() fail if one or more of the following apply:
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 a path component exceeds NAME-MAX charac-
ters, or the length of the path exceeds PATHMAX charac-
ters.
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.
Page 3 Reliant UNIX 5.44 Printed 11/98
stat(2) stat(2)
EOVERFLOW A component is too large to store in the structure
pointed to by buf.
The file size in bytes or the number of blocks allocated
to the file or the file serial number cannot be repre-
sented correctly in the structure pointed to by buf.
fstat() fails if one or more of the following apply:
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.
EOVERFLOW A component is too large to store in the structure
pointed to by buf.
The file size in bytes or the number of blocks allocated
to the file or the file serial number cannot be repre-
sented correctly in the structure pointed to by buf.
RESULT
Upon successful completion a value of 0 is returned. Otherwise, a
value of -1 is returned and errno is set to indicate the error.
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), lfs(5), stat(5),
types(5).
Page 4 Reliant UNIX 5.44 Printed 11/98