GETSOCKNAME

The GETSOCKNAME macro stores the name of the socket into the structure pointed to by NAME and returns the address to the socket that has been bound.

If the socket is not bound to an address, the macro returns with the FAMILY field completed and the rest of the structure set to zeros.

Stream sockets are not assigned a name until after a successful call to BIND, CONNECT, or ACCEPT.

Use the GETSOCKNAME macro to determine the port assigned to a socket after that socket has been implicitly bound to a port. If an application calls CONNECT without previously calling BIND, the CONNECT macro completes the binding necessary by assigning a port to the socket. You can determine the port assigned to the socket by issuing GETSOCKNAME.

Important: IPv6 support is not available with TCP/IP for z/VSE. Any reference to IPv6 addresses or address structures do not apply, if this program is used.

Format

Parameters

S

Input parameter. A value, or the address of a halfword binary number specifying the socket descriptor.

NAME

Initially, the application provides a pointer to the IPv4 or IPv6 socket address structure, which is filled in on completion of the call with the socket name. Include the PRD1.MACLIB(EZBREHST) macro to get the assembler mappings for the socket address structure. The socket address structure mappings begin at the SOCKADDR label. The AF_INET socket address structure fields start at the SOCK_SIN label. The AF_INET6 socket address structure fields start at the SOCK_SIN6 label.

The IPv4 socket address structure contains the following fields:

FAMILY: A halfword binary field specifying the IPv4 addressing family. For TCP/IP the value is a decimal 2, indicating AF_INET.
PORT: A halfword binary field specifying the port number bound to this socket. If the socket is not bound, a zero is returned.
IPv4-ADDRESS: A fullword binary field specifying the 32-bit IPv4 Internet address.
RESERVED: Specifies eight bytes of binary zeros. This field is required, but is not used.

The IPv6 socket address structure contains the following fields:

NAMELEN: A 1-byte binary field that specifies the length of the IPv6 socket address structure. Any value specified by the use of this field is ignored, if processed as input. The field is set to 0, if processed as output.
FAMILY: A 1-byte binary field that specifies the IPv6 addressing family. For TCP/IP the value is a decimal 19, indicating AF_INET6.
PORT: A halfword binary field specifying the port number bound to this socket. If the socket is not bound, a zero is returned.
FLOW-INFO: A fullword binary field specifying the traffic class and flow label. This value of this field is undefined.
IPv6-ADDRESS: A 16-byte binary field that is set to the 128-bit IPv6 Internet address, in network byte order, of the client machine.
SCOPE-ID: A fullword binary field which identifies a set of interfaces as appropriate for the scope of the address carried in the IPv6-ADDRESS field. For a link scope IPv6-ADDRESS, SCOPE-ID contains the link index for the IPv6-ADDRESS. For all other address scopes, SCOPE-ID is undefined.

ERRNO

Output parameter. A fullword binary field. If RETCODE is negative, this field contains an error number. See ERRNO Values for information about ERRNO return codes.

RETCODE

Output parameter. A fullword binary field that returns one of the following:

Value: Description
0: Successful call
-1: Check ERRNO for an error code

ECB

Input parameter. It points to a 160-byte field containing:

A four-byte ECB posted by TCP/IP when the macro completes.
A 156-byte storage field used by the interface to save the state information.

Note: This storage must not be modified until the macro function has completed and the ECB has been posted.

ERROR

Input parameter. The location in your program to receive control, if the application programming interface (API) processing module cannot be loaded.

TASK

Input parameter. The location of the task storage area in your program.