stat(2)

NAME

stat, lstat, fstat − get file status

SYNTAX

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

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

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

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

DESCRIPTION

The stat system call obtains detailed information about file name. The fstat system call obtains the same information about an open file known by the fildes returned from a successful creat, dup, fcntl, open, or pipe call.

The lstat system call is similar to stat, except in the case where the named file is a symbolic link. In that case, lstat returns information about the link, while stat returns information about the file the link references.

The specified name points to a null-terminated string naming a file. The buf is the address of a buffer into which information concerning the file is placed. It is unnecessary to have any permissions at all with respect to the file, but all directories leading to the file must be searchable. The layout of the structure pointed to by buf as defined in <stat.h>. The st_mode is encoded according to the #define statements.

struct stat
{
        dev_t   st_dev;
        ino_t   st_ino;
        ushort st_mode;
        short   st_nlink;
        ushort st_uid;
        ushort st_gid;
        dev_t   st_rdev;
        off_t   st_size;
        time_t st_atime;
        time_t st_mtime;
        time_t st_ctime;
};
#define S_IFMT   0170000 /* type of file */
#define S_IFDIR 0040000 /* directory */
#define S_IFCHR 0020000 /* character special */
#define S_IFBLK 0060000 /* block special */
#define S_IFLNK 0120000 /* symbolic link */
#define S_IFREG 0100000 /* regular */
#define S_IFIFO 0010000 /* fifo */
#define S_ISUID 0004000 /* set user id on execution */
#define S_ISGID 0002000 /* set group id on execution */
#define S_ISVTX 0001000 /* save swapped text even after use */
#define S_IREAD 0000400 /* read permission, owner */
#define S_IWRITE 0000200 /* write permission, owner */
#define S_IEXEC 0000100 /* execute/search permission, owner */

st_atime Time when file data was last accessed. Changed by the creat, mknod, pipe, read, and utime calls.

st_mtime Time when data was last modified. Changed by the creat, mknod, pipe, utime, and write calls.

st_ctime Time when file status was last changed. Changed by the chmod, chown, creat, link, mknod, pipe, unlink, utime, and write.

The mode bits 0000070 and 0000007 encode group and others permissions. For further information, see chmod(2). The defined types, ino_t, off_t, time_t, name various width integer values. The dev_t encodes major and minor device numbers. Their exact definitions are in the include file <sys/types.h>. For further information, see types(5).

When fildes is associated with a pipe, fstat call reports an ordinary file with restricted permissions. The size is the number of bytes queued in the pipe.

The st_atime is the time the file was last read. For reasons of efficiency, it is not set when a directory is searched, although this would be more logical. The st_mtime is the time the file was last written or created. It is not set by changes of owner, group, link count, or mode. The st_ctime is set both by writing and changing the inode.

DIAGNOSTICS

The stat call will fail if:

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

[EFAULT] Either name or buf points to an invalid address.

[ENFILE] There is insufficient system space to contain the inode.

[ENOENT] Either the named file or an element within the named file does not exist.

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

The fstat call will fail if:

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

[EFAULT] The specified buf points to an address outside of the process’s allocated address space.

ASSEMBLER

(stat = 18.)
sys stat; name; buf

(fstat = 28.)
(file descriptor in r0)
sys fstat; buf

Museum