IPv6(7P)IPv6(7P)NAMEipv6 - Internet Protocol Version 6
SYNOPSIS
#include <sys/socket.h>
#include <netinet/in.h>
s = socket(AF_INET6, SOCK_RAW, proto);
DESCRIPTION
IP version 6 (also known as IPv6 and IPng) is the protocol designed to
eventually replace IP (also known as IPv4) as the Internet's network
layer protocol. The necessity of IPv6 comes primarily from the limited
address space of IPv4 in an exponentially expanding Internet, but IPv6
also supports other important functionality not present in IPv4.
This version of IRIX contains support for IPv6 functionality as described
by the following IETF documents:
Supported RFCs:
1981 Path MTU Discovery for IP version 6
1993 Transition Mechanisms for IPv6 Hosts and Routers
2080 RIPng for IPv6
2292 Advanced Sockets API for IPv6
2373 IP Version 6 Addressing Architecture
2460 Internet Protocol, Version 6 (IPv6) Specification
2461 Neighbor Discovery for IP Version 6 (IPv6)
2462 IPv6 Stateless Address Autoconfiguration
2463 Internet Control Message Protocol (ICMPv6)
2464 Transmission of IPv6 Packets over Ethernet Network
2472 IP Version 6 over PPP
2553 Basic Socket Interface Extensions for IPv6
2675 IPv6 Jumbograms
(Note: some of these RFCs are under revision and may be assigned
new numbers. This man page will refer to RFCs by their titles)
IRIX supports IPv6 using the Berkeley sockets system calls. The
differences between using sockets for IPv4 networking and IPv6 networking
are minimal. A new address family type, AF_INET6 is defined, so an IPv6
socket would be created using:
s = socket(AF_INET6, type, protocol);
The UDP and TCP transport layer protocols work in exactly the same way
over IPv6 as they do over IPv4. A new socket address structure,
sockaddr_in6 is defined to represent an IPv6 address. It is important to
note that since IPv6 addresses are 128 bits long, the generic sockaddr
structure cannot be used to reserve memory for an IPv6 address, since it
is too small. For this a new structure is defined, sockaddr_storage,
Page 1
IPv6(7P)IPv6(7P)
which, if used, ensures correct 64-bit alignment of IPv6 addresses. For
full details of the IPv6 API, the reader is referred to the "Basic Socket
Interface Extensions for IPv6" and "Advanced Sockets API for IPv6" RFCs
to which this implementation conforms.
SOCKET OPTIONS
The following socket options are supported for IPv6:
Options for use with [gs]etsockopt
IPV6_MULTICAST_IF set/get IPv6 multicast interface
IPV6_MULTICAST_HOPS set/get IPv6 multicast hoplimit
IPV6_MULTICAST_LOOP set/get IPv6 multicast loopback
IPV6_JOIN_GROUP (1) add an IPv6 group membership
IPV6_LEAVE_GROUP (1) drop an IPv6 group membership
IPV6_CHECKSUM calculate and insert checksum
ICMP6_FILTER icmp6 packet filtering
IPV6_UNICAST_HOPS unicast hop limit
IPV6_USE_MIN_MTU send packets at the minimum MTU
(1) these options can only be used with setsockopt()
Options to control the reception of ancillary data
IPV6_RECVPKTINFO receive packet information
IPV6_RECVHOPLIMIT hop limit received per packet
IPV6_RECVRTHDR routing header received
IPV6_RECVHOPOPTS hop-by-hop options received
IPV6_RECVDSTOPTS destination options received
IPV6_RECVTCLASS traffic class received
IPV6_RECVPATHMTU receive path MTU information
Options which be used with ancillary data or socket options
IPV6_PKTINFO set packet info (interface selection)
IPV6_HOPLIMIT (2) IPv6 hop limit
IPV6_NEXTHOP next hop address
IPV6_RTHDR routing header
IPV6_HOPOPTS hop by hop options
IPV6_DSTOPTS destination options
IPV6_RTHDRDSTOPTS per-route hop destination options
IPV6_TCLASS traffic class
(2) these options can only be used in ancillary data
IPV6_V6ONLY only bind INET6
IPV6_DONTFRAG disable IPv6 fragmentation
Page 2
IPv6(7P)IPv6(7P)
Many of these options are described in detail by the RFC "Advanced
Sockets API for IPv6". That document should be consulted for additional
background information.
IPV6_MULTICAST_IF, IPV6_MULTICAST_HOPS and IPV6_MULTICAST_LOOP control
IPv6 multicast. IPV6_MULTICAST_IF takes an integer argument which is the
index of the interface to be used to send outgoing multicast packets.
IPV6_MULTICAST_HOPS is the equivalent of IPV6_UNICAST_HOPS for multicast
and also takes an integer argument. IPV6_MULTICAST_LOOP switches local
loopback of outgoing multicast packets. If its integer argument is set
to 1 (which is the default), then copies are made of all outgoing
multicast packets on that socket and sent back into the IPv6 layer.
IPV6_JOIN_GROUP and IPV6_LEAVE_GROUP are used to leave and join multicast
groups and take an ipv6_mreq structure as an argument. The ipv6_mreq
structure is shown below:
struct ipv6_mreq {
struct in6_addr ipv6mr_multiaddr; /* IPv6 multicast addr */
unsigned int ipv6mr_interface; /* interface index */
};
The ipv6mr_interface may be given a value of zero, which indicates that
the kernel should choose the interface to be used. Otherwise it is the
index of the interface to be used to send and receive multicast packets
on that socket.
The IPV6_CHECKSUM checksum socket option is used when a raw socket is
opened and the protocol is something other than IPPROTO_ICMPV6. ICMPv6
checksums are mandatory and automatically calculated, even when using raw
sockets. The application should set this to have the kernel compute the
checksum and also verify the received checksum on input. Checksums will
incorporate the necessary IPv6 addresses in the pseudo header.
ICMP6_FILTER sets or gets the icmpv6 filtering options. The ICMP6_FILTER
series of macros defined in netinet/icmp6.h and the "Advanced Sockets API
for IPv6" RFC is available for manipulating the filter masks.
void ICMP6_FILTER_SETBLOCK(int, struct icmp6_filter *);
void ICMP6_FILTER_SETBLOCKALL(struct icmp6_filter *);
void ICMP6_FILTER_SETPASS(int, struct icmp6_filter *);
void ICMP6_FILTER_SETPASSALL(struct icmp6_filter *);
int ICMP6_FILTER_WILLBLOCK(int, const struct icmp6_filter *);
int ICMP6_FILTER_WILLPASS(int, const struct icmp6_filter *);
IPV6_UNICAST_HOPS sets the value initialized in the hop-limit field of
outgoing IPv6 packets. The following example sets the hop-limit of all
packets sent on the socket referenced by s to 10:
Page 3
IPv6(7P)IPv6(7P)
int hoplimit = 10;
if (setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS,
(char *) &hoplimit, sizeof(hoplimit)) == -1)
perror("setsockopt IPV6_UNICAST_HOPS");
Applications can use IPV6_USE_MIN_MTU to control the behavior of path MTU
discovery. There are three types of integer arguments:
-1: perform path MTU discovery for unicast destinations but do
not perform it for multicast destinations. Packets to
multicast destinations are therefore sent with the minimum
MTU.
0: always perform path MTU discovery.
1: always disable path MTU discovery and send packets at the
minimum MTU.
where the default is -1.
IPV6_RECVPKTINFO, IPV6_RECVHOPLIMIT, IPV6_RECVRTHDR, IPV6_RECVHOPOPTS,
IPV6_RECVDSTOPTS, IPV6_RECVPATHMTU and IPV6_RECVTCLASS are for requesting
reception of ancillary data objects associated with incoming packets from
the kernel. The ancillary object types are described in the "Advanced
Sockets API for IPv6" RFC. When these flags are set to 1, the stack will
send the relevant information to the application via the cmsghdr
mechanism.
int on = 1;
setsockopt(s, IPPROTO_IPV6, IPV6_RECVPKTINFO,
(char *)&on, sizeof(on));
Control of IPv6 and Extension Headers
To control IPv6 header and extension header content when sending, the
following socket option types can be used with setsockopt and with
ancillary data. A description of ancillary data follows this section.
opt level/ optname/ optval/
cmsg_level cmsg_type cmsg_data[]
------------------------------------------------
IPPROTO_IPV6 IPV6_PKTINFO in6_pktinfo structure
IPPROTO_IPV6 IPV6_HOPLIMIT (1) int
IPPROTO_IPV6 IPV6_NEXTHOP socket address structure
IPPROTO_IPV6 IPV6_RTHDR ip6_rthdr structure
IPPROTO_IPV6 IPV6_HOPOPTS ip6_hbh structure
IPPROTO_IPV6 IPV6_DSTOPTS ip6_dest structure
IPPROTO_IPV6 IPV6_RTHDRDSTOPTS ip6_dest structure
Page 4
IPv6(7P)IPv6(7P)
IPPROTO_IPV6 IPV6_TCLASS int
(1) for use as ancillary data items only
IPV6_PKTINFO can be used to specify the outgoing interface using the
in6_pktinfo structure's ipi6_addr and ipi6_ifindex fields. An application
can clear a "sticky" IPV6_PKTINFO option by doing a setsockopt() call
with ipi6_addr set to in6addr_any and ipi6_ifindex set to zero.
struct in6_pktinfo {
struct in6_addr ipi6_addr; /* src/dst IPv6 address */
unsigned int ipi6_ifindex; /* send/recv interface index */
};
IPV6_HOPLIMIT is ancillary only data and is used to set the IPv6 hop
limit. The first byte of cmsg_data[] should be the first byte of the
integer hop limit.
IPV6_NEXTHOP ancillary data specifies the next hop for the datagram as a
socket address structure. The next hop address must be an IPv6 address of
a neighbor of the sending host.
IPV6_RTHDR specifies a Routing header with the contents of the cmsg_type
member containing the implementation dependent data. The Advanced
Sockets API defines a set of universal functions which should be used to
manipulate the routing structure. See the RFC for more details on usage.
inet6_rth_space() return size required to hold header
inet6_rth_init() buffer initialization
inet6_rth_add() add an new address
inet6_rth_reverse() create new header using reverse path
inet6_rth_segments() returns number of addresses contained in
header
inet6_rth_getaddr() return pointer to address specified by index
IPV6_HOPOPTS is used to create a single or variable number of hop-by-hop
options. A set of utility functions is available to build and examine
hop-by-hop 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 options
header
inet6_opt_set_val() add one component of the option content to
the option
Three functions deal with a returned options header:
inet6_opt_next() extract the next option from the options
Page 5
IPv6(7P)IPv6(7P)
header
inet6_opt_find() extract an option of a specified type from the
header
inet6_opt_get_val() retrieve one component of the option content
To send an Destinations options header use the IPV6_DSTOPTS or
IPV6_RTHDRDSTOPTS options. The header specification can be done with
either ancillary data in a call to sendmsg() or using setsockopt(). To
precede the routing header, use IPV6_RTHDRDSTOPTS. IPV6_DSTOPTS places
the header after the routing header, if it exists.
IPV6_TCLASS specifes the traffic class of the packets. Specify the
control information as ancillary data using sendmsg() or setsockopt().
Using setsockopt to specify the options will affect all outgoing packets
on the socket until changed with new setsockopt call or overridden with
new ancillary data. In this case, they are treated as "sticky" options.
When using ancillary data to specify the options, it applies to that
particular outgoing datagram.
Using getsockopt with the flags above will retreive the current setting.
In the case of IPV6_NEXTHOP, only setsockopt() can be used.
IPV6_V6ONLY controls behavior of AF_INET6 wildcard listening socket. The
following example sets the option to 1:
int on = 1;
setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY, &on, sizeof(on));
If set to 1, AF_INET6 wildcard listening socket will accept IPv6 traffic
only. If set to 0, it will accept IPv4 traffic as well, as if it were
from an IPv4 mapped address like ::ffff:10.1.1.1. Note that if you set
it to 0, IPv4 access control gets much more complicated. For example,
even if you have no listening AF_INET listening socket on port X, you
will end up accepting IPv4 traffic by AF_INET6 listening socket on the
same port. The option affects TCP and UDP sockets only.
IPV6_DONTFRAG causes the kernel to not fragment the ipv6 packet. The
caller must assure that total size of the packet fits within IPv6 packet
size contraints, else the call will return with an error of EMSGSIZE.
TCP sticky options
For TCP connections it is not usual to use the sendmsg system call to
send data. If the application needs to set any of the above mentioned
IPv6 options for all packets of a TCP connection, it can use setsockopt
to specify the desired options. For example,
setsockopt(fd, IPPROTO_IPV6, IPV6_HOPLIMIT, &buf, len);
where buf is a byte array containing one or more ancillary data objects
(as described below) and len is the total length of all the objects
Page 6
IPv6(7P)IPv6(7P)
passed in. When the TCP protocol sends a packet, it behaves as if the
user had specifed the options for that packet by passing the ancillary
data objects to sendmsg().
Ancillary data objects
Ancillary data objects are passed to sendmsg() and and received from
recvmsg() in a cmsghdr structure as header, as shown below:
struct cmsghdr {
size_t cmsg_len; /* #bytes, including this header */
int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */
/* followed by u_char cmsg_data[]; */
};
Application source should include <sys/socket.h> to use this structure.
cmsg_len is the total length of the object, including the cmsghdr header,
but excluding any bytes required for alignment padding at the end of the
data object (see below). cmsg_level is the level of the ancillary data
object, which is IPPROTO_IPV6 for IPv6 and cmsg_type is the type of
message being passed, as described above. This header is followed by the
ancillary data object itself, as described above. When more than one
message is passed to a function, it may be necessary for padding bytes to
be inserted between the end of one ancillary data object and the start of
the next. Since the padding requirements are architecture-dependent,
several macros are provided for manipulating these objects: CMSG_DATA() ,
CMSG_NXTHDR() , and CMSG_FIRSTHDR() These are described in the "Advanced
Sockets API for IPv6" RFC
SEE ALSOgetsockopt(2), setsockopt(2), send(2), recv(2), recvmsg(2), intro(3),
icmp(7P), inet(7F), route(7F), route6d(7), netstat(1), ifconfig(1),
getaddrinfo(3C),
IRIX Network Programming Guide
"Basic Socket Interface Extensions for IPv6" RFC
"Advanced Sockets API for IPv6" RFC
Page 7