fcntl()--Retrieve or Change Descriptor Attributes

#include <sys/types.h>
#include <fcntl.h>

int fcntl(int descriptor,
          int command,
          ...)

Threadsafe: Conditional; see Usage Notes.

The fcntl() function is used to obtain or change the attributes of a file or socket descriptor.

Parameters

descriptor

(Input) The descriptor to have its attributes retrieved or changed. The descriptor is either a file or socket descriptor.

command

(Input) The command that is to be performed on the descriptor. The following table lists the fcntl() commands that are supported.

Figure 1-1. fcntl() Commands Supported by Sockets

Command	Description
F_DUPFD	Duplicate the descriptor.
F_GETFL	Return status flags for the descriptor.
F_SETFL	Set status flags for the descriptor.
F_GETOWN	Return the process ID or process group ID that is set to receive the SIGIO (I/O is possible on a descriptor) and SIGURG (urgent condition is present) signals.
F_SETOWN	Set the process ID or process group ID that is to receive the SIGIO and SIGURG signals.
F_GETFD	Return the descriptor flags for descriptor. Descriptor flags are associated with a single descriptor and do not affect other descriptors that refer to the same file.
F_SETFD	Set the descriptor flags for descriptor. Descriptor flags are associated with a single descriptor and do not affect other descriptors that refer to the same file.

...

(Input) A variable number of optional parameters that is dependent on the command. Only some of the commands use this parameter. The following table shows what commands use the parameter and what the parameter represents.

Figure 1-2. Commands Used by the ... Parameter

Command	Argument Description
F_DUPFD	The minimum value that the duplicated descriptor can assume.
F_SETFL	Status flags that are to be set for the descriptor. The flag value is obtained by performing an OR operation on one or more of the following constants: FASYNC The SIGIO signal is sent to the process when it is possible to do I/O. O_NONBLOCK Sets nonblocking I/O and functions that would block return [EAGAIN] or [EWOULDBLOCK]. O_NDELAY This flag is defined to be equivalent to O_NONBLOCK. FNDELAY This flag is defined to be equivalent to O_NDELAY.	F_SETOWN	Process ID or process group ID that is to receive the SIGIO and SIGURG signals. A positive value specifies a process ID and a negative value specifies a process group ID.	F_SETFD	Descriptor flags to set. See for a description of valid descriptor flags.

Return Value

Possible values returned by fcntl() are:

• -1 (unsuccessful)

• n (successful), where n is one of the following depending on the value of the command parameter.

  • A descriptor if command is F_DUPFD.

  • A value other than -1 if command is F_SETFD, F_SETFL, or F_SETOWN.

  • Value of descriptor flags if command is F_GETFD.

  • Value of status flags and access modes if command is F_GETFL.

  • Process ID or process group ID if command is F_GETOWN.

Error Conditions

When fcntl() fails, errno can be set to one of the following:

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

[ERROR_INVALID_PARAMETER]

An invalid parameter was found.

A parameter passed to this function is not valid.

[EIO]

Input/output error.

A physical I/O error occurred.

A referenced object may be damaged.

[EMFILE]

Too many open files for this process.

An attempt was made to open more files than allowed by the value of OPEN_MAX. The value of OPEN_MAX can be retrieved using the sysconf() function.

The process has more than OPEN_MAX descriptors already open (see the sysconf() function).

[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 all the following conditions are true:

   • There are secondary threads active in the job.

   • The object on which this function is operating 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. In most cases, similar function can be obtained by using ioctl()

Related Information

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

• fcntl()--Perform File Control Command

• ioctl()--Change Descriptor Attributes