fstat()--Retrieve Status Information about a Descriptor

#include <sys/stat.h>

int fstat(int descriptor,
          struct stat *buffer)

Threadsafe: Conditional; see Usage Notes.

The fstat() function is used to retrieve information about a file or socket.

Parameters

descriptor

(Input) The descriptor for which information is to be retrieved. The descriptor is either a file or socket descriptor.

buffer

(I/O) A pointer to a buffer of type struct stat in which the information is returned. The structure pointed to by the buffer parameter is defined in <sys/stat.h>.

      struct stat {
        mode_t         st_mode;
        ino_t          st_ino;
        nlink_t        st_nlink;
        uid_t          st_uid;
        gid_t          st_gid;
        off_t          st_size;
        time_t         st_atime;
        time_t         st_mtime;
        time_t         st_ctime;
        dev_t          st_dev;
        size_t         st_blksize;
        long           st_blocks;
        qp0l_objtype_t st_objtype;
      };

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

fstat() returns an integer. Possible values are:

• -1 (unsuccessful)

• 0 (successful)

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.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

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]

Operation would have caused the process to be suspended.

[EBADFUNC]

Function parameter in the signal function is not set.

A given file descriptor or directory pointer is not valid for this operation. The specified descriptor is incorrect, or does not refer to an open file.

[EBADFID]

A file ID could not be assigned when linking an object to a directory.

The file ID table is missing or damaged.

To recover from this error, run the Reclaim Storage (RCLSTG) command as soon as possible.

[EBUSY]

Resource busy.

An attempt was made to use a system resource that is not available at this time.

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid. [EFAULT] is returned if this function is passed a pointer parameter that is not valid.

[ERROR_INVALID_PARAMETER]

An invalid parameter was found.

A parameter passed to this function is not valid.

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]

Input/output error.

A physical I/O error occurred.

A referenced object may be damaged.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOSYSRSC]

System resources not available to complete request.

[EPERM]

Operation not permitted.

You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

[ESTALE]

File or object handle rejected by server.

If you are accessing a remote file through the Network File System, the file may have been deleted at the server.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Error Messages

CPE3418 E

Possible APAR condition or hardware failure.

CPF3CF2 E

Error(s) occurred during running of &1 API.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

CPFA081 E

Unable to set return value or error code.

CPFA0D4 E

File system error occurred.

Usage Notes

1. This function will fail with error code [ENOTSAFE] when both of the following conditions occur:

   • There are secondary threads active 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

     • QOPT

     • QLANSrv

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

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

   For connection-oriented sockets with an address family of AF_NS, the value returned for st_blksize is set to the MTU size that is in effect once the connection is established.

   Note: IBM reserves the right to change the calculation of the optimal send size.

Related Information

• The <sys/types.h>file (see Header Files for UNIX-Type Functions)

• The <sys/stat.h>file

• fcntl()--Perform File Control Command

• fcntl()--Retrieve or Change Descriptor Attributes

• fstat()--Get File Information by Descriptor

• lstat()--Get File or Link Information

• open()--Open File

• socket()--Create Socket

• stat()--Get File Information