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/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 function lstat() 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> and into which information is placed concerning the file. The Standard Structure The following standards-compliant fields are defined in the structure: Type Entry Description dev_t st_dev device ID containing the file ino_t st_ino serial number of the file mode_t st_mode mode of the file nlink_t st_nlink number of hard links to the file uid_t st_uid user ID of the owner gid_t st_gid group ID of the owner dev_t st_rdev device type (character or block special) off_t st_size size of the file in bytes time_t st_atime time of last access time_t st_mtime time of last data modification time_t st_ctime time of last file status change blksize_t st_blksize preferred I/O block size (fs-specific) blkcnt_t st_blocks blocks allocated for the file These are specified in the IEEE Std 1003.1-2004 ("POSIX.1") standard. The st_ino and st_dev fields taken together uniquely identify the file within the system. Most of the types are defined in types(3). The time-related fields are: st_atime Time when file data was last accessed. Changed by the mknod(2), utimes(2), and read(2) system calls. st_mtime Time when file data was last modified. Changed by the mknod(2), utimes(2), and write(2) system calls. st_ctime Time when file status was last changed (file metadata modification). Changed by the chflags(2), chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), and write(2) system calls. The size-related fields of the struct stat are as follows: st_size The size of the file in bytes. The meaning of the size reported for a directory is file system dependent. Some file systems (e.g. FFS) return the total size used for the directory metadata, possibly including free slots; others (notably ZFS) return the number of en- tries in the directory. Some may also return other things or always report zero. 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 contains bits that define the access mode (see chmod(2)) and the type (see dirent(3)) of the file. The fol- lowing macros can be used to test whether a file is of the specified type. The value m supplied to the macros is the value of st_mode. S_ISBLK(m) Test for a block special file. S_ISCHR(m) Test for a character special file. S_ISDIR(m) Test for a directory. S_ISFIFO(m) Test for a pipe or FIFO special file. S_ISREG(m) Test for a regular file. S_ISLNK(m) Test for a symbolic link. S_ISSOCK(m) Test for a socket. The macros evaluate to a non-zero value if the test is true or to the value 0 if the test is false. NetBSD Extensions The following additional NetBSD specific fields are present: Type Entry Description long st_atimensec last access (nanoseconds) long st_mtimensec last modification (nanoseconds) long st_ctimensec last status change (nanoseconds) time_t st_birthtime time of inode creation long st_birthtimensec inode creation (nanoseconds) uint32_t st_flags user defined flags for the file uint32_t st_gen file generation number uint32_t st_spare[2] implementation detail However, if _NETBSD_SOURCE is furthermore defined, instead of the above, the following are present in the structure: Type Entry Description struct timespec st_atimespec time of last access struct timespec st_mtimespec time of last modification struct timespec st_birthtimespec time of creation uint32_t st_flags user defined flags uint32_t st_gen file generation number uint32_t st_spare[2] implementation detail In this case the following macros are provided for convenience: #if defined(_NETBSD_SOURCE) #define st_atime st_atimespec.tv_sec #define st_atimensec st_atimespec.tv_nsec #define st_mtime st_mtimespec.tv_sec #define st_mtimensec st_mtimespec.tv_nsec #define st_ctime st_ctimespec.tv_sec #define st_ctimensec st_ctimespec.tv_nsec #define st_birthtime st_birthtimespec.tv_sec #define st_birthtimensec st_birthtimespec.tv_nsec #endif The status information word st_flags has the following bits: Constant Description UF_NODUMP do not dump a file UF_IMMUTABLE file may not be changed UF_APPEND writes to file may only append UF_OPAQUE directory is opaque wrt. union SF_ARCHIVED file is archived SF_IMMUTABLE file may not be changed SF_APPEND writes to file may only append For a description of the flags, see chflags(2). RETURN VALUES Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is returned and 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 stat() and lstat() will fail if: [EACCES] Search permission is denied for a component of the path prefix. [EBADF] A badly formed vnode was encountered. This can happen if a file system information node is incorrect. [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 {NAME_MAX} charac- ters, or an entire path name exceeded {PATH_MAX} char- acters. [ENOENT] The named file does not exist. [ENOTDIR] A component of the path prefix is not a directory. [ENXIO] The named file is a character special or block special file, and the device associated with this special file does not exist. fstat() 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. SEE ALSO chflags(2), chmod(2), chown(2), utimes(2), dirent(3), types(3), symlink(7) STANDARDS The described functions conform to IEEE Std 1003.1-2004 ("POSIX.1"). HISTORY A stat() function call appeared in Version 2 AT&T UNIX. A lstat() func- tion call appeared in 4.2BSD. BUGS Applying fstat() to a socket (and thus to a pipe) returns a zero'd buf- fer, except for the blocksize field, and a unique device and file serial number. BSD September 14, 2011 BSD
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | COMPATIBILITY | ERRORS | SEE ALSO | STANDARDS | HISTORY | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=stat&sektion=2&manpath=NetBSD+6.0>