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