writev (BPX1WRV, BPX4WRV) — Write data from a set of buffers

Function

The writev callable service writes data from a set of buffers.

Requirements

Parameters

File_descriptor

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the file descriptor for which the writev is to be done.

Iov_count

Supplied and returned parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the number of buffers that are pointed to by Iov_struct. The total number of buffers may not exceed IOV_MAX (defined in BPXYIOV — Map the I/O vector structure).

Iov_struct

Supplied parameter

Type:

Character

Length:

iov_count × length(iov)

The name of a field that contains 31(64)-bit pointers to buffers from which data is to be retrieved for the purpose of writing to the file or socket. In 64-bit mode, Iov_struct contains doubleword pointer and length subfields. See BPXYIOV — Map the I/O vector structure for more information about the format of this field.

Iov_alet

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the ALET for Iov_struct.

Iov_buffer_alet

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a field that contains the ALET for buffers that are pointed to by Iov_struct.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the writev service returns one of the following:

• The number of bytes that were written from the buffers, if the request is successful.
• -1, if the request is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the writev service stores the return code. The writev 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 writev service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EBADF	An incorrect file descriptor was specified. 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 supported by the physical file system.
EINTR	A signal interrupted the writev service before any data was written. The following reason code can accompany the return code: JRSockRdwrSignal.
EINVAL	An incorrect value was specified on one of the input parameters. The following reason code can accompany the return code: JRSocketCallParmError.
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.
ENOTSOCK	Socket_descriptor does not refer to a valid socket descriptor. The following reason code can accompany the return code: JRMustBeSocket.
EPIPE	An attempt was made to write to a socket that is shut down or closed. The following reason code can accompany the return code: JRSocketClosed. This error also generates a SIGPIPE signal.
EPROTOTYPE	An incorrect socket type was supplied. The following reason code can accompany the return code: JRIncorrectSocketType.
EWOULDBLOCK	The socket is marked nonblocking and no space is available for data to be written, or the SO_SNDTIMEO timeout value was reached before space became available. The socket is marked blocking. The call is blocked, without sending any data, for that time period which was specified in the SO_SNDTIMEO option. The following reason codes can accompany the return code: JRTimeout, JRWouldBlock.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the writev service stores the reason code. The writev 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

1. See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
2. This callable service works with any open file descriptor, including files and sockets.
3. Number of bytes written: If the number of bytes to be written is greater than the remaining space on the output device, or greater than the file size limit for the process, not all of the data can be written. When at least 1 byte is written, the writev is considered successful. The return value shows the number of bytes that were written. An attempt to writev again to the same file causes an EFBIG error, and if the process file size limit has been exceeded, the writev service generates a SIGXFSZ signal for the process.
4. Bytes written: The number of bytes that are requested for writing is not checked against any system limit. A limit can be imposed by a high-level-language POSIX implementation.

   The number of bytes that are requested for writing 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.

5. File offset: If File_descriptor specifies a regular file or any other type of file on which you can seek, the write service begins writing at the file offset that is associated with that file descriptor. A successful write operation increments the file offset by the number of bytes that are written. If the incremented file offset is greater than the previous length of the file, the file is extended; the length of the file is set to the new file offset.

   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 writing output.

6. Number of bytes written: Ordinarily, the number of bytes that are written to the output file is the number requested for writing. (This number can be zero. If you ask to write zero bytes, the service simply returns a return value of zero without attempting any other action.)

   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 that were 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 were written. But if no bytes were written before the routine was interrupted, the return value is -1 and an EINTR error is reported.

7. The writev service causes signal SIGTTOU to be sent if all the following conditions are met:
   • The process is attempting to write to its controlling terminal.
   • TOSTOP is set as a terminal attribute (see tcgetattr (BPX1TGA, BPX4TGA) — Get the attributes for a terminal or tcsetattr (BPX1TSA, BPX4TSA) — Set the attributes for a terminal).
   • The process is running in a background process group.
   • The SIGTTOU signal is not blocked or ignored.
   • The process is not an orphan.

Related services

• readv (BPX1RDV, BPX4RDV) — Read data and store it in a set of buffers
• write (BPX1WRT, BPX4WRT) — Write to a file or a socket

Characteristics and restrictions

There are no restrictions on the use of the writev service.