unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 fstat(2)							    fstat(2)




 NAME
      fstat - get file status

 SYNOPSIS
      #include <&lt&lt&lt;sys/types.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/stat.h>&gt&gt&gt;

      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 <&lt&lt&lt;sys/stat.h>&gt&gt&gt;, 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.

      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
				    ioctl() FIOSNBIO request, and the
				    requested operation would block.

 ERRORS
      The fstat() function will fail if:




 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 fstat(2)							    fstat(2)




	   [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 <&lt&lt&lt;sys/types.h>&gt&gt&gt; 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.










				    - 2 -	  Formatted:  August 2, 2006






 fstat(2)							    fstat(2)




				 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_t    st_dev;	  /* ID of device containing a */
				  /* directory entry for this file */
	   ino_t    st_ino;	  /* Inode number */
	   ushort   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 */





 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 fstat(2)							    fstat(2)




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





 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 fstat(2)							    fstat(2)




			  +  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, 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.

 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), acl(2), 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), aclv(5), stat(5).

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










 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000