lstat(2)                            CLIX                            lstat(2)



  NAME

    lstat - Gets file status

  LIBRARY

    Berkeley Software Distribution Library (libbsd.a)

  SYNOPSIS

    #include <sys/types.h>

    #include <sys/stat.h>

    int lstat(
      char *path ,
      struct stat *buf );

  PARAMETERS

    path   Specifies the pathname of the file for which status is requested.

    buf    Points to a stat structure where status information is stored.

  DESCRIPTION

    The lstat() function obtains information about the named file except when
    the named file is a symbolic link.  In this case, lstat() function returns
    information about the link.

    The path parameter points to the pathname of a file.  Read, write, or
    execute permission of the named file is not required, but all directories
    listed in the pathname leading to the file must be searchable.

    The contents of the structure pointed to by buf include the following
    members:

    ushort  st_mode;   /* File mode (see mknod()) */
    ino_t   st_ino;    /* Inode number */
    dev_t   st_dev;    /* ID of device containing */
                       /*   a directory entry for this file */
    dev_t   st_rdev;   /* ID of device */
                       /*   This entry is defined only for */
                       /*   character or block special files */
    short   st_nlink;  /* Number of links */
    ushort  st_uid;    /* User ID of the file's owner */
    ushort  st_gid;    /* Group ID of the file's group */
    off_t   st_size;   /* File size in bytes */
    time_t  st_atime;  /* Time of last access */
    time_t  st_mtime;  /* Time of last data modification */
    time_t  st_ctime;  /* Time of last file status change */



  2/94 - Intergraph Corporation                                              1

  lstat(2)                            CLIX                            lstat(2)



                       /*   Times measured in seconds since */
                       /*   00:00:00 GMT, Jan. 1, 1970 */


    st_mode    The mode of the file as described in the mknod() function.

    st_ino     This uniquely identifies the file in a given file system.  The
               pair st_ino and st_dev uniquely identifies regular files.

    st_dev     This uniquely identifies the file system that contains the
               file.  Its value may be used as input to the ustat() function
               to determine more information about this file system.  No other
               meaning is associated with this value.

    st_rdev    This should be used only by administrative commands.  It is
               valid only for block special or character special files and
               only has meaning on the system where the file was configured.

    st_nlink   This should be used only by administrative commands.

    st_uid     The user ID of the file's owner.

    st_gid     The group ID of the file's group.

    st_size    The address of the end of the file for regular files.  For
               pipes or FIFOs, this is the count of the data currently in the
               file.  For block special or character special files, this is
               not defined.

    st_atime   Time when file data was last accessed.  This time is changed by
               the following functions:  creat(), mknod(), pipe(), symlink(),
               utime(), and read().

    st_mtime   Time when data was last modified.  This time is changed by the
               following functions: creat(), mknod(), pipe(), symlink(),
               utime(), and write().

    st_ctime   Time when file status was last changed.  This time is changed
               by the following functions:  chmod(), chown(), creat(), link(),
               mknod(), pipe(), symlink(), unlink(), utime(), and write().

  EXAMPLES

    To get file status for the current directory:

    struct stat statbuf;
    if (lstat(".", &statbuf) != 0)
         perror("lstat failed");


  RETURN VALUES



  2                                              Intergraph Corporation - 2/94

  lstat(2)                            CLIX                            lstat(2)



    Upon successful completion, a value of 0 is returned.  Otherwise, a value
    of -1 is returned and errno is set to indicate the error.

  ERRORS

    The lstat() function fails if one or more of the following is true:

    [ENOTDIR]
           A component of the path prefix is not a directory.

    [ENOENT]
           The named file does not exist or too many symbolic links were in
           the path.

    [EACCES]
           Search permission is denied for a component of the path prefix.

    [EFAULT]
           Either buf or path points to an invalid address.

    [EINTR]
           A signal was caught during the stat() function.

    [ENOLINK]
           The path parameter points to a remote machine and the link to that
           machine is no longer active.

    [EMULTIHOP]
           Components of path require hopping to multiple remote machines.

  RELATED INFORMATION

    Commands:  chmod(1), chown(1)

    Functions:  read(2), write(2), symlink(2), creat(2), link(2), mknod(2),
    pipe(2), time(2), unlink(2), utime(2)


















  2/94 - Intergraph Corporation                                              3