stat(2) stat(2) NAME stat - get file status SYNOPSIS OH #include <sys/types.h> #include <sys/stat.h> int stat(const char *path, struct stat *buf); DESCRIPTION The stat() function obtains information about the named file and writes it to the area pointed to by the buf argument. The path argument 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. An implementation that provides additional or alternate file access control mechanisms may, under implementation-dependent conditions, cause stat() to fail. In particular, the system may deny the existence of the file specified by path. The buf argument is a pointer to a stat structure, as defined in the header <sys/stat.h>, into which information is placed concerning the file. The stat() function updates any time-related fields (as described in the definition of File Times Update in the XBD specification), before writing into the stat structure. The structure members st_mode, st_ino, st_dev, st_uid, st_gid, st_atime, st_ctime, and st_mtime will have meaningful values for all file types defined in this document. The value of the member st_nlink will be set to the number of links to the file. RETURN VALUE Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno is set to indicate the error. ERRORS The stat() function will fail if: [EACCES] Search permission is denied for a component of the path prefix. [EIO] An error occurred while reading from the file system. [ELOOP] Too many symbolic links were encountered in resolving path. [ENAMETOOLONG] The length of the path argument exceeds {PATH_MAX} or a pathname component is Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 stat(2) stat(2) longer than {NAME_MAX}. [ENOENT] A component of path does not name an existing file or path is an empty string. [ENOTDIR] A component of the path prefix is not a directory. The stat() function may fail if: [ENAMETOOLONG] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}. [EOVERFLOW] A value to be stored would overflow one of the members of the stat structure. SEE ALSO fstat(), lstat(), <sys/stat.h>, <sys/types.h>. CHANGE HISTORY First released in Issue 1. Derived from Issue 1 of the SVID. Issue 4 The following changes are incorporated for alignment with the ISO POSIX-1 standard: o The type of argument path is changed from char * (Reg.)to const char * (Reg.). o In the DESCRIPTION section, (a) statements indicating the purpose of this interface and a paragraph defining the contents of stat structure members are added, and (b) the words "extended security controls" are replaced by "additional or alternate file access control mechanisms." The following change is incorporated for alignment with the FIPS requirements: o In the ERRORS section, the condition whereby [ENAMETOOLONG] will be returned if a pathname component is larger that {NAME_MAX} is now defined as mandatory and marked as an extension. Another change is incorporated as follows: o The header <sys/types.h> is now marked as optional (OH); this header need not be included on XSI-conformant systems. Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 stat(2) stat(2) Issue 4, Version 2 The ERRORS section is updated for X/OPEN UNIX conformance as follows: o In the mandatory section, EIO is added to indicate that a physical I/O error has occurred, and ELOOP to indicate that too many symbolic links were encountered during pathname resolution. o In the optional section, a second ENAMETOOLONG condition is defined that may report excessive length of an intermediate result of pathname resolution of a symbolic link. o In the optional section, EOVERFLOW is added to indicate that a value to be stored in a member of the stat structure would cause overflow. - 3 - Formatted: April 25, 2001 stat(2) stat(2) HP-UX EXTENSIONS DESCRIPTION If the chosen path name or file descriptor refers to a Multi-Level Directory (MLD), and the process does not have the multilevel effective privilege, the i-node number returned in st_ino is the i-node of the MLD itself. The parameters for the stat() function are as follows: path is a pointer to a path name of any file within the mounted file system. (All directories listed in the path name must be searchable.) buf is a pointer to a stat structure, which is where the file status information is stored. The stat structure contains the following members: dev_t st_dev; /* ID of device containing a */ /* directory entry for this file */ ino_t st_ino; /* Inode number */ ushort st_fstype; /* Type of filesystem this file */ /* is in; see sysfs(2) */ ushort st_mode; /* File type, attributes, and */ /* access control summary */ ushort st_basemode /* Permission bits (see chmod(1)) */ ushort st_nlink; /* Number of links */ uid_t st_uid; /* User ID of file owner */ gid_t st_gid; /* Group ID of file group */ dev_t st_rdev; /* Device ID; this entry defined */ /* only for char or blk spec files */ off_t st_size; /* File size (bytes) */ time_t st_atime; /* Time of last access */ time_t st_mtime; /* Last modification time */ time_t st_ctime; /* Last file status change time */ /* Measured in secs since */ /* 00:00:00 GMT, Jan 1, 1970 */ long st_blksize; /* File system block size */ uint st_acl:1; /* Set if the file has optional */ /* access control list entries */ /* HFS File Systems only */ (Note that the position of items in this list does not necessarily reflect the order of the members in the structure.) ERRORS [EFAULT] buf or path points to an invalid address. The reliable detection of this error is implementation Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 stat(2) stat(2) dependent. [EOVERFLOW] The file size in bytes or the number of blocks allocated to the file cannot be represented correctly in the structure pointed to by buf. NFS The st_basemode and st_acl fields are zero on files accessed remotely. st_acl field is applicable to HFS File Systems only. WARNINGS Access Control Lists - HFS File Systems only Access control list descriptions in this entry apply only to HFS file systems on standard HP-UX operating systems. DEPENDENCIES CD-ROM The st_uid and st_gid fields are set to -1 if they are not specified on the disk for a given file. AUTHOR stat() and fstat() were developed by AT&T. lstat() was developed by the University of California, Berkeley. SEE ALSO touch(1), chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2), read(2), rename(2), setacl(2), stat64(2), sysfs(2), time(2), truncate(2), unlink(2), utime(2), write(2), acl(5), stat(5). STANDARDS CONFORMANCE stat(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996