lstat()
NAME
lstat − get symbolic link status
SYNOPSIS
#include <sys/stat.h>
int lstat(const char *path, struct stat *buf);
DESCRIPTION
The lstat() function has the same effect as stat(), except when path refers to a symbolic link. In that case lstat() returns information about the link, while stat() returns information about the file the link references.
For symbolic links, the st_mode member will contain meaningful information when used with the file type macros, and the st_size member will contain the length of the pathname contained in the symbolic link. File mode bits and the contents of the remaining members of the stat structure are unspecified. The value returned in the st_size member is the length of the contents of the symbolic link, and does not count any trailing null.
RETURN VALUE
Upon successful completion, lstat() returns 0. Otherwise, it returns −1 and sets errno to indicate the error.
ERRORS
The lstat() function will fail if:
[EACCES] A component of the path prefix denies search permission.
[EIO] An error occurred while reading from the file system.
[ELOOP] Too many symbolic links were encountered in resolving path.
[ENAMETOOLONG] The length of a pathname exceeds {PATH_MAX}, or pathname component is longer than {NAME_MAX}.
[ENOTDIR] A component of the path prefix is not a directory.
[ENOENT] A component of path does not name an existing file or path is an empty string.
[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.
The lstat() function may fail if:
[ENAMETOOLONG] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.
SEE ALSO
fstat(), readlink(), stat(), symlink(), <sys/stat.h>.
CHANGE HISTORY
First released in Issue 4, Version 2.
HP−UX EXTENSIONS
SYNOPSIS
#include <sys/stat.h>
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 lstat() function is 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 points to an invalid address. The reliable detection of this error is implementation dependent.
No ERROR for the following:
[EIO] An error occurred while reading from the file system.
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
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), lstat64(2), mknod(2), pipe(2), read(2), rename(2), setacl(2), sysfs(2), time(2), truncate(2), unlink(2), utime(2), write(2), stat(5), privileges(5), acl(5), stat(5).
STANDARDS CONFORMANCE
lstat(): AES, SVID3
Hewlett-Packard Company — HP-UX Release 10.20: July 1996