DESCRIPTION

     These functions return information about the specified file.
     You  do  not  need any access rights to the file to get this
     information but you need search rights  to  all  directories
     named in the path leading to the file.

     stat stats the file pointed to by  file_name  and  fills  in
     buf.

     lstat is identical to stat, only the link itself is  stated,
     not the file that is obtained by tracing the links.

     fstat is identical to stat, only the open file pointed to by
     filedes  (as  returned  by  open(2))  is  stated in place of
     file_name.


     They all return a stat structure, which contains the follow-
     ing fields:

          struct stat
          {
              dev_t         st_dev;      /* device */
              ino_t         st_ino;      /* inode */
              mode_t        st_mode;     /* protection */
              nlink_t       st_nlink;    /* number of hard links */
              uid_t         st_uid;      /* user ID of owner */
              gid_t         st_gid;      /* group ID of owner */
              dev_t         st_rdev;     /* device type (if inode device) */
              off_t         st_size;     /* total size, in bytes */
              unsigned long st_blksize;  /* blocksize for filesystem I/O */
              unsigned long st_blocks;   /* number of blocks allocated */
              time_t        st_atime;    /* time of last access */
              time_t        st_mtime;    /* time of last modification */
              time_t        st_ctime;    /* time of last change */
          };

     Note that st_blocks may not always be in terms of blocks  of
     size  st_blksize,  and that st_blksize may instead provide a
     notion of the "preferred" blocksize for efficient file  sys-
     tem I/O.
     Not all of the Linux filesystems implement all of  the  time
     fields.   Traditionally,  st_atime  is  changed by mknod(2),
     utime(2), read(2),

     Traditionally, st_mtime is changed  by  mknod(2),  utime(2),
     and  write(2).   The  st_mtime is not changed for changes in
     owner, group, hard link count, or mode.

     Traditionally, st_ctime is changed by writing or by  setting
     inode  information  (i.e.,  owner,  group, link count, mode,
     etc.).

     The following POSIX macros are defined  to  check  the  file
     type:

          S_ISLNK(m)  is it a symbolic link?

          S_ISREG(m)  regular file?

          S_ISDIR(m)  directory?

          S_ISCHR(m)  character device?

          S_ISBLK(m)  block device?

          S_ISFIFO(m) fifo?

          S_ISSOCK(m) socket?

     The following flags are defined for the st_mode field:

          S_IFMT   00170000 bitmask for the file  type  bitfields
                   (not POSIX)

          S_IFSOCK 0140000 socket (not POSIX)

          S_IFLNK  0120000 symbolic link (not POSIX)

          S_IFREG  0100000 regular file (not POSIX)

          S_IFBLK  0060000 block device (not POSIX)

          S_IFDIR  0040000 directory (not POSIX)

          S_IFCHR  0020000 character device (not POSIX)

          S_IFIFO  0010000 fifo (not POSIX)

          S_ISUID  0004000 set UID bit

          S_ISGID  0002000 set GID bit

          S_ISVTX  0001000 sticky bit (not POSIX)

          S_IRWXU  00700 user (file owner) has  read,  write  and
                   execute permission

          S_IRUSR  00400  user  has  read  permission  (same   as
                   S_IREAD, which is not POSIX)

          S_IWUSR  00200  user  has  write  permission  (same  as
                   S_IWRITE, which is not POSIX)

          S_IXUSR  00100 user has  execute  permission  (same  as
                   S_IEXEC, which is not POSIX)

          S_IRWXG  00070 group has read, write and  execute  per-
                   mission

          S_IRGRP  00040 group has read permission

          S_IWGRP  00020 group has write permission

          S_IXGRP  00010 group has execute permission

          S_IRWXO  00007 others have read, write and execute per-
                   mission

          S_IROTH  00004 others have read permission

          S_IWOTH  00002 others have write permisson

          S_IXOTH  00001 others have execute permission

RETURN VALUE

     On success, zero is returned.  On error, -1 is returned, and
     errno is set appropriately.

ERRORS

     EBADF
          filedes is bad.

     ENOENT
          A component of the path file_name does  not  exist,  or
          the path is an empty string.

     ENOTDIR
          A component of the path is not a directory.

     ELOOP
          Too many symbolic links  encountered  while  traversing
          the path.

     EFAULT
          Bad address.

     EACCES
          Permission denied.

     ENOMEM
          Out of memory (i.e. kernel memory).

     ENAMETOOLONG
          File name too long.

CONFORMING TO

     The stat and fstat  calls  conform  to  SVr4,  SVID,  POSIX,
     X/OPEN,  BSD  4.3.   The  lstat  call conforms to 4.3BSD and
     SVr4.  SVr4  documents  additional  fstat  error  conditions
     EINTR,  ENOLINK,  and  EOVERFLOW.  SVr4 documents additional
     stat and lstat error conditions  EACCES,  EINTR,  EMULTIHOP,
     ENOLINK, and EOVERFLOW.

SEE ALSO

     chmod(2), chown(2), readlink(2), utime (2)