read (BPX1RED, BPX4RED) — Read from a file or socket

Function

The read callable service reads the number of bytes that you specify from a file or socket into a buffer that you provide.

Requirements

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 (BPX1RED): 31-bit task or srb mode
AMODE (BPX4RED): 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

The syntax format is as follows:
CALL BPX1RED,(File_descriptor,
              Buffer_address,
              Buffer_ALET,
              Read_count,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4RED with the same parameters. The Buffer_address parameter is a doubleword.

Parameters

File_descriptor
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the file descriptor of an open file or socket.

Buffer_address
Parameter supplied and returned
Type:
Address
Length:
Fullword (doubleword)

The name of a fullword (doubleword) that contains the address of the buffer into which data is to be read.

Buffer_ALET
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the ALET for the Buffer_address that identifies the address space or data space where the buffer resides.

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).

Read_count
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the number of bytes that you want to read from the file. This number must be less than or equal to the length of the buffer that you provide for data to be read into.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the read service returns the number of bytes that were actually read (this may be 0) if the request is successful, or -1 if it is not successful.

For more information about the return value, refer to usage note 5.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the read service stores the return code. The read 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 read service can return one of the following values in the Return_code parameter:
Return_code Explanation
EAGAIN The file was opened with the nonblock option, and data is not available to be read.
EBADF The File_descriptor parameter does not contain the descriptor of an open file; or the file is not opened for read. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen.
EINTR The service was interrupted by a signal before it could read any data.
EINVAL The Read_Count parameter contains a value that is less than zero; or the socket is marked shutdown for read. The following reason codes can accompany the return code: JRSocketClosed, JRSocketCallParmError.
EIO The process is in a background process group, and is attempting to read from its controlling terminal. Either the process is ignoring or blocking the SIGTTIN signal, or the process group is orphaned.
ENOBUFS A buffer could not be obtained. The following reason code can accompany the return code: JROutofSocketCells.
ENOTSOCK The Socket_descriptor does not refer to a valid socket descriptor. The following reason code can accompany the return code: JRMustBeSocket.
EWOULDBLOCK
  • The socket is marked nonblocking, and no data is waiting to be received. The following reason code can accompany the return code: JRWouldBlock.
  • The socket is marked blocking, and the call has blocked, without receiving any data, for the time period specified in the SO_RCVTIMEO option. The following reason code can accompany the return code: JRTimeout.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

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

  1. See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
  2. Read_count: The value of Read_count is not checked against any system limit. A limit can be imposed by a high-level-language POSIX implementation.
  3. Access time: A successful read updates the access time of the file read.
  4. Origin of bytes read: If the file that is specified by File_descriptor is a regular file, or any other type of file where a seek operation is possible, bytes are read from the file offset that is associated with the file descriptor. A successful read increments the file offset by the number of bytes that are read. For files for which no seek operation is possible, there is no file offset associated with the file descriptor. Reading begins at the current position in the file.
  5. Number of bytes read: When a read request completes, the Return_value field shows the number of bytes that were actually read—a number less than or equal to the number that was specified as Read_count. The following are some reasons why the number of bytes read might be less than the number of bytes requested:
    • Fewer than the requested number of bytes remained in the file; the end of file was reached before Read_count bytes were read.
    • The service was interrupted by a signal after some, but not all, of the requested bytes were read. (If no bytes were read, the return value is set to —1 and an error is reported.)
    • The file is a pipe, FIFO, or special file, and fewer bytes than Read_count specified were available for reading.
      There are several reasons why a read request might complete successfully with no bytes read. That is, with Return_value set to 0. For example, zero bytes are read in these cases:
      • The service specified a Read_count of zero.
      • The starting position for the read was at or beyond the end of the file.
      • The file that is being read is a FIFO file or a pipe, and no process has the pipe open for writing.
      • The file that is being read is a slave pseudoterminal, and a zero-length canonical line was written to the master.
      • A directory is being read and the Physical File System does not support simple reads from directories. Opendir() and readdir() should be used.
  6. Nonblocking: If a process has a pipe open for reading with nonblocking specified, a request to read from the file ends with a return value of —1 and a "Resource temporarily unavailable" return code. But if nonblocking is not specified, the read request is blocked (does not return) until some data is written, or until the pipe is closed by all other processes that have the pipe open for writing.

    Master and slave pseudoterminals also operate this way, except that how they act depends on how they were opened. If the master or the slave is opened blocking, the reads are blocked if there is no data. If they are opened nonblocking, EAGAIN is returned if there is no data.

  7. SIGTTIN processing: The read service causes signal SIGTTIN to be sent under the following conditions:
    • The process is attempting to read from its controlling terminal, and
    • The process is running in a background process group, and
    • The SIGTTIN signal is not blocked or ignored, and
    • The process group of the process is not orphaned.
    If these conditions are met, SIGTTIN is sent. If SIGTTIN has a handler, the handler gets control, and the read ends with the return code set to EINTR. If SIGTTIN is set to default, the process stops in the read and continues when the process is moved to the foreground.

Related services

Note: The read service is not related to the read shell command.

Characteristics and restrictions

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 read (BPX1RED, BPX4RED) and write (BPX1WRT, BPX4WRT) callable services do not support simultaneous reading or writing of the same shared open file by different threads when one or both of the following are true:
  1. Automatic conversion is enabled using Enhanced ASCII (ON) and different character set IDs (CCSIDs) are used.
  2. Automatic conversion is enabled using Unicode Services (ALL) and different CCSIDs are used, or mixing read and write operations of multibyte characters are performed which result is storing of partial characters.

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 the BPX1FCT (fcntl) operations for instances of how a lseek operation in a conversion environment can affect read and write operations

Examples

See BPX1RED (read) example.