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 .Fn stat structure as defined by .Aq Pa sys/stat.h (shown below) and into which information is placed concerning the file. d -literal 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 or 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 special file inode */ 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 */ off_t st_size; /* file size, in bytes */ int64_t st_blocks; /* blocks allocated for file */ u_int32_t st_blksize; /* optimal file sys I/O ops blocksize */ u_int32_t st_flags; /* user defined flags for file */ u_int32_t st_gen; /* file generation number */ }; .Ed
p The time-related fields of .Fa struct stat are as follows: l -tag -width XXXst_mtime 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 (inode data 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. .El
p The size-related fields of the .Fa struct stat are as follows: l -tag -width XXXst_blksize 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 .Aq Pa 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 ENOTDIR A component of the path prefix is not a directory. 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 EACCES Search permission is denied for a component of the path prefix. t Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. 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. .El
p l -tag -width Er .Fn fstat will fail if: 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 symlink 7 .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 inode number. .Sh STANDARDS The .Fn stat and .Fn fstat functions conform to .St -p1003.1-90 . .Sh HISTORY A .Fn lstat function call appeared in x 4.2 .