STAT(2)

NAME

stat, lstat, fstat − get file status

SYNOPSIS

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

int stat (path, buf)
char ∗path;
struct stat ∗buf;

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

int fstat (fildes, buf)
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(2), creat(2), dup(2), fcntl(2), or pipe(2) system call.

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 the 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_tst_dev; /* ID of device containing a */
/* directory entry for this file */

ino_tst_ino; /* Inode number */

ushortst_fstype; /* Type of filesystem this file */
/* is in; see vfsmount(OS) */

ushortst_mode; /* File type, attributes, and */
/* access control summary */

ushortst_basemode /* Permission bits (see chmod(1)) */

ushortst_nlink; /* Number of links */

uid_tst_uid; /* User ID of file owner */

gid_tst_gid; /* Group ID of file group */

dev_tst_rdev; /* Device ID; this entry defined */
/* only for char or blk spec files */

off_tst_size; /* File size (bytes) */

time_tst_atime; /* Time of last access */

time_tst_mtime; /* Last modification time */

time_tst_ctime; /* Last file status change time */
/* Measured in secs since */
/* 00:00:00 GMT, Jan 1, 1970 */

uintst_acl:1; /* Set if the file has optional */
/* access control list entries */

st_atime Field indicating when file data was last accessed. Changed by the following system calls: creat(2), mknod(2), pipe(2), read(2), readv (on read(2)), and utime(2).

st_mtime Field indicating when data was last modified. Changed by the following system calls: creat(2), truncate(2), ftruncate (on truncate(2)), mknod(2), pipe(2), prealloc(2), utime(2), write(2), and writev (on write(2)). Also changed by close(2) when the reference count reaches zero on a named pipe (FIFO special) file that contains data.

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

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

st_mode The value returned in this field is the bitwise 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 superusers, 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(2) clears this bit under these conditions.

NETWORKING FEATURES

RFA

The contents of the structure stat pointed to by buf also include the following members:

uintst_remote:1; /* Set if file is remote */

dev_tst_netdev; /* ID of device containing */
/* network special file */

ino_tst_netino; /* Inode number of network special file */

st_remote Field indicating whether the file is on a remote node. A zero value indicates that the file is on the local node; non-zero indicates that the file is on a remote node, and accessed through remote file access (RFA). Not all HP-UX systems support RFA; st_remote is always zero on non-RFA supported systems.

st_netdev, st_netino All remote file access takes place through a special file in the local file system known as a network special file. Each network special file identifies a particular remote node. When st_remote is non-zero, st_netdev and st_netino identify the appropriate network special file; otherwise these fields are zero.

RETURN VALUE

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

ERRORS

Stat or lstat fails if any of the following is true:

[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 is true:

[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_tst_cnode;/* Cnode ID of machine */
/* where the inode lives */
cnode_tst_rcnode/* Cnode ID where this */
/* device file can be used */
dev_tst_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.

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

AUTHOR

Stat and fstat were developed by AT&T. Lstat was developed by the University of California, Berkeley.

STANDARDS CONFORMANCE

stat: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1

fstat: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1

Hewlett-Packard Company — HP-UX Release 7.0: Sept 1989

Museum

Related Articles