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(): _BSD_SOURCE || _XOPEN_SOURCE >= 500
20

DESCRIPTION

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

RETURN VALUE

150       On  success,  zero is returned.  On error, -1 is returned, and errno is
151       set appropriately.
152

ERRORS

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

CONFORMING TO

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

NOTES

243       Since  kernel 2.5.48, the stat structure supports nanosecond resolution
244       for the three file timestamp fields.  Glibc exposes the nanosecond com‐
245       ponent of each field using names either of the form st_atim.tv_nsec, if
246       the _BSD_SOURCE or _SVID_SOURCE feature test macro is  defined,  or  of
247       the  form st_atimensec, if neither of these macros is defined.  On file
248       systems that do not  support  subsecond  timestamps,  these  nanosecond
249       fields are returned with the value 0.
250
251       On  Linux,  lstat()  will  generally  not  trigger  automounter action,
252       whereas stat() will.
253
254       For most files under the /proc directory, stat() does  not  return  the
255       file  size in the st_size field; instead the field is returned with the
256       value 0.
257
258   Underlying kernel interface
259       Over time, increases in the size of the  stat  structure  have  led  to
260       three  successive  versions  of stat(): sys_stat() (slot __NR_oldstat),
261       sys_newstat() (slot __NR_stat), and sys_stat64() (new  in  kernel  2.4;
262       slot  __NR_stat64).   The  glibc  stat()  wrapper  function hides these
263       details from applications, invoking the most recent version of the sys‐
264       tem call provided by the kernel, and repacking the returned information
265       if required for old binaries.  Similar remarks apply  for  fstat()  and
266       lstat().
267

EXAMPLE

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

SEE ALSO

330       access(2), chmod(2), chown(2), fstatat(2), readlink(2), utime(2), capa‐
331       bilities(7), symlink(7)
332

COLOPHON

334       This  page  is  part of release 3.25 of the Linux man-pages project.  A
335       description of the project, and information about reporting  bugs,  can
336       be found at http://www.kernel.org/doc/man-pages/.
337
338
339
340Linux                             2009-09-30                           STAT(2)
Impressum