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