hpux man page for fstat

fstat(2)							System Calls Manual							  fstat(2)

NAME
       fstat() - get file status

SYNOPSIS
DESCRIPTION
       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 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_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 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: (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	conditions
			     are met:

			     o	The file is a regular file,

			     o	No permission execute bits are set, and

			     o	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 exe-
			     cuted.  However, 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 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 descriptor.

	      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 implementation-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 California, Berkeley.

SEE ALSO
       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), privileges(5), stat(5), <sys/stat.h>, <sys/types.h>.

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

																	  fstat(2)