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