vn_anr — Accept a socket connection and read the first block of data

Function

The vn_anr operation accepts a connection request for a socket server from a socket client, and reads the first block of data.

Environment on entry and exit

See Environment for PFS operations.

Input parameter format

vn_anr      (Token_structure,
             OSI_structure,
             Audit_structure,
             Anr_addrs
             User_IO_structure
             Open_flags,
             Acp_token,
             Return_value,
             Return_code,
             Reason_code)

Parameters

Token_structure

Supplied parameter

Type:: TOKSTR
Length:: Specified by TOKSTR.ts_hdr.cblen.

The Token_structure represents the file (vnode) that is being operated on. It contains the PFS's initialization token, mount token, and the file token. Refer to LFS/PFS control block structure for a discussion of this structure, and to the TOKSTR typedef in BPXYPFSI in Interface structures for C language servers and clients for its mapping.

OSI_structure

Supplied and returned parameter

Type:: OSI
Length:: Specified by OSI.osi_hdr.cblen.

The OSI_structure contains information that is used by the OSI operations that might be called by the PFS. See OSI services for more information.

It also contains MVS-specific information that needs to be passed to the PFS, including SMF accounting fields, a work area, a recovery area, and an optional pointer to an output ATTR structure. For more information about the OSI structure, see The OSI structure.

This area is mapped by the OSI typedef in BPXYPFSI in Interface structures for C language servers and clients.

Audit_structure

Supplied parameter

Type:: CRED
Length:: Specified by CRED.cred_hdr.cblen.

The Audit_structure contains information that is used by the security product for access checks and auditing. It is passed to most SAF routines that are invoked by the PFS.

Refer to Security responsibilities and considerations for a discussion of security processing, and to the CRED typedef in BPXYPFSI in Interface structures for C language servers and clients for the mapping of this structure.

Open_flags

Supplied parameter

Type:: Structure
Length:: Fullword

A fullword that supplies the bits associated with the socket. The defined values for this field are mapped by fcntl.h.

Acp_token

Supplied and returned parameter

Type:: Token
Length:: 8 bytes

An area that is used in one of two ways:

The LFS passes the PFS's token for a reusable socket.
The LFS passes a value of 0, and the PFS returns the Vnode token for a new accepted socket.

User_IO_structure

Supplied and returned parameter

Type:: UIO
Length:: Specified by UIO.u_hdr.cblen.

An area that contains the buffer parameters for the receive operation that is to be performed. This area is mapped by the UIO typedef in the BPXYVFSI header file (see Interface structures for C language servers and clients). See "Specific processing notes" for details on how the fields in this structure are processed.

Anr_addrs

Supplied parameter

Type:: struct anr_addrs
Length:: sizeof(anr_addrs)

A structure that describes the remote and local socket addresses. This structure contains the following fields:

Field

Description

Remote_sockaddr_length

A fullword that supplies the length of the Remote_sockaddr buffer that is pointed to by Remote_sockaddr_ptr. On return, this parameter contains the length of the socket address that was put in the Remote_sockaddr buffer.

If the value of Remote_sockaddr_length is 0, the Remote_sockaddr is not to be returned.

Remote_sockaddr_ptr

A pointer to the Remote_sockaddr buffer. On return, this buffer contains the socket address of the remote socket that has just connected.

Local_sockaddr_length

A fullword that supplies the length of the Local_sockaddr buffer that is pointed to by Local_sockaddr_ptr.

On return, this parameter contains the length of the socket address that was put in the Local_sockaddr buffer.

If this value is 0, the Local_sockaddr is not to be returned.

Local_sockaddr_ptr

A pointer to the Local_sockaddr buffer. On return, this buffer contains the socket address of the new local socket that was just created.

msg_flags

A fullword that supplies the message flags mapped by BPXYMSGF. On return this parameter contains the updated message flags. (For more information, see Mapping macros in z/OS UNIX System Services Programming: Assembler Callable Services Reference).

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_anr operation returns the results of the operation, as one of the following:

