1STAT(2)                    Linux Programmer's Manual                   STAT(2)
2
3
4

NAME

6       stat, fstat, lstat - get file status
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/stat.h>
11       #include <unistd.h>
12
13       int stat(const char *path, struct stat *buf);
14       int fstat(int fd, struct stat *buf);
15       int lstat(const char *path, struct stat *buf);
16
17   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
18
19       lstat():
20           _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
21           _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
22           || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
23

DESCRIPTION

25       These functions return information about a file.   No  permissions  are
26       required  on  the  file itself, but—in the case of stat() and lstat() —
27       execute (search) permission is required on all of  the  directories  in
28       path that lead to the file.
29
30       stat() stats the file pointed to by path and fills in buf.
31
32       lstat() is identical to stat(), except that if path is a symbolic link,
33       then the link itself is stat-ed, not the file that it refers to.
34
35       fstat() is identical to stat(), except that the file to be  stat-ed  is
36       specified by the file descriptor fd.
37
38       All  of  these system calls return a stat structure, which contains the
39       following fields:
40
41           struct stat {
42               dev_t     st_dev;     /* ID of device containing file */
43               ino_t     st_ino;     /* inode number */
44               mode_t    st_mode;    /* protection */
45               nlink_t   st_nlink;   /* number of hard links */
46               uid_t     st_uid;     /* user ID of owner */
47               gid_t     st_gid;     /* group ID of owner */
48               dev_t     st_rdev;    /* device ID (if special file) */
49               off_t     st_size;    /* total size, in bytes */
50               blksize_t st_blksize; /* blocksize for file system I/O */
51               blkcnt_t  st_blocks;  /* number of 512B blocks allocated */
52               time_t    st_atime;   /* time of last access */
53               time_t    st_mtime;   /* time of last modification */
54               time_t    st_ctime;   /* time of last status change */
55           };
56
57       The st_dev field describes the device on which this file resides.  (The
58       major(3)  and  minor(3) macros may be useful to decompose the device ID
59       in this field.)
60
61       The st_rdev field describes the device that this  file  (inode)  repre‐
62       sents.
63
64       The  st_size  field gives the size of the file (if it is a regular file
65       or a symbolic link) in bytes.  The size  of  a  symbolic  link  is  the
66       length of the pathname it contains, without a terminating null byte.
67
68       The  st_blocks  field  indicates  the number of blocks allocated to the
69       file, 512-byte units.  (This may be smaller than st_size/512  when  the
70       file has holes.)
71
72       The st_blksize field gives the "preferred" blocksize for efficient file
73       system I/O.  (Writing to a file in smaller chunks may cause an  ineffi‐
74       cient read-modify-rewrite.)
75
76       Not  all  of  the  Linux file systems implement all of the time fields.
77       Some file system types allow mounting in such a way  that  file  and/or
78       directory  accesses do not cause an update of the st_atime field.  (See
79       noatime, nodiratime, and relatime in mount(8), and related  information
80       in mount(2).)  In addition, st_atime is not updated if a file is opened
81       with the O_NOATIME; see open(2).
82
83       The field st_atime  is  changed  by  file  accesses,  for  example,  by
84       execve(2),  mknod(2),  pipe(2), utime(2) and read(2) (of more than zero
85       bytes).  Other routines, like mmap(2), may or may not update st_atime.
86
87       The field st_mtime is changed by file modifications,  for  example,  by
88       mknod(2), truncate(2), utime(2) and write(2) (of more than zero bytes).
89       Moreover, st_mtime of a directory is changed by the creation  or  dele‐
90       tion of files in that directory.  The st_mtime field is not changed for
91       changes in owner, group, hard link count, or mode.
92
93       The field st_ctime is changed by writing or by setting  inode  informa‐
94       tion (i.e., owner, group, link count, mode, etc.).
95
96       The following POSIX macros are defined to check the file type using the
97       st_mode field:
98
99           S_ISREG(m)  is it a regular file?
100
101           S_ISDIR(m)  directory?
102
103           S_ISCHR(m)  character device?
104
105           S_ISBLK(m)  block device?
106
107           S_ISFIFO(m) FIFO (named pipe)?
108
109           S_ISLNK(m)  symbolic link?  (Not in POSIX.1-1996.)
110
111           S_ISSOCK(m) socket?  (Not in POSIX.1-1996.)
112
113       The following flags are defined for the st_mode field:
114
115           S_IFMT     0170000   bit mask for the file type bit fields
116           S_IFSOCK   0140000   socket
117           S_IFLNK    0120000   symbolic link
118           S_IFREG    0100000   regular file
119           S_IFBLK    0060000   block device
120           S_IFDIR    0040000   directory
121           S_IFCHR    0020000   character device
122           S_IFIFO    0010000   FIFO
123           S_ISUID    0004000   set-user-ID bit
124           S_ISGID    0002000   set-group-ID bit (see below)
125           S_ISVTX    0001000   sticky bit (see below)
126           S_IRWXU    00700     mask for file owner permissions
127           S_IRUSR    00400     owner has read permission
128           S_IWUSR    00200     owner has write permission
129           S_IXUSR    00100     owner has execute permission
130           S_IRWXG    00070     mask for group permissions
131           S_IRGRP    00040     group has read permission
132
133           S_IWGRP    00020     group has write permission
134           S_IXGRP    00010     group has execute permission
135           S_IRWXO    00007     mask for permissions for others (not in group)
136           S_IROTH    00004     others have read permission
137           S_IWOTH    00002     others have write permission
138           S_IXOTH    00001     others have execute permission
139
140       The set-group-ID bit (S_ISGID) has several special uses.  For a  direc‐
141       tory  it indicates that BSD semantics is to be used for that directory:
142       files created there inherit their group ID from the directory, not from
143       the effective group ID of the creating process, and directories created
144       there will also get the S_ISGID bit set.  For a file that does not have
145       the  group  execution bit (S_IXGRP) set, the set-group-ID bit indicates
146       mandatory file/record locking.
147
148       The sticky bit (S_ISVTX) on a directory  means  that  a  file  in  that
149       directory  can  be renamed or deleted only by the owner of the file, by
150       the owner of the directory, and by a privileged process.
151

