lstat()--Get File or Link Information

 #include <sys/stat.h>

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

The lstat() function gets status information about a specified file and places it in the area of memory pointed to by buf. If the named file is a symbolic link, lstat() returns information about the symbolic link itself.

The information is returned in the stat structure, referenced by buf. For details on the stat structure, see stat()--Get File Information.

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

Parameters

path

(Input) A pointer to the null-terminated path name of the file.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

See QlgLstat()--Get File or Link Information for a description and an example of supplying the path in any CCSID.

buf

(Output) A pointer to the area to which the information should be written.

Authorities

Note: Adopted authority is not used.

Authorization Required for lstat()

Return Value

0

lstat() was successful. The information is returned in buf.

-1

lstat() was not successful. The errno global variable is set to indicate the error.

Error Conditions

If lstat() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

If interaction with a file server is required to access the object, errno could indicate one of the following errors:

Error Messages

The following messages may be sent from this function:

Usage Notes

1. This function will fail with error code [ENOTSAFE] when both of the following conditions occur:
   
   
   • Where multiple threads exist in the job.
     
   • The object this function is operating on resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     
     
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400
   
   
2. QOPT File System Differences
   

   The value for st_atime will always be zero. The value for st_ctime will always be the creation date and time of the file or directory.

   If the object exists on a volume formatted in Universal Disk Format (UDF), the authorization that is checked for the object and each directory in the path name follows the rules described in Authorization Required for lstat(). If the object exists on a volume formatted in some other media format, no authorization checks are made on the object or each directory in the path name. The volume authorization list is checked for *USE authority regardless of the volume media format.

   The user, group, and other mode bits are always on for an object tha exists on a volume not formatted in Universal Disk format (UDF).

   lstat() on /QOPT will always return 2,147,483,647 for size fields.

   lstat() on optical volumes will return the volume capacity or 2,147,483,647, whichever is smaller.

   The file access time is not changed.

   
   
3. Network File System Differences

   Local access to remote files through the Network File System may produce unexpected results due to conditions at the server. Once a file is open, subsequent requests to perform operations on the file can fail because file attributes are checked at the server on each request. If permissions on the file are made more restrictive at the server or the file is unlinked or made unavailable by the server for another client, your operation on an open file descriptor will fail when the local Network File System receives these updates. The local Network File System also impacts operations that retrieve file attributes. Recent changes at the server may not be available at your client yet, and old values may be returned from operations. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.)

   
   
4. QFileSvr.400 File System Differences

   The value of st_vfs will always be 0 for remote objects accessed via QFileSvr.400.

   The st_uid and st_gid fields that are returned for the object represent uids and gids on the remote system. These uids and gids may not exist on the local system or, if they do exist, may not represent the expected users or groups.

5. This function will fail with the [EOVERFLOW] error if the file size in bytes cannot be represented correctly in the structure pointed to by buf (the file is larger than 2GB minus 1 byte).
   
   
6. When you develop in C-based languages and this function is compiled with _LARGE_FILES defined, it will be mapped to lstat64(). Note that the type of the buf parameter, struct stat, also will be mapped to type struct stat64.

Related Information

• The <sys/stat.h> file (see Header Files for UNIX^®-Type Functions)
• The <sys/types.h> file (see Header Files for UNIX-Type Functions)
• chmod()--Change File Authorizations
• chown()--Change Owner and Group of File
• creat()--Create or Rewrite File
• dup()--Duplicate Open File Descriptor
• fclear()--Write (Binary Zeros) to Descriptor
• fclear64()--Write (Binary Zeros) to Descriptor (Large File Enabled)
• fcntl()--Perform File Control Command
• fstat()--Get File Information by Descriptor
• link()--Create Link to File
• mkdir()--Make Directory
• open()--Open File
• QlgLstat()--Get File or Link Information
• read()--Read from Descriptor
• readlink()--Read Value of Symbolic Link
• stat()--Get File Information
• symlink()--Make Symbolic Link
• unlink()--Remove Link to File
• utime()--Set File Access and Modification Times
• write()--Write to Descriptor

Example

The following example provides status information for a file.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <sys/types.h>
#include <sys/stat.h>
#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <time.h>
#include <stdio.h>

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

  if ((file_descriptor = creat(fn, S_IWUSR)) < 0)
    perror("creat() error");
  else {
    close(file_descriptor);
    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);
      }
      unlink(ln);
    }
    unlink(fn);
  }
}

Output:

lstat() returned:
  inode:   3022
 dev id:   1
   mode:   00008080
  links:   2
    uid:   137
    gid:   500

[ Back to top | UNIX-Type APIs | APIs by category ]