fstat(2) fstat(2)
NAME [Toc] [Back]
fstat - get file status
SYNOPSIS [Toc] [Back]
#include <sys/types.h>
#include <sys/stat.h>
int fstat(int fildes, struct stat *buf);
DESCRIPTION [Toc] [Back]
The 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 filesystem information is stored. The stat structure
contains the following 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_mtime; /* Last modification time */
time_t st_ctime; /* Last file status change time */
/* Measured in secs since */
/* 00:00:00 GMT, Jan 1, 1970 */
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.)
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
fstat(2) fstat(2)
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.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
fstat(2) fstat(2)
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 VALUE [Toc] [Back]
Upon 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] Non-blocking I/O is enabled using the
ioctl() FIOSNBIO request, and the requested
operation would block.
ERRORS [Toc] [Back]
The 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.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
fstat(2) fstat(2)
[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 FEATURES [Toc] [Back]
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 [Toc] [Back]
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, st_ino will be truncated to its least
significant 32-bits for filesystems that use 64-bit values.
DEPENDENCIES [Toc] [Back]
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 [Toc] [Back]
stat() and fstat() were developed by AT&T. lstat() was developed by
the University of California, Berkeley.
SEE ALSO [Toc] [Back]
touch(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 CONFORMANCE [Toc] [Back]
fstat(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003 [ Back ] |
