STAT(2)

NAME
stat, lstat, fstat - get file status

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

int stat (const char *path, struct stat *sb);
int lstat (const char *path, struct stat *sb);
int fstat (int fd, struct stat *sb);

DESCRIPTION
These calls are used to retrieve status information about files. They do much the same think as the GS/OS call GetFileInfoGS, except that they return the information in a format compatible with Unix's stat calls, and also provide information about sockets and GNO character devices.

The stat 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.

lstat is like stat except in the case where the named file is a symbolic link, in which case lstat returns information about the link, while stat 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 lstat that refer to the symbolic link itself are the file type (S_IFLNK), size, blocks, and link count (always 1).

The fstat obtains the same information about an open file known by the file descriptor fd.

The sb argument is a pointer to a stat structure as defined by <sys/stat.h> (shown below) and into which information is placed concerning the file.
struct stat {
    dev_t    st_dev;    /* device inode resides on */
    ino_t    st_ino;    /* inode's number */
    mode_t   st_mode;   /* inode protection mode */
    nlink_t  st_nlink;  /* number or hard links to the file */
    uid_t    st_uid;    /* user-id of owner */
    gid_t    st_gid;    /* group-id of owner */
    dev_t    st_rdev;   /* device type, for special file inode */
    off_t    st_size;   /* file size, in bytes */
    time_t   st_atime;  /* time of last access (GNO: same as st_mtime) */
    int      st_spare1; /* reserved */
    time_t   st_mtime;  /* time of last data modification */
    int      st_spare2; /* reserved */
    time_t   st_ctime;  /* time of last file status change */
    int      st_spare3; /* reserved */
    long     st_blksize;/* size in bytes of blocks on filesystem */
    long     st_blocks; /* blocks allocated for file */
    long     st_spare4[2]; /* reserved */
}

The items marked 'reserved' are not currently used but are reserved for future expansion; do not use these fields for any reason. st_dev is the number of the device on which the file resides. This number is the same as the GS/OS device ID number. st_rdev is not currently used, but may in the future designate a device type code.

As short symbolic links are stored in the inode, st_blocks may be zero.

The status information word st_mode has the following bits:
#define S_IFCHR  0020000  /* character special */
#define S_IFDIR  0040000  /* directory */
#define S_IFBLK  0060000  /* block special */
#define S_IFREG  0100000  /* regular */
#define S_IFLNK  0120000  /* symbolic link */
#define S_IFSOCK 0140000  /* socket */
#define S_IRUSR  0000400  /* read permission, owner */
#define S_IWUSR  0000200  /* write permission, owner */
#define S_IXUSR  0000100  /* execute/search permission, owner */

For a list of access modes, see <sys/stat.h>, access(2) and chmod(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.

COMPATIBILITY
BSD uses a larger set of defined fields than does GNO. The types of the fields also, in general, differ.

The stat man page for GNO v2.0.4 documented the macros S_IREAD, S_IWRITE, and S_IEXEC. These macros are still available in <sys/stat.h> provided that _POSIX_SOURCE is not defined.

ERRORS
Stat and lstat will fail if:

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

    ENOENT
        The named file does not exist.

    EBADF
        fd does not refer to an open file.

    Fstat will fail if:

    EBADF
        fd is not a valid open file descriptor.

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

SEE ALSO
chmod(2), chown(2), utimes(2) symlink(7)

BUGS
GNO does not yet support hard or symbolic file links on the IIgs. Therefore, lstat operates exactly like stat. If there's a case where lstat might be more appropriate at a time when links are supported, then use lstat instead and be ready for the future.

fstat doesn't do anything clever with all the unused fields when its argument is a pipe or terminal.

STANDARDS
The stat and fstat function calls are close, but do not conform, to IEEE Std 1003.1-1988 (POSIX). In particular,

    - this implementation does not make the distinction of file ownership;

    - not all the required error return codes are implemented; and

    - file access time mirrors modification time.

HISTORY
An lstat function call appeared in 4.2BSD.