fstat

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

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
       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 fopen(3) ) is stated  in  place
       of file_name.


       They  all  return  a  stat structure, which is declared as
       follows:

              struct stat
              {
                  dev_t         st_dev;      /* device */
                  ino_t         st_ino;      /* inode */
                  umode_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
       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 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

              S_IFSOCK 0140000 socket

              S_IFLNK  0120000 symbolic link

              S_IFREG  0100000 regular file

              S_IFBLK  0060000 block device

              S_IFDIR  0040000 directory

              S_IFCHR  0020000 character device

              S_IFIFO  0010000 fifo

              S_ISUID  0004000 set UID bit

              S_ISGID  0002000 set GID bit

              S_ISVTX  0001000 sticky bit

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

              S_IRUSR (S_IREAD)
                       00400 user has read permission

              S_IWUSR (S_IWRITE)
                       00200 user has write permission

              S_IXUSR (S_IEXEC)
                       00100 user has execute permission

              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  File does not exist.


CONFORMING TO

       SVID  (not  lstat()),  AT&T  (not  lstat()),  POSIX   (not
       lstat()), X/OPEN (not lstat()), BSD 4.3


SEE ALSO

       chmod(2), chown(2), readlink(2), utime(2)
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.