draft-ietf-ipngwg-rfc2553bis-05.txt   draft-ietf-ipngwg-rfc2553bis-06.txt 
IPNG Working Group R.E. Gilligan IPNG Working Group R.E. Gilligan
INTERNET-DRAFT: draft-ietf-ipngwg-rfc2553bis-05.txt Cache Flow INTERNET-DRAFT: draft-ietf-ipngwg-rfc2553bis-06.txt Cache Flow
Obsoletes RFC 2553 S. Thomson Obsoletes RFC 2553 S. Thomson
Cisco Cisco
J. Bound J. Bound
J. McCann J. McCann
Compaq Hewlett-Packard
W. R. Stevens W. R. Stevens
February 2002
Basic Socket Interface Extensions for IPv6 Basic Socket Interface Extensions for IPv6
<draft-ietf-ipngwg-rfc2553bis-05.txt> <draft-ietf-ipngwg-rfc2553bis-06.txt>
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
This document is a submission by the Internet Protocol IPv6 Working This document is a submission by the Internet Protocol IPv6 Working
Group of the Internet Engineering Task Force (IETF). Comments should Group of the Internet Engineering Task Force (IETF). Comments should
be submitted to the ipng@sunroof.eng.sun.com mailing list. be submitted to the ipng@sunroof.eng.sun.com mailing list.
skipping to change at page 1, line 46 skipping to change at page 1, line 44
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
Abstract Abstract
The de facto standard application program interface (API) for TCP/IP The de facto standard application program interface (API) for TCP/IP
applications is the "sockets" interface. Although this API was applications is the "sockets" interface. Although this API was
developed for Unix in the early 1980s it has also been implemented on a developed for Unix in the early 1980s it has also been implemented on
wide variety of non-Unix systems. TCP/IP applications written using the a wide variety of non-Unix systems. TCP/IP applications written
sockets API have in the past enjoyed a high degree of portability and we using the sockets API have in the past enjoyed a high degree of
would like the same portability with IPv6 applications. But changes are portability and we would like the same portability with IPv6
required to the sockets API to support IPv6 and this memo describes applications. But changes are required to the sockets API to support
these changes. These include a new socket address structure to carry IPv6 and this memo describes these changes. These include a new
IPv6 addresses, new address conversion functions, and some new socket socket address structure to carry IPv6 addresses, new address
options. These extensions are designed to provide access to the basic conversion functions, and some new socket options. These extensions
IPv6 features required by TCP and UDP applications, including are designed to provide access to the basic IPv6 features required by
multicasting, while introducing a minimum of change into the system and TCP and UDP applications, including multicasting, while introducing a
minimum of change into the system and providing complete
providing complete compatibility for existing IPv4 applications. compatibility for existing IPv4 applications. Additional extensions
Additional extensions for advanced IPv6 features (raw sockets and access for advanced IPv6 features (raw sockets and access to the IPv6
to the IPv6 extension headers) are defined in another document [4]. extension headers) are defined in another document [4].
Table of Contents: Table of Contents:
1. Introduction.................................................4 1. Introduction.................................................3
2. Design Considerations........................................4 2. Design Considerations........................................3
2.1 What Needs to be Changed....................................4 2.1 What Needs to be Changed....................................4
2.2 Data Types..................................................6 2.2 Data Types..................................................5
2.3 Headers.....................................................6 2.3 Headers.....................................................5
2.4 Structures...................................................6 2.4 Structures..................................................5
3. Socket Interface.............................................6 3. Socket Interface.............................................5
3.1 IPv6 Address Family and Protocol Family.....................6 3.1 IPv6 Address Family and Protocol Family.....................6
3.2 IPv6 Address Structure......................................6 3.2 IPv6 Address Structure......................................6
3.3 Socket Address Structure for 4.3BSD-Based Systems...........7 3.3 Socket Address Structure for 4.3BSD-Based Systems...........6
3.4 Socket Address Structure for 4.4BSD-Based Systems...........8 3.4 Socket Address Structure for 4.4BSD-Based Systems...........7
3.5 The Socket Functions........................................9 3.5 The Socket Functions........................................8
3.6 Compatibility with IPv4 Applications.......................10 3.6 Compatibility with IPv4 Applications........................9
3.7 Compatibility with IPv4 Nodes..............................10 3.7 Compatibility with IPv4 Nodes...............................9
3.8 IPv6 Wildcard Address......................................10 3.8 IPv6 Wildcard Address......................................10
3.9 IPv6 Loopback Address......................................11 3.9 IPv6 Loopback Address......................................11
3.10 Portability Additions.....................................12 3.10 Portability Additions.....................................11
4. Interface Identification....................................14 4. Interface Identification....................................13
4.1 Name-to-Index..............................................14 4.1 Name-to-Index..............................................14
4.2 Index-to-Name..............................................14 4.2 Index-to-Name..............................................14
4.3 Return All Interface Names and Indexes......................15 4.3 Return All Interface Names and Indexes.....................14
4.4 Free Memory................................................15 4.4 Free Memory................................................15
5. Socket Options..............................................16 5. Socket Options..............................................15
5.1 Unicast Hop Limit..........................................16 5.1 Unicast Hop Limit..........................................15
5.2 Sending and Receiving Multicast Packets....................17 5.2 Sending and Receiving Multicast Packets....................16
5.3 IPV6_V6ONLY option for AF_INET6 Sockets....................18 5.3 IPV6_V6ONLY option for AF_INET6 Sockets....................18
6. Library Functions...........................................19 6. Library Functions...........................................18
6.1 Protocol-Independent Nodename and Service Name Translation.19 6.1 Protocol-Independent Nodename and Service Name Translation.19
6.2 Socket Address Structure to Nodename and Service Name......24 6.2 Socket Address Structure to Node Name and Service Name.....23
6.3 Address Conversion Functions...............................26 6.3 Address Conversion Functions...............................25
6.4 Address Testing Macros.....................................27 6.4 Address Testing Macros.....................................26
7. Summary of New Definitions..................................28 7. Summary of New Definitions..................................27
8. Security Considerations.....................................29 8. Security Considerations.....................................29
9. Year 2000 Considerations....................................29 Changes from RFC 2553..........................................29
Changes made to rfc2553bis-04 to rfc2553bis-05.................29 Acknowledgments................................................29
Changes made to rfc2553bis-03 to rfc2553bis-04.................30 References.....................................................30
Changes made to rfc2553bis-02 to rfc2553bis-03.................30 Authors' Addresses.............................................31
Changes made to rfc2553bis-01 to rfc2553bis-02.................30
Changes made to rfc2553bis-00 to rfc2553bis-01.................30
Changes made rfc2553 to rfc2553bis-00:.........................30
Acknowledgments................................................31
References.....................................................31
Authors' Addresses.............................................32
1. Introduction 1. Introduction
While IPv4 addresses are 32 bits long, IPv6 interfaces are identified by While IPv4 addresses are 32 bits long, IPv6 addresses are 128 bits long.
128-bit addresses. The socket interface makes the size of an IP address The socket interface makes the size of an IP address quite visible to an
quite visible to an application; virtually all TCP/IP applications for application; virtually all TCP/IP applications for BSD-based systems
BSD-based systems have knowledge of the size of an IP address. Those have knowledge of the size of an IP address. Those parts of the API
parts of the API that expose the addresses must be changed to that expose the addresses must be changed to accommodate the larger IPv6
accommodate the larger IPv6 address size. IPv6 also introduces new address size. IPv6 also introduces new features (e.g., traffic class
features (e.g., traffic class and flowlabel), some of which must be made and flowlabel), some of which must be made visible to applications via
visible to applications via the API. This memo defines a set of the API. This memo defines a set of extensions to the socket interface
extensions to the socket interface to support the larger address size to support the larger address size and new features of IPv6. It defines
and new features of IPv6. "basic" extensions that are of use to a broad range of applications. A
companion document, the "advanced" API [4], covers extensions that are
of use to more specialized applications, examples of which include
routing daemons, and the "ping" and "traceroute" utilities.
The development of this API was started in 1994 in the IETF IPng working
group. The API has evolved over the years, published first in RFC 2133,
then again in RFC 2553, and reaching its final form in this document.
As the API matured and stabilized, it was incorporated into the Open
Group's Networking Services (XNS) specification, issue 5.2, which was
subsequently incorporated into a joint Open Group/IEEE/ISO standard [3].
Effort has been made to ensure that this document and [3] contain the
same information with regard to the API definitions. However, the
reader should note that this document is for informational purposes
only, and that the official standard specification of the sockets API is
[3].
It is expected that any future standardization work on this API would be
done by the Open Group Base Working Group [6].
It should also be noted that this document describes only those portions
of the API needed for IPv4 and IPv6 communications. Other potential
uses of the API, for example the use of getaddrinfo() and getnameinfo()
with the AF_UNIX address family, are beyond the scope of this document.
2. Design Considerations 2. Design Considerations
There are a number of important considerations in designing changes to There are a number of important considerations in designing changes to
this well-worn API: this well-worn API:
- The API changes should provide both source and binary - The API changes should provide both source and binary
compatibility for programs written to the original API. That compatibility for programs written to the original API. That
is, existing program binaries should continue to operate when is, existing program binaries should continue to operate when
run on a system supporting the new API. In addition, existing run on a system supporting the new API. In addition, existing
applications that are re-compiled and run on a system supporting applications that are re-compiled and run on a system supporting
the new API should continue to operate. Simply put, the API the new API should continue to operate. Simply put, the API
changes for IPv6 should not break existing programs. An additional changes for IPv6 should not break existing programs. An additional
mechanism for implementations to verify this is to verify the new mechanism for implementations to verify this is to verify the new
symbols are protected by Feature Test Macros as described in IEEE Std symbols are protected by Feature Test Macros as described in [3].
1003.1-200x. (Such Feature Test Macros are not defined by this RFC.) (Such Feature Test Macros are not defined by this RFC.)
- The changes to the API should be as small as possible in order - The changes to the API should be as small as possible in order
to simplify the task of converting existing IPv4 applications to to simplify the task of converting existing IPv4 applications to
IPv6. IPv6.
- Where possible, applications should be able to use this - Where possible, applications should be able to use this
API to interoperate with both IPv6 and IPv4 hosts. Applications API to interoperate with both IPv6 and IPv4 hosts. Applications
should not need to know which type of host they are should not need to know which type of host they are
communicating with. communicating with.
skipping to change at page 5, line 37 skipping to change at page 4, line 59
information (address family and port number) that is needed. So a new information (address family and port number) that is needed. So a new
address data structure must be defined for IPv6. address data structure must be defined for IPv6.
IPv6 addresses are scoped [2] so they could be link-local, site, IPv6 addresses are scoped [2] so they could be link-local, site,
organization, global, or other scopes at this time undefined. To organization, global, or other scopes at this time undefined. To
support applications that want to be able to identify a set of support applications that want to be able to identify a set of
interfaces for a specific scope, the IPv6 sockaddr_in structure must interfaces for a specific scope, the IPv6 sockaddr_in structure must
support a field that can be used by an implementation to identify a set support a field that can be used by an implementation to identify a set
of interfaces identifying the scope for an IPv6 address. of interfaces identifying the scope for an IPv6 address.
The name-to-address translation functions in the socket interface are The IPv4 name-to-address translation functions in the socket interface
gethostbyname() and gethostbyaddr(). These are left as is and new
functions are defined to support IPv4 and IPv6. The new API is based on
the IEEE Std 1003.1-200x draft [3] and specifies a new nodename-to-
address translation function which is protocol independent. This
function can also be used with IPv4 and IPv6.
The address conversion functions -- inet_ntoa() and inet_addr() -- are gethostbyname() and gethostbyaddr(). These are left as is, and new
functions are defined which support both IPv4 and IPv6.
The IPv4 address conversion functions -- inet_ntoa() and inet_addr() --
convert IPv4 addresses between binary and printable form. These convert IPv4 addresses between binary and printable form. These
functions are quite specific to 32-bit IPv4 addresses. We have designed functions are quite specific to 32-bit IPv4 addresses. We have designed
two analogous functions that convert both IPv4 and IPv6 addresses, and two analogous functions that convert both IPv4 and IPv6 addresses, and
carry an address type parameter so that they can be extended to other carry an address type parameter so that they can be extended to other
protocol families as well. protocol families as well.
Finally, a few miscellaneous features are needed to support IPv6. New Finally, a few miscellaneous features are needed to support IPv6. New
interfaces are needed to support the IPv6 traffic class, flow label, and interfaces are needed to support the IPv6 traffic class, flow label, and
hop limit header fields. New socket options are needed to control the hop limit header fields. New socket options are needed to control the
sending and receiving of IPv6 multicast packets. sending and receiving of IPv6 multicast packets.
The socket interface will be enhanced in the future to provide access to The socket interface will be enhanced in the future to provide access to
other IPv6 features. These extensions are described in [4]. other IPv6 features. These extensions are described in [4].
2.2 Data Types 2.2 Data Types
The data types of the structure elements given in this memo are intended The data types of the structure elements given in this memo are intended
to track the relevant standards. uintN_t means an unsigned integer of to track the relevant standards. uintN_t means an unsigned integer of
exactly N bits (e.g., uint16_t). exactly N bits (e.g., uint16_t). The sa_family_t and in_port_t types
are defined in [3].
2.3 Headers 2.3 Headers
When function prototypes and structures are shown we show the headers When function prototypes and structures are shown we show the headers
that must be #included to cause that item to be defined. that must be #included to cause that item to be defined.
2.4 Structures 2.4 Structures
When structures are described the members shown are the ones that must When structures are described the members shown are the ones that must
appear in an implementation. Additional, nonstandard members may also appear in an implementation. Additional, nonstandard members may also
be defined by an implementation. As an additional precaution be defined by an implementation. As an additional precaution
nonstandard members could be verified by Feature Test Macros as nonstandard members could be verified by Feature Test Macros as
described in IEEE Std 1003.1-200x. (Such Feature Test Macros are not described in [3]. (Such Feature Test Macros are not defined by this
defined by this RFC.) RFC.)
The ordering shown for the members of a structure is the recommended The ordering shown for the members of a structure is the recommended
ordering, given alignment considerations of multibyte members, but an ordering, given alignment considerations of multibyte members, but an
implementation may order the members differently. implementation may order the members differently.
3. Socket Interface 3. Socket Interface
This section specifies the socket interface changes for IPv6. This section specifies the socket interface changes for IPv6.
3.1 IPv6 Address Family and Protocol Family 3.1 IPv6 Address Family and Protocol Family
skipping to change at page 6, line 45 skipping to change at page 6, line 17
A new address family name, AF_INET6, is defined in <sys/socket.h>. The A new address family name, AF_INET6, is defined in <sys/socket.h>. The
AF_INET6 definition distinguishes between the original sockaddr_in AF_INET6 definition distinguishes between the original sockaddr_in
address data structure, and the new sockaddr_in6 data structure. address data structure, and the new sockaddr_in6 data structure.
A new protocol family name, PF_INET6, is defined in <sys/socket.h>. A new protocol family name, PF_INET6, is defined in <sys/socket.h>.
Like most of the other protocol family names, this will usually be Like most of the other protocol family names, this will usually be
defined to have the same value as the corresponding address family name: defined to have the same value as the corresponding address family name:
#define PF_INET6 AF_INET6 #define PF_INET6 AF_INET6
The PF_INET6 is used in the first argument to the socket() function to The AF_INET6 is used in the first argument to the socket() function to
indicate that an IPv6 socket is being created. indicate that an IPv6 socket is being created.
3.2 IPv6 Address Structure 3.2 IPv6 Address Structure
A new in6_addr structure holds a single IPv6 address and is defined as a A new in6_addr structure holds a single IPv6 address and is defined as a
result of including <netinet/in.h>: result of including <netinet/in.h>:
struct in6_addr { struct in6_addr {
uint8_t s6_addr[16]; /* IPv6 address */ uint8_t s6_addr[16]; /* IPv6 address */
}; };
skipping to change at page 8, line 23 skipping to change at page 7, line 45
The sin6_addr field is a single in6_addr structure (defined in the The sin6_addr field is a single in6_addr structure (defined in the
previous section). This field holds one 128-bit IPv6 address. The previous section). This field holds one 128-bit IPv6 address. The
address is stored in network byte order. address is stored in network byte order.
The ordering of elements in this structure is specifically designed so The ordering of elements in this structure is specifically designed so
that when sin6_addr field is aligned on a 64-bit boundary, the start of that when sin6_addr field is aligned on a 64-bit boundary, the start of
the structure will also be aligned on a 64-bit boundary. This is done the structure will also be aligned on a 64-bit boundary. This is done
for optimum performance on 64-bit architectures. for optimum performance on 64-bit architectures.
The sin6_scope_id field is a 32-bit integer that identifies a set of The sin6_scope_id field is a 32-bit integer that identifies a set of
interfaces as appropriate for the scope of the address carried in the interfaces as appropriate for the scope [2] of the address carried in
sin6_addr field [2][5][6][7]. For a link scope sin6_addr, sin6_scope_id the sin6_addr field. The mapping of sin6_scope_id to an interface or
would be an interface index. For a site scope sin6_addr, sin6_scope_id set of interfaces is left to implementation and future specifications on
would be a site identifier. The mapping of sin6_scope_id to an the subject of scoped addresses.
interface or set of interfaces is left to implementation and future
specifications on the subject of site identifiers.
Notice that the sockaddr_in6 structure will normally be larger than the Notice that the sockaddr_in6 structure will normally be larger than the
generic sockaddr structure. On many existing implementations the generic sockaddr structure. On many existing implementations the
sizeof(struct sockaddr_in) equals sizeof(struct sockaddr), with both sizeof(struct sockaddr_in) equals sizeof(struct sockaddr), with both
being 16 bytes. Any existing code that makes this assumption needs to being 16 bytes. Any existing code that makes this assumption needs to
be examined carefully when converting to IPv6. be examined carefully when converting to IPv6.
3.4 Socket Address Structure for 4.4BSD-Based Systems 3.4 Socket Address Structure for 4.4BSD-Based Systems
The 4.4BSD release includes a small, but incompatible change to the The 4.4BSD release includes a small, but incompatible change to the
skipping to change at page 9, line 19 skipping to change at page 8, line 40
the data structure. the data structure.
3.5 The Socket Functions 3.5 The Socket Functions
Applications call the socket() function to create a socket descriptor Applications call the socket() function to create a socket descriptor
that represents a communication endpoint. The arguments to the socket() that represents a communication endpoint. The arguments to the socket()
function tell the system which protocol to use, and what format address function tell the system which protocol to use, and what format address
structure will be used in subsequent functions. For example, to create structure will be used in subsequent functions. For example, to create
an IPv4/TCP socket, applications make the call: an IPv4/TCP socket, applications make the call:
s = socket(PF_INET, SOCK_STREAM, 0); s = socket(AF_INET, SOCK_STREAM, 0);
To create an IPv4/UDP socket, applications make the call: To create an IPv4/UDP socket, applications make the call:
s = socket(PF_INET, SOCK_DGRAM, 0); s = socket(AF_INET, SOCK_DGRAM, 0);
Applications may create IPv6/TCP and IPv6/UDP sockets (which may also Applications may create IPv6/TCP and IPv6/UDP sockets (which may also
handle IPv4 communication as described in section 3.7) by simply using handle IPv4 communication as described in section 3.7) by simply using
the constant PF_INET6 instead of PF_INET in the first argument. For the constant AF_INET6 instead of AF_INET in the first argument. For
example, to create an IPv6/TCP socket, applications make the call: example, to create an IPv6/TCP socket, applications make the call:
s = socket(PF_INET6, SOCK_STREAM, 0); s = socket(AF_INET6, SOCK_STREAM, 0);
To create an IPv6/UDP socket, applications make the call: To create an IPv6/UDP socket, applications make the call:
s = socket(PF_INET6, SOCK_DGRAM, 0); s = socket(AF_INET6, SOCK_DGRAM, 0);
Once the application has created a PF_INET6 socket, it must use the Once the application has created a AF_INET6 socket, it must use the
sockaddr_in6 address structure when passing addresses in to the system. sockaddr_in6 address structure when passing addresses in to the system.
The functions that the application uses to pass addresses into the The functions that the application uses to pass addresses into the
system are: system are:
bind() bind()
connect() connect()
sendmsg() sendmsg()
sendto() sendto()
The system will use the sockaddr_in6 address structure to return The system will use the sockaddr_in6 address structure to return
addresses to applications that are using PF_INET6 sockets. The addresses to applications that are using AF_INET6 sockets. The
functions that return an address from the system to an application are: functions that return an address from the system to an application are:
accept() accept()
recvfrom() recvfrom()
recvmsg() recvmsg()
getpeername() getpeername()
getsockname() getsockname()
No changes to the syntax of the socket functions are needed to support No changes to the syntax of the socket functions are needed to support
IPv6, since all of the "address carrying" functions use an opaque IPv6, since all of the "address carrying" functions use an opaque
address pointer, and carry an address length as a function argument. address pointer, and carry an address length as a function argument.
3.6 Compatibility with IPv4 Applications 3.6 Compatibility with IPv4 Applications
In order to support the large base of applications using the original In order to support the large base of applications using the original
API, system implementations must provide complete source and binary API, system implementations must provide complete source and binary
compatibility with the original API. This means that systems must compatibility with the original API. This means that systems must
continue to support PF_INET sockets and the sockaddr_in address continue to support AF_INET sockets and the sockaddr_in address
structure. Applications must be able to create IPv4/TCP and IPv4/UDP structure. Applications must be able to create IPv4/TCP and IPv4/UDP
sockets using the PF_INET constant in the socket() function, as sockets using the AF_INET constant in the socket() function, as
described in the previous section. Applications should be able to hold described in the previous section. Applications should be able to hold
a combination of IPv4/TCP, IPv4/UDP, IPv6/TCP and IPv6/UDP sockets a combination of IPv4/TCP, IPv4/UDP, IPv6/TCP and IPv6/UDP sockets
simultaneously within the same process. simultaneously within the same process.
Applications using the original API should continue to operate as they Applications using the original API should continue to operate as they
did on systems supporting only IPv4. That is, they should continue to did on systems supporting only IPv4. That is, they should continue to
interoperate with IPv4 nodes. interoperate with IPv4 nodes.
3.7 Compatibility with IPv4 Nodes 3.7 Compatibility with IPv4 Nodes
skipping to change at page 10, line 35 skipping to change at page 9, line 54
uses the IPv4-mapped IPv6 address format defined in the IPv6 addressing uses the IPv4-mapped IPv6 address format defined in the IPv6 addressing
architecture specification [2]. This address format allows the IPv4 architecture specification [2]. This address format allows the IPv4
address of an IPv4 node to be represented as an IPv6 address. The IPv4 address of an IPv4 node to be represented as an IPv6 address. The IPv4
address is encoded into the low-order 32 bits of the IPv6 address, and address is encoded into the low-order 32 bits of the IPv6 address, and
the high-order 96 bits hold the fixed prefix 0:0:0:0:0:FFFF. IPv4- the high-order 96 bits hold the fixed prefix 0:0:0:0:0:FFFF. IPv4-
mapped addresses are written as follows: mapped addresses are written as follows:
::FFFF:<IPv4-address> ::FFFF:<IPv4-address>
These addresses can be generated automatically by the getaddrinfo() These addresses can be generated automatically by the getaddrinfo()
function, when the specified host has only IPv4 addresses (as described function, as described in Section 6.1.
in Section 6.1 and 6.2).
Applications may use PF_INET6 sockets to open TCP connections to IPv4 Applications may use AF_INET6 sockets to open TCP connections to IPv4
nodes, or send UDP packets to IPv4 nodes, by simply encoding the nodes, or send UDP packets to IPv4 nodes, by simply encoding the
destination's IPv4 address as an IPv4-mapped IPv6 address, and passing destination's IPv4 address as an IPv4-mapped IPv6 address, and passing
that address, within a sockaddr_in6 structure, in the connect() or that address, within a sockaddr_in6 structure, in the connect() or
sendto() call. When applications use PF_INET6 sockets to accept TCP sendto() call. When applications use AF_INET6 sockets to accept TCP
connections from IPv4 nodes, or receive UDP packets from IPv4 nodes, the connections from IPv4 nodes, or receive UDP packets from IPv4 nodes, the
system returns the peer's address to the application in the accept(), system returns the peer's address to the application in the accept(),
recvfrom(), or getpeername() call using a sockaddr_in6 structure encoded recvfrom(), or getpeername() call using a sockaddr_in6 structure encoded
this way.. this way.
Few applications will likely need to know which type of node they are Few applications will likely need to know which type of node they are
interoperating with. However, for those applications that do need to interoperating with. However, for those applications that do need to
know, the IN6_IS_ADDR_V4MAPPED() macro, defined in Section 6.7, is know, the IN6_IS_ADDR_V4MAPPED() macro, defined in Section 6.7, is
provided. provided.
3.8 IPv6 Wildcard Address 3.8 IPv6 Wildcard Address
While the bind() function allows applications to select the source IP While the bind() function allows applications to select the source IP
address of UDP packets and TCP connections, applications often want the address of UDP packets and TCP connections, applications often want the
skipping to change at page 12, line 40 skipping to change at page 11, line 58
struct in6_addr loopbackaddr = IN6ADDR_LOOPBACK_INIT; struct in6_addr loopbackaddr = IN6ADDR_LOOPBACK_INIT;
Like IN6ADDR_ANY_INIT, this constant cannot be used in an assignment to Like IN6ADDR_ANY_INIT, this constant cannot be used in an assignment to
a previously declared IPv6 address variable. a previously declared IPv6 address variable.
3.10 Portability Additions 3.10 Portability Additions
One simple addition to the sockets API that can help application writers One simple addition to the sockets API that can help application writers
is the "struct sockaddr_storage". This data structure can simplify is the "struct sockaddr_storage". This data structure can simplify
writing portable code across multiple address families and platforms. writing code that is portable across multiple address families and
This data structure is designed with the following goals.
platforms. This data structure is designed with the following goals.
- Large enough to accommodate all supported protocol-specific address - Large enough to accommodate all supported protocol-specific address
structures. structures.
- Aligned at an appropriate boundary so that pointers to it can be cast - Aligned at an appropriate boundary so that pointers to it can be cast
as pointers to protocol specific address structures and used to as pointers to protocol specific address structures and used to
access the fields of those structures without alignment problems. access the fields of those structures without alignment problems.
The sockaddr_storage structure contains field ss_family which is of type The sockaddr_storage structure contains field ss_family which is of type
sa_family_t. When a sockaddr_storage structure is cast to a sockaddr sa_family_t. When a sockaddr_storage structure is cast to a sockaddr
structure, the ss_family field of the sockaddr_storage structure maps structure, the ss_family field of the sockaddr_storage structure maps
onto the sa_family field of the sockaddr structure. When a onto the sa_family field of the sockaddr structure. When a
sockaddr_storage structure is cast as a protocol specific address sockaddr_storage structure is cast as a protocol specific address
structure, the ss_family field maps onto a field of that structure that structure, the ss_family field maps onto a field of that structure that
skipping to change at page 13, line 32 skipping to change at page 12, line 53
/* specific pad up to alignment field that */ /* specific pad up to alignment field that */
/* follows explicit in the data structure */ /* follows explicit in the data structure */
int64_t __ss_align; /* field to force desired structure */ int64_t __ss_align; /* field to force desired structure */
/* storage alignment */ /* storage alignment */
char __ss_pad2[_SS_PAD2SIZE]; char __ss_pad2[_SS_PAD2SIZE];
/* 112 byte pad to achieve desired size, */ /* 112 byte pad to achieve desired size, */
/* _SS_MAXSIZE value minus size of ss_family */ /* _SS_MAXSIZE value minus size of ss_family */
/* __ss_pad1, __ss_align fields is 112 */ /* __ss_pad1, __ss_align fields is 112 */
}; };
The above example implementation illustrates a data structure which The above example implementation illustrates a data structure which will
will align on a 64-bit boundary. An implementation-specific field align on a 64-bit boundary. An implementation-specific field "_ss_align"
"_ss_align" along "_ss_pad1" is used to force a 64-bit alignment which along with "_ss_pad1" is used to force a 64-bit alignment which covers
covers proper alignment good enough for needs of sockaddr_in6 (IPv6), proper alignment good enough for the needs of sockaddr_in6 (IPv6),
sockaddr_in (IPv4) address data structures. The size of padding fields sockaddr_in (IPv4) address data structures. The size of padding field
_ss_pad1 depends on the chosen alignment boundary. The size of padding _ss_pad1 depends on the chosen alignment boundary. The size of padding
field _ss_pad2 depends on the value of overall size chosen for the total field _ss_pad2 depends on the value of overall size chosen for the total
size of the structure. This size and alignment are represented in the size of the structure. This size and alignment are represented in the
above example by implementation specific (not required) constants above example by implementation specific (not required) constants
_SS_MAXSIZE (chosen value 128) and _SS_ALIGNMENT (with chosen value 8). _SS_MAXSIZE (chosen value 128) and _SS_ALIGNMENT (with chosen value 8).
Constants _SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value Constants _SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value
112) are also for illustration and not required. The implementation specific 112) are also for illustration and not required. The derived values
definitions and structure field names above start with an underscore to assume sa_family_t is 2 bytes. The implementation specific definitions
denote implementation private namespace. Portable code is not expected to and structure field names above start with an underscore to denote
implementation private namespace. Portable code is not expected to
access or reference those fields or constants. access or reference those fields or constants.
On implementations where sockaddr data structure includes a "sa_len", On implementations where sockaddr data structure includes a "sa_len",
field this data structure would look like this: field this data structure would look like this:
/* /*
* Definitions used for sockaddr_storage structure paddings design. * Definitions used for sockaddr_storage structure paddings design.
*/ */
#define _SS_PAD1SIZE (_SS_ALIGNSIZE - #define _SS_PAD1SIZE (_SS_ALIGNSIZE -
(sizeof (uint8_t) + sizeof (sa_family_t)) (sizeof (uint8_t) + sizeof (sa_family_t))
skipping to change at page 19, line 8 skipping to change at page 18, line 32
int on = 1; int on = 1;
if (setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY, if (setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY,
(char *)&on, sizeof(on)) == -1) (char *)&on, sizeof(on)) == -1)
perror("setsockopt IPV6_V6ONLY"); perror("setsockopt IPV6_V6ONLY");
else else
printf("IPV6_V6ONLY set0); printf("IPV6_V6ONLY set0);
Note - This option has no effect on the use of IPv4 Mapped addresses Note - This option has no effect on the use of IPv4 Mapped addresses
which enter a node as a valid IPv6 addresses for IPv6 communications as which enter a node as a valid IPv6 addresses for IPv6 communications as
defined by Stateless IP/ICMP Translation Algorithm (SIIT) [8]. defined by Stateless IP/ICMP Translation Algorithm (SIIT) [5].
An example use of this option is to allow two versions of the same
server process to run on the same port, one providing service over IPv6,
the other providing the same service over IPv4.
6. Library Functions 6. Library Functions
New library functions are needed to perform a variety of operations with New library functions are needed to perform a variety of operations with
IPv6 addresses. Functions are needed to lookup IPv6 addresses in the IPv6 addresses. Functions are needed to lookup IPv6 addresses in the
Domain Name System (DNS). Both forward lookup (nodename-to-address Domain Name System (DNS). Both forward lookup (nodename-to-address
translation) and reverse lookup (address-to-nodename translation) need translation) and reverse lookup (address-to-nodename translation) need
to be supported. Functions are also needed to convert IPv6 addresses to be supported. Functions are also needed to convert IPv6 addresses
between their binary and textual form. between their binary and textual form.
skipping to change at page 19, line 30 skipping to change at page 19, line 4
gethostbyaddr(), are left as-is. New functions are defined to handle gethostbyaddr(), are left as-is. New functions are defined to handle
both IPv4 and IPv6 addresses. both IPv4 and IPv6 addresses.
The commonly used function gethostbyname() is inadequate for many The commonly used function gethostbyname() is inadequate for many
applications, first because it provides no way for the caller to specify applications, first because it provides no way for the caller to specify
anything about the types of addresses desired (IPv4 only, IPv6 only, anything about the types of addresses desired (IPv4 only, IPv6 only,
IPv4-mapped IPv6 are OK, etc.), and second because many implementations IPv4-mapped IPv6 are OK, etc.), and second because many implementations
of this function are not thread safe. RFC 2133 defined a function named of this function are not thread safe. RFC 2133 defined a function named
gethostbyname2() but this function was also inadequate, first because gethostbyname2() but this function was also inadequate, first because
its use required setting a global option (RES_USE_INET6) when IPv6 its use required setting a global option (RES_USE_INET6) when IPv6
addresses were required, and second because a flag argument is needed to addresses were required, and second because a flag argument is needed to
provide the caller with additional control over the types of addresses provide the caller with additional control over the types of addresses
required. required. The gethostbyname2() function was deprecated in RFC 2553 and
is no longer part of the basic API.
6.1 Protocol-Independent Nodename and Service Name Translation 6.1 Protocol-Independent Nodename and Service Name Translation
Nodename-to-address translation is done in a protocol-independent Nodename-to-address translation is done in a protocol-independent
fashion using the getaddrinfo() function that is taken from the fashion using the getaddrinfo() function.
Institute of Electrical and Electronic Engineers IEEE 1003.1-200x
(POSIX) draft specification [3].
The official specification for this function will be the final IEEE
standard. In addition this specification is not specifying all
parameter possibilities for this function, but only the parameters that
can be provided to support IPv4 and IPv6 communications to support this
specification. This is beyond the scope of this document and additional
work on this function will be done by the Austin (IEEE/ISO/TOG) Group.
#include <sys/socket.h> #include <sys/socket.h>
#include <netdb.h> #include <netdb.h>
int getaddrinfo(const char *nodename, const char *servname, int getaddrinfo(const char *nodename, const char *servname,
const struct addrinfo *hints, struct addrinfo **res); const struct addrinfo *hints, struct addrinfo **res);
void freeaddrinfo(struct addrinfo *ai); void freeaddrinfo(struct addrinfo *ai);
struct addrinfo { struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, .. */ int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, .. */
int ai_family; /* PF_xxx */ int ai_family; /* AF_xxx */
int ai_socktype; /* SOCK_xxx */ int ai_socktype; /* SOCK_xxx */
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
socklen_t ai_addrlen; /* length of ai_addr */ socklen_t ai_addrlen; /* length of ai_addr */
char *ai_canonname; /* canonical name for nodename */ char *ai_canonname; /* canonical name for nodename */
struct sockaddr *ai_addr; /* binary address */ struct sockaddr *ai_addr; /* binary address */
struct addrinfo *ai_next; /* next structure in linked list */ struct addrinfo *ai_next; /* next structure in linked list */
}; };
The getaddrinfo() function translates the name of a service location The getaddrinfo() function translates the name of a service location
(for example, a host name) and/or a service name and returns a set of (for example, a host name) and/or a service name and returns a set of
skipping to change at page 20, line 35 skipping to change at page 19, line 55
as valid within multiple supported families, the implementation will as valid within multiple supported families, the implementation will
attempt to resolve the name in all supported families and, in absence attempt to resolve the name in all supported families and, in absence
of errors, one or more results shall be returned. of errors, one or more results shall be returned.
If the nodename argument is not null, it can be a descriptive name or If the nodename argument is not null, it can be a descriptive name or
can be an address string. If the specified address family is AF_INET, can be an address string. If the specified address family is AF_INET,
AF_INET6, or AF_UNSPEC, valid descriptive names include host names. AF_INET6, or AF_UNSPEC, valid descriptive names include host names.
If the specified address family is AF_INET or AF_UNSPEC, address If the specified address family is AF_INET or AF_UNSPEC, address
strings using Internet standard dot notation as specified in strings using Internet standard dot notation as specified in
inet_addr() are valid. If the specified address family is AF_INET6 inet_addr() are valid. If the specified address family is AF_INET6
or AF_UNSPEC, standard IPv6 text forms described in inet_ntop() and or AF_UNSPEC, standard IPv6 text forms described in inet_ntop() are
[5] are valid. valid.
If nodename is not null, the requested service location is named by If nodename is not null, the requested service location is named by
nodename; otherwise, the requested service location is local to the nodename; otherwise, the requested service location is local to the
caller. caller.
If servname is null, the call shall return network-level addresses If servname is null, the call shall return network-level addresses
for the specified nodename. If servname is not null, it is a null- for the specified nodename. If servname is not null, it is a null-
terminated character string identifying the requested service. This terminated character string identifying the requested service. This
can be either a descriptive name or a numeric representation suitable can be either a descriptive name or a numeric representation suitable
for use with the address family or families. If the specified address for use with the address family or families. If the specified address
skipping to change at page 21, line 55 skipping to change at page 21, line 20
If the AI_NUMERICSERV flag is specified, then a non-null servname If the AI_NUMERICSERV flag is specified, then a non-null servname
string supplied shall be a numeric port string. Otherwise, an string supplied shall be a numeric port string. Otherwise, an
[EAI_NONAME] error shall be returned. This flag shall prevent any [EAI_NONAME] error shall be returned. This flag shall prevent any
type of name resolution service (for example, NIS+) from being type of name resolution service (for example, NIS+) from being
invoked. invoked.
If the AI_V4MAPPED flag is specified along with an ai_family of If the AI_V4MAPPED flag is specified along with an ai_family of
AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6 addresses AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6 addresses
on finding no matching IPv6 addresses (ai_addrlen shall be 16). on finding no matching IPv6 addresses (ai_addrlen shall be 16).
For example, when using the DNS, if no AAAA or A6 records are found For example, when using the DNS, if no AAAA records are found
then a query is made for A records and any found are returned as then a query is made for A records and any found are returned as
IPv4-mapped IPv6 addresses. IPv4-mapped IPv6 addresses.
The AI_V4MAPPED flag shall be ignored unless ai_family equals The AI_V4MAPPED flag shall be ignored unless ai_family equals
AF_INET6. AF_INET6.
If the AI_ALL flag is used with the AI_V4MAPPED flag, then If the AI_ALL flag is used with the AI_V4MAPPED flag, then
getaddrinfo() shall return all matching IPv6 and IPv4 addresses. getaddrinfo() shall return all matching IPv6 and IPv4 addresses.
For example, when using the DNS, a query is first made for AAAA/A6 For example, when using the DNS, queries are made for both AAAA
records and if successful, those IPv6 addresses are returned. records and A records, and getaddrinfo() returns the combined
Another query is then made for A records and any IPv4 addresses results of both queries. Any IPv4 addresses found are returned
found are returned as IPv4-mapped IPv6 addresses. as IPv4-mapped IPv6 addresses.
The AI_ALL flag without the AI_V4MAPPED flag is ignored. The AI_ALL flag without the AI_V4MAPPED flag is ignored.
Note: Note:
When ai_family is not specified (AF_UNSPEC), AI_V4MAPPED and When ai_family is not specified (AF_UNSPEC), AI_V4MAPPED and
AI_ALL flags will only be used if AF_INET6 is supported. AI_ALL flags will only be used if AF_INET6 is supported.
If the AI_ADDRCONFIG flag is specified then a query for AAAA or A6 If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be
records should occur only if the node has at least one IPv6 source returned only if an IPv4 address is configured on the local system,
address configured and a query for A records should occur only if the and IPv6 addresses shall be returned only if an IPv6 address is
node has at least one IPv4 source address configured. The loopback configured on the local system. The loopback address is not
address is not considered for this case as valid as a configured considered for this case as valid as a configured address.
sources address.
For example, when using the DNS, a query for AAAA records
should occur only if the node has at least one IPv6 address
configured (other than IPv6 loopback) and a query for A records
should occur only if the node has at least one IPv4 address
configured (other than the IPv4 loopback).
The ai_socktype field to which argument hints points specifies the The ai_socktype field to which argument hints points specifies the
socket type for the service, as defined for socket(). If a specific socket type for the service, as defined for socket(). If a specific
socket type is not given (for example, a value of zero) and the socket type is not given (for example, a value of zero) and the
service name could be interpreted as valid with multiple supported service name could be interpreted as valid with multiple supported
socket types, the implementation shall attempt to resolve the service socket types, the implementation shall attempt to resolve the service
name for all supported socket types and, in the absence of errors, name for all supported socket types and, in the absence of errors,
all possible results shall be returned. A non-zero socket type value all possible results shall be returned. A non-zero socket type value
shall limit the returned information to values with the specified shall limit the returned information to values with the specified
socket type. socket type.
skipping to change at page 24, line 5 skipping to change at page 23, line 30
of these must be supplied. of these must be supplied.
[EAI_SERVICE] The service passed was not recognized for the specified [EAI_SERVICE] The service passed was not recognized for the specified
socket type. socket type.
[EAI_SOCKTYPE] The intended socket type was not recognized. [EAI_SOCKTYPE] The intended socket type was not recognized.
[EAI_SYSTEM] A system error occurred; the error code can be found in [EAI_SYSTEM] A system error occurred; the error code can be found in
errno. errno.
The gai_strerror() function provides a descriptive text string
corresponding to an EAI_xxx error value.
#include <netdb.h> #include <netdb.h>
const char *gai_strerror(int ecode); const char *gai_strerror(int ecode);
The argument is one of the EAI_xxx values defined for the getaddrinfo() The argument is one of the EAI_xxx values defined for the getaddrinfo()
and getnameinfo() functions. The return value points to a string and getnameinfo() functions. The return value points to a string
describing the error. If the argument is not one of the EAI_xxx values, describing the error. If the argument is not one of the EAI_xxx values,
the function still returns a pointer to a string whose contents indicate the function still returns a pointer to a string whose contents indicate
an unknown error. an unknown error.
6.2 Socket Address Structure to Nodename and Service Name 6.2 Socket Address Structure to Node Name and Service Name
The official specification for this function will be the final Austin The getnameinfo() function is used to translate the contents of a socket
Group standard update to getaddrinfo(), and will incorporate this address structure to a node name and/or service name.
function. In addition this specification is not specifying all
parameter possibilities for this function, but only the parameters that
can be provided to support IPv4 and IPv6 communications to support this
specification. This is beyond the scope of this document and additional
work on this function will be done by the Austin group.
#include <sys/socket.h> #include <sys/socket.h>
#include <netdb.h> #include <netdb.h>
int getnameinfo(const struct sockaddr *sa, socklen_t salen, int getnameinfo(const struct sockaddr *sa, socklen_t salen,
char *host, socklen_t hostlen, char *node, socklen_t nodelen,
char *serv, socklen_t servlen, char *service, socklen_t servicelen,
int flags); int flags);
The getnameinfo() function shall translate a socket address to a node The getnameinfo() function shall translate a socket address to a node
name and service location, all of which are defined as in getaddrinfo(). name and service location, all of which are defined as in getaddrinfo().
The sa argument points to a socket address structure to be translated. The sa argument points to a socket address structure to be translated.
The salen argument holds the size of the socket address structure
pointed to by sa.
If the socket address structure contains an IPv4-mapped IPv6 address or If the socket address structure contains an IPv4-mapped IPv6 address or
an IPv4-compatible IPv6 address, the implementation shall extract the an IPv4-compatible IPv6 address, the implementation shall extract the
embedded IPv4 address and lookup the node name for that IPv4 address. embedded IPv4 address and lookup the node name for that IPv4 address.
Note: The IPv6 unspecified address ("::") and the IPv6 Note: The IPv6 unspecified address ("::") and the IPv6
loopback address ("::1") are not IPv4-compatible addresses. loopback address ("::1") are not IPv4-compatible addresses.
If the address is the IPv6 unspecified address ("::"), a If the address is the IPv6 unspecified address ("::"), a
lookup is not performed, and the [EAI_NONAME] error is returned. lookup is not performed, and the [EAI_NONAME] error is returned.
If the node argument is non-NULL and the nodelen argument is nonzero, If the node argument is non-NULL and the nodelen argument is nonzero,
then the node argument points to a buffer able to contain up to nodelen then the node argument points to a buffer able to contain up to nodelen
characters that receives the node name as a null-terminated string. If characters that receives the node name as a null-terminated string. If
the node argument is NULL or the nodelen argument is zero, the node name the node argument is NULL or the nodelen argument is zero, the node name
shall not be returned. If the node's name cannot be located, the numeric shall not be returned. If the node's name cannot be located, the numeric
form of the node's address is returned instead of its name. If the sa form of the node's address is returned instead of its name.
argument is an IPv6 address the returned nodename may be in the format
as defined in [5].
If the service argument is non-NULL and the servicelen argument is non- If the service argument is non-NULL and the servicelen argument is non-
zero, then the service argument points to a buffer able to contain up to zero, then the service argument points to a buffer able to contain up to
servicelen bytes that receives the service name as a null-terminated servicelen bytes that receives the service name as a null-terminated
string. If the service argument is NULL or the servicelen argument is string. If the service argument is NULL or the servicelen argument is
zero, the service name shall not be returned. If the service's name zero, the service name shall not be returned. If the service's name
cannot be located, the numeric form of the service address (for example, cannot be located, the numeric form of the service address (for example,
its port number) shall be returned instead of its name. its port number) shall be returned instead of its name.
The arguments node and service cannot both be NULL. The arguments node and service cannot both be NULL.
The flags argument is a flag that changes the default actions of the The flags argument is a flag that changes the default actions of the
function. By default the fully-qualified domain name (FQDN) for the host function. By default the fully-qualified domain name (FQDN) for the host
shall be returned, but: shall be returned, but:
- If the flag bit NI_NOFQDN is set, only the node name portion of the - If the flag bit NI_NOFQDN is set, only the node name portion of the
skipping to change at page 25, line 25 skipping to change at page 24, line 49
FQDN shall be returned for local hosts. FQDN shall be returned for local hosts.
- If the flag bit NI_NUMERICHOST is set, the numeric form of the - If the flag bit NI_NUMERICHOST is set, the numeric form of the
host's address shall be returned instead of its name, under all host's address shall be returned instead of its name, under all
circumstances. circumstances.
- If the flag bit NI_NAMEREQD is set, an error shall be returned if the - If the flag bit NI_NAMEREQD is set, an error shall be returned if the
host's name cannot be located. host's name cannot be located.
- If the flag bit NI_NUMERICSERV is set, the numeric form of the - If the flag bit NI_NUMERICSERV is set, the numeric form of the
service address shall be returned (for example, its port number) instead of service address shall be returned (for example, its port number)
its name, under all circumstances. instead of its name, under all circumstances.
- If the flag bit NI_NUMERICSCOPE is set, the numeric form of the - If the flag bit NI_NUMERICSCOPE is set, the numeric form of the
scope identifier shall be returned (for example, interface index) scope identifier shall be returned (for example, interface index)
instead of its name. This flag is ignored if the sa argument is instead of its name. This flag is ignored if the sa argument is
not an IPv6 address. not an IPv6 address.
- If the flag bit NI_DGRAM is set, this indicates that the service is - If the flag bit NI_DGRAM is set, this indicates that the service is
a datagram service (SOCK_DGRAM). The default behavior shall assume that a datagram service (SOCK_DGRAM). The default behavior shall assume that
the service is a stream service (SOCK_STREAM). the service is a stream service (SOCK_STREAM).
skipping to change at page 26, line 23 skipping to change at page 25, line 48
NI_NAMEREQD is set and the host's name cannot be located, or NI_NAMEREQD is set and the host's name cannot be located, or
both nodename and servname were null. both nodename and servname were null.
[EAI_OVERFLOW] An argument buffer overflowed. [EAI_OVERFLOW] An argument buffer overflowed.
[EAI_SYSTEM] A system error occurred. The error code can be found in [EAI_SYSTEM] A system error occurred. The error code can be found in
errno. errno.
6.3 Address Conversion Functions 6.3 Address Conversion Functions
The two functions inet_addr() and inet_ntoa() convert an IPv4 address The two IPv4 functions inet_addr() and inet_ntoa() convert an IPv4
between binary and text form. IPv6 applications need similar functions. address between binary and text form. IPv6 applications need similar
The following two functions convert both IPv6 and IPv4 addresses: functions. The following two functions convert both IPv6 and IPv4
addresses:
#include <arpa/inet.h> #include <arpa/inet.h>
int inet_pton(int af, const char *src, void *dst); int inet_pton(int af, const char *src, void *dst);
const char *inet_ntop(int af, const void *src, const char *inet_ntop(int af, const void *src,
char *dst, socklen_t size); char *dst, socklen_t size);
The inet_pton() function shall convert an address in its standard text The inet_pton() function shall convert an address in its standard text
presentation form into its numeric binary form. The af argument shall presentation form into its numeric binary form. The af argument shall
specify the family of the address. The AF_INET and AF_INET6 address specify the family of the address. The AF_INET and AF_INET6 address
families shall be supported. The src argument points to the string families shall be supported. The src argument points to the string
being passed in. The dst argument points to a buffer into which the being passed in. The dst argument points to a buffer into which the
function stores the numeric address; this shall be large enough to hold function stores the numeric address; this shall be large enough to hold
the numeric address (32 bits for AF_INET, 128 bits for AF_INET6). The the numeric address (32 bits for AF_INET, 128 bits for AF_INET6). The
inet_pton() function shall return 1 if the conversion succeeds, with the inet_pton() function shall return 1 if the conversion succeeds, with the
address pointed to by dst in network byte order. It shall return 0 if address pointed to by dst in network byte order. It shall return 0 if
the input is not a valid IPv4 dotted-decimal string or a valid IPv6 the input is not a valid IPv4 dotted-decimal string or a valid IPv6
address string, or -1 with errno set to EAFNOSUPPORT if the af argument address string, or -1 with errno set to EAFNOSUPPORT if the af argument
skipping to change at page 27, line 52 skipping to change at page 27, line 21
int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *);
int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *);
int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *);
int IN6_IS_ADDR_MC_ORGLOCAL (const struct in6_addr *); int IN6_IS_ADDR_MC_ORGLOCAL (const struct in6_addr *);
int IN6_IS_ADDR_MC_GLOBAL (const struct in6_addr *); int IN6_IS_ADDR_MC_GLOBAL (const struct in6_addr *);
The first seven macros return true if the address is of the specified The first seven macros return true if the address is of the specified
type, or false otherwise. The last five test the scope of a multicast type, or false otherwise. The last five test the scope of a multicast
address and return true if the address is a multicast address of the address and return true if the address is a multicast address of the
specified scope or false if the address is either not a multicast specified scope or false if the address is either not a multicast
address or not of the specified scope. Note that IN6_IS_ADDR_LINKLOCAL address or not of the specified scope.
and IN6_IS_ADDR_SITELOCAL return true only for the two types of local-
use IPv6 unicast addresses (Link-Local and Site-Local) defined in [2], Note that IN6_IS_ADDR_LINKLOCAL and IN6_IS_ADDR_SITELOCAL return true
and that by this definition, the IN6_IS_ADDR_LINKLOCAL macro returns only for the two types of local-use IPv6 unicast addresses (Link-Local
false for the IPv6 loopback address (::1). These two macros do not and Site-Local) defined in [2], and that by this definition, the
return true for IPv6 multicast addresses of either link-local scope or IN6_IS_ADDR_LINKLOCAL macro returns false for the IPv6 loopback address
site-local scope. (::1). These two macros do not return true for IPv6 multicast addresses
of either link-local scope or site-local scope.
7. Summary of New Definitions 7. Summary of New Definitions
The following list summarizes the constants, structure, and extern The following list summarizes the constants, structure, and extern
definitions discussed in this memo, sorted by header. definitions discussed in this memo, sorted by header.
<net/if.h> IF_NAMESIZE <net/if.h> IF_NAMESIZE
<net/if.h> struct if_nameindex{}; <net/if.h> struct if_nameindex{};
<netdb.h> AI_ADDRCONFIG <netdb.h> AI_ADDRCONFIG
skipping to change at page 29, line 41 skipping to change at page 29, line 11
<netinet/in.h> int IN6_IS_ADDR_UNSPECIFIED(const struct in6_addr *); <netinet/in.h> int IN6_IS_ADDR_UNSPECIFIED(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_V4COMPAT(const struct in6_addr *); <netinet/in.h> int IN6_IS_ADDR_V4COMPAT(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_V4MAPPED(const struct in6_addr *); <netinet/in.h> int IN6_IS_ADDR_V4MAPPED(const struct in6_addr *);
8. Security Considerations 8. Security Considerations
IPv6 provides a number of new security mechanisms, many of which need to IPv6 provides a number of new security mechanisms, many of which need to
be accessible to applications. Companion memos detailing the extensions be accessible to applications. Companion memos detailing the extensions
to the socket interfaces to support IPv6 security are being written. to the socket interfaces to support IPv6 security are being written.
9. Year 2000 Considerations Changes from RFC 2553
There are no issues for this draft concerning the Year 2000 issue
regarding the use of dates.
Changes made to rfc2553bis-04 to rfc2553bis-05
1. Added Jack McCann as coauthor for signicant work on draft 04.
Changes made to rfc2553bis-03 to rfc2553bis-04
1. Alignments with [3].
Changes made to rfc2553bis-02 to rfc2553bis-03
1. Edits only.
Changes made to rfc2553bis-01 to rfc2553bis-02
1. Updated all references to comply with latest IEEEE work on
socket APIs and changed all remaining size_t to socklen_t.
2. Edits caught. 1. Add brief description of the history of this API and its
relation to the Open Group/IEEE/ISO standards.
Changes made to rfc2553bis-00 to rfc2553bis-01 2. Alignments with [3].
1. Removed all references to getipnodebyname() and 3. Removed all references to getipnodebyname() and
getipnodebyaddr(). getipnodebyaddr(), which are deprecated in favor
of getaddrinfo() and getnameinfo().
2. Added IPV6_V6ONLY Socket IP level option to permit nodes 4. Added IPV6_V6ONLY IP level socket option to permit nodes
to not process IPv4 packets as IPv4 Mapped addresses to not process IPv4 packets as IPv4 Mapped addresses
in implementations. in implementations.
3. Added note to getaddrinfo() and getnameinfo() 5. Added SIIT to references and added new contributors.
that final specification of parameter associations for
these functions will be done by Austin.
4. Added SIIT to references and added new contributors.
Changes made rfc2553 to rfc2553bis-00:
1. Updated Portability Section 3.10 to conform to XNS 5.2.
2. Updated getaddrinfo(), getnameinfo(), to conform to XNS 5.2.
3. Added references to Scope Architecture, Scope Routing, and
Extension Format for Scoped Addresses work in progress.
4. Added NI_NUMERICSCOPE flag to getnameinfo().
5. Added qualification to getipnodebyname/addr() functions that
they will not work as is with scope identifiers with IPv6, and
getaddrinfo/getnameinfo should be used.
6. Added DNS A6 record notation to AAAA and added ip6.arpa as new
PTR record domain.
Acknowledgments Acknowledgments
This specification's evolution and completeness were significantly This specification's evolution and completeness were significantly
influenced by the efforts of Richard Stevens, who has passed on. Rich's influenced by the efforts of Richard Stevens, who has passed on. Rich's
wisdom and talent made the specification what it is today. The co- wisdom and talent made the specification what it is today. The co-
authors will long think of Richard with great respect. authors will long think of Richard with great respect.
Thanks to the many people who made suggestions and provided feedback to Thanks to the many people who made suggestions and provided feedback to
this document, including: Werner Almesberger, Ran Atkinson, Fred Baker, this document, including:
Dave Borman, Andrew Cherenson, Alex Conta, Alan Cox, Steve Deering,
Richard Draves, Francis Dupont, Robert Elz, Brian Haberman, Jun-ichiro Werner Almesberger, Ran Atkinson, Fred Baker, Dave Borman, Andrew
itojun Hagino, Marc Hasson, Tom Herbert, Bob Hinden, Wan-Yen Hsu, Cherenson, Alex Conta, Alan Cox, Steve Deering, Richard Draves, Francis
Christian Huitema, Koji Imada, Markus Jork, Ron Lee, Alan Lloyd, Charles Dupont, Robert Elz, Brian Haberman, Jun-ichiro itojun Hagino, Marc
Lynn, Dan McDonald, Dave Mitton, Thomas Narten, Josh Osborne, Craig Hasson, Tom Herbert, Bob Hinden, Wan-Yen Hsu, Christian Huitema, Koji
Imada, Markus Jork, Ron Lee, Alan Lloyd, Charles Lynn, Dan McDonald,
Dave Mitton, Finnbarr Murphy, Thomas Narten, Josh Osborne, Craig
Partridge, Jean-Luc Richier, Bill Sommerfield, Erik Scoredos, Keith Partridge, Jean-Luc Richier, Bill Sommerfield, Erik Scoredos, Keith
Sklower, JINMEI Tatuya, Dave Thaler, Matt Thomas, Harvey Thompson, Dean Sklower, JINMEI Tatuya, Dave Thaler, Matt Thomas, Harvey Thompson, Dean
D. Throop, Karen Tracey, Glenn Trewitt, Paul Vixie, David Waitzman, Carl D. Throop, Karen Tracey, Glenn Trewitt, Paul Vixie, David Waitzman, Carl
Williams, Kazu Yamamoto, Vlad Yasevich, Stig Venaas, and Brian Zill Williams, Kazu Yamamoto, Vlad Yasevich, Stig Venaas, and Brian Zill.
The getaddrinfo() and getnameinfo() functions are taken from an earlier The getaddrinfo() and getnameinfo() functions are taken from an earlier
Internet Draft by Keith Sklower. As noted in that draft, William Durst, Internet Draft by Keith Sklower. As noted in that draft, William Durst,
Steven Wise, Michael Karels, and Eric Allman provided many useful Steven Wise, Michael Karels, and Eric Allman provided many useful
discussions on the subject of protocol-independent name-to-address discussions on the subject of protocol-independent name-to-address
translation, and reviewed early versions of Keith Sklower's original translation, and reviewed early versions of Keith Sklower's original
proposal. Eric Allman implemented the first prototype of getaddrinfo(). proposal. Eric Allman implemented the first prototype of getaddrinfo().
The observation that specifying the pair of name and service would The observation that specifying the pair of name and service would
suffice for connecting to a service independent of protocol details was suffice for connecting to a service independent of protocol details was
made by Marshall Rose in a proposal to X/Open for a "Uniform Network made by Marshall Rose in a proposal to X/Open for a "Uniform Network
skipping to change at page 31, line 52 skipping to change at page 30, line 19
of contributions and co-authored an earlier version of this memo. of contributions and co-authored an earlier version of this memo.
References References
[1] S. Deering, R. Hinden, "Internet Protocol, Version 6 (IPv6) [1] S. Deering, R. Hinden, "Internet Protocol, Version 6 (IPv6)
Specification", RFC 2460 Draft Standard. Specification", RFC 2460 Draft Standard.
[2] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture", [2] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture",
RFC 2373, July 1998 Draft Standard. RFC 2373, July 1998 Draft Standard.
[3] IEEE Std. 1003.1-200x Standard for Information Technology -- [3] IEEE Std. 1003.1-2001 Standard for Information Technology --
Portable Operating System Interface (POSIX) Portable Operating System Interface (POSIX)
[4] W. Stevens, M. Thomas, "Advanced Sockets API for IPv6",
RFC 2292, February 1998.
[5] T. Jinmei, A. Onoe, "An Extension of Format for IPv6 Scoped Open Group Technical Standard: Base Specifications, Issue 6
Addresses", Work-in-Progress. December 2001
[6] S. Deering, B. Haberman, B. Zill "IP Version 6 Scoped Address ISO 9945 (pending final approval by ISO)
Architecture", Work-in-Progress.
[7] B. Haberman " Routing of Scoped Addresses in the Internet Protocol http://www.opengroup.org/austin
Version 6 (IPv6)", Work-in-Progress.
[8] E. Nordmark "Stateless IP/ICMP Translation Algorithm (SIIT)" [4] W. Stevens, M. Thomas, "Advanced Sockets API for IPv6",
RFC 2292, February 1998.
[5] E. Nordmark "Stateless IP/ICMP Translation Algorithm (SIIT)"
RFC 2765, February 2000. RFC 2765, February 2000.
[6] The Open Group Base Working Group
http://www.opengroup.org/platform/base.html
Authors' Addresses Authors' Addresses
Bob Gilligan Bob Gilligan
Cacheflow, Inc. Cacheflow, Inc.
650 Almanor Ave. 650 Almanor Ave.
Sunnyvale, CA 94086 Sunnyvale, CA 94086
Telephone: 408-220-2084 (voice) Telephone: 408-220-2084 (voice)
408-220-2250 (fax) 408-220-2250 (fax)
Email: gilligan@cacheflow.com Email: gilligan@cacheflow.com
Susan Thomson Susan Thomson
Cisco Systems Cisco Systems
499 Thornall Street, 8th floor 499 Thornall Street, 8th floor
Edison, NJ 08837 Edison, NJ 08837
Telephone: 732-635-3086 Telephone: 732-635-3086
Email: sethomso@cisco.com Email: sethomso@cisco.com
Jim Bound Jim Bound
Compaq Computer Corporation Hewlett-Packard Company
110 Spitbrook Road ZKO3-3/W20 110 Spitbrook Road ZKO3-3/W20
Nashua, NH 03062 Nashua, NH 03062
Telephone: 603-884-0062 Telephone: 603-884-0062
Email: Jim.Bound@compaq.com Email: Jim.Bound@hp.com
Jack McCann Jack McCann
Compaq Computer Corporation Hewlett-Packard Company
110 Spitbrook Road ZKO3-3/W20 110 Spitbrook Road ZKO3-3/W20
Nashua, NH 03062 Nashua, NH 03062
Telephone: 603-884-2608 Telephone: 603-884-2608
Email: John.McCann@compaq.com Email: Jack.McCann@hp.com
 End of changes. 81 change blocks. 
224 lines changed or deleted 210 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/