1.\" Copyright (c) 1980, 1991, 1993, 1994 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)stat.2 8.4 (Berkeley) 05/01/95 7.\" 8.Dd 9.Dt STAT 2 10.Os BSD 4 11.Sh NAME 12.Nm stat , 13.Nm lstat , 14.Nm fstat 15.Nd get file status 16.Sh SYNOPSIS 17.Fd #include <sys/types.h> 18.Fd #include <sys/stat.h> 19.Ft int 20.Fn stat "const char *path" "struct stat *sb" 21.Ft int 22.Fn lstat "const char *path" "struct stat *sb" 23.Ft int 24.Fn fstat "int fd" "struct stat *sb" 25.Sh DESCRIPTION 26The 27.Fn stat 28function obtains information about the file pointed to by 29.Fa path . 30Read, write or execute 31permission of the named file is not required, but all directories 32listed in the path name leading to the file must be searchable. 33.Pp 34.Fn Lstat 35is like 36.Fn stat 37except in the case where the named file is a symbolic link, 38in which case 39.Fn lstat 40returns information about the link, 41while 42.Fn stat 43returns information about the file the link references. 44Unlike other filesystem objects, 45symbolic links do not have an owner, group, access mode, times, etc. 46Instead, these attributes are taken from the directory that 47contains the link. 48The only attributes returned from an 49.Fn lstat 50that refer to the symbolic link itself are the file type (S_IFLNK), 51size, blocks, and link count (always 1). 52.Pp 53The 54.Fn fstat 55obtains the same information about an open file 56known by the file descriptor 57.Fa fd . 58.Pp 59The 60.Fa sb 61argument is a pointer to a 62.Fn stat 63structure 64as defined by 65.Aq Pa sys/stat.h 66(shown below) 67and into which information is placed concerning the file. 68.Bd -literal 69struct stat { 70 dev_t st_dev; /* device inode resides on */ 71 ino_t st_ino; /* inode's number */ 72 mode_t st_mode; /* inode protection mode */ 73 nlink_t st_nlink; /* number or hard links to the file */ 74 uid_t st_uid; /* user-id of owner */ 75 gid_t st_gid; /* group-id of owner */ 76 dev_t st_rdev; /* device type, for special file inode */ 77 struct timespec st_atimespec; /* time of last access */ 78 struct timespec st_mtimespec; /* time of last data modification */ 79 struct timespec st_ctimespec; /* time of last file status change */ 80 off_t st_size; /* file size, in bytes */ 81 quad_t st_blocks; /* blocks allocated for file */ 82 u_long st_blksize;/* optimal file sys I/O ops blocksize */ 83 u_long st_flags; /* user defined flags for file */ 84 u_long st_gen; /* file generation number */ 85}; 86.Ed 87.Pp 88The time-related fields of 89.Fa struct stat 90are as follows: 91.Bl -tag -width XXXst_mtime 92.It st_atime 93Time when file data last accessed. 94Changed by the 95.Xr mknod 2 , 96.Xr utimes 2 97and 98.Xr read 2 99system calls. 100.It st_mtime 101Time when file data last modified. 102Changed by the 103.Xr mknod 2 , 104.Xr utimes 2 105and 106.Xr write 2 107system calls. 108.It st_ctime 109Time when file status was last changed (inode data modification). 110Changed by the 111.Xr chmod 2 , 112.Xr chown 2 , 113.Xr link 2 , 114.Xr mknod 2 , 115.Xr rename 2 , 116.Xr unlink 2 , 117.Xr utimes 2 118and 119.Xr write 2 120system calls. 121.El 122.Pp 123The size-related fields of the 124.Fa struct stat 125are as follows: 126.Bl -tag -width XXXst_blksize 127.It st_blksize 128The optimal I/O block size for the file. 129.It st_blocks 130The actual number of blocks allocated for the file in 512-byte units. 131As short symbolic links are stored in the inode, this number may 132be zero. 133.El 134.Pp 135The status information word 136.Fa st_mode 137has the following bits: 138.Bd -literal 139#define S_IFMT 0170000 /* type of file */ 140#define S_IFIFO 0010000 /* named pipe (fifo) */ 141#define S_IFCHR 0020000 /* character special */ 142#define S_IFDIR 0040000 /* directory */ 143#define S_IFBLK 0060000 /* block special */ 144#define S_IFREG 0100000 /* regular */ 145#define S_IFLNK 0120000 /* symbolic link */ 146#define S_IFSOCK 0140000 /* socket */ 147#define S_ISUID 0004000 /* set user id on execution */ 148#define S_ISGID 0002000 /* set group id on execution */ 149#define S_ISVTX 0001000 /* save swapped text even after use */ 150#define S_IRUSR 0000400 /* read permission, owner */ 151#define S_IWUSR 0000200 /* write permission, owner */ 152#define S_IXUSR 0000100 /* execute/search permission, owner */ 153.Ed 154.Pp 155For a list of access modes, see 156.Aq Pa sys/stat.h , 157.Xr access 2 158and 159.Xr chmod 2 . 160.Sh RETURN VALUES 161Upon successful completion a value of 0 is returned. 162Otherwise, a value of -1 is returned and 163.Va errno 164is set to indicate the error. 165.Sh COMPATIBILITY 166Previous versions of the system used different types for the 167.Li st_dev , 168.Li st_uid , 169.Li st_gid , 170.Li st_rdev , 171.Li st_size , 172.Li st_blksize 173and 174.Li st_blocks 175fields. 176.Sh ERRORS 177.Fn Stat 178and 179.Fn lstat 180will fail if: 181.Bl -tag -width ENAMETOOLONGAA 182.It Bq Er ENOTDIR 183A component of the path prefix is not a directory. 184.It Bq Er EINVAL 185The pathname contains a character with the high-order bit set. 186.It Bq Er ENAMETOOLONG 187A component of a pathname exceeded 255 characters, 188or an entire path name exceeded 1023 characters. 189.It Bq Er ENOENT 190The named file does not exist. 191.It Bq Er EACCES 192Search permission is denied for a component of the path prefix. 193.It Bq Er ELOOP 194Too many symbolic links were encountered in translating the pathname. 195.It Bq Er EFAULT 196.Fa Sb 197or 198.Em name 199points to an invalid address. 200.It Bq Er EIO 201An I/O error occurred while reading from or writing to the file system. 202.El 203.Pp 204.Bl -tag -width [EFAULT] 205.Fn Fstat 206will fail if: 207.It Bq Er EBADF 208.Fa fd 209is not a valid open file descriptor. 210.It Bq Er EFAULT 211.Fa Sb 212points to an invalid address. 213.It Bq Er EIO 214An I/O error occurred while reading from or writing to the file system. 215.El 216.Sh SEE ALSO 217.Xr chmod 2 , 218.Xr chown 2 , 219.Xr utimes 2 220.Xr symlink 7 221.Sh BUGS 222Applying 223.Xr fstat 224to a socket (and thus to a pipe) 225returns a zero'd buffer, 226except for the blocksize field, 227and a unique device and inode number. 228.Sh STANDARDS 229The 230.Fn stat 231and 232.Fn fstat 233function calls are expected to 234conform to IEEE Std 1003.1-1988 235.Pq Dq Tn POSIX . 236.Sh HISTORY 237A 238.Nm lstat 239function call appeared in 240.Bx 4.2 . 241