bsd/man/man2/stat.2

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