stat(2)

NAME

stat, fstat, lstat − get file status

SYNOPSIS

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

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

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

SYNOPSIS (4.2BSD)

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

DESCRIPTION

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. stat obtains information about the named file.

Similarly, fstat obtains information about an open file known by the file descriptor fildes, obtained from a successful open, creat, shm_open, dup, fcntl, or pipe system call. When fildes refers to a socket, fstat will zero out the first fifty-six bytes of the stat structure pointed to by buf. The state of the remaining bytes of this stat structure is undefined and the st_mode member of the stat structure will be set to S_IFSOCK.

Lstat is like stat except when the named file is a symbolic link, in which case lstat returns information about the link, while stat returns information about the file the link references.

If the file is classified, the current clearance of the calling process must dominate the file’s classification. Otherwise, access is denied. [See intro(2).] (B1 only)

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

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

mode_tst_mode;/∗ File mode; see mknod(2) ∗/
ino_tst_ino;/∗ Inode number ∗/
dev_tst_dev;/∗ ID of device containing a ∗/
/∗ directory entry for this file ∗/
dev_tst_rdev;/∗ ID of device ∗/
/∗ This entry is defined only ∗/
/∗ for character special or ∗/
/∗ block special files ∗/
nlink_tst_nlink;/∗ Number of links ∗/
uid_tst_uid;/∗ User ID of the file’s owner ∗/
gid_tst_gid;/∗ Group ID of the file’s group ∗/
off_tst_size;/∗ File size in bytes ∗/
time_tst_atime;/∗ Time of last access ∗/
time_tst_mtime;/∗ Time of last modification ∗/
time_tst_ctime;/∗ Time of last status change ∗/
/∗ Times are measured in seconds ∗/
/∗ since 00:00:00 ∗/
unsigned long st_ausec; /∗ Time of last access in ∗/
/∗ microseconds ∗/
unsigned long st_musec; /∗ Time of last modification ∗/
/∗ in microseconds ∗/
unsigned long st_cusec; /∗ Time of last status change ∗/
/∗ in microseconds ∗/
/∗ Microsecond times are values ∗/
/∗ between 0 and 999999 and are ∗/
/∗ added to the respective ∗/
/∗ seconds fields ∗/
longst_blksize;/∗ Optimal blocksize for file ∗/
/∗ system I/O operations ∗/
longst_blocks;/ ∗ Actual number of blocks ∗/
/∗ allocated ∗/

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

st_mtime
Time when data was last modified. Changed by the following system calls: creat(2), mknod(2), pipe(2), utime(2), and write(2).

st_ctime Time when file status was last changed. Changed by the following system calls: chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2), unlink(2), utime(2), and write(2).

ERRORS

stat and lstat will fail if one or more of the following are true:

[EACCES] Search permission is denied for a component of the path prefix, or the security level of the user does not dominate the object. (B1 only)

[ENAMETOOLONG] The path argument exceeds {PATH_MAX} in length, or a pathname component is longer than {NAME_MAX} (see pathconf(2)).

[ENOENT] The named file does not exist, or the path argument points to an empty string.

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

[EFAULT] Buf or path points to an invalid address.

Fstat will fail if one or more of the following are true:

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

[EFAULT] Buf points to an invalid address.

[EACCES] The file is classified and the current security level of the subject process does not dominate the object file. (B1 only)

SECURITY AND COMPATIBILITY

The standard command returns the status information for an object file without regard to access permissions for the object. All that is required is search access to the directory containing the object file. This allows an unclassified process to stat a classified file in an unclassified directory and read the inode information, resulting in a potential covert channel. For this reason, the mandatory security policy, described in intro(2) is applied to stat and fstat. This policy allows a user to stat an object only if user’s current classification dominates the object.

Compatibility problems can result since stat is used by some commands as a technique for merely testing the existence of a file. Examples identified so far include rm(1) and test(1). Further, ls(1) cannot list classified file in -l format unless the current level of the user dominates. As a result, you cannot use ls -l file from the unclassified level in order to find out what clearance level is required to access a given file! You must dominate a file before you can list its classification.

The test command has not been modified as its use with the -f option is limited. If a script is encountered in which -f is used and may encounter an existing but classified file, consider using the -r or -w flags. In applications where fstat is used to test existence, consider using link(2) with both arguments pointing to the file. The command will fail, but the errno returned will indicate if the file exists or not, totally without regard to access rights. [See test(1) and link(2).]

The rm(1) command has been modified to report cannot stat in this case rather than file does not exist. Further, if called with -f flag, the file is unlinked if possible. Of course, one cannot recursively remove the files in a classified directory unless operating at a level that matches the classification level of the directory.

This incompatibility is unavoidable if strict mandatory protection is to be enforced. Please report problems introduced by this feature so that the cost of strict mandatory protection can be properly assessed and alternatives considered.

NOTE

These functions are defined in the 88open Binary and Object Compatibility Standards (BCS/OCS) for use in BCS/OCS compliant applications. The fstat function is also called out in the 88open BCS and OCS Networking Supplements (BCSNS/OCSNS) for use with BCS/OCS compliant networking applications. OCS/OCSNS-defined functions may be accessed by passing OCS options to cc(1) and ld(1).

RETURN VALUE

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

Museum

Related Articles