The write callable service writes data from a buffer to an open file or socket.
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task SRB - AF_INET/AF_INET6 socket support only |
Cross memory mode: | PASN = HASN |
AMODE (BPX1WRT): | 31-bit task or SRB mode |
AMODE (BPX4WRT): | 64-bit task or SRB mode |
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. |
|
AMODE 64 callers use BPX4WRT with the same parameters. The Buffer_address parameter is a doubleword.
The name of a fullword that contains the file descriptor of the file or socket to write to.
The name of a fullword (doubleword) that contains the starting address of the data that is to be written.
The name of a fullword that contains the ALET for Buffer_address, which identifies the address space or data space the buffer resides in.
You should specify a Buffer_ALET of 0 for the normal case of a buffer in the user's address space (current primary address space). If a value other than 0 is specified for the Buffer_ALET, the value must represent a valid entry in the dispatchable unit access list (DUAL).
The name of a fullword that contains the number of bytes that are to be written.
The name of a fullword in which the write service returns the number of actual bytes that were written, if the request is successful, or -1, if it is not successful.
Return_code | Explanation |
---|---|
EAGAIN | Blocking is not in effect for the specified file, and output cannot be written immediately. |
EBADF | The File_descriptor parameter does not contain the descriptor of an open file; or that file is not opened for write services. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen. |
ECONNRESET | Connection reset by peer. The following reason code can accompany the return code: JRSocketNotCon. |
EFBIG | Writing to the specified file would exceed either the file size limit for the process or the maximum file size that is supported by the physical file system. |
EINTR | The service was interrupted by a signal before it could write any data. The following reason code can accompany the return code: JRSockRdwrSignal. |
EINVAL | The Write_Count parameter contains a value that is less than zero. |
EIO | The process is in a background process group and is attempting to write to its controlling terminal. However, TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU signals, and the process group of the process is orphaned. This can happen, for example, if a background job tries to write to the terminal after the user has logged off. |
EMSGSIZE | The message is too large to be sent all at once, as the socket requires. The following reason code can accompany the return code: JRSockBufMax. |
ENOBUFS | A buffer could not be obtained. The following reason code can accompany the return code: JROutofSocketCells. |
ENOTCONN | The socket was not connected. The following reason code can accompany the return code: JRSocketNotCon. |
EPIPE | The request is for a write to a pipe that is not open for reading by any other process; or an attempt was made to write to a socket that is shut down or closed. This error also generates a SIGPIPE signal. The following reason code can accompany the return code: JRSocketClosed. |
EWOULDBLOCK |
The following reason codes can accompany the return code: JRWouldBlock, JRTimeout. |
The name of a fullword in which the write service stores the reason code. The write 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.
The value of Write_count is checked against the file size limit for the process. If no data can be written without exceeding this limit, an error of EFBIG is returned and the SIGXFSZ signal is generated for the process. If at least one byte can be written before exceeding the file size limit, the write is considered successful.
If the file descriptor refers to a file on which you cannot seek, the service begins writing at the current position. No file offset is associated with such a file.
If the file was opened with the "append" option, the write routine sets the file offset to the end of the file before it writes output.
If the write count that you specify is greater than the remaining space on the output device, or greater than the file size limit for the process, fewer bytes than you requested are written. When at least 1 byte is written, the write is considered successful. If you are not using a pseudoterminal, an attempt to append to the same file causes an error. An error of ENOSPC is returned when there is no remaining space on the output device. An error of EFBIG is returned when the file size limit for the physical file system is exceeded. An error of EFBIG is also returned if the file size limit for the process is exceeded, at which time the write service also generates a SIGXFSZ signal for the process. With a pseudoterminal, if there is not enough room in the buffer for the whole write, the number of bytes that fit are written, and the number of bytes written is returned. However, on the next write (assuming the buffer is still full), there is a block or EAGAIN is returned, depending on whether the file was opened blocking or nonblocking.
Similarly, fewer bytes are written if the service is interrupted by a signal after some, but not all, of the specified number of bytes are written. The return value shows the number of bytes that are written. But if no bytes were written before the routine was interrupted, the return value is -1, and an EINTR error is reported.
If the file was opened by an authorized program, all subsequent reads and writes against the file must be issued from an authorized state.
The first restriction is not applicable if each thread coordinates its reads and writes so that simultaneous I/O does not occur. Both restrictions are not applicable if each thread opens the file independently.
Reads or writes that cause a conversion of greater than 2 G result in an EINVAL error with reason JrUniOpTooBig.
Refer to lseek (BPX1LSK, BPX4LSK) — Change a file's offset for instances of how a lseek operation in a conversion environment can affect read and write operations
For an example using this callable service, see BPX1WRT (write) example.