stat(2) 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 suc-
cessful 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 struc-
ture is undefined and the st_mode member of the stat struc-
ture 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 cal-
ling process must dominate the file's classification. Oth-
erwise, 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_t st_mode; /* File mode; see mknod(2) */
ino_t st_ino; /* Inode number */
Page 1 CX/UX Programmer's Reference Manual
stat(2) stat(2)
dev_t st_dev; /* ID of device containing a */
/* directory entry for this file */
dev_t st_rdev; /* ID of device */
/* This entry is defined only */
/* 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 modification */
time_t st_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 */
long st_blksize; /* Optimal blocksize for file */
/* system I/O operations */
long st_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)
Page 2 CX/UX Programmer's Reference Manual
stat(2) stat(2)
[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 secu-
rity 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 direc-
tory containing the object file. This allows an unclassi-
fied 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 com-
mand will fail, but the errno returned will indicate if the
file exists or not, totally without regard to access rights.
Page 3 CX/UX Programmer's Reference Manual
stat(2) stat(2)
[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 classi-
fied directory unless operating at a level that matches the
classification level of the directory.
This incompatibility is unavoidable if strict mandatory pro-
tection is to be enforced. Please report problems intro-
duced by this feature so that the cost of strict mandatory
protection can be properly assessed and alternatives con-
sidered.
NOTE
These functions are defined in the 88open Binary and Object
Compatibility Standards (BCS/OCS) for use in BCS/OCS compli-
ant 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. Other-
wise, a value of -1 is returned and errno is set to indicate
the error.
SEE ALSO
chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2),
read(2), time(2), unlink(2), utime(2), write(2), lstat(2),
socket(2), stat(5).
Page 4 CX/UX Programmer's Reference Manual