fstat(2)fstat(2)NAMEfstat() - get file status
SYNOPSISDESCRIPTION
The function obtains information about an open file associated with the
file descriptor fildes, and writes it to the area pointed to by buf.
fildes is a file descriptor for an open file, which is created with the
successful completion of an or system call. See the open(2), creat(2),
dup(2), fcntl(2), or pipe(2)) manpages for more detailed information.
The buf argument is a pointer to a structure, as defined in where the
file system information is stored. The structure contains the follow‐
ing members:
dev_t st_dev; /* ID of device containing a */
/* directory entry for this file */
ino_t st_ino; /* Inode number */
short st_fstype; /* Type of filesystem this file */
/* is in; see sysfs(2) */
ushort st_mode; /* File type, attributes, and */
/* access control summary */
ushort st_basemode /* Permission bits (see chmod(1)) */
ushort st_nlink; /* Number of links */
uid_t st_uid; /* User ID of file owner */
gid_t st_gid; /* Group ID of file group */
dev_t st_rdev; /* Device ID; this entry defined */
/* only for char or blk spec files */
off_t st_size; /* File size (bytes) */
time_t st_atime; /* Time of last access */
time_t st_natime; /* Reserved. DO NOT USE; field may change. */
time_t st_mtime; /* Last modification time */
time_t st_nmtime; /* Reserved. DO NOT USE; field may change. */
time_t st_ctime; /* Last file status change time */
/* Measured in secs since */
/* 00:00:00 GMT, Jan 1, 1970 */
time_t st_nctime; /* Reserved. DO NOT USE; field may change. */
long st_blksize; /* File system block size */
uint st_acl:1; /* Set if the file has optional */
/* access control list entries */
/* HFS File Systems only */
uint st_aclv:1; /* Set if the file has optional */
/* access control list entries */
/* JFS File Systems only */
(Note that the position of items in this list does not necessarily
reflect the order of the members in the structure.)
The fields contain the following information:
st_atime Time when file data was last accessed. Changed
by the following system calls: (see the read(2)),
and If a file is mapped into virtual memory,
accesses of file data through the mapping may
also modify st_mtime. See mmap(2).
st_mtime Time when data was last modified. Changed by the
following system calls: (see truncate(2)), and
(see write(2)). Also changed by when the refer‐
ence count reaches zero on a named pipe (FIFO
special) file that contains data. If a file is
mapped into virtual memory, updates of file data
through the mapping may also modify st_mtime.
See mmap(2).
st_ctime Time when file status was last changed. Changed
by the following system calls: (see truncate(2)),
and (see write(2)). The command (see touch(1))
can be used to explicitly control the times of a
file.
st_mode The value returned in this field is the bit-wise
inclusive OR of a value indicating the file's
type, attribute bits, and a value summarizing its
access permission. See mknod(2). For ordinary
users, the least significant nine bits consist of
the file's permission bits modified to reflect
the access granted or denied to the caller by
optional entries in the file's access control
list. For users with appropriate privileges the
least significant nine bits are the file's access
permission bits. In addition, the (execute by
owner) mode bit is set if the following condi‐
tions are met:
· The file is a regular file,
· No permission execute bits are set, and
· An execute bit is set in one or more of the
file's optional access control list entries.
The write bit is not cleared for a file on a
read-only file system or a shared-text program
file that is being executed. However, clears
this bit under these conditions (see getac‐
cess(2).
The value of the member st_nlink will be set to the number of links to
the file. If the chosen path name or file descriptor refers to a
Multi-Level Directory (MLD), and the process does not have the multi‐
level effective privilege, the i-node number returned in st_ino is the
i-node of the MLD itself.
An implementation that provides additional or alternative file access
control mechanisms may, under implementation-dependent conditions,
cause to fail.
The function updates any time-related fields as described in "File
Times Update" (see the Chapter 4, Character Set), before writing into
the structure.
Note: The st_natime, st_nmtime, and st_nctime fields are currently
reserved. To avoid compatibility problems, these fields should not be
used.
RETURN VALUE
Upon successful completion, is returned. Otherwise, is returned and is
set to indicate the error.
When using to get the status of a socket descriptor, the following
return values are also possible:
[EINPROGRESS] Nonblocking I/O is enabled using or and the
connection cannot be completed immediately.
This is not a failure. Make the call again
a few seconds later. Alternatively, wait
for completion by calling and selecting for
write.
[EWOULDBLOCK] Non-blocking I/O is enabled using the
request, and the requested operation would
block.
ERRORS
The function will fail if:
The fildes argument is not a valid file descrip‐
tor.
An I/O error occurred while reading from the file system.
buf or path points to an invalid address. The
reliable detection of this error is imple‐
mentation-dependent.
A 32-bit application is making this call on a file where the
or other field(s) would need to hold a
64-bit value.
NETWORKING FEATURES
NFS
The st_basemode, st_acl and st_aclv fields are zero on files accessed
remotely. The st_acl field is applicable to HFS File Systems only.
The st_aclv field is applicable to JFS File Systems only.
WARNINGS
Access Control Lists - HFS and JFS File Systems Only
Access control list descriptions in this entry apply only to HFS and
JFS file systems on standard HP-UX operating systems.
For 32-bit applications, will be truncated to its least significant
32-bits for filesystems that use 64-bit values.
DEPENDENCIES
CD-ROM
The st_uid and st_gid fields are set to −1 if they are not specified on
the disk for a given file.
AUTHOR
and were developed by AT&T. was developed by the University of Cali‐
fornia, Berkeley.
SEE ALSOtouch(1), acl(2), chmod(2), chown(2), creat(2), fstat64(2), link(2),
lstat(2), mknod(2), pipe(2), read(2), rename(2), setacl(2), sysfs(2),
time(2), truncate(2), unlink(2), utime(2), write(2), acl(5), aclv(5),
privileges(5), stat(5), <sys/stat.h>, <sys/types.h>.
STANDARDS CONFORMANCEfstat(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
fstat(2)