stat(2)

NAME

stat, lstat, fstat − get file status

SYNOPSIS

#include <sys/stat.h>

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

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

int fstat(int fildes, struct stat *buf);

DESCRIPTION

stat() obtains information about the named file.

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

Similarly, fstat() obtains information about an open file known by the file descriptor fildes, obtained from a successful open(), creat(), dup(), fcntl(), or pipe() system call (see open(2), creat(2), dup(2), fcntl(2), or pipe(2)).

lstat() is similar to stat() except when the named file is a symbolic link, in which case lstat() returns the information about the link, while stat() returns information about the file to which the link points.

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

The contents of structure stat() pointed to by buf include the following members. Note that there is no necessary correlation between the placement in this list and the order in the structure.

dev_t    st_dev;       /* ID of device containing a */
                       /* directory entry for this file */
ino_t    st_ino;       /* Inode number */
ushort    st_fstype;   /* Type of filesystem this file */
                       /* is in; see vfsmount(2) */
ushort    st_mode;     /* File type, attributes, and */
                       /* access control summary */
ushort    st_basemode /* Permission bits (see chmod(1)) */
ushort    st_nlink;    /* Number of links */
uid_t    st_uid;       /* User ID of file owner */
gid_t    st_gid;       /* Group ID of file group */
dev_t    st_rdev;      /* Device ID; this entry defined */
                       /* only for char or blk spec files */
off_t    st_size;      /* File size (bytes) */
time_t    st_atime;    /* Time of last access */
time_t    st_mtime;    /* Last modification time */
time_t    st_ctime;    /* Last file status change time */
                       /* Measured in secs since */
                       /* 00:00:00 GMT, Jan 1, 1970 */
uint    st_acl:1;      /* Set if the file has optional */
                       /* access control list entries */

Field contents are as follows:

st_atime Time when file data was last accessed. Changed by the following system calls: creat(), mknod(), pipe(), read(), readv() (see read(2)), and utime(). If a file is mapped into virtual memory, accesses of file data through the mapping may also modify st_mtime. See mmap(2).

st_mtime Time when data was last modified. Changed by the following system calls: creat(), truncate(), ftruncate(), (see truncate(2)), mknod(), pipe(), prealloc(), utime(), write(), and writev() (see write(2)). Also changed by close() when the reference count reaches zero on a named pipe ( FIFO special) file that contains data. If a file is mapped into virtual memory, updates of file data through the mapping may also modify st_mtime. See mmap(2).

st_ctime Time when file status was last changed. Changed by the following system calls: chmod(), chown(), creat(), fchmod(), fchown(), truncate(), ftruncate(), (see truncate(2)), link(), mknod(), pipe(), prealloc(), rename(), setacl(), unlink(), utime(), write(), and writev() (see write(2)).

The touch command (see touch(1) can be used to explicitly control the times of a file.

st_mode The value returned in this field is the bit-wise inclusive OR of a value indicating the file’s type, attribute bits, and a value summarizing its access permission. See mknod(2).

For ordinary users, the least significant nine bits consist of the file’s permission bits modified to reflect the access granted or denied to the caller by optional entries in the file’s access control list.

For users with appropriate privileges
the least significant nine bits are the file’s access permission bits. In addition, the S_IXUSR (execute by owner) mode bit is set if the following conditions are met:

• The file is a regular file,

• No permission execute bits are set, and

• An execute bit is set in one or more of the file’s optional access control list entries.

The write bit is not cleared for a file on a read-only file system or a shared-text program file that is being executed. However, getaccess() clears this bit under these conditions (see getaccess(2).

RETURN VALUE

Upon successful completion, 0 is returned. Otherwise, −1 is returned and errno is set to indicate the error.

ERRORS

stat() and lstat() fail if any of the following conditions are encountered:

[ENOTDIR] A component of the path prefix is not a directory.

[ENOENT] The named file does not exist (for example, path is null or a component of path does not exist).

[EACCES] Search permission is denied for a component of the path prefix.

[EFAULT] buf or path points to an invalid address. The reliable detection of this error is implementation dependent.

[ELOOP] Too many symbolic links were encountered in translating the path name.

[ENAMETOOLONG] The length of the specified path name exceeds PATH_MAX bytes, or the length of a component of the path name exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in effect.

fstat() fails if any of the following conditions are encountered:

[EBADF] fildes is not a valid open file descriptor.

[EFAULT] buf points to an invalid address. The reliable detection of this error is implementation dependent.

DEPENDENCIES

HP Clustered Environment

The contents of the stat() structure include the following additional members:

cnode_t     st_cnode;      /* cnode ID of machine */
                           /* where the inode lives */
cnode_t     st_rcnode      /* cnode ID where this */
                           /* device file can be used */
dev_t       st_realdev;    /* Real device number of device */
                           /* containing the inode for this file */

st_dev The ID number for the volume on which the inode exists. This number may or may not be the device number for the device containing the volume. Device numbers are not unique throughout a cluster, but the value of st_dev is guaranteed to be unique among all volumes currently mounted in the file system. The device number for the volume can always be found in the field st_realdev, which, together with st_cnode, fully specifies the device containing the volume.

CD-ROM

The st_uid and st_gid fields are set to −1 if they are not specified on the disk for a given file.

NFS

The st_basemode and st_acl fields are zero on files accessed remotely.

WARNINGS

Access Control Lists

Access control list descriptions in this entry apply only to standard HP-UX operating systems. If HP-UX BLS software has been installed, access control lists are handled differently. Refer to HP-UX BLS documentation for information about access control lists in the HP-UX BLS environment.

AUTHOR

stat() and fstat() were developed by AT&T. lstat() was developed by the University of California, Berkeley.

STANDARDS CONFORMANCE

stat(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

fstat(): AES, SVID2, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

lstat(): AES

Hewlett-Packard Company — HP-UX Release 9.0: August 1992

Museum

Related Articles