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