Reading Attributes (The GNU C Library)

#### 14.10.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`.

Function: `int` stat `(const char *filename, struct stat *buf)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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.

Function: `int` stat64 `(const char *filename, struct stat64 *buf)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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.

Function: `int` fstat `(int filedes, struct stat *buf)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  The `fstat` function is like `stat`, except that it takes an open file descriptor as an argument instead of a file name. See Low-Level Input/Output.

  Like `stat`, `fstat` returns `0` on success and `-1` on failure. The following `errno` error conditions are defined for `fstat`:

  `EBADF`

    The filedes argument is not a valid file descriptor.

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

Function: `int` fstat64 `(int filedes, struct stat64 *buf)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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.

Function: `int` fstatat `(int filedes, const char *filename, struct stat *buf, int flags)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This function is a descriptor-relative version of the `fstat` function above. See Descriptor-Relative Access. The flags argument can contain a combination of the flags `AT_EMPTY_PATH`, `AT_NO_AUTOMOUNT`, `AT_SYMLINK_NOFOLLOW`.

  Compared to `fstat`, the following additional error conditions can occur:

  `EBADF`

    The filedes argument is not a valid file descriptor.

  `EINVAL`

    The flags argument is not valid for this function.

  `ENOTDIR`

    The descriptor filedes is not associated with a directory, and filename is a relative file name.

  `ENOENT`

    The file named by filename does not exist, it’s a dangling symbolic link and flags does not contain `AT_SYMLINK_NOFOLLOW`, or filename is an empty string and flags does not contain `AT_EMPTY_PATH`.

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

Function: `int` fstatat64 `(int filedes, const char *filename, struct stat64 *buf, int flags)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This function is the large-file variant of `fstatat`, similar to how `fstat64` is the variant of `fstat`.

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

Function: `int` lstat `(const char *filename, struct stat *buf)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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.

Function: `int` lstat64 `(const char *filename, struct stat64 *buf)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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.