gtpc2m70C/C++ Language Support User's Guide

stat-Get File Information

This function gets file information.

Format

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

pathname
A pointer to the path name of the file or directory.

info
A pointer to the struct stat object in which file status information will be returned.

This function gets status information about a specified file and places it in the area of storage pointed to by the info argument. The process does not need permissions on the file itself, but must have search permission on all directory components of pathname. If the named file is a symbolic link, the stat function resolves the symbolic link. It also returns information about the resulting file.

The information is returned as shown in the following stat structure table as defined in the sys/stat.h header file.

Table 15. Elements of the stat Structure

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. In the TPF file system, this is the subsystem ID.
nlink_t st_nlink The number of links to the file.
uid_t st_uid The numeric user ID of the file owner.
gid_t st_gid The numeric group ID of the file group.
off_t st_size For regular files, this field contains the file size in bytes. For other kinds of files where the file size cannot be determined, the value of this field is set to -1. For directories, this field contains the number of entries in the directory.
time_t st_atime The TPF system does not update st_atime. It contains (time_t) - 1 unless the file's access time stamp has been updated by the utime function.
time_t st_ctime The TPF system does not update st_ctime. It always contains the value (time_t) - 1.
time_t st_mtime The most recent time the contents of the file were changed given in terms of seconds that have elapsed since epoch.
TPF deviation from POSIX

The TPF system updates the mtime time stamp only when a file that was previously opened for write access, or for read and write access, is closed.

st_blksize The preferred block size. In the TPF file system, this field is always set to 1. This does not imply anything about the underlying structure of the TPF file system. This field is provided for Berkeley Software Distribution (BSD) compatibility only.
st_blocks The number of blocks used by the file. In the TPF file system, this value is equal to the size of the file. This field is provided for BSD compatibility only.
st_atimespec The time the file was last accessed, expressed as a struct timespec (seconds since epoch plus nanoseconds). The value of the st_atimespec field has the same restrictions as the st_atime field. This field is provided for BSD compatability only.
st_ctimespec The time the file status last changed, expressed as struct timespec (seconds since epoch plus nanoseconds). The value of the st_ctimespec field has the same restrictions as the st_ctime field. This field is provided for BSD compatibility only.
st_mtimespec The time the file data last changed, expressed as struct timespec (seconds since epoch plus nanoseconds). The value of the st_mtimespec field has the same restrictions as the st_mtime field. This field is provided for BSD compatability only.
TPF deviation from POSIX

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

Values for time_t are given in terms of seconds since epoch.

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

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.

If the stat function successfully determines this information, it stores the information in the area indicated by the info argument.

Normal Return

If successful, the stat function returns a value of zero.

Error Return

If unsuccessful, the stat 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
info is a null pointer.

ELOOP
This error is issued if the number of symbolic links found while resolving 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. 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 gets status information about a file.

#include <sys/types.h>
#include <sys/stat.h>
#include <stdio.h>
#include <time.h>
 
main() {
  struct stat info;
 
  if (stat("/", &info) != 0)
    perror("stat() error");
  else {
    puts("stat() returned the following information about root f/s:");
    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);
    printf("modified:   %s",           ctime(&info.st_mtime));
  }
}

Output

stat() returned the following information about root f/s:
   inode:   0
    mode:   010001ed
   links:   0
     uid:   0
     gid:   1
modified:   Fri Jan 16 10:07:55 1998

Related Information

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