fullstat, ffullstat
Purpose
Provides information about a file or path to a file.
Syntax
#include <sys/fullstat.h>
int fullstat (path, cmd, buf) int ffullstat (fildes, cmd, buf)
char *path; int fildes, cmd;
int cmd; struct fullstat *buf;
struct fullstat *buf;
Description
The fullstat 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 fullstat system call places the informa-
tion obtained into a structure pointed to by the buf
parameter, and the cmd parameter specifies both the
behavior of fullstat and the meaning of buf.
Use the ffullstat 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 ffullstat system call places the information obtained
into a structure pointed to by the buf parameter.
The fullstat and ffullstat system calls provide all of
the information available with a stat or fstat call, plus
additional information on group IDs, user IDs, and file
location.
The fullstat structure pointed to by the buf parameter is
defined in the sys/fullstat.h header file, and it con-
tains the following members:
dev_t st_dev; /* ID of the device that contains */
/* a directory entry for this file */
ino_t st_ino; /* File serial number */
ushort st_mode; /* File access mode */
short st_nlink; /* Number of links */
ushort st_uid; /* Translated UID of the file's owner */
ushort st_gid; /* Translated GID of the file's group */
dev_t st_rdev; /* ID of device */
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 */
/* Above fields are the same as stat fields */
ushort fst_uid_raw; /* Untranslated user ID of the owner */
/* of the file */
ushort fst_gid_raw; /* Untranslated group ID of the file */
vtype fst_type; /* Vnode type */
tagtype fst_uid_rev_tag; /* Contains special value representing */
/* result of reverse UID mapping */
tagtype fst_gid_rev_tag; /* Contains special value representing */
/* result of reverse GID mapping */
short * fst_other_gid_list; /* Pointer to first group ID on the */
/* alternate concurrent group list */
short fst_other_gid_count; /* Number of group IDs on the
/* alternate concurrent group list */
long fst_vfs; /* Virtual file system ID */
long fst_nid; /* Node ID where the file resides */
int fst_flag; /* Indicates whether the directory or */
/* file is a virtual mount point */
long fst_i_gen; /* Inode generation number */
long fst_reserved[8|; /* Reserved */
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, made by combining a 16-bit
connection ID, the 8-bit major device number,
and the 8-bit minor device number.
st_mode The access mode of the file. (See "stat.h"
for a list of values for this field.)
st_uid The user ID of the file's owner after reverse
translation. (See Managing the AIX Operating
System for a complete discussion of reverse
translation.) 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.
When cmd is FS_STAT_OTHER, this field is used
to input a user ID.
st_gid The group ID of the file's owner after reverse
translation. (See Managing the AIX Operating
System for a complete discussion of reverse
translation.) 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.
When cmd is FS_STAT_OTHER, this field is used
to input a group ID.
st_rdev The ID of the device. This field is defined
only for block or character special files.
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, mknod, 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.
fst_uid_rev_tag
For a local file, this field is undefined.
For a remote file, this tag describes how
st_uid was mapped to a remote user ID. Pos-
sible values are:
CALLER The st_uid returned is that of the
calling process, which maps to the
file's owner ID.
OTHER The st_uid returned is that of a
user at this node, which maps to the
file's owner ID.
SOMEONE The st_uid field is undefined, but
some user ID at this node maps to
the file's owner ID.
NO_ONE The st_uid field is undefined, and
no user ID at this node maps to the
file's owner ID.
fst_gid_rev_tag
For a local file, this field is undefined.
For a remote file, this tag describes how
st_gid was mapped to a remote group ID. Pos-
sible values are:
CALLER The st_gid returned is that of the
calling process, which maps to the
file's group ID.
OTHER The st_gid returned is that of a
group at this node, which maps to
the file's group ID.
SOMEONE The st_gid field is undefined, but
some group ID at this node maps to
the file's group ID.
NO_ONE The st_gid field is undefined, and
no group ID at this node maps to the
file's group ID.
fst_gid_list
A pointer to an array that holds an alternate
concurrent group list.
fst_gid_count
The number of group IDs on the alternate con-
current group list.
fst_vfs Virtual file system ID. A value of zero indi-
cates the root file system.
fst_flag A flag indicating whether the file or direc-
tory is a virtual mount point. A value of
FS_VMP indicates that it is a virtual mount
point.
The following cmds are available:
FL_STAT Returns all of the elements in the struc-
ture returned by the stat system call,
plus additional information about the
file. Differs from FL_STAT_REV and
FL_STAT_OTHER in that the values in the
st_uid and st_gid fields are undefined.
For this cmd, the relevant user ID and
group ID information is instead contained
in the fst_uid_raw and fst_gid_raw
fields.
This cmd allows programs that don't care
about the ID values to use the fullstat
system call without the performance cost
of using the translate tables.
FL_STAT_REV Returns all of the elements in the struc-
ture returned by the stat system call,
plus additional information about user
and group IDs of the file. When using
FL_STAT_REV, the returned ID information
is the result of the reverse mapping of
the user ID and group ID of the calling
process. (See Managing the AIX Operating
System for a complete discussion of
reverse translation.)
FL_STAT_OTHER Returns all of the elements in the struc-
ture returned by the stat system call,
plus additional information about the
user and group IDs of the file. Differs
from FL_STAT_REV in that the returned ID
information is the result of the reverse
mapping of the user ID, group ID, and
concurrent group list contained in the
st_uid, st_gid, fst_other_gid_list, and
fst_other_gid_count fields. (See Man-
aging the AIX Operating System for a com-
plete discussion of reverse translation.)
When the FL_STAT_OTHER cmd is used, the
return values of fst_uid_rev_tag and
fst_gid_rev_tag are relative to the sup-
plied IDs, rather than to the calling
process's IDs. If either
fst_other_gid_list is NULL or
fst_other_gid_count is 0, there is no
concurrent group list.
Return Value
Upon successful completion, both the fullstat and the
ffullstat system calls return a value of 0. If either
the fullstat or the ffullstat system call fails, a value
of -1 is returned and errno is set to indicate the error.
Diagnostics
The fullstat system call fails if one or more of the fol-
lowing are true:
EFAULT The buf or path parameter &pointsout..
ENOENT A component of the path does not exist.
ENOTDIR A component of the path prefix is not a direc-
tory.
EACCES Search permission is denied for a component of
the path.
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,
ffullstat 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 ffullstat system call fails if one or more of the
following are true:
EBADF fildes is not a valid file descriptor.
EFAULT The buf parameter &pointsout..
If Distributed Services is installed on your system,
ffullstat 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,"
"link," "mknod," "pipe," "read, readx," "stat, fstat,"
"time," "unlink," "ustat," "utime," "write, writex,"
"master," "stat.h," and "fullstat.h."
Managing the AIX Operating System.