getsockname or getpeername (BPX1GNM, BPX4GNM) - Get the name of a socket or connected peer

Function

The getsockname or getpeername callable service obtains the name of a socket or the name of a peer connected to 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 (BPX1GNM):	31-bit task or SRB mode
AMODE (BPX4GNM):	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.

AMODE 64 callers use BPX4GNM with the same parameters.

Format

CALL BPX1GNM,(Socket_descriptor,
              Operation,
              Sockaddr_length,
              Sockaddr,
              Return_value,
              Return_code,
              Reason_code)

Parameters

Socket_descriptor

Supplied parameter

Type:: Integer
Length:: Fullword

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

Operation

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the operation option. The value of this field determines whether the service to be performed is getsockname or getpeername. See BPXYSOCK — Map SOCKADDR structure and constants for valid Operation values.

Sockaddr_length

Supplied and returned parameter

Type:: Integer
Length:: Fullword

The name of a field that contains the length of Sockaddr. On return, this field specifies the size required to represent the address of the connecting socket. If this value is larger than the size supplied on input, the information contained in Sockaddr is truncated to the length supplied on input. The size of this field must be less than 4096 bytes (4KB) in length. The size of the buffer that is specified must be the maximum length that the sockaddr could be on output.

Sockaddr

Supplied and returned parameter

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

The name of a field in which the socket name or peer name is to be returned. See BPXYSOCK — Map SOCKADDR structure and constants for valid Operation values.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the getsockname or getpeername 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 getsockname or getpeername service stores the return code. The getsockname or getpeername service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The getsockname or getpeername service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EBADF	The socket descriptor is incorrect. The following reason codes can accompany the return code: JRFileDesNotInUse, JRFileNotOpen.
EINVAL	The length that is specified by the sockaddr_length operand is too small to allow the name to be returned. The following reason code can accompany the return code: JRSocketCallParmError.
ENOBUFS	Unable to obtain a buffer. Consult Reason_code to determine the exact reason the error occurred. The following reason code can accompany the return code: JROutofSocketCells.
ENOTCONN	getpeername() was specified and the socket is not connected.
ENOTSOCK	Socket_descriptor does not refer to a valid socket descriptor. The following reason code can accompany the return code: JRMustBeSocket.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

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

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 getsockname or getpeername service.

Examples

For an example using this callable service, see BPX1GNM (getpeername or getsockname) example.