lstat

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
       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(P)