14.9.2 Reading the Attributes of a File

To examine the attributes of files, use the functions stat,
fstat and lstat. They return the attribute information in
a struct stat object. All three functions are declared in the
header file sys/stat.h.

The stat function returns information about the attributes of the
file named by filename in the structure pointed to by buf.

If filename is the name of a symbolic link, the attributes you get
describe the file that the link points to. If the link points to a
nonexistent file name, then stat fails reporting a nonexistent
file.

The return value is 0 if the operation is successful, or
-1 on failure. In addition to the usual file name errors
(see File Name Errors, the following errno error conditions
are defined for this function:

ENOENT

The file named by filename doesn’t exist.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this
function is in fact stat64 since the LFS interface transparently
replaces the normal implementation.

This function is similar to stat but it is also able to work on
files larger than 2^31 bytes on 32-bit systems. To be able to do
this the result is stored in a variable of type struct stat64 to
which buf must point.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this
function is available under the name stat and so transparently
replaces the interface for small files on 32-bit machines.

This function is similar to fstat but is able to work on large
files on 32-bit platforms. For large files the file descriptor
filedes should be obtained by open64 or creat64.
The buf pointer points to a variable of type struct stat64
which is able to represent the larger values.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this
function is available under the name fstat and so transparently
replaces the interface for small files on 32-bit machines.

The lstat function is like stat, except that it does not
follow symbolic links. If filename is the name of a symbolic
link, lstat returns information about the link itself; otherwise
lstat works like stat. See Symbolic Links.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this
function is in fact lstat64 since the LFS interface transparently
replaces the normal implementation.

This function is similar to lstat but it is also able to work on
files larger than 2^31 bytes on 32-bit systems. To be able to do
this the result is stored in a variable of type struct stat64 to
which buf must point.

When the sources are compiled with _FILE_OFFSET_BITS == 64 this
function is available under the name lstat and so transparently
replaces the interface for small files on 32-bit machines.