Standards / Extensions | C or C++ | Dependencies |
---|---|---|
z/OS® UNIX |
both |
#define _POSIX1_SOURCE 2
#include <sys/stat.h>
int lstat(const char *__restrict__ pathname, struct stat *__restrict__ buf);
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 information is returned in the following stat structure, defined in the sys/stat.h header file.
Structure | Description |
---|---|
mode_t st_mode | A bit string indicating the permissions and privileges of the file. 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 | The serial number of the file. |
dev_t st_dev | The numeric ID of the device containing the file. |
nlink_t st_nlink | The number of links to the file. |
uid_t st_uid | The numeric user ID of the file's owner. |
gid_t st_gid | The numeric group ID of the file's group. |
off_t st_size | For regular files, the file's size in bytes. For symbolic links, the length of the pathname contained therein not counting the trailing NULL. For other kinds of files, the value of this field is unspecified. |
time_t st_atime | The most recent time the file was accessed. |
time_t st_ctime | The most recent time the status of the file was changed. |
time_t st_mtime | The most recent time the contents of the file were changed. |
Values for time_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.
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: Large z/OS UNIX files are supported automatically 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 this function 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.
If successful, lstat() returns 0.
⁄* 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);
}
}
lstat() returned:
inode: 3022
dev id: 1
mode: 03000080
links: 2
uid: 25
gid: 500
created: Fri Jun 16 15:00:00 2001