Function

write invokes the write callable service to copy data to a buffer and then write it to an open file. The number of bytes written is returned in RETVAL.

Refer to z/OS UNIX System Services Programming: Assembler Callable Services Reference for restrictions when running in a conversion environment.

Parameters

fd

The file descriptor (a number) for a file.

variable

The name of the variable that is to store the data to be written to the file.

length

The number of bytes to be written to the file identified by fd. If you want a length longer than 4096 bytes, specify the length parameter. If you do not specify length, the length of variable is used, up to a maximum length of 4096 bytes. A variable longer than 4096 bytes is truncated to 4096, and RC is set to 4.

Usage notes

1. Within the variable, you can use the predefined variables beginning with ESC_ the same way you use C language escape sequences to avoid code page dependence with some control characters. For example:

   buf='line 1' || esc_n

   appends a newline character to the string 'line 1'.

   ESC_A

   Alert (bell)

   ESC_B

   Backspace

   ESC_F

   Form feed (new page)

   ESC_N

   Newline

   ESC_R

   Carriage return

   ESC_T

   Horizontal tab

   ESC_V

   Vertical tab

2. Return codes:
   • 4 indicates one of these:
     • If length was specified, the number of characters specified by length is not the same as the length of variable. The data is truncated or padded as required. The characters used for padding are arbitrarily selected.
     • If length was not specified, 4 indicates that a variable longer than 4096 bytes was truncated to 4096.
   • -24 indicates that storage could not be obtained for the buffer.
3. File offset: If fd specifies a regular file or any other type of file on which you can seek, the write service begins writing at the file offset associated with that file descriptor. A successful write operation increments the file offset by the number of bytes 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.

4. Number of bytes written: Ordinarily, the number of bytes written to the output file is the number you specify in the length parameter. (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 length you specify is greater than the remaining space on the output device, fewer bytes than you requested are written. When at least 1 byte is written, the write is considered successful. The return value shows the number of bytes written. An attempt to write again to the same file, however, causes an ENOSPC error unless you are using a pseudoterminal. With a pseudoterminal, if there is not enough room in the buffer for the whole write, the number of bytes that can 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 written. If no bytes were written before the routine was interrupted, the return value is -1 and an EINTR error is reported.

5. The write service causes signal SIGTTOU to be sent under all the following conditions:
   • The process is attempting to write to its controlling terminal.
   • TOSTOP is set as a terminal attribute.
   • The process is running in a background process group.
   • The SIGTTOU signal is not blocked or ignored.
   • The process is not an orphan.
   If all the conditions are met, SIGTTOU is sent.
6. Write requests to a pipe (FIFO) are handled in the same as write requests to a regular file, with the following exceptions:
   • There is no file offset associated with a pipe; each write request appends to the end of the pipe.
   • If the size of the write request is less than or equal to the value of the PIPE_BUFF variable (described in the pathconf service), the write is guaranteed to be atomic. The data is not interleaved with data from other write processes on the same pipe. If the size of the write request is greater than the value of PIPE_BUFF, the data can be interleaved, on arbitrary boundaries, with writes by other processes, whether or not the O_NONBLOCK flag is set.