# 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 *buf)
         int lstat(const char *path, struct stat *buf)         (Minix-vmd)
         int fstat(int fd, struct stat *buf)

## DESCRIPTION

         Stat obtains information about the file 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 reachable.

         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 references.  (Minix-vmd)

         Fstat obtains the same information about an open file referenced  by  the
         argument  descriptor,  such  as  would be obtained by an open call.  Pipe
         descriptors look like named pipes with a link count of zero.  The st_size
         field  of  pipes  or  named  pipes  shows  the  amount of bytes currently
         buffered in the pipe.

         Buf is a pointer to a stat structure into  which  information  is  placed
         concerning  the file.  The contents of the structure pointed to by buf is
         as follows:

         struct stat {
             dev_t     st_dev;     /* device inode resides on */
             ino_t     st_ino;     /* this inode's number */
             mode_t    st_mode;    /* file mode, protection bits, etc. */
             nlink_t   st_nlink;   /* number or hard links to the file */
             uid_t     st_uid;     /* user-id of the file's owner */
             gid_t     st_gid;     /* group-id of the file's owner */
             dev_t     st_rdev;    /* the device type, for inode that is device */
             off_t     st_size;    /* total size of file */
             time_t    st_atime;   /* time of last access */
             time_t    st_mtime;   /* time of last data modification */
             time_t    st_ctime;   /* time of last file status change */
         };

         st_atime    Time when file data was last read or  modified.   Changed  by
                     the following system calls:  mknod(2), utime(2), read(2), and
                     write(2).  For reasons of efficiency,  st_atime  is  not  set
                     when  a  directory  is  searched, although this would be more
                     logical.

         st_mtime    Time when data was last modified.  It is not set  by  changes
                     of  owner,  group,  link  count,  or  mode.   Changed  by the
                     following system calls:  mknod(2), utime(2), write(2).

         st_ctime    Time when file status was last changed.  It is set both  both
                     by writing and changing the i-node.  Changed by the following
                     system  calls:    chmod(2)   chown(2),   link(2),   mknod(2),
                     rename(2), unlink(2), utime(2), write(2).

         The file type information in st_mode has bits:

              #define S_IFMT     0170000    /* type of file */
              #define    S_IFIFO 0010000    /* named pipe */
              #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 (Minix-vmd) */

         The mode bits 0007777 encode set-uid/gid bits and  permission  bits  (see
         chmod(2)).

## RETURN VALUE

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

## ERRORS

         Stat and lstat will fail if one or more of the following are true:

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

         [ENAMETOOLONG] The path name exceeds PATH_MAX characters.

         [ENOENT]       The named file does not exist.

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

         [ELOOP]        Too many symbolic links were  encountered  in  translating
                        the pathname.  (Minix-vmd)

         [EFAULT]       Buf or name points to an invalid address.

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

         Fstat will fail if one or both of the following are true:

         [EBADF]        Fildes 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.

## SEE ALSO

         chmod(2), chown(2), utime(2).