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