*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> fstat (2)              


 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

           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

      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

           [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

 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.

      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]
      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>.

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

 Hewlett-Packard Company            - 4 -   HP-UX 11i Version 2: August 2003
[ Back ]
 Similar pages
Name OS Title
kldstat FreeBSD get status of kld file
pxfstat IRIX Retrieves the file status
stat FreeBSD display file status
readlink FreeBSD display file status
check IRIX check RCS status of a file
pthread_exc_get_status_np Tru64 (Macro) Obtains a systemdefined error status from a DECthreads status exception object
VFS_STATFS FreeBSD return file system status
stl_sts Tru64 setld subset status file
fsclean_hfs HP-UX determine the shutdown status of HFS file systems
sm Tru64 Status monitor directories and file structures
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service