The fcntl callable service performs general control functions for open files: it retrieves or sets file descriptor flags, file status flags, locking information, and file tags. It also controls the automatic conversion of text data within files.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1FCT): | 31-bit |
AMODE (BPX4FCT): | 64-bit |
ASC mode: | Primary address space control (ASC) mode |
Interrupt status: | Enabled for interrupts |
Locks: | Unlocked |
Control parameters: | All parameters must be addressable by the caller and in the primary address space. |
|
AMODE 64 callers use BPX4FCT with the same parameters. However, for AMODE 64 callers, the Argument parameter may be either a 64-bit pointer or a 4-byte value, depending upon the Action parameter.
The name of a fullword that contains the file descriptor for the file. This parameter must specify an opened file descriptor, except when the Action parameter is F_CLOSFD, in which case this file descriptor is not expected to be in use.
The name of a fullword that contains an integer value, mapped in the BPXYFCTL macro, that indicates the action to be performed. For a list of actions, see BPXYFCTL — Command values and flags for fcntl.
For AMODE 64 callers using F_SETLK, F_GETLK, F_SETLKW, F_SETTAG, or F_CONTROL_CVT, the Argument is a 64-bit pointer. For AMODE 31 callers using F_SETLK, F_GETLK, F_SETLKW, F_SETTAG, or F_CONTROL_CVT, the argument is a 31-bit pointer.
When Action is F_DUPFD, fcntl returns the lowest file descriptor equal to or greater than File_descriptor_2 that is not already associated with an open file. File_descriptor is duplicated.
When Action is F_DUPFD2, the file descriptor that is returned is equal to File_descriptor_2. File_descriptor_2 is closed if it is already in use. F_CLOEXEC is cleared.
File_descriptor is duplicated. If File_descriptor is equal to File_descriptor_2, the F_DUPFD2 action returns File_descriptor_2 without closing it. F_CLOEXEC is not cleared.
When Action is F_CLOSFD, File_descriptor_2 specifies the upper limit for the range of file descriptors to be closed, and File_descriptor specifies the lower limit. If a -1 is specified for File_descriptor_2, all file descriptors greater than or equal to the lower limit are closed.
To get File_descriptor_flags, specify action F_GETFD. If the action is successful, Return_value maps to the bit settings of File_descriptor_flags
File descriptor flags are mapped by the BPXYFCTL macro; see BPXYFCTL — Command values and flags for fcntl.
To get File_status_flags, specify action F_GETFL. If the action is successful, Return_value maps to the bit settings of File_status_flags
Similarly, to set File_status_flags, specify action F_SETFL and use the mapping to set or reset File_status_flags to the desired value. Only the O_ASYNCSIG, O_APPEND, O_NONBLOCK, and O_SYNC flags are set when Action is F_SETFL; any other flags specified are ignored.
File status flags are used to set some of the open flags that are mapped by the BPXYOPNF macro. For the mapping of the file status flags, see BPXYOPNF — Map flag values for open.
Two masks are available for use with the return value from an F_GETFL request. You can use the O_ACCMODE mask to extract the file access mode flags from the return value, or you can use the O_GETFL mask to extract both the file access mode and the file status flags.
Word | Description |
---|---|
0 | l_type: Bytes 0–1 specify the type of lock that is being set, cleared, or queried. For more information, see "File Locking" in the usage notes. |
0 | l_whence: Bytes 2–3 specify how the lock offset is to be determined. For more information, see "File Locking" in the usage notes. |
1–2 | l_start specifies the starting byte offset of the lock that is to be set, cleared, or queried. This is a doubleword value. |
3–4 | l_len specifies the length of the byte range that is to be set, cleared, or queried. This is a doubleword value. |
5 | l_pid: On return from a F_GETLK request, this field contains the process ID of the process that is holding the blocking lock, if one was found. |
Every socket has an associated process group number, which is initialized to zero. You set it by calling the fcntl service and specifying the F_SETOWN action. This value can also be set using the w_ioctl callable service. The Argument value for the F_SETOWN can be a positive integer, specifying a process ID, or a negative integer (other than -1), specifying a process group ID. The F_GETOWN command returns in the return value field either the process ID or the process group ID that is associated with the socket. The difference between specifying a process ID and specifying a process group ID is that in the first case only a single process receives the signal, while in the second case all processes in the process group receive the signal. The F_SETOWN and F_GETOWN actions are only available for AF_INET stream sockets.
When Action is F_SETTAG, the fcntl service sets the file tag attributes for the file. The file must be a regular, FIFO, or character special file and must be opened in write mode. The file must be empty. If the file is not empty and the DeferTag bit is set, no error is returned and no processing occurs, assuming that the command would otherwise have worked. This allows the caller to issue F_SETTAG without checking the file size, but not incur an error. If you use F_SETTAG to set a tag that is already tagged and opened, O_TRUNC is ignored.
When the DeferTag bit is off, the file tag is set immediately. When the DeferTag bit is on, the setting of the file tag is deferred until the first write by a call to BPX1WRT (BPX4WRT). The file tag is lost if no write ever occurs and the file is closed. If the write fails, file tagging might or might not have occurred. When the file is a FIFO or pipe, the file tag is deferred until the first read (BPX1RED/BPX4RED) or first write (BPX1WRT/BPX4WRT), whichever comes first. This is because a read can precede a write when blocking is enabled, even for an empty file.
If the file is /dev/null, /dev/random, /dev/urandom, or /dev/zero, the file tag is not hardened to disk.
Recommendation: Using F_SETTAG multiple times with deferred tagging before the first write to the file is not recommended. Be aware that there are C-RTL environment options that may cause F_SETTAG with deferred tagging (such as FILETAG(,AUTOTAG)).
When Action is F_CONTROL_CVT, the fcntl service controls how conversion occurs when the opened file is being read from (via BPX1RED or BPX4RED) or written to (via BPX1WRT or BPX4WRT). The file must be a regular, FIFO, or character special file.
A hex value of 0 for the file CCSID indicates that the current setting is not to be changed. The values do not affect the stored file tag or program CCSID; they only change the values that are being used to control conversion on this data stream.
Setting or referencing ThliCcsid is still valid, but no longer recommended.
Action | Argument | Return_value |
---|---|---|
F_CLOSFD | File_descriptor_2 | 0 |
F_CONTROL_CVT | F_CVT | 0 |
F_DUPFD | File_descriptor_2 | File_descriptor |
F_DUPFD2 | File_descriptor_2 | File_descriptor |
F_GETFD | 0 | File_descriptor_flags |
F_GETFL | 0 | File_status_flags |
F_GETLK | Lock_information | Lock_information |
F_GETOWN | 0 | Pid |
F_SETFD | File_descriptor_flags | 0 |
F_SETFL | File_status_flags | 0 |
F_SETLK | Lock_information | 0 |
F_SETLKW | Lock_information | 0 |
F_SETOWN | Pid | 0 |
F_SETTAG | File_Tag | 0 |
Return_code | Explanation |
---|---|
EAGAIN | The calling process asked to set a lock, but the lock conflicts with a lock on an overlapping part of the file that is already set by another process. |
EBADF | The request was not accepted, for one of these reasons:
The following reason code can accompany the return code: JRFdTooBig. |
EDEADLK | The action requested was F_SETLKW; the potential for deadlock was detected. |
EINTR | While processing a F_SETLKW request, fcntl was interrupted by a signal. |
EINVAL | The request was not accepted, for one of these reasons:
The following reason codes can accompany the return code: JRFdTooBig, JRFd2TooSmall, JrBrlmBadFileType, JrBrlmBadL_Type, JrBrlmInvalidRange, JrBrlmBadL_Whence, JrNotsupportedForFileType, JrBadInputBufAddr, JrFileNotEmpty, JrWFildeRdOnly, JrInvalidFileTag, JrInvalidCcsid, JrBadOptCode. |
EMFILE | The action requested was F_DUPFD. The process has already reached its maximum number of file descriptors, or there is no file descriptor available greater than File_descriptor_2. |
ENOTSOCK | Socket_descriptor does not refer to a valid socket descriptor. The following reason code can accompany the return code: JRMustBeSocket. |
EPERM | The action requested was F_CLOSFD, and at least one of the file descriptors in the specified range remains open. For a description of the file descriptors that cannot be closed with F_CLOSFD, see the Usage notes. |
The name of a fullword in which the fcntl service stores the reason code. The fcntl service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.
If there are no locks that would prevent the proposed lock operation from completing successfully, the returned structure is modified to have an l_type of F_UNLCK, but otherwise remains unchanged.
There are no restrictions on the use of the fcntl service.
For an example that uses this callable service, see BPX1FCT (fcntl) example.