bind2addrsel (BPX1BAS, BPX4BAS) — Bind the socket descriptor to the best source address
Function
The bind with source address selection callable service binds the best source address for the provided destination IP address to an AF_INET6 socket descriptor.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task or SRB |
Cross memory mode: | PASN = HASN |
AMODE (BPX1BAS): | 31-bit task or SRB mode |
AMODE (BPX4BAS): | 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
|
AMODE 64 callers use BPX4BAS with the same parameters.
Parameters
- Socket_descriptor
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains the AF_INET6 socket file descriptor for which the bind with source address selection 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 destination IP address. The best source address for the provided destination address will be selected and bound to the AF_INET6 socket descriptor.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the bind with source address selection 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 bind with source address selection service stores the return code. The bind with source address selection 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 bind with source address selection service can return one of the following values in the Return_code parameter:Return_code Explanation EAFNOSUPPORT The address family 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. EINVAL One of the input parameters was not valid. The following reason codes can accompany the return code: JRSocketCallParmError, JRSockNoname, JrInAddrAnyNotAllowed. EIO There has been a network or transport failure. The following reason code can accompany the return code: JRPrevSockError. 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 domain type is not supported. The following reason code can accompany the return code: JrIncorrectSocketType. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the bind with source address selection service stores the reason code. The bind with source address selection 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
- An application can retrieve the assigned socket name with the getsockname service.
- An application's suggestion of “best” source address is set by the IPv6 setsockopt() call socket option SOCK#IPV6_ADDR_PREFERENCES.
- In CINET environment, bind with source address selection service is routed to the TCPIP stack that is most appropriate for the provided destination IP address.
- See Callable services available to SRB mode routines for more information about programming considerations for SRB mode.
Related services
- bind (BPX1BND, BPX4BND) — Bind a unique local name to a socket descriptor
- accept (BPX1ACP, BPX4ACP) — Accept a connection request from a client socket
- listen (BPX1LSN, BPX4LSN) — Prepare a server socket to queue incoming connection requests from clients
- socket or socketpair (BPX1SOC, BPX4SOC) — Create a socket or a pair of sockets
Characteristics and restrictions
- The bind with source address selection service is for IPv6 and IPv4-mapped IPv6 addresses only.
- Only TCP and UDP sockets are supported. RAW sockets are not supported.
- Port number is irrelevant for bind with source address selection service and will not be validated.
- Destination IP address of IN6ADDR_ANY is not supported. The bind with source address selection service will fail with EINVAL return code and JrInAddrAnyNotAllowed reason code.
Examples
For an example using this callable service, see BPX1BAS (bind with source address selection) example.