man2/stat.2

   1 '\" t
   2 .\" Hey Emacs! This file is -*- nroff -*- source.
   3 .\"
   4 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   5 .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
   6 .\" and Copyright (c) 2007 Michael Kerrisk <mtk-manpages@gmx.net>
   7 .\"
   8 .\" Permission is granted to make and distribute verbatim copies of this
   9 .\" manual provided the copyright notice and this permission notice are
  10 .\" preserved on all copies.
  11 .\"
  12 .\" Permission is granted to copy and distribute modified versions of this
  13 .\" manual under the conditions for verbatim copying, provided that the
  14 .\" entire resulting derived work is distributed under the terms of a
  15 .\" permission notice identical to this one.
  16 .\"
  17 .\" Since the Linux kernel and libraries are constantly changing, this
  18 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  19 .\" responsibility for errors or omissions, or for damages resulting from
  20 .\" the use of the information contained herein.  The author(s) may not
  21 .\" have taken the same level of care in the production of this manual,
  22 .\" which is licensed free of charge, as they might when working
  23 .\" professionally.
  24 .\"
  25 .\" Formatted or processed versions of this manual, if unaccompanied by
  26 .\" the source, must acknowledge the copyright and authors of this work.
  27 .\"
  28 .\" Modified by Michael Haardt <michael@moria.de>
  29 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  30 .\" Modified 1995-05-18 by Todd Larason <jtl@molehill.org>
  31 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
  32 .\" Modified 1995-01-09 by Richard Kettlewell <richard@greenend.org.uk>
  33 .\" Modified 1998-05-13 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de>
  34 .\" Modified 1999-07-06 by aeb & Albert Cahalan
  35 .\" Modified 2000-01-07 by aeb
  36 .\" Modified 2004-06-23 by Michael Kerrisk <mtk-manpages@gmx.net>
  37 .\" 2007-06-08 mtk: Added example program
  38 .\"
  39 .TH STAT 2 2007-06-08 "Linux" "Linux Programmer's Manual"
  40 .SH NAME
  41 stat, fstat, lstat \- get file status
  42 .SH SYNOPSIS
  43 .B #include <sys/types.h>
  44 .br
  45 .B #include <sys/stat.h>
  46 .br
  47 .B #include <unistd.h>
  48 .sp
  49 .BI "int stat(const char *" path ", struct stat *" buf );
  50 .br
  51 .BI "int fstat(int " filedes ", struct stat *" buf );
  52 .br
  53 .BI "int lstat(const char *" path ", struct stat *" buf );
  54 .SH DESCRIPTION
  55 .PP
  56 These functions return information about a file.
  57 No permissions are required on the file itself, but \(em in the case of
  58 .BR stat ()
  59 and
  60 .BR lstat ()
  61 \(em
  62 execute (search) permission is required on all of the directories in
  63 .I path
  64 that lead to the file.
  65 .PP
  66 .BR stat ()
  67 stats the file pointed to by
  68 .I path
  69 and fills in
  70 .IR buf .
  71
  72 .BR lstat ()
  73 is identical to
  74 .BR stat (),
  75 except that if
  76 .I path
  77 is a symbolic link, then the link itself is stat-ed,
  78 not the file that it refers to.
  79
  80 .BR fstat ()
  81 is identical to
  82 .BR stat (),
  83 except that the file to be stat-ed is specified by the file descriptor
  84 .IR filedes .
  85 .PP
  86 All of these system calls return a
  87 .I stat
  88 structure, which contains the following fields:
  89 .PP
  90 .RS 0.25i
  91 .nf
  92 struct stat {
  93     dev_t     st_dev;     /* ID of device containing file */
  94     ino_t     st_ino;     /* inode number */
  95     mode_t    st_mode;    /* protection */
  96     nlink_t   st_nlink;   /* number of hard links */
  97     uid_t     st_uid;     /* user ID of owner */
  98     gid_t     st_gid;     /* group ID of owner */
  99     dev_t     st_rdev;    /* device ID (if special file) */
 100     off_t     st_size;    /* total size, in bytes */
 101     blksize_t st_blksize; /* blocksize for filesystem I/O */
 102     blkcnt_t  st_blocks;  /* number of blocks allocated */
 103     time_t    st_atime;   /* time of last access */
 104     time_t    st_mtime;   /* time of last modification */
 105     time_t    st_ctime;   /* time of last status change */
 106 };
 107 .fi
 108 .RE
 109 .PP
 110 The
 111 .I st_dev
 112 field describes the device on which this file resides.
 113
 114 The
 115 .I st_rdev
 116 field describes the device that this file (inode) represents.
 117
 118 The
 119 .I st_size
 120 field gives the size of the file (if it is a regular
 121 file or a symbolic link) in bytes.
 122 The size of a symlink is the length of the pathname
 123 it contains, without a trailing null byte.
 124
 125 The
 126 .I st_blocks
 127 field indicates the number of blocks allocated to the file, 512-byte units.
 128 (This may be smaller than
 129 .IR st_size /512,
 130 for example, when the file has holes.)
 131
 132 The
 133 .IR st_blksize
 134 field gives the "preferred" blocksize for efficient file system I/O.
 135 (Writing to a file in smaller chunks may cause
 136 an inefficient read-modify-rewrite.)
 137 .PP
 138 Not all of the Linux filesystems implement all of the time fields.
 139 Some file system types allow mounting in such a way that file
 140 accesses do not cause an update of the
 141 .I st_atime
 142 field.
 143 (See `noatime' in
 144 .BR mount (8).)
 145
 146 The field
 147 .I st_atime
 148 is changed by file accesses, for example, by
 149 .BR execve (2),
 150 .BR mknod (2),
 151 .BR pipe (2),
 152 .BR utime (2)
 153 and
 154 .BR read (2)
 155 (of more than zero bytes).
 156 Other routines, like
 157 .BR mmap (2),
 158 may or may not update
 159 .IR st_atime .
 160
 161 The field
 162 .I st_mtime
 163 is changed by file modifications, for example, by
 164 .BR mknod (2),
 165 .BR truncate (2),
 166 .BR utime (2)
 167 and
 168 .BR write (2)
 169 (of more than zero bytes).
 170 Moreover,
 171 .I st_mtime
 172 of a directory is changed by the creation or deletion of files
 173 in that directory.
 174 The
 175 .I st_mtime
 176 field is
 177 .I not
 178 changed for changes in owner, group, hard link count, or mode.
 179
 180 The field
 181 .I st_ctime
 182 is changed by writing or by setting inode information
 183 (i.e., owner, group, link count, mode, etc.).
 184 .PP
 185 The following POSIX macros are defined to check the file type using the
 186 .I st_mode
 187 field:
 188 .RS
 189 .TP 1.2i
 190 S_ISREG(m)
 191 is it a regular file?
 192 .TP
 193 S_ISDIR(m)
 194 directory?
 195 .TP
 196 S_ISCHR(m)
 197 character device?
 198 .TP
 199 S_ISBLK(m)
 200 block device?
 201 .TP
 202 S_ISFIFO(m)
 203 FIFO (named pipe)?
 204 .TP
 205 S_ISLNK(m)
 206 symbolic link? (Not in POSIX.1-1996.)
 207 .TP
 208 S_ISSOCK(m)
 209 socket? (Not in POSIX.1-1996.)
 210 .RE
 211 .PP
 212 The following flags are defined for the
 213 .I st_mode
 214 field:
 215 .TS
 216 l l l.
 217 S_IFMT  0170000 bitmask for the file type bitfields
 218 S_IFSOCK        0140000 socket
 219 S_IFLNK 0120000 symbolic link
 220 S_IFREG 0100000 regular file
 221 S_IFBLK 0060000 block device
 222 S_IFDIR 0040000 directory
 223 S_IFCHR 0020000 character device
 224 S_IFIFO 0010000 FIFO
 225 S_ISUID 0004000 set UID bit
 226 S_ISGID 0002000 set-group-ID bit (see below)
 227 S_ISVTX 0001000 sticky bit (see below)
 228 S_IRWXU 00700   mask for file owner permissions
 229 S_IRUSR 00400   owner has read permission
 230 S_IWUSR 00200   owner has write permission
 231 S_IXUSR 00100   owner has execute permission
 232 S_IRWXG 00070   mask for group permissions
 233 S_IRGRP 00040   group has read permission
 234 S_IWGRP 00020   group has write permission
 235 S_IXGRP 00010   group has execute permission
 236 S_IRWXO 00007   mask for permissions for others (not in group)
 237 S_IROTH 00004   others have read permission
 238 S_IWOTH 00002   others have write permission
 239 S_IXOTH 00001   others have execute permission
 240 .TE
 241 .P
 242 The set-group-ID bit (S_ISGID) has several special uses.
 243 For a directory it indicates that BSD semantics is to be used
 244 for that directory: files created there inherit their group ID from
 245 the directory, not from the effective group ID of the creating process,
 246 and directories created there will also get the S_ISGID bit set.
 247 For a file that does not have the group execution bit (S_IXGRP) set,
 248 the set-group-ID bit indicates mandatory file/record locking.
 249 .P
 250 The `sticky' bit (S_ISVTX) on a directory means that a file
 251 in that directory can be renamed or deleted only by the owner
 252 of the file, by the owner of the directory, and by a privileged
 253 process.
 254 .SH "RETURN VALUE"
 255 On success, zero is returned.
 256 On error, \-1 is returned, and
 257 .I errno
 258 is set appropriately.
 259 .SH ERRORS
 260 .TP
 261 .B EACCES
 262 Search permission is denied for one of the directories
 263 in the path prefix of
 264 .IR path .
 265 (See also
 266 .BR path_resolution (7).)
 267 .TP
 268 .B EBADF
 269 .I filedes
 270 is bad.
 271 .TP
 272 .B EFAULT
 273 Bad address.
 274 .TP
 275 .B ELOOP
 276 Too many symbolic links encountered while traversing the path.
 277 .TP
 278 .B ENAMETOOLONG
 279 File name too long.
 280 .TP
 281 .B ENOENT
 282 A component of the path
 283 .I path
 284 does not exist, or the path is an empty string.
 285 .TP
 286 .B ENOMEM
 287 Out of memory (i.e., kernel memory).
 288 .TP
 289 .B ENOTDIR
 290 A component of the path is not a directory.
 291 .SH "CONFORMING TO"
 292 These system calls conform to SVr4, 4.3BSD, POSIX.1-2001.
 293 .\" SVr4 documents additional
 294 .\" .BR fstat ()
 295 .\" error conditions EINTR, ENOLINK, and EOVERFLOW.  SVr4
 296 .\" documents additional
 297 .\" .BR stat ()
 298 .\" and
 299 .\" .BR lstat ()
 300 .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
 301
 302 Use of the
 303 .I st_blocks
 304 and
 305 .I st_blksize
 306 fields may be less portable.
 307 (They were introduced in BSD.
 308 The interpretation differs between systems,
 309 and possibly on a single system when NFS mounts are involved.)
 310 .LP
 311 POSIX does not describe the S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK,
 312 S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX bits, but instead demands the use of
 313 the macros S_ISDIR(), etc.
 314 The S_ISLNK and S_ISSOCK macros are not in
 315 POSIX.1-1996, but both are present in POSIX.1-2001;
 316 the former is from SVID 4, the latter from SUSv2.
 317 .LP
 318 Unix V7 (and later systems) had S_IREAD, S_IWRITE, S_IEXEC, where POSIX
 319 prescribes the synonyms S_IRUSR, S_IWUSR, S_IXUSR.
 320 .SS "Other Systems"
 321 Values that have been (or are) in use on various systems:
 322 .TS
 323 l l l l l.
 324 hex     name    ls      octal   description
 325 f000    S_IFMT          170000  mask for file type
 326 0000                    000000  SCO out-of-service inode, BSD unknown type
 327                                 SVID-v2 and XPG2 have both 0 and 0100000 for ordinary file
 328 1000    S_IFIFO p|      010000  FIFO (named pipe)
 329 2000    S_IFCHR c       020000  character special (V7)
 330 3000    S_IFMPC         030000  multiplexed character special (V7)
 331 4000    S_IFDIR d/      040000  directory (V7)
 332 5000    S_IFNAM         050000  XENIX named special file
 333                                 with two subtypes, distinguished by st_rdev values 1, 2:
 334 0001    S_INSEM s       000001  XENIX semaphore subtype of IFNAM
 335 0002    S_INSHD m       000002  XENIX shared data subtype of IFNAM
 336 6000    S_IFBLK b       060000  block special (V7)
 337 7000    S_IFMPB         070000  multiplexed block special (V7)
 338 8000    S_IFREG -       100000  regular (V7)
 339 9000    S_IFCMP         110000  VxFS compressed
 340 9000    S_IFNWK n       110000  network special (HP-UX)
 341 a000    S_IFLNK l@      120000  symbolic link (BSD)
 342 b000    S_IFSHAD                130000  Solaris shadow inode for ACL (not seen by userspace)
 343 c000    S_IFSOCK        s=      140000  socket (BSD; also "S_IFSOC" on VxFS)
 344 d000    S_IFDOOR        D>      150000  Solaris door
 345 e000    S_IFWHT w%      160000  BSD whiteout (not used for inode)
 346
 347 0200    S_ISVTX         001000  `sticky bit': save swapped text even after use (V7)
 348                                 reserved (SVID-v2)
 349                                 On non-directories: don't cache this file (SunOS)
 350                                 On directories: restricted deletion flag (SVID-v4.2)
 351 0400    S_ISGID         002000  set-group-ID on execution (V7)
 352                                 for directories: use BSD semantics for propagation of GID
 353 0400    S_ENFMT         002000  SysV file locking enforcement (shared with S_ISGID)
 354 0800    S_ISUID         004000  set-user-ID on execution (V7)
 355 0800    S_CDF           004000  directory is a context dependent file (HP-UX)
 356 .TE
 357
 358 A sticky command appeared in Version 32V AT&T UNIX.
 359 .SH NOTES
 360 .SS Linux Notes
 361 Since kernel 2.5.48, the
 362 .I stat
 363 structure supports nanosecond resolution for the three
 364 file timestamp fields.
 365 Glibc exposes the nanosecond component of each field using names either
 366 of the form
 367 .IR st_atim.tv_nsec ,
 368 if the _BSD_SOURCE or _SVID_SOURCE feature test macro is defined,
 369 or of the form
 370 .IR st_atimensec ,
 371 if neither of these macros is defined.
 372 On file systems that do not support sub-second timestamps,
 373 these nanosecond fields are returned with the value 0.
 374
 375 For most files under the
 376 .I /proc
 377 directory,
 378 .BR stat ()
 379 does not return the file size in the
 380 .I st_size
 381 field; instead the field is returned with the value 0.
 382 .SH EXAMPLE
 383 The following program calls
 384 .BR stat (2)
 385 and displays selected fields in the returned
 386 .I stat
 387 structure.
 388 .nf
 389
 390 #include <sys/types.h>
 391 #include <sys/stat.h>
 392 #include <time.h>
 393 #include <stdio.h>
 394 #include <stdlib.h>
 395
 396 int
 397 main(int argc, char *argv[])
 398 {
 399     struct stat sb;
 400
 401     if (argc != 2) {
 402         fprintf(stderr, "Usage: %s <pathname>\\n", argv[0]);
 403         exit(EXIT_FAILURE);
 404     }
 405
 406     if (stat(argv[1], &sb) == \-1) {
 407         perror("stat");
 408         exit(EXIT_SUCCESS);
 409     }
 410
 411     printf("File type:                ");
 412     switch (sb.st_mode & S_IFMT) {
 413     case S_IFBLK:  printf("block device\\n");            break;
 414     case S_IFCHR:  printf("character device\\n");        break;
 415     case S_IFDIR:  printf("directory\\n");               break;
 416     case S_IFIFO:  printf("FIFO/pipe\\n");               break;
 417     case S_IFLNK:  printf("symlink\\n");                 break;
 418     case S_IFREG:  printf("regular file\\n");            break;
 419     case S_IFSOCK: printf("socket\\n");                  break;
 420     default:       printf("unknown?\\n");                break;
 421     }
 422
 423     printf("I\-node number:            %ld\\n", (long) sb.st_ino);
 424
 425     printf("Mode:                     %lo (octal)\\n",
 426             (unsigned long) sb.st_mode);
 427
 428     printf("Link count:               %ld\\n", (long) sb.st_nlink);
 429     printf("Ownership:                UID=%ld   GID=%ld\\n",
 430             (long) sb.st_uid, (long) sb.st_gid);
 431
 432     printf("Preferred I/O block size: %ld bytes\\n",
 433             (long) sb.st_blksize);
 434     printf("File size:                %lld bytes\\n",
 435             (long long) sb.st_size);
 436     printf("Blocks allocated:         %lld\\n",
 437             (long long) sb.st_blocks);
 438
 439     printf("Last inode change:        %s", ctime(&sb.st_ctime));
 440     printf("Last file access:         %s", ctime(&sb.st_atime));
 441     printf("Last file modification:   %s", ctime(&sb.st_mtime));
 442
 443     exit(EXIT_SUCCESS);
 444 }
 445 .fi
 446 .SH "SEE ALSO"
 447 .BR access (2),
 448 .BR chmod (2),
 449 .BR chown (2),
 450 .BR fstatat (2),
 451 .BR readlink (2),
 452 .BR utime (2),
 453 .BR capabilities (7)