File: *manpages*,  Node: fstat,  Up: (dir)



STAT(2)                    System calls                   STAT(2)

NAME
       stat, fstat, lstat - get file status

SYNOPSIS
       #include <sys/stat.h>
       #include <unistd.h>

       int stat(const char *file_name, struct stat *buf);
       int fstat(int filedes, struct stat *buf);
       int lstat(const char *file_name, struct stat *buf);

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 stat
       ted, 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 statted in place of
       file_name.

       They all return a stat structure, which contains the  fol
       lowing 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  pro
       vide  a  notion of the "preferred" blocksize for efficient
       file system I/O.

       Not all of the Linux filesystems implement all of the time

Linux                      May 13, 1998                         1

STAT(2)                    System calls                   STAT(2)

       fields.   Traditionally,  st_atime is changed by mknod(2),
       utime(2), read(2), write(2), and truncate(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  set
       ting  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 bit
                       fields (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

Linux                      May 13, 1998                         2

STAT(2)                    System calls                   STAT(2)

                       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
                       permission

              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
                       permission

              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  travers
              ing the path.

       EFAULT Bad address.

       EACCES Permission denied.

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

       ENAMETOOLONG
              File name too long.

Linux                      May 13, 1998                         3

STAT(2)                    System calls                   STAT(2)

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)

Linux                      May 13, 1998                         4

