4.3BSD-Reno/share/man/cat2/stat.0
STAT(2) 1989 STAT(2)
NNAAMMEE
stat, lstat, fstat - get file status
SSYYNNOOPPSSIISS
##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
##iinncclluuddee <<ssyyss//ssttaatt..hh>>
ssttaatt((ppaatthh,, bbuuff))
cchhaarr **ppaatthh;;
ssttrruucctt ssttaatt **bbuuff;;
llssttaatt((ppaatthh,, bbuuff))
cchhaarr **ppaatthh;;
ssttrruucctt ssttaatt **bbuuff;;
ffssttaatt((ffdd,, bbuuff))
iinntt ffdd;;
ssttrruucctt ssttaatt **bbuuff;;
DDEESSCCRRIIPPTTIIOONN
_S_t_a_t obtains information about the file _p_a_t_h. Read, write
or execute permission of the named file is not required, but
all directories listed in the path name leading to the file
must be reachable.
_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:
struct stat {
dev_t st_dev; /* device inode resides on */
ino_t st_ino; /* inode's number */
u_short st_mode; /* inode protection mode */
short 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 */
off_t st_size; /* file size, in bytes */
time_t st_atime; /* time of last access */
int st_spare1;
time_t st_mtime; /* time of last data modification */
int st_spare2;
time_t st_ctime; /* time of last file status change */
Printed 7/27/90 August 1
STAT(2) 1989 STAT(2)
int st_spare3;
long st_blksize; /* optimal file system I/O ops blocksize */
long st_blocks; /* blocks allocated for file */
u_long st_flags; /* user defined flags for file */
u_long st_gen; /* file generation number */
};
st_atime
Time when file data was last accessed. Changed by the
following system calls: _m_k_n_o_d(2), _u_t_i_m_e_s(2), and
_r_e_a_d(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(2).
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(2).
st_blocks
The actual number of blocks allocated for the file in
512-byte units.
The status information word _s_t__m_o_d_e has bits:
#define S_IFMT 0170000 /* type of file */
#define S_IFDIR 0040000/* directory */
#define S_IFCHR 0020000/* character special */
#define S_IFBLK 0060000/* block special */
#define S_IFREG 0100000/* regular */
#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)).
RREETTUURRNN VVAALLUUEE
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.
Printed 7/27/90 August 2
STAT(2) 1989 STAT(2)
EERRRROORRSS
_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 is not a
directory.
[EINVAL] The pathname contains a character with the
high-order bit set.
[ENAMETOOLONG] A component of a pathname exceeded 255 char-
acters, or an entire path name exceeded 1023
characters.
[ENOENT] The named file does not exist.
[EACCES] Search permission is denied for a component
of the path prefix.
[ELOOP] Too many symbolic links were encountered in
translating the pathname.
[EFAULT] _B_u_f or _n_a_m_e 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_i_l_d_e_s 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.
CCAAVVEEAATT
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 that depend on the time stamps being
contiguous (in calls to _u_t_i_m_e_s(2)).
SSEEEE AALLSSOO
chmod(2), chown(2), utimes(2)
BBUUGGSS
Applying _f_s_t_a_t 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.
Printed 7/27/90 August 3