1LSTAT(3P)                  POSIX Programmer's Manual                 LSTAT(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       lstat - get symbolic link status
13

SYNOPSIS

15       #include <sys/stat.h>
16
17       int lstat(const char *restrict path, struct stat *restrict buf);
18
19

DESCRIPTION

21       The lstat() function shall be equivalent to stat(),  except  when  path
22       refers  to  a symbolic link. In that case lstat() shall return informa‐
23       tion about the link, while stat() shall return  information  about  the
24       file the link references.
25
26       For  symbolic links, the st_mode member shall contain meaningful infor‐
27       mation when used with the file type  macros,  and  the  st_size  member
28       shall  contain  the  length  of  the pathname contained in the symbolic
29       link. File mode bits and the contents of the remaining members  of  the
30       stat structure are unspecified.  The value returned in the st_size mem‐
31       ber is the length of the contents of the symbolic link,  and  does  not
32       count any trailing null.
33

RETURN VALUE

35       Upon successful completion, lstat() shall return 0. Otherwise, it shall
36       return -1 and set errno to indicate the error.
37

ERRORS

39       The lstat() function shall fail if:
40
41       EACCES A component of the path prefix denies search permission.
42
43       EIO    An error occurred while reading from the file system.
44
45       ELOOP  A loop exists in symbolic links encountered during resolution of
46              the path argument.
47
48       ENAMETOOLONG
49              The length of a pathname exceeds {PATH_MAX} or a pathname compo‐
50              nent is longer than {NAME_MAX}.
51
52       ENOTDIR
53              A component of the path prefix is not a directory.
54
55       ENOENT A component of path does not name an existing file or path is an
56              empty string.
57
58       EOVERFLOW
59              The  file size in bytes or the number of blocks allocated to the
60              file or the file serial number cannot be  represented  correctly
61              in the structure pointed to by buf.
62
63
64       The lstat() function may fail if:
65
66       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
67              resolution of the path argument.
68
69       ENAMETOOLONG
70              As a result of encountering a symbolic link in resolution of the
71              path  argument,  the  length  of the substituted pathname string
72              exceeded {PATH_MAX}.
73
74       EOVERFLOW
75              One of the members is too large  to  store  into  the  structure
76              pointed to by the buf argument.
77
78
79       The following sections are informative.
80

EXAMPLES

82   Obtaining Symbolic Link Status Information
83       The following example shows how to obtain status information for a sym‐
84       bolic link named  /modules/pass1.  The  structure  variable  buffer  is
85       defined  for  the  stat  structure.  If the path argument specified the
86       filename  for  the  file  pointed   to   by   the   symbolic   link   (
87       /home/cnd/mod1),  the results of calling the function would be the same
88       as those returned by a call to the stat() function.
89
90
91              #include <sys/stat.h>
92
93
94              struct stat buffer;
95              int status;
96              ...
97              status = lstat("/modules/pass1", &buffer);
98

APPLICATION USAGE

100       None.
101

RATIONALE

103       The lstat() function is not required to update the time-related  fields
104       if  the  named  file  is not a symbolic link. While the st_uid, st_gid,
105       st_atime, st_mtime, and st_ctime members  of  the  stat  structure  may
106       apply  to a symbolic link, they are not required to do so. No functions
107       in IEEE Std 1003.1-2001 are required to  maintain  any  of  these  time
108       fields.
109

FUTURE DIRECTIONS

111       None.
112

SEE ALSO

114       fstat(),  readlink(), stat(), symlink(), the Base Definitions volume of
115       IEEE Std 1003.1-2001, <sys/stat.h>
116

118       Portions of this text are reprinted and reproduced in  electronic  form
119       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
120       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
121       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
122       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
123       event of any discrepancy between this version and the original IEEE and
124       The Open Group Standard, the original IEEE and The Open Group  Standard
125       is  the  referee document. The original Standard can be obtained online
126       at http://www.opengroup.org/unix/online.html .
127
128
129
130IEEE/The Open Group                  2003                            LSTAT(3P)
Impressum