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