stat()--Get File Information

 #include <sys/stat.h>

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

The stat() function gets status information about a specified file and places it in the area of memory pointed to by the buf argument.

If the named file is a symbolic link, stat() resolves the symbolic link. It also returns information about the resulting file.

Parameters

path

(Input) A pointer to the null-terminated path name of the file from which information is required.

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 QlgStat()--Get File Information (using NLS-enabled path name) 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.

The information is returned in the following stat structure, as defined in the <sys/stat.h> header file:

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 File Authorizations.
ino_t	st_ino	The file ID for the object. This number uniquely identifies the object within a file system. When st_ino and st_dev are used together, they uniquely identify the object on the system.
nlink_t	st_nlink	The number of links to the file. This field will be 65,535 if the value could not fit in the specified nlink_t field. The complete value will be in the st_nlink32 field.
unsigned short	st_reserved2	Reserved.
uid_t	st_uid	The numeric user ID (uid) of the owner of the file.
gid_t	st_gid	The numeric group ID (gid) for the file.
off_t	st_size	Defined as follows for each file type: Regular File The number of data bytes in the file. Directory The number of bytes allocated to the directory. Symbolic Link The number of bytes in the path name stored in the symbolic link. Local Socket Always zero. Operating System Native Object This value is dependent on the object type.
time_t	st_atime	The most recent time the file was accessed.
time_t	st_mtime	The most recent time the contents of the file were changed.
time_t	st_ctime	The most recent time the status of the file was changed.
dev_t	st_dev	The file system ID to which the object belongs. This number uniquely identifies the file system to which the object belongs. When st_ino and st_dev are used together, they uniquely identify the object on the system. This field will be 4,294,967,295 if the value could not fit in the specified dev_t field. The complete value will be in the st_dev64 field.
size_t	st_blksize	The block size of the file in bytes. This number is the number of bytes in a block of disk unit storage.
unsigned long	st_allocsize	The number of bytes allocated to the file. The allocated size varies by object type and file system. For example, the allocated size includes the object data size as shown in st_size as well as any logically sized extents to accomodate anticipated future requirements for the object data. It may or may not include additional bytes for attribute information.
qp0l_objtype_t	st_objtype	The object type; for example, *STMF or *DIR. Refer to CL Programming topic for a list of the object types.
unsigned short	st_codepage	The code page derived from the CCSID used for the data in the file or the extended attributes of the directory. If the returned value of this field is zero (0), there is more than one code page associated with the st_ccsid. If the st_ccsid is not a supported CCSID, the st_codepage is set equal to the st_ccsid.
unsigned short	st_ccsid	The CCSID used for the data in the file or the extended attributes of the directory.
dev_t	st_rdev	The device ID of the object if the object is a character special file or block special file. This number uniquely identifies the file device. This field will be 4,294,967,295 if the value could not fit in the specified dev_t field. The complete value will be in the st_rdev64 field.
nlink32_t	st_nlink32	The number of links to the file.
dev64_t	st_rdev64	The device ID of the object in 64 bit format. See st_rdev for more information.
dev64_t	st_dev64	The file system ID to which the object belongs in 64 bit format. See st_dev for more information.
unsigned int	st_vfs	The unique mount ID of the file system on which the object is located. Information about each mounted file system can be obtained by using the QP0L_RETRIEVE_MOUNTED_FILE_SYSTEMS option of QP0LFLOP()--Perform file system operation. Unlike st_dev and st_dev64, st_vfs identifies a particular instance of a file system. For any single file system, st_dev and st_dev64 will remain the same across multiple mounts. In contrast, st_vfs is incremented whenever a file system is mounted and is different for each mount of a file system. Therefore, the value of st_vfs may change due to any system processing which unmounts and mounts file systems, such as IPL and Reclaim Storage (RCLSTG).
char	st_reserved1[32]	Reserved.
unsigned int	st_ino_gen_id	The generation ID associated with the file ID.

Values of time_t are given in terms of seconds since a fixed point in time called the Epoch.

You can examine properties of a mode_t value from the st_mode field using a collection of macros defined in the <sys/stat.h> header file. If mode is a mode_t value, 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_ISFIFO(mode)

Is nonzero for pipes and FIFO special files

S_ISREG(mode)

Is nonzero for regular files

S_ISLNK(mode)

Is nonzero for symbolic links

S_ISSOCK(mode)

Is nonzero for local sockets

S_ISNATIVE(mode)

Is nonzero for operating system native objects

Authorities

Note: Adopted authority is not used.

Return Value

0

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

-1

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

Error Conditions

If stat() 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. "Root" (/), QOpenSys, and User-Defined File System Differences

   The st_allocsize value can be influenced by the setting of the disk storage option attribute. See Qp0lSetAttr()--Set Attributes for more information.

3. QSYS.LIB and Independent ASP QSYS.LIB File System Differences

   The stat() function could return zero for the st_atime value (in the stat structure) under some conditions.

4. QDLS File System Differences

   If the date corresponding to the st_atime, st_mtime, or st_ctime value precedes 1970, stat() returns zero for that value. Also, if the specified path is /QDLS, stat() returns zero for all three values st_atime, st_mtime, and st_ctime.

5. 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.

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

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

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

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

   The file access time is not changed.

6. 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.)

7. QNetWare File System Differences

   The QNetWare file system does not fully support mode bits. See NetWare on iSeries for more information.

8. QFileSvr.400 File System Differences

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

9. 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).
   
   
10. When you develop in C-based languages and this function is compiled with _LARGE_FILES defined, it will be mapped to stat64(). 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
• lstat()--Get File or Link Information
• mkdir()--Make Directory
• open()--Open File
• QlgStat()--Get File Information (using NLS-enabled path name)
• QP0LFLOP()--Perform file system operation
• read()--Read from Descriptor
• readlink()--Read Value of Symbolic Link
• stat64()--Get File Information (Large File Enabled)
• symlink()--Make Symbolic Link
• unlink()--Remove Link to File
• utime()--Set File Access and Modification Times
• write()--Write to Descriptor

Example

See Code disclaimer information for information pertaining to code 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(" 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);
  }
}

Output: note that the following information will vary from system to system.

stat() returned the following information about root f/s:
  inode:   0
 dev id:   1
   mode:   010001ed
  links:   3
    uid:   137
    gid:   500