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 (the
 131 .Ft ino_t
 132 type is 32-bits), the
 133 .Fa stat
 134 structure is defined as:
 135 .Bd -literal
 136 struct stat { /* when _DARWIN_FEATURE_64_BIT_INODE is NOT defined */
 137     dev_t    st_dev;    /* device inode resides on */
 138     ino_t    st_ino;    /* inode's number */
 139     mode_t   st_mode;   /* inode protection mode */
 140     nlink_t  st_nlink;  /* number or hard links to the file */
 141     uid_t    st_uid;    /* user-id of owner */
 142     gid_t    st_gid;    /* group-id of owner */
 143     dev_t    st_rdev;   /* device type, for special file inode */
 144     struct timespec st_atimespec;  /* time of last access */
 145     struct timespec st_mtimespec;  /* time of last data modification */
 146     struct timespec st_ctimespec;  /* time of last file status change */
 147     off_t    st_size;   /* file size, in bytes */
 148     quad_t   st_blocks; /* blocks allocated for file */
 149     u_long   st_blksize;/* optimal file sys I/O ops blocksize */
 150     u_long   st_flags;  /* user defined flags for file */
 151     u_long   st_gen;    /* file generation number */
 152 };
 153 .Ed
 154 .Pp
 155 However, when the macro
 156 .Dv _DARWIN_FEATURE_64_BIT_INODE
 157 is defined, the
 158 .Ft ino_t
 159 type will be 64-bits (force 64-bit inode mode by defining the
 160 .Dv _DARWIN_USE_64_BIT_INODE
 161 macro before including header files).
 162 This will cause symbol variants of the
 163 .Fa stat
 164 family, with the
 165 .Fa $INODE64
 166 suffixes, to be automatically linked in.
 167 In addition, the
 168 .Fa stat
 169 structure will now be defined as:
 170 .Bd -literal
 171 struct stat { /* when _DARWIN_FEATURE_64_BIT_INODE is defined */
 172     dev_t           st_dev;           /* ID of device containing file */
 173     mode_t          st_mode;          /* Mode of file (see below) */
 174     nlink_t         st_nlink;         /* Number of hard links */
 175     ino_t           st_ino;           /* File serial number */
 176     uid_t           st_uid;           /* User ID of the file */
 177     gid_t           st_gid;           /* Group ID of the file */
 178     dev_t           st_rdev;          /* Device ID */
 179     struct timespec st_atimespec;     /* time of last access */
 180     struct timespec st_mtimespec;     /* time of last data modification */
 181     struct timespec st_ctimespec;     /* time of last status change */
 182     struct timespec st_birthtimespec; /* time of file creation(birth) */
 183     off_t           st_size;          /* file size, in bytes */
 184     blkcnt_t        st_blocks;        /* blocks allocated for file */
 185     blksize_t       st_blksize;       /* optimal blocksize for I/O */
 186     uint32_t        st_flags;         /* user defined flags for file */
 187     uint32_t        st_gen;           /* file generation number */
 188     int32_t         st_lspare;        /* RESERVED: DO NOT USE! */
 189     int64_t         st_qspare[2];     /* RESERVED: DO NOT USE! */
 190 };
 191 .Ed
 192 .Pp
 193 The time-related fields of
 194 .Fa struct stat
 195 are as follows:
 196 .Bl -tag -width XXXst_birthtime
 197 .It st_atime
 198 Time when file data last accessed.
 199 Changed by the
 200 .Xr mknod 2 ,
 201 .Xr utimes 2
 202 and
 203 .Xr read 2
 204 system calls.
 205 .It st_mtime
 206 Time when file data last modified.
 207 Changed by the
 208 .Xr mknod 2 ,
 209 .Xr utimes 2
 210 and
 211 .Xr write 2
 212 system calls.
 213 .It st_ctime
 214 Time when file status was last changed (inode data modification).
 215 Changed by the
 216 .Xr chmod 2 ,
 217 .Xr chown 2 ,
 218 .Xr link 2 ,
 219 .Xr mknod 2 ,
 220 .Xr rename 2 ,
 221 .Xr unlink 2 ,
 222 .Xr utimes 2
 223 and
 224 .Xr write 2
 225 system calls.
 226 .It st_birthtime
 227 Time of file creation. Only set once when the file is created. This field is
 228 only available in the 64 bit inode variants. On filesystems where birthtime is
 229 not available, this field holds the
 230 .Fa ctime
 231 instead.
 232 .El
 233 .Pp
 234 The size-related fields of the structures are as follows:
 235 .Bl -tag -width XXXst_blksize
 236 .It st_blksize
 237 The optimal I/O block size for the file.
 238 .It st_blocks
 239 The actual number of blocks allocated for the file in 512-byte units.
 240 As short symbolic links are stored in the inode, this number may
 241 be zero.
 242 .El
 243 .Pp
 244 The status information word
 245 .Fa st_mode
 246 has the following bits:
 247 .Bd -literal
 248 #define S_IFMT 0170000           /* type of file */
 249 #define        S_IFIFO  0010000  /* named pipe (fifo) */
 250 #define        S_IFCHR  0020000  /* character special */
 251 #define        S_IFDIR  0040000  /* directory */
 252 #define        S_IFBLK  0060000  /* block special */
 253 #define        S_IFREG  0100000  /* regular */
 254 #define        S_IFLNK  0120000  /* symbolic link */
 255 #define        S_IFSOCK 0140000  /* socket */
 256 #define        S_IFWHT  0160000  /* whiteout */
 257 #define S_ISUID 0004000  /* set user id on execution */
 258 #define S_ISGID 0002000  /* set group id on execution */
 259 #define S_ISVTX 0001000  /* save swapped text even after use */
 260 #define S_IRUSR 0000400  /* read permission, owner */
 261 #define S_IWUSR 0000200  /* write permission, owner */
 262 #define S_IXUSR 0000100  /* execute/search permission, owner */
 263 .Ed
 264 .Pp
 265 For a list of access modes, see
 266 .Aq Pa sys/stat.h ,
 267 .Xr access 2
 268 and
 269 .Xr chmod 2 .
 270 .Pp
 271 For a list of the file flags in the
 272 .Fa st_flags
 273 field, see
 274 .Aq Pa sys/stat.h
 275 and
 276 .Xr chflags 2 .
 277 .Sh RETURN VALUES
 278 Upon successful completion a value of 0 is returned.
 279 Otherwise, a value of -1 is returned and
 280 .Va errno
 281 is set to indicate the error.
 282 .Sh COMPATIBILITY
 283 Previous versions of the system used different types for the
 284 .Li st_dev ,
 285 .Li st_uid ,
 286 .Li st_gid ,
 287 .Li st_rdev ,
 288 .Li st_size ,
 289 .Li st_blksize
 290 and
 291 .Li st_blocks
 292 fields.
 293 .Sh ERRORS
 294 .Bl -tag -width Er
 295 The
 296 .Fn fstat
 297 system call will fail if:
 298 .\" ===========
 299 .It Bq Er EBADF
 300 .Fa fildes
 301 is not a valid open file descriptor.
 302 .\" ===========
 303 .It Bq Er EFAULT
 304 .Fa Sb
 305 points to an invalid address.
 306 .\" ===========
 307 .It Bq Er EIO
 308 An I/O error occurs while reading from or writing to the file system.
 309 .El
 310 .Pp
 311 The
 312 .Fn lstat
 313 and
 314 .Fn stat
 315 system calls will fail if:
 316 .Bl -tag -width Er
 317 .\" ===========
 318 .It Bq Er EACCES
 319 Search permission is denied for a component of the path prefix.
 320 .\" ===========
 321 .It Bq Er EFAULT
 322 .Fa Sb
 323 or
 324 .Em name
 325 points to an invalid address.
 326 .\" ===========
 327 .It Bq Er EIO
 328 An I/O error occurs while reading from or writing to the file system.
 329 .\" ===========
 330 .It Bq Er ELOOP
 331 Too many symbolic links are encountered in translating the pathname.
 332 This is taken to be indicative of a looping symbolic link.
 333 .\" ===========
 334 .It Bq Er ENAMETOOLONG
 335 A component of a pathname exceeds
 336 .Dv {NAME_MAX}
 337 characters, or an entire path name exceeds
 338 .Dv {PATH_MAX}
 339 characters.
 340 .\" ===========
 341 .It Bq Er ENOENT
 342 The named file does not exist.
 343 .\" ===========
 344 .It Bq Er ENOTDIR
 345 A component of the path prefix is not a directory.
 346 .El
 347 .Pp
 348 The
 349 .Fn fstat ,
 350 .Fn lstat ,
 351 and
 352 .Fn stat
 353 system calls will fail if:
 354 .Bl -tag -width Er
 355 .\" ===========
 356 .It Bq Er EOVERFLOW
 357 The file size in bytes
 358 or the number of blocks allocated to the file
 359 or the file serial number cannot be represented correctly
 360 in the structure pointed to by
 361 .Fa buf .
 362 .El
 363 .Sh CAVEATS
 364 The file generation number,
 365 .Fa st_gen ,
 366 is only available to the super-user.
 367 .br
 368 The fields in the stat structure currently marked
 369 .Fa st_spare1 ,
 370 .Fa st_spare2 ,
 371 and
 372 .Fa st_spare3
 373 are present in preparation for inode time stamps expanding
 374 to 64 bits.  This, however, can break certain programs that
 375 depend on the time stamps being contiguous (in calls to
 376 .Xr utimes 2 ) .
 377 .Sh TRANSITIONAL DESCRIPTION (NOW DEPRECATED)
 378 The
 379 .Fa fstat64 ,
 380 .Fa lstat64
 381 and
 382 .Fa stat64
 383 routines are equivalent to their corresponding non-64-suffixed routine,
 384 when 64-bit inodes are in effect.
 385 They were added before there was support for the symbol variants, and so are
 386 now deprecated.
 387 Instead of using these, set the
 388 .Dv _DARWIN_USE_64_BIT_INODE
 389 macro before including header files to force 64-bit inode support.
 390 .Pp
 391 The
 392 .Fa stat64
 393 structure used by these deprecated routines is the same as the
 394 .Fa stat
 395 structure when 64-bit inodes are in effect (see above).
 396 .Sh SEE ALSO
 397 .Xr chflags 2 ,
 398 .Xr chmod 2 ,
 399 .Xr chown 2 ,
 400 .Xr utimes 2 ,
 401 .Xr compat 5 ,
 402 .Xr symlink 7
 403 .Sh BUGS
 404 Applying
 405 .Xr fstat
 406 to a socket (and thus to a pipe)
 407 returns a zero'd buffer,
 408 except for the blocksize field,
 409 and a unique device and inode number.
 410 .Sh STANDARDS
 411 The
 412 .Fn stat
 413 and
 414 .Fn fstat
 415 function calls are expected to conform to
 416 .St -p1003.1-88 .
 417 .Sh HISTORY
 418 An
 419 .Fn lstat
 420 function call appeared in
 421 .Bx 4.2 .
 422 The
 423 .Fn stat64 ,
 424 .Fn fstat64 ,
 425 and
 426 .Fn lstat64
 427 system calls first appeared in Mac OS X 10.5 (Leopard) and are now deprecated
 428 in favor of the corresponding symbol variants.