Options to control the sending of packets

Some of these options add extension headers to outbound packets. z/OS® TCP/IP allows the application to specify a maximum of 512 bytes of extension headers for an outbound packet.

Use the following options to control the sending of packets:

IPV6_PKTINFO (used with UDP and RAW applications)

The IPV6_PKTINFO option enables the application to provide the following pieces of information:

The source IP address for an outgoing packet
The outgoing interface for a packet

The option value contains a 16-byte IPv6 address and a 4-byte interface index. An application can provide a nonzero value for one or both pieces of information.

To perform this operation, an application must meet one of the following criteria:

The application must be APF-authorized.
The application must have superuser authority.
The SERVAUTH resource EZB.SOCKOPT.sysname.tcpname.IPV6_PKTINFO must be defined and the application must at least have READ access to it.

This option can be enabled or disabled for the following cases:

A socket with a setsockopt()
A single send operation with ancillary data on the sendmsg()

To disable the option, specify both the IPv6 address and the interface index as 0 in the option value.

A getsockopt() with this option returns the value set by setsockopt(). If a setsockopt() has not been done, a value of 0 is returned.

See Options for setting the source address for a discussion of the interaction of socket options and ancillary data for the setting of the source address. See Options for specifying the outgoing interface for a discussion of the interaction of socket options and ancillary data for determining the outgoing interface.

IPV6_HOPLIMIT (used with UDP and RAW applications)

The IPv6 header contains a hop limit field that controls the number of hops over which a datagram can be sent before being discarded. This is similar to the TTL field in the IPv4 header. The IPV6_HOPLIMIT option can be used to set the hop limit value for an outgoing packet. The option value should be between 0 and 255 inclusive. A value of -1 causes the TCP/IP protocol stack default to be used.

To perform this operation, an application must meet one of the following criteria:

The application must be APF-authorized.
The application must have superuser authority.
The SERVAUTH resource EZB.SOCKOPT.sysname.tcpname.IPV6_HOPLIMIT must be defined and the application must at least have READ access to it.

The IPV6_UNICAST_HOPS socket option and the IPV6_MULTICAST_HOPS socket option are available to set a hop limit value also. See Hop limit options for information about the interaction of IPV6_UNICAST_HOPS, IPV6_MULTICAST_HOPS and IPV6_HOPLIMIT.

IPV6_NEXTHOP (used with UDP and RAW applications)

The IPV6_NEXTHOP option enables the application to specify the next hop address for an outgoing packet. The option value contains a sockaddr_in6 socket address structure and must contain an IPv6 address.

Restriction: This option does not support IPv4-mapped IPv6 addresses.

To perform this operation, an application must meet one of the following criteria:

The application must be APF-authorized.
The application must have superuser authority.
The SERVAUTH resource EZB.SOCKOPT.sysname.tcpname.IPV6_NEXTHOP must be defined and the application must at least have READ access to it.

This option can be enabled or disabled for the following cases:

A socket with a setsockopt()
A single send operation with ancillary data on the sendmsg()

Restriction: IPV6_NEXTHOP is valid only for unicast destinations.

An option value with the optlen value of 0 disables IPV6_NEXTHOP. This option does not have any meaning for multicast destinations and is ignored for multicast.

A getsockopt() with this option returns the value set by a setsockopt(). If a setsockopt() has not been performed, then getsockopt() returns the value 0 in optlen.

See Options for specifying the outgoing interface for information about the interaction of socket options and ancillary data for determining the outgoing interface.

Tips:

If you use this socket option in a Common INET environment, establish affinity to the appropriate stack to ensure predictable results; some stacks might not have a route to the specified next hop address.
If you specify a link-local address as the next hop address, specify the outgoing interface either on IPV6_PKTINFO or by using the scope portion of the socket address structure.

Rule: The next hop address cannot be a multicast address and must be a neighbor (for example, the stack must have a direct route to the next hop address).

IPV6_RTHDR (used with UDP and RAW applications)

The IPV6_RTHDR option enables the application to specify an IPv6 routing header (as an extension header) for an outgoing packet.

Restriction: Because the type 0 routing header is deprecated in z/OS Communications Server V1R11, no routing header type is currently supported. The IPV6_RTHDR option is accepted as a valid option, but all option type values are rejected as incorrect values.

To perform this operation, an application must meet one of the following criteria:

The application must be APF-authorized.
The application must have superuser authority.
The SERVAUTH resource EZB.SOCKOPT.sysname.tcpname.IPV6_RTHDR must be defined and the application must at least have READ access to it.

This option can be enabled or disabled for the following cases:

A socket with a setsockopt()
A single send operation with ancillary data on the sendmsg()

A getsockopt() with this option returns the value set by a setsockopt(). If a setsockopt() has not been performed, then getsockopt() returns a value of 0 in optlen.

