fstat, fstat64, fstatx, fstat64x, fstatat, fstatat64, fstatatx, fstatat64x - get file status of open file

Syntax

#include <sys/stat.h>

Optional
#include <sys/types.h> (End)

int fstat(int fildes, struct stat *buf);
int fstat64(int fildes, struct stat64 *buf);
int fstatat(int fd, const char *path, struct stat *buf, int flag);
int fstatat64(int fd, const char *path, struct stat64 *buf, int flag); 

CRTE111A30
int fstatx(int fildes, struct statx *buf);
int fstat64x(int fildes, struct stat64x *buf);
int fstatatx(int fd, const char *path, struct statx *buf, int flag);
int fstatat64x(int fd, const char *path, struct stat64x *buf, int flag); (End)

 Description

fstat() obtains information on an open file associated with the file descriptor fildes, which is returned by a successful open(), creat(), dup(), fcntl() or pipe() system call.

buf is a pointer to a stat structure into which information concerning the respective file is placed.

There is no difference in functionality between fstat() and fstat64() except that fstat64() returns the file status in 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 contents of the structure pointed to by buf include the following members:

mode_t    st_mode;    /* File mode (see mknod()) */
ino_t     st_ino;     /* Inode number (i-Node) */
dev_t     st_dev;     /* ID of device containing a
                        directory entry for this file */
dev_t     st_rdev;    /* Device ID, only defined for 
                        character special or block special files */
nlink_t   st_nlink;   /* Number of links */
uid_t     st_uid;     /* User ID of the file's owner */
gid_t     st_gid;     /* Group ID of the file's group */
off_t     st_size;    /* File size in bytes */
time_t    st_atime;   /* Time of last access */
time_t    st_mtime;   /* Time of last data modification */
time_t    st_ctime;   /* Time of last file status change
                        The time is measured in seconds since
                        00:00:00 UTC, Jan 1, 1970 */
long      st_blksize; /* Preferred I/O block size */
blkcnt_t   st_blocks;   /* Number of st_blksize blocks allocated */

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 have the following meanings:

st_mode	The mode of the file is defined in the system call mknod(). Apart from the modes defined in mknod(), the mode of a file can be S_IFLNK if the file is a symbolic link, or S_IFSOCK if a socket descriptor is involved.
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. It 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	The group ID of the file's group.
st_size	For regular files, this is the address of the end of the file. 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(), pipe(), utime() and read().
st_mtime	Time when data was last updated. Modified by the following system calls: creat(), mknod(), pipe(), utime() and write().
st_ctime	Time when the file status was last changed. Modified by the following system calls: chmod(), chown(), creat(), link(), mknod(), pipe(), unlink(), utime() and write().
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 actually allocated on disk. This field is not defined for block special or character special files.

The elements have the following meanings:

BS2000

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

mode_t st_mode

File mode containing access permissions and file type.

Access permissions:

Here the Basic ACL is mapped to the file mode bits. The file mode bits are all 0 if the file does not have basic ACL protection.

File type:

Introduction of a new file type S_IFDVSBS2=X'10000000'. This type is, however, not disjoint to S_IFPOSIXBS2. The S_ISDVSBS2(mode) macro can be used to query.

Introduction of 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 to query.

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 on the disk that are occupied by the file.

dev_t st_dev

Contains the 4-byte catalog ID.

 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.

The fstatat() and fstatat64() functions are equivalent to the stat() and stat64() and the lstat() and lstat64() functions depending on the value flag except when the path parameter specifies a relative path. In this case the file whose status to be determined is not searched for in the current directory, but in the directory connected with the file descriptor fd. If the file descriptor was opened without O_SEARCH, the functions check whether a search is permitted in the connected directory with the authorizations applicable for the directory. If the file descriptor was opened with O_SEARCH, the check is not performed.

In the flag parameter, the value AT_SYMLINK_NOFOLLOW, which is defined in the fnctl.h header, can be transferred. If path specifies a symbolic link, the status of the symbolic link is returned.

The functions with the suffix x behave like the functions of the same name without a suffix, except that they also working correctly after 01/19/2038 03:14:07 UTC.

Return val.

0

if successful.

-1

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

Errors

fstat(), fstat64(), fstatat(), fstatat64(), fstatx(), fstat64x(), fstatatx() and fstatat64x() will fail if:

 

EBADF

fildes is not a valid file descriptor.

 

EFAULT

buf points to an invalid address.

 

EIO

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

 

ENOLINK

fildes refers to a remote computer, whereby the connection to this computer is not active anymore.

 

EOVERFLOW

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

 

EINTR

A signal was caught during the fstat() system call.

fstat(), fstat64(), fstatat() and fstatat64() 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)

fstatat() and fstatat64() fail when the following applies: 

 

EACCES

The fd parameter was not opened with O_SEARCH, and the authorizations applicable for the directory do not permit the directory to be searched.

 

EBADF

The path parameter does not specify an absolute pathname, and the fd parameter does not have the value AT_FDCWD, nor does it contain a valid file descriptor opened for reading or searching.

 

ENOTDIR

The path parameter does not specify an absolute pathname, and the file descriptor fd is not connected with a directory.

 

EINVAL

The value of the flag parameter is invalid.

fstatx() and fstat64x() fail when the following applies: 

 

EINVAL

POSIX-BC correction status < A47.

fstatatx() and fstatat64x() fail when the following applies: 

 

ENOSYS

POSIX-BC correction status < A47.

See also

chmod(), chown(), creat(), link(), lstat(), mknod(), stat(), unlink(), write(), fcntl.h, sys/stat.h, sys/types.h.