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