Function
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.
Requirements
| 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. |
Format
|
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.
Parameters
- File_descriptor
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
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.
- Action
- Supplied parameter
- Type:
- Structure
- Length:
- Fullword
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.
- Argument
- Parameter supplied and returned
- Type:
- Structure
- Length:
- Fullword (doubleword)
The name of a fullword (doubleword) that contains an argument, or zero. The type of argument depends upon the action requested:- Action
- Argument
- F_CLOSFD
- File_descriptor_2
- F_CONTROL_CVT
- fcntl convert (F_CVT) structure
- F_DUPFD
- File_descriptor_2
- F_DUPFD2
- File_descriptor_2
- F_GETFD
- 0
- F_GETFL
- 0
- F_GETLK
- Lock_information
- F_GETOWN
- 0
- F_SETFD
- File_descriptor_flags
- F_SETFL
- File_status_flags
- F_SETLK
- Lock_information
- F_SETLKW
- Lock_information
- F_SETOWN
- Pid
- F_SETTAG
- File_Tag
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.
- Argument Options
- The options you can use as an argument follow:
- File_descriptor_2
- The name of a fullword that contains a file descriptor.
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.
- File_descriptor_flags
- The name of a fullword that contains the file descriptor flags
that are to be set or retrieved for File_descriptor.
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
Similarly, to set File_descriptor_flags, specify action F_SETFD and use the mapping to set or reset File_descriptor_flags to the desired value.Note: After the FCTLCLOFORK flag has been set on, it cannot be set off again.File descriptor flags are mapped by the BPXYFCTL macro; see BPXYFCTL — Command values and flags for fcntl.
- File_status_flags
- The name of a fullword that contains the file status flags to
be set or retrieved for File_descriptor.
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.
- Lock_information
- The name of a fullword (doubleword) that contains a pointer
to a structure that contains information about a file segment for
which locks are to be set, cleared, or queried.The Lock_information is mapped by the BPXYBRLK macro as follows:For more information, see "File Locking" in the usage notes.
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. - Pid
- The name of a fullword that contains either the process ID or
the process group ID that is to receive the SIGIO or SIGURG signals
for the socket that is associated with File_descriptor.
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.
- File_Tag
- The name of a fullword (doubleword) that contains a pointer to
a file tag. The file tag is mapped in BPXYSTAT (BPXYSTAT — Map the response structure for stat).
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)).
- fcntl convert structure
- The name of a two-word structure that describes how conversion
is to occur for this file. The two-word structure is mapped in BPXYFCTL
(BPXYFCTL — Command values and flags for fcntl; see F_CVT). The first word is one
of four possible subcommands, followed by a 2-byte program CCSID and
a 2-byte file CCSID.
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.
The subcommands are:- Subcommand
- Description
- SetCvtAll
- Behaves the same as SetCvtOn, except automatic conversion is set
to ALL, which enables UNICODE conversion. ThliCcsid is not used. SetCvtAll
is ignored if I/O for the file has already started. A thread can set
different program CCSIDs for each open file. However, an I/O error
will result if any two threads have different program CCSIDs for the
same open file that is shared by those two threads.
- SetCvtOff
- Turns off any conversion that may be in effect. The CCSID values are ignored. If automatic conversion is set to ALL and I/O has already started for the file, this command is ignored.
- SetCvtOn
- Turns automatic conversion on for the stream and, optionally,
sets the program CCSID or file CCSID, or both. A hex value of 0 for
program-ccsid indicates using the current program CCSID at the time
of each read or write. The current program CCSID is initially 1047,
but can be reset directly by the program, or indirectly by setting
the appropriate runtime option or environment variable.
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.
- SetAutoCvtAll
- If conversion is enabled for the environment (by BPXPRMxx parmlib statement AUTOCVT setting of ALL or with the appropriate environment variable), this subcommand behaves identically to SetCvtAll. Otherwise, it has no effect.
- SetAutoCvtOn
- If conversion is enabled for the environment (by AUTOCVT in BPXPRMxx
or with the appropriate environment variable), this subcommand behaves
identically to SetCvtOn. Otherwise, it has no effect.
- QueryCvt
- Returns information about whether conversion is in
effect, and the program and file CCSIDs that are being used. On input,
the subcommand is QueryCvt. On output, the subcommand is reset to
SetCvtOn, SetCvtAll, or SetCvtOff, indicating that conversion is ON
or ALL or OFF, respectively. The current CCSIDs are returned in their
respective positions in the F_CVT structure.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the fcntl service returns 0 or greater, if the request is successful; or -1, if it is not successful. The following table lists the possible values of Return_value for each action specified: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
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the fcntl service stores the return code. The fcntl service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The fcntl service can return one of the following values in the Return_code parameter: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 File_descriptor parameter does not specify a valid, open file descriptor.
- The request was to set a read lock, but the file is open for writing only.
- The request was to set a write lock, but the file is open for reading only.
- File_descriptor was opened with an opendir request. Many of the other requests are rejected for an opendir filedes.
- If the action requested was F_DUPFD2, this error indicates that File_descriptor_2 was negative, or was equal to or greater than the highest file descriptor value allowed for the process. The MAXFILEPROC parmlib option is used to specify the largest file descriptor value for the system.
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: - If the action requested was F_DUPFD, File_descriptor_2 was negative, or it was equal to or greater than the highest file descriptor value that is allowed for the process. The MAXFILEPROC parmlib option is used to specify the largest file descriptor value for the system.
- If the action requested was F_SETLK or F_SETLKW, the file that is specified by File_descriptor does not support locking, or the Lock_information parameter contains incorrect values.
- The action requested was F_CLOSFD and the file descriptor that is specified by File_descriptor_2 was less than File_descriptor, but not equal to -1.
- The action requested was F_SETTAG or F_CONTROL_CVT, and either incorrect input data was supplied, or the file was inappropriate for this use.
- An incorrect action was requested.
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. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
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.
Usage notes
- A process can use the fcntl service to close a range of file descriptors. File_descriptor_2 must be greater than or equal to File_descriptor, or it can be -1, which indicates that all file descriptors greater than or equal to File_descriptor are to be closed.
- Use of F_CLOSFD is meant to be consistent with use of the close service (BPX1CLO, BPX4CLO). You cannot close file descriptors that could not also be closed using the close service.
- If a file descriptor cannot be closed, it is considered an error, but the request continues with the next file descriptor in the range. File descriptors that are not in use are ignored.
- A process can use the fcntl service to lock out other cooperating processes from part of a file, so that the process can read or write to that part of the file without interference from others. This ensures data integrity when several processes are accessing a file concurrently.
- File locking can only be performed on file descriptors that refer to regular files. Locking is not permitted on file descriptors that refer to directories, FIFO files, pipes, character special files, or any other type of file.
- Locking operations are controlled with a structure mapped by BPXYBRLK, whose format is described in Parameters. This structure is needed whether the request is for setting a lock, releasing a lock, or querying a particular byte range for a lock. The following is a more detailed description of the BPXYBRLK structure.
- The l_type field is used to specify the type of lock that is to
be set, cleared, or queried. Valid values for l_type are as follows:
- Type
- Description
- F_RDLCK
- A read lock. Specified as a halfword integer value of 1, this is also known as a shared lock. This type of lock specifies that the process can read the locked part of the file, and other processes cannot write on that part of the file while it is doing so. A process can change a held write lock, or any part of it, to a read lock, thereby making it available for other processes to read. Multiple processes can have read locks on the same part of a file simultaneously. To establish a read lock, a process must have the file that is accessed for reading.
- F_WRLCK
- A write lock. Specified as a halfword integer value of 2, this is also know as an exclusive lock. This type of lock indicates that the process can write on the locked part of the file, without interference from other processes. If one process puts a write lock on part of a file, no other process can establish a read lock or write lock on that same part of the file. A process cannot put a write lock on part of a file if there is already a read lock on an overlapping part of the file, unless that process is the only owner of that overlapping read lock. In such a case, the read lock on the overlapping section is replaced by the write lock that is being requested. To establish a write lock, a process must have the file that is accessed for writing.
- F_UNLCK
- Indicates unlock. Specified as a halfword integer value of 3, this is used to unlock all locks held on the given range by the requesting process.
- The use of the l_whence and l_start fields for the fcntl service parallels their processing for the lseek service (BPX1LSK, BPX4LSK). See lseek (BPX1LSK, BPX4LSK) — Change a file's offset for more information.
- The l_whence field is used to specify how the byte range offset
is to be found within the file. Valid values for l_whence are as follows:
- Value
- Description
- SEEK_SET
- Stands for the start of the file, and is specified as a halfword integer value of 0.
- SEEK_CUR
- Stands for the current file offset in the file, and is specified as a halfword integer value of 1.
- SEEK_END
- Stands for the end of the file, and is specified as a halfword integer value of 2.
- The l_start field is used to identify the part of the file that
is to be locked, unlocked, or queried. The part of the file that
is affected by the lock begins at this offset from the location specified
by the l_whence field. For example, if l_whence is SEEK_CUR and l_start
is the value 10, a F_SETLK request attempts to set
a lock beginning 10 bytes past the current cursor position. The l_start
value may be negative, provided that when it is added to the offset
indicated by the l_whence position, the resulting offset does not
extend beyond the beginning of the file. Note: Although you cannot request a byte range that begins or extends beyond the beginning of the file, you can request a byte range that starts or extends beyond the end of the file.
- The l_len field is used to give the size of the locked part of the file, in bytes. The value specified for l_len may be negative. If l_len is positive, the area affected begins at l_start and ends at l_start+l_len-1. If l_len is negative, the area affected begins at l_start+l_len and ends at l_start-1. If l_len is zero, the locked part of the file begins at the position specified by l_whence and l_start, and extends to the end of the file.
- The l_pid field identifies the process ID of the process that holds the lock found on an F_GETLK request, if one was found.
- You can set locks by specifying F_SETLK as the Action parameter for the BPX1FCT (BPX4FCT) service. If the lock cannot be obtained, a Return_value of -1 is returned along with an appropriate Return_code and Reason_code. You can also use F_SETLK to release locks that are already held, by setting l_type to F_UNLCK.
- You can also set locks by specifying F_SETLKW as the Action parameter for the BPX1FCT (BPX4FCT) service. If the lock cannot be obtained because another process has a lock on all or part of the requested range, the F_SETLKW request waits until the specified range becomes free and the request can be completed. You can also use F_SETLKW to release locks that are already held, by setting l_type to F_UNLCK.
- If a signal interrupts a call to the fcntl service while it is waiting in an F_SETLKW operation, the function returns with a Return_value of -1 and a Return_code of EINTR.
- F_SETLKW operations can encounter deadlocks. This happens when process A is waiting for process B to unlock a region, and process B is waiting for process A to unlock a different region. If the system detects that an F_SETLKW might cause a deadlock, the fcntl service returns with a Return_value of -1 and a Return_code of EDEADLK.
- A process can determine locking information about a file by using F_GETLK as the Action parameter for the fcntl service. In this case, Argument should specify a pointer to a structure that is mapped by the BPXYBRLK macro. This structure should describe a lock operation that the caller would like to perform. When the fcntl service returns, the structure is modified to describe the first lock found that would prevent the proposed lock operation from completing successfully.
- If a lock is found that would prevent the proposed lock from being
set, the F_GETLK request returns a modified structure whose:
- l_whence value is always SEEK_SET
- l_start value gives the offset of the locked portion from the beginning of the file
- l_len value is set to the length of the locked portion of the file
- l_pid value is set to the process ID of the process that is holding the lock
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.
- A process can have several locks on a file simultaneously, but it can have only one type of lock set on any given byte. If a process puts a new lock on part of a file that it has previously locked, the process has only one lock on that part of the file and the lock type is the one given by the most recent locking operation.
- If an F_SETLK or F_SETLKW request is made to unlock a byte region of a file, all locks that are held by that process within the specified region are released. In other words, each byte specified on an unlock request is freed from any lock that is held against it by the requesting process.
- All of a process's locks on a file are removed when the process closes a file descriptor for that file. Locks are not inherited by a child process created with the fork service. See fork (BPX1FRK, BPX4FRK) — Create a new process for more information about the fork service.
Related services
Characteristics and restrictions
There are no restrictions on the use of the fcntl service.
Examples
For an example that uses this callable service, see BPX1FCT (fcntl) example.