gtpc2m4oC/C++ Language Support User's Guide

lstat-Get Status of a File or Symbolic Link

This function gets status information about a specified file.

Format

#include <sys/stat.h>
int lstat(const char *pathname, struct stat *buf);

pathname
The path name of the file or symbolic link.

buf
The address of the struct stat object where information is to be stored.

After the lstat function gets status information about a specified file, the function places this information in the area of storage 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 pathname.

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

See Table 15 for more information about the stat structure, which is defined in the sys/stat.h header file.

TPF deviation from POSIX

The TPF system does not support the atime (access time) or ctime (change time) time stamp.

You can examine properties of a mode_t value from the st_mode field by using a collection of macros defined in the modes.h header file. If mode is a mode_t value from the stat structure:

S_ISBLK(mode)
Is nonzero for block special files.
TPF deviation from POSIX

The TPF system does not support block special files; this macro is included for compatibility only.

S_ISCHR(mode)
Is nonzero for character special files.

S_ISDIR(mode)
Is nonzero for directories.

S_ISFIFO(mode)
Is nonzero for pipes and first-in-first-out (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.
TPF deviation from POSIX

TPF sockets are non-standard, and are not associated with links or standard file descriptors; therefore, it is not possible to get status for a TPF socket. This macro is included for compatability only.

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

Normal Return

If successful, the lstat function returns a value of 0.

Error Return

If unsuccessful, the lstat function returns a value of -1 and sets errno to one of the following:

EACCES
The process does not have search permission on some component of the pathname prefix.

EINVAL
buf contains a null pointer.

ELOOP
A loop exists in symbolic links. This error is issued if the number of symbolic links found while resolving the pathname argument is greater than the POSIX_SYMLOOP.

ENAMETOOLONG
pathname is longer than PATH_MAX characters or some component of pathname is longer than NAME_MAX characters. For symbolic links, the length of the path name string substituted for a symbolic link exceeds PATH_MAX.

ENOENT
There is no file named pathname, or pathname is an empty string.

ENOTDIR
A component of the pathname prefix is not a directory.

Programming Considerations

None.

Examples

The following example provides status information for a file.

#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#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("   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);
      }
      unlink(ln);
    }
    unlink(fn);
  }
}

Output

lstat() returned:
  inode:   3022
   mode:   03000080
  links:   2
    uid:   255
    gid:   256

Related Information

See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.