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