Provides information about a file or shared memory object.
Standard C Library (libc.a)
#include <sys/stat.h>int stat (Path, Buffer)
const char *Path;
struct stat *Buffer;int fstatat (DirFileDescriptor, Path, Buffer, Flag)
int DirFileDescriptor;
const char * Path;
struct stat * Buffer;
int Flag;int lstat (Path,Buffer)
const char *Path;
struct stat *Buffer;int fstat (FileDescriptor, Buffer)
int FileDescriptor;
struct stat *Buffer;int statx (Path, Buffer, Length, Command)
char *Path;
struct stat *Buffer;
int Length;
int Command;int statxat (DirFileDescriptor, Path, Buffer, Length, Command)
int DirFileDescriptor;
char * Path;
struct stat *Buffer;
int Length;
int Command;int fstatx (FileDescriptor, Buffer, Length, Command)
int FileDescriptor;
struct stat *Buffer;
int Length;
int Command;int stat64 (Path, Buffer)
const char *Path;
struct stat64 *Buffer;int stat64at (DirFileDescriptorPath, BufferFlag)
int DirFileDescriptor
const char *Path;
struct stat64 *Buffer;
int Flag;int lstat64 (Path, Buffer)
const char *Path;
struct stat64 *Buffer;int fstat64 (FileDescriptor, Buffer)
int FileDescriptor;
struct stat64 *Buffer;int stat64x (Path,Buffer)
const char *Path;
struct stat64x *Buffer;int stat64xat(DirFileDescriptor, Path, Buffer, Flag)
int DirFileDescriptor;
const char * Path;
struct stat64x * Buffer;
int Flag;int lstat64x (Path,Buffer)
const char *Path;
struct stat64x *Buffer;int fstat64x (FileDescriptor,Buffer)
int FileDescriptor;
struct stat64x *Buffer;#include <sys/fullstat.h>int fullstat (Path,Command, Buffer)
struct fullstat *Buffer;
char *Path;
int Command;int ffullstat (FileDescriptor,Command, Buffer)
int FileDescriptor;
int Command;
struct fullstat *Buffer;The stat subroutine obtains information about the file named by the Path parameter. Read, write, or execute permission for the named file is not required, but all directories listed in the path leading to the file must be searchable. The file information, which is a subset of the stat structure, is written to the area specified by the Buffer parameter.
The lstat subroutine obtains information about a file that is a symbolic link. The lstat subroutine returns information about the link, while the stat subroutine returns information about the file referenced by the link.
The fstat subroutine obtains information about the open file or shared memory object referenced by the FileDescriptor parameter. The fstatx subroutine obtains information about the open file or shared memory object referenced by the FileDescriptor parameter, as in the fstat subroutine.
The st_mode, st_dev, st_uid, st_gid, st_atime, st_ctime, and st_mtime fields of the stat structure have meaningful values for all file types. The statx, stat, lstat, fstatx, fstat, fullstat, or ffullstat subroutine sets the st_nlink field to a value equal to the number of links to the file.
The statx subroutine obtains a greater set of file information than the stat subroutine. The Path parameter is processed differently, depending on the contents of the Command parameter. The Command parameter provides the ability to collect information about symbolic links (as with the lstat subroutine) as well as information about mount points and hidden directories. The statx subroutine returns the amount of information specified by the Length parameter.
The fullstat and ffullstat subroutines are interfaces maintained for backward compatibility. With the exception of some field names, the fullstat structure is identical to the stat structure.
The stat64, lstat64, and fstat64 subroutines are similar to the stat, lstat, fstat subroutines except that they return file information in a stat64 structure instead of a stat structure. The information is identical except that the st_size field is defined to be a 64-bit size. This allows stat64, lstat64, and fstat64 to return file sizes which are greater than OFF_MAX (2 gigbytes minus 1).
In the large file enabled programming environment, stat is redefined to be stat64, lstat is redefined to be lstat64 and fstat is redefined to be fstat64.
This allows stat64x,fstat64x, and lstat64x to return the specified information in invariant 64-bit sizes, regardless of the mode of an application or the kernel it is running on.
If the i-node number is larger than the maximum number that can be represented in the stat structure, the returned i-node number has a value of -1. In this condition, use the stat64x subroutine to retrieve the accurate i-node number.
The statxat subroutine is equivalent to the statx subroutine if the DirFileDescriptor parameter is AT_FDCWD or the Path parameter is an absolute path name. If DirFileDescriptor is a valid file descriptor of an open directory and Path is a relative path name, Path is considered to be relative to the directory associated with the DirFileDescriptor parameter instead of the current working directory.
Similarly, the fstatat, stat64at, or stat64xat subroutine is equivalent to the stat, stat64, or stat64x subroutine, respectively, in the same way as statx and statxat if the Flag parameter does not have the AT_SYMLINK_NOFOLLOW bit set.
If the Flag parameter does have the AT_SYMLINK_NOFOLLOW bit set in the fstatat, stat64at, or stat64xat subroutine, then it is equivalent to the lstat, lstat64, or lstat64x subroutine, respectively.
If the Command parameter specifies the STX_LINK flag and the Path value refers to a symbolic link, the st_mode field of the returned stat structure indicates that the file is a symbolic link.
If the Command parameter specifies the STX_HIDDEN flag and Path refers to a hidden directory, the st_mode field of the returned stat structure indicates that this is a hidden directory.
If the Command parameter specifies the STX_MOUNT flag, the FS_MOUNT bit in the st_flag field of the returned stat structure is set if, and only if, this file is mounted over.
If the Command parameter does not specify the STX_MOUNT flag, the FS_MOUNT bit in the st_flag field of the returned stat structure is set if, and only if, this file is the root directory of a virtual file system.
For the fstatx subroutine, there are currently no special processing options. The only valid value for the Command parameter is the STX_NORMAL flag.
For the fullstat and ffullstat subroutines, the Command parameter may specify the FL_STAT flag, which is equivalent to the STX_NORMAL flag, or the FL_NOFOLLOW flag, which is equivalent to STX_LINK flag.
Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.
The stat, fstatat, lstat, statx, statxat, and fullstat subroutines are unsuccessful if one or more of the following are true:
| Item | Description |
|---|---|
| EACCES | Search permission is denied for one component of the path prefix. |
| ENAMETOOLONG | The length of the path prefix exceeds the PATH_MAX flag value or a path name is longer than the NAME_MAX flag value while the POSIX_NO_TRUNC flag is in effect. |
| ENOTDIR | A component of the path prefix is not a directory. |
| EFAULT | Either the Path or the Buffer parameter points to a location outside of the allocated address space of the process. |
| ENOENT | The file named by the Path parameter does not exist. |
| EOVERFLOW | The file size is larger than the maximum value that can be represented in the stat structure pointed to by the Buffer parameter. |
The stat, fstatat,lstat, statx, statxat, and fullstat subroutines can be unsuccessful for other reasons. See Base Operating System error codes for services that require path-name resolution for a list of additional errors.
The fstat,fstatx, andffullstat subroutines fail if one or more of the following are true:
| Item | Description |
|---|---|
| EBADF | The FileDescriptor parameter is not a valid file descriptor. |
| EFAULT | The Buffer parameter points to a location outside the allocated address space of the process. |
| EIO | An input/output (I/O) error occurred while reading from the file system. |
The statx, statxat, and fstatx subroutines are unsuccessful if one or more of the following are true:
| Item | Description |
|---|---|
| EINVAL | The Length value is not between 0 and the value returned by the STATSIZE macro, inclusive. |
| EINVAL | The Command parameter contains an unacceptable value. |
The statxat, fstatat, stat64at, and stat64xat subroutines are unsuccessful if one or more of the following are true:
| Item | Description |
|---|---|
| EBADF | The Path parameter does not specify an absolute path and the DirFileDescriptor parameter is neither AT_FDCWD nor a valid file descriptor. |
| ENOTDIR | The Path parameter does not specify an absolute path and the DirFileDescriptor parameter is neither AT_FDCWD nor a file descriptor associated with a directory. |
The fstatat, stat64at, and stat64xat subroutines are unsuccessful if the following is true:
| Item | Description |
|---|---|
| EINVAL | The Flag parameter is invalid. |
| Item | Description |
|---|---|
| /usr/include/sys/fullstat.h | Contains the fullstat structure. |
| /usr/include/sys/mode.h | Defines values on behalf of the stat.h file. |