Tip: If you use this socket option in a Common INET environment, establish affinity to the appropriate stack to ensure predictable results; some stacks might not have a path to the first destination that is specified in the routing header.

A z/OS UNIX C/C++ application can use the following utilities to build routing headers:

inet6_rth_space() - return number of bytes required for routing header
inet6_rth_init() - initialize buffer data for routing header
inet6_rth_add() - add one IPv6 address to the routing header

See z/OS XL C/C++ Runtime Library Reference for a description of these utilities.

A z/OS UNIX Assembler Callable Services application needs to build the routing headers explicitly. See z/OS UNIX System Services Programming: Assembler Callable Services Reference for information about z/OS UNIX Assembler Callable Services and the data structures defined in the BPXYSOCK macro.

IPV6_DSTOPTS (used with UDP and RAW applications)

The IPV6_DSTOPTS option enables the application to specify destination options that get examined by the host at the final destination.

The IPV6_DSTOPTS option can be used to set a destination options header (as an extension header) for an outgoing packet. The option value contains a destination options header.

To perform this operation, an application must meet one of the following criteria:

The application must be APF-authorized.
The application must have superuser authority.
The SERVAUTH resource EZB.SOCKOPT.sysname.tcpname.IPV6_DSTOPTS must be defined and the application must at least have READ access to it.

This option can be enabled or disabled for the following cases:

A socket with a setsockopt()
A single send operation with ancillary data on the sendmsg()

A getsockopt() with this option returns the value set by a setsockopt(). If a setsockopt() has not been performed, then getsockopt() returns a value of 0 in optlen.

A z/OS UNIX C/C++ application can use the following utilities to build the following destination options headers:

inet6_opt_init() - initialize buffer data for options header
inet6_opt_append() - add one TLV option to the options header
inet6_opt_finish() - finish adding TLV options to the option header
inet6_opt_set_val() - add one component of the option content to the option

See z/OS XL C/C++ Runtime Library Reference for a description of these utilities.

A z/OS UNIX Assembler Callable Services application needs to build the options headers explicitly. See z/OS UNIX System Services Programming: Assembler Callable Services Reference for information about z/OS UNIX Assembler Callable Services and the data structures defined in the BPXYSOCK macro.

IPV6_RTHDRDSTOPTS (used with UDP and RAW applications)

The IPV6_RTHDRDSTOPTS option enables the application to specify destination options that get examined by every IP host that appears in the routing header.

The IPV6_RTHDRDSTOPTS option can be used to set a destination options header (as an extension header) for an outgoing packet. The option value contains a destination options header. This option is ignored if the application does not also use the IPV6_RTHDR option to specify a routing header.

To perform this operation, an application must meet one of the following criteria:

The application must be APF-authorized.
The application must have superuser authority.
The SERVAUTH resource EZB.SOCKOPT.sysname.tcpname.IPV6_RTHDRDSTOPTS must be defined and the application must at least have READ access to it.

This option can be enabled or disabled for the following cases:

A socket with a setsockopt()
A single send operation with ancillary data on the sendmsg()

A getsockopt() with this option returns the value set by a setsockopt(). If a setsockopt() has not been performed, then getsockopt() returns a value of 0 in optlen.

A z/OS UNIX C/C++ application can use the following utilities to build destination options headers:

inet6_opt_init() - initialize buffer data for options header
inet6_opt_append() - add one TLV option to the options header
inet6_opt_finish() - finish adding TLV options to the option header
inet6_opt_set_val() - add one component of the option content to the option

See z/OS XL C/C++ Runtime Library Reference for a description of these utilities.

IPV6_TCLASS (used with TCP, UDP and RAW applications)

The IPv6 header contains a traffic class field that can be used to identify and distinguish between different classes or priorities of IPv6 packets. This is similar to the type of service (ToS) field in the IPv4 header. The IPV6_TCLASS option can be used to set the traffic class value for an outgoing packet. However, if a QoS policy that specifies a traffic class for the packet is also in effect, then the stack ignores the value specified with the IPV6_TCLASS option and uses the value specified by the QoS policy.

To perform this operation, an application must meet one of the following criteria:

The application must be APF-authorized.
The application must have superuser authority.
The SERVAUTH resource EZB.SOCKOPT.sysname.tcpname.IPV6_TCLASS must be defined and the application must at least have READ access to it.

This socket option is also valid for an AF_INET6 socket that is using IPv4-mapped IPv6 addresses.

This option can be enabled or disabled for a socket with a setsockopt(). For UDP and RAW, this option can be enabled or disabled for a single send operation with ancillary data on the sendmsg().

The option value is in the range 0 – 255. The value -1 causes the TCP/IP protocol stack to use the traffic class value that the policy specifies (if any) or the default value 0.

A getsockopt() with this option returns the value set by a setsockopt(). If a setsockopt() has not been performed, then the stack returns the traffic class value specified by policy (if any) or the default value 0.