fstat()--Get File Information by Descriptor
Syntax
#include <sys/stat.h> int fstat(int descriptor, struct stat *buffer)
Service Program Name: QP0LLIB1
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The fstat() function gets status information about the object specified by the open descriptor descriptor and stores the information in the area of memory indicated by the buffer argument. The status information is returned in a stat structure, as defined in the <sys/stat.h> header file.
Parameters
- descriptor
- (Input) The descriptor for which information is to be retrieved.
- buffer
- (Output) A pointer to a buffer of type struct stat in
which the information is returned. The structure pointed to by the
buffer parameter is described in stat()-- Get File
Information.
The st_mode, st_dev, and st_blksize fields are the only fields set for socket descriptors. The st_mode field is set to a value that indicates the descriptor is a socket descriptor, the st_dev field is set to -1, and the st_blksize field is set to an optimal value determined by the system.
Authorities
No authorization is required.
Return Value
0 | fstat() was successful. The information is returned in buffer. |
-1 | fstat() was not successful. The errno global variable is set to indicate the error. |
Error Conditions
If fstat() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.
Error condition | Additional information |
---|---|
[EACCES] |
If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems. |
[EAGAIN] | |
[EBADF] | |
[EBADFID] | |
[EBADFUNC] |
A given descriptor or directory pointer is not valid for this operation. The specified descriptor is incorrect, or does not refer to an open object. |
[EBUSY] | |
[EDAMAGE] | |
[EFAULT] | |
[EINVAL] |
This error code may be returned when the underlying object represented by the descriptor is unable to fill the stat structure (for example, if the function was issued against a socket descriptor that had its connection reset). |
[EIO] | |
[ENOBUFS] | |
[ENOSYSRSC] | |
[ENOTAVAIL] | |
[ENOTSAFE] | |
[EOVERFLOW] |
The specified file exists and its size is too large to be represented in the structure pointed to by buffer (the file is larger than 2GB minus 1 byte). |
[EPERM] | |
[ESTALE] |
If you are accessing a remote file through the Network File System, the file may have been deleted at the server. |
[EUNATCH] | |
[EUNKNOWN] |
If interaction with a file server is required to access the object, errno could also indicate one of the following errors:
Error condition | Additional information |
---|---|
[EADDRNOTAVAIL] | |
[ECONNABORTED] | |
[ECONNREFUSED] | |
[ECONNRESET] | |
[EHOSTDOWN] | |
[EHOSTUNREACH] | |
[ENETDOWN] | |
[ENETRESET] | |
[ENETUNREACH] | |
[ETIMEDOUT] |
Error Messages
The following messages may be sent from this function:
Message ID | Error Message Text |
---|---|
CPFA0D4 E | File system error occurred. Error number &1. |
CPFA081 E | Unable to set return value or error code. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPE3418 E | Possible APAR condition or hardware failure. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- 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
- Where multiple threads exist in the job.
- Sockets-Specific Notes
- The field st_mode can be inspected using the S_ISSOCK macro
(defined in <sys/stat.h>) to determine if the descriptor
is pointing to a socket descriptor.
- For socket descriptors, use the send buffer size (this is the value
returned for st_blksize) for the length parameter on your input and
output functions. This can improve performance.
Note: IBM reserves the right to change the calculation of the optimal send size.
- The field st_mode can be inspected using the S_ISSOCK macro
(defined in <sys/stat.h>) to determine if the descriptor
is pointing to a socket descriptor.
- 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).
fstat() on /QOPT will always return 2,147,483,647 for size fields.
fstat() on optical volumes will return the volume capacity or 2,147,483,647, whichever is smaller.
The file access time is not changed.
- 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 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.)
- 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.
- This function will fail with the [EOVERFLOW] error if the specified file
exists and its size is too large to be represented in the structure pointed to
by buffer (the file is larger than 2GB minus 1 byte).
- When you develop in C-based languages and this function is compiled with
_LARGE_FILES defined, it will be mapped to fstat64(). Note
that the type of the buffer parameter, struct stat *,
also will be mapped to type struct stat64 *. See stat64() for more information about this structure.
-
When you develop in C-based languages and this function is compiled with
_64_BIT_TIME defined, it will be mapped to fstat64_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.
- If a descriptor for a pipe or socket is passed to this function, the value of st_vfs will be 0. Therefore, information about these objects' corresponding file system cannot be obtained using the QP0L_RETRIEVE_MOUNTED_FILE_SYSTEMS option of the Perform File System Operation (QP0LFLOP) API.
Related Information
- The <sys/types.h> file (see Header Files for UNIX®-Type Functions)
- The <sys/stat.h> file (see Header Files for UNIX-Type Functions)
- fcntl()--Perform File Control Command
- fstat64()--Get File Information by Descriptor (Large File Enabled)
- lstat()--Get File or Link Information
- open()--Open File
- socket()--Create Socket
- stat()--Get File Information
- stat64()--Get File Information (Large File Enabled)
- QP0LFLOP--Perform File System Operation
Example
The following example gets status information.
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 <fcntl.h> #include <stdio.h> #include <time.h> main() { char fn[]="temp.file"; struct stat info; int file_descriptor; if ((file_descriptor = creat(fn, S_IWUSR)) < 0) perror("creat() error"); else { if (fstat(file_descriptor, &info) != 0) perror("fstat() error"); else { puts("fstat() 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); } close(file_descriptor); unlink(fn); } }
Output: Note that the output may vary from system to system.
fstat() returned: inode: 3057 dev id: 1 mode: 03000080 links: 1 uid: 137 gid: 500
API introduced: V3R1