stat64()--Get File Information (Large File Enabled)
Syntax
#include <sys/stat.h> int stat64(const char *path, struct stat64 *buf);Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The stat64() 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, stat64() resolves the symbolic link. It also returns information about the resulting file.
stat64() is enabled for large files. It is capable of operating on files larger than 2GB minus 1 byte and returning correct sizes.
For additional information about authorities required, error conditions, and examples, see stat()--Get File Information.
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 QlgStat64()--Get File Information (large file enabled and 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 stat64 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. |
| 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. |
| off64_t | st_size | Defined as follows for each file 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.
|
| 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_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 0, a code page could not be derived. |
| unsigned long 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.
|
| unsigned int | st_ino_gen_id | The generation ID associated with the file
ID. |
| 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. |
| char | st_reserved2[5] | Reserved. |
| 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. |
| 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. |
| nlink32_t | st_nlink32 | The number of links to the file. |
| 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
the Perform File System Operation (QP0LFLOP) API.
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[22] | Reserved. |
| unsigned short | st_ccsid | The CCSID used for the data in the file or the
extended attributes of the directory. |
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
Usage Notes
- When you develop in C-based languages, the prototypes for the 64-bit APIs
are normally hidden. To use either the stat64() API or the
QlgStat64() API and the struct stat64 data type,
you must compile the source with _LARGE_FILE_API defined.
When you develop in C-based languages and this function is compiled with
_64_BIT_TIME defined, it will be mapped to stat64_time64().
This mapping will occur whether or not _LARGE_FILES is also defined. Note
that the type of the buffer parameter, struct stat *,
also will be mapped to type struct stat64_time64 *. See stat64_time64() for more information about this structure.
- All of the usage notes for stat() also apply to stat64() and to QlgStat64(). See Usage Notes in the stat() API.
API introduced: V4R4