STAT(2)                          System Calls                          STAT(2)

NAME

       stat, lstat, fstat - get file status

SYNOPSIS

       #include <sys/types.h>
       #include <sys/stat.h>

       int stat (const char *path, struct stat *sb);
       int lstat (const char *path, struct stat *sb);
       int fstat (int fd, struct stat *sb);

DESCRIPTION

       These  calls are used to retrieve status information about files.  They
       do much the same think as the GS/OS  call  GetFileInfoGS,  except  that
       they  return  the  information  in a format compatible with Unix's stat
       calls, and also provide information about sockets and GNO character de‐
       vices.

       The  stat  function  obtains  information  about the file pointed to by
       path.  Read, write or execute permission of the named file is  not  re‐
       quired, but all directories listed in the path name leading to the file
       must be searchable.

       lstat is like stat except in the case where the named file  is  a  sym‐
       bolic  link,  in  which  case lstat returns information about the link,
       while stat returns information about the file the link references.  Un‐
       like  other  filesystem  objects,  symbolic links do not have an owner,
       group, access mode, times, etc.  Instead, these  attributes  are  taken
       from  the  directory  that  contains the link.  The only attributes re‐
       turned from an lstat that refer to the symbolic  link  itself  are  the
       file type (S_IFLNK), size, blocks, and link count (always 1).

       The  fstat obtains the same information about an open file known by the
       file descriptor fd.

       The sb argument is  a  pointer  to  a  stat  structure  as  defined  by
       <sys/stat.h>  (shown  below)  and into which information is placed con‐
       cerning the file.
       struct stat {
           dev_t    st_dev;    /* device inode resides on */
           ino_t    st_ino;    /* inode's number */
           mode_t   st_mode;   /* inode protection mode */
           nlink_t  st_nlink;  /* number or hard links to the file */
           uid_t    st_uid;    /* user-id of owner */
           gid_t    st_gid;    /* group-id of owner */
           dev_t    st_rdev;   /* device type, for special file inode */
           off_t    st_size;   /* file size, in bytes */
           time_t   st_atime;  /* time of last access (GNO: same as st_mtime) */
           int      st_spare1; /* reserved */
           time_t   st_mtime;  /* time of last data modification */
           int      st_spare2; /* reserved */
           time_t   st_ctime;  /* time of last file status change */
           int      st_spare3; /* reserved */
           long     st_blksize;/* size in bytes of blocks on filesystem */
           long     st_blocks; /* blocks allocated for file */
           long     st_spare4[2]; /* reserved */
       }

       The items marked 'reserved' are not currently used but are reserved for
       future  expansion;  do  not use these fields for any reason.  st_dev is
       the number of the device on which the file resides.  This number is the
       same as the GS/OS device ID number.  st_rdev is not currently used, but
       may in the future designate a device type code.

       As short symbolic links are stored in the inode, st_blocks may be zero.

       The status information word st_mode has the following bits:
       #define S_IFCHR  0020000  /* character special */
       #define S_IFDIR  0040000  /* directory */
       #define S_IFBLK  0060000  /* block special */
       #define S_IFREG  0100000  /* regular */
       #define S_IFLNK  0120000  /* symbolic link */
       #define S_IFSOCK 0140000  /* socket */
       #define S_IRUSR  0000400  /* read permission, owner */
       #define S_IWUSR  0000200  /* write permission, owner */
       #define S_IXUSR  0000100  /* execute/search permission, owner */

       For a list of access modes, see <sys/stat.h>, access(2) and chmod(2).

RETURN VALUES

       Upon successful completion a value of  0  is  returned.   Otherwise,  a
       value of -1 is returned and errno is set to indicate the error.

COMPATIBILITY

       BSD  uses  a  larger set of defined fields than does GNO.  The types of
       the fields also, in general, differ.

       The stat man  page  for  GNO  v2.0.4  documented  the  macros  S_IREAD,
       S_IWRITE,   and   S_IEXEC.    These   macros  are  still  available  in
       <sys/stat.h> provided that _POSIX_SOURCE is not defined.

ERRORS

       Stat and lstat will fail if:

              ENOTDIR
                     A component of the path prefix is not a directory.

              ENOENT The named file does not exist.

              EBADF  fd does not refer to an open file.

              Fstat will fail if:

              EBADF  fd is not a valid open file descriptor.

              EIO    An I/O error occurred while reading from  or  writing  to
                     the file system.

SEE ALSO

       chmod(2), chown(2), utimes(2) symlink(7)

BUGS

       GNO  does  not  yet  support  hard  or symbolic file links on the IIgs.
       Therefore, lstat operates exactly like stat.  If there's a  case  where
       lstat  might  be  more  appropriate at a time when links are supported,
       then use lstat instead and be ready for the future.

       fstat doesn't do anything clever with all the unused  fields  when  its
       argument is a pipe or terminal.

STANDARDS

       The  stat  and  fstat  function calls are close, but do not conform, to
       IEEE Std 1003.1-1988 (POSIX).  In particular,

              - this implementation does not make the distinction of file own‐
              ership;

              - not all the required error return codes are implemented; and

              - file access time mirrors modification time.

HISTORY

       An lstat function call appeared in 4.2BSD.



GNO                             19 January 1997                        STAT(2)