 |
» |
|
|
|
NAMEfstat() — get file status SYNOPSIS#include <sys/types.h>
#include <sys/stat.h>
int fstat(int fildes, struct stat *buf); DESCRIPTIONThe
fstat()
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
open(),
creat(),
dup(),
fcntl(),
or
pipe()
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
stat
structure, as defined in
<sys/stat.h>,
where the file system information is stored.
The
stat
structure contains the following members:
(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:
creat(),
mknod(),
pipe(),
read(),
readv()
(see the
read(2)),
and
utime().
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:
creat(),
truncate(),
ftruncate(),
(see
truncate(2)),
mknod(),
pipe(),
prealloc(),
utime(),
write(),
and
writev()
(see
write(2)).
Also changed by
close()
when the reference 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:
acl(),
chmod(),
chown(),
creat(),
fchmod(),
fchown(),
truncate(),
ftruncate(),
(see
truncate(2)),
link(),
mknod(),
pipe(),
prealloc(),
rename(),
setacl(),
unlink(),
utime(),
write(),
and
writev()
(see
write(2)).
The
touch
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
S_IXUSR
(execute by owner) mode bit is set if the following conditions 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,
getaccess()
clears this bit under these conditions (see
getaccess(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
multilevel 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
fstat()
to fail. The
fstat()
function updates any time-related fields
as described in "File Times Update" (see the
XBD Specification,
Chapter 4,
Character Set),
before writing into the
stat
structure. RETURN VALUEUpon successful completion,
0
is returned.
Otherwise,
-1
is returned and
errno
is set to indicate the error. When using
fstat()
to get the status of a socket descriptor, the
following return values are also possible:
- EINPROGRESS
Nonblocking I/O is enabled using
O_NONBLOCK,
O_NODELAY,
or
FIOSNBIO,
and the connection
cannot be completed immediately.
This is not a failure.
Make the
connect()
call again a few seconds later.
Alternatively, wait for completion by calling
select()
and selecting for write. - EWOULDBLOCK
Nonblocking I/O is enabled using the
ioctl()
FIOSNBIO
request, and the requested operation
would block.
ERRORSThe
fstat()
function will fail if:
- EBADF
The
fildes
argument is not a valid file descriptor. - EIO
An I/O error occurred while reading from the file system. - EFAULT
buf
or
path
points to an invalid address.
The reliable detection of this error is implementation-dependent. - EOVERFLOW
A 32-bit application is making this call on a file where the
st_size
or other field(s) would need to hold a 64-bit value.
NETWORKING FEATURESNFSThe
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. WARNINGSAccess Control Lists - HFS and JFS File Systems OnlyAccess control list descriptions in this entry apply only to HFS and
JFS file systems on standard HP-UX operating systems. For 32-bit applications,
st_ino
will be truncated to its least significant 32-bits for filesystems
that use 64-bit values. DEPENDENCIESCD-ROMThe
st_uid
and
st_gid
fields are set to -1 if they are not specified on the disk for
a given file. AUTHORstat()
and
fstat()
were developed by AT&T.
lstat()
was developed by
the University of California, 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),
stat(5),
<sys/stat.h>,
<sys/types.h>. STANDARDS CONFORMANCEfstat(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 |
Printable version
