NAME
lstat — get symbolic link status
SYNOPSIS
#include <sys/stat.h>
int lstat(
const char *path,
struct stat *buf
);
PARAMETERS
The parameters for the
lstat()
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 where the file status information is stored.
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.
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
stat
structure contains the following members:
(Note that the position of items in this list does not necessarily
reflect the order of the members in the structure.)
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.
- [ELOOP]
Too many symbolic links were encountered in resolving path.
- [ENAMETOOLONG]
The length of a pathname exceeds
{PATH_MAX},
or the 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]
A 32-bit application is making this call on a file where the
st_size
or other field(s) would need to hold a 64-bit value.
- [EFAULT]
buf
points to an invalid address.
The reliable detection of this error is
implementation dependent.
The
lstat()
function may fail if:
- [ENAMETOOLONG]
The pathname resolution of a symbolic link produced an intermediate result
with a length exceeding
{PATH_MAX}.
NETWORKING FEATURES
NFS
The
st_basemode,
st_acl
and
st_aclv
fields are zero on files accessed remotely. The
st_acl
field is applicable to HFS File Systems only. The
st_aclv
field is applicable to JFS File Systems only.
WARNINGS
Access Control Lists - HFS and JFS File Systems Only
Access control list descriptions in this entry apply only to HFS and
JFS file systems on standard HP-UX operating systems.
For 32-bit applications,
st_ino
will be truncated to its least significant 32-bits for filesystems that use
64-bit values.
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),
acl(2),
chmod(2),
chown(2),
creat(2),
fstat(2),
link(2),
lstat64(2),
mknod(2),
pipe(2),
read(2),
readlink(2),
rename(2),
setacl(2),
stat(2),
symlink(2),
sysfs(2),
time(2),
truncate(2),
unlink(2),
utime(2),
write(2),
acl(5),
aclv(5),
privileges(5),
stat(5),
<sys/stat.h>.
STANDARDS CONFORMANCE
lstat(): AES, SVID3
CHANGE HISTORY
First released in Issue 4, Version 2.
Printable version
