1.\" $NetBSD: stat.2,v 1.46 2010/06/04 05:42:24 jruoho 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 June 4, 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. 155A directory will be a multiple of the size of the 156.Xr dirent 3 157structure. 158Some file systems (notably ZFS) return the number of entries in the directory 159instead of the size in bytes. 160.It Va st_blksize 161The optimal I/O block size for the file. 162.It Va st_blocks 163The actual number of blocks allocated for the file in 512-byte units. 164As short symbolic links are stored in the inode, this number may 165be zero. 166.El 167.Pp 168The status information word 169.Fa st_mode 170contains bits that define the access mode (see 171.Xr chmod 2 ) 172and the type (see 173.Xr dirent 3 ) 174of the file. 175The following macros can be used to test 176whether a file is of the specified type. 177The value 178.Fa m 179supplied to the macros is the value of 180.Va st_mode . 181.Bl -tag -width "S_ISSOCK(m)" -offset indent 182.It Fn S_ISBLK "m" 183Test for a block special file. 184.It Fn S_ISCHR "m" 185Test for a character special file. 186.It Fn S_ISDIR "m" 187Test for a directory. 188.It Fn S_ISFIFO "m" 189Test for a pipe or FIFO special file. 190.It Fn S_ISREG "m" 191Test for a regular file. 192.It Fn S_ISLNK "m" 193Test for a symbolic link. 194.It Fn S_ISSOCK "m" 195Test for a socket. 196.El 197.Pp 198The macros evaluate to a non-zero value if the test 199is true or to the value 0 if the test is false. 200.Ss NetBSD Extensions 201The following additional 202.Nx 203specific fields are present: 204.Bl -column -offset indent \ 205"uint32_t" "st_birthtimensec" "Description" 206.It Sy Type Ta Sy Entry Ta Sy Description 207.It Vt long Ta st_atimensec Ta last access (nanoseconds) 208.It Vt long Ta st_mtimensec Ta last modification (nanoseconds) 209.It Vt long Ta st_ctimensec Ta last status change (nanoseconds) 210.It Vt time_t Ta st_birthtime Ta time of inode creation 211.It Vt long Ta st_birthtimensec Ta inode creation (nanoseconds) 212.It Vt uint32_t Ta st_flags Ta user defined flags for the file 213.It Vt uint32_t Ta st_gen Ta file generation number 214.\" 215.\" XXX: What is this? 216.\" 217.It Vt uint32_t Ta st_spare[2] Ta implementation detail 218.El 219.Pp 220However, if 221_NETBSD_SOURCE 222is furthermore defined, instead of the above, 223the following are present in the structure: 224.Bl -column -offset indent \ 225"struct timespec " "st_birthtimensec" "Description" 226.It Sy Type Ta Sy Entry Ta Sy Description 227.It Vt struct timespec Ta st_atimespec Ta time of last access 228.It Vt struct timespec Ta st_mtimespec Ta time of last modification 229.It Vt struct timespec Ta st_birthtimespec Ta time of creation 230.It Vt uint32_t Ta st_flags Ta user defined flags 231.It Vt uint32_t Ta st_gen Ta file generation number 232.\" 233.\" XXX: What is this? 234.\" 235.It Vt uint32_t Ta st_spare[2] Ta implementation detail 236.El 237.Pp 238In this case the following macros are provided for convenience: 239.Bd -literal -offset indent 240#if defined(_NETBSD_SOURCE) 241 #define st_atime st_atimespec.tv_sec 242 #define st_atimensec st_atimespec.tv_nsec 243 #define st_mtime st_mtimespec.tv_sec 244 #define st_mtimensec st_mtimespec.tv_nsec 245 #define st_ctime st_ctimespec.tv_sec 246 #define st_ctimensec st_ctimespec.tv_nsec 247 #define st_birthtime st_birthtimespec.tv_sec 248 #define st_birthtimensec st_birthtimespec.tv_nsec 249#endif 250.Ed 251.Pp 252The status information word 253.Fa st_flags 254has the following bits: 255.Bl -column -offset indent \ 256"struct timespec " "st_birthtimensec" 257.It Sy Constant Ta Sy Description 258.It Dv UF_NODUMP Ta do not dump a file 259.It Dv UF_IMMUTABLE Ta file may not be changed 260.It Dv UF_APPEND Ta writes to file may only append 261.It Dv UF_OPAQUE Ta directory is opaque wrt. union 262.It Dv SF_ARCHIVED Ta file is archived 263.It Dv SF_IMMUTABLE Ta file may not be changed 264.It Dv SF_APPEND Ta writes to file may only append 265.El 266.Pp 267For a description of the flags, see 268.Xr chflags 2 . 269.Sh RETURN VALUES 270Upon successful completion a value of 0 is returned. 271Otherwise, a value of \-1 is returned and 272.Va errno 273is set to indicate the error. 274.Sh COMPATIBILITY 275Previous versions of the system used different types for the 276.Li st_dev , 277.Li st_uid , 278.Li st_gid , 279.Li st_rdev , 280.Li st_size , 281.Li st_blksize 282and 283.Li st_blocks 284fields. 285.Sh ERRORS 286.Fn stat 287and 288.Fn lstat 289will fail if: 290.Bl -tag -width Er 291.It Bq Er EACCES 292Search permission is denied for a component of the path prefix. 293.It Bq Er EBADF 294A badly formed v-node was encountered. 295This can happen if a file system information node is incorrect. 296.It Bq Er EFAULT 297.Fa sb 298or 299.Em name 300points to an invalid address. 301.It Bq Er EIO 302An I/O error occurred while reading from or writing to the file system. 303.It Bq Er ELOOP 304Too many symbolic links were encountered in translating the pathname. 305.It Bq Er ENAMETOOLONG 306A component of a pathname exceeded 307.Brq Dv NAME_MAX 308characters, or an entire path name exceeded 309.Brq Dv PATH_MAX 310characters. 311.It Bq Er ENOENT 312The named file does not exist. 313.It Bq Er ENOTDIR 314A component of the path prefix is not a directory. 315.It Bq Er ENXIO 316The named file is a character special or block 317special file, and the device associated with this special file 318does not exist. 319.El 320.Pp 321.Fn fstat 322will fail if: 323.Bl -tag -width Er 324.It Bq Er EBADF 325.Fa fd 326is not a valid open file descriptor. 327.It Bq Er EFAULT 328.Fa sb 329points to an invalid address. 330.It Bq Er EIO 331An I/O error occurred while reading from or writing to the file system. 332.El 333.Sh SEE ALSO 334.Xr chflags 2 , 335.Xr chmod 2 , 336.Xr chown 2 , 337.Xr utimes 2 , 338.Xr dirent 3 , 339.Xr types 3 , 340.Xr symlink 7 341.Sh STANDARDS 342The described functions conform to 343.St -p1003.1-2004 . 344.Sh HISTORY 345A 346.Fn stat 347function call appeared in 348.At v2 . 349A 350.Fn lstat 351function call appeared in 352.Bx 4.2 . 353.Sh BUGS 354Applying 355.Fn fstat 356to a socket (and thus to a pipe) 357returns a zero'd buffer, 358except for the blocksize field, 359and a unique device and file serial number. 360