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

       The  stat  function  obtains  information  about the file pointed to by
       path.  Read, write or execute permission  of  the  named  file  is  not
       required,  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.
       Unlike  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
       returned 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)

Man(1) output converted with man2html