Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > F

fstat(2)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

fstat() — get file status

SYNOPSIS

#include <sys/types.h> #include <sys/stat.h> int fstat(int fildes, struct stat *buf);

DESCRIPTION

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 file system information is stored. The stat structure contains the following members:

dev_tst_dev;/* ID of device containing a */
/* directory entry for this file */
ino_tst_ino;/* Inode number */
shortst_fstype;/* Type of filesystem this file */
/* is in; see sysfs(2) */
ushortst_mode;/* File type, attributes, and */
/* access control summary */
ushortst_basemode/* Permission bits (see chmod(1)) */
ushortst_nlink;/* Number of links */
uid_tst_uid;/* User ID of file owner */
gid_tst_gid;/* Group ID of file group */
dev_tst_rdev;/* Device ID; this entry defined */
/* only for char or blk spec files */
off_tst_size;/* File size (bytes) */
time_tst_atime;/* Time of last access */
time_tst_mtime;/* Last modification time */
time_tst_ctime;/* Last file status change time */
/* Measured in secs since */
/* 00:00:00 GMT, Jan 1, 1970 */
longst_blksize;/* File system block size */
uintst_acl:1;/* Set if the file has optional */
/* access control list entries */
/* HFS File Systems only */
uintst_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: 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 VALUE

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

Nonblocking I/O is enabled using the ioctl() FIOSNBIO request, and the requested operation would block.

ERRORS

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.

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

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, st_ino 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

stat() and fstat() were developed by AT&T. lstat() was developed by the University of California, Berkeley.

STANDARDS CONFORMANCE

fstat(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.