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.
The following requirements apply to this call:
Authorization: |
Supervisor state or problem state, any PSW key. |
Dispatchable unit mode: |
Task. |
Cross memory mode: |
PASN = HASN. |
Amode: |
31-bit or 24-bit.
|
ASC mode: |
Primary address space control (ASC) mode. |
Interrupt status: |
Enabled for interrupts. |
Locks: |
Unlocked. |
Control parameters: |
All parameters must be addressable by the caller
and in the primary address space. |
>>-EZASMI--TYPE=GETSOCKNAME--,S--=--+-number---+---------------->
+-address--+
+-*indaddr-+
'-(reg)----'
>--,NAME--=--+-address--+--,ERRNO--=--+-address--+-------------->
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
>--,RETCODE--=--+-address--+--+---------------------------+----->
+-*indaddr-+ +-,ECB--=--+-address--+-----+
'-(reg)----' | +-*indaddr-+ |
| '-(reg)----' |
'-,REQAREA--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
>--+-------------------------+--+------------------------+-----><
'-,ERROR--=--+-address--+-' '-,TASK--=--+-address--+-'
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
- Keyword
- Description
- 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 specified on completion of the call with the socket name. Include
the SYS1.MACLIB(BPXYSOCK) 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 must specify the following fields:
- Field
- Description
- FAMILY
- Output parameter. A halfword binary field containing the IPv4
addressing family. The value for IPv4 socket descriptor (S parameter)
is a decimal 2, indicating AF_INET.
- PORT
- Output parameter. A halfword binary field set to the port number
bound to this socket. If the socket is not bound, a 0 is returned.
- IPv4-ADDRESS
- Output parameter. A fullword binary field set to the 32-bit IPv4
Internet address of the local host machine.
- RESERVED
- Output parameter. Specifies 8 bytes of binary zeros. This field
is required, but not used.
The IPv6 socket structure must specify the following
fields:
- Field
- Description
- NAMELEN
- Output parameter. A 1-byte binary field specifying the length
of this IPv6 socket address structure. Any value specified by the
use of this field is ignored when processed as input and the field
is set to 0 when processed as output.
- FAMILY
- Output parameter. A 1-byte binary field specifying the IPv6 addressing
family. The value for IPv6 socket descriptor (S parameter) is a decimal
19, indicating AF_INET6.
- PORT
- Output parameter. A halfword binary field set to the port number
bound to this socket. If the socket is not bound, a 0 is returned.
- FLOW-INFO
- Output parameter. A fullword binary field specifying the traffic
class and flow label. This value of this field is undefined.
- IPv6-ADDRESS
- Output parameter. A 16-byte binary field that is set to the 128-bit
IPv6 Internet address, in network byte order, of the local host 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 Socket call error return codes for information about ERRNO return
codes.
- RETCODE
- Output parameter. A fullword
binary field that returns one of the following values:
- Value
- Description
- 0
- Successful call.
- -1
- An error occurred.
- ECB or REQAREA
- Input parameter. This parameter is required if you are
using APITYPE=3. It points to a 104-byte field containing:
- For ECB
- A 4-byte ECB posted by TCP/IP when the
macro completes.
- For REQAREA
- A 4-byte user token (set by you) that is presented to your exit
when the response to this function request is complete.
- For ECB/REQAREA
- The last 100 bytes is a 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, or the asynchronous exit has been driven.
- ERROR
- Input parameter. The location in your program to receive
control when the application programming interface (API) processing
module cannot be loaded.
- TASK
- Input parameter. The location of the task storage area in your
program.