STAT(2)

NAME
stat, fstat, lstat - grab inode information.

SYNOPSIS
#include <sys/stat.h>
#include <unistd.h>
int stat (const char *file_name, struct stat_buf *buf);
int fstat (int filedes, struct stat_buf *buf);
int lstat (const char *file_name, struct stat_buf *buf);

DESCRIPTION
stat(), fstat(), and lstat() return a stat_buf structure, which is declared as follows in sys/stat.h:
struct  stat {
dev_t	st_dev;
ino_t	st_ino;
umode_t	st_mode;
nlink_t	st_nlink;
uid_t	st_uid;
gid_t	st_gid;
dev_t	st_rdev;
off_t	st_size;
time_t	st_atime;
time_t	st_mtime;
time_t	st_ctime;
};

The following flags are defined in the st_mode field :
S_IFMT
S_IFLNK
S_IFREG
S_IFBLK
S_IFDIR
S_IFCHR
S_IFIFO
S_ISUID
S_ISGID
S_ISVTX

And the following macros are defined to utilize those fields :
#define S_ISLNK(m)	(((m) & S_IFMT) == S_IFLNK)
#define S_ISREG(m)	(((m) & S_IFMT) == S_IFREG)
#define S_ISDIR(m)	(((m) & S_IFMT) == S_IFDIR)
#define S_ISCHR(m)	(((m) & S_IFMT) == S_IFCHR)
#define S_ISBLK(m)	(((m) & S_IFMT) == S_IFBLK)
#define S_ISFIFO(m)	(((m) & S_IFMT) == S_IFIFO)
#define S_IRWXU 00700
#define S_IRUSR 00400
#define S_IWUSR 00200
#define S_IXUSR 00100
#define S_IRWXG 00070
#define S_IRGRP 00040
#define S_IWGRP 00020
#define S_IXGRP 00010
#define S_IRWXO 00007
#define S_IROTH 00004
#define S_IWOTH 00002
#define S_IXOTH 00001

stat() stats the file pointed to by file_name and fills in the stat_buf pointed to by 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 is stated in place of file_name.

0 is returned on success, a negative value on error. -EBADF is returned by fstat() on a bad file descriptor.

-ENOENT is returned when you attempt to stat a non-existant file.

FILES
linux/fs/stat.c, /usr/include/linux/sys.h, /usr/include/unistd.h

BUGS
A user can stat files in directories where they have no permissions.