stat(2)

stat, stat64, lstat, lstat64 fstat, fstat64 -- get file status

Synopsis

   #include <sys/types.h>
   #include <sys/stat.h>
   
   int stat(const char path, struct stat buf);
   

   int stat64(const char path, struct stat64 buf);
   

   int lstat(const char path, struct stat buf);
   

   int lstat64(const char path, struct stat64 buf);
   

   int fstat(int fildes, struct stat buf);
   

   int fstat64(int fildes, struct stat64 buf);

Description

The stat system calls get information about a file. path points to a pathname naming a file. Read, write, or execute permission of the named file is not required, but all directories listed in the pathname leading to the file must be searchable.

If an Access Control List (ACL) exists for the file, the value of the file mode may not reflect the entire set of access permissions for the file [see acl].

lstat obtains file attributes similar to stat, except when the named file is a symbolic link; in that case lstat returns information about the link, while stat returns information about the file the link references.

fstat obtains information about an open file known by the file descriptor fildes, obtained from a successful creat, open, dup, fcntl, pipe, or ioctl system call.

buf is a pointer to a stat structure into which information is placed concerning the file.

For details on the stat and stat64 structures see stat(5).

Return values

On success, stat, lstat, fstat, stat64, lstat64, and fstat64 return 0. On failure, they return -1 and set errno to identify the error.

In the following conditions, stat, lstat and fstat fail and set errno to:

EOVERFLOW: A component is too large to store in the structure pointed to by buf.
EOVERFLOW: The file size, in bytes, cannot be represented correctly in the structure pointed to by buf.

In the following conditions, stat, stat64, lstat, and lstat64 fail and set errno to:

EACCES: Search permission is denied for a component of the path prefix.
EACCES: Read permission is denied on the named file.
EFAULT: buf or path points to an invalid address.
EINTR: A signal was caught during the stat, stat64, lstat, or lstat64 system call.
ELOOP: Too many symbolic links were encountered in translating path.
EMULTIHOP: Components of path require hopping to multiple remote machines and the file system does not allow it.
ENAMETOOLONG: The length of the path argument exceeds {PATH_MAX}, or the length of a path component exceeds {NAME_MAX} while _POSIX_NO_TRUNC is in effect.
ENOENT: The named file does not exist or is the null pathname.
ENOTDIR: A component of the path prefix is not a directory.
ENOLINK: path points to a remote machine and the link to that machine is no longer active.

In the following conditions, fstat and fstat64, fail and set errno to:

EBADF: fildes is not a valid open file descriptor.
EFAULT: buf points to an invalid address.
EINTR: A signal was caught during the fstat or fstat64 system call.
ENOLINK: fildes points to a remote machine and the link to that machine is no longer active.

References

acl(2), aclipc(2), chmod(2), chown(2), creat(2), fattach(3C), intro(2), link(2), mknod(2), pipe(2), read(2), realpath(3C), stat(5), time(2), unlink(2), utime(2), write(2)

Notices

Considerations for large file support

stat64, lstat64, and fstat64 support large files, but otherwise are identical to stat, lstat, and fstat, respectively. For details on programming for large file capable applications, see ``Large File Support'' on intro(2).