close (BPX1CLO, BPX4CLO) — Close a file
Function
The close callable service closes a file. You identify the file by its file descriptor.
Requirements
| Operation | Environment |
|---|---|
| Authorization: | Supervisor state or problem state, any PSW key |
| Dispatchable unit mode: | Task or SRB. If SRB, AF_INET/AF_INET6 socket support only |
| Cross memory mode: | PASN = HASN |
| AMODE (BPX1CLO): | 31-bit task or SRB mode |
| AMODE (BPX4CLO): | 64-bit task mode only |
| ASC mode: | Primary 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
CALL BPX1CLO,(File_descriptor,
Return_value,
Return_code,
Reason_code)AMODE 64 callers use BPX4CLO with the same parameters.
Parameters
- File_descriptor
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword containing the file descriptor of the file or socket the caller wants closed. The file descriptor is returned by the open service (see open (BPX1OPN, BPX4OPN) — Open a file) or by the socket service (see socket or socketpair (BPX1SOC, BPX4SOC) — Create a socket or a pair of sockets).
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the close service returns
0if the request is successful, or-1if it is not successful. - Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the close service stores the return code. The close service returns Return_code only if Return_value is-1. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. The close service can return one of the following values in the Return_code parameter:Return_code Explanation EAGAIN The service did not complete because the file descriptor specified is in use by another thread in the same process. EBADF The File_descriptor does not identify a valid, open file. The following reason codes can accompany the return code: JRClNeedClose and JRNotForDir. EINTR The service was interrupted by a signal while it was processing the close request. The file may or may not be closed. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword where the close service stores the reason code. The close service returns Reason_code only if Return_value is
-1. Reason_code further qualifies the Return_code value. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes
- Closing a file closes, or frees, the file descriptor by which the file was known to the process. The system can then reassign the file descriptor to the same file or to another file when it is opened.
- Closing a file descriptor also unlocks all outstanding byte range locks that a process has on the associated file.
- If a file has been opened by more than one process, each process has a file descriptor. When the last open file descriptor is closed, the file itself is closed. If the file's link count is zero at that time, the file's space is freed and the file becomes inaccessible. When the last open file descriptor for a pipe or FIFO special file is closed, any data remaining in the file is discarded.
- The close callable service is for files or sockets.
- See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
Related services
- exec (BPX1EXC, BPX4EXC) — Run a program
- fcntl (BPX1FCT, BPX4FCT) — Control open file descriptors
- fork (BPX1FRK, BPX4FRK) — Create a new process
- open (BPX1OPN, BPX4OPN) — Open a file
- pipe (BPX1PIP, BPX4PIP) — Create an unnamed pipe
- socket or socketpair (BPX1SOC, BPX4SOC) — Create a socket or a pair of sockets
- unlink (BPX1UNL, BPX4UNL) — Remove a directory entry
Characteristics and restrictions
There are no restrictions on the use of the close service.