lstat(), lstat64() — Get status of file or symbolic link

Standards

Standards / Extensions C or C++ Dependencies
z/OS®
UNIX

XPG4.2
Single UNIX Specification, Version 3
both  

Format

lstat:
#define _POSIX1_SOURCE 2
#include <sys/stat.h>

int lstat(const char *__restrict__ pathname, struct stat *__restrict__ buf);
lstat64:
#define _LARGE_TIME_API
#define _POSIX1_SOURCE 2
#include <sys/stat.h>

int lstat64(const char *__restrict__ pathname, struct stat64 *__restrict__ info);

Compile requirement: Use of the lstat64 function requires the long long data type. For more information on how to make the long long data type available, see z/OS XL C/C++ Language Reference.

General description

Gets status information about a specified file and places it in the area of memory pointed to by the buf argument. You do not need permissions on the file itself, but you must have search permission on all directory components of the pathname.

If the named file is a symbolic link, lstat() returns information about the symbolic link itself.

The lstat64() function behaves exactly like lstat() except lstat64() uses structure stat64 instead of struct stat to support time beyond 03:14:07 UTC on January 19, 2038.

The information is returned in the following stat and stat64 structures, defined in the sys/stat.h header file.

Table 1. Values Returned in stat and stat64 Structures
Value for stat Value for stat64 Description
mode_t st_mode mode_t st_mode A bit string indicating the permissions and privileges of the Symbols are defined in the sys/stat.h header file to refer to bits in a mode_t value; these symbols are listed in chmod() — Change the mode of a file or directory.
ino_t st_ino ino_t st_ino The serial number of the file.
dev_t st_dev dev_t st_dev The numeric ID of the device containing the file.
nlink_t st_nlink nlink_t st_nlink The number of links to the file.
uid_t st_uid uid_t st_uid The numeric user ID (UID) of the file's owner.
gid_t st_gid gid_t st_gid The numeric group ID (GID) of the file's group.
off_t st_size long long st_size For regular files, the file's size in bytes. For other kinds of files, the value of this field is unspecified.
time_t st_atime time64_t st_atime The most recent time the file was accessed.
time_t st_ctime time64_t st_ctime The most recent time the status of the file was changed.
time_t st_mtime time64_t st_mtime The most recent time the contents of the file were changed.

Values for time_t and time64_t are given in terms of seconds that have elapsed since epoch.

If the named file is a symbolic link, lstat() updates the time-related fields before putting information in the stat structure.

You can examine properties of a mode_t value from the st_mode field by using a collection of macros defined in the sys/modes.h header file. If mode is a mode_t value, and genvalue is an unsigned int value from the stat structure, then:
S_ISBLK(mode)
Is nonzero for block special files.
S_ISCHR(mode)
Is nonzero for character special files.
S_ISDIR(mode)
Is nonzero for directories.
S_ISEXTL(mode,genvalue)
Is nonzero for external links.
S_ISFIFO(mode)
Is nonzero for pipes and FIFO special files.
S_ISLNK(mode)
Is nonzero for symbolic links.
S_ISREG(mode)
Is nonzero for regular files.
S_ISSOCK(mode)
Is nonzero for sockets.

If lstat() successfully determines all this information, it stores it in the area indicated by the buf argument.

Large file support for z/OS UNIX files: lstat64() automatically supports large z/OS UNIX files for both AMODE 31 and AMODE 64 C/C++ applications, which means there is no need for _LARGE_FILES feature test macro to be defined. As for lstat(), the automatic support is only for AMODE 64 C/C++ applications. AMODE 31 C/C++ applications must be compiled with the option LANGLVL(LONGLONG) and define the _LARGE_FILES feature test macro before any headers are included to enable lstat() to operate on z/OS UNIX files that are larger than 2 GB in size. File size and offset fields are enlarged to 63 bits in width. Therefore, any other function operating on the file is required to define the _LARGE_FILES feature test macro as well.

Returned value

If successful, lstat() returns 0.

If unsuccessful, lstat() returns -1 and sets errno to one of the following values:
Error Code
Description
EACCES
The process does not have search permission on some component of the pathname prefix.
EINVAL
buf contains a NULL.
EIO
Added for XPG4.2: An I/O error occurred while reading from the file system.
ELOOP
A loop exists in symbolic links. This error is issued if the number of symbolic links encountered during resolution of the pathname argument is greater than POSIX_SYMLOOP.
ENAMETOOLONG
pathname is longer than PATH_MAX characters or some component of pathname is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the pathname string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined through pathconf().
ENOENT
There is no file named pathname, or pathname is an empty string.
ENOTDIR
A component of the pathname prefix is not a directory.
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.
Note: Starting with z/OS V1.9, environment variable _EDC_EOVERFLOW can be used to control behavior of lstat() with respect to detecting an EOVERFLOW condition for z/OS UNIX files. By default, lstat() will not set EOVERFLOW when the file size can not be represented correctly in structure pointed to by buf. When _EDC_EOVERFLOW is set to YES, lstat() will check for an overflow condition.

Example

CELEBL12
/* CELEBL12

   This example provides status information for a file.

 */
#define _POSIX_SOURCE
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#undef _POSIX_SOURCE
#include <stdio.h>
#include <time.h>

main() {
  char fn[]="temp.file", ln[]="temp.link";
  struct stat info;
  int fd;

  if ((fd = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(fd);
    if (link(fn, ln) != 0)
      perror("link() error");
    else {
      if (lstat(ln, &info) != 0)
        perror("lstat() error");
      else {
        puts("lstat() returned:");
        printf("  inode:   %d\n",   (int) info.st_ino);
        printf(" dev id:   %d\n",   (int) info.st_dev);
        printf("   mode:   %08x\n",       info.st_mode);
        printf("  links:   %d\n",         info.st_nlink);
        printf("    uid:   %d\n",   (int) info.st_uid);
        printf("    gid:   %d\n",   (int) info.st_gid);
        printf("created:   %s",           ctime(&info.st_createtime));
      }
      unlink(ln);
    }
    unlink(fn);
  }
}
Output
lstat() returned:
  inode:   3022
 dev id:   1
   mode:   03000080
  links:   2
    uid:   25
    gid:   500
created:   Fri Jun 16 15:00:00 2006

Related information