lstat2

Usage

#include <sys/stat.h>

    /* Since glibc 2.20 */ _DEFAULT_SOURCE
        || _XOPEN_SOURCE >= 500
        || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
        || /* glibc 2.19 and earlier */ _BSD_SOURCE

    Since glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    Before glibc 2.10:
        _ATFILE_SOURCE

Library

Standard C library (libc, -lc)

Overview

These functions return information about a file, in the buffer pointed to by statbuf. No permissions are required on the file itself, but—in the case of stat(), fstatat(), and lstat()—execute (search) permission is required on all of the directories in path that lead to the file.

stat() and fstatat() retrieve information about the file pointed to by path; the differences for fstatat() are described below.

lstat() is identical to stat(), except that if path is a symbolic link, then it returns information about the link itself, not the file that the link refers to.

fstat() is identical to stat(), except that the file about which information is to be retrieved is specified by the file descriptor fd.

Return value

On success, zero is returned. On error, -1 is returned, and errno is set to indicate the error.

Errors

EACCES

Search permission is denied for one of the directories in the path prefix of path. (See also path_resolution(7).)

EBADF

fd is not a valid open file descriptor.

EBADF

(fstatat()) path is relative but dirfd is neither AT_FDCWD nor a valid file descriptor.

EFAULT

Bad address.

EINVAL

(fstatat()) Invalid flag specified in flags.

ELOOP

Too many symbolic links encountered while traversing the path.

ENAMETOOLONG

path is too long.

ENOENT

A component of path does not exist or is a dangling symbolic link.

ENOENT

path is an empty string and AT_EMPTY_PATH was not specified in flags.

ENOMEM

Out of memory (i.e., kernel memory).

ENOTDIR

A component of the path prefix of path is not a directory.

ENOTDIR

(fstatat()) path is relative and dirfd is a file descriptor referring to a file other than a directory.

EOVERFLOW

path or fd refers to a file whose size, inode number, or number of blocks cannot be represented in, respectively, the types off_t, ino_t, or blkcnt_t. This error can occur when, for example, an application compiled on a 32-bit platform without -D_FILE_OFFSET_BITS=64 calls stat() on a file whose size exceeds (1<<31)-1 bytes.

Examples

The following program calls lstat() and displays selected fields in the returned stat structure.

#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>
#include <sys/sysmacros.h>
#include <time.h>
int
main(int argc, char *argv[])
{
    struct stat sb;
    if (argc != 2) {
        fprintf(stderr, "Usage: %s <path>\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    if (lstat(argv[1], &sb) == -1) {
        perror("lstat");
        exit(EXIT_FAILURE);
    }
    printf("ID of containing device:  [%x,%x]\n",
           major(sb.st_dev),
           minor(sb.st_dev));
    printf("File type:                ");
    switch (sb.st_mode & S_IFMT) {
    case S_IFBLK:  printf("block device\n");            break;
    case S_IFCHR:  printf("character device\n");        break;
    case S_IFDIR:  printf("directory\n");               break;
    case S_IFIFO:  printf("FIFO/pipe\n");               break;
    case S_IFLNK:  printf("symlink\n");                 break;
    case S_IFREG:  printf("regular file\n");            break;
    case S_IFSOCK: printf("socket\n");                  break;
    default:       printf("unknown?\n");                break;
    }
    printf("I-node number:            %ju\n", (uintmax_t) sb.st_ino);
    printf("Mode:                     %jo (octal)\n",
           (uintmax_t) sb.st_mode);
    printf("Link count:               %ju\n", (uintmax_t) sb.st_nlink);
    printf("Ownership:                UID=%ju   GID=%ju\n",
           (uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid);
    printf("Preferred I/O block size: %jd bytes\n",
           (intmax_t) sb.st_blksize);
    printf("File size:                %jd bytes\n",
           (intmax_t) sb.st_size);
    printf("Blocks allocated:         %jd\n",
           (intmax_t) sb.st_blocks);
    printf("Last status change:       %s", ctime(&sb.st_ctime));
    printf("Last file access:         %s", ctime(&sb.st_atime));
    printf("Last file modification:   %s", ctime(&sb.st_mtime));
    exit(EXIT_SUCCESS);
}