lib/libc/sys/stat.2

   1 .\" Copyright (c) 1980, 1991, 1993, 1994
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)stat.2      8.4 (Berkeley) 5/1/95
  29 .\"
  30 .Dd March 30, 2021
  31 .Dt STAT 2
  32 .Os
  33 .Sh NAME
  34 .Nm stat ,
  35 .Nm lstat ,
  36 .Nm fstat ,
  37 .Nm fstatat
  38 .Nd get file status
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/stat.h
  43 .Ft int
  44 .Fn stat "const char * restrict path" "struct stat * restrict sb"
  45 .Ft int
  46 .Fn lstat "const char * restrict path" "struct stat * restrict sb"
  47 .Ft int
  48 .Fn fstat "int fd" "struct stat *sb"
  49 .Ft int
  50 .Fn fstatat "int fd" "const char *path" "struct stat *sb" "int flag"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn stat
  54 system call obtains information about the file pointed to by
  55 .Fa path .
  56 Read, write or execute
  57 permission of the named file is not required, but all directories
  58 listed in the path name leading to the file must be searchable.
  59 .Pp
  60 The
  61 .Fn lstat
  62 system call is like
  63 .Fn stat
  64 except when the named file is a symbolic link,
  65 in which case
  66 .Fn lstat
  67 returns information about the link,
  68 while
  69 .Fn stat
  70 returns information about the file the link references.
  71 .Pp
  72 The
  73 .Fn fstat
  74 system call obtains the same information about an open file
  75 known by the file descriptor
  76 .Fa fd .
  77 .Pp
  78 The
  79 .Fn fstatat
  80 system call is equivalent to
  81 .Fn stat
  82 and
  83 .Fn lstat
  84 except when the
  85 .Fa path
  86 specifies a relative path.
  87 For
  88 .Fn fstatat
  89 and relative
  90 .Fa path ,
  91 the status is retrieved from a file relative to
  92 the directory associated with the file descriptor
  93 .Fa fd
  94 instead of the current working directory.
  95 .Pp
  96 The values for the
  97 .Fa flag
  98 are constructed by a bitwise-inclusive OR of flags from this list,
  99 defined in
 100 .In fcntl.h :
 101 .Bl -tag -width indent
 102 .It Dv AT_SYMLINK_NOFOLLOW
 103 If
 104 .Fa path
 105 names a symbolic link, the status of the symbolic link is returned.
 106 .It Dv AT_RESOLVE_BENEATH
 107 Only walk paths below the starting directory.
 108 See the description of the
 109 .Dv O_RESOLVE_BENEATH
 110 flag in the
 111 .Xr open 2
 112 manual page.
 113 .It Dv AT_EMPTY_PATH
 114 If the
 115 .Fa path
 116 argument is an empty string, operate on the file or directory
 117 referenced by the descriptor
 118 .Fa fd .
 119 If
 120 .Fa fd
 121 is equal to
 122 .Dv AT_FDCWD ,
 123 operate on the current working directory.
 124 .El
 125 .Pp
 126 If
 127 .Fn fstatat
 128 is passed the special value
 129 .Dv AT_FDCWD
 130 in the
 131 .Fa fd
 132 parameter, the current working directory is used and the behavior is
 133 identical to a call to
 134 .Fn stat
 135 or
 136 .Fn lstat
 137 respectively, depending on whether or not the
 138 .Dv AT_SYMLINK_NOFOLLOW
 139 bit is set in
 140 .Fa flag .
 141 .Pp
 142 When
 143 .Fn fstatat
 144 is called with an absolute
 145 .Fa path ,
 146 it ignores the
 147 .Fa fd
 148 argument.
 149 .Pp
 150 The
 151 .Fa sb
 152 argument is a pointer to a
 153 .Vt stat
 154 structure
 155 as defined by
 156 .In sys/stat.h
 157 and into which information is placed concerning the file.
 158 .Pp
 159 The fields of
 160 .Vt "struct stat"
 161 related to the file system are:
 162 .Bl -tag -width ".Va st_nlink"
 163 .It Va st_dev
 164 Numeric ID of the device containing the file.
 165 .It Va st_ino
 166 The file's inode number.
 167 .It Va st_nlink
 168 Number of hard links to the file.
 169 .It Va st_flags
 170 Flags enabled for the file.
 171 See
 172 .Xr chflags 2
 173 for the list of flags and their description.
 174 .El
 175 .Pp
 176 The
 177 .Va st_dev
 178 and
 179 .Va st_ino
 180 fields together identify the file uniquely within the system.
 181 .Pp
 182 The time-related fields of
 183 .Vt "struct stat"
 184 are:
 185 .Bl -tag -width ".Va st_birthtim"
 186 .It Va st_atim
 187 Time when file data was last accessed.
 188 Changed implicitly by syscalls such as
 189 .Xr read 2
 190 and
 191 .Xr readv 2 ,
 192 and explicitly by
 193 .Xr utimes 2 .
 194 .It Va st_mtim
 195 Time when file data was last modified.
 196 Changed implicitly by syscalls such as
 197 .Xr truncate 2 ,
 198 .Xr write 2 ,
 199 and
 200 .Xr writev 2 ,
 201 and explicitly by
 202 .Xr utimes 2 .
 203 Also, any syscall which modifies directory content changes the
 204 .Va st_mtim
 205 for the affected directory.
 206 For instance,
 207 .Xr creat 2 ,
 208 .Xr mkdir 2 ,
 209 .Xr rename 2 ,
 210 .Xr link 2 ,
 211 and
 212 .Xr unlink 2 .
 213 .It Va st_ctim
 214 Time when file status was last changed (inode data modification).
 215 Changed implicitly by any syscall that affects file metadata, including
 216 .Va st_mtim ,
 217 such as
 218 .Xr chflags 2 ,
 219 .Xr chmod 2 ,
 220 .Xr chown 2 ,
 221 .Xr truncate 2 ,
 222 .Xr utimes 2 ,
 223 and
 224 .Xr write 2 .
 225 Also, any syscall which modifies directory content changes the
 226 .Va st_ctim
 227 for the affected directory.
 228 For instance,
 229 .Xr creat 2 ,
 230 .Xr mkdir 2 ,
 231 .Xr rename 2 ,
 232 .Xr link 2 ,
 233 and
 234 .Xr unlink 2 .
 235 .It Va st_birthtim
 236 Time when the inode was created.
 237 .El
 238 .Pp
 239 These time-related macros are defined for compatibility:
 240 .Bd -literal
 241 #define st_atime                st_atim.tv_sec
 242 #define st_mtime                st_mtim.tv_sec
 243 #define st_ctime                st_ctim.tv_sec
 244 #ifndef _POSIX_SOURCE
 245 #define st_birthtime            st_birthtim.tv_sec
 246 #endif
 247
 248 #ifndef _POSIX_SOURCE
 249 #define st_atimespec            st_atim
 250 #define st_mtimespec            st_mtim
 251 #define st_ctimespec            st_ctim
 252 #define st_birthtimespec        st_birthtim
 253 #endif
 254 .Ed
 255 .Pp
 256 Size-related fields of the
 257 .Vt "struct stat"
 258 are:
 259 .Bl -tag -width ".Va st_blksize"
 260 .It Va st_size
 261 File size in bytes.
 262 .It Va st_blksize
 263 Optimal I/O block size for the file.
 264 .It Va st_blocks
 265 Actual number of blocks allocated for the file in 512-byte units.
 266 As short symbolic links are stored in the inode, this number may
 267 be zero.
 268 .El
 269 .Pp
 270 The access-related fields of
 271 .Vt "struct stat"
 272 are:
 273 .Bl -tag -width ".Va st_mode"
 274 .It Va st_uid
 275 User ID of the file's owner.
 276 .It Va st_gid
 277 Group ID of the file.
 278 .It Va st_mode
 279 Status of the file (see below).
 280 .El
 281 .Pp
 282 The status information word
 283 .Fa st_mode
 284 has these bits:
 285 .Bd -literal
 286 #define S_IFMT   0170000  /* type of file mask */
 287 #define S_IFIFO  0010000  /* named pipe (fifo) */
 288 #define S_IFCHR  0020000  /* character special */
 289 #define S_IFDIR  0040000  /* directory */
 290 #define S_IFBLK  0060000  /* block special */
 291 #define S_IFREG  0100000  /* regular */
 292 #define S_IFLNK  0120000  /* symbolic link */
 293 #define S_IFSOCK 0140000  /* socket */
 294 #define S_IFWHT  0160000  /* whiteout */
 295 #define S_ISUID  0004000  /* set user id on execution */
 296 #define S_ISGID  0002000  /* set group id on execution */
 297 #define S_ISVTX  0001000  /* save swapped text even after use */
 298 #define S_IRWXU  0000700  /* RWX mask for owner */
 299 #define S_IRUSR  0000400  /* read permission, owner */
 300 #define S_IWUSR  0000200  /* write permission, owner */
 301 #define S_IXUSR  0000100  /* execute/search permission, owner */
 302 #define S_IRWXG  0000070  /* RWX mask for group */
 303 #define S_IRGRP  0000040  /* read permission, group */
 304 #define S_IWGRP  0000020  /* write permission, group */
 305 #define S_IXGRP  0000010  /* execute/search permission, group */
 306 #define S_IRWXO  0000007  /* RWX mask for other */
 307 #define S_IROTH  0000004  /* read permission, other */
 308 #define S_IWOTH  0000002  /* write permission, other */
 309 #define S_IXOTH  0000001  /* execute/search permission, other */
 310 .Ed
 311 .Pp
 312 For a list of access modes, see
 313 .In sys/stat.h ,
 314 .Xr access 2
 315 and
 316 .Xr chmod 2 .
 317 These macros are available to test whether a
 318 .Va st_mode
 319 value passed in the
 320 .Fa m
 321 argument corresponds to a file of the specified type:
 322 .Bl -tag -width ".Fn S_ISFIFO m"
 323 .It Fn S_ISBLK m
 324 Test for a block special file.
 325 .It Fn S_ISCHR m
 326 Test for a character special file.
 327 .It Fn S_ISDIR m
 328 Test for a directory.
 329 .It Fn S_ISFIFO m
 330 Test for a pipe or FIFO special file.
 331 .It Fn S_ISLNK m
 332 Test for a symbolic link.
 333 .It Fn S_ISREG m
 334 Test for a regular file.
 335 .It Fn S_ISSOCK m
 336 Test for a socket.
 337 .It Fn S_ISWHT m
 338 Test for a whiteout.
 339 .El
 340 .Pp
 341 The macros evaluate to a non-zero value if the test is true
 342 or to the value 0 if the test is false.
 343 .Sh RETURN VALUES
 344 .Rv -std
 345 .Sh COMPATIBILITY
 346 Previous versions of the system used different types for the
 347 .Va st_dev ,
 348 .Va st_uid ,
 349 .Va st_gid ,
 350 .Va st_rdev ,
 351 .Va st_size ,
 352 .Va st_blksize
 353 and
 354 .Va st_blocks
 355 fields.
 356 .Sh ERRORS
 357 The
 358 .Fn stat
 359 and
 360 .Fn lstat
 361 system calls will fail if:
 362 .Bl -tag -width Er
 363 .It Bq Er EACCES
 364 Search permission is denied for a component of the path prefix.
 365 .It Bq Er EFAULT
 366 The
 367 .Fa sb
 368 or
 369 .Fa path
 370 argument
 371 points to an invalid address.
 372 .It Bq Er EIO
 373 An I/O error occurred while reading from or writing to the file system.
 374 .It Bq Er EINTEGRITY
 375 Corrupted data was detected while reading from the file system.
 376 .It Bq Er ELOOP
 377 Too many symbolic links were encountered in translating the pathname.
 378 .It Bq Er ENAMETOOLONG
 379 A component of a pathname exceeded 255 characters,
 380 or an entire path name exceeded 1023 characters.
 381 .It Bq Er ENOENT
 382 The named file does not exist.
 383 .It Bq Er ENOTDIR
 384 A component of the path prefix is not a directory.
 385 .It Bq Er EOVERFLOW
 386 The file size in bytes cannot be
 387 represented correctly in the structure pointed to by
 388 .Fa sb .
 389 .El
 390 .Pp
 391 The
 392 .Fn fstat
 393 system call will fail if:
 394 .Bl -tag -width Er
 395 .It Bq Er EBADF
 396 The
 397 .Fa fd
 398 argument
 399 is not a valid open file descriptor.
 400 .It Bq Er EFAULT
 401 The
 402 .Fa sb
 403 argument
 404 points to an invalid address.
 405 .It Bq Er EIO
 406 An I/O error occurred while reading from or writing to the file system.
 407 .It Bq Er EINTEGRITY
 408 Corrupted data was detected while reading from the file system.
 409 .It Bq Er EOVERFLOW
 410 The file size in bytes cannot be
 411 represented correctly in the structure pointed to by
 412 .Fa sb .
 413 .El
 414 .Pp
 415 In addition to the errors returned by the
 416 .Fn lstat ,
 417 the
 418 .Fn fstatat
 419 may fail if:
 420 .Bl -tag -width Er
 421 .It Bq Er EBADF
 422 The
 423 .Fa path
 424 argument does not specify an absolute path and the
 425 .Fa fd
 426 argument is neither
 427 .Dv AT_FDCWD
 428 nor a valid file descriptor open for searching.
 429 .It Bq Er EINVAL
 430 The value of the
 431 .Fa flag
 432 argument is not valid.
 433 .It Bq Er ENOTDIR
 434 The
 435 .Fa path
 436 argument is not an absolute path and
 437 .Fa fd
 438 is neither
 439 .Dv AT_FDCWD
 440 nor a file descriptor associated with a directory.
 441 .It Bq Er ENOTCAPABLE
 442 .Fa path
 443 is an absolute path,
 444 or contained a ".." component leading to a
 445 directory outside of the directory hierarchy specified by
 446 .Fa fd ,
 447 and the process is in capability mode or the
 448 .Dv AT_RESOLVE_BENEATH
 449 flag was specified.
 450 .El
 451 .Sh SEE ALSO
 452 .Xr access 2 ,
 453 .Xr chmod 2 ,
 454 .Xr chown 2 ,
 455 .Xr fhstat 2 ,
 456 .Xr statfs 2 ,
 457 .Xr utimes 2 ,
 458 .Xr sticky 7 ,
 459 .Xr symlink 7
 460 .Sh STANDARDS
 461 The
 462 .Fn stat
 463 and
 464 .Fn fstat
 465 system calls are expected to conform to
 466 .St -p1003.1-90 .
 467 The
 468 .Fn fstatat
 469 system call follows The Open Group Extended API Set 2 specification.
 470 .Sh HISTORY
 471 The
 472 .Fn stat
 473 and
 474 .Fn fstat
 475 system calls appeared in
 476 .At v1 .
 477 The
 478 .Fn lstat
 479 system call appeared in
 480 .Bx 4.2 .
 481 The
 482 .Fn fstatat
 483 system call appeared in
 484 .Fx 8.0 .
 485 .Sh BUGS
 486 Applying
 487 .Fn fstat
 488 to a socket
 489 returns a zeroed buffer,
 490 except for the blocksize field,
 491 and a unique device and inode number.