stat() — Get file information
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
POSIX.1 |
both |
Format
#define _POSIX_SOURCE
#include <sys/stat.h>
int stat(const char *__restrict__ pathname, struct stat *__restrict__ info);
General description
Gets status information about a specified file and places it in the area of memory pointed to by the info argument. The process does not need permissions on the file itself, but must have search permission on all directory components of the pathname. If the named file is a symbolic link, stat() resolves the symbolic link. It also returns information about the resulting file.
The information is returned as shown in the following stat structure table, as defined in the sys/stat.h header file.
Value | Description |
---|---|
mode_t st_mode | A bit string indicating the permissions and privileges of the Symbols are defined in the sys/stat.h header file to refer to bits in a mode_t value; these symbols are listed in chmod() — Change the mode of a file or directory. |
ino_t st_ino | The serial number of the file. |
dev_t st_dev | The numeric ID of the device containing the file. |
nlink_t st_nlink | The number of links to the file. |
uid_t st_uid | The numeric user ID (UID) of the file's owner. |
gid_t st_gid | The numeric group ID (GID) of the file's group. |
off_t st_size | For regular files, the file's size in bytes. For other kinds of files, the value of this field is unspecified. |
time_t st_atime | The most recent time the file was accessed. |
time_t st_ctime | The most recent time the status of the file was changed. |
time_t st_mtime | The most recent time the contents of the file were changed. |
Values for time_t_ are given in terms of seconds since epoch.
stat() updates the time-related fields before putting information in the stat structure.
- S_ISBLK(mode)
- Is nonzero for block special files.
- S_ISCHR(mode)
- Is nonzero for character special files.
- S_ISDIR(mode)
- Is nonzero for directories.
- S_ISEXTL(mode,genvalue)
- Is nonzero for external links.
- S_ISFIFO(mode)
- Is nonzero for pipes and FIFO special files.
- S_ISLNK(mode)
- Is nonzero for symbolic links.
- S_ISREG(mode)
- Is nonzero for regular files.
- S_ISSOCK(mode)
- Is nonzero for sockets.
If stat() successfully determines this information, it stores it in the area indicated by the info argument. The size of the buffer determines how much information is stored; data that exceeds the size of the buffer is truncated.
Large file support for z/OS UNIX files: Large z/OS UNIX files are supported automatically for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications must be compiled with the option LANGLVL(LONGLONG) and define the _LARGE_FILES feature test macro before any headers are included to enable this function to operate on z/OS UNIX files that are larger than 2 GB in size. File size and offset fields are enlarged to 63 bits in width. Therefore, any other function operating on the file is required to define the _LARGE_FILES feature test macro as well.
Returned value
If successful, stat() returns 0.
- Error Code
- Description
- EACCES
- The process does not have search permission on some component of the pathname prefix.
- EINVAL
- info is a NULL pointer.
- EIO
- Added for XPG4.2: An error occurred while reading from the file system.
- ELOOP
- A loop exists in symbolic links encountered during resolution of the pathname argument. This error is returned if more than POSIX_SYMLOOP (defined in the limits.h header file) symbolic links are encountered during resolution of the pathname argument.
- ENAMETOOLONG
- pathname is longer than PATH_MAX characters, or some component of pathname is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the path name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined with pathconf().
- ENOENT
- There is no file named pathname, or pathname is an empty string.
- ENOTDIR
- A component of the pathname prefix is not a directory.
- EOVERFLOW
- The file size in bytes or the number of blocks allocated to the file or the file serial number cannot be represented correctly in the structure pointed to by info.
Example
/* CELEBS33
This example gets status information about a file.
*/
#define _POSIX_SOURCE
#include <sys/types.h>
#include <sys/stat.h>
#undef _POSIX_SOURCE
#include <stdio.h>
#include <time.h>
main() {
struct stat info;
if (stat("/", &info) != 0)
perror("stat() error");
else {
puts("stat() returned the following information about root f/s:");
printf(" inode: %d\n", (int) info.st_ino);
printf(" dev id: %d\n", (int) info.st_dev);
printf(" mode: %08x\n", info.st_mode);
printf(" links: %d\n", info.st_nlink);
printf(" uid: %d\n", (int) info.st_uid);
printf(" gid: %d\n", (int) info.st_gid);
printf("created: %s", ctime(&info.st_createtime));
}
}
stat() returned the following information about root f/s:
inode: 0
dev id: 1
mode: 010001ed
links: 11
uid: 0
gid: 500
created: Fri Jun 16 10:07:55 2006
Related information
- sys/stat.h
- sys/types.h
- chmod() — Change the mode of a file or directory
- chown() — Change the owner or group of a file or directory
- creat() — Create a new file or rewrite an existing one
- dup() — Duplicate an open file descriptor
- fcntl() — Control open file descriptors
- fstat() — Get status information about a file
- link() — Create a link to a file
- lstat() — Get status of file or symbolic link
- mkdir() — Make a directory
- mkfifo() — Make a FIFO special file
- open() — Open a file
- pipe() — Create an unnamed pipe
- read() — Read from a file or socket
- readlink() — Read the value of a symbolic link
- remove() — Delete file
- rexec() — Execute commands one at a time on a remote host
- symlink() — Create a symbolic link to a path name
- unlink() — Remove a directory entry
- utime() — Set file access and modification times
- write() — Write data on a file or socket