bsd/man/man2/stat.2

   1 .\"     $OpenBSD: stat.2,v 1.3 1997/02/13 05:20:55 millert Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993, 1994
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)stat.2      8.3 (Berkeley) 4/19/94
  35 .\"
  36 .Dd April 19, 1994
  37 .Dt STAT 2
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm stat ,
  41 .Nm lstat ,
  42 .Nm fstat
  43 .Nd get file status
  44 .Sh SYNOPSIS
  45 .Fd #include <sys/types.h>
  46 .Fd #include <sys/stat.h>
  47 .Ft int
  48 .Fn stat "const char *path" "struct stat *sb"
  49 .Ft int
  50 .Fn lstat "const char *path" "struct stat *sb"
  51 .Ft int
  52 .Fn fstat "int fd" "struct stat *sb"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn stat
  56 function 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 .Fn Lstat
  63 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 Unlike other filesystem objects,
  73 symbolic links do not have an owner, group, access mode, times, etc.
  74 Instead, these attributes are taken from the directory that
  75 contains the link.
  76 The only attributes returned from an
  77 .Fn lstat
  78 that refer to the symbolic link itself are the file type (S_IFLNK),
  79 size, blocks, and link count (always 1).
  80 .Pp
  81 The
  82 .Fn fstat
  83 obtains the same information about an open file
  84 known by the file descriptor
  85 .Fa fd .
  86 .Pp
  87 The
  88 .Fa sb
  89 argument is a pointer to a
  90 .Fn stat
  91 structure
  92 as defined by
  93 .Aq Pa sys/stat.h
  94 (shown below)
  95 and into which information is placed concerning the file.
  96 .Bd -literal
  97 struct stat {
  98     dev_t    st_dev;    /* device inode resides on */
  99     ino_t    st_ino;    /* inode's number */
 100     mode_t   st_mode;   /* inode protection mode */
 101     nlink_t  st_nlink;  /* number or hard links to the file */
 102     uid_t    st_uid;    /* user-id of owner */
 103     gid_t    st_gid;    /* group-id of owner */
 104     dev_t    st_rdev;   /* device type, for special file inode */
 105     struct timespec st_atimespec;  /* time of last access */
 106     struct timespec st_mtimespec;  /* time of last data modification */
 107     struct timespec st_ctimespec;  /* time of last file status change */
 108     off_t    st_size;   /* file size, in bytes */
 109     quad_t   st_blocks; /* blocks allocated for file */
 110     u_long   st_blksize;/* optimal file sys I/O ops blocksize */
 111     u_long   st_flags;  /* user defined flags for file */
 112     u_long   st_gen;    /* file generation number */
 113 };
 114 .Ed
 115 .Pp
 116 The time-related fields of
 117 .Fa struct stat
 118 are as follows:
 119 .Bl -tag -width XXXst_mtime
 120 .It st_atime
 121 Time when file data last accessed.
 122 Changed by the
 123 .Xr mknod 2 ,
 124 .Xr utimes 2
 125 and
 126 .Xr read 2
 127 system calls.
 128 .It st_mtime
 129 Time when file data last modified.
 130 Changed by the
 131 .Xr mknod 2 ,
 132 .Xr utimes 2
 133 and
 134 .Xr write 2
 135 system calls.
 136 .It st_ctime
 137 Time when file status was last changed (inode data modification).
 138 Changed by the
 139 .Xr chmod 2 ,
 140 .Xr chown 2 ,
 141 .Xr link 2 ,
 142 .Xr mknod 2 ,
 143 .Xr rename 2 ,
 144 .Xr unlink 2 ,
 145 .Xr utimes 2
 146 and
 147 .Xr write 2
 148 system calls.
 149 .El
 150 .Pp
 151 The size-related fields of the
 152 .Fa struct stat
 153 are as follows:
 154 .Bl -tag -width XXXst_blksize
 155 .It st_blksize
 156 The optimal I/O block size for the file.
 157 .It st_blocks
 158 The actual number of blocks allocated for the file in 512-byte units.
 159 As short symbolic links are stored in the inode, this number may
 160 be zero.
 161 .El
 162 .Pp
 163 The status information word
 164 .Fa st_mode
 165 has the following bits:
 166 .Bd -literal
 167 #define S_IFMT 0170000           /* type of file */
 168 #define        S_IFIFO  0010000  /* named pipe (fifo) */
 169 #define        S_IFCHR  0020000  /* character special */
 170 #define        S_IFDIR  0040000  /* directory */
 171 #define        S_IFBLK  0060000  /* block special */
 172 #define        S_IFREG  0100000  /* regular */
 173 #define        S_IFLNK  0120000  /* symbolic link */
 174 #define        S_IFSOCK 0140000  /* socket */
 175 #define        S_IFWHT  0160000  /* whiteout */
 176 #define S_ISUID 0004000  /* set user id on execution */
 177 #define S_ISGID 0002000  /* set group id on execution */
 178 #define S_ISVTX 0001000  /* save swapped text even after use */
 179 #define S_IRUSR 0000400  /* read permission, owner */
 180 #define S_IWUSR 0000200  /* write permission, owner */
 181 #define S_IXUSR 0000100  /* execute/search permission, owner */
 182 .Ed
 183 .Pp
 184 For a list of access modes, see
 185 .Aq Pa sys/stat.h ,
 186 .Xr access 2
 187 and
 188 .Xr chmod 2 .
 189 .Sh RETURN VALUES
 190 Upon successful completion a value of 0 is returned.
 191 Otherwise, a value of -1 is returned and
 192 .Va errno
 193 is set to indicate the error.
 194 .Sh COMPATIBILITY
 195 Previous versions of the system used different types for the
 196 .Li st_dev ,
 197 .Li st_uid ,
 198 .Li st_gid ,
 199 .Li st_rdev ,
 200 .Li st_size ,
 201 .Li st_blksize
 202 and
 203 .Li st_blocks
 204 fields.
 205 .Sh ERRORS
 206 .Fn Stat
 207 and
 208 .Fn lstat
 209 will fail if:
 210 .Bl -tag -width Er
 211 .It Bq Er ENOTDIR
 212 A component of the path prefix is not a directory.
 213 .It Bq Er ENAMETOOLONG
 214 A component of a pathname exceeded
 215 .Dv {NAME_MAX}
 216 characters, or an entire path name exceeded
 217 .Dv {PATH_MAX}
 218 characters.
 219 .It Bq Er ENOENT
 220 The named file does not exist.
 221 .It Bq Er EACCES
 222 Search permission is denied for a component of the path prefix.
 223 .It Bq Er ELOOP
 224 Too many symbolic links were encountered in translating the pathname.
 225 .It Bq Er EFAULT
 226 .Fa Sb
 227 or
 228 .Em name
 229 points to an invalid address.
 230 .It Bq Er EIO
 231 An I/O error occurred while reading from or writing to the file system.
 232 .El
 233 .Pp
 234 .Bl -tag -width Er
 235 .Fn Fstat
 236 will fail if:
 237 .It Bq Er EBADF
 238 .Fa fd
 239 is not a valid open file descriptor.
 240 .It Bq Er EFAULT
 241 .Fa Sb
 242 points to an invalid address.
 243 .It Bq Er EIO
 244 An I/O error occurred while reading from or writing to the file system.
 245 .El
 246 .Sh CAVEATS
 247 The file generation number,
 248 .Fa st_gen ,
 249 is only available to the super-user.
 250 .br
 251 The fields in the stat structure currently marked
 252 .Fa st_spare1 ,
 253 .Fa st_spare2 ,
 254 and
 255 .Fa st_spare3
 256 are present in preparation for inode time stamps expanding
 257 to 64 bits.  This, however, can break certain programs that
 258 depend on the time stamps being contiguous (in calls to
 259 .Xr utimes 2 ) .
 260 .Sh SEE ALSO
 261 .Xr chmod 2 ,
 262 .Xr chown 2 ,
 263 .Xr utimes 2
 264 .Xr symlink 7
 265 .Sh BUGS
 266 Applying
 267 .Xr fstat
 268 to a socket (and thus to a pipe)
 269 returns a zero'd buffer,
 270 except for the blocksize field,
 271 and a unique device and inode number.
 272 .Sh STANDARDS
 273 The
 274 .Fn stat
 275 and
 276 .Fn fstat
 277 function calls are expected to conform to
 278 .St -p1003.1-88 .
 279 .Sh HISTORY
 280 An
 281 .Fn lstat
 282 function call appeared in
 283 .Bx 4.2 .