The INET6_IS_SRCADDR macro indicates whether an input
IPV6 socket address matches an address that is defined to the stack,
which conforms to one or more input IPV6_ADDR_PREFERENCES flags.
A client or server program can use the INET6_IS_SRCADDR
macro when it strictly requires the IP addresses that it uses to have
one or more specific attributes before allowing network activity.
Such an application would perform the following tasks:
- (Optional) Issue the SETSOCKOPT macro with the IPV6_ADDR_PREFERENCES
option to set the selection preferences of the source IP address for
the socket.
- Issue the BIND2ADDRSEL macro to bind a socket to a local IP address.
The BIND2ADDRSEL macro attempts to assign a local IP address that
matches the IPV6_ADDR_PREFERENCES flags that are specified with the
SETSOCKOPT macro, but does not guarantee that the local IP address
that it selects satisfies all preferences.
- Issue the GETSOCKNAME macro to obtain the local IP address bound
to the socket.
- Issue the INET6_IS_SRCADDR macro to verify whether the local IP
address has the correct attributes.
The macro returns true (value 1) when the IPv6 address
corresponds to a valid address in the node, and satisfies the given
IPV6_ADDR_PREFERENCES flag or flags. If the IPv6 address input value
does not correspond to any address in the node, or if the flags are
not valid preference flags, the macro returns a failure (value -1).
If the input address is a valid address on the node, but does not
satisfy the preference flags indicated, the function returns false
(value 0).
You can specify more than one IPV6_ADDR_PREFERENCES flag
on this macro. All flags must be satisfied for the result to be true.
Some IPV6_ADDR_PREFERENCES flags are contradictory. If you combine
contradictory flags on a single macro invocation, the result will
be false.
>>-EZASMI--TYPE=INET6_IS_SRCADDR--,NAME--=--+-address--+-------->
+-*indaddr-+
'-(reg)----'
>--,FLAGS--=--+-'IPV6_PREFER_SRC_HOME'---+---------------------->
+-'IPV6_PREFER_SRC_COA'----+
+-'IPV6_PREFER_SRC_PUBLIC'-+
+-'IPV6_PREFER_SRC_TMP'----+
+-'IPV6_PREFER_SRC_CGA'----+
+-'IPV6_PREFER_SRC_NONCGA'-+
+-address------------------+
+-*indaddr-----------------+
'-(reg)--------------------'
>--,ERRNO--=--+-address--+--,RETCODE--=--+-address--+----------->
+-*indaddr-+ +-*indaddr-+
'-(reg)----' '-(reg)----'
>--+---------------------------+--+-------------------------+--->
+-,ECB--=--+-address--+-----+ '-,ERROR--=--+-address--+-'
| +-*indaddr-+ | +-*indaddr-+
| '-(reg)----' | '-(reg)----'
'-,REQAREA--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
>--+------------------------+----------------------------------><
'-,TASK--=--+-address--+-'
+-*indaddr-+
'-(reg)----'
- Keyword
- Descriptions
- NAME
- An input parameter. An IPv6 socket address structure
describing the interface address to be tested. Include the SYS1.MACLIB(BPXYSOCK)
macro in your program to get the assembler mappings for the socket
address structure. The socket address structure mappings begin at
the SOCKADDR label. The AF_INET6 socket address structure fields start
at the SOCK_SIN6 label.
The IPv6 socket address structure specifies
the following fields:
- FAMILY
- A halfword binary field that specifies the IPv6 addressing family.
This value must be set to AF_INET6.
Tip: You can specify
an IPv4-mapped IPv6 address.
- PORT
- This field is ignored by the TYPE=INET6_IS_SRCADDR macro.
- FLOWINFO
- This field is ignored by the TYPE=INET6_IS_SRCADDR macro.
- IP-ADDRESS
- A 16-byte binary field that specifies the 128-bit IPv6 Internet
address, in network byte order.
- SCOPE-ID
- A fullword binary field that specifies the scope for an IPv6 address
as an interface index. This field must be nonzero if the address specified
in the IPv6-ADDRESS field is a link-local address and must be 0 for
any other scope.
- FLAGS
- An input parameter. The
FLAGS argument can be a literal value or a fullword binary field.
The following flags can be specified individually or in combination.
Flag name |
Binary value |
Description |
IPV6_PREFER_SRC_HOME |
X'00000001' |
Test whether the input IP address is a home
address.1 |
IPV6_PREFER_SRC_COA |
X'00000002' |
Test whether the input IP address is a care-of
address.2 |
IPV6_PREFER_SRC_TMP |
X'00000004' |
Test whether the input IP address is a temporary
address. |
IPV6_PREFER_SRC_PUBLIC |
X'00000008' |
Test whether the input IP address is a public
address. |
IPV6_PREFER_SRC_CGA |
X'00000010' |
Test whether the input IP address is cryptographically
generated.2 |
IPV6_PREFER_SRC_NONCGA |
X'00000020' |
Test whether the input IP address is not cryptographically
generated.1 |
Notes: - Any valid IP address that is known to the stack satisfies this
flag.
- z/OS® Communications
Server does not support this type of address. The macro always
returns FALSE if this flag is specified with a valid IP address that
is known to the stack.
|
Requirement: You must pass
a binary number to the macro to specify more than one preference flags.
Include the BPXYSOCK macro in your program to get the binary values
for the flags.
Tip: Some of these flags
are contradictory, for example:
- The flag IPV6_PREFER_SRC_HOME contradicts the flag IPV6_PREFER_SRC_COA.
- The flag IPV6_PREFER_SRC_CGA contradicts the flag IPV6_PREFER_SRC_NONCGA.
- The flag IPV6_PREFER_SRC_TMP contradicts the flags IPV6_PREFER_SRC_PUBLIC.
Result: If you specify contradictory
flags on the macro, the result is FALSE.
Example: MYFLAGS DC A(IPV6_PREFER_SRC_HOME+IPV6_PREFER_SRC_NONCGA) one way to combine flags
EZASMI TYPE=INET6_IS_SRCADDR,
NAME=name,
FLAGS=MYFLAGS
- ERRNO
- Output parameter. A fullword
binary field. If the RETCODE value is negative,
the ERRNO field contains a valid error number;
otherwise, ignore ERRNO.
See Socket call error return codes for information about ERRNO return codes.
- ECB or REQAREA
- Input parameter. This parameter is required if you use
APITYPE=3. This parameter points to a 104-byte field that contains
one of the following values:
- For ECB
- A 4-byte ECB that is 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 both ECB and REQAREA
- The last 100 bytes is a storage field that is used by the interface
to save the state information.
Requirement: 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.
- RETCODE
- Output parameter. A fullword
binary field that returns one of the following values:
- Value
- Description
- 0
- False. The IPv6 address corresponds to a valid address in the
node, but does not satisfy one or more of the input IPV6_ADDR_PREFERENCES
flags.
- 1
- True. The IPv6 address corresponds to a valid address in the node
and satisfies the given IPV6_ADDR_PREFERENCES flag or flags.
Tip: Any valid IPv6 address on a z/OS V1R12 node satisfies the following preference flags:
- IPV6_PREFER_SRC_HOME
- IPV6_PREFER_SRC_NONCGA
- -1
- The input IPV6 address does not correspond to an address on the
node or the input flags are not valid IPV6_PREFER_SRC_ADDR flags.
Check the ERRNO value for an error code.
- 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.