stat, stat64, statx, stat64x - get file status

Syntax

#include <sys/stat.h>
#include <sys/types.h>

int stat (const char *path, struct stat *buf);
int stat64 (const char *path, struct stat64 *buf);

CRTE111A30

int statx(const char *path, struct statx *buf);
int stat64x(const char *path, struct stat64x *buf); (End)

Description

stat() obtains information about the named file and writes it to the area pointed to by buf.

path points to a pathname naming a file. Read, write or execute permission of the named file is not required, but all directories listed in the pathname leading to the file must be searchable.

buf is a pointer to a structure of type stat, as defined in the header file sys/stat.h, into which information concerning the file is placed.

stat() updates any time-related structure components, as described in the definition of "File times update" in the glossary, before writing into the stat structure.

The structure components st_mode, st_ino, st_dev, st_uid, st_gid, st_atime, st_ctime and st_mtime will then have meaningful values for all file types. The value of the structure component st_nlink will be set to the number of links to the file.

There is no difference in functionality between stat() and stat64() except that stat64() uses a stat64 structure.

The functions with the suffix x behave like the functions of the same name without a suffix, except that they return the file status in a corresponding stat structure with suffix x and therefore will work correctly after 01/19/2038 03:14:07 UTC.

The stat structure pointed to by buf contains the following elements:

mode_t    st_mode;    /* File mode (see mknod()) */
ino_t     st_ino;     /* Inode number */
dev_t     st_dev;     /* Device ID which contains a directory entry for
                         this file */
dev_t     st_rdev;    /* Device ID, defined for character-special or
                         block-special files only */
nlink_t   st_nlink;   /* Number of links */
uid_t     st_uid;     /* User ID of the file owner */
gid_t     st_gid;     /* Group ID of the file owner */
off_t     st_size;    /* File size in bytes */
time_t    st_atime;   /* Time of the last access */
time_t    st_mtime;   /* Time of the last data modification */
time_t    st_ctime;   /* Time of the last change of file status
                         The time is measured in seconds as of
                         January 1, 1970, 00:00:00 */

Extension

long     st_blksize; /* Preferred I/O block size */
blkcnt_t st_blocks;  /* Number of assigned st_blksize blocks */

(End)

The elements of the structure stat64 structure are defined like the stat structure except for the following components:

ino64_t st_ino
off64_t st_size and
blkcnt64_t st_blocks

The elements of the structures statx and stat64x are defined like those of the structures stat bzw. stat64, with the exception of the following components:

time64_t    st_atime;
time64_t    st_mtime;
time64_t    st_ctime; 

The elements of the structure have the following meanings:

st_mode	The mode of the file is defined in the system call mknod().
st_ino	Uniquely identifies the file in a given file system. The pair st_ino and  st_dev uniquely identifies regular files.
st_dev	Uniquely identifies the file system that contains the file.
st_rdev	May be used only by administrative commands. This flag is valid only for block special or character special files and only has meaning on the system where the file was configured.
st_nlink	May be used only by administrative commands.
st_uid	The user ID of the file's owner.
st_gid	Group ID of the group to which the file is assigned.
st_size	For regular files, this is the size of the file in bytes. It is undefined for block special or character special files. For PAM files this member contains the file size. Any existing marker is not considered. If the LBP is zero, the entire last block counts to the size.
st_atime	Time when file data was last accessed. Modified by the following system calls: creat(), mknod(), utime() and read().
st_mtime	Time when data was last updated. Modified by the following system calls:  creat(), mknod(), utime() and write().
st_ctime	Time when the file status was last changed. Modified by the following system calls: chmod(), chown(), creat(), link(), mknod(), unlink(),  utime() and write().
Extension
st_blksize	A hint as to the 'best' unit size for I/O operations. This field is not defined for block special or character special files.
st_blocks	The total number of physical blocks of size 512 bytes currently used on disk. This field is not defined for block special or character special files. (End)

BS2000

With BS2000 files the following elements of the stat structure are set:

mode_t st_mode	File mode containing the access permissions and file type. Access permissions: here the Basic ACL is mapped to the file mode bits. The mode bits are all 0 if the file does not have Basic ACL protection. File type: introduces a new file type S_IFDVSBS2=X'10000000'. This type, however, is not disjoint to S_IFPOSIXBS2. The S_ISD-VSBS2(mode) macro can be used for querying. Introduces a new file type S_IFDVSNODE=X'20000000'. This type is also not disjoint to S_IFPOSIXBS2. The S_ISDVSNODE(mode) macro can be used for querying. A node file is also a BS2000 DVS file. I.e. for node files the bit S_IFDVSBS2 is always set.
time_t st_atime	Last access time, as is usual in BS2000 but in seconds since 1.1.1970 UTC.
time_t st_mtime	Last modification time.
time_t st_ctime	Creation time.
long st_blksize	Block size, 2K (i.e. 1 PAM page).
long st_blocks	Number of blocks occupied by the file on the disk.
dev_t st_dev	Contains the 4-byte catid.
The two consecutive fields
uid_t st_uid gid_t st_uid	and contain the 8-byte BS2000 user ID.
All other fields are set to 0.

(End)

Return val.

0

if successful.

-1

if an error occurs. For  POSIX files errno is set to indicate the error.

Errors

stat(), stat64(), statx() and stat64x will fail if: 

 

EACCES

Search permission is denied for a component of the path.

 

Extension

 

EFAULT

buf or path points to an invalid address.

 

EINTR

A signal was caught during the stat() or lstat() system call.

 

EINVAL

The named file does not exist or the path argument points to an empty string. (End)

 

EIO

An I/O error occurred while reading the file system.

 

ELOOP

Too many symbolic links were encountered in resolving path.

 

Extension

 

EMULTIHOP

Components of path require hops to several remote computers, but the file system does not permit this. (End)

 

ENAMETOOLONG 

The length of path exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX} and {_POSIX_NO_TRUNC} is in effect.

 

Extension 

 

ENOLINK

path refers to a remote computer to which there is no active connection. (End)

 

ENOENT

The specified file does not exist or the path is the null path.

 

ENOTDIR

A component of the path is not a directory.

 

EOVERFLOW

A component is too large to be stored in the structure pointed to by buf.

stat() and stat64() fail when the following applies: 
Extension

 

EOVERFLOW

A timestamp is too large for a time-t component (this will happen after 01/19/2038 03:14:07 a.m. UTC). (End)

statx() and stat64x() fail when the following applies: 

 

EINVAL

POSIX-BC correction status < A47.

See also

chmod(), chown(), creat(), fstat(), lstat(), link(), mknod(), sys/stat.h,  sys/types.h.