1stat(2) System Calls Manual stat(2)
2
6 stat, fstat, lstat, fstatat - get file status
7
9 Standard C library (libc, -lc)
10
12 #include <sys/stat.h>
13 int stat(const char *restrict pathname,
15 struct stat *restrict statbuf);
16 int fstat(int fd, struct stat *statbuf);
17 int lstat(const char *restrict pathname,
18 struct stat *restrict statbuf);
19 #include <fcntl.h> /* Definition of AT_* constants */
21 #include <sys/stat.h>
22 int fstatat(int dirfd, const char *restrict pathname,
24 struct stat *restrict statbuf, int flags);
25 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
27 lstat():
29 /* Since glibc 2.20 */ _DEFAULT_SOURCE
30 || _XOPEN_SOURCE >= 500
31 || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
32 || /* glibc 2.19 and earlier */ _BSD_SOURCE
33 fstatat():
35 Since glibc 2.10:
36 _POSIX_C_SOURCE >= 200809L
37 Before glibc 2.10:
38 _ATFILE_SOURCE
39
41 These functions return information about a file, in the buffer pointed
42 to by statbuf. No permissions are required on the file itself, but—in
43 the case of stat(), fstatat(), and lstat()—execute (search) permission
44 is required on all of the directories in pathname that lead to the
45 file.
46 stat() and fstatat() retrieve information about the file pointed to by
48 pathname; the differences for fstatat() are described below.
49 lstat() is identical to stat(), except that if pathname is a symbolic
51 link, then it returns information about the link itself, not the file
52 that the link refers to.
53 fstat() is identical to stat(), except that the file about which infor‐
55 mation is to be retrieved is specified by the file descriptor fd.
56 The stat structure
58 All of these system calls return a stat structure (see stat(3type)).
59 Note: for performance and simplicity reasons, different fields in the
61 stat structure may contain state information from different moments
62 during the execution of the system call. For example, if st_mode or
63 st_uid is changed by another process by calling chmod(2) or chown(2),
64 stat() might return the old st_mode together with the new st_uid, or
65 the old st_uid together with the new st_mode.
66 fstatat()
68 The fstatat() system call is a more general interface for accessing
69 file information which can still provide exactly the behavior of each
70 of stat(), lstat(), and fstat().
71 If the pathname given in pathname is relative, then it is interpreted
73 relative to the directory referred to by the file descriptor dirfd
74 (rather than relative to the current working directory of the calling
75 process, as is done by stat() and lstat() for a relative pathname).
76 If pathname is relative and dirfd is the special value AT_FDCWD, then
78 pathname is interpreted relative to the current working directory of
79 the calling process (like stat() and lstat()).
80 If pathname is absolute, then dirfd is ignored.
82 flags can either be 0, or include one or more of the following flags
84 ORed:
85 AT_EMPTY_PATH (since Linux 2.6.39)
87 If pathname is an empty string, operate on the file referred to
88 by dirfd (which may have been obtained using the open(2) O_PATH
89 flag). In this case, dirfd can refer to any type of file, not
90 just a directory, and the behavior of fstatat() is similar to
91 that of fstat(). If dirfd is AT_FDCWD, the call operates on the
92 current working directory. This flag is Linux-specific; define
93 _GNU_SOURCE to obtain its definition.
94 AT_NO_AUTOMOUNT (since Linux 2.6.38)
96 Don't automount the terminal ("basename") component of pathname.
97 Since Linux 3.1 this flag is ignored. Since Linux 4.11 this
98 flag is implied.
99 AT_SYMLINK_NOFOLLOW
101 If pathname is a symbolic link, do not dereference it: instead
102 return information about the link itself, like lstat(). (By de‐
103 fault, fstatat() dereferences symbolic links, like stat().)
104 See openat(2) for an explanation of the need for fstatat().
106
108 On success, zero is returned. On error, -1 is returned, and errno is
109 set to indicate the error.
110
112 EACCES Search permission is denied for one of the directories in the
113 path prefix of pathname. (See also path_resolution(7).)
114 EBADF fd is not a valid open file descriptor.
116 EBADF (fstatat()) pathname is relative but dirfd is neither AT_FDCWD
118 nor a valid file descriptor.
119 EFAULT Bad address.
121 EINVAL (fstatat()) Invalid flag specified in flags.
123 ELOOP Too many symbolic links encountered while traversing the path.
125 ENAMETOOLONG
127 pathname is too long.
128 ENOENT A component of pathname does not exist or is a dangling symbolic
130 link.
131 ENOENT pathname is an empty string and AT_EMPTY_PATH was not specified
133 in flags.
134 ENOMEM Out of memory (i.e., kernel memory).
136 ENOTDIR
138 A component of the path prefix of pathname is not a directory.
139 ENOTDIR
141 (fstatat()) pathname is relative and dirfd is a file descriptor
142 referring to a file other than a directory.
143 EOVERFLOW
145 pathname or fd refers to a file whose size, inode number, or
146 number of blocks cannot be represented in, respectively, the
147 types off_t, ino_t, or blkcnt_t. This error can occur when, for
148 example, an application compiled on a 32-bit platform without
149 -D_FILE_OFFSET_BITS=64 calls stat() on a file whose size exceeds
150 (1<<31)-1 bytes.
151
153 POSIX.1-2008.
154
156 stat()
157 fstat()
158 lstat()
159 SVr4, 4.3BSD, POSIX.1-2001.
160 fstatat()
162 POSIX.1-2008. Linux 2.6.16, glibc 2.4.
163 According to POSIX.1-2001, lstat() on a symbolic link need return valid
165 information only in the st_size field and the file type of the st_mode
166 field of the stat structure. POSIX.1-2008 tightens the specification,
167 requiring lstat() to return valid information in all fields except the
168 mode bits in st_mode.
169 Use of the st_blocks and st_blksize fields may be less portable. (They
171 were introduced in BSD. The interpretation differs between systems,
172 and possibly on a single system when NFS mounts are involved.)
173 C library/kernel differences
175 Over time, increases in the size of the stat structure have led to
176 three successive versions of stat(): sys_stat() (slot __NR_oldstat),
177 sys_newstat() (slot __NR_stat), and sys_stat64() (slot __NR_stat64) on
178 32-bit platforms such as i386. The first two versions were already
179 present in Linux 1.0 (albeit with different names); the last was added
180 in Linux 2.4. Similar remarks apply for fstat() and lstat().
181 The kernel-internal versions of the stat structure dealt with by the
183 different versions are, respectively:
184 __old_kernel_stat
186 The original structure, with rather narrow fields, and no pad‐
187 ding.
188 stat Larger st_ino field and padding added to various parts of the
190 structure to allow for future expansion.
191 stat64 Even larger st_ino field, larger st_uid and st_gid fields to ac‐
193 commodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits,
194 and various other enlarged fields and further padding in the
195 structure. (Various padding bytes were eventually consumed in
196 Linux 2.6, with the advent of 32-bit device IDs and nanosecond
197 components for the timestamp fields.)
198 The glibc stat() wrapper function hides these details from applica‐
200 tions, invoking the most recent version of the system call provided by
201 the kernel, and repacking the returned information if required for old
202 binaries.
203 On modern 64-bit systems, life is simpler: there is a single stat()
205 system call and the kernel deals with a stat structure that contains
206 fields of a sufficient size.
207 The underlying system call employed by the glibc fstatat() wrapper
209 function is actually called fstatat64() or, on some architectures,
210 newfstatat().
211
213 The following program calls lstat() and displays selected fields in the
214 returned stat structure.
215 #include <stdint.h>
217 #include <stdio.h>
218 #include <stdlib.h>
219 #include <sys/stat.h>
220 #include <sys/sysmacros.h>
221 #include <time.h>
222 int
224 main(int argc, char *argv[])
225 {
226 struct stat sb;
227 if (argc != 2) {
229 fprintf(stderr, "Usage: %s <pathname>\n", argv[0]);
230 exit(EXIT_FAILURE);
231 }
232 if (lstat(argv[1], &sb) == -1) {
234 perror("lstat");
235 exit(EXIT_FAILURE);
236 }
237 printf("ID of containing device: [%x,%x]\n",
239 major(sb.st_dev),
240 minor(sb.st_dev));
241 printf("File type: ");
243 switch (sb.st_mode & S_IFMT) {
245 case S_IFBLK: printf("block device\n"); break;
246 case S_IFCHR: printf("character device\n"); break;
247 case S_IFDIR: printf("directory\n"); break;
248 case S_IFIFO: printf("FIFO/pipe\n"); break;
249 case S_IFLNK: printf("symlink\n"); break;
250 case S_IFREG: printf("regular file\n"); break;
251 case S_IFSOCK: printf("socket\n"); break;
252 default: printf("unknown?\n"); break;
253 }
254 printf("I-node number: %ju\n", (uintmax_t) sb.st_ino);
256 printf("Mode: %jo (octal)\n",
258 (uintmax_t) sb.st_mode);
259 printf("Link count: %ju\n", (uintmax_t) sb.st_nlink);
261 printf("Ownership: UID=%ju GID=%ju\n",
262 (uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid);
263 printf("Preferred I/O block size: %jd bytes\n",
265 (intmax_t) sb.st_blksize);
266 printf("File size: %jd bytes\n",
267 (intmax_t) sb.st_size);
268 printf("Blocks allocated: %jd\n",
269 (intmax_t) sb.st_blocks);
270 printf("Last status change: %s", ctime(&sb.st_ctime));
272 printf("Last file access: %s", ctime(&sb.st_atime));
273 printf("Last file modification: %s", ctime(&sb.st_mtime));
274 exit(EXIT_SUCCESS);
276 }
277
279 ls(1), stat(1), access(2), chmod(2), chown(2), readlink(2), statx(2),
280 utime(2), stat(3type), capabilities(7), inode(7), symlink(7)
281Linux man-pages 6.04 2023-03-30 stat(2)