huschi.net

LSTAT(3P)                  POSIX Programmer's Manual                 LSTAT(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       lstat - get symbolic link status
SYNOPSIS
       #include <sys/stat.h>
       int lstat(const char *restrict path, struct stat *restrict buf);

DESCRIPTION
       The lstat() function shall be equivalent to stat(),  except  when  path
       refers  to  a symbolic link. In that case lstat() shall return informa-
       tion about the link, while stat() shall return  information  about  the
       file the link references.
       For  symbolic links, the st_mode member shall contain meaningful infor-
       mation when used with the file type  macros,  and  the  st_size  member
       shall  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 mem-
       ber is the length of the contents of the symbolic link,  and  does  not
       count any trailing null.
RETURN VALUE
       Upon successful completion, lstat() shall return 0. Otherwise, it shall
       return -1 and set errno to indicate the error.
ERRORS
       The lstat() function shall fail if:
       EACCES A component of the path prefix denies search permission.
       EIO    An error occurred while reading from the file system.
       ELOOP  A loop exists in symbolic links encountered during resolution of
              the path argument.
       ENAMETOOLONG
              The length of a pathname exceeds {PATH_MAX} or a pathname compo-
              nent 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 or the file serial number cannot be  represented  correctly
              in the structure pointed to by buf.

       The lstat() function may fail if:
       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
              resolution of the path argument.
       ENAMETOOLONG
              As a result of encountering a symbolic link in resolution of the
              path  argument,  the  length  of the substituted pathname string
              exceeded {PATH_MAX}.
       EOVERFLOW
              One of the members is too large  to  store  into  the  structure
              pointed to by the buf argument.

       The following sections are informative.
EXAMPLES
   Obtaining Symbolic Link Status Information
       The following example shows how to obtain status information for a sym-
       bolic link named  /modules/pass1.  The  structure  variable  buffer  is
       defined  for  the  stat  structure.  If the path argument specified the
       filename  for  the  file  pointed   to   by   the   symbolic   link   (
       /home/cnd/mod1),  the results of calling the function would be the same
       as those returned by a call to the stat() function.

              #include <sys/stat.h>

              struct stat buffer;
              int status;
              ...
              status = lstat("/modules/pass1", &buffer);
APPLICATION USAGE
       None.
RATIONALE
       The lstat() function is not required to update the time-related  fields
       if  the  named  file  is not a symbolic link. While the st_uid, st_gid,
       st_atime, st_mtime, and st_ctime members  of  the  stat  structure  may
       apply  to a symbolic link, they are not required to do so. No functions
       in IEEE Std 1003.1-2001 are required to  maintain  any  of  these  time
       fields.
FUTURE DIRECTIONS
       None.
SEE ALSO
       fstat(),  readlink(), stat(), symlink(), the Base Definitions volume of
       IEEE Std 1003.1-2001, <sys/stat.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                            LSTAT(3P)