1.\" $NetBSD: stat.2,v 1.47 2010/11/25 20:53:23 dholland Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993, 1994 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)stat.2 8.4 (Berkeley) 5/1/95 31.\" 32.Dd November 25, 2010 33.Dt STAT 2 34.Os 35.Sh NAME 36.Nm stat , 37.Nm lstat , 38.Nm fstat 39.Nd get file status 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In sys/stat.h 44.Ft int 45.Fn stat "const char *path" "struct stat *sb" 46.Ft int 47.Fn lstat "const char *path" "struct stat *sb" 48.Ft int 49.Fn fstat "int fd" "struct stat *sb" 50.Sh DESCRIPTION 51The 52.Fn stat 53function obtains information about the file pointed to by 54.Fa path . 55Read, write or execute 56permission of the named file is not required, but all directories 57listed in the path name leading to the file must be searchable. 58.Pp 59The function 60.Fn lstat 61is like 62.Fn stat 63except in the case where the named file is a symbolic link, 64in which case 65.Fn lstat 66returns information about the link, 67while 68.Fn stat 69returns information about the file the link references. 70The 71.Fn fstat 72function obtains the same information about an open file 73known by the file descriptor 74.Fa fd . 75.Pp 76The 77.Fa sb 78argument is a pointer to a 79.Fa stat 80structure 81as defined by 82.In sys/stat.h 83and into which information is placed concerning the file. 84.Ss The Standard Structure 85The following standards-compliant fields are defined in the structure: 86.Bl -column -offset indent \ 87"nlink_t " "st_nlink " "Description" 88.It Sy Type Ta Sy Entry Ta Sy Description 89.It Vt dev_t Ta st_dev Ta device ID containing the file 90.It Vt ino_t Ta st_ino Ta serial number of the file 91.It Vt mode_t Ta st_mode Ta mode of the file 92.It Vt nlink_t Ta st_nlink Ta number of hard links to the file 93.It Vt uid_t Ta st_uid Ta user ID of the owner 94.It Vt gid_t Ta st_gid Ta group ID of the owner 95.It Vt dev_t Ta st_rdev Ta device type (character or block special) 96.It Vt off_t Ta st_size Ta size of the file in bytes 97.It Vt time_t Ta st_atime Ta time of last access 98.It Vt time_t Ta st_mtime Ta time of last data modification 99.It Vt time_t Ta st_ctime Ta time of last file status change 100.It Vt blksize_t Ta st_blksize Ta preferred I/O block size (fs-specific) 101.It Vt blkcnt_t Ta st_block Ta blocks allocated for the file 102.El 103.Pp 104These are specified in the 105.St -p1003.1-2004 106standard. 107The 108.Va st_ino 109and 110.Va st_dev 111fields taken together to uniquely identify the file within the system. 112Most of the types are defined in 113.Xr types 3 . 114.Pp 115The time-related fields are: 116.Bl -tag -width st_blksize -offset indent 117.It Va st_atime 118Time when file data was last accessed. 119Changed by the 120.Xr mknod 2 , 121.Xr utimes 2 , 122and 123.Xr read 2 124system calls. 125.It Va st_mtime 126Time when file data was last modified. 127Changed by the 128.Xr mknod 2 , 129.Xr utimes 2 , 130and 131.Xr write 2 132system calls. 133.It Va st_ctime 134Time when file status was last changed (file metadata modification). 135Changed by the 136.Xr chflags 2 , 137.Xr chmod 2 , 138.Xr chown 2 , 139.Xr link 2 , 140.Xr mknod 2 , 141.Xr rename 2 , 142.Xr unlink 2 , 143.Xr utimes 2 , 144and 145.Xr write 2 146system calls. 147.El 148.Pp 149The size-related fields of the 150.Fa struct stat 151are as follows: 152.Bl -tag -width st_blksize -offset indent 153.It Va st_size 154The size of the file in bytes. 155The meaning of the size reported for a directory is file system 156dependent. 157Some file systems (e.g. FFS) return the total size used for the 158directory metadata, possibly including free slots; others (notably 159ZFS) return the number of entries in the directory. 160Some may also return other things or always report zero. 161.It Va st_blksize 162The optimal I/O block size for the file. 163.It Va st_blocks 164The actual number of blocks allocated for the file in 512-byte units. 165As short symbolic links are stored in the inode, this number may 166be zero. 167.El 168.Pp 169The status information word 170.Fa st_mode 171contains bits that define the access mode (see 172.Xr chmod 2 ) 173and the type (see 174.Xr dirent 3 ) 175of the file. 176The following macros can be used to test 177whether a file is of the specified type. 178The value 179.Fa m 180supplied to the macros is the value of 181.Va st_mode . 182.Bl -tag -width "S_ISSOCK(m)" -offset indent 183.It Fn S_ISBLK "m" 184Test for a block special file. 185.It Fn S_ISCHR "m" 186Test for a character special file. 187.It Fn S_ISDIR "m" 188Test for a directory. 189.It Fn S_ISFIFO "m" 190Test for a pipe or FIFO special file. 191.It Fn S_ISREG "m" 192Test for a regular file. 193.It Fn S_ISLNK "m" 194Test for a symbolic link. 195.It Fn S_ISSOCK "m" 196Test for a socket. 197.El 198.Pp 199The macros evaluate to a non-zero value if the test 200is true or to the value 0 if the test is false. 201.Ss NetBSD Extensions 202The following additional 203.Nx 204specific fields are present: 205.Bl -column -offset indent \ 206"uint32_t" "st_birthtimensec" "Description" 207.It Sy Type Ta Sy Entry Ta Sy Description 208.It Vt long Ta st_atimensec Ta last access (nanoseconds) 209.It Vt long Ta st_mtimensec Ta last modification (nanoseconds) 210.It Vt long Ta st_ctimensec Ta last status change (nanoseconds) 211.It Vt time_t Ta st_birthtime Ta time of inode creation 212.It Vt long Ta st_birthtimensec Ta inode creation (nanoseconds) 213.It Vt uint32_t Ta st_flags Ta user defined flags for the file 214.It Vt uint32_t Ta st_gen Ta file generation number 215.\" 216.\" XXX: What is this? 217.\" 218.It Vt uint32_t Ta st_spare[2] Ta implementation detail 219.El 220.Pp 221However, if 222_NETBSD_SOURCE 223is furthermore defined, instead of the above, 224the following are present in the structure: 225.Bl -column -offset indent \ 226"struct timespec " "st_birthtimensec" "Description" 227.It Sy Type Ta Sy Entry Ta Sy Description 228.It Vt struct timespec Ta st_atimespec Ta time of last access 229.It Vt struct timespec Ta st_mtimespec Ta time of last modification 230.It Vt struct timespec Ta st_birthtimespec Ta time of creation 231.It Vt uint32_t Ta st_flags Ta user defined flags 232.It Vt uint32_t Ta st_gen Ta file generation number 233.\" 234.\" XXX: What is this? 235.\" 236.It Vt uint32_t Ta st_spare[2] Ta implementation detail 237.El 238.Pp 239In this case the following macros are provided for convenience: 240.Bd -literal -offset indent 241#if defined(_NETBSD_SOURCE) 242 #define st_atime st_atimespec.tv_sec 243 #define st_atimensec st_atimespec.tv_nsec 244 #define st_mtime st_mtimespec.tv_sec 245 #define st_mtimensec st_mtimespec.tv_nsec 246 #define st_ctime st_ctimespec.tv_sec 247 #define st_ctimensec st_ctimespec.tv_nsec 248 #define st_birthtime st_birthtimespec.tv_sec 249 #define st_birthtimensec st_birthtimespec.tv_nsec 250#endif 251.Ed 252.Pp 253The status information word 254.Fa st_flags 255has the following bits: 256.Bl -column -offset indent \ 257"struct timespec " "st_birthtimensec" 258.It Sy Constant Ta Sy Description 259.It Dv UF_NODUMP Ta do not dump a file 260.It Dv UF_IMMUTABLE Ta file may not be changed 261.It Dv UF_APPEND Ta writes to file may only append 262.It Dv UF_OPAQUE Ta directory is opaque wrt. union 263.It Dv SF_ARCHIVED Ta file is archived 264.It Dv SF_IMMUTABLE Ta file may not be changed 265.It Dv SF_APPEND Ta writes to file may only append 266.El 267.Pp 268For a description of the flags, see 269.Xr chflags 2 . 270.Sh RETURN VALUES 271Upon successful completion a value of 0 is returned. 272Otherwise, a value of \-1 is returned and 273.Va errno 274is set to indicate the error. 275.Sh COMPATIBILITY 276Previous versions of the system used different types for the 277.Li st_dev , 278.Li st_uid , 279.Li st_gid , 280.Li st_rdev , 281.Li st_size , 282.Li st_blksize 283and 284.Li st_blocks 285fields. 286.Sh ERRORS 287.Fn stat 288and 289.Fn lstat 290will fail if: 291.Bl -tag -width Er 292.It Bq Er EACCES 293Search permission is denied for a component of the path prefix. 294.It Bq Er EBADF 295A badly formed v-node was encountered. 296This can happen if a file system information node is incorrect. 297.It Bq Er EFAULT 298.Fa sb 299or 300.Em name 301points to an invalid address. 302.It Bq Er EIO 303An I/O error occurred while reading from or writing to the file system. 304.It Bq Er ELOOP 305Too many symbolic links were encountered in translating the pathname. 306.It Bq Er ENAMETOOLONG 307A component of a pathname exceeded 308.Brq Dv NAME_MAX 309characters, or an entire path name exceeded 310.Brq Dv PATH_MAX 311characters. 312.It Bq Er ENOENT 313The named file does not exist. 314.It Bq Er ENOTDIR 315A component of the path prefix is not a directory. 316.It Bq Er ENXIO 317The named file is a character special or block 318special file, and the device associated with this special file 319does not exist. 320.El 321.Pp 322.Fn fstat 323will fail if: 324.Bl -tag -width Er 325.It Bq Er EBADF 326.Fa fd 327is not a valid open file descriptor. 328.It Bq Er EFAULT 329.Fa sb 330points to an invalid address. 331.It Bq Er EIO 332An I/O error occurred while reading from or writing to the file system. 333.El 334.Sh SEE ALSO 335.Xr chflags 2 , 336.Xr chmod 2 , 337.Xr chown 2 , 338.Xr utimes 2 , 339.Xr dirent 3 , 340.Xr types 3 , 341.Xr symlink 7 342.Sh STANDARDS 343The described functions conform to 344.St -p1003.1-2004 . 345.Sh HISTORY 346A 347.Fn stat 348function call appeared in 349.At v2 . 350A 351.Fn lstat 352function call appeared in 353.Bx 4.2 . 354.Sh BUGS 355Applying 356.Fn fstat 357to a socket (and thus to a pipe) 358returns a zero'd buffer, 359except for the blocksize field, 360and a unique device and file serial number. 361