STAT(2) BSD System Calls Manual STAT(2)

NAME
     ffssttaatt, ffssttaatt6644, llssttaatt, llssttaatt6644, ssttaatt, ssttaatt6644 - get file status

SYNOPSIS
     ##iinncclluuddee <>

     int
     ffssttaatt(int fildes, struct stat *buf);

     int
     ffssttaatt6644(int fildes, struct stat64 *buf);

     int
     llssttaatt(const char *restrict path, struct stat *restrict buf);

     int
     llssttaatt6644(const char *restrict path, struct stat64 *restrict buf);

     int
     ssttaatt(const char *restrict path, struct stat *restrict buf);

     int
     ssttaatt6644(const char *restrict path, struct stat64 *restrict buf);

DESCRIPTION
     The ssttaatt() family of functions and their 64 bit variants obtain informa-
     tion about a file. The ssttaatt() function obtains information about the file
     pointed to by 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 searchable.

     LLssttaatt() is like ssttaatt() except in the case where the named file is a sym-
     bolic link, in which case llssttaatt() returns information about the link,
     while ssttaatt() returns information about the file the link references.
     Unlike other filesystem objects, symbolic links do not have an owner,
     group, access mode, times, etc.  Instead, these attributes are taken from
     the directory that contains the link.  The only attributes returned from
     an llssttaatt() that refer to the symbolic link itself are the file type
     (SIFLNK), size, blocks, and link count (always 1).

     The ffssttaatt() obtains the same information about an open file known by the
     file descriptor fildes.

     The buf argument is a pointer to a stat or stat64 structure as defined by
      (both shown below) and into which information is placed con-
     cerning the file.

     struct stat {
         devt    stdev;    /* device inode resides on */
         inot    stino;    /* inode's number */
         modet   stmode;   /* inode protection mode */
         nlinkt  stnlink;  /* number or hard links to the file */
         uidt    stuid;    /* user-id of owner */
         gidt    stgid;    /* group-id of owner */
         devt    strdev;   /* device type, for special file inode */
         struct timespec statimespec;  /* time of last access */
         struct timespec stmtimespec;  /* time of last data modification */
         struct timespec stctimespec;  /* time of last file status change */
         offt    stsize;   /* file size, in bytes */
         quadt   stblocks; /* blocks allocated for file */
         ulong   stblksize;/* optimal file sys I/O ops blocksize */
         ulong   stflags;  /* user defined flags for file */
         ulong   stgen;    /* file generation number */
     };


     struct stat64 {
         devt           stdev;           /* ID of device containing file */
         modet          stmode;          /* Mode of file (see below) */
         nlinkt         stnlink;         /* Number of hard links */
         ino64t         stino;          /* File serial number */
         uidt           stuid;           /* User ID of the file */
         gidt           stgid;           /* Group ID of the file */
         devt           strdev;          /* Device ID */
         struct timespec statimespec;     /* time of last access */
         struct timespec stmtimespec;     /* time of last data modification */
         struct timespec stctimespec;     /* time of last status change */
         struct timespec stbirthtimespec; /* time of file creation(birth) */
         offt           stsize;          /* file size, in bytes */
         blkcntt        stblocks;        /* blocks allocated for file */
         blksizet       stblksize;       /* optimal blocksize for I/O */
         uint32t        stflags;         /* user defined flags for file */
         uint32t        stgen;           /* file generation number */
         int32t         stlspare;        /* RESERVED: DO NOT USE! */
         int64t         stqspare[2];     /* RESERVED: DO NOT USE! */
     };



     The time-related fields of struct stat and struct stat64 are as follows:

     statime         Time when file data last accessed.  Changed by the
                      mknod(2), utimes(2) and read(2) system calls.

     stmtime         Time when file data last modified.  Changed by the
                      mknod(2), utimes(2) and write(2) system calls.

     stctime         Time when file status was last changed (inode data modi-
                      fication).  Changed by the chmod(2), chown(2), link(2),
                      mknod(2), rename(2), unlink(2), utimes(2) and write(2)
                      system calls.

     stbirthtime     Time of file creation. Only set once when the file is
                      created. This field is only available in the 64 bit
                      variants. On filesystems where birthtime is not avail-
                      able, this field holds the ctime instead.

     The size-related fields of the structures are as follows:

     stblksize     The optimal I/O block size for the file.

     stblocks      The actual number of blocks allocated for the file in
                    512-byte units.  As short symbolic links are stored in the
                    inode, this number may be zero.

     The status information word stmode has the following bits:

     #define SIFMT 0170000           /* type of file */
     #define        SIFIFO  0010000  /* named pipe (fifo) */
     #define        SIFCHR  0020000  /* character special */
     #define        SIFDIR  0040000  /* directory */
     #define        SIFBLK  0060000  /* block special */
     #define        SIFREG  0100000  /* regular */
     #define        SIFLNK  0120000  /* symbolic link */
     #define        SIFSOCK 0140000  /* socket */
     #define        SIFWHT  0160000  /* whiteout */
     #define SISUID 0004000  /* set user id on execution */
     #define SISGID 0002000  /* set group id on execution */
     #define SISVTX 0001000  /* save swapped text even after use */
     #define SIRUSR 0000400  /* read permission, owner */
     #define SIWUSR 0000200  /* write permission, owner */
     #define SIXUSR 0000100  /* execute/search permission, owner */

     For a list of access modes, see , access(2) and chmod(2).

     For a list of the file flags in the stflags field, see  and
     chflags(2).

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

