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