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