|
|
0febb9 |
From f14d3a310dbaf5456e5267ee56d2b35a78ec540b Mon Sep 17 00:00:00 2001
|
|
|
0febb9 |
From: =?UTF-8?q?Nikola=20Forr=C3=B3?= <nforro@redhat.com>
|
|
|
0febb9 |
Date: Mon, 22 May 2017 14:54:07 +0200
|
|
|
0febb9 |
Subject: [PATCH 2/2] stat.2: update to cover latest things used in RHEL 7
|
|
|
0febb9 |
|
|
|
0febb9 |
---
|
|
|
0febb9 |
man-pages/man2/stat.2 | 760 +++++++++++++++++++++++++++++++++++---------------
|
|
|
0febb9 |
1 file changed, 540 insertions(+), 220 deletions(-)
|
|
|
0febb9 |
|
|
|
0febb9 |
diff --git a/man-pages/man2/stat.2 b/man-pages/man2/stat.2
|
|
|
0febb9 |
index c86ebc0..f108020 100644
|
|
|
0febb9 |
--- a/man-pages/man2/stat.2
|
|
|
0febb9 |
+++ b/man-pages/man2/stat.2
|
|
|
0febb9 |
@@ -1,7 +1,7 @@
|
|
|
0febb9 |
'\" t
|
|
|
0febb9 |
.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
|
|
|
0febb9 |
.\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
|
|
|
0febb9 |
-.\" and Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
|
0febb9 |
+.\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
|
0febb9 |
.\"
|
|
|
0febb9 |
.\" %%%LICENSE_START(VERBATIM)
|
|
|
0febb9 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
0febb9 |
@@ -37,21 +37,30 @@
|
|
|
0febb9 |
.\" 2007-06-08 mtk: Added example program
|
|
|
0febb9 |
.\" 2007-07-05 mtk: Added details on underlying system call interfaces
|
|
|
0febb9 |
.\"
|
|
|
0febb9 |
-.TH STAT 2 2012-11-11 "Linux" "Linux Programmer's Manual"
|
|
|
0febb9 |
+.TH STAT 2 2017-03-13 "Linux" "Linux Programmer's Manual"
|
|
|
0febb9 |
.SH NAME
|
|
|
0febb9 |
-stat, fstat, lstat \- get file status
|
|
|
0febb9 |
+stat, fstat, lstat, fstatat \- get file status
|
|
|
0febb9 |
.SH SYNOPSIS
|
|
|
0febb9 |
+.nf
|
|
|
0febb9 |
.B #include <sys/types.h>
|
|
|
0febb9 |
.br
|
|
|
0febb9 |
.B #include <sys/stat.h>
|
|
|
0febb9 |
.br
|
|
|
0febb9 |
.B #include <unistd.h>
|
|
|
0febb9 |
.sp
|
|
|
0febb9 |
-.BI "int stat(const char *" path ", struct stat *" buf );
|
|
|
0febb9 |
+.BI "int stat(const char *" pathname ", struct stat *" buf );
|
|
|
0febb9 |
.br
|
|
|
0febb9 |
.BI "int fstat(int " fd ", struct stat *" buf );
|
|
|
0febb9 |
.br
|
|
|
0febb9 |
-.BI "int lstat(const char *" path ", struct stat *" buf );
|
|
|
0febb9 |
+.BI "int lstat(const char *" pathname ", struct stat *" buf );
|
|
|
0febb9 |
+.sp
|
|
|
0febb9 |
+.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
|
|
|
0febb9 |
+.B #include <sys/stat.h>
|
|
|
0febb9 |
+.sp
|
|
|
0febb9 |
+.BI "int fstatat(int " dirfd ", const char *" pathname ", struct stat *" \
|
|
|
0febb9 |
+buf ,
|
|
|
0febb9 |
+.BI " int " flags );
|
|
|
0febb9 |
+.fi
|
|
|
0febb9 |
.sp
|
|
|
0febb9 |
.in -4n
|
|
|
0febb9 |
Feature Test Macro Requirements for glibc (see
|
|
|
0febb9 |
@@ -62,45 +71,67 @@ Feature Test Macro Requirements for glibc (see
|
|
|
0febb9 |
.sp
|
|
|
0febb9 |
.BR lstat ():
|
|
|
0febb9 |
.RS 4
|
|
|
0febb9 |
-_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
|
|
|
0febb9 |
-_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
|
|
|
0febb9 |
+/* glibc 2.19 and earlier */ _BSD_SOURCE
|
|
|
0febb9 |
+.br
|
|
|
0febb9 |
+ || /* Since glibc 2.20 */ _DEFAULT_SOURCE
|
|
|
0febb9 |
.br
|
|
|
0febb9 |
-|| /* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200112L
|
|
|
0febb9 |
+ || _XOPEN_SOURCE\ >=\ 500
|
|
|
0febb9 |
+.\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
|
|
|
0febb9 |
+.br
|
|
|
0febb9 |
+ || /* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200112L
|
|
|
0febb9 |
+.RE
|
|
|
0febb9 |
+.sp
|
|
|
0febb9 |
+.BR fstatat ():
|
|
|
0febb9 |
+.PD 0
|
|
|
0febb9 |
+.ad l
|
|
|
0febb9 |
+.RS 4
|
|
|
0febb9 |
+.TP 4
|
|
|
0febb9 |
+Since glibc 2.10:
|
|
|
0febb9 |
+_POSIX_C_SOURCE\ >=\ 200809L
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+Before glibc 2.10:
|
|
|
0febb9 |
+_ATFILE_SOURCE
|
|
|
0febb9 |
.RE
|
|
|
0febb9 |
.PD
|
|
|
0febb9 |
.ad
|
|
|
0febb9 |
.SH DESCRIPTION
|
|
|
0febb9 |
.PP
|
|
|
0febb9 |
-These functions return information about a file.
|
|
|
0febb9 |
+These functions return information about a file, in the buffer pointed to by
|
|
|
0febb9 |
+.IR buf .
|
|
|
0febb9 |
No permissions are required on the file itself, but\(emin the case of
|
|
|
0febb9 |
-.BR stat ()
|
|
|
0febb9 |
+.BR stat (),
|
|
|
0febb9 |
+.BR fstatat (),
|
|
|
0febb9 |
and
|
|
|
0febb9 |
-.BR lstat ()
|
|
|
0febb9 |
-\(em
|
|
|
0febb9 |
-execute (search) permission is required on all of the directories in
|
|
|
0febb9 |
-.I path
|
|
|
0febb9 |
+.BR lstat ()\(emexecute
|
|
|
0febb9 |
+(search) permission is required on all of the directories in
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
that lead to the file.
|
|
|
0febb9 |
.PP
|
|
|
0febb9 |
.BR stat ()
|
|
|
0febb9 |
-stats the file pointed to by
|
|
|
0febb9 |
-.I path
|
|
|
0febb9 |
-and fills in
|
|
|
0febb9 |
-.IR buf .
|
|
|
0febb9 |
+and
|
|
|
0febb9 |
+.BR fstatat ()
|
|
|
0febb9 |
+retrieve information about the file pointed to by
|
|
|
0febb9 |
+.IR pathname ;
|
|
|
0febb9 |
+the differences for
|
|
|
0febb9 |
+.BR fstatat ()
|
|
|
0febb9 |
+are described below.
|
|
|
0febb9 |
|
|
|
0febb9 |
.BR lstat ()
|
|
|
0febb9 |
is identical to
|
|
|
0febb9 |
.BR stat (),
|
|
|
0febb9 |
except that if
|
|
|
0febb9 |
-.I path
|
|
|
0febb9 |
-is a symbolic link, then the link itself is stat-ed,
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
+is a symbolic link, then it returns information about the link itself,
|
|
|
0febb9 |
not the file that it refers to.
|
|
|
0febb9 |
|
|
|
0febb9 |
.BR fstat ()
|
|
|
0febb9 |
is identical to
|
|
|
0febb9 |
.BR stat (),
|
|
|
0febb9 |
-except that the file to be stat-ed is specified by the file descriptor
|
|
|
0febb9 |
+except that the file about which information is to be retrieved
|
|
|
0febb9 |
+is specified by the file descriptor
|
|
|
0febb9 |
.IR fd .
|
|
|
0febb9 |
-.PP
|
|
|
0febb9 |
+.\"
|
|
|
0febb9 |
+.SS The stat structure
|
|
|
0febb9 |
All of these system calls return a
|
|
|
0febb9 |
.I stat
|
|
|
0febb9 |
structure, which contains the following fields:
|
|
|
0febb9 |
@@ -108,84 +139,123 @@ structure, which contains the following fields:
|
|
|
0febb9 |
.in +4n
|
|
|
0febb9 |
.nf
|
|
|
0febb9 |
struct stat {
|
|
|
0febb9 |
- dev_t st_dev; /* ID of device containing file */
|
|
|
0febb9 |
- ino_t st_ino; /* inode number */
|
|
|
0febb9 |
- mode_t st_mode; /* protection */
|
|
|
0febb9 |
- nlink_t st_nlink; /* number of hard links */
|
|
|
0febb9 |
- uid_t st_uid; /* user ID of owner */
|
|
|
0febb9 |
- gid_t st_gid; /* group ID of owner */
|
|
|
0febb9 |
- dev_t st_rdev; /* device ID (if special file) */
|
|
|
0febb9 |
- off_t st_size; /* total size, in bytes */
|
|
|
0febb9 |
- blksize_t st_blksize; /* blocksize for file system I/O */
|
|
|
0febb9 |
- blkcnt_t st_blocks; /* number of 512B blocks allocated */
|
|
|
0febb9 |
- time_t st_atime; /* time of last access */
|
|
|
0febb9 |
- time_t st_mtime; /* time of last modification */
|
|
|
0febb9 |
- time_t st_ctime; /* time of last status change */
|
|
|
0febb9 |
+ dev_t st_dev; /* ID of device containing file */
|
|
|
0febb9 |
+ ino_t st_ino; /* inode number */
|
|
|
0febb9 |
+ mode_t st_mode; /* file type and mode */
|
|
|
0febb9 |
+ nlink_t st_nlink; /* number of hard links */
|
|
|
0febb9 |
+ uid_t st_uid; /* user ID of owner */
|
|
|
0febb9 |
+ gid_t st_gid; /* group ID of owner */
|
|
|
0febb9 |
+ dev_t st_rdev; /* device ID (if special file) */
|
|
|
0febb9 |
+ off_t st_size; /* total size, in bytes */
|
|
|
0febb9 |
+ blksize_t st_blksize; /* blocksize for filesystem I/O */
|
|
|
0febb9 |
+ blkcnt_t st_blocks; /* number of 512B blocks allocated */
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+ /* Since Linux 2.6, the kernel supports nanosecond
|
|
|
0febb9 |
+ precision for the following timestamp fields.
|
|
|
0febb9 |
+ For the details before Linux 2.6, see NOTES. */
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+ struct timespec st_atim; /* time of last access */
|
|
|
0febb9 |
+ struct timespec st_mtim; /* time of last modification */
|
|
|
0febb9 |
+ struct timespec st_ctim; /* time of last status change */
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+#define st_atime st_atim.tv_sec /* Backward compatibility */
|
|
|
0febb9 |
+#define st_mtime st_mtim.tv_sec
|
|
|
0febb9 |
+#define st_ctime st_ctim.tv_sec
|
|
|
0febb9 |
};
|
|
|
0febb9 |
.fi
|
|
|
0febb9 |
.in
|
|
|
0febb9 |
-.PP
|
|
|
0febb9 |
-The
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+.IR Note :
|
|
|
0febb9 |
+the order of fields in the
|
|
|
0febb9 |
+.I stat
|
|
|
0febb9 |
+structure varies somewhat
|
|
|
0febb9 |
+across architectures.
|
|
|
0febb9 |
+In addition,
|
|
|
0febb9 |
+the definition above does not show the padding bytes
|
|
|
0febb9 |
+that may be present between some fields on various architectures.
|
|
|
0febb9 |
+Consult the glibc and kernel source code
|
|
|
0febb9 |
+if you need to know the details.
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+.\" Background: inode attributes are modified with i_mutex held, but
|
|
|
0febb9 |
+.\" read by stat() without taking the mutex.
|
|
|
0febb9 |
+.IR Note :
|
|
|
0febb9 |
+For performance and simplicity reasons, different fields in the
|
|
|
0febb9 |
+.I stat
|
|
|
0febb9 |
+structure may contain state information from different moments
|
|
|
0febb9 |
+during the execution of the system call.
|
|
|
0febb9 |
+For example, if
|
|
|
0febb9 |
+.IR st_mode
|
|
|
0febb9 |
+or
|
|
|
0febb9 |
+.IR st_uid
|
|
|
0febb9 |
+is changed by another process by calling
|
|
|
0febb9 |
+.BR chmod (2)
|
|
|
0febb9 |
+or
|
|
|
0febb9 |
+.BR chown (2),
|
|
|
0febb9 |
+.BR stat ()
|
|
|
0febb9 |
+might return the old
|
|
|
0febb9 |
+.I st_mode
|
|
|
0febb9 |
+together with the new
|
|
|
0febb9 |
+.IR st_uid ,
|
|
|
0febb9 |
+or the old
|
|
|
0febb9 |
+.I st_uid
|
|
|
0febb9 |
+together with the new
|
|
|
0febb9 |
+.IR st_mode .
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+The fields in the
|
|
|
0febb9 |
+.I stat
|
|
|
0febb9 |
+structure are as follows:
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
.I st_dev
|
|
|
0febb9 |
-field describes the device on which this file resides.
|
|
|
0febb9 |
+This field describes the device on which this file resides.
|
|
|
0febb9 |
(The
|
|
|
0febb9 |
.BR major (3)
|
|
|
0febb9 |
and
|
|
|
0febb9 |
.BR minor (3)
|
|
|
0febb9 |
macros may be useful to decompose the device ID in this field.)
|
|
|
0febb9 |
-
|
|
|
0febb9 |
-The
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.I st_ino
|
|
|
0febb9 |
+This field contains the file's inode number.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.I st_mode
|
|
|
0febb9 |
+See the discussion of file type and mode, below.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.I st_nlink
|
|
|
0febb9 |
+This field contains the number of hard links to the file.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.I st_uid
|
|
|
0febb9 |
+This field contains the user ID of the owner of the file.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.I st_gid
|
|
|
0febb9 |
+This field contains the ID of the group owner of the file.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
.I st_rdev
|
|
|
0febb9 |
-field describes the device that this file (inode) represents.
|
|
|
0febb9 |
-
|
|
|
0febb9 |
-The
|
|
|
0febb9 |
+This field describes the device that this file (inode) represents.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
.I st_size
|
|
|
0febb9 |
-field gives the size of the file (if it is a regular
|
|
|
0febb9 |
+This field gives the size of the file (if it is a regular
|
|
|
0febb9 |
file or a symbolic link) in bytes.
|
|
|
0febb9 |
The size of a symbolic link is the length of the pathname
|
|
|
0febb9 |
it contains, without a terminating null byte.
|
|
|
0febb9 |
-
|
|
|
0febb9 |
-The
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.I st_blksize
|
|
|
0febb9 |
+This field gives the "preferred" blocksize for efficient filesystem I/O.
|
|
|
0febb9 |
+(Writing to a file in smaller chunks may cause
|
|
|
0febb9 |
+an inefficient read-modify-rewrite.)
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
.I st_blocks
|
|
|
0febb9 |
-field indicates the number of blocks allocated to the file, 512-byte units.
|
|
|
0febb9 |
+This field indicates the number of blocks allocated to the file,
|
|
|
0febb9 |
+512-byte units.
|
|
|
0febb9 |
(This may be smaller than
|
|
|
0febb9 |
.IR st_size /512
|
|
|
0febb9 |
when the file has holes.)
|
|
|
0febb9 |
-
|
|
|
0febb9 |
-The
|
|
|
0febb9 |
-.I st_blksize
|
|
|
0febb9 |
-field gives the "preferred" blocksize for efficient file system I/O.
|
|
|
0febb9 |
-(Writing to a file in smaller chunks may cause
|
|
|
0febb9 |
-an inefficient read-modify-rewrite.)
|
|
|
0febb9 |
-.PP
|
|
|
0febb9 |
-Not all of the Linux file systems implement all of the time fields.
|
|
|
0febb9 |
-Some file system types allow mounting in such a way that file
|
|
|
0febb9 |
-and/or directory accesses do not cause an update of the
|
|
|
0febb9 |
-.I st_atime
|
|
|
0febb9 |
-field.
|
|
|
0febb9 |
-(See
|
|
|
0febb9 |
-.IR noatime ,
|
|
|
0febb9 |
-.IR nodiratime ,
|
|
|
0febb9 |
-and
|
|
|
0febb9 |
-.I relatime
|
|
|
0febb9 |
-in
|
|
|
0febb9 |
-.BR mount (8),
|
|
|
0febb9 |
-and related information in
|
|
|
0febb9 |
-.BR mount (2).)
|
|
|
0febb9 |
-In addition,
|
|
|
0febb9 |
-.I st_atime
|
|
|
0febb9 |
-is not updated if a file is opened with the
|
|
|
0febb9 |
-.BR O_NOATIME ;
|
|
|
0febb9 |
-see
|
|
|
0febb9 |
-.BR open (2).
|
|
|
0febb9 |
-
|
|
|
0febb9 |
-The field
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
.I st_atime
|
|
|
0febb9 |
-is changed by file accesses, for example, by
|
|
|
0febb9 |
+This is the file's last access timestamp.
|
|
|
0febb9 |
+It is changed by file accesses, for example, by
|
|
|
0febb9 |
.BR execve (2),
|
|
|
0febb9 |
.BR mknod (2),
|
|
|
0febb9 |
.BR pipe (2),
|
|
|
0febb9 |
-.BR utime (2)
|
|
|
0febb9 |
+.BR utime (2),
|
|
|
0febb9 |
and
|
|
|
0febb9 |
.BR read (2)
|
|
|
0febb9 |
(of more than zero bytes).
|
|
|
0febb9 |
@@ -193,13 +263,13 @@ Other routines, like
|
|
|
0febb9 |
.BR mmap (2),
|
|
|
0febb9 |
may or may not update
|
|
|
0febb9 |
.IR st_atime .
|
|
|
0febb9 |
-
|
|
|
0febb9 |
-The field
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
.I st_mtime
|
|
|
0febb9 |
-is changed by file modifications, for example, by
|
|
|
0febb9 |
+This is the file's last modification timestamp.
|
|
|
0febb9 |
+It is changed by file modifications, for example, by
|
|
|
0febb9 |
.BR mknod (2),
|
|
|
0febb9 |
.BR truncate (2),
|
|
|
0febb9 |
-.BR utime (2)
|
|
|
0febb9 |
+.BR utime (2),
|
|
|
0febb9 |
and
|
|
|
0febb9 |
.BR write (2)
|
|
|
0febb9 |
(of more than zero bytes).
|
|
|
0febb9 |
@@ -212,15 +282,78 @@ The
|
|
|
0febb9 |
field is
|
|
|
0febb9 |
.I not
|
|
|
0febb9 |
changed for changes in owner, group, hard link count, or mode.
|
|
|
0febb9 |
-
|
|
|
0febb9 |
-The field
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
.I st_ctime
|
|
|
0febb9 |
-is changed by writing or by setting inode information
|
|
|
0febb9 |
+This is the file's last status change timestamp.
|
|
|
0febb9 |
+It is changed by writing or by setting inode information
|
|
|
0febb9 |
(i.e., owner, group, link count, mode, etc.).
|
|
|
0febb9 |
.PP
|
|
|
0febb9 |
-The following POSIX macros are defined to check the file type using the
|
|
|
0febb9 |
+Not all of the Linux filesystems implement all of the time fields.
|
|
|
0febb9 |
+Some filesystem types allow mounting in such a way that file
|
|
|
0febb9 |
+and/or directory accesses do not cause an update of the
|
|
|
0febb9 |
+.I st_atime
|
|
|
0febb9 |
+field.
|
|
|
0febb9 |
+(See
|
|
|
0febb9 |
+.IR noatime ,
|
|
|
0febb9 |
+.IR nodiratime ,
|
|
|
0febb9 |
+and
|
|
|
0febb9 |
+.I relatime
|
|
|
0febb9 |
+in
|
|
|
0febb9 |
+.BR mount (8),
|
|
|
0febb9 |
+and related information in
|
|
|
0febb9 |
+.BR mount (2).)
|
|
|
0febb9 |
+In addition,
|
|
|
0febb9 |
+.I st_atime
|
|
|
0febb9 |
+is not updated if a file is opened with the
|
|
|
0febb9 |
+.BR O_NOATIME
|
|
|
0febb9 |
+flag; see
|
|
|
0febb9 |
+.BR open (2).
|
|
|
0febb9 |
+.\"
|
|
|
0febb9 |
+.SS The file type and mode (st_mode)
|
|
|
0febb9 |
+POSIX refers to the
|
|
|
0febb9 |
+.I st_mode
|
|
|
0febb9 |
+bits corresponding to the mask
|
|
|
0febb9 |
+.B S_IFMT
|
|
|
0febb9 |
+(see below) as the
|
|
|
0febb9 |
+.IR "file type" ,
|
|
|
0febb9 |
+the 12 bits corresponding to the mask 07777 as the
|
|
|
0febb9 |
+.IR "file mode bits"
|
|
|
0febb9 |
+and the least significant 9 bits (0777) as the
|
|
|
0febb9 |
+.IR "file permission bits" .
|
|
|
0febb9 |
+.PP
|
|
|
0febb9 |
+The following mask values are defined for the file type of the
|
|
|
0febb9 |
.I st_mode
|
|
|
0febb9 |
field:
|
|
|
0febb9 |
+.in +4n
|
|
|
0febb9 |
+.TS
|
|
|
0febb9 |
+lB l l.
|
|
|
0febb9 |
+S_IFMT 0170000 bit mask for the file type bit field
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+S_IFSOCK 0140000 socket
|
|
|
0febb9 |
+S_IFLNK 0120000 symbolic link
|
|
|
0febb9 |
+S_IFREG 0100000 regular file
|
|
|
0febb9 |
+S_IFBLK 0060000 block device
|
|
|
0febb9 |
+S_IFDIR 0040000 directory
|
|
|
0febb9 |
+S_IFCHR 0020000 character device
|
|
|
0febb9 |
+S_IFIFO 0010000 FIFO
|
|
|
0febb9 |
+.TE
|
|
|
0febb9 |
+.in
|
|
|
0febb9 |
+.PP
|
|
|
0febb9 |
+Thus, to test for a regular file (for example), one could write:
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+.nf
|
|
|
0febb9 |
+.in +4n
|
|
|
0febb9 |
+stat(pathname, &sb);
|
|
|
0febb9 |
+if ((sb.st_mode & S_IFMT) == S_IFREG) {
|
|
|
0febb9 |
+ /* Handle regular file */
|
|
|
0febb9 |
+}
|
|
|
0febb9 |
+.in
|
|
|
0febb9 |
+.fi
|
|
|
0febb9 |
+.PP
|
|
|
0febb9 |
+Because tests of the above form are common, additional
|
|
|
0febb9 |
+macros are defined by POSIX to allow the test of the file type in
|
|
|
0febb9 |
+.I st_mode
|
|
|
0febb9 |
+to be written more concisely:
|
|
|
0febb9 |
.RS 4
|
|
|
0febb9 |
.TP 1.2i
|
|
|
0febb9 |
.BR S_ISREG (m)
|
|
|
0febb9 |
@@ -245,42 +378,85 @@ symbolic link? (Not in POSIX.1-1996.)
|
|
|
0febb9 |
socket? (Not in POSIX.1-1996.)
|
|
|
0febb9 |
.RE
|
|
|
0febb9 |
.PP
|
|
|
0febb9 |
-The following flags are defined for the
|
|
|
0febb9 |
+The preceding code snippet could thus be rewritten as:
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+.nf
|
|
|
0febb9 |
+.in +4n
|
|
|
0febb9 |
+stat(pathname, &sb);
|
|
|
0febb9 |
+if (S_ISREG(sb.st_mode)) {
|
|
|
0febb9 |
+ /* Handle regular file */
|
|
|
0febb9 |
+}
|
|
|
0febb9 |
+.in
|
|
|
0febb9 |
+.fi
|
|
|
0febb9 |
+.PP
|
|
|
0febb9 |
+The definitions of most of the above file type test macros
|
|
|
0febb9 |
+are provided if any of the following feature test macros is defined:
|
|
|
0febb9 |
+.BR _BSD_SOURCE
|
|
|
0febb9 |
+(in glibc 2.19 and earlier),
|
|
|
0febb9 |
+.BR _SVID_SOURCE
|
|
|
0febb9 |
+(in glibc 2.19 and earlier),
|
|
|
0febb9 |
+or
|
|
|
0febb9 |
+.BR _DEFAULT_SOURCE
|
|
|
0febb9 |
+(in glibc 2.20 and later).
|
|
|
0febb9 |
+In addition, definitions of all of the above macros except
|
|
|
0febb9 |
+.BR S_IFSOCK
|
|
|
0febb9 |
+and
|
|
|
0febb9 |
+.BR S_ISSOCK ()
|
|
|
0febb9 |
+are provided if
|
|
|
0febb9 |
+.BR _XOPEN_SOURCE
|
|
|
0febb9 |
+is defined.
|
|
|
0febb9 |
+The definition of
|
|
|
0febb9 |
+.BR S_IFSOCK
|
|
|
0febb9 |
+can also be exposed by defining
|
|
|
0febb9 |
+.BR _XOPEN_SOURCE
|
|
|
0febb9 |
+with a value of 500 or greater.
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+The definition of
|
|
|
0febb9 |
+.BR S_ISSOCK ()
|
|
|
0febb9 |
+is exposed if any of the following feature test macros is defined:
|
|
|
0febb9 |
+.BR _BSD_SOURCE
|
|
|
0febb9 |
+(in glibc 2.19 and earlier),
|
|
|
0febb9 |
+.BR _DEFAULT_SOURCE
|
|
|
0febb9 |
+(in glibc 2.20 and later),
|
|
|
0febb9 |
+.BR _XOPEN_SOURCE
|
|
|
0febb9 |
+with a value of 500 or greater, or
|
|
|
0febb9 |
+.BR _POSIX_C_SOURCE
|
|
|
0febb9 |
+with a value of 200112L or greater.
|
|
|
0febb9 |
+.PP
|
|
|
0febb9 |
+The following mask values are defined for
|
|
|
0febb9 |
+the file mode component of the
|
|
|
0febb9 |
.I st_mode
|
|
|
0febb9 |
field:
|
|
|
0febb9 |
.in +4n
|
|
|
0febb9 |
.TS
|
|
|
0febb9 |
lB l l.
|
|
|
0febb9 |
-S_IFMT 0170000 bit mask for the file type bit fields
|
|
|
0febb9 |
-S_IFSOCK 0140000 socket
|
|
|
0febb9 |
-S_IFLNK 0120000 symbolic link
|
|
|
0febb9 |
-S_IFREG 0100000 regular file
|
|
|
0febb9 |
-S_IFBLK 0060000 block device
|
|
|
0febb9 |
-S_IFDIR 0040000 directory
|
|
|
0febb9 |
-S_IFCHR 0020000 character device
|
|
|
0febb9 |
-S_IFIFO 0010000 FIFO
|
|
|
0febb9 |
-S_ISUID 0004000 set-user-ID bit
|
|
|
0febb9 |
-S_ISGID 0002000 set-group-ID bit (see below)
|
|
|
0febb9 |
-S_ISVTX 0001000 sticky bit (see below)
|
|
|
0febb9 |
-S_IRWXU 00700 mask for file owner permissions
|
|
|
0febb9 |
-S_IRUSR 00400 owner has read permission
|
|
|
0febb9 |
-S_IWUSR 00200 owner has write permission
|
|
|
0febb9 |
-S_IXUSR 00100 owner has execute permission
|
|
|
0febb9 |
-S_IRWXG 00070 mask for group permissions
|
|
|
0febb9 |
-S_IRGRP 00040 group has read permission
|
|
|
0febb9 |
-S_IWGRP 00020 group has write permission
|
|
|
0febb9 |
-S_IXGRP 00010 group has execute permission
|
|
|
0febb9 |
-S_IRWXO 00007 mask for permissions for others (not in group)
|
|
|
0febb9 |
-S_IROTH 00004 others have read permission
|
|
|
0febb9 |
-S_IWOTH 00002 others have write permission
|
|
|
0febb9 |
-S_IXOTH 00001 others have execute permission
|
|
|
0febb9 |
+S_ISUID 04000 set-user-ID bit
|
|
|
0febb9 |
+S_ISGID 02000 set-group-ID bit (see below)
|
|
|
0febb9 |
+S_ISVTX 01000 sticky bit (see below)
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+S_IRWXU 00700 owner has read, write, and execute permission
|
|
|
0febb9 |
+S_IRUSR 00400 owner has read permission
|
|
|
0febb9 |
+S_IWUSR 00200 owner has write permission
|
|
|
0febb9 |
+S_IXUSR 00100 owner has execute permission
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+S_IRWXG 00070 group has read, write, and execute permission
|
|
|
0febb9 |
+S_IRGRP 00040 group has read permission
|
|
|
0febb9 |
+S_IWGRP 00020 group has write permission
|
|
|
0febb9 |
+S_IXGRP 00010 group has execute permission
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+S_IRWXO 00007 T{
|
|
|
0febb9 |
+others (not in group) have read, write, and execute permission
|
|
|
0febb9 |
+T}
|
|
|
0febb9 |
+S_IROTH 00004 others have read permission
|
|
|
0febb9 |
+S_IWOTH 00002 others have write permission
|
|
|
0febb9 |
+S_IXOTH 00001 others have execute permission
|
|
|
0febb9 |
.TE
|
|
|
0febb9 |
.in
|
|
|
0febb9 |
.P
|
|
|
0febb9 |
The set-group-ID bit
|
|
|
0febb9 |
.RB ( S_ISGID )
|
|
|
0febb9 |
has several special uses.
|
|
|
0febb9 |
-For a directory it indicates that BSD semantics is to be used
|
|
|
0febb9 |
+For a directory, it indicates that BSD semantics is to be used
|
|
|
0febb9 |
for that directory: files created there inherit their group ID from
|
|
|
0febb9 |
the directory, not from the effective group ID of the creating process,
|
|
|
0febb9 |
and directories created there will also get the
|
|
|
0febb9 |
@@ -297,6 +473,100 @@ on a directory means that a file
|
|
|
0febb9 |
in that directory can be renamed or deleted only by the owner
|
|
|
0febb9 |
of the file, by the owner of the directory, and by a privileged
|
|
|
0febb9 |
process.
|
|
|
0febb9 |
+.\"
|
|
|
0febb9 |
+.\"
|
|
|
0febb9 |
+.SS fstatat()
|
|
|
0febb9 |
+The
|
|
|
0febb9 |
+.BR fstatat ()
|
|
|
0febb9 |
+system call operates in exactly the same way as
|
|
|
0febb9 |
+.BR stat (),
|
|
|
0febb9 |
+except for the differences described here.
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+If the pathname given in
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
+is relative, then it is interpreted relative to the directory
|
|
|
0febb9 |
+referred to by the file descriptor
|
|
|
0febb9 |
+.I dirfd
|
|
|
0febb9 |
+(rather than relative to the current working directory of
|
|
|
0febb9 |
+the calling process, as is done by
|
|
|
0febb9 |
+.BR stat ()
|
|
|
0febb9 |
+for a relative pathname).
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+If
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
+is relative and
|
|
|
0febb9 |
+.I dirfd
|
|
|
0febb9 |
+is the special value
|
|
|
0febb9 |
+.BR AT_FDCWD ,
|
|
|
0febb9 |
+then
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
+is interpreted relative to the current working
|
|
|
0febb9 |
+directory of the calling process (like
|
|
|
0febb9 |
+.BR stat ()).
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+If
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
+is absolute, then
|
|
|
0febb9 |
+.I dirfd
|
|
|
0febb9 |
+is ignored.
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+.I flags
|
|
|
0febb9 |
+can either be 0, or include one or more of the following flags ORed:
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.BR AT_EMPTY_PATH " (since Linux 2.6.39)"
|
|
|
0febb9 |
+.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
|
|
|
0febb9 |
+If
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
+is an empty string, operate on the file referred to by
|
|
|
0febb9 |
+.IR dirfd
|
|
|
0febb9 |
+(which may have been obtained using the
|
|
|
0febb9 |
+.BR open (2)
|
|
|
0febb9 |
+.B O_PATH
|
|
|
0febb9 |
+flag).
|
|
|
0febb9 |
+In this case,
|
|
|
0febb9 |
+.I dirfd
|
|
|
0febb9 |
+can refer to any type of file, not just a directory.
|
|
|
0febb9 |
+If
|
|
|
0febb9 |
+.I dirfd
|
|
|
0febb9 |
+is
|
|
|
0febb9 |
+.BR AT_FDCWD ,
|
|
|
0febb9 |
+the call operates on the current working directory.
|
|
|
0febb9 |
+This flag is Linux-specific; define
|
|
|
0febb9 |
+.B _GNU_SOURCE
|
|
|
0febb9 |
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
|
|
|
0febb9 |
+to obtain its definition.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
|
|
|
0febb9 |
+Don't automount the terminal ("basename") component of
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
+if it is a directory that is an automount point.
|
|
|
0febb9 |
+This allows the caller to gather attributes of an automount point
|
|
|
0febb9 |
+(rather than the location it would mount).
|
|
|
0febb9 |
+This flag can be used in tools that scan directories
|
|
|
0febb9 |
+to prevent mass-automounting of a directory of automount points.
|
|
|
0febb9 |
+The
|
|
|
0febb9 |
+.B AT_NO_AUTOMOUNT
|
|
|
0febb9 |
+flag has no effect if the mount point has already been mounted over.
|
|
|
0febb9 |
+This flag is Linux-specific; define
|
|
|
0febb9 |
+.B _GNU_SOURCE
|
|
|
0febb9 |
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
|
|
|
0febb9 |
+to obtain its definition.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.B AT_SYMLINK_NOFOLLOW
|
|
|
0febb9 |
+If
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
+is a symbolic link, do not dereference it:
|
|
|
0febb9 |
+instead return information about the link itself, like
|
|
|
0febb9 |
+.BR lstat ().
|
|
|
0febb9 |
+(By default,
|
|
|
0febb9 |
+.BR fstatat ()
|
|
|
0febb9 |
+dereferences symbolic links, like
|
|
|
0febb9 |
+.BR stat ().)
|
|
|
0febb9 |
+.PP
|
|
|
0febb9 |
+See
|
|
|
0febb9 |
+.BR openat (2)
|
|
|
0febb9 |
+for an explanation of the need for
|
|
|
0febb9 |
+.BR fstatat ().
|
|
|
0febb9 |
.SH RETURN VALUE
|
|
|
0febb9 |
On success, zero is returned.
|
|
|
0febb9 |
On error, \-1 is returned, and
|
|
|
0febb9 |
@@ -307,13 +577,13 @@ is set appropriately.
|
|
|
0febb9 |
.B EACCES
|
|
|
0febb9 |
Search permission is denied for one of the directories
|
|
|
0febb9 |
in the path prefix of
|
|
|
0febb9 |
-.IR path .
|
|
|
0febb9 |
+.IR pathname .
|
|
|
0febb9 |
(See also
|
|
|
0febb9 |
.BR path_resolution (7).)
|
|
|
0febb9 |
.TP
|
|
|
0febb9 |
.B EBADF
|
|
|
0febb9 |
.I fd
|
|
|
0febb9 |
-is bad.
|
|
|
0febb9 |
+is not a valid open file descriptor.
|
|
|
0febb9 |
.TP
|
|
|
0febb9 |
.B EFAULT
|
|
|
0febb9 |
Bad address.
|
|
|
0febb9 |
@@ -322,26 +592,26 @@ Bad address.
|
|
|
0febb9 |
Too many symbolic links encountered while traversing the path.
|
|
|
0febb9 |
.TP
|
|
|
0febb9 |
.B ENAMETOOLONG
|
|
|
0febb9 |
-.I path
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
is too long.
|
|
|
0febb9 |
.TP
|
|
|
0febb9 |
.B ENOENT
|
|
|
0febb9 |
A component of
|
|
|
0febb9 |
-.I path
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
does not exist, or
|
|
|
0febb9 |
-.I path
|
|
|
0febb9 |
-is an empty string.
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
+is an empty string and AT_EMPTY_PATH was not specified.
|
|
|
0febb9 |
.TP
|
|
|
0febb9 |
.B ENOMEM
|
|
|
0febb9 |
Out of memory (i.e., kernel memory).
|
|
|
0febb9 |
.TP
|
|
|
0febb9 |
.B ENOTDIR
|
|
|
0febb9 |
A component of the path prefix of
|
|
|
0febb9 |
-.I path
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
is not a directory.
|
|
|
0febb9 |
.TP
|
|
|
0febb9 |
.B EOVERFLOW
|
|
|
0febb9 |
-.I path
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
or
|
|
|
0febb9 |
.I fd
|
|
|
0febb9 |
refers to a file whose size, inode number,
|
|
|
0febb9 |
@@ -358,8 +628,32 @@ calls
|
|
|
0febb9 |
on a file whose size exceeds
|
|
|
0febb9 |
.I (1<<31)-1
|
|
|
0febb9 |
bytes.
|
|
|
0febb9 |
+.PP
|
|
|
0febb9 |
+The following additional errors can occur for
|
|
|
0febb9 |
+.BR fstatat ():
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.B EBADF
|
|
|
0febb9 |
+.I dirfd
|
|
|
0febb9 |
+is not a valid file descriptor.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.B EINVAL
|
|
|
0febb9 |
+Invalid flag specified in
|
|
|
0febb9 |
+.IR flags .
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.B ENOTDIR
|
|
|
0febb9 |
+.I pathname
|
|
|
0febb9 |
+is relative and
|
|
|
0febb9 |
+.I dirfd
|
|
|
0febb9 |
+is a file descriptor referring to a file other than a directory.
|
|
|
0febb9 |
+.SH VERSIONS
|
|
|
0febb9 |
+.BR fstatat ()
|
|
|
0febb9 |
+was added to Linux in kernel 2.6.16;
|
|
|
0febb9 |
+library support was added to glibc in version 2.4.
|
|
|
0febb9 |
.SH CONFORMING TO
|
|
|
0febb9 |
-These system calls conform to SVr4, 4.3BSD, POSIX.1-2001.
|
|
|
0febb9 |
+.BR stat (),
|
|
|
0febb9 |
+.BR fstat (),
|
|
|
0febb9 |
+.BR lstat ():
|
|
|
0febb9 |
+SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008.
|
|
|
0febb9 |
.\" SVr4 documents additional
|
|
|
0febb9 |
.\" .BR fstat ()
|
|
|
0febb9 |
.\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4
|
|
|
0febb9 |
@@ -369,18 +663,21 @@ These system calls conform to SVr4, 4.3BSD, POSIX.1-2001.
|
|
|
0febb9 |
.\" .BR lstat ()
|
|
|
0febb9 |
.\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
|
|
|
0febb9 |
|
|
|
0febb9 |
+.BR fstatat ():
|
|
|
0febb9 |
+POSIX.1-2008.
|
|
|
0febb9 |
+
|
|
|
0febb9 |
According to POSIX.1-2001,
|
|
|
0febb9 |
.BR lstat ()
|
|
|
0febb9 |
on a symbolic link need return valid information only in the
|
|
|
0febb9 |
.I st_size
|
|
|
0febb9 |
-field and the file-type component of the
|
|
|
0febb9 |
+field and the file type of the
|
|
|
0febb9 |
.IR st_mode
|
|
|
0febb9 |
field of the
|
|
|
0febb9 |
.IR stat
|
|
|
0febb9 |
structure.
|
|
|
0febb9 |
-POSIX.-2008 tightens the specification, requiring
|
|
|
0febb9 |
+POSIX.1-2008 tightens the specification, requiring
|
|
|
0febb9 |
.BR lstat ()
|
|
|
0febb9 |
-to return valid information in all fields except the permission bits in
|
|
|
0febb9 |
+to return valid information in all fields except the mode bits in
|
|
|
0febb9 |
.IR st_mode .
|
|
|
0febb9 |
|
|
|
0febb9 |
Use of the
|
|
|
0febb9 |
@@ -413,10 +710,10 @@ POSIX.1-1990 did not describe the
|
|
|
0febb9 |
.BR S_IFCHR ,
|
|
|
0febb9 |
.BR S_IFIFO ,
|
|
|
0febb9 |
.B S_ISVTX
|
|
|
0febb9 |
-constants, but instead demanded the use of
|
|
|
0febb9 |
+constants, but instead specified the use of
|
|
|
0febb9 |
the macros
|
|
|
0febb9 |
.BR S_ISDIR (),
|
|
|
0febb9 |
-etc.
|
|
|
0febb9 |
+and so on.
|
|
|
0febb9 |
The
|
|
|
0febb9 |
.BR S_IF*
|
|
|
0febb9 |
constants are present in POSIX.1-2001 and later.
|
|
|
0febb9 |
@@ -425,11 +722,11 @@ The
|
|
|
0febb9 |
.BR S_ISLNK ()
|
|
|
0febb9 |
and
|
|
|
0febb9 |
.BR S_ISSOCK ()
|
|
|
0febb9 |
-macros are not in
|
|
|
0febb9 |
+macros were not in
|
|
|
0febb9 |
POSIX.1-1996, but both are present in POSIX.1-2001;
|
|
|
0febb9 |
the former is from SVID 4, the latter from SUSv2.
|
|
|
0febb9 |
.LP
|
|
|
0febb9 |
-UNIX V7 (and later systems) had
|
|
|
0febb9 |
+UNIX\ V7 (and later systems) had
|
|
|
0febb9 |
.BR S_IREAD ,
|
|
|
0febb9 |
.BR S_IWRITE ,
|
|
|
0febb9 |
.BR S_IEXEC ,
|
|
|
0febb9 |
@@ -438,104 +735,74 @@ prescribes the synonyms
|
|
|
0febb9 |
.BR S_IRUSR ,
|
|
|
0febb9 |
.BR S_IWUSR ,
|
|
|
0febb9 |
.BR S_IXUSR .
|
|
|
0febb9 |
-.SS Other systems
|
|
|
0febb9 |
-Values that have been (or are) in use on various systems:
|
|
|
0febb9 |
-.ad l
|
|
|
0febb9 |
-.TS
|
|
|
0febb9 |
-l l l l l.
|
|
|
0febb9 |
-hex name ls octal description
|
|
|
0febb9 |
-f000 S_IFMT 170000 mask for file type
|
|
|
0febb9 |
-0000 000000 T{
|
|
|
0febb9 |
-SCO out-of-service inode; BSD unknown type; SVID-v2 and XPG2
|
|
|
0febb9 |
-have both 0 and 0100000 for ordinary file
|
|
|
0febb9 |
-T}
|
|
|
0febb9 |
-1000 S_IFIFO p| 010000 FIFO (named pipe)
|
|
|
0febb9 |
-2000 S_IFCHR c 020000 character special (V7)
|
|
|
0febb9 |
-3000 S_IFMPC 030000 multiplexed character special (V7)
|
|
|
0febb9 |
-4000 S_IFDIR d/ 040000 directory (V7)
|
|
|
0febb9 |
-5000 S_IFNAM 050000 T{
|
|
|
0febb9 |
-XENIX named special file with two subtypes, distinguished by
|
|
|
0febb9 |
-\fIst_rdev\fP values 1, 2
|
|
|
0febb9 |
-T}
|
|
|
0febb9 |
-0001 S_INSEM s 000001 XENIX semaphore subtype of IFNAM
|
|
|
0febb9 |
-0002 S_INSHD m 000002 XENIX shared data subtype of IFNAM
|
|
|
0febb9 |
-6000 S_IFBLK b 060000 block special (V7)
|
|
|
0febb9 |
-7000 S_IFMPB 070000 multiplexed block special (V7)
|
|
|
0febb9 |
-8000 S_IFREG - 100000 regular (V7)
|
|
|
0febb9 |
-9000 S_IFCMP 110000 VxFS compressed
|
|
|
0febb9 |
-9000 S_IFNWK n 110000 network special (HP-UX)
|
|
|
0febb9 |
-a000 S_IFLNK l@ 120000 symbolic link (BSD)
|
|
|
0febb9 |
-b000 S_IFSHAD 130000 T{
|
|
|
0febb9 |
-Solaris shadow inode for ACL (not seen by user space)
|
|
|
0febb9 |
-T}
|
|
|
0febb9 |
-c000 S_IFSOCK s= 140000 socket (BSD; also "S_IFSOC" on VxFS)
|
|
|
0febb9 |
-d000 S_IFDOOR D> 150000 Solaris door
|
|
|
0febb9 |
-e000 S_IFWHT w% 160000 BSD whiteout (not used for inode)
|
|
|
0febb9 |
-0200 S_ISVTX 001000 T{
|
|
|
0febb9 |
-sticky bit: save swapped text even after use (V7)
|
|
|
0febb9 |
-.br
|
|
|
0febb9 |
-reserved (SVID-v2)
|
|
|
0febb9 |
-.br
|
|
|
0febb9 |
-On nondirectories: don't cache this file (SunOS)
|
|
|
0febb9 |
-.br
|
|
|
0febb9 |
-On directories: restricted deletion flag (SVID-v4.2)
|
|
|
0febb9 |
-T}
|
|
|
0febb9 |
-0400 S_ISGID 002000 T{
|
|
|
0febb9 |
-set-group-ID on execution (V7)
|
|
|
0febb9 |
-.br
|
|
|
0febb9 |
-for directories: use BSD semantics for propagation of GID
|
|
|
0febb9 |
-T}
|
|
|
0febb9 |
-0400 S_ENFMT 002000 T{
|
|
|
0febb9 |
-System V file locking enforcement (shared with S_ISGID)
|
|
|
0febb9 |
-T}
|
|
|
0febb9 |
-0800 S_ISUID 004000 set-user-ID on execution (V7)
|
|
|
0febb9 |
-0800 S_CDF 004000 T{
|
|
|
0febb9 |
-directory is a context dependent file (HP-UX)
|
|
|
0febb9 |
-T}
|
|
|
0febb9 |
-.TE
|
|
|
0febb9 |
-.ad
|
|
|
0febb9 |
-
|
|
|
0febb9 |
-A sticky command appeared in Version 32V AT&T UNIX.
|
|
|
0febb9 |
.SH NOTES
|
|
|
0febb9 |
+On Linux,
|
|
|
0febb9 |
+.BR lstat ()
|
|
|
0febb9 |
+will generally not trigger automounter action, whereas
|
|
|
0febb9 |
+.BR stat ()
|
|
|
0febb9 |
+will (but see the description of
|
|
|
0febb9 |
+.BR fstatat ()
|
|
|
0febb9 |
+.B AT_NO_AUTOMOUNT
|
|
|
0febb9 |
+fag, above).
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+For pseudofiles that are autogenerated by the kernel,
|
|
|
0febb9 |
+.BR stat ()
|
|
|
0febb9 |
+does not return an accurate value in the
|
|
|
0febb9 |
+.IR st_size
|
|
|
0febb9 |
+field.
|
|
|
0febb9 |
+For example, the value 0 is returned for many files under the
|
|
|
0febb9 |
+.I /proc
|
|
|
0febb9 |
+directory,
|
|
|
0febb9 |
+while various files under
|
|
|
0febb9 |
+.IR /sys
|
|
|
0febb9 |
+report a size of 4096 bytes, even though the file content is smaller.
|
|
|
0febb9 |
+For such files, one should simply try to read as many bytes as possible
|
|
|
0febb9 |
+(and append \(aq\e0\(aq to the returned buffer
|
|
|
0febb9 |
+if it is to be interpreted as a string).
|
|
|
0febb9 |
+.\"
|
|
|
0febb9 |
+.SS Timestamp fields
|
|
|
0febb9 |
+Older kernels and older standards did not support nanosecond timestamp
|
|
|
0febb9 |
+fields.
|
|
|
0febb9 |
+Instead, there were three timestamp
|
|
|
0febb9 |
+.RI fields\(em st_atime ,
|
|
|
0febb9 |
+.IR st_mtime ,
|
|
|
0febb9 |
+and
|
|
|
0febb9 |
+.IR st_ctime \(emtyped
|
|
|
0febb9 |
+as
|
|
|
0febb9 |
+.IR time_t
|
|
|
0febb9 |
+that recorded timestamps with one-second precision.
|
|
|
0febb9 |
+
|
|
|
0febb9 |
Since kernel 2.5.48, the
|
|
|
0febb9 |
.I stat
|
|
|
0febb9 |
structure supports nanosecond resolution for the three file timestamp fields.
|
|
|
0febb9 |
-Glibc exposes the nanosecond component of each field using names of the form
|
|
|
0febb9 |
-.IR st_atim.tv_nsec
|
|
|
0febb9 |
-if the
|
|
|
0febb9 |
-.B _BSD_SOURCE
|
|
|
0febb9 |
-or
|
|
|
0febb9 |
-.B _SVID_SOURCE
|
|
|
0febb9 |
-feature test macro is defined.
|
|
|
0febb9 |
-These fields are specified in POSIX.1-2008, and, starting with version 2.12,
|
|
|
0febb9 |
-glibc also exposes these field names if
|
|
|
0febb9 |
+The nanosecond components of each timestamp are available
|
|
|
0febb9 |
+via names of the form
|
|
|
0febb9 |
+.IR st_atim.tv_nsec ,
|
|
|
0febb9 |
+if suitable feature test macros are defined.
|
|
|
0febb9 |
+Nanosecond timestamps were standardized in POSIX.1-2008,
|
|
|
0febb9 |
+and, starting with version 2.12,
|
|
|
0febb9 |
+glibc exposes the nanosecond component names if
|
|
|
0febb9 |
.BR _POSIX_C_SOURCE
|
|
|
0febb9 |
is defined with the value 200809L or greater, or
|
|
|
0febb9 |
.BR _XOPEN_SOURCE
|
|
|
0febb9 |
is defined with the value 700 or greater.
|
|
|
0febb9 |
+Up to and including glibc 2.19,
|
|
|
0febb9 |
+the definitions of the nanoseconds components are also defined if
|
|
|
0febb9 |
+.B _BSD_SOURCE
|
|
|
0febb9 |
+or
|
|
|
0febb9 |
+.B _SVID_SOURCE
|
|
|
0febb9 |
+is defined.
|
|
|
0febb9 |
If none of the aforementioned macros are defined,
|
|
|
0febb9 |
then the nanosecond values are exposed with names of the form
|
|
|
0febb9 |
.IR st_atimensec .
|
|
|
0febb9 |
-On file systems that do not support subsecond timestamps,
|
|
|
0febb9 |
-the nanosecond fields are returned with the value 0.
|
|
|
0febb9 |
-.\" As at kernel 2.6.25, XFS and JFS support nanosecond timestamps,
|
|
|
0febb9 |
-.\" but ext2, ext3, and Reiserfs do not.
|
|
|
0febb9 |
-
|
|
|
0febb9 |
-On Linux,
|
|
|
0febb9 |
-.BR lstat ()
|
|
|
0febb9 |
-will generally not trigger automounter action, whereas
|
|
|
0febb9 |
-.BR stat ()
|
|
|
0febb9 |
-will (but see
|
|
|
0febb9 |
-.BR fstatat (2)).
|
|
|
0febb9 |
|
|
|
0febb9 |
-For most files under the
|
|
|
0febb9 |
-.I /proc
|
|
|
0febb9 |
-directory,
|
|
|
0febb9 |
-.BR stat ()
|
|
|
0febb9 |
-does not return the file size in the
|
|
|
0febb9 |
-.I st_size
|
|
|
0febb9 |
-field; instead the field is returned with the value 0.
|
|
|
0febb9 |
-.SS Underlying kernel interface
|
|
|
0febb9 |
+Nanosecond timestamps are supported on XFS, JFS, Btrfs, and
|
|
|
0febb9 |
+ext4 (since Linux 2.6.23).
|
|
|
0febb9 |
+.\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80
|
|
|
0febb9 |
+Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs.
|
|
|
0febb9 |
+On filesystems that do not support subsecond timestamps,
|
|
|
0febb9 |
+the nanosecond fields are returned with the value 0.
|
|
|
0febb9 |
+.SS C library/kernel differences
|
|
|
0febb9 |
Over time, increases in the size of the
|
|
|
0febb9 |
.I stat
|
|
|
0febb9 |
structure have led to three successive versions of
|
|
|
0febb9 |
@@ -548,17 +815,51 @@ structure have led to three successive versions of
|
|
|
0febb9 |
.IR __NR_stat ),
|
|
|
0febb9 |
and
|
|
|
0febb9 |
.I sys_stat64()
|
|
|
0febb9 |
-(new in kernel 2.4; slot
|
|
|
0febb9 |
-.IR __NR_stat64 ).
|
|
|
0febb9 |
+(slot
|
|
|
0febb9 |
+.IR __NR_stat64 )
|
|
|
0febb9 |
+on 32-bit platforms such as i386.
|
|
|
0febb9 |
+The first two versions were already present in Linux 1.0
|
|
|
0febb9 |
+(albeit with different names);
|
|
|
0febb9 |
+.\" See include/asm-i386/stat.h in the Linux 2.4 source code for the
|
|
|
0febb9 |
+.\" various versions of the structure definitions
|
|
|
0febb9 |
+the last was added in Linux 2.4.
|
|
|
0febb9 |
+Similar remarks apply for
|
|
|
0febb9 |
+.BR fstat ()
|
|
|
0febb9 |
+and
|
|
|
0febb9 |
+.BR lstat ().
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+The kernel-internal versions of the
|
|
|
0febb9 |
+.I stat
|
|
|
0febb9 |
+structure dealt with by the different versions are, respectively:
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.IR __old_kernel_stat
|
|
|
0febb9 |
+The original structure, with rather narrow fields, and no padding.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.IR stat
|
|
|
0febb9 |
+Larger
|
|
|
0febb9 |
+.I st_ino
|
|
|
0febb9 |
+field and padding added to various parts of the structure to
|
|
|
0febb9 |
+allow for future expansion.
|
|
|
0febb9 |
+.TP
|
|
|
0febb9 |
+.IR stat64
|
|
|
0febb9 |
+Even larger
|
|
|
0febb9 |
+.I st_ino
|
|
|
0febb9 |
+field,
|
|
|
0febb9 |
+larger
|
|
|
0febb9 |
+.I st_uid
|
|
|
0febb9 |
+and
|
|
|
0febb9 |
+.I st_gid
|
|
|
0febb9 |
+fields to accommodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits,
|
|
|
0febb9 |
+and various other enlarged fields and further padding in the structure.
|
|
|
0febb9 |
+(Various padding bytes were eventually consumed in Linux 2.6,
|
|
|
0febb9 |
+with the advent of 32-bit device IDs and nanosecond components
|
|
|
0febb9 |
+for the timestamp fields.)
|
|
|
0febb9 |
+.PP
|
|
|
0febb9 |
The glibc
|
|
|
0febb9 |
.BR stat ()
|
|
|
0febb9 |
wrapper function hides these details from applications,
|
|
|
0febb9 |
invoking the most recent version of the system call provided by the kernel,
|
|
|
0febb9 |
and repacking the returned information if required for old binaries.
|
|
|
0febb9 |
-Similar remarks apply for
|
|
|
0febb9 |
-.BR fstat ()
|
|
|
0febb9 |
-and
|
|
|
0febb9 |
-.BR lstat ().
|
|
|
0febb9 |
.\"
|
|
|
0febb9 |
.\" A note from Andries Brouwer, July 2007
|
|
|
0febb9 |
.\"
|
|
|
0febb9 |
@@ -587,6 +888,20 @@ and
|
|
|
0febb9 |
.\" interface, rather than the libc-kernel interface.
|
|
|
0febb9 |
.\"
|
|
|
0febb9 |
.\" (Note that the details depend on gcc being used as c compiler.)
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+On modern 64-bit systems, life is simpler: there is a single
|
|
|
0febb9 |
+.BR stat ()
|
|
|
0febb9 |
+system call and the kernel deals with a
|
|
|
0febb9 |
+.I stat
|
|
|
0febb9 |
+structure that contains fields of a sufficient size.
|
|
|
0febb9 |
+
|
|
|
0febb9 |
+The underlying system call employed by the glibc
|
|
|
0febb9 |
+.BR fstatat ()
|
|
|
0febb9 |
+wrapper function is actually called
|
|
|
0febb9 |
+.BR fstatat64 ()
|
|
|
0febb9 |
+or, on some architectures,
|
|
|
0febb9 |
+.\" strace(1) shows the name "newfstatat" on x86-64
|
|
|
0febb9 |
+.BR newfstatat ().
|
|
|
0febb9 |
.SH EXAMPLE
|
|
|
0febb9 |
The following program calls
|
|
|
0febb9 |
.BR stat ()
|
|
|
0febb9 |
@@ -600,6 +915,7 @@ structure.
|
|
|
0febb9 |
#include <time.h>
|
|
|
0febb9 |
#include <stdio.h>
|
|
|
0febb9 |
#include <stdlib.h>
|
|
|
0febb9 |
+#include <sys/sysmacros.h>
|
|
|
0febb9 |
|
|
|
0febb9 |
int
|
|
|
0febb9 |
main(int argc, char *argv[])
|
|
|
0febb9 |
@@ -616,6 +932,9 @@ main(int argc, char *argv[])
|
|
|
0febb9 |
exit(EXIT_FAILURE);
|
|
|
0febb9 |
}
|
|
|
0febb9 |
|
|
|
0febb9 |
+ printf("ID of containing device: [%lx,%lx]\\n",
|
|
|
0febb9 |
+ (long) major(sb.st_dev), (long) minor(sb.st_dev));
|
|
|
0febb9 |
+
|
|
|
0febb9 |
printf("File type: ");
|
|
|
0febb9 |
|
|
|
0febb9 |
switch (sb.st_mode & S_IFMT) {
|
|
|
0febb9 |
@@ -653,10 +972,11 @@ main(int argc, char *argv[])
|
|
|
0febb9 |
}
|
|
|
0febb9 |
.fi
|
|
|
0febb9 |
.SH SEE ALSO
|
|
|
0febb9 |
+.BR ls (1),
|
|
|
0febb9 |
+.BR stat (1),
|
|
|
0febb9 |
.BR access (2),
|
|
|
0febb9 |
.BR chmod (2),
|
|
|
0febb9 |
.BR chown (2),
|
|
|
0febb9 |
-.BR fstatat (2),
|
|
|
0febb9 |
.BR readlink (2),
|
|
|
0febb9 |
.BR utime (2),
|
|
|
0febb9 |
.BR capabilities (7),
|
|
|
0febb9 |
--
|
|
|
0febb9 |
2.7.4
|
|
|
0febb9 |
|