stat(S)                        6 January 1993                        stat(S)


 Name

    stat, fstat, lstat, statlstat - returns file status

 Syntax


    cc  . . .  -lc


    #include  <sys/types.h>
    #include  <sys/stat.h>

    int stat (path, buf)
    char *path;
    struct stat *buf;

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

    int lstat (path, buf)
    char *path;
    struct stat *buf;

    int statlstat (path, buf)
    char *path;
    struct stat *buf;

    S_ISBLK (fmode)

    S_ISCHR (fmode)

    S_ISDIR (fmode)

    S_ISFIFO (fmode)

    S_ISNAM (fmode)

    S_ISREG (fmode)


 Description

    The stat system call obtains information about the named file.  Both the
    stat and fstat functions update any time-related fields before writing
    into the stat structure.

    fstat obtains information about an open file known by the file descriptor
    fildes, obtained from a successful open, creat, dup, fcntl, or pipe sys-
    tem call.

    lstat obtains information about a symbolic link.  Use the macro SISLNK
    to determine if the file is a symbolic link.

    Calls to lstat or symlink made on a kernel on which these calls are not
    supported, such as SCO UNIX System V Version 2.0, produce the signal SIG-
    SYS.  Programs can be made to operate correctly on kernels that do and do
    not support these routines by first calling lstat(S) and then calling
    stat(S) if SIGSYS is produced by the first call.

    path points to a path name naming a file.  Read, write, or execute per-
    mission of the named file is not required, but all directories listed in
    the path name leading to the file must be searchable.  An implementation
    that provides extended security controls may, under implementation-
    defined conditions, cause the stat function to fail.  In particular, the
    system may deny the existence of the file specified by path.

    The lstat system call is supported by SCO UNIX System V Version 4.0, but
    not by earlier versions of SCO UNIX.  A SIGSYS signal is sent to a pro-
    gram attempting an lstat system call on earlier versions, which typically
    results in a core dump.  If you are developing a program to use lstat,
    and that program is also required to run on systems which do not support
    lstat, then you should use statlstat in place of lstat.  On its first
    call to lstat, statlstat uses signal(S) to catch SIGSYS without core
    dumping, and uses stat instead and thereafter, if the system does not
    support lstat.

    The SIS* macros provide POSIX file testing capabilities.  The fmode
    argument is the file mode.  If a test is correct, a nonzero value is
    returned; otherwise, a value of zero is returned.  The purpose of the
    update any time-related fieeds before writing into the macros is:

    _________________________________________________________________________
    Macro     Purpose
    _________________________________________________________________________
    S_ISBLK   determine if file is a block special file
    S_ISCHR   determine if file is a character special file
    S_ISDIR   determine if file is a directory
    S_ISFIFO  determine if file is a first-in, first-out (FIFO)
    S_ISNAM   determine if file is a special named file
    S_ISREG   determine if file is a regular file


    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 include the following
    members:

       dev_t st_dev;           /* ID of device containing */
                               /* a directory entry for this file */
       ino_t   st_ino;         /* Inode number */
       mode_t  st_mode;        /* File mode (see mknod (S)) */
       nlink_t st_nlink;       /* Number of links */
       uid_t   st_uid;         /* User ID of the file's owner */
       gid_t   st_gid;         /* Group ID of the file's group */
       dev_t   st_rdev;        /* ID of device */
                               /* This entry is defined only for */
                               /* character special or */
                               /* block special files */
       off_t   st_size;        /* File size in bytes */
       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 */
                               /* Times measured in seconds since */
                               /* 00:00:00 GMT, Jan. 1, 1970 */


    stmode   The mode of the file as described in the mknod(S) system call.

    stino    This field uniquely identifies the file in a given file system.
              The pair stino and stdev uniquely identifies regular files.

    stdev    This field uniquely identifies the file system that contains
              the file.  Its value may be used as input to the ustat(S) sys-
              tem call to determine more information about this file system.
              No other meaning is associated with this value.

    strdev   This field should be used only by administrative commands.  It
              is valid only for block special or character special files and
              only has meaning on the system where the file was configured.

    stnlink  This field should be used only by administrative commands.

    stuid    The user ID of the file's owner.

    stgid    The group ID of the file's group.

    stsize   For regular files, this is the address of the end of the file.
              For pipes or fifos, this is the count of the data currently in
              the file.  For block special or character special, this is not
              defined.

    statime  Time when file data was last accessed.  Changed by the follow-
              ing system calls:  creat(S), mknod(S), pipe(S), utime(S), and
              read(S).

    stmtime  Time when data was last modified.  Changed by the following
              system calls:  creat(S), link(S), mknod(S), pipe(S), unlink(S),
              utime(S), and write(S).

    stctime  Time when file status was last changed.  Changed by the follow-
              ing system calls:  chmod(S), chown(S), creat(S), link(S),
              mknod(S), pipe(S), unlink(S), utime(S), and write(S).

    The stat system call fails if one or more of the following is true:

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

    [ENAMETOOLONG] The length of the path argument exceeds [PATHMAX] or a
                   pathname component is longer than [NAMEMAX] while
                   [POSIXNOTRUNC] is in effect.

    [ENOENT]       The named file does not exist.

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

    fstat fails if:

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


 Diagnostics

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

 See also

    chmod(S), chown(S), creat(S), link(S), mknod(S), pipe(S), read(S),
    readlink(S), symlink(S), time(S), unlink(S), utime(S), write(S)

 Standards conformance

    fstat and stat are conformant with:
    AT&T SVID Issue 2;
    X/Open Portability Guide, Issue 3, 1989;
    Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2);
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1); and NIST FIPS 151-1.

    lstat and statlstat are not part of any currently supported standard;
    they are an extension of AT&T System V provided by the Santa Cruz Opera-
    tion.