STAT(2) SYSTEM CALLS STAT(2) NAME stat, lstat, fstat - get file status SYNOPSIS #include #include stat(path, buf) char *path; struct stat *buf; lstat(path, buf) char *path; struct stat *buf; fstat(fd, buf) int fd; struct stat *buf; DESCRIPTION _s_t_a_t obtains information about the file named by _p_a_t_h. Read, write or execute permission of the named file is not required, but all directories listed in the path name lead- ing to the file must be searchable. _l_s_t_a_t is like _s_t_a_t except in the case where the named file is a symbolic link, in which case _l_s_t_a_t returns information about the link, while _s_t_a_t returns information about the file the link references. _f_s_t_a_t obtains the same information about an open file refer- enced by the argument descriptor, such as would be obtained by an _o_p_e_n call. _b_u_f is a pointer to a _s_t_a_t structure into which information is placed concerning the file. The contents of the struc- ture pointed to by _b_u_f include the following members: dev_t st_dev; /* device inode resides on */ ino_t st_ino; /* this inode's number */ u_short st_mode;/* protection */ short st_nlink;/* number of hard links to the file */ short st_uid; /* user ID of owner */ short st_gid; /* group ID of owner */ dev_t st_rdev;/* the device type, for inode that is device */ off_t st_size;/* total size of file, in bytes */ time_t st_atime;/* file last access time */ time_t st_mtime;/* file last modify time */ time_t st_ctime;/* file last status change time */ long st_blksize;/* optimal blocksize for file system i/o ops */ long st_blocks;/* actual number of blocks allocated */ Sun Release 3.2 Last change: 16 July 1986 1 STAT(2) SYSTEM CALLS STAT(2) st_atime Time when file data was last read or modified. Changed by the following system calls: _m_k_n_o_d(2), _u_t_i_m_e_s(2), _r_e_a_d(2V), _w_r_i_t_e(2V), and _t_r_u_n_c_a_t_e(2). For reasons of efficiency, st_atime is not set when a directory is searched, although this would be more logical. st_mtime Time when data was last modified. It is not set by changes of owner, group, link count, or mode. Changed by the following system calls: _m_k_n_o_d(2), _u_t_i_m_e_s(2), _w_r_i_t_e(2V). st_ctime Time when file status was last changed. It is set both both by writing and changing the i- node. Changed by the following system calls: _c_h_m_o_d(2) _c_h_o_w_n(2), _l_i_n_k(2), _m_k_n_o_d(2), _r_e_n_a_m_e(2), _u_n_l_i_n_k(2), _u_t_i_m_e_s(2), _w_r_i_t_e(2V), _t_r_u_n_c_a_t_e(2). The status information word _s_t__m_o_d_e has bits: #define S_IFMT 0170000/* type of file */ #define S_IFIFO 0010000/* fifo special */ #define S_IFCHR 0020000/* character special */ #define S_IFDIR 0040000/* directory */ #define S_IFBLK 0060000/* block special */ #define S_IFREG 0100000/* regular file */ #define S_IFLNK 0120000/* symbolic link */ #define S_IFSOCK 0140000/* socket */ #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_IREAD 0000400/* read permission, owner */ #define S_IWRITE 0000200/* write permission, owner */ #define S_IEXEC 0000100/* execute/search permission, owner */ The mode bits 0000070 and 0000007 encode group and others permissions (see _c_h_m_o_d(2)). RETURN VALUE Upon successful completion a value of 0 is returned. Other- wise, a value of -1 is returned and _e_r_r_n_o is set to indicate the error. ERRORS _s_t_a_t and _l_s_t_a_t will fail if one or more of the following are true: ENOTDIR A component of the path prefix of _p_a_t_h is not a directory. EINVAL _p_a_t_h contains a character with the high-order bit set. Sun Release 3.2 Last change: 16 July 1986 2 STAT(2) SYSTEM CALLS STAT(2) ENAMETOOLONG The length of a component of _p_a_t_h exceeds 255 characters, or the length of _p_a_t_h exceeds 1023 characters. ENOENT The file referred to by _p_a_t_h does not exist. EACCES Search permission is denied for a component of the path prefix of _p_a_t_h. ELOOP Too many symbolic links were encountered in translating _p_a_t_h. EFAULT _b_u_f or _p_a_t_h points to an invalid address. EIO An I/O error occurred while reading from or writing to the file system. _f_s_t_a_t will fail if one or both of the following are true: EBADF _f_d is not a valid open file descriptor. EFAULT _b_u_f points to an invalid address. EIO An I/O error occurred while reading from or writing to the file system. CAVEAT The fields in the stat structure currently marked _s_t__s_p_a_r_e_1, _s_t__s_p_a_r_e_2, and _s_t__s_p_a_r_e_3 are present in preparation for inode time stamps expanding to 64 bits. This, however, can break certain programs which depend on the time stamps being contiguous (in calls to _u_t_i_m_e_s(2)). SEE ALSO chmod(2), chown(2), readlink(2), utimes(2) Sun Release 3.2 Last change: 16 July 1986 3