FreeBSD Manual Pages
STAT(2) BSD System Calls Manual STAT(2) NAME stat, lstat, fstat -- get file status LIBRARY Standard C Library (libc, -lc) SYNOPSIS #include <sys/types.h> #include <sys/stat.h> int stat(const char *path, struct stat *sb); int lstat(const char *path, struct stat *sb); int fstat(int fd, struct stat *sb); DESCRIPTION The stat() function obtains information about the file pointed to by path. Read, write or execute permission of the named file is not re- quired, but all directories listed in the path name leading to the file must be searchable. The lstat() function 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 refer- ences. 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 concern- ing the file. struct stat { dev_t st_dev; /* inode's device */ ino_t st_ino; /* inode's number */ mode_t st_mode; /* inode protection mode */ nlink_t st_nlink; /* number of hard links */ uid_t st_uid; /* user ID of the file's owner */ gid_t st_gid; /* group ID of the file's group */ dev_t st_rdev; /* device type */ #ifndef _POSIX_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 */ int64_t st_blocks; /* blocks allocated for file */ u_int32_t st_blksize; /* optimal blocksize for I/O */ fflags_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; The time-related fields of struct stat are as follows: st_atime Time when file data last accessed. Changed by the mknod(2), utimes(2) and read(2) system calls. st_mtime Time when file data last modified. Changed by the mknod(2), utimes(2) and write(2) system calls. st_ctime Time when file status was last changed (inode data modifica- tion). Changed by the chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2) and write(2) sys- tem calls. If _POSIX_SOURCE is not defined, the time-related fields are defined as: #ifndef _POSIX_SOURCE #define st_atime st_atimespec.tv_sec #define st_mtime st_mtimespec.tv_sec #define st_ctime st_ctimespec.tv_sec #endif The size-related fields of the struct stat are as follows: st_blksize The optimal I/O block size for the file. st_blocks The actual number of blocks allocated for the file in 512-byte units. As short symbolic links are stored in the inode, this number may be zero. 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 */ For a list of access modes, see <sys/stat.h>, access(2) and chmod(2). RETURN VALUES Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable errno is set to indicate the error. COMPATIBILITY Previous versions of the system used different types for the st_dev, st_uid, st_gid, st_rdev, st_size, st_blksize and st_blocks fields. ERRORS The stat() and lstat() functions will fail if: [EACCES] Search permission is denied for a component of the path prefix. [EFAULT] sb or name points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. [ELOOP] Too many symbolic links were encountered in translat- ing the pathname. [ENAMETOOLONG] A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. [ENOENT] The named file does not exist. [ENOTDIR] A component of the path prefix is not a directory. [EOVERFLOW] The file size in bytes cannot be represented correctly in the structure pointed to by sb. The fstat() function will fail if: [EBADF] fd is not a valid open file descriptor. [EFAULT] sb points to an invalid address. [EIO] An I/O error occurred while reading from or writing to the file system. [EOVERFLOW] The file size in bytes cannot be represented correctly in the structure pointed to by sb. SEE ALSO access(2), chmod(2), chown(2), utimes(2), symlink(7) BUGS Applying fstat() to a socket (and thus to a pipe) returns a zeroed buf- fer, except for the blocksize field, and a unique device and inode num- ber. STANDARDS The stat() and fstat() function calls are expected to conform to ISO/IEC 9945-1:1990 ("POSIX.1"). HISTORY A stat() and a fstat() function call appeared in Version 7 AT&T UNIX. A lstat() function call appeared in 4.2BSD. BSD February 15, 2002 BSD
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | COMPATIBILITY | ERRORS | SEE ALSO | BUGS | STANDARDS | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=stat&sektion=2&manpath=FreeBSD+5.0-RELEASE>