CCOOMMPPAATTIIBBIILLIITTYY
     Previous versions of the system used different types for the stdev,
     stuid, stgid, strdev, stsize, stblksize and stblocks fields.

EERRRROORRSS
     The ffssttaatt() system call will fail if:

     [EBADF]            fildes is not a valid open file descriptor.

     [EFAULT]           Sb points to an invalid address.

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

     The llssttaatt() and ssttaatt() system calls will fail if:

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

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

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

     [ELOOP]            Too many symbolic links are encountered in translating
                        the pathname.  This is taken to be indicative of a
                        looping symbolic link.

     [ENAMETOOLONG]     A component of a pathname exceeds {NAMEMAX} charac-
                        ters, or an entire path name exceeds {PATHMAX} char-
                        acters.

     [ENOENT]           The named file does not exist.

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

     The ffssttaatt(), llssttaatt(), and ssttaatt() system calls will fail if:

     [EOVERFLOW]        The file size in bytes or the number of blocks allo-
                        cated to the file or the file serial number cannot be
                        represented correctly in the structure pointed to by
                        buf.

CCAAVVEEAATTSS
     The file generation number, stgen, is only available to the super-user.
     The fields in the stat structure currently marked stspare1, stspare2,
     and stspare3 are present in preparation for inode time stamps expanding
     to 64 bits.  This, however, can break certain programs that depend on the
     time stamps being contiguous (in calls to utimes(2)).

LEGACY SYNOPSIS
     ##iinncclluuddee <>
     ##iinncclluuddee <>

     The include file  is necessary.

SEE ALSO
     chflags(2), chmod(2), chown(2), utimes(2), compat(5), symlink(7)

BUGS
     Applying fstat to a socket (and thus to a pipe) returns a zero'd buffer,
     except for the blocksize field, and a unique device and inode number.

STANDARDS     The ssttaatt() and ffssttaatt() function calls are expected to conform to IEEE Std
     1003.1-1988 (``POSIX.1'').

HISTORY     An llssttaatt() function call appeared in 4.2BSD.  The ssttaatt6644(), ffssttaatt6644(),
     and llssttaatt6644() system calls first appeared in Mac OS X 10.5 (Leopard).

4th Berkeley Distribution       April 19, 1994       4th Berkeley Distribution