unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

STAT(2V)                                                              STAT(2V)



NAME
       stat, lstat, fstat - get file status

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

       int stat(path, buf)
       char *path;
       struct stat *buf;

       int lstat(path, buf)
       char *path;
       struct stat *buf;

       int fstat(fd, buf)
       int fd;
       struct stat *buf;

DESCRIPTION
       stat()  obtains  information about the file named by path.  Read, write
       or execute permission of the named file is not required, but all direc-
       tories 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
       symbolic link, in which case  lstat()  returns  information  about  the
       link,  while  stat() returns information about the file the link refer-
       ences.

       fstat() obtains the same information about an open file  referenced  by
       the argument descriptor, such as would be obtained by an open(2V) call.

       buf  is  a pointer to a stat structure into which information is placed
       concerning the file.  A stat structure includes the following members:

              dev_t     st_dev;        /* device file resides on */
              ino_t     st_ino;        /* the file serial number */
              mode_t    st_mode;       /* file mode */
              nlink_t   st_nlink;      /* number of 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;       /* the device identifier (special files only)*/
              off_t     st_size;       /* total size of file, in bytes */
              time_t    st_atime;      /* file last access time */
              time_t    st_mtime;      /* file last modify time */
              time_t    st_ctime;      /* file last status change time */
              long      st_blksize;    /* preferred blocksize for file system I/O*/
              long      st_blocks;     /* actual number of blocks allocated */

       st_atime    Time when file data was last accessed.  This  can  also  be
                   set  explicitly  by utimes(2).  st_atime is not updated for
                   directories searched during pathname resolution.

       st_mtime    Time when file data was last modified.  This  can  also  be
                   set  explicitly  by utimes(2).  It is not set by changes of
                   owner, group, link count, or mode.

       st_ctime    Time when file status was last changed.   It  is  set  both
                   both  by  writing and changing the file status information,
                   such as changes of owner, group, link count, or mode.

       The following macros test whether a file is of the specified type.  The
       value  m  is  the value of st_mode.  Each macro evaluates to a non-zero
       value if the test is true or to zero if the test is false.

       S_ISDIR(m)     Test for directory file.

       S_ISCHR(m)     Test for character special file.

       S_ISBLK(m)     Test for block special file.

       S_ISREG(m)     Test for regular file.

       S_ISLNK(m)     Test for a symbolic link.

       S_ISSOCK(m)    Test for a socket.

       S_ISFIFO(m)    Test for pipe or FIFO special file.

       The status information word st_mode is bit-encoded using the  following
       masks and bits:

       S_IRWXU        Read, write, search (if a directory), or execute (other-
                      wise) permissions mask for the owner of the file.

                      S_IRUSR        Read permission bit for the owner of  the
                                     file.

                      S_IWUSR        Write permission bit for the owner of the
                                     file.

                      S_IXUSR        Search (if a directory) or execute  (oth-
                                     erwise)  permission  bit for the owner of
                                     the file.

       S_IRWXG        Read, write, search (if directory), or  execute  (other-
                      wise) permissions mask for the file group class.

                      S_IRGRP        Read  permission  bit  for the file group
                                     class.

                      S_IWGRP        Write permission bit for the  file  group
                                     class.

                      S_IXGRP        Search  (if a directory) or execute (oth-
                                     erwise) permission bit for the file group
                                     class.

       S_IRWXO        Read, write, search (if a directory), or execute (other-
                      wise) permissions mask for the file other class.

                      S_IROTH        Read permission bit for  the  file  other
                                     class.

                      S_IWOTH        Write  permission  bit for the file other
                                     class.

                      S_IXOTH        Search (if a directory) or execute  (oth-
                                     erwise) permission bit for the file other
                                     class.

       S_ISUID        Set user ID on execution.  The process's effective  user
                      ID is set to that of the owner of the file when the file
                      is run as a program  (see  execve(2V)).   On  a  regular
                      file, this bit should be cleared on any write.

       S_ISGID        Set  group  ID  on  execution.   The process's effective
                      group ID is set to that of the file when the file is run
                      as  a program (see execve(2V)).  On a regular file, this
                      bit should be cleared on any write.

       In addition, the following bits and masks are made available for  back-
       ward compatibility:
              #define    S_IFMT         0170000  /* type of file */
              #define    S_IFIFO        0010000  /* FIFO special */
              #define    S_IFCHR        0020000  /* character special */
              #define    S_IFDIR        0040000  /* directory */
              #define    S_IFBLK        0060000  /* block special */
              #define    S_IFREG        0100000  /* regular file */
              #define    S_IFLNK        0120000  /* symbolic link */
              #define    S_IFSOCK       0140000  /* socket */
              #define    S_ISVTX        0001000  /* save swapped text even after use */
              #define    S_IREAD        0000400  /* read permission, owner */
              #define    S_IWRITE       0000200  /* write permission, owner */
              #define    S_IEXEC        0000100  /* execute/search permission, owner */

       For more information on st_mode bits see chmod(2V).

RETURN VALUES
       stat(), lstat() and fstat() return:

       0      on success.

       -1     on failure and set errno to indicate the error.

ERRORS
       stat() and lstat() will fail if one or more of the following are true:

       EACCES              Search  permission is denied for a component of the
                           path prefix of path.

       EFAULT              buf or path points to an invalid address.

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

       ELOOP               Too  many symbolic links were encountered in trans-
                           lating path.

       ENAMETOOLONG        The   length   of   the   path   argument   exceeds
                           {PATH_MAX}.n

                           A  pathname  component  is  longer  than {NAME_MAX}
                           while {_POSIX_NO_TRUNC} is  in  effect  (see  path-
                           conf(2V)).

       ENOENT              The file referred to by path does not exist.

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

       fstat() will fail if one or more of the following are true:

       EBADF               fd is not a valid open file descriptor.

       EFAULT              buf points to an invalid address.

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

SYSTEM V ERRORS
       In addition to the above, the following may also occur:

       ENOENT              path points to an empty string.

WARNINGS
       The  st_atime  and  st_mtime  fields  of the stat() are not contiguous.
       Programs that depend on them being contiguous (in calls to utimes(2) or
       utime(3V)) will not work.

SEE ALSO
       chmod(2V),   chown(2V),   link(2V),  open(2V),  read(2V),  readlink(2),
       rename(2V), truncate(2), unlink(2V), utimes(2), write(2V)



                                21 January 1990                       STAT(2V)