1.\" $NetBSD: stat.2,v 1.55 2013/07/28 15:46:34 njoly 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 July 28, 2013 33.Dt STAT 2 34.Os 35.Sh NAME 36.Nm stat , 37.Nm lstat , 38.Nm fstat , 39.Nm fstatat , 40.Nd get file status 41.Sh LIBRARY 42.Lb libc 43.Sh SYNOPSIS 44.In sys/stat.h 45.Ft int 46.Fn stat "const char *path" "struct stat *sb" 47.Ft int 48.Fn lstat "const char *path" "struct stat *sb" 49.Ft int 50.Fn fstat "int fd" "struct stat *sb" 51.Ft int 52.Fn fstatat "int fd" "const char *path" "struct stat *sb" "int flag" 53.Sh DESCRIPTION 54The 55.Fn stat 56function obtains information about the file pointed to by 57.Fa path . 58Read, write or execute 59permission of the named file is not required, but all directories 60listed in the path name leading to the file must be searchable. 61.Pp 62The function 63.Fn lstat 64is like 65.Fn stat 66except in the case where the named file is a symbolic link, 67in which case 68.Fn lstat 69returns information about the link, 70while 71.Fn stat 72returns information about the file the link references. 73The 74.Fn fstat 75function obtains the same information about an open file 76known by the file descriptor 77.Fa fd . 78.Pp 79.Fn fstatat 80works the same way as 81.Fn stat 82(or 83.Fn lstat 84if 85.Dv AT_SYMLINK_NOFOLLOW 86is set in 87.Fa flag ) 88except if 89.Fa path 90is relative. 91In that case, it is looked up from a directory whose file 92descriptor was passed as 93.Fa fd . 94Search permission is required on this directory. 95.\" (These alternatives await a decision about the semantics of O_SEARCH) 96.\" Search permission is required on this directory 97.\" except if 98.\" .Fa fd 99.\" was opened with the 100.\" .Dv O_SEARCH 101.\" flag. 102.\" - or - 103.\" This file descriptor must have been opened with the 104.\" .Dv O_SEARCH 105.\" flag. 106.Fa fd 107can be set to 108.Dv AT_FDCWD 109in order to specify the current directory. 110.Pp 111The 112.Fa sb 113argument is a pointer to a 114.Fa stat 115structure 116as defined by 117.In sys/stat.h 118and into which information is placed concerning the file. 119.Ss The Standard Structure 120The following standards-compliant fields are defined in the structure: 121.Bl -column -offset indent \ 122"nlink_t " "st_nlink " "Description" 123.It Sy Type Ta Sy Entry Ta Sy Description 124.It Vt dev_t Ta st_dev Ta device ID containing the file 125.It Vt ino_t Ta st_ino Ta serial number of the file 126.It Vt mode_t Ta st_mode Ta mode of the file 127.It Vt nlink_t Ta st_nlink Ta number of hard links to the file 128.It Vt uid_t Ta st_uid Ta user ID of the owner 129.It Vt gid_t Ta st_gid Ta group ID of the owner 130.It Vt dev_t Ta st_rdev Ta device type (character or block special) 131.It Vt off_t Ta st_size Ta size of the file in bytes 132.It Vt time_t Ta st_atime Ta time of last access 133.It Vt time_t Ta st_mtime Ta time of last data modification 134.It Vt time_t Ta st_ctime Ta time of last file status change 135.It Vt blksize_t Ta st_blksize Ta preferred I/O block size (fs-specific) 136.It Vt blkcnt_t Ta st_blocks Ta blocks allocated for the file 137.El 138.Pp 139These are specified in the 140.St -p1003.1-2004 141standard. 142The 143.Va st_ino 144and 145.Va st_dev 146fields taken together uniquely identify the file within the system. 147Most of the types are defined in 148.Xr types 3 . 149.Pp 150The time-related fields are: 151.Bl -tag -width st_blksize -offset indent 152.It Va st_atime 153Time when file data was last accessed. 154Changed by the 155.Xr mknod 2 , 156.Xr utimes 2 , 157and 158.Xr read 2 159system calls. 160.It Va st_mtime 161Time when file data was last modified. 162Changed by the 163.Xr mknod 2 , 164.Xr utimes 2 , 165and 166.Xr write 2 167system calls. 168.It Va st_ctime 169Time when file status was last changed (file metadata modification). 170Changed by the 171.Xr chflags 2 , 172.Xr chmod 2 , 173.Xr chown 2 , 174.Xr link 2 , 175.Xr mknod 2 , 176.Xr rename 2 , 177.Xr unlink 2 , 178.Xr utimes 2 , 179and 180.Xr write 2 181system calls. 182.El 183.Pp 184The size-related fields of the 185.Fa struct stat 186are as follows: 187.Bl -tag -width st_blksize -offset indent 188.It Va st_size 189The size of the file in bytes. 190The meaning of the size reported for a directory is file system 191dependent. 192Some file systems (e.g. FFS) return the total size used for the 193directory metadata, possibly including free slots; others (notably 194ZFS) return the number of entries in the directory. 195Some may also return other things or always report zero. 196.It Va st_blksize 197The optimal I/O block size for the file. 198.It Va st_blocks 199The actual number of blocks allocated for the file in 512-byte units. 200As short symbolic links are stored in the inode, this number may 201be zero. 202.El 203.Pp 204The status information word 205.Fa st_mode 206contains bits that define the access mode (see 207.Xr chmod 2 ) 208and the type (see 209.Xr dirent 3 ) 210of the file. 211The following macros can be used to test 212whether a file is of the specified type. 213The value 214.Fa m 215supplied to the macros is the value of 216.Va st_mode . 217.Bl -tag -width "S_ISSOCK(m)" -offset indent 218.It Fn S_ISBLK "m" 219Test for a block special file. 220.It Fn S_ISCHR "m" 221Test for a character special file. 222.It Fn S_ISDIR "m" 223Test for a directory. 224.It Fn S_ISFIFO "m" 225Test for a pipe or FIFO special file. 226.It Fn S_ISREG "m" 227Test for a regular file. 228.It Fn S_ISLNK "m" 229Test for a symbolic link. 230.It Fn S_ISSOCK "m" 231Test for a socket. 232.El 233.Pp 234The macros evaluate to a non-zero value if the test 235is true or to the value 0 if the test is false. 236.Ss NetBSD Extensions 237The following additional 238.Nx 239specific fields are present: 240.Bl -column -offset indent \ 241"uint32_t" "st_birthtimensec" "Description" 242.It Sy Type Ta Sy Entry Ta Sy Description 243.It Vt long Ta st_atimensec Ta last access (nanoseconds) 244.It Vt long Ta st_mtimensec Ta last modification (nanoseconds) 245.It Vt long Ta st_ctimensec Ta last status change (nanoseconds) 246.It Vt time_t Ta st_birthtime Ta time of inode creation 247.It Vt long Ta st_birthtimensec Ta inode creation (nanoseconds) 248.It Vt uint32_t Ta st_flags Ta user defined flags for the file 249.It Vt uint32_t Ta st_gen Ta file generation number 250.\" 251.\" XXX: What is this? 252.\" 253.It Vt uint32_t Ta st_spare[2] Ta implementation detail 254.El 255.Pp 256However, if 257_NETBSD_SOURCE 258is furthermore defined, instead of the above, 259the following are present in the structure: 260.Bl -column -offset indent \ 261"struct timespec " "st_birthtimensec" "Description" 262.It Sy Type Ta Sy Entry Ta Sy Description 263.It Vt struct timespec Ta st_atimespec Ta time of last access 264.It Vt struct timespec Ta st_mtimespec Ta time of last modification 265.It Vt struct timespec Ta st_birthtimespec Ta time of creation 266.It Vt uint32_t Ta st_flags Ta user defined flags 267.It Vt uint32_t Ta st_gen Ta file generation number 268.\" 269.\" XXX: What is this? 270.\" 271.It Vt uint32_t Ta st_spare[2] Ta implementation detail 272.El 273.Pp 274In this case the following macros are provided for convenience: 275.Bd -literal -offset indent 276#if defined(_NETBSD_SOURCE) 277 #define st_atime st_atimespec.tv_sec 278 #define st_atimensec st_atimespec.tv_nsec 279 #define st_mtime st_mtimespec.tv_sec 280 #define st_mtimensec st_mtimespec.tv_nsec 281 #define st_ctime st_ctimespec.tv_sec 282 #define st_ctimensec st_ctimespec.tv_nsec 283 #define st_birthtime st_birthtimespec.tv_sec 284 #define st_birthtimensec st_birthtimespec.tv_nsec 285#endif 286.Ed 287.Pp 288The status information word 289.Fa st_flags 290has the following bits: 291.Bl -column -offset indent \ 292"struct timespec " "st_birthtimensec" 293.It Sy Constant Ta Sy Description 294.It Dv UF_NODUMP Ta do not dump a file 295.It Dv UF_IMMUTABLE Ta file may not be changed 296.It Dv UF_APPEND Ta writes to file may only append 297.It Dv UF_OPAQUE Ta directory is opaque wrt. union 298.It Dv SF_ARCHIVED Ta file is archived 299.It Dv SF_IMMUTABLE Ta file may not be changed 300.It Dv SF_APPEND Ta writes to file may only append 301.El 302.Pp 303For a description of the flags, see 304.Xr chflags 2 . 305.Sh RETURN VALUES 306.Rv -std stat lstat fstat fstatat 307.Sh COMPATIBILITY 308Previous versions of the system used different types for the 309.Li st_dev , 310.Li st_uid , 311.Li st_gid , 312.Li st_rdev , 313.Li st_size , 314.Li st_blksize 315and 316.Li st_blocks 317fields. 318.Sh ERRORS 319.Fn stat , 320.Fn lstat 321and 322.Fn fstatat 323will fail if: 324.Bl -tag -width Er 325.It Bq Er EACCES 326Search permission is denied for a component of the path prefix. 327.It Bq Er EBADF 328A badly formed vnode was encountered. 329This can happen if a file system information node is incorrect. 330.It Bq Er EFAULT 331.Fa sb 332or 333.Fa path 334points to an invalid address. 335.It Bq Er EIO 336An I/O error occurred while reading from or writing to the file system. 337.It Bq Er ELOOP 338Too many symbolic links were encountered in translating the pathname. 339.It Bq Er ENAMETOOLONG 340A component of a pathname exceeded 341.Brq Dv NAME_MAX 342characters, or an entire path name exceeded 343.Brq Dv PATH_MAX 344characters. 345.It Bq Er ENOENT 346The named file does not exist. 347.It Bq Er ENOTDIR 348A component of the path prefix is not a directory. 349.It Bq Er ENXIO 350The named file is a character special or block 351special file, and the device associated with this special file 352does not exist. 353.El 354.Pp 355In addition, 356.Fn fstatat 357will fail if: 358.Bl -tag -width Er 359.It Bq Er EBADF 360.Fa path 361does not specify an absolute path and 362.Fa fd 363is neither 364.Dv AT_FDCWD 365nor a valid file descriptor open for reading or searching. 366.It Bq Er ENOTDIR 367.Fa path 368is not an absolute path and 369.Fa fd 370is a file descriptor associated with a non-directory file. 371.El 372.Pp 373.Fn fstat 374will fail if: 375.Bl -tag -width Er 376.It Bq Er EBADF 377.Fa fd 378is not a valid open file descriptor. 379.It Bq Er EFAULT 380.Fa sb 381points to an invalid address. 382.It Bq Er EIO 383An I/O error occurred while reading from or writing to the file system. 384.El 385.Sh SEE ALSO 386.Xr chflags 2 , 387.Xr chmod 2 , 388.Xr chown 2 , 389.Xr utimes 2 , 390.Xr dirent 3 , 391.Xr types 3 , 392.Xr symlink 7 393.Sh STANDARDS 394.Fn stat , 395.Fn lstat , 396and 397.Fn fstat 398conform to 399.St -p1003.1-2004 . 400.Fn fstatat 401conforms to 402.St -p1003.1-2008 . 403.Sh HISTORY 404A 405.Fn stat 406function call appeared in 407.At v2 . 408A 409.Fn lstat 410function call appeared in 411.Bx 4.2 . 412.Sh BUGS 413Applying 414.Fn fstat 415to a socket (and thus to a pipe) 416returns a zero'd buffer, 417except for the blocksize field, 418and a unique device and file serial number. 419