Return_value: Meaning
-1: The operation was either not successful or, when Return_code is EINTRNODATA, partially successful. The Return_code and Reason_Code values must be filled in by the PFS when Return_value is -1.
0: The operation was successful; the value represents the number of bytes that were transferred.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword in which the vn_anr operation stores the return code. The vn_anr operation returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of supported return code values.

The vn_anr operation should support at least the following error values:

Return_code	Explanation
EFAULT	The address of one of the buffers is not in addressable storage.
EINTR	A signal arrived before a connection was assigned to this request.
EINTRNODATA	A signal arrived after a connection was assigned to this request, but before any data arrived. The connection has been established. The result of this call is equivalent to a successful vn_accept. This condition does not occur in a PFS that does not assign arrived connections to a vn_anr request until some data has also arrived.
EINVAL	An incorrect parameter was specified.
EWOULDBLOCK	A new connection has been established but the SO_RCVTIMEO timeout value was reached before any data arrived. The result of this call is equivalent to a successful vn_accept. This condition does not occur in a PFS that does not assign arrived connections to a vn_Anr request until some data has also arrived.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

A fullword where the vn_anr operation stores the reason code. The vn_anr operation returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. These reason codes are documented by the PFS.

Implementation notes

Overview of vn_anr processing:
The vn_anr operation is a functional combination of the vn_accept and vn_rdwr operations, in that an inbound connection is accepted to create a new socket and the first block of data is read on that socket. The output is the new connected socket and the data.

The vn_anr operation is generated from an application call to the accept_and_recv callable service (BPX1ANR). The accept_and_recv callable service is designed to work with the send_file service (BPX1SF) to provide an efficient file transfer capability for connection-oriented servers with short connection times and high connection rates. See accept_and_recv (BPX1ANR, BPX4ANR) — Accept a connection and receive the first block of data in z/OS UNIX System Services Programming: Assembler Callable Services Reference for more information.

The vn_anr operation is intended to be used from a multithreaded server, that is, a server with several threads simultaneously calling accept_and_recv() on the same socket. The PFS must handle queuing for vn_anr requests on the same socket that are waiting to be satisfied. When a connection and its first data have arrived, the connection and data are given to one of the waiting vn_anr requesters. All of the server threads are expected to be equal, and their requests may be satisfied in any order. In particular, LIFO order would reduce the serialization necessary to manage the requester queue.

The PFS does not complete the vn_anr operation until the first data has arrived on the new connection or a signal arrives for this thread. The listening socket must be in blocking mode; this requirement is enforced by the LFS.

When socket reuse is supported by the PFS, the Acp_token parameter is used to pass the PFS's token for the socket that is being reused. When reuse is not supported, or when a reusable socket is not supplied by the application, the Acp_token parameter is used to return the vnode token of the new socket that is created. In this case, the input Acp_token is 0, and the output Acp_token is basically the same as the Vnode_token parameter of the vn_accept operation.

A PFS that does not support socket reuse does not have to be coded to reject vn_anr requests that attempt to reuse a socket. A reusable socket is one that was closed by a prior write-type operation that specified the REUSE flag. If the PFS does not honor the REUSE flag, it is assumed that the PFS does not support reuse, and the socket is closed in the normal way. Consequently, the Acp_token parameter would be 0 on a subsequent vn_anr request.

Because the vn_anr operation is a combined operation, it can be interrupted between the connection arrival and the data arrival. If the PFS irrevocably associates a new connection to a vn_anr request before any data has arrived and is subsequently interrupted by a signal, it may return the connection via Acp_token, and set a Return_value of -1 and a Return_code of EINTRNODATA. It is strongly recommended that the PFS not assign connections to vn_anr requests until data has arrived, because doing so ties up a server's worker threads while the PFS is waiting for the data to arrive.
If an application uses both accept() and accept_and_recv() calls on the same socket from several threads at the same time, the results are allowed to be unpredictable. Depending on PFS design and timing, the vn_accept and vn_anr calls may be satisfied in any order. Because it is not recommended that connections be assigned to vn_anr requests until the first data has arrived, it is possible that vn_accept requests could consume all arriving connections.