1.\" $OpenBSD: stat.2,v 1.3 1997/02/13 05:20:55 millert 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)stat.2 8.3 (Berkeley) 4/19/94 35.\" 36.Dd May 15, 2008 37.Dt STAT 2 38.Os 39.Sh NAME 40.Nm fstat , 41.Nm fstat64 , 42.Nm lstat , 43.Nm lstat64 , 44.Nm stat , 45.Nm stat64 , 46.Nm fstatat 47.Nd get file status 48.Sh SYNOPSIS 49.Fd #include <sys/stat.h> 50.Ft int 51.Fo fstat 52.Fa "int fildes" 53.Fa "struct stat *buf" 54.Fc 55.Ft int 56.Fo lstat 57.Fa "const char *restrict path" 58.Fa "struct stat *restrict buf" 59.Fc 60.Ft int 61.Fo stat 62.Fa "const char *restrict path" 63.Fa "struct stat *restrict buf" 64.Fc 65.Ft int 66.Fn fstatat "int fd" "const char *path" "struct stat *buf" "int flag" 67.Sh TRANSITIIONAL SYNOPSIS (NOW DEPRECATED) 68.Ft int 69.br 70.Fo fstat64 71.Fa "int fildes" 72.Fa "struct stat64 *buf" 73.Fc ; 74.sp 75.Ft int 76.br 77.Fo lstat64 78.Fa "const char *restrict path" 79.Fa "struct stat64 *restrict buf" 80.Fc ; 81.sp 82.Ft int 83.br 84.Fo stat64 85.Fa "const char *restrict path" 86.Fa "struct stat64 *restrict buf" 87.Fc ; 88.Sh DESCRIPTION 89The 90.Fn stat 91function obtains information about the file pointed to by 92.Fa path . 93Read, write or execute 94permission of the named file is not required, but all directories 95listed in the path name leading to the file must be searchable. 96.Pp 97The 98.Fn lstat 99function 100is like 101.Fn stat 102except in the case where the named file is a symbolic link; 103.Fn lstat 104returns information about the link, 105while 106.Fn stat 107returns information about the file the link references. 108For symbolic links, the st_mode member contains meaningful information 109when used with the file type macros, and the st_size member contains 110the length of the pathname contained in the symbolic link. 111File mode bits and the contents of the remaining members of the stat 112structure are unspecified. 113The value returned in the st_size member is the length of the contents of 114the symbolic link, and does not count any trailing null. 115.Pp 116The 117.Fn fstat 118obtains the same information about an open file 119known by the file descriptor 120.Fa fildes . 121.Pp 122The 123.Fn fstatat 124system call is equivalent to 125.Fn stat 126and 127.Fn lstat 128except in the case where the 129.Fa path 130specifies a relative path. 131In this case the status is retrieved from a file relative to 132the directory associated with the file descriptor 133.Fa fd 134instead of the current working directory. 135.Pp 136The values for the 137.Fa flag 138are constructed by a bitwise-inclusive OR of flags from the following list, 139defined in 140.In fcntl.h : 141.Bl -tag -width AT_SYMLINK_NOFOLLOW_ANY 142.It Dv AT_SYMLINK_NOFOLLOW 143If 144.Fa path 145names a symbolic link, the status of the symbolic link is returned. 146.El 147.Bl -tag -width AT_SYMLINK_NOFOLLOW_ANY 148.It Dv AT_SYMLINK_NOFOLLOW_ANY 149If 150.Fa path 151names a symbolic link, the status of the symbolic link is returned. 152If a symbolic link is encountered during pathname resolution, an error 153is returned. 154.El 155.Bl -tag -width AT_SYMLINK_NOFOLLOW_ANY 156.It Dv AT_RESOLVE_BENEATH 157If 158.Fa path 159does not reside in the hierarchy beneath the starting directory, 160an error is returned. 161.El 162.Bl -tag -width AT_SYMLINK_NOFOLLOW_ANY 163.It Dv AT_UNIQUE 164If 165.Fa path 166resolves to a vnode with multiple hard links, 167an error is returned. 168.El 169.Pp 170If 171.Fn fstatat 172is passed the special value 173.Dv AT_FDCWD 174in the 175.Fa fd 176parameter, the current working directory is used and the behavior is 177identical to a call to 178.Fn stat 179or 180.Fn lstat 181respectively, depending on whether or not the 182.Dv AT_SYMLINK_NOFOLLOW 183bit is set in 184.Fa flag . 185.Pp 186The 187.Fa buf 188argument is a pointer to a 189.Fa stat 190structure 191as defined by 192.Aq Pa sys/stat.h 193and into which information is placed concerning the file. 194When the macro 195.Dv _DARWIN_FEATURE_64_BIT_INODE 196is not defined (see below for more information about this macro), the 197.Fa stat 198structure is defined as: 199.Bd -literal 200struct stat { /* when _DARWIN_FEATURE_64_BIT_INODE is NOT defined */ 201 dev_t st_dev; /* device inode resides on */ 202 ino_t st_ino; /* inode's number */ 203 mode_t st_mode; /* inode protection mode */ 204 nlink_t st_nlink; /* number of hard links to the file */ 205 uid_t st_uid; /* user-id of owner */ 206 gid_t st_gid; /* group-id of owner */ 207 dev_t st_rdev; /* device type, for special file inode */ 208 struct timespec st_atimespec; /* time of last access */ 209 struct timespec st_mtimespec; /* time of last data modification */ 210 struct timespec st_ctimespec; /* time of last file status change */ 211 off_t st_size; /* file size, in bytes */ 212 quad_t st_blocks; /* blocks allocated for file */ 213 u_long st_blksize;/* optimal file sys I/O ops blocksize */ 214 u_long st_flags; /* user defined flags for file */ 215 u_long st_gen; /* file generation number */ 216}; 217.Ed 218.Pp 219However, when the macro 220.Dv _DARWIN_FEATURE_64_BIT_INODE 221is defined, the 222.Fa stat 223structure will now be defined as: 224.Bd -literal 225struct stat { /* when _DARWIN_FEATURE_64_BIT_INODE is defined */ 226 dev_t st_dev; /* ID of device containing file */ 227 mode_t st_mode; /* Mode of file (see below) */ 228 nlink_t st_nlink; /* Number of hard links */ 229 ino_t st_ino; /* File serial number */ 230 uid_t st_uid; /* User ID of the file */ 231 gid_t st_gid; /* Group ID of the file */ 232 dev_t st_rdev; /* Device ID */ 233 struct timespec st_atimespec; /* time of last access */ 234 struct timespec st_mtimespec; /* time of last data modification */ 235 struct timespec st_ctimespec; /* time of last status change */ 236 struct timespec st_birthtimespec; /* time of file creation(birth) */ 237 off_t st_size; /* file size, in bytes */ 238 blkcnt_t st_blocks; /* blocks allocated for file */ 239 blksize_t st_blksize; /* optimal blocksize for I/O */ 240 uint32_t st_flags; /* user defined flags for file */ 241 uint32_t st_gen; /* file generation number */ 242 int32_t st_lspare; /* RESERVED: DO NOT USE! */ 243 int64_t st_qspare[2]; /* RESERVED: DO NOT USE! */ 244}; 245.Ed 246.Pp 247The time-related fields of 248.Fa struct stat 249are as follows: 250.Bl -tag -width XXXst_birthtime 251.It st_atime 252Time when file data last accessed. 253Changed by the 254.Xr mknod 2 , 255.Xr utimes 2 256and 257.Xr read 2 258system calls. 259.It st_mtime 260Time when file data last modified. 261Changed by the 262.Xr mknod 2 , 263.Xr utimes 2 264and 265.Xr write 2 266system calls. 267.It st_ctime 268Time when file status was last changed (inode data modification). 269Changed by the 270.Xr chmod 2 , 271.Xr chown 2 , 272.Xr link 2 , 273.Xr mknod 2 , 274.Xr rename 2 , 275.Xr unlink 2 , 276.Xr utimes 2 277and 278.Xr write 2 279system calls. 280.It st_birthtime 281Time of file creation. 282Only set once when the file is created. 283This field is only available in the 64 bit inode variants. 284On filesystems where birthtime is not available, this field is set to 0 285(i.e. epoch). 286.El 287.Pp 288The size-related fields of the structures are as follows: 289.Bl -tag -width XXXst_blksize 290.It st_blksize 291The optimal I/O block size for the file. 292.It st_blocks 293The actual number of blocks allocated for the file in 512-byte units. 294As short symbolic links are stored in the inode, this number may 295be zero. 296.El 297.Pp 298The status information word 299.Fa st_mode 300has the following bits: 301.Bd -literal 302#define S_IFMT 0170000 /* type of file */ 303#define S_IFIFO 0010000 /* named pipe (fifo) */ 304#define S_IFCHR 0020000 /* character special */ 305#define S_IFDIR 0040000 /* directory */ 306#define S_IFBLK 0060000 /* block special */ 307#define S_IFREG 0100000 /* regular */ 308#define S_IFLNK 0120000 /* symbolic link */ 309#define S_IFSOCK 0140000 /* socket */ 310#define S_IFWHT 0160000 /* whiteout */ 311#define S_ISUID 0004000 /* set user id on execution */ 312#define S_ISGID 0002000 /* set group id on execution */ 313#define S_ISVTX 0001000 /* save swapped text even after use */ 314#define S_IRUSR 0000400 /* read permission, owner */ 315#define S_IWUSR 0000200 /* write permission, owner */ 316#define S_IXUSR 0000100 /* execute/search permission, owner */ 317.Ed 318.Pp 319For a list of access modes, see 320.Aq Pa sys/stat.h , 321.Xr access 2 322and 323.Xr chmod 2 . 324.Pp 325For a list of the file flags in the 326.Fa st_flags 327field, see 328.Aq Pa sys/stat.h 329and 330.Xr chflags 2 . 331.Sh _DARWIN_FEATURE_64_BIT_INODE 332In order to accommodate advanced capabilities of newer file systems, the 333.Fa struct stat , 334.Fa struct statfs , 335and 336.Fa struct dirent 337data structures were updated in Mac OSX 10.5. 338.Pp 339The most obvious change is the increased size of 340.Fa ino_t 341from 32 bits to 64 bits. 342As a consequence, storing an ino_t in an int is no longer safe, and file 343formats storing ino_t as 32-bit values may need to be updated. 344There are other changes as well, such as the widening of 345.Fa f_fstypename , 346.Fa f_mntonname , 347and 348.Fa f_mntfromname 349in 350.Fa struct statfs . 351Please refer to 352.Xr dir 5 353for more detail on the specific changes to the other affected data structures. 354.Pp 355On platforms that existed before these updates were available, ABI 356compatibility is achieved by providing two implementations for related 357functions: one using the legacy data structures and one using the updated 358data structures. 359Variants which make use of the newer structures have their symbols suffixed 360with $INODE64. 361These $INODE64 suffixes are automatically appended by the compiler 362tool-chain and should not be used directly. 363.Pp 364Platforms that were released after these updates only have the newer variants 365available to them. 366These platforms have the macro 367.Dv _DARWIN_FEATURE_ONLY_64_BIT_INODE 368defined. 369.Pp 370The 371.Dv _DARWIN_FEATURE_64_BIT_INODE 372macro should not be set directly. 373Instead, developers should make use of the 374.Dv _DARWIN_NO_64_BIT_INODE 375or 376.Dv _DARWIN_USE_64_BIT_INODE 377macros when the default variant is not desired. 378The following table details the effects of defining these macros for 379different deployment targets. 380.Pp 381.hy 0 382.TS 383center; 384c s s s 385l | c s s 386c | c c c 387c | c c c 388l | c c c. 389T{ 390_DARWIN_FEATURE_ONLY_64_BIT_INODE \fBnot defined\fP 391T} 392= 393 Deployment Target 394user defines: < 10.5 10.5 > 10.5 395_ 396T{ 397\fI(none)\fP 398T} 32-bit 32-bit 64-bit 399T{ 400_DARWIN_NO_64_BIT_INODE 401T} 32-bit 32-bit 32-bit 402T{ 403_DARWIN_USE_64_BIT_INODE 404T} 32-bit 64-bit 64-bit 405_ 406.T& 407c s s s 408c | s s 409c | l s s 410c | c c c 411l | c c c. 412 413T{ 414_DARWIN_FEATURE_ONLY_64_BIT_INODE \fBdefined\fP 415T} 416= 417user defines: Any Deployment Target 418_ 419T{ 420\fI(none)\fP 421T} 64-bit-only 422T{ 423_DARWIN_NO_64_BIT_INODE 424T} T{ 425\fI(error)\fP 426T} 427T{ 428_DARWIN_USE_64_BIT_INODE 429T} 64-bit-only 430_ 431.TE 432.hy 433.Bl -tag -width 64-bit-only -offset indent 434.It 32-bit 43532-bit inode values are enabled, and the legacy structures involving the 436.Vt ino_t 437type are in use. 438The macro 439.Dv _DARWIN_FEATURE_64_BIT_INODE 440is not defined. 441.It 64-bit 44264-bit inode values are enabled, and the expanded structures involving the 443.Vt ino_t 444type are in use. 445The macro 446.Dv _DARWIN_FEATURE_64_BIT_INODE 447is defined, and loader symbols will contain the 448.Li $INODE64 449suffix. 450.It 64-bit-only 451Like 64-bit, except loader symbols do not have the 452.Li $INODE64 453suffix. 454.It Em (error) 455A compile time error is generated. 456.El 457.Pp 458Due to the increased benefits of the larger structure, it is highly 459recommended that developers not define 460.Dv _DARWIN_NO_64_BIT_INODE 461and make use of 462.Dv _DARWIN_USE_64_BIT_INODE 463when targeting Mac OSX 10.5. 464.Pp 465In addition to the $INODE64 suffixed symbols, variants suffixed with 64 are 466also available for related functions. 467These functions were provided as a way for developers to use the updated 468structures in code that also made use of the legacy structures. 469The enlarged stat structures were also prefixed with 64 to distinguish them 470from their legacy variants. 471These functions have been deprecated and should be avoided. 472.Sh RETURN VALUES 473Upon successful completion a value of 0 is returned. 474Otherwise, a value of -1 is returned and 475.Va errno 476is set to indicate the error. 477.Sh COMPATIBILITY 478Previous versions of the system used different types for the 479.Li st_dev , 480.Li st_uid , 481.Li st_gid , 482.Li st_rdev , 483.Li st_size , 484.Li st_blksize 485and 486.Li st_blocks 487fields. 488.Sh ERRORS 489The 490.Fn fstat 491system call will fail if: 492.Bl -tag -width Er 493.It Bq Er EBADF 494.Fa fildes 495is not a valid open file descriptor. 496.It Bq Er EFAULT 497.Fa Sb 498points to an invalid address. 499.It Bq Er EIO 500An I/O error occurs while reading from or writing to the file system. 501.El 502.Pp 503The 504.Fn lstat 505and 506.Fn stat 507system calls will fail if: 508.Bl -tag -width Er 509.\" =========== 510.It Bq Er EACCES 511Search permission is denied for a component of the path prefix. 512.\" =========== 513.It Bq Er EFAULT 514.Fa Sb 515or 516.Em name 517points to an invalid address. 518.\" =========== 519.It Bq Er EIO 520An I/O error occurs while reading from or writing to the file system. 521.\" =========== 522.It Bq Er ELOOP 523Too many symbolic links are encountered in translating the pathname. 524This is taken to be indicative of a looping symbolic link. 525.\" =========== 526.It Bq Er ELOOP 527If AT_SYMLINK_NOFOLLOW_ANY is passed and symbolic link was encountered 528during pathname resolution. 529.\" =========== 530.It Bq Er ENAMETOOLONG 531A component of a pathname exceeds 532.Dv {NAME_MAX} 533characters, or an entire path name exceeds 534.Dv {PATH_MAX} 535characters. 536.\" =========== 537.It Bq Er ENOENT 538The named file does not exist. 539.\" =========== 540.It Bq Er ENOTDIR 541A component of the path prefix is not a directory. 542.El 543.Pp 544The 545.Fn fstat , 546.Fn lstat , 547and 548.Fn stat 549system calls will fail if: 550.Bl -tag -width Er 551.\" =========== 552.It Bq Er EOVERFLOW 553The file size in bytes 554or the number of blocks allocated to the file 555or the file serial number cannot be represented correctly 556in the structure pointed to by 557.Fa buf . 558.El 559.Pp 560In addition to the errors returned by the 561.Fn stat 562and 563.Fn lstat , 564.Fn fstatat 565may fail if: 566.Bl -tag -width Er 567.It Bq Er EBADF 568The 569.Fa path 570argument does not specify an absolute path and the 571.Fa fd 572argument is neither 573.Dv AT_FDCWD 574nor a valid file descriptor open for searching. 575.It Bq Er EINVAL 576The value of the 577.Fa flag 578argument is not valid. 579.It Bq Er ENOTDIR 580The 581.Fa path 582argument is not an absolute path and 583.Fa fd 584is neither 585.Dv AT_FDCWD 586nor a file descriptor associated with a directory. 587.It Bq Er ENOTCAPABLE 588if AT_RESOLVE_BENEATH is passed and 589.Fa path 590does not reside in the directory hierarchy beneath the starting directory. 591.It Bq Er ENOTCAPABLE 592if AT_UNIQUE was passed and 593.Fa path 594resolves to a vnode with multiple links. 595.El 596.Sh CAVEATS 597The file generation number, 598.Fa st_gen , 599is only available to the super-user. 600.br 601The fields in the stat structure currently marked 602.Fa st_spare1 , 603.Fa st_spare2 , 604and 605.Fa st_spare3 606are present in preparation for inode time stamps expanding 607to 64 bits. 608This, however, can break certain programs that 609depend on the time stamps being contiguous (in calls to 610.Xr utimes 2 ) . 611.Sh TRANSITIONAL DESCRIPTION (NOW DEPRECATED) 612The 613.Fa fstat64 , 614.Fa lstat64 615and 616.Fa stat64 617routines are equivalent to their corresponding non-64-suffixed routine, 618when 64-bit inodes are in effect. 619They were added before there was support for the symbol variants, and so are 620now deprecated. 621Instead of using these, set the 622.Dv _DARWIN_USE_64_BIT_INODE 623macro before including header files to force 64-bit inode support. 624.Pp 625The 626.Fa stat64 627structure used by these deprecated routines is the same as the 628.Fa stat 629structure when 64-bit inodes are in effect (see above). 630.Sh SEE ALSO 631.Xr chflags 2 , 632.Xr chmod 2 , 633.Xr chown 2 , 634.Xr statfs 2 , 635.Xr utimes 2 , 636.Xr compat 5 , 637.Xr symlink 7 638.Sh BUGS 639Applying 640.Fn fstat 641to a socket (and thus to a pipe) 642returns a zero'd buffer, 643except for the blocksize field, 644and a unique device and inode number. 645.Sh STANDARDS 646The 647.Fn stat 648and 649.Fn fstat 650function calls are expected to conform to 651.St -p1003.1-88 . 652The 653.Fn fstatat 654system call is expected to conform to POSIX.1-2008 . 655.Sh HISTORY 656An 657.Fn lstat 658function call appeared in 659.Bx 4.2 . 660The 661.Fn stat64 , 662.Fn fstat64 , 663and 664.Fn lstat64 665system calls first appeared in Mac OS X 10.5 (Leopard) and are now deprecated 666in favor of the corresponding symbol variants. 667The 668.Fn fstatat 669system call appeared in OS X 10.10 670