connect (BPX1CON, BPX4CON) — Establish a connection between two sockets

Function

For stream sockets, the connect callable service establishes a connection from a client socket to a socket at a server. For UDP (Universal Datagram Protocol) sockets, the connect callable service specifies the peer for a socket.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN = HASN
AMODE (BPX1CON):	31-bit task or SRB mode
AMODE (BPX41CON):	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 BPX1CON,(Socket_descriptor,
              Sockaddr_length,
              Sockaddr,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4CON with the same parameters.

Parameters

Socket_descriptor

Supplied parameter

Type:: Integer
Length:: Fullword

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

Sockaddr_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the length of Sockaddr.

Sockaddr

Supplied parameter

Type:: Character
Length:: Length specified by Sockaddr_length.

The name of a field that contains the address of the socket or the name of the peer to which a connection is to be attempted.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

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

0, 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 connect service stores the return code. The connect 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 connect service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	For AF_UNIX sockets, search permission is denied for a component of the path prefix, or write access to the named socket is denied.
EAFNOSUPPORT	The address family that was specified in the address structure is not supported.
EBADF	The socket descriptor is incorrect. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen.
ECONNREFUSED	The attempt to connect was rejected. The connect request might exceed the backlog count of the target socket, or the target socket might be closed. The following reason codes can accompany the return code: JRSocketNotFound, JRExceedsBacklogCount, JRListenNotDone.
EINVAL	The length that is specified in the Sockaddr_length or in the name length field in the Sockaddr is not valid. The following reason codes can accompany the return code: JRSocketCallParmError, JRSockNoName.
EINTR	A signal interrupted the connect service before this connection was accepted. The following reason code can accompany the return code: JRSignalReceived.
EIO	There has been a network or transport failure. The following reason codes can accompany the return code: JRPrevSockError, JRTransportDriverNotAccessible.
EISCONN	The socket is already connected.
ENOBUFS	A buffer could not be obtained. The following reason code can accompany the return code: JROutofSocketCells.
ENOTSOCK	Socket_descriptor does not refer to a valid socket descriptor. The following reason code can accompany the return code: JRMustBeSocket.
EOPNOTSUPP	The socket is ready to accept connections. An accept request was expected. The following reason code can accompany the return code: JRListenAlreadyDone.
EPROTOTYPE	The address specifies a socket that is not the correct type for this request. The following reason code can accompany the return code: JRIncorrectSocketType.
EWOULDBLOCK	The socket is marked nonblocking, and the connection cannot be completed immediately.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

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

For connectionless sockets, the connect service might be advantageous because the destination address need not be specified for every datagram sent. Once a UDP (connectionless) socket is connected, the read, write, recv, and send system calls can be used for I/O on those sockets. Otherwise, only the sendto/recvfrom system calls can be used. Once a UDP socket is connected, only datagrams from the specified sockaddr are received on the socket. To disconnect a UDP socket from a previous connection, issue the connect system call with an invalid (null) sockaddr.
The connect callable service can be used to test whether a target socket is available for the connect. If the socket is not available, an ECONNREFUSED is returned.
The connect callable service will always either immediately succeed or fail, depending on the condition of the queue of pending connections, or backlog queue. If the backlog queue is not full, the connect request will immediately succeed. If the backlog queue is full, the connect request will fail with Return_code of ECONNREFUSED.
See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.

Characteristics and restrictions

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

Examples

For an example that uses this callable service, see BPX1CON (connect) example.