'\" t
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
.\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
-.\" and Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" Modified by Michael Haardt <michael@moria.de>
.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
.\" 2007-06-08 mtk: Added example program
.\" 2007-07-05 mtk: Added details on underlying system call interfaces
.\"
-.TH STAT 2 2009-09-30 "Linux" "Linux Programmer's Manual"
+.TH STAT 2 2014-03-19 "Linux" "Linux Programmer's Manual"
.SH NAME
-stat, fstat, lstat \- get file status
+stat, fstat, lstat, fstatat \- get file status
.SH SYNOPSIS
+.nf
.B #include <sys/types.h>
.br
.B #include <sys/stat.h>
.br
.B #include <unistd.h>
.sp
-.BI "int stat(const char *" path ", struct stat *" buf );
+.BI "int stat(const char *" pathname ", struct stat *" buf );
.br
.BI "int fstat(int " fd ", struct stat *" buf );
.br
-.BI "int lstat(const char *" path ", struct stat *" buf );
+.BI "int lstat(const char *" pathname ", struct stat *" buf );
+.sp
+.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
+.B #include <sys/stat.h>
+.sp
+.BI "int fstatat(int " dirfd ", const char *" pathname ", struct stat *" \
+buf ,
+.BI " int " flags );
+.fi
.sp
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
+.ad l
+.PD 0
.sp
.BR lstat ():
-_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
+.RS 4
+_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
+_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
+.br
+|| /* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200112L
+.RE
+.sp
+.BR fstatat ():
+.PD 0
+.ad l
+.RS 4
+.TP 4
+Since glibc 2.10:
+_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
+.TP
+Before glibc 2.10:
+_ATFILE_SOURCE
+.RE
+.PD
+.ad
.SH DESCRIPTION
.PP
-These functions return information about a file.
-No permissions are required on the file itself, but \(em in the case of
-.BR stat ()
+These functions return information about a file, in the buffer pointed to by
+.IR stat .
+No permissions are required on the file itself, but\(emin the case of
+.BR stat (),
+.BR fstatat (),
and
-.BR lstat ()
-\(em
-execute (search) permission is required on all of the directories in
-.I path
+.BR lstat ()\(emexecute
+(search) permission is required on all of the directories in
+.I pathname
that lead to the file.
.PP
.BR stat ()
-stats the file pointed to by
-.I path
-and fills in
-.IR buf .
+and
+.BR fstatat ()
+retrieve information about the file pointed to by
+.IR pathname ;
+the differences for
+.BR fstatat ()
+are described below.
.BR lstat ()
is identical to
.BR stat (),
except that if
-.I path
-is a symbolic link, then the link itself is stat-ed,
+.I pathname
+is a symbolic link, then it returns information about the link itself,
not the file that it refers to.
.BR fstat ()
is identical to
.BR stat (),
-except that the file to be stat-ed is specified by the file descriptor
+except that the file about which information is to be retrieved
+is specified by the file descriptor
.IR fd .
.PP
All of these system calls return a
.in +4n
.nf
struct stat {
- dev_t st_dev; /* ID of device containing file */
- ino_t st_ino; /* inode number */
- mode_t st_mode; /* protection */
- nlink_t st_nlink; /* number of hard links */
- uid_t st_uid; /* user ID of owner */
- gid_t st_gid; /* group ID of owner */
- dev_t st_rdev; /* device ID (if special file) */
- off_t st_size; /* total size, in bytes */
- blksize_t st_blksize; /* blocksize for file system I/O */
- blkcnt_t st_blocks; /* number of 512B blocks allocated */
- time_t st_atime; /* time of last access */
- time_t st_mtime; /* time of last modification */
- time_t st_ctime; /* time of last status change */
+ dev_t st_dev; /* ID of device containing file */
+ ino_t st_ino; /* inode number */
+ mode_t st_mode; /* protection */
+ nlink_t st_nlink; /* number of hard links */
+ uid_t st_uid; /* user ID of owner */
+ gid_t st_gid; /* group ID of owner */
+ dev_t st_rdev; /* device ID (if special file) */
+ off_t st_size; /* total size, in bytes */
+ blksize_t st_blksize; /* blocksize for filesystem I/O */
+ blkcnt_t st_blocks; /* number of 512B blocks allocated */
+
+ /* Since Linux 2.6, the kernel supports nanosecond
+ precision for the following timestamp fields.
+ For the details before Linux 2.6, see NOTES. */
+
+ struct timespec st_atim; /* time of last access */
+ struct timespec st_mtim; /* time of last modification */
+ struct timespec st_ctim; /* time of last status change */
+
+#define st_atime st_atim.tv_sec /* Backward compatibility */
+#define st_mtime st_mtim.tv_sec
+#define st_ctime st_ctim.tv_sec
};
.fi
.in
-.PP
+
+.I Note:
+the order of fields in the
+.I stat
+structure varies somewhat
+across architectures.
+In addition,
+the definition above does not show the padding bytes
+that may be present between some fields on various architectures.
+Consult the the glibc and kernel source code
+if you need to know the details.
+
The
.I st_dev
field describes the device on which this file resides.
.I st_size
field gives the size of the file (if it is a regular
file or a symbolic link) in bytes.
-The size of a symlink is the length of the pathname
-it contains, without a trailing null byte.
+The size of a symbolic link is the length of the pathname
+it contains, without a terminating null byte.
The
.I st_blocks
The
.I st_blksize
-field gives the "preferred" blocksize for efficient file system I/O.
+field gives the "preferred" blocksize for efficient filesystem I/O.
(Writing to a file in smaller chunks may cause
an inefficient read-modify-rewrite.)
.PP
-Not all of the Linux file systems implement all of the time fields.
-Some file system types allow mounting in such a way that file
+Not all of the Linux filesystems implement all of the time fields.
+Some filesystem types allow mounting in such a way that file
and/or directory accesses do not cause an update of the
.I st_atime
field.
FIFO (named pipe)?
.TP
.BR S_ISLNK (m)
-symbolic link? (Not in POSIX.1-1996.)
+symbolic link? (Not in POSIX.1-1996.)
.TP
.BR S_ISSOCK (m)
-socket? (Not in POSIX.1-1996.)
+socket? (Not in POSIX.1-1996.)
.RE
.PP
The following flags are defined for the
S_IFDIR 0040000 directory
S_IFCHR 0020000 character device
S_IFIFO 0010000 FIFO
-S_ISUID 0004000 set UID bit
+S_ISUID 0004000 set-user-ID bit
S_ISGID 0002000 set-group-ID bit (see below)
S_ISVTX 0001000 sticky bit (see below)
S_IRWXU 00700 mask for file owner permissions
S_IRGRP 00040 group has read permission
S_IWGRP 00020 group has write permission
S_IXGRP 00010 group has execute permission
-S_IRWXO 00007 mask for permissions for others (not in group)
+S_IRWXO 00007 T{
+mask for permissions for others (not in group)
+T}
S_IROTH 00004 others have read permission
S_IWOTH 00002 others have write permission
S_IXOTH 00001 others have execute permission
in that directory can be renamed or deleted only by the owner
of the file, by the owner of the directory, and by a privileged
process.
-.SH "RETURN VALUE"
+.\"
+.\"
+.SS fstatat()
+The
+.BR fstatat ()
+system call operates in exactly the same way as
+.BR stat (),
+except for the differences described here.
+
+If the pathname given in
+.I pathname
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I dirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR stat ()
+for a relative pathname).
+
+If
+.I pathname
+is relative and
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I pathname
+is interpreted relative to the current working
+directory of the calling process (like
+.BR stat ()).
+
+If
+.I pathname
+is absolute, then
+.I dirfd
+is ignored.
+
+.I flags
+can either be 0, or include one or more of the following flags ORed:
+.TP
+.BR AT_EMPTY_PATH " (since Linux 2.6.39)"
+.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
+If
+.I pathname
+is an empty string, operate on the file referred to by
+.IR dirfd
+(which may have been obtained using the
+.BR open (2)
+.B O_PATH
+flag).
+If
+.I dirfd
+is
+.BR AT_FDCWD ,
+the call operates on the current working directory.
+In this case,
+.I dirfd
+can refer to any type of file, not just a directory.
+This flag is Linux-specific; define
+.B _GNU_SOURCE
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
+to obtain its definition.
+.TP
+.BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
+Don't automount the terminal ("basename") component of
+.I pathname
+if it is a directory that is an automount point.
+This allows the caller to gather attributes of an automount point
+(rather than the location it would mount).
+This flag can be used in tools that scan directories
+to prevent mass-automounting of a directory of automount points.
+The
+.B AT_NO_AUTOMOUNT
+flag has no effect if the mount point has already been mounted over.
+This flag is Linux-specific; define
+.B _GNU_SOURCE
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
+to obtain its definition.
+.TP
+.B AT_SYMLINK_NOFOLLOW
+If
+.I pathname
+is a symbolic link, do not dereference it:
+instead return information about the link itself, like
+.BR lstat ().
+(By default,
+.BR fstatat ()
+dereferences symbolic links, like
+.BR stat ().)
+.PP
+See
+.BR openat (2)
+for an explanation of the need for
+.BR fstatat ().
+.SH RETURN VALUE
On success, zero is returned.
On error, \-1 is returned, and
.I errno
.B EACCES
Search permission is denied for one of the directories
in the path prefix of
-.IR path .
+.IR pathname .
(See also
.BR path_resolution (7).)
.TP
Too many symbolic links encountered while traversing the path.
.TP
.B ENAMETOOLONG
-File name too long.
+.I pathname
+is too long.
.TP
.B ENOENT
A component of
-.I path
+.I pathname
does not exist, or
-.I path
+.I pathname
is an empty string.
.TP
.B ENOMEM
.TP
.B ENOTDIR
A component of the path prefix of
-.I path
+.I pathname
is not a directory.
.TP
.B EOVERFLOW
-.RB ( stat ())
-.I path
-refers to a file whose size cannot be represented in the type
-.IR off_t .
-This can occur when an application compiled on a 32-bit platform without
+.I pathname
+or
+.I fd
+refers to a file whose size, inode number,
+or number of blocks cannot be represented in, respectively, the types
+.IR off_t ,
+.IR ino_t ,
+or
+.IR blkcnt_t .
+This error can occur when, for example,
+an application compiled on a 32-bit platform without
.I -D_FILE_OFFSET_BITS=64
calls
.BR stat ()
on a file whose size exceeds
-.I (2<<31)-1
-bits.
-.SH "CONFORMING TO"
-These system calls conform to SVr4, 4.3BSD, POSIX.1-2001.
+.I (1<<31)-1
+bytes.
+.PP
+The following additional errors can occur for
+.BR fstatat ():
+.TP
+.B EBADF
+.I dirfd
+is not a valid file descriptor.
+.TP
+.B EINVAL
+Invalid flag specified in
+.IR flags .
+.TP
+.B ENOTDIR
+.I pathname
+is relative and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
+.SH VERSIONS
+.BR fstatat ()
+was added to Linux in kernel 2.6.16;
+library support was added to glibc in version 2.4.
+.SH CONFORMING TO
+.BR stat (),
+.BR fstat (),
+.BR lstat ():
+SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008.
.\" SVr4 documents additional
.\" .BR fstat ()
.\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4
.\" .BR lstat ()
.\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
+.BR fstatat ():
+POSIX.1-2008.
+
+According to POSIX.1-2001,
+.BR lstat ()
+on a symbolic link need return valid information only in the
+.I st_size
+field and the file-type component of the
+.IR st_mode
+field of the
+.IR stat
+structure.
+POSIX.1-2008 tightens the specification, requiring
+.BR lstat ()
+to return valid information in all fields except the permission bits in
+.IR st_mode .
+
Use of the
.I st_blocks
and
(They were introduced in BSD.
The interpretation differs between systems,
and possibly on a single system when NFS mounts are involved.)
+If you need to obtain the definition of the
+.IR blkcnt_t
+or
+.IR blksize_t
+types from
+.IR <sys/stat.h> ,
+then define
+.BR _XOPEN_SOURCE
+with the value 500 or greater (before including
+.I any
+header files).
.LP
-POSIX does not describe the
+POSIX.1-1990 did not describe the
.BR S_IFMT ,
.BR S_IFSOCK ,
.BR S_IFLNK ,
.BR S_IFCHR ,
.BR S_IFIFO ,
.B S_ISVTX
-bits, but instead demands the use of
+constants, but instead demanded the use of
the macros
.BR S_ISDIR (),
-etc.
+and so on.
+The
+.BR S_IF*
+constants are present in POSIX.1-2001 and later.
+
The
.BR S_ISLNK ()
and
POSIX.1-1996, but both are present in POSIX.1-2001;
the former is from SVID 4, the latter from SUSv2.
.LP
-Unix V7 (and later systems) had
+UNIX V7 (and later systems) had
.BR S_IREAD ,
.BR S_IWRITE ,
.BR S_IEXEC ,
.BR S_IRUSR ,
.BR S_IWUSR ,
.BR S_IXUSR .
-.SS "Other Systems"
+.SS Other systems
Values that have been (or are) in use on various systems:
+.ad l
.TS
l l l l l.
hex name ls octal description
f000 S_IFMT 170000 mask for file type
-0000 000000 SCO out-of-service inode; BSD unknown
- type; SVID-v2 and XPG2 have both
- 0 and 0100000 for ordinary file
+0000 000000 T{
+SCO out-of-service inode; BSD unknown type; SVID-v2 and XPG2
+have both 0 and 0100000 for ordinary file
+T}
1000 S_IFIFO p| 010000 FIFO (named pipe)
2000 S_IFCHR c 020000 character special (V7)
3000 S_IFMPC 030000 multiplexed character special (V7)
4000 S_IFDIR d/ 040000 directory (V7)
-5000 S_IFNAM 050000 XENIX named special file
- with two subtypes, distinguished by
- \fIst_rdev\fP values 1, 2
+5000 S_IFNAM 050000 T{
+XENIX named special file with two subtypes, distinguished by
+\fIst_rdev\fP values 1, 2
+T}
0001 S_INSEM s 000001 XENIX semaphore subtype of IFNAM
0002 S_INSHD m 000002 XENIX shared data subtype of IFNAM
6000 S_IFBLK b 060000 block special (V7)
9000 S_IFCMP 110000 VxFS compressed
9000 S_IFNWK n 110000 network special (HP-UX)
a000 S_IFLNK l@ 120000 symbolic link (BSD)
-b000 S_IFSHAD 130000 Solaris shadow inode for ACL
- (not seen by userspace)
+b000 S_IFSHAD 130000 T{
+Solaris shadow inode for ACL (not seen by user space)
+T}
c000 S_IFSOCK s= 140000 socket (BSD; also "S_IFSOC" on VxFS)
d000 S_IFDOOR D> 150000 Solaris door
e000 S_IFWHT w% 160000 BSD whiteout (not used for inode)
-0200 S_ISVTX 001000 sticky bit: save swapped text even
- after use (V7)
- reserved (SVID-v2)
- On nondirectories: don't cache this
- file (SunOS)
- On directories: restricted deletion
- flag (SVID-v4.2)
-0400 S_ISGID 002000 set-group-ID on execution (V7)
- for directories: use BSD semantics for
- propagation of GID
-0400 S_ENFMT 002000 System V file locking enforcement (shared
- with S_ISGID)
+0200 S_ISVTX 001000 T{
+sticky bit: save swapped text even after use (V7)
+.br
+reserved (SVID-v2)
+.br
+On nondirectories: don't cache this file (SunOS)
+.br
+On directories: restricted deletion flag (SVID-v4.2)
+T}
+0400 S_ISGID 002000 T{
+set-group-ID on execution (V7)
+.br
+for directories: use BSD semantics for propagation of GID
+T}
+0400 S_ENFMT 002000 T{
+System V file locking enforcement (shared with S_ISGID)
+T}
0800 S_ISUID 004000 set-user-ID on execution (V7)
-0800 S_CDF 004000 directory is a context dependent
- file (HP-UX)
+0800 S_CDF 004000 T{
+directory is a context dependent file (HP-UX)
+T}
.TE
+.ad
A sticky command appeared in Version 32V AT&T UNIX.
.SH NOTES
-Since kernel 2.5.48, the
-.I stat
-structure supports nanosecond resolution for the three
-file timestamp fields.
-Glibc exposes the nanosecond component of each field using names either
-of the form
-.IR st_atim.tv_nsec ,
-if the
-.B _BSD_SOURCE
-or
-.B _SVID_SOURCE
-feature test macro is defined,
-or of the form
-.IR st_atimensec ,
-if neither of these macros is defined.
-On file systems that do not support subsecond timestamps,
-these nanosecond fields are returned with the value 0.
-.\" As at kernel 2.6.25, XFS and JFS support nanosecond timestamps,
-.\" but ext2, ext3, and Reiserfs do not.
-.\" FIXME . SUSv4 specifies nanosecond timestamps.
-
On Linux,
.BR lstat ()
will generally not trigger automounter action, whereas
.BR stat ()
-will.
+will (but see
+.BR fstatat (2)).
For most files under the
.I /proc
does not return the file size in the
.I st_size
field; instead the field is returned with the value 0.
+.SS Timestamp fields
+Older kernels and older standards did not support nanosecond timestamp
+fields.
+Instead, there were three timestamp
+.RI fields\(em st_atime ,
+.IR st_mtime ,
+and
+.IR st_ctime \(emtyped
+as
+.IR time_t
+that recorded timestamps with one-second precision.
+
+Since kernel 2.5.48, the
+.I stat
+structure supports nanosecond resolution for the three file timestamp fields.
+The nanosecond components of each timestamp are available
+via names of the form
+.IR st_atim.tv_nsec
+if the
+.B _BSD_SOURCE
+or
+.B _SVID_SOURCE
+feature test macro is defined.
+Nanosecond timestamps are nowadays standardized,
+starting with POSIX.1-2008, and, starting with version 2.12,
+glibc also exposes the nanosecond component names if
+.BR _POSIX_C_SOURCE
+is defined with the value 200809L or greater, or
+.BR _XOPEN_SOURCE
+is defined with the value 700 or greater.
+If none of the aforementioned macros are defined,
+then the nanosecond values are exposed with names of the form
+.IR st_atimensec .
+
+Nanosecond timestamps are supported on XFS, JFS, Btrfs, and
+ext4 (since Linux 2.6.23).
+.\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80
+Nanosecond timestamps are not supported in ext2, ext3, and Resierfs.
+On filesystems that do not support subsecond timestamps,
+the nanosecond fields are returned with the value 0.
.SS Underlying kernel interface
Over time, increases in the size of the
.I stat
.\" interface, rather than the libc-kernel interface.
.\"
.\" (Note that the details depend on gcc being used as c compiler.)
+
+The underlying system call employed by the glibc
+.BR fstatat ()
+wrapper function is actually called
+.BR fstatat64 ().
.SH EXAMPLE
The following program calls
.BR stat ()
exit(EXIT_SUCCESS);
}
.fi
-.SH "SEE ALSO"
+.SH SEE ALSO
+.BR ls (1),
+.BR stat (1),
.BR access (2),
.BR chmod (2),
.BR chown (2),
-.BR fstatat (2),
.BR readlink (2),
.BR utime (2),
.BR capabilities (7),
.BR symlink (7)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
