STAT

Section: Linux Programmer's Manual (2)
Updated: 1 January 1995
Index Return to Main Contents
 

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 provide 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 setting 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 bitfields
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)


 

Index

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
ERRORS
CONFORMING TO
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 12:25:06 GMT, March 22, 2025