RETURN VALUE

153       On success, zero is returned.  On error, -1 is returned, and  errno  is
154       set appropriately.
155

ERRORS

157       EACCES Search  permission  is  denied for one of the directories in the
158              path prefix of path.  (See also path_resolution(7).)
159
160       EBADF  fd is bad.
161
162       EFAULT Bad address.
163
164       ELOOP  Too many symbolic links encountered while traversing the path.
165
166       ENAMETOOLONG
167              path is too long.
168
169       ENOENT A component of path does not exist, or path is an empty string.
170
171       ENOMEM Out of memory (i.e., kernel memory).
172
173       ENOTDIR
174              A component of the path prefix of path is not a directory.
175
176       EOVERFLOW
177              path or fd refers to a file whose size, inode number, or  number
178              of  blocks  cannot  be  represented  in, respectively, the types
179              off_t, ino_t, or blkcnt_t.  This error can occur when, for exam‐
180              ple,  an  application  compiled  on  a  32-bit  platform without
181              -D_FILE_OFFSET_BITS=64 calls stat() on a file whose size exceeds
182              (1<<31)-1 bytes.
183

CONFORMING TO

185       These system calls conform to SVr4, 4.3BSD, POSIX.1-2001.
186
187       According to POSIX.1-2001, lstat() on a symbolic link need return valid
188       information only in the st_size field and the  file-type  component  of
189       the  st_mode  field  of  the  stat structure.  POSIX.-2008 tightens the
190       specification, requiring lstat() to return  valid  information  in  all
191       fields except the permission bits in st_mode.
192
193       Use of the st_blocks and st_blksize fields may be less portable.  (They
194       were introduced in BSD.  The interpretation  differs  between  systems,
195       and  possibly on a single system when NFS mounts are involved.)  If you
196       need to obtain the definition of the blkcnt_t or blksize_t  types  from
197       <sys/stat.h>,  then  define _XOPEN_SOURCE with the value 500 or greater
198       (before including any header files).
199
200       POSIX.1-1990 did not describe the S_IFMT, S_IFSOCK,  S_IFLNK,  S_IFREG,
201       S_IFBLK,  S_IFDIR,  S_IFCHR,  S_IFIFO,  S_ISVTX  constants, but instead
202       demanded the use of the macros S_ISDIR(), etc.  The S_IF* constants are
203       present in POSIX.1-2001 and later.
204
205       The  S_ISLNK()  and S_ISSOCK() macros are not in POSIX.1-1996, but both
206       are present in POSIX.1-2001; the former is from SVID 4, the latter from
207       SUSv2.
208
209       UNIX V7 (and later systems) had S_IREAD, S_IWRITE, S_IEXEC, where POSIX
210       prescribes the synonyms S_IRUSR, S_IWUSR, S_IXUSR.
211
212   Other systems
213       Values that have been (or are) in use on various systems:
214
215       hex    name       ls   octal    description
216       f000   S_IFMT          170000   mask for file type
217       0000                   000000   SCO out-of-service inode; BSD
218                                       unknown type; SVID-v2 and XPG2 have
219                                       both 0 and 0100000 for ordinary file
220       1000   S_IFIFO    p|   010000   FIFO (named pipe)
221       2000   S_IFCHR    c    020000   character special (V7)
222       3000   S_IFMPC         030000   multiplexed character special (V7)
223       4000   S_IFDIR    d/   040000   directory (V7)
224       5000   S_IFNAM         050000   XENIX named special file with two
225                                       subtypes, distinguished by st_rdev
226                                       values 1, 2
227       0001   S_INSEM    s    000001   XENIX semaphore subtype of IFNAM
228       0002   S_INSHD    m    000002   XENIX shared data subtype of IFNAM
229       6000   S_IFBLK    b    060000   block special (V7)
230       7000   S_IFMPB         070000   multiplexed block special (V7)
231       8000   S_IFREG    -    100000   regular (V7)
232       9000   S_IFCMP         110000   VxFS compressed
233       9000   S_IFNWK    n    110000   network special (HP-UX)
234       a000   S_IFLNK    l@   120000   symbolic link (BSD)
235       b000   S_IFSHAD        130000   Solaris shadow inode for ACL (not
236                                       seen by user space)
237       c000   S_IFSOCK   s=   140000   socket (BSD; also "S_IFSOC" on VxFS)
238       d000   S_IFDOOR   D>   150000   Solaris door
239       e000   S_IFWHT    w%   160000   BSD whiteout (not used for inode)
240       0200   S_ISVTX         001000   sticky bit: save swapped text even
241                                       after use (V7)
242                                       reserved (SVID-v2)
243                                       On nondirectories: don't cache this
244                                       file (SunOS)
245                                       On directories: restricted deletion
246                                       flag (SVID-v4.2)
247       0400   S_ISGID         002000   set-group-ID on execution (V7)
248                                       for directories: use BSD semantics
249                                       for propagation of GID
250       0400   S_ENFMT         002000   System V file locking enforcement
251                                       (shared with S_ISGID)
252       0800   S_ISUID         004000   set-user-ID on execution (V7)
253       0800   S_CDF           004000   directory is a context dependent
254                                       file (HP-UX)
255
256       A sticky command appeared in Version 32V AT&T UNIX.
257

