HPlogo HP-UX Reference Volume 3 of 5 > f

fstat(2)
» 

Technical documentation

Complete book in PDF

 » Table of Contents

 » Index

spacerspacerspacer
spacer
spacer
  		 
 

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. The buf argument is a pointer to a stat structure, as defined in <sys/stat.h>, into which information is placed concerning the file.

The structure members st_mode, st_ino, st_dev, st_uid, st_gid, st_atime, st_ctime, and st_mtime will have meaningful values for all file types defined in this document. The value of the member st_nlink will be set to the number of links to the file.

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.

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.

The fstat() function may fail if:

[EOVERFLOW]

One of the values is too large to store into the structure pointed to by the buf argument.

SEE ALSO

lstat(2), stat(2), <sys/stat.h>, <sys/types.h>.

CHANGE HISTORY

First released in Issue 1.

Derived from Issue 1 of the SVID.

Issue 4

The following changes are incorporated in the DESCRIPTION section for alignment with the ISO POSIX-1 standard:

  • A paragraph defining the contents of stat structure members is added.

  • The words "extended security controls" are replaced by "additional or alternative file access control mechanisms."

Another change is incorporated as follows:

  • The header <sys/types.h> is now marked as optional (OH); this header need not be included on XSI-conformant systems.

Issue 4, Version 2

The ERRORS section is updated for X/OPEN UNIX conformance as follows:

  • The EIO error is added as a mandatory error indicated the occurrence of an I/O error.

  • The EOVERFLOW error is added as an optional error indicating that one of the values is too large to store in the area pointed to by buf.

fstat HP-UX EXTENSIONS

DESCRIPTION

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.

The parameters for the fstat() function is as follows:

buf

is a pointer to a stat() structure, which is where the file status information is stored.

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 open(2), creat(2), dup(2), fcntl(2), or pipe(2)).

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 */
ushortst_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 */

(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 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: 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).

ERRORS

[EFAULT]

buf or path points to an invalid address. The reliable detection of this error is implementation-dependent.

[EOVERFLOW]

The file size in bytes or the number of blocks allocated to the file cannot be represented correctly in the structure pointed to by buf.

NFS

The st_basemode and st_acl fields are zero on files accessed remotely. st_acl field is applicable to HFS File Systems only.

WARNINGS

Access Control Lists - HFS File Systems only

Access control list descriptions in this entry apply only to HFS file systems on standard HP-UX operating systems.

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.

SEE ALSO

touch(1), chmod(2), chown(2), creat(2), fstat64(2), link(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), stat(5).

STANDARDS CONFORMANCE

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



fsctl
  		 


fsync  
© Hewlett-Packard Development Company, L.P.