1STAT(2) System Calls Manual STAT(2)
2
6 stat, fstat - get file status
7
9 #include <sys/types.h>
10 #include <sys/stat.h>
11 stat(name, buf)
13 char *name;
14 struct stat *buf;
15 fstat(fildes, buf)
17 struct stat *buf;
18
20 Stat obtains detailed information about a named file. Fstat obtains
21 the same information about an open file known by the file descriptor
22 from a successful open, creat, dup or pipe(2) call.
23 Name points to a null-terminated string naming a file; buf is the
25 address of a buffer into which information is placed concerning the
26 file. It is unnecessary to have any permissions at all with respect to
27 the file, but all directories leading to the file must be searchable.
28 The layout of the structure pointed to by buf as defined in <stat.h> is
29 given below. St_mode is encoded according to the `#define' statements.
30 /* Copyright (C) 1991, 1992, 1995-2007, 2009, 2010, 2012
32 Free Software Foundation, Inc.
33 This file is part of the GNU C Library.
34 The GNU C Library is free software; you can redistribute it and/or
36 modify it under the terms of the GNU Lesser General Public
37 License as published by the Free Software Foundation; either
38 version 2.1 of the License, or (at your option) any later version.
39 The GNU C Library is distributed in the hope that it will be useful,
41 but WITHOUT ANY WARRANTY; without even the implied warranty of
42 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
43 Lesser General Public License for more details.
44 You should have received a copy of the GNU Lesser General Public
46 License along with the GNU C Library; if not, see
47 <http://www.gnu.org/licenses/>. */
48 /*
50 * POSIX Standard: 5.6 File Characteristics <sys/stat.h>
51 */
52 #ifndef _SYS_STAT_H
54 #define _SYS_STAT_H 1
55 #include <features.h>
57 #include <bits/types.h> /* For __mode_t and __dev_t. */
59 #if defined __USE_XOPEN || defined __USE_XOPEN2K || defined __USE_MISC || defined __USE_ATFILE
61 # if defined __USE_XOPEN || defined __USE_XOPEN2K
62 # define __need_time_t
63 # endif
64 # if defined __USE_MISC || defined __USE_ATFILE
65 # define __need_timespec
66 # endif
67 # include <time.h> /* For time_t resp. timespec. */
68 #endif
69 #if defined __USE_XOPEN || defined __USE_XOPEN2K
71 /* The Single Unix specification says that some more types are
72 available here. */
73 # ifndef __dev_t_defined
74 typedef __dev_t dev_t;
75 # define __dev_t_defined
76 # endif
77 # ifndef __gid_t_defined
79 typedef __gid_t gid_t;
80 # define __gid_t_defined
81 # endif
82 # ifndef __ino_t_defined
84 # ifndef __USE_FILE_OFFSET64
85 typedef __ino_t ino_t;
86 # else
87 typedef __ino64_t ino_t;
88 # endif
89 # define __ino_t_defined
90 # endif
91 # ifndef __mode_t_defined
93 typedef __mode_t mode_t;
94 # define __mode_t_defined
95 # endif
96 # ifndef __nlink_t_defined
98 typedef __nlink_t nlink_t;
99 # define __nlink_t_defined
100 # endif
101 # ifndef __off_t_defined
103 # ifndef __USE_FILE_OFFSET64
104 typedef __off_t off_t;
105 # else
106 typedef __off64_t off_t;
107 # endif
108 # define __off_t_defined
109 # endif
110 # ifndef __uid_t_defined
112 typedef __uid_t uid_t;
113 # define __uid_t_defined
114 # endif
115 #endif /* X/Open */
116 #ifdef __USE_UNIX98
118 # ifndef __blkcnt_t_defined
119 # ifndef __USE_FILE_OFFSET64
120 typedef __blkcnt_t blkcnt_t;
121 # else
122 typedef __blkcnt64_t blkcnt_t;
123 # endif
124 # define __blkcnt_t_defined
125 # endif
126 # ifndef __blksize_t_defined
128 typedef __blksize_t blksize_t;
129 # define __blksize_t_defined
130 # endif
131 #endif /* Unix98 */
132 __BEGIN_DECLS
134 #include <bits/stat.h>
136 #if defined __USE_BSD || defined __USE_MISC || defined __USE_XOPEN
138 # define S_IFMT __S_IFMT
139 # define S_IFDIR __S_IFDIR
140 # define S_IFCHR __S_IFCHR
141 # define S_IFBLK __S_IFBLK
142 # define S_IFREG __S_IFREG
143 # ifdef __S_IFIFO
144 # define S_IFIFO __S_IFIFO
145 # endif
146 # ifdef __S_IFLNK
147 # define S_IFLNK __S_IFLNK
148 # endif
149 # if (defined __USE_BSD || defined __USE_MISC || defined __USE_UNIX98) && defined __S_IFSOCK
150 # define S_IFSOCK __S_IFSOCK
151 # endif
152 #endif
153 /* Test macros for file types. */
155 #define __S_ISTYPE(mode, mask) (((mode) & __S_IFMT) == (mask))
157 #define S_ISDIR(mode) __S_ISTYPE((mode), __S_IFDIR)
159 #define S_ISCHR(mode) __S_ISTYPE((mode), __S_IFCHR)
160 #define S_ISBLK(mode) __S_ISTYPE((mode), __S_IFBLK)
161 #define S_ISREG(mode) __S_ISTYPE((mode), __S_IFREG)
162 #ifdef __S_IFIFO
163 # define S_ISFIFO(mode) __S_ISTYPE((mode), __S_IFIFO)
164 #endif
165 #ifdef __S_IFLNK
166 # define S_ISLNK(mode) __S_ISTYPE((mode), __S_IFLNK)
167 #endif
168 #if defined __USE_BSD && !defined __S_IFLNK
170 # define S_ISLNK(mode) 0
171 #endif
172 #if (defined __USE_BSD || defined __USE_UNIX98 || defined __USE_XOPEN2K) && defined __S_IFSOCK
174 # define S_ISSOCK(mode) __S_ISTYPE((mode), __S_IFSOCK)
175 #elif defined __USE_XOPEN2K
176 # define S_ISSOCK(mode) 0
177 #endif
178 /* These are from POSIX.1b. If the objects are not implemented using separate
180 distinct file types, the macros always will evaluate to zero. Unlike the
181 other S_* macros the following three take a pointer to a `struct stat'
182 object as the argument. */
183 #ifdef __USE_POSIX199309
184 # define S_TYPEISMQ(buf) __S_TYPEISMQ(buf)
185 # define S_TYPEISSEM(buf) __S_TYPEISSEM(buf)
186 # define S_TYPEISSHM(buf) __S_TYPEISSHM(buf)
187 #endif
188 /* Protection bits. */
191 #define S_ISUID __S_ISUID /* Set user ID on execution. */
193 #define S_ISGID __S_ISGID /* Set group ID on execution. */
194 #if defined __USE_BSD || defined __USE_MISC || defined __USE_XOPEN
196 /* Save swapped text after use (sticky bit). This is pretty well obsolete. */
197 # define S_ISVTX __S_ISVTX
198 #endif
199 #define S_IRUSR __S_IREAD /* Read by owner. */
201 #define S_IWUSR __S_IWRITE /* Write by owner. */
202 #define S_IXUSR __S_IEXEC /* Execute by owner. */
203 /* Read, write, and execute by owner. */
204 #define S_IRWXU (__S_IREAD|__S_IWRITE|__S_IEXEC)
205 #if defined __USE_MISC && defined __USE_BSD
207 # define S_IREAD S_IRUSR
208 # define S_IWRITE S_IWUSR
209 # define S_IEXEC S_IXUSR
210 #endif
211 #define S_IRGRP (S_IRUSR >> 3) /* Read by group. */
213 #define S_IWGRP (S_IWUSR >> 3) /* Write by group. */
214 #define S_IXGRP (S_IXUSR >> 3) /* Execute by group. */
215 /* Read, write, and execute by group. */
216 #define S_IRWXG (S_IRWXU >> 3)
217 #define S_IROTH (S_IRGRP >> 3) /* Read by others. */
219 #define S_IWOTH (S_IWGRP >> 3) /* Write by others. */
220 #define S_IXOTH (S_IXGRP >> 3) /* Execute by others. */
221 /* Read, write, and execute by others. */
222 #define S_IRWXO (S_IRWXG >> 3)
223 #ifdef __USE_BSD
226 /* Macros for common mode bit masks. */
227 # define ACCESSPERMS (S_IRWXU|S_IRWXG|S_IRWXO) /* 0777 */
228 # define ALLPERMS (S_ISUID|S_ISGID|S_ISVTX|S_IRWXU|S_IRWXG|S_IRWXO)/* 07777 */
229 # define DEFFILEMODE (S_IRUSR|S_IWUSR|S_IRGRP|S_IWGRP|S_IROTH|S_IWOTH)/* 0666*/
230 # define S_BLKSIZE 512 /* Block size for `st_blocks'. */
232 #endif
233 #ifndef __USE_FILE_OFFSET64
236 /* Get file attributes for FILE and put them in BUF. */
237 extern int stat (const char *__restrict __file,
238 struct stat *__restrict __buf) __THROW __nonnull ((1, 2));
239 /* Get file attributes for the file, device, pipe, or socket
241 that file descriptor FD is open on and put them in BUF. */
242 extern int fstat (int __fd, struct stat *__buf) __THROW __nonnull ((2));
243 #else
244 # ifdef __REDIRECT_NTH
245 extern int __REDIRECT_NTH (stat, (const char *__restrict __file,
246 struct stat *__restrict __buf), stat64)
247 __nonnull ((1, 2));
248 extern int __REDIRECT_NTH (fstat, (int __fd, struct stat *__buf), fstat64)
249 __nonnull ((2));
250 # else
251 # define stat stat64
252 # define fstat fstat64
253 # endif
254 #endif
255 #ifdef __USE_LARGEFILE64
256 extern int stat64 (const char *__restrict __file,
257 struct stat64 *__restrict __buf) __THROW __nonnull ((1, 2));
258 extern int fstat64 (int __fd, struct stat64 *__buf) __THROW __nonnull ((2));
259 #endif
260 #ifdef __USE_ATFILE
262 /* Similar to stat, get the attributes for FILE and put them in BUF.
263 Relative path names are interpreted relative to FD unless FD is
264 AT_FDCWD. */
265 # ifndef __USE_FILE_OFFSET64
266 extern int fstatat (int __fd, const char *__restrict __file,
267 struct stat *__restrict __buf, int __flag)
268 __THROW __nonnull ((2, 3));
269 # else
270 # ifdef __REDIRECT_NTH
271 extern int __REDIRECT_NTH (fstatat, (int __fd, const char *__restrict __file,
272 struct stat *__restrict __buf,
273 int __flag),
274 fstatat64) __nonnull ((2, 3));
275 # else
276 # define fstatat fstatat64
277 # endif
278 # endif
279 # ifdef __USE_LARGEFILE64
281 extern int fstatat64 (int __fd, const char *__restrict __file,
282 struct stat64 *__restrict __buf, int __flag)
283 __THROW __nonnull ((2, 3));
284 # endif
285 #endif
286 #if defined __USE_BSD || defined __USE_XOPEN_EXTENDED || defined __USE_XOPEN2K
288 # ifndef __USE_FILE_OFFSET64
289 /* Get file attributes about FILE and put them in BUF.
290 If FILE is a symbolic link, do not follow it. */
291 extern int lstat (const char *__restrict __file,
292 struct stat *__restrict __buf) __THROW __nonnull ((1, 2));
293 # else
294 # ifdef __REDIRECT_NTH
295 extern int __REDIRECT_NTH (lstat,
296 (const char *__restrict __file,
297 struct stat *__restrict __buf), lstat64)
298 __nonnull ((1, 2));
299 # else
300 # define lstat lstat64
301 # endif
302 # endif
303 # ifdef __USE_LARGEFILE64
304 extern int lstat64 (const char *__restrict __file,
305 struct stat64 *__restrict __buf)
306 __THROW __nonnull ((1, 2));
307 # endif
308 #endif
309 /* Set file access permissions for FILE to MODE.
311 If FILE is a symbolic link, this affects its target instead. */
312 extern int chmod (const char *__file, __mode_t __mode)
313 __THROW __nonnull ((1));
314 #ifdef __USE_BSD
316 /* Set file access permissions for FILE to MODE.
317 If FILE is a symbolic link, this affects the link itself
318 rather than its target. */
319 extern int lchmod (const char *__file, __mode_t __mode)
320 __THROW __nonnull ((1));
321 #endif
322 /* Set file access permissions of the file FD is open on to MODE. */
324 #if defined __USE_BSD || defined __USE_POSIX
325 extern int fchmod (int __fd, __mode_t __mode) __THROW;
326 #endif
327 #ifdef __USE_ATFILE
329 /* Set file access permissions of FILE relative to
330 the directory FD is open on. */
331 extern int fchmodat (int __fd, const char *__file, __mode_t __mode,
332 int __flag)
333 __THROW __nonnull ((2)) __wur;
334 #endif /* Use ATFILE. */
335 /* Set the file creation mask of the current process to MASK,
339 and return the old creation mask. */
340 extern __mode_t umask (__mode_t __mask) __THROW;
341 #ifdef __USE_GNU
343 /* Get the current `umask' value without changing it.
344 This function is only available under the GNU Hurd. */
345 extern __mode_t getumask (void) __THROW;
346 #endif
347 /* Create a new directory named PATH, with permission bits MODE. */
349 extern int mkdir (const char *__path, __mode_t __mode)
350 __THROW __nonnull ((1));
351 #ifdef __USE_ATFILE
353 /* Like mkdir, create a new directory with permission bits MODE. But
354 interpret relative PATH names relative to the directory associated
355 with FD. */
356 extern int mkdirat (int __fd, const char *__path, __mode_t __mode)
357 __THROW __nonnull ((2));
358 #endif
359 /* Create a device file named PATH, with permission and special bits MODE
361 and device number DEV (which can be constructed from major and minor
362 device numbers with the `makedev' macro above). */
363 #if defined __USE_MISC || defined __USE_BSD || defined __USE_XOPEN_EXTENDED
364 extern int mknod (const char *__path, __mode_t __mode, __dev_t __dev)
365 __THROW __nonnull ((1));
366 # ifdef __USE_ATFILE
368 /* Like mknod, create a new device file with permission bits MODE and
369 device number DEV. But interpret relative PATH names relative to
370 the directory associated with FD. */
371 extern int mknodat (int __fd, const char *__path, __mode_t __mode,
372 __dev_t __dev) __THROW __nonnull ((2));
373 # endif
374 #endif
375 /* Create a new FIFO named PATH, with permission bits MODE. */
378 extern int mkfifo (const char *__path, __mode_t __mode)
379 __THROW __nonnull ((1));
380 #ifdef __USE_ATFILE
382 /* Like mkfifo, create a new FIFO with permission bits MODE. But
383 interpret relative PATH names relative to the directory associated
384 with FD. */
385 extern int mkfifoat (int __fd, const char *__path, __mode_t __mode)
386 __THROW __nonnull ((2));
387 #endif
388
389 #ifdef __USE_ATFILE
390 /* Set file access and modification times relative to directory file
391 descriptor. */
392 extern int utimensat (int __fd, const char *__path,
393 const struct timespec __times[2],
394 int __flags)
395 __THROW __nonnull ((2));
396 #endif
397 #ifdef __USE_XOPEN2K8
399 /* Set file access and modification times of the file associated with FD. */
400 extern int futimens (int __fd, const struct timespec __times[2]) __THROW;
401 #endif
402
403 /* To allow the `struct stat' structure and the file type `mode_t'
404 bits to vary without changing shared library major version number,
405 the `stat' family of functions and `mknod' are in fact inline
406 wrappers around calls to `xstat', `fxstat', `lxstat', and `xmknod',
407 which all take a leading version-number argument designating the
408 data structure and bits used. <bits/stat.h> defines _STAT_VER with
409 the version number corresponding to `struct stat' as defined in
410 that file; and _MKNOD_VER with the version number corresponding to
411 the S_IF* macros defined therein. It is arranged that when not
412 inlined these function are always statically linked; that way a
413 dynamically-linked executable always encodes the version number
414 corresponding to the data structures it uses, so the `x' functions
415 in the shared library can adapt without needing to recompile all
416 callers. */
417 #ifndef _STAT_VER
419 # define _STAT_VER 0
420 #endif
421 #ifndef _MKNOD_VER
422 # define _MKNOD_VER 0
423 #endif
424 /* Wrappers for stat and mknod system calls. */
426 #ifndef __USE_FILE_OFFSET64
427 extern int __fxstat (int __ver, int __fildes, struct stat *__stat_buf)
428 __THROW __nonnull ((3));
429 extern int __xstat (int __ver, const char *__filename,
430 struct stat *__stat_buf) __THROW __nonnull ((2, 3));
431 extern int __lxstat (int __ver, const char *__filename,
432 struct stat *__stat_buf) __THROW __nonnull ((2, 3));
433 extern int __fxstatat (int __ver, int __fildes, const char *__filename,
434 struct stat *__stat_buf, int __flag)
435 __THROW __nonnull ((3, 4));
436 #else
437 # ifdef __REDIRECT_NTH
438 extern int __REDIRECT_NTH (__fxstat, (int __ver, int __fildes,
439 struct stat *__stat_buf), __fxstat64)
440 __nonnull ((3));
441 extern int __REDIRECT_NTH (__xstat, (int __ver, const char *__filename,
442 struct stat *__stat_buf), __xstat64)
443 __nonnull ((2, 3));
444 extern int __REDIRECT_NTH (__lxstat, (int __ver, const char *__filename,
445 struct stat *__stat_buf), __lxstat64)
446 __nonnull ((2, 3));
447 extern int __REDIRECT_NTH (__fxstatat, (int __ver, int __fildes,
448 const char *__filename,
449 struct stat *__stat_buf, int __flag),
450 __fxstatat64) __nonnull ((3, 4));
451 # else
453 # define __fxstat __fxstat64
454 # define __xstat __xstat64
455 # define __lxstat __lxstat64
456 # endif
457 #endif
458 #ifdef __USE_LARGEFILE64
460 extern int __fxstat64 (int __ver, int __fildes, struct stat64 *__stat_buf)
461 __THROW __nonnull ((3));
462 extern int __xstat64 (int __ver, const char *__filename,
463 struct stat64 *__stat_buf) __THROW __nonnull ((2, 3));
464 extern int __lxstat64 (int __ver, const char *__filename,
465 struct stat64 *__stat_buf) __THROW __nonnull ((2, 3));
466 extern int __fxstatat64 (int __ver, int __fildes, const char *__filename,
467 struct stat64 *__stat_buf, int __flag)
468 __THROW __nonnull ((3, 4));
469 #endif
470 extern int __xmknod (int __ver, const char *__path, __mode_t __mode,
471 __dev_t *__dev) __THROW __nonnull ((2, 4));
472 extern int __xmknodat (int __ver, int __fd, const char *__path,
474 __mode_t __mode, __dev_t *__dev)
475 __THROW __nonnull ((3, 5));
476 #if defined __GNUC__ && __GNUC__ >= 2 && defined __USE_EXTERN_INLINES
478 /* Inlined versions of the real stat and mknod functions. */
479 __extern_inline int
481 __NTH (stat (const char *__path, struct stat *__statbuf))
482 {
483 return __xstat (_STAT_VER, __path, __statbuf);
484 }
485 # if defined __USE_BSD || defined __USE_XOPEN_EXTENDED
487 __extern_inline int
488 __NTH (lstat (const char *__path, struct stat *__statbuf))
489 {
490 return __lxstat (_STAT_VER, __path, __statbuf);
491 }
492 # endif
493 __extern_inline int
495 __NTH (fstat (int __fd, struct stat *__statbuf))
496 {
497 return __fxstat (_STAT_VER, __fd, __statbuf);
498 }
499 # ifdef __USE_ATFILE
501 __extern_inline int
502 __NTH (fstatat (int __fd, const char *__filename, struct stat *__statbuf,
503 int __flag))
504 {
505 return __fxstatat (_STAT_VER, __fd, __filename, __statbuf, __flag);
506 }
507 # endif
508 # if defined __USE_MISC || defined __USE_BSD
510 __extern_inline int
511 __NTH (mknod (const char *__path, __mode_t __mode, __dev_t __dev))
512 {
513 return __xmknod (_MKNOD_VER, __path, __mode, &__dev);
514 }
515 # endif
516 # ifdef __USE_ATFILE
518 __extern_inline int
519 __NTH (mknodat (int __fd, const char *__path, __mode_t __mode,
520 __dev_t __dev))
521 {
522 return __xmknodat (_MKNOD_VER, __fd, __path, __mode, &__dev);
523 }
524 # endif
525 # if defined __USE_LARGEFILE64 && (! defined __USE_FILE_OFFSET64 || (defined __REDIRECT_NTH && defined __OPTIMIZE__))
527 __extern_inline int
528 __NTH (stat64 (const char *__path, struct stat64 *__statbuf))
529 {
530 return __xstat64 (_STAT_VER, __path, __statbuf);
531 }
532 # if defined __USE_BSD || defined __USE_XOPEN_EXTENDED
534 __extern_inline int
535 __NTH (lstat64 (const char *__path, struct stat64 *__statbuf))
536 {
537 return __lxstat64 (_STAT_VER, __path, __statbuf);
538 }
539 # endif
540 __extern_inline int
542 __NTH (fstat64 (int __fd, struct stat64 *__statbuf))
543 {
544 return __fxstat64 (_STAT_VER, __fd, __statbuf);
545 }
546 # ifdef __USE_ATFILE
548 __extern_inline int
549 __NTH (fstatat64 (int __fd, const char *__filename, struct stat64 *__statbuf,
550 int __flag))
551 {
552 return __fxstatat64 (_STAT_VER, __fd, __filename, __statbuf, __flag);
553 }
554 # endif
555 # endif
557 #endif
559 __END_DECLS
561 #endif /* sys/stat.h */
564 The mode bits 0000070 and 0000007 encode group and others permissions
566 (see chmod(2)). The defined types, ino_t, off_t, time_t, name various
567 width integer values; dev_t encodes major and minor device numbers;
568 their exact definitions are in the include file <sys/types.h> (see
569 types(5).
570 When fildes is associated with a pipe, fstat reports an ordinary file
572 with restricted permissions. The size is the number of bytes queued in
573 the pipe.
574 st_atime is the file was last read. For reasons of efficiency, it is
576 not set when a directory is searched, although this would be more logi‐
577 cal. st_mtime is the time the file was last written or created. It is
578 not set by changes of owner, group, link count, or mode. st_ctime is
579 set both both by writing and changing the i-node.
580
582 ls(1), filsys(5)
583
585 Zero is returned if a status is available; -1 if the file cannot be
586 found.
587
589 (stat = 18.)
590 sys stat; name; buf
591 (fstat = 28.)
593 (file descriptor in r0)
594 sys fstat; buf
595 STAT(2)