NOTES

259       Since  kernel 2.5.48, the stat structure supports nanosecond resolution
260       for the three file timestamp fields.  Glibc exposes the nanosecond com‐
261       ponent  of  each  field  using names of the form st_atim.tv_nsec if the
262       _BSD_SOURCE or _SVID_SOURCE  feature  test  macro  is  defined.   These
263       fields  are specified in POSIX.1-2008, and, starting with version 2.12,
264       glibc also exposes these field names if _POSIX_C_SOURCE is defined with
265       the  value  200809L  or  greater,  or _XOPEN_SOURCE is defined with the
266       value 700 or  greater.   If  none  of  the  aforementioned  macros  are
267       defined,  then the nanosecond values are exposed with names of the form
268       st_atimensec.  On file systems that  do  not  support  subsecond  time‐
269       stamps, the nanosecond fields are returned with the value 0.
270
271       On  Linux,  lstat()  will  generally  not  trigger  automounter action,
272       whereas stat() will (but see fstatat(2)).
273
274       For most files under the /proc directory, stat() does  not  return  the
275       file  size in the st_size field; instead the field is returned with the
276       value 0.
277
278   Underlying kernel interface
279       Over time, increases in the size of the  stat  structure  have  led  to
280       three  successive  versions  of stat(): sys_stat() (slot __NR_oldstat),
281       sys_newstat() (slot __NR_stat), and sys_stat64() (new  in  kernel  2.4;
282       slot  __NR_stat64).   The  glibc  stat()  wrapper  function hides these
283       details from applications, invoking the most recent version of the sys‐
284       tem call provided by the kernel, and repacking the returned information
285       if required for old binaries.  Similar remarks apply  for  fstat()  and
286       lstat().
287

