stat(2) CLIX stat(2)
NAME
stat, fstat - Provides information about a file
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <sys/stat.h>
#include <sys/types.h>
stat(
char *path ,
struct stat *buffer );
fstat(
int filedes ,
struct stat *buffer );
PARAMETERS
path Points to the pathname identifying the file.
filedes Specifies the file descriptor identifying the file.
buffer Points to the stat structure in which information is returned.
The stat structure is described in the <sys/stat.h> header file.
DESCRIPTION
The stat() function obtains information about the named file. Read,
write, or execute permission of the named file is not required, but all
directories listed in the pathname leading to the file must be searchable.
Note that in a Remote File Sharing environment, the information returned
by stat() depends upon the user/group mapping set up between the local and
remote computers. (See the idload command.)
The fstat() function obtains information about an open file known by the
file descriptor fildes, obtained from a successful open(), creat(), dup(),
fcntl(), or pipe() function.
The contents of the structure pointed to by buffer include the following
members:
ushort st_mode; /* File mode [see mknod(2)] */
ino_t st_ino; /* Inode number */
dev_t st_dev; /* ID of device containing */
2/94 - Intergraph Corporation 1
stat(2) CLIX stat(2)
/* 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 */
short st_nlink; /* Number of links */
ushort st_uid; /* User ID of the file's owner */
ushort 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 */
/* Times measured in seconds since */
/* 00:00:00 GMT, Jan. 1, 1970 */
st_mode The mode of the file as described in the mknod() function.
st_ino This field uniquely identifies the file in a given file system.
The pair st_ino and st_dev uniquely identifies regular files.
st_dev This field uniquely identifies the file system that contains
the file. Its value may be used as input to the ustat()
function to determine more information about this file system.
No other meaning is associated with this value.
st_rdev This field should 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 This field tells the number of srchive links. This field
should 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.
For pipes or fifos, this is the count of the data currently in
the file. For block special or character special files, this
is not defined.
st_atime Time when the file data was last accessed. This time is
changed by the following functions: creat(), mknod(), pipe(),
utime(), and read().
st_mtime Time when the data was last modified. This data is changed by
the following functions: creat(), mknod(), pipe(), utime(),
and write().
st_ctime Time when the file status was last changed. This time is
changed by the following functions: chmod(), chown(), creat(),
2 Intergraph Corporation - 2/94
stat(2) CLIX stat(2)
link(), mkdir(), mknod(), pipe(), rename(), rmdir(), unlink(),
utime(), and write().
EXAMPLES
To determine the owner of a file:
struct stat statbuf;
if (stat("filename", &statbuf) == -1) {
perror("stat failed");
return(-1);
owner = statbuf.st_uid;
RETURN VALUES
Upon successful completion a value of 0 is returned. Otherwise, a value
of -1 is returned and the global variable errno is set to indicate the
error.
ERRORS
The stat() function fails if one or more of the following are true:
[ENOTDIR]
A component of the path prefix is not a directory.
[ENOENT]
The named file does not exist.
[EACCES]
Search permission is denied for a component of the path prefix.
[EFAULT]
The buffer or path parameter points to an address that is not
valid.
[EINTR]
A signal was caught during the stat() function.
[ENAMETOOLONG]
The length of the path argument exceeds PATH_MAX, or a pathname
component is longer than NAME_MAX while _POSIX_NO_TRUNC is in
effect.
[ENOLINK]
The path parameter points to a remote machine and the link to that
machine is no longer active.
[EMULTIHOP]
Components of path require hopping to multiple remote machines.
2/94 - Intergraph Corporation 3
stat(2) CLIX stat(2)
The fstat() function fails if one or more of the following are true:
[EBADF] The fildes parameter is not a valid open file descriptor.
[EFAULT] The buffer parameter points to an address that is not valid.
[ENOLINK] The fildes parameter points to a remote machine and the link
to that machine is no longer active.
RELATED INFORMATION
Functions: chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2),
read(2), time(2), unlink(2), utime(2), write(2), rmdir(2), mkdir(2)
4 Intergraph Corporation - 2/94