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 */ 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. 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. 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 ALSO chmod(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