EXAMPLE

289       The  following program calls stat() and displays selected fields in the
290       returned stat structure.
291
292       #include <sys/types.h>
293       #include <sys/stat.h>
294       #include <time.h>
295       #include <stdio.h>
296       #include <stdlib.h>
297
298       int
299       main(int argc, char *argv[])
300       {
301           struct stat sb;
302
303           if (argc != 2) {
304               fprintf(stderr, "Usage: %s <pathname>\n", argv[0]);
305               exit(EXIT_FAILURE);
306           }
307
308           if (stat(argv[1], &sb) == -1) {
309               perror("stat");
310               exit(EXIT_FAILURE);
311           }
312
313           printf("File type:                ");
314
315           switch (sb.st_mode & S_IFMT) {
316           case S_IFBLK:  printf("block device\n");            break;
317           case S_IFCHR:  printf("character device\n");        break;
318           case S_IFDIR:  printf("directory\n");               break;
319           case S_IFIFO:  printf("FIFO/pipe\n");               break;
320           case S_IFLNK:  printf("symlink\n");                 break;
321           case S_IFREG:  printf("regular file\n");            break;
322           case S_IFSOCK: printf("socket\n");                  break;
323           default:       printf("unknown?\n");                break;
324           }
325
326           printf("I-node number:            %ld\n", (long) sb.st_ino);
327
328           printf("Mode:                     %lo (octal)\n",
329                   (unsigned long) sb.st_mode);
330
331           printf("Link count:               %ld\n", (long) sb.st_nlink);
332           printf("Ownership:                UID=%ld   GID=%ld\n",
333                   (long) sb.st_uid, (long) sb.st_gid);
334
335           printf("Preferred I/O block size: %ld bytes\n",
336                   (long) sb.st_blksize);
337           printf("File size:                %lld bytes\n",
338                   (long long) sb.st_size);
339           printf("Blocks allocated:         %lld\n",
340                   (long long) sb.st_blocks);
341
342           printf("Last status change:       %s", ctime(&sb.st_ctime));
343           printf("Last file access:         %s", ctime(&sb.st_atime));
344           printf("Last file modification:   %s", ctime(&sb.st_mtime));
345
346           exit(EXIT_SUCCESS);
347       }
348

SEE ALSO

350       access(2), chmod(2), chown(2), fstatat(2), readlink(2), utime(2), capa‐
351       bilities(7), symlink(7)
352

COLOPHON

354       This  page  is  part of release 3.53 of the Linux man-pages project.  A
355       description of the project, and information about reporting  bugs,  can
356       be found at http://www.kernel.org/doc/man-pages/.
357
358
359
360Linux                             2012-11-11                           STAT(2)
Impressum