stat, fstat
Purpose
Gets the status of a file.
Syntax
#include <sys/stat.h>
int stat (path, buf) int fstat (fildes, buf)
char *path; int fildes;
struct stat *buf; struct stat *buf;
Description
The stat system call obtains information about the file
pointed to by the path parameter. Read, write, or
execute permission of the named file is not required, but
all directories in the path leading to the file must be
searchable. The stat system call places the information
obtained into a structure pointed to by the buf param-
eter.
Use the fstat system call to obtain information about an
open file pointed to by the fildes parameter. The fildes
parameter is a file descriptor obtained from a successful
open, creat, dup, fcntl, or pipe system call. The fstat
system call places the information obtained into a struc-
ture pointed to by the buf parameter.
The stat structure pointed to by the buf parameter is
defined in the sys/stat.h header file, and it contains
the following members:
dev_t st_dev; /* ID of the device that contains */
/* a directory entry for this file */
ino_t st_ino; /* Inode number */
ushort st_mode; /* File mode; see mknod and chmod */
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 */
dev_t st_rdev; /* ID of device */
/* st_rdev is defined only for */
/* character or block special files */
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 are measured in seconds since */
/* 00:00:00 GMT, Jan. 1, 1970 */
st_dev The device that contains a directory entry for
this file. On a nondistributed file system,
this is a 32-bit quantity that uses only the
low 16-bits to contain the concatenated 8-bit
major device number and the 8-bit minor device
number. On a distributed system, this is a
32-bit quantity, created by combining a 16-bit
connection ID, the 8-bit major device number,
and the 8-bit minor device number.
st_uid The user ID of the file's owner. If the file
is a remote file, this value can also be one
of the two special values netnoone or
netsomeone, as defined in the /etc/master
file. For remote files, this field contains
the user ID after reverse translation. (See
Managing the AIX Operating System for a dis-
cussion of reverse translation.)
st_gid The group ID of the file's owner. If the file
is a remote file, this value can also be one
of the two special values netnoone or
netsomeone, as defined in the /etc/master
file. For remote files, this field contains
the group ID after reverse translation. (See
Managing the AIX Operating System for a dis-
cussion of reverse translation.)
st_atime The time when file data was last accessed.
For remote files, this field contains the time
at the server. Changed by the following
system calls: creat, mknod, pipe, utime, and
read.
st_mtime The time when data was last modified. For
remote files, this field contains the time at
the server. Changed by the following system
calls: creat, fclear, ftruncate, mknod, open,
pipe, utime, and write.
st_ctime The time when file status was last changed.
For remote files, this field contains the time
at the server. Changed by the following
system calls: chmod, chown, creat, link,
mknod, pipe, unlink, utime, and write.
Return Value
Upon successful completion, both the stat and the fstat
system calls return a value of 0. If either the stat or
the fstat system calls fail, a value of -1 is returned
and errno is set to indicate the error.
Diagnostics
The stat system call fails if one or more of the fol-
lowing are true:
ENOTDIR A component of the path prefix is not a direc-
tory.
ENOENT The named file does not exist.
EACCES Search permission is denied for a component of
the path prefix.
EFAULT The buf or path parameter &pointsout..
ESTALE The process's root or current directory is
located in a virtual file system that has been
unmounted.
If Distributed Services is installed on your system, stat
can also fail if one or more of the following are true:
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EDIST The server has a release level of Distrib-
uted Services that cannot communicate with
this node.
EAGAIN The server is too busy to accept the
request.
ESTALE The file descriptor for a remote file has
become obsolete.
EPERM The translate tables of the server did not
contain any entry for either the effective
user ID or effective group ID of the
calling process.
ENODEV The named file is a remote file located on
a device that has been unmounted at the
server.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
ENOCONNECT An attempt to establish a new network con-
nection with a remote node failed.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
The fstat system call fails if one or more of the fol-
lowing are true:
EBADF fildes is not a valid open file descriptor.
EFAULT buf &pointsout..
If Distributed Services is installed on your system,
fstat can also fail if one or more of the following are
true:
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EAGAIN The server is too busy to accept the
request.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "chmod," "chown, chownx," "creat,"
"fullstat, ffullstat," "link," "mknod," "pipe," "read,
readx," "time," "unlink," "ustat," "utime," "write,
writex," "master," and "stat.h."