p .Fn lstat is like .Fn stat except in the case where the named file is a symbolic link, in which case .Fn lstat returns information about the link, while .Fn stat returns information about the file the link references.
p The .Fn fstat function obtains the same information about an open file known by the file descriptor .Fa fd .
p The .Fa sb argument is a pointer to a .Fa stat structure as defined by n sys/stat.h (shown below) and into which information is placed concerning the file. d -literal struct stat { dev_t st_dev; /* device containing the file */ ino_t st_ino; /* file's serial number */ mode_t st_mode; /* file's mode (protection and type) */ nlink_t st_nlink; /* number of hard links to the file */ uid_t st_uid; /* user-id of owner */ gid_t st_gid; /* group-id of owner */ dev_t st_rdev; /* device type, for device special file */ #if defined(_NETBSD_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 */ blkcnt_t st_blocks; /* blocks allocated for file */ blksize_t st_blksize; /* optimal file sys I/O ops blocksize */ uint32_t st_flags; /* user defined flags for file */ uint32_t st_gen; /* file generation number */ #if defined(_NETBSD_SOURCE) struct timespec st_birthtimespec; /* time of inode creation */ #else time_t st_birthtime; /* time of inode creation */ long st_birthtimensec; /* nsec of inode creation */ #endif }; .Ed
p The time-related fields of .Fa struct stat are as follows: l -tag -width XXXst_birthtime t st_atime Time when file data was last accessed. Changed by the .Xr mknod 2 , .Xr utimes 2 and .Xr read 2 system calls. t st_mtime Time when file data was last modified. Changed by the .Xr mknod 2 , .Xr utimes 2 and .Xr write 2 system calls. t st_ctime Time when file status was last changed (file metadata modification). Changed by the .Xr chflags 2 , .Xr chmod 2 , .Xr chown 2 , .Xr link 2 , .Xr mknod 2 , .Xr rename 2 , .Xr unlink 2 , .Xr utimes 2 and .Xr write 2 system calls. t st_birthtime Time when the inode was created. .El
p If .Dv _NETBSD_SOURCE is defined, the time-related fields are defined as: d -literal #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 .Ed
p The size-related fields of the .Fa struct stat are as follows: l -tag -width XXXst_blksize t st_size The size of the file in bytes. A directory will be a multiple of the size of the .Xr dirent 5 structure. Some filesystems (notably ZFS) return the number of entries in the directory instead of the size in bytes. t st_blksize The optimal I/O block size for the file. t 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. .El
p The status information word .Fa st_mode has the following bits: d -literal #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 */ #define S_IRGRP 0000040 /* read permission, group */ #define S_IWGRP 0000020 /* write permission, group */ #define S_IXGRP 0000010 /* execute/search permission, group */ #define S_IROTH 0000004 /* read permission, other */ #define S_IWOTH 0000002 /* write permission, other */ #define S_IXOTH 0000001 /* execute/search permission, other */ .Ed
p For a list of access modes, see n sys/stat.h , .Xr access 2 and .Xr chmod 2 .
p The status information word .Fa st_flags has the following bits: d -literal #define UF_NODUMP 0x00000001 /* do not dump file */ #define UF_IMMUTABLE 0x00000002 /* file may not be changed */ #define UF_APPEND 0x00000004 /* writes to file may only append */ #define UF_OPAQUE 0x00000008 /* directory is opaque wrt. union */ #define SF_ARCHIVED 0x00010000 /* file is archived */ #define SF_IMMUTABLE 0x00020000 /* file may not be changed */ #define SF_APPEND 0x00040000 /* writes to file may only append */ .Ed
p For a description of the flags, see .Xr chflags 2 . .Sh RETURN VALUES Upon successful completion a value of 0 is returned. Otherwise, a value of -1 is returned and .Va errno is set to indicate the error. .Sh COMPATIBILITY Previous versions of the system used different types for the .Li st_dev , .Li st_uid , .Li st_gid , .Li st_rdev , .Li st_size , .Li st_blksize and .Li st_blocks fields. .Sh ERRORS .Fn stat and .Fn lstat will fail if: l -tag -width Er t Bq Er EACCES Search permission is denied for a component of the path prefix. t Bq Er EBADF A badly formed v-node was encountered. This can happen if a file system information node is incorrect. t Bq Er EFAULT .Fa sb or .Em name points to an invalid address. t Bq Er EIO An I/O error occurred while reading from or writing to the file system. t Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. t Bq Er ENAMETOOLONG A component of a pathname exceeded .Dv { NAME_MAX } characters, or an entire path name exceeded .Dv { PATH_MAX } characters. t Bq Er ENOENT The named file does not exist. t Bq Er ENOTDIR A component of the path prefix is not a directory. t Bq Er ENXIO The named file is a character special or block special file, and the device associated with this special file does not exist. .El
p .Fn fstat will fail if: l -tag -width Er t Bq Er EBADF .Fa fd is not a valid open file descriptor. t Bq Er EFAULT .Fa sb points to an invalid address. t Bq Er EIO An I/O error occurred while reading from or writing to the file system. .El .Sh SEE ALSO .Xr chflags 2 , .Xr chmod 2 , .Xr chown 2 , .Xr utimes 2 , .Xr dir 5 , .Xr symlink 7 .Sh STANDARDS The .Fn stat and .Fn fstat functions conform to .St -p1003.1-90 . .Sh HISTORY A .Fn stat function call appeared in .At v2 . A .Fn lstat function call appeared in x 4.2 . .Sh BUGS Applying .Fn fstat to a socket (and thus to a pipe) returns a zero'd buffer, except for the blocksize field, and a unique device and file serial number.