idnits 2.17.1 draft-ietf-ipngwg-rfc2553bis-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 31 longer pages, the longest (page 2) being 66 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 31 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 29 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** The abstract seems to contain references ([4]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 709 has weird spacing: '...ned int if_na...' == Line 741 has weird spacing: '...ned int if_i...' == Line 767 has weird spacing: '... void if_fr...' == Line 793 has weird spacing: '... int hoplim...' == Line 814 has weird spacing: '... int hoplim...' == (1 more instance...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 2002) is 7893 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '16' is mentioned on line 294, but not defined == Missing Reference: '512' is mentioned on line 1317, but not defined == Missing Reference: '514' is mentioned on line 1317, but not defined ** Obsolete normative reference: RFC 2460 (ref. '1') (Obsoleted by RFC 8200) ** Obsolete normative reference: RFC 2373 (ref. '2') (Obsoleted by RFC 3513) -- Possible downref: Non-RFC (?) normative reference: ref. '3' ** Obsolete normative reference: RFC 2292 (ref. '4') (Obsoleted by RFC 3542) ** Obsolete normative reference: RFC 2765 (ref. '5') (Obsoleted by RFC 6145) -- Possible downref: Non-RFC (?) normative reference: ref. '6' Summary: 11 errors (**), 0 flaws (~~), 13 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 IPNG Working Group R.E. Gilligan 2 INTERNET-DRAFT: draft-ietf-ipngwg-rfc2553bis-07.txt Cache Flow 3 Obsoletes RFC 2553 S. Thomson 4 Cisco 5 J. Bound 6 J. McCann 7 Hewlett-Packard 8 W. R. Stevens 9 September 2002 11 Basic Socket Interface Extensions for IPv6 13 15 Status of this Memo 17 This document is an Internet-Draft and is in full conformance with 18 all provisions of Section 10 of RFC2026. 20 This document is a submission by the Internet Protocol IPv6 Working 21 Group of the Internet Engineering Task Force (IETF). Comments should 22 be submitted to the ipng@sunroof.eng.sun.com mailing list. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet- Drafts as reference 32 material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 Abstract 42 The de facto standard application program interface (API) for TCP/IP 43 applications is the "sockets" interface. Although this API was 44 developed for Unix in the early 1980s it has also been implemented on 45 a wide variety of non-Unix systems. TCP/IP applications written 46 using the sockets API have in the past enjoyed a high degree of 47 portability and we would like the same portability with IPv6 48 applications. But changes are required to the sockets API to support 49 IPv6 and this memo describes these changes. These include a new 50 socket address structure to carry IPv6 addresses, new address 51 conversion functions, and some new socket options. These extensions 52 are designed to provide access to the basic IPv6 features required by 53 TCP and UDP applications, including multicasting, while introducing a 54 minimum of change into the system and providing complete 55 compatibility for existing IPv4 applications. Additional extensions 56 for advanced IPv6 features (raw sockets and access to the IPv6 57 extension headers) are defined in another document [4]. 59 Table of Contents: 61 1. Introduction.................................................3 62 2. Design Considerations........................................3 63 2.1 What Needs to be Changed....................................4 64 2.2 Data Types..................................................5 65 2.3 Headers.....................................................5 66 2.4 Structures..................................................5 67 3. Socket Interface.............................................5 68 3.1 IPv6 Address Family and Protocol Family.....................6 69 3.2 IPv6 Address Structure......................................6 70 3.3 Socket Address Structure for 4.3BSD-Based Systems...........6 71 3.4 Socket Address Structure for 4.4BSD-Based Systems...........7 72 3.5 The Socket Functions........................................8 73 3.6 Compatibility with IPv4 Applications........................9 74 3.7 Compatibility with IPv4 Nodes...............................9 75 3.8 IPv6 Wildcard Address......................................10 76 3.9 IPv6 Loopback Address......................................11 77 3.10 Portability Additions.....................................11 78 4. Interface Identification....................................13 79 4.1 Name-to-Index..............................................14 80 4.2 Index-to-Name..............................................14 81 4.3 Return All Interface Names and Indexes.....................14 82 4.4 Free Memory................................................15 83 5. Socket Options..............................................15 84 5.1 Unicast Hop Limit..........................................15 85 5.2 Sending and Receiving Multicast Packets....................16 86 5.3 IPV6_V6ONLY option for AF_INET6 Sockets....................18 87 6. Library Functions...........................................18 88 6.1 Protocol-Independent Nodename and Service Name Translation.19 89 6.2 Socket Address Structure to Node Name and Service Name.....23 90 6.3 Address Conversion Functions...............................25 91 6.4 Address Testing Macros.....................................26 92 7. Summary of New Definitions..................................27 93 8. Security Considerations.....................................29 94 Changes from RFC 2553..........................................29 95 Acknowledgments................................................29 96 References.....................................................30 97 Authors' Addresses.............................................31 98 1. Introduction 100 While IPv4 addresses are 32 bits long, IPv6 addresses are 128 bits long. 101 The socket interface makes the size of an IP address quite visible to an 102 application; virtually all TCP/IP applications for BSD-based systems 103 have knowledge of the size of an IP address. Those parts of the API 104 that expose the addresses must be changed to accommodate the larger IPv6 105 address size. IPv6 also introduces new features (e.g., traffic class 106 and flowlabel), some of which must be made visible to applications via 107 the API. This memo defines a set of extensions to the socket interface 108 to support the larger address size and new features of IPv6. It defines 109 "basic" extensions that are of use to a broad range of applications. A 110 companion document, the "advanced" API [4], covers extensions that are 111 of use to more specialized applications, examples of which include 112 routing daemons, and the "ping" and "traceroute" utilities. 114 The development of this API was started in 1994 in the IETF IPng working 115 group. The API has evolved over the years, published first in RFC 2133, 116 then again in RFC 2553, and reaching its final form in this document. 118 As the API matured and stabilized, it was incorporated into the Open 119 Group's Networking Services (XNS) specification, issue 5.2, which was 120 subsequently incorporated into a joint Open Group/IEEE/ISO standard [3]. 122 Effort has been made to ensure that this document and [3] contain the 123 same information with regard to the API definitions. However, the 124 reader should note that this document is for informational purposes 125 only, and that the official standard specification of the sockets API is 126 [3]. 128 It is expected that any future standardization work on this API would be 129 done by the Open Group Base Working Group [6]. 131 It should also be noted that this document describes only those portions 132 of the API needed for IPv4 and IPv6 communications. Other potential 133 uses of the API, for example the use of getaddrinfo() and getnameinfo() 134 with the AF_UNIX address family, are beyond the scope of this document. 136 2. Design Considerations 138 There are a number of important considerations in designing changes to 139 this well-worn API: 141 - The API changes should provide both source and binary 142 compatibility for programs written to the original API. That 143 is, existing program binaries should continue to operate when 144 run on a system supporting the new API. In addition, existing 145 applications that are re-compiled and run on a system supporting 146 the new API should continue to operate. Simply put, the API 147 changes for IPv6 should not break existing programs. An additional 148 mechanism for implementations to verify this is to verify the new 149 symbols are protected by Feature Test Macros as described in [3]. 150 (Such Feature Test Macros are not defined by this RFC.) 152 - The changes to the API should be as small as possible in order 153 to simplify the task of converting existing IPv4 applications to 154 IPv6. 156 - Where possible, applications should be able to use this 157 API to interoperate with both IPv6 and IPv4 hosts. Applications 158 should not need to know which type of host they are 159 communicating with. 161 - IPv6 addresses carried in data structures should be 64-bit 162 aligned. This is necessary in order to obtain optimum 163 performance on 64-bit machine architectures. 165 Because of the importance of providing IPv4 compatibility in the API, 166 these extensions are explicitly designed to operate on machines that 167 provide complete support for both IPv4 and IPv6. A subset of this API 168 could probably be designed for operation on systems that support only 169 IPv6. However, this is not addressed in this memo. 171 2.1 What Needs to be Changed 173 The socket interface API consists of a few distinct components: 175 - Core socket functions. 177 - Address data structures. 179 - Name-to-address translation functions. 181 - Address conversion functions. 183 The core socket functions -- those functions that deal with such things 184 as setting up and tearing down TCP connections, and sending and 185 receiving UDP packets -- were designed to be transport independent. 186 Where protocol addresses are passed as function arguments, they are 187 carried via opaque pointers. A protocol-specific address data structure 188 is defined for each protocol that the socket functions support. 189 Applications must cast pointers to these protocol-specific address 190 structures into pointers to the generic "sockaddr" address structure 191 when using the socket functions. These functions need not change for 192 IPv6, but a new IPv6-specific address data structure is needed. 194 The "sockaddr_in" structure is the protocol-specific data structure for 195 IPv4. This data structure actually includes 8-octets of unused space, 196 and it is tempting to try to use this space to adapt the sockaddr_in 197 structure to IPv6. Unfortunately, the sockaddr_in structure is not 198 large enough to hold the 16-octet IPv6 address as well as the other 199 information (address family and port number) that is needed. So a new 200 address data structure must be defined for IPv6. 202 IPv6 addresses are scoped [2] so they could be link-local, site, 203 organization, global, or other scopes at this time undefined. To 204 support applications that want to be able to identify a set of 205 interfaces for a specific scope, the IPv6 sockaddr_in structure must 206 support a field that can be used by an implementation to identify a set 207 of interfaces identifying the scope for an IPv6 address. 209 The IPv4 name-to-address translation functions in the socket interface 210 are gethostbyname() and gethostbyaddr(). These are left as is, and new 211 functions are defined which support both IPv4 and IPv6. 213 The IPv4 address conversion functions -- inet_ntoa() and inet_addr() -- 214 convert IPv4 addresses between binary and printable form. These 215 functions are quite specific to 32-bit IPv4 addresses. We have designed 216 two analogous functions that convert both IPv4 and IPv6 addresses, and 217 carry an address type parameter so that they can be extended to other 218 protocol families as well. 220 Finally, a few miscellaneous features are needed to support IPv6. New 221 interfaces are needed to support the IPv6 traffic class, flow label, and 222 hop limit header fields. New socket options are needed to control the 223 sending and receiving of IPv6 multicast packets. 225 The socket interface will be enhanced in the future to provide access to 226 other IPv6 features. These extensions are described in [4]. 228 2.2 Data Types 230 The data types of the structure elements given in this memo are intended 231 to track the relevant standards. uintN_t means an unsigned integer of 232 exactly N bits (e.g., uint16_t). The sa_family_t and in_port_t types 233 are defined in [3]. 235 2.3 Headers 237 When function prototypes and structures are shown we show the headers 238 that must be #included to cause that item to be defined. 240 2.4 Structures 242 When structures are described the members shown are the ones that must 243 appear in an implementation. Additional, nonstandard members may also 244 be defined by an implementation. As an additional precaution 245 nonstandard members could be verified by Feature Test Macros as 246 described in [3]. (Such Feature Test Macros are not defined by this 247 RFC.) 249 The ordering shown for the members of a structure is the recommended 250 ordering, given alignment considerations of multibyte members, but an 251 implementation may order the members differently. 253 3. Socket Interface 255 This section specifies the socket interface changes for IPv6. 257 3.1 IPv6 Address Family and Protocol Family 259 A new address family name, AF_INET6, is defined in . The 260 AF_INET6 definition distinguishes between the original sockaddr_in 261 address data structure, and the new sockaddr_in6 data structure. 263 A new protocol family name, PF_INET6, is defined in . 264 Like most of the other protocol family names, this will usually be 265 defined to have the same value as the corresponding address family name: 267 #define PF_INET6 AF_INET6 269 The AF_INET6 is used in the first argument to the socket() function to 270 indicate that an IPv6 socket is being created. 272 3.2 IPv6 Address Structure 274 A new in6_addr structure holds a single IPv6 address and is defined as a 275 result of including : 277 struct in6_addr { 278 uint8_t s6_addr[16]; /* IPv6 address */ 279 }; 281 This data structure contains an array of sixteen 8-bit elements, which 282 make up one 128-bit IPv6 address. The IPv6 address is stored in network 283 byte order. 285 The structure in6_addr above is usually implemented with an embedded 286 union with extra fields that force the desired alignment level in a 287 manner similar to BSD implementations of "struct in_addr". Those 288 additional implementation details are omitted here for simplicity. 290 An example is as follows: 292 struct in6_addr { 293 union { 294 uint8_t _S6_u8[16]; 295 uint32_t _S6_u32[4]; 296 uint64_t _S6_u64[2]; 297 } _S6_un; 298 }; 299 #define s6_addr _S6_un._S6_u8 301 3.3 Socket Address Structure for 4.3BSD-Based Systems 303 In the socket interface, a different protocol-specific data structure is 304 defined to carry the addresses for each protocol suite. Each protocol- 305 specific data structure is designed so it can be cast into a protocol- 306 independent data structure -- the "sockaddr" structure. Each has a 307 "family" field that overlays the "sa_family" of the sockaddr data 308 structure. This field identifies the type of the data structure. 310 The sockaddr_in structure is the protocol-specific address data 311 structure for IPv4. It is used to pass addresses between applications 312 and the system in the socket functions. The following sockaddr_in6 313 structure holds IPv6 addresses and is defined as a result of including 314 the header: 316 struct sockaddr_in6 { 317 sa_family_t sin6_family; /* AF_INET6 */ 318 in_port_t sin6_port; /* transport layer port # */ 319 uint32_t sin6_flowinfo; /* IPv6 traffic class & flow info */ 320 struct in6_addr sin6_addr; /* IPv6 address */ 321 uint32_t sin6_scope_id; /* set of interfaces for a scope */ 322 }; 324 This structure is designed to be compatible with the sockaddr data 325 structure used in the 4.3BSD release. 327 The sin6_family field identifies this as a sockaddr_in6 structure. This 328 field overlays the sa_family field when the buffer is cast to a sockaddr 329 data structure. The value of this field must be AF_INET6. 331 The sin6_port field contains the 16-bit UDP or TCP port number. This 332 field is used in the same way as the sin_port field of the sockaddr_in 333 structure. The port number is stored in network byte order. 335 The sin6_flowinfo field is a 32-bit field that contains two pieces of 336 information: the traffic class and the flow label. The contents and 337 interpretation of this member is specified in [1]. 339 The sin6_addr field is a single in6_addr structure (defined in the 340 previous section). This field holds one 128-bit IPv6 address. The 341 address is stored in network byte order. 343 The ordering of elements in this structure is specifically designed so 344 that when sin6_addr field is aligned on a 64-bit boundary, the start of 345 the structure will also be aligned on a 64-bit boundary. This is done 346 for optimum performance on 64-bit architectures. 348 The sin6_scope_id field is a 32-bit integer that identifies a set of 349 interfaces as appropriate for the scope [2] of the address carried in 350 the sin6_addr field. The mapping of sin6_scope_id to an interface or 351 set of interfaces is left to implementation and future specifications on 352 the subject of scoped addresses. 354 Notice that the sockaddr_in6 structure will normally be larger than the 355 generic sockaddr structure. On many existing implementations the 356 sizeof(struct sockaddr_in) equals sizeof(struct sockaddr), with both 357 being 16 bytes. Any existing code that makes this assumption needs to 358 be examined carefully when converting to IPv6. 360 3.4 Socket Address Structure for 4.4BSD-Based Systems 362 The 4.4BSD release includes a small, but incompatible change to the 363 socket interface. The "sa_family" field of the sockaddr data structure 364 was changed from a 16-bit value to an 8-bit value, and the space saved 365 used to hold a length field, named "sa_len". The sockaddr_in6 data 366 structure given in the previous section cannot be correctly cast into 367 the newer sockaddr data structure. For this reason, the following 368 alternative IPv6 address data structure is provided to be used on 369 systems based on 4.4BSD. It is defined as a result of including the 370 header. 372 struct sockaddr_in6 { 373 uint8_t sin6_len; /* length of this struct */ 374 sa_family_t sin6_family; /* AF_INET6 */ 375 in_port_t sin6_port; /* transport layer port # */ 376 uint32_t sin6_flowinfo; /* IPv6 flow information */ 377 struct in6_addr sin6_addr; /* IPv6 address */ 378 uint32_t sin6_scope_id; /* set of interfaces for a scope */ 379 }; 381 The only differences between this data structure and the 4.3BSD variant 382 are the inclusion of the length field, and the change of the family 383 field to a 8-bit data type. The definitions of all the other fields are 384 identical to the structure defined in the previous section. 386 Systems that provide this version of the sockaddr_in6 data structure 387 must also declare SIN6_LEN as a result of including the 388 header. This macro allows applications to determine whether they are 389 being built on a system that supports the 4.3BSD or 4.4BSD variants of 390 the data structure. 392 3.5 The Socket Functions 394 Applications call the socket() function to create a socket descriptor 395 that represents a communication endpoint. The arguments to the socket() 396 function tell the system which protocol to use, and what format address 397 structure will be used in subsequent functions. For example, to create 398 an IPv4/TCP socket, applications make the call: 400 s = socket(AF_INET, SOCK_STREAM, 0); 402 To create an IPv4/UDP socket, applications make the call: 404 s = socket(AF_INET, SOCK_DGRAM, 0); 406 Applications may create IPv6/TCP and IPv6/UDP sockets (which may also 407 handle IPv4 communication as described in section 3.7) by simply using 408 the constant AF_INET6 instead of AF_INET in the first argument. For 409 example, to create an IPv6/TCP socket, applications make the call: 411 s = socket(AF_INET6, SOCK_STREAM, 0); 413 To create an IPv6/UDP socket, applications make the call: 415 s = socket(AF_INET6, SOCK_DGRAM, 0); 417 Once the application has created a AF_INET6 socket, it must use the 418 sockaddr_in6 address structure when passing addresses in to the system. 419 The functions that the application uses to pass addresses into the 420 system are: 422 bind() 423 connect() 424 sendmsg() 425 sendto() 427 The system will use the sockaddr_in6 address structure to return 428 addresses to applications that are using AF_INET6 sockets. The 429 functions that return an address from the system to an application are: 431 accept() 432 recvfrom() 433 recvmsg() 434 getpeername() 435 getsockname() 437 No changes to the syntax of the socket functions are needed to support 438 IPv6, since all of the "address carrying" functions use an opaque 439 address pointer, and carry an address length as a function argument. 441 3.6 Compatibility with IPv4 Applications 443 In order to support the large base of applications using the original 444 API, system implementations must provide complete source and binary 445 compatibility with the original API. This means that systems must 446 continue to support AF_INET sockets and the sockaddr_in address 447 structure. Applications must be able to create IPv4/TCP and IPv4/UDP 448 sockets using the AF_INET constant in the socket() function, as 449 described in the previous section. Applications should be able to hold 450 a combination of IPv4/TCP, IPv4/UDP, IPv6/TCP and IPv6/UDP sockets 451 simultaneously within the same process. 453 Applications using the original API should continue to operate as they 454 did on systems supporting only IPv4. That is, they should continue to 455 interoperate with IPv4 nodes. 457 3.7 Compatibility with IPv4 Nodes 459 The API also provides a different type of compatibility: the ability for 460 IPv6 applications to interoperate with IPv4 applications. This feature 461 uses the IPv4-mapped IPv6 address format defined in the IPv6 addressing 462 architecture specification [2]. This address format allows the IPv4 463 address of an IPv4 node to be represented as an IPv6 address. The IPv4 464 address is encoded into the low-order 32 bits of the IPv6 address, and 465 the high-order 96 bits hold the fixed prefix 0:0:0:0:0:FFFF. IPv4- 466 mapped addresses are written as follows: 468 ::FFFF: 470 These addresses can be generated automatically by the getaddrinfo() 471 function, as described in Section 6.1. 473 Applications may use AF_INET6 sockets to open TCP connections to IPv4 474 nodes, or send UDP packets to IPv4 nodes, by simply encoding the 475 destination's IPv4 address as an IPv4-mapped IPv6 address, and passing 476 that address, within a sockaddr_in6 structure, in the connect() or 477 sendto() call. When applications use AF_INET6 sockets to accept TCP 478 connections from IPv4 nodes, or receive UDP packets from IPv4 nodes, the 479 system returns the peer's address to the application in the accept(), 480 recvfrom(), or getpeername() call using a sockaddr_in6 structure encoded 481 this way. 483 Few applications will likely need to know which type of node they are 484 interoperating with. However, for those applications that do need to 485 know, the IN6_IS_ADDR_V4MAPPED() macro, defined in Section 6.7, is 486 provided. 488 3.8 IPv6 Wildcard Address 490 While the bind() function allows applications to select the source IP 491 address of UDP packets and TCP connections, applications often want the 492 system to select the source address for them. With IPv4, one specifies 493 the address as the symbolic constant INADDR_ANY (called the "wildcard" 494 address) in the bind() call, or simply omits the bind() entirely. 496 Since the IPv6 address type is a structure (struct in6_addr), a symbolic 497 constant can be used to initialize an IPv6 address variable, but cannot 498 be used in an assignment. Therefore systems provide the IPv6 wildcard 499 address in two forms. 501 The first version is a global variable named "in6addr_any" that is an 502 in6_addr structure. The extern declaration for this variable is defined 503 in : 505 extern const struct in6_addr in6addr_any; 507 Applications use in6addr_any similarly to the way they use INADDR_ANY in 508 IPv4. For example, to bind a socket to port number 23, but let the 509 system select the source address, an application could use the following 510 code: 512 struct sockaddr_in6 sin6; 513 . . . 514 sin6.sin6_family = AF_INET6; 515 sin6.sin6_flowinfo = 0; 516 sin6.sin6_port = htons(23); 517 sin6.sin6_addr = in6addr_any; /* structure assignment */ 518 . . . 519 if (bind(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 520 . . . 522 The other version is a symbolic constant named IN6ADDR_ANY_INIT and is 523 defined in . This constant can be used to initialize an 524 in6_addr structure: 526 struct in6_addr anyaddr = IN6ADDR_ANY_INIT; 528 Note that this constant can be used ONLY at declaration time. It can 529 not be used to assign a previously declared in6_addr structure. For 530 example, the following code will not work: 532 /* This is the WRONG way to assign an unspecified address */ 533 struct sockaddr_in6 sin6; 534 . . . 535 sin6.sin6_addr = IN6ADDR_ANY_INIT; /* will NOT compile */ 537 Be aware that the IPv4 INADDR_xxx constants are all defined in host byte 538 order but the IPv6 IN6ADDR_xxx constants and the IPv6 in6addr_xxx 539 externals are defined in network byte order. 541 3.9 IPv6 Loopback Address 543 Applications may need to send UDP packets to, or originate TCP 544 connections to, services residing on the local node. In IPv4, they can 545 do this by using the constant IPv4 address INADDR_LOOPBACK in their 546 connect(), sendto(), or sendmsg() call. 548 IPv6 also provides a loopback address to contact local TCP and UDP 549 services. Like the unspecified address, the IPv6 loopback address is 550 provided in two forms -- a global variable and a symbolic constant. 552 The global variable is an in6_addr structure named "in6addr_loopback." 553 The extern declaration for this variable is defined in : 555 extern const struct in6_addr in6addr_loopback; 557 Applications use in6addr_loopback as they would use INADDR_LOOPBACK in 558 IPv4 applications (but beware of the byte ordering difference mentioned 559 at the end of the previous section). For example, to open a TCP 560 connection to the local telnet server, an application could use the 561 following code: 563 struct sockaddr_in6 sin6; 564 . . . 565 sin6.sin6_family = AF_INET6; 566 sin6.sin6_flowinfo = 0; 567 sin6.sin6_port = htons(23); 568 sin6.sin6_addr = in6addr_loopback; /* structure assignment */ 569 . . . 570 if (connect(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 571 . . . 573 The symbolic constant is named IN6ADDR_LOOPBACK_INIT and is defined in 574 . It can be used at declaration time ONLY; for example: 576 struct in6_addr loopbackaddr = IN6ADDR_LOOPBACK_INIT; 578 Like IN6ADDR_ANY_INIT, this constant cannot be used in an assignment to 579 a previously declared IPv6 address variable. 581 3.10 Portability Additions 583 One simple addition to the sockets API that can help application writers 584 is the "struct sockaddr_storage". This data structure can simplify 585 writing code that is portable across multiple address families and 586 platforms. This data structure is designed with the following goals. 588 - Large enough to accommodate all supported protocol-specific address 589 structures. 591 - Aligned at an appropriate boundary so that pointers to it can be cast 592 as pointers to protocol specific address structures and used to 593 access the fields of those structures without alignment problems. 595 The sockaddr_storage structure contains field ss_family which is of type 596 sa_family_t. When a sockaddr_storage structure is cast to a sockaddr 597 structure, the ss_family field of the sockaddr_storage structure maps 598 onto the sa_family field of the sockaddr structure. When a 599 sockaddr_storage structure is cast as a protocol specific address 600 structure, the ss_family field maps onto a field of that structure that 601 is of type sa_family_t and that identifies the protocol's address 602 family. 604 An example implementation design of such a data structure would be as 605 follows. 607 /* 608 * Desired design of maximum size and alignment 609 */ 610 #define _SS_MAXSIZE 128 /* Implementation specific max size */ 611 #define _SS_ALIGNSIZE (sizeof (int64_t)) 612 /* Implementation specific desired alignment */ 613 /* 614 * Definitions used for sockaddr_storage structure paddings design. 615 */ 616 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof (sa_family_t)) 617 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t) + 618 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 619 struct sockaddr_storage { 620 sa_family_t ss_family; /* address family */ 621 /* Following fields are implementation specific */ 622 char __ss_pad1[_SS_PAD1SIZE]; 623 /* 6 byte pad, this is to make implementation 624 /* specific pad up to alignment field that */ 625 /* follows explicit in the data structure */ 626 int64_t __ss_align; /* field to force desired structure */ 627 /* storage alignment */ 628 char __ss_pad2[_SS_PAD2SIZE]; 629 /* 112 byte pad to achieve desired size, */ 630 /* _SS_MAXSIZE value minus size of ss_family */ 631 /* __ss_pad1, __ss_align fields is 112 */ 632 }; 634 The above example implementation illustrates a data structure which will 635 align on a 64-bit boundary. An implementation-specific field 636 "__ss_align" along with "__ss_pad1" is used to force a 64-bit alignment 637 which covers proper alignment good enough for the needs of sockaddr_in6 638 (IPv6), sockaddr_in (IPv4) address data structures. The size of padding 639 field __ss_pad1 depends on the chosen alignment boundary. The size of 640 padding field __ss_pad2 depends on the value of overall size chosen for 641 the total size of the structure. This size and alignment are represented 642 in the above example by implementation specific (not required) constants 643 _SS_MAXSIZE (chosen value 128) and _SS_ALIGNSIZE (with chosen value 8). 644 Constants _SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 645 112) are also for illustration and not required. The derived values 646 assume sa_family_t is 2 bytes. The implementation specific definitions 647 and structure field names above start with an underscore to denote 648 implementation private namespace. Portable code is not expected to 649 access or reference those fields or constants. 651 On implementations where the sockaddr data structure includes a "sa_len" 652 field this data structure would look like this: 654 /* 655 * Definitions used for sockaddr_storage structure paddings design. 656 */ 657 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - 658 (sizeof (uint8_t) + sizeof (sa_family_t)) 659 #define _SS_PAD2SIZE (_SS_MAXSIZE - 660 (sizeof (uint8_t) + sizeof (sa_family_t) + 661 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 662 struct sockaddr_storage { 663 uint8_t ss_len; /* address length */ 664 sa_family_t ss_family; /* address family */ 665 /* Following fields are implementation specific */ 666 char __ss_pad1[_SS_PAD1SIZE]; 667 /* 6 byte pad, this is to make implementation 668 /* specific pad up to alignment field that */ 669 /* follows explicit in the data structure */ 670 int64_t __ss_align; /* field to force desired structure */ 671 /* storage alignment */ 672 char __ss_pad2[_SS_PAD2SIZE]; 673 /* 112 byte pad to achieve desired size, */ 674 /* _SS_MAXSIZE value minus size of ss_len, */ 675 /* __ss_family, __ss_pad1, __ss_align fields is 112 */ 676 }; 678 4. Interface Identification 680 This API uses an interface index (a small positive integer) to identify 681 the local interface on which a multicast group is joined (Section 5.3). 682 Additionally, the advanced API [4] uses these same interface indexes to 683 identify the interface on which a datagram is received, or to specify 684 the interface on which a datagram is to be sent. 686 Interfaces are normally known by names such as "le0", "sl1", "ppp2", and 687 the like. On Berkeley-derived implementations, when an interface is 688 made known to the system, the kernel assigns a unique positive integer 689 value (called the interface index) to that interface. These are small 690 positive integers that start at 1. (Note that 0 is never used for an 691 interface index.) There may be gaps so that there is no current 692 interface for a particular positive interface index. 694 This API defines two functions that map between an interface name and 695 index, a third function that returns all the interface names and 696 indexes, and a fourth function to return the dynamic memory allocated by 697 the previous function. How these functions are implemented is left up 698 to the implementation. 4.4BSD implementations can implement these 699 functions using the existing sysctl() function with the NET_RT_IFLIST 700 command. Other implementations may wish to use ioctl() for this 701 purpose. 703 4.1 Name-to-Index 705 The first function maps an interface name into its corresponding index. 707 #include 709 unsigned int if_nametoindex(const char *ifname); 711 If ifname is the name of an interface, the if_nametoindex() function 712 shall return the interface index corresponding to name ifname; 713 otherwise, it shall return zero. No errors are defined. 715 4.2 Index-to-Name 717 The second function maps an interface index into its corresponding name. 719 #include 721 char *if_indextoname(unsigned int ifindex, char *ifname); 723 When this function is called, the ifname argument shall point to a 724 buffer of at least IF_NAMESIZE bytes. The function shall place in this 725 buffer the name of the interface with index ifindex. (IF_NAMESIZE is 726 also defined in and its value includes a terminating null 727 byte at the end of the interface name.) If ifindex is an interface 728 index, then the function shall return the value supplied in ifname, 729 which points to a buffer now containing the interface name. Otherwise, 730 the function shall return a NULL pointer and set errno to indicate the 731 error. If there is no interface corresponding to the specified index, 732 errno is set to ENXIO. If there was a system error (such as running out 733 of memory), errno would be set to the proper value (e.g., ENOMEM). 735 4.3 Return All Interface Names and Indexes 737 The if_nameindex structure holds the information about a single 738 interface and is defined as a result of including the header. 740 struct if_nameindex { 741 unsigned int if_index; /* 1, 2, ... */ 742 char *if_name; /* null terminated name: "le0", ... */ 743 }; 745 The final function returns an array of if_nameindex structures, one 746 structure per interface. 748 #include 750 struct if_nameindex *if_nameindex(void); 752 The end of the array of structures is indicated by a structure with an 753 if_index of 0 and an if_name of NULL. The function returns a NULL 754 pointer upon an error, and would set errno to the appropriate value. 756 The memory used for this array of structures along with the interface 757 names pointed to by the if_name members is obtained dynamically. This 758 memory is freed by the next function. 760 4.4 Free Memory 762 The following function frees the dynamic memory that was allocated by 763 if_nameindex(). 765 #include 767 void if_freenameindex(struct if_nameindex *ptr); 769 The ptr argument shall be a pointer that was returned by if_nameindex(). 770 After if_freenameindex() has been called, the application shall not use 771 the array of which ptr is the address. 773 5. Socket Options 775 A number of new socket options are defined for IPv6. All of these new 776 options are at the IPPROTO_IPV6 level. That is, the "level" parameter 777 in the getsockopt() and setsockopt() calls is IPPROTO_IPV6 when using 778 these options. The constant name prefix IPV6_ is used in all of the new 779 socket options. This serves to clearly identify these options as 780 applying to IPv6. 782 The declaration for IPPROTO_IPV6, the new IPv6 socket options, and 783 related constants defined in this section are obtained by including the 784 header . 786 5.1 Unicast Hop Limit 788 A new setsockopt() option controls the hop limit used in outgoing 789 unicast IPv6 packets. The name of this option is IPV6_UNICAST_HOPS, and 790 it is used at the IPPROTO_IPV6 layer. The following example illustrates 791 how it is used: 793 int hoplimit = 10; 795 if (setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 796 (char *) &hoplimit, sizeof(hoplimit)) == -1) 797 perror("setsockopt IPV6_UNICAST_HOPS"); 799 When the IPV6_UNICAST_HOPS option is set with setsockopt(), the option 800 value given is used as the hop limit for all subsequent unicast packets 801 sent via that socket. If the option is not set, the system selects a 802 default value. The integer hop limit value (called x) is interpreted as 803 follows: 805 x < -1: return an error of EINVAL 806 x == -1: use kernel default 807 0 <= x <= 255: use x 808 x >= 256: return an error of EINVAL 810 The IPV6_UNICAST_HOPS option may be used with getsockopt() to determine 811 the hop limit value that the system will use for subsequent unicast 812 packets sent via that socket. For example: 814 int hoplimit; 815 socklen_t len = sizeof(hoplimit); 817 if (getsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 818 (char *) &hoplimit, &len) == -1) 819 perror("getsockopt IPV6_UNICAST_HOPS"); 820 else 821 printf("Using %d for hop limit.\n", hoplimit); 823 5.2 Sending and Receiving Multicast Packets 825 IPv6 applications may send multicast packets by simply specifying an 826 IPv6 multicast address as the destination address, for example in the 827 destination address argument of the sendto() function. 829 Three socket options at the IPPROTO_IPV6 layer control some of the 830 parameters for sending multicast packets. Setting these options is not 831 required: applications may send multicast packets without using these 832 options. The setsockopt() options for controlling the sending of 833 multicast packets are summarized below. These three options can also be 834 used with getsockopt(). 836 IPV6_MULTICAST_IF 838 Set the interface to use for outgoing multicast packets. 839 The argument is the index of the interface to use. 840 If the interface index is specified as zero, the system 841 selects the interface (for example, by looking up the 842 address in a routing table and using the resulting interface). 844 Argument type: unsigned int 846 IPV6_MULTICAST_HOPS 848 Set the hop limit to use for outgoing multicast packets. 849 (Note a separate option - IPV6_UNICAST_HOPS - is 850 provided to set the hop limit to use for outgoing 851 unicast packets.) 853 The interpretation of the argument is the same 854 as for the IPV6_UNICAST_HOPS option: 856 x < -1: return an error of EINVAL 857 x == -1: use kernel default 858 0 <= x <= 255: use x 859 x >= 256: return an error of EINVAL 860 If IPV6_MULTICAST_HOPS is not set, the default is 1 861 (same as IPv4 today) 863 Argument type: int 865 IPV6_MULTICAST_LOOP 867 If a multicast datagram is sent to a group to which the sending host 868 itself belongs (on the outgoing interface), a copy of the datagram is 869 looped back by the IP layer for local delivery if this option is set to 870 1. If this option is set to 0 a copy is not looped back. Other option 871 values return an error of EINVAL. 873 If IPV6_MULTICAST_LOOP is not set, the default is 1 (loopback; same as 874 IPv4 today). 876 Argument type: unsigned int 878 The reception of multicast packets is controlled by the two setsockopt() 879 options summarized below. An error of EOPNOTSUPP is returned if these 880 two options are used with getsockopt(). 882 IPV6_JOIN_GROUP 884 Join a multicast group on a specified local interface. 885 If the interface index is specified as 0, 886 the kernel chooses the local interface. 887 For example, some kernels look up the multicast group 888 in the normal IPv6 routing table and use the resulting interface. 890 Argument type: struct ipv6_mreq 892 IPV6_LEAVE_GROUP 894 Leave a multicast group on a specified interface. 895 If the interface index is specified as 0, the system 896 may choose a multicast group membership to drop by 897 matching the multicast address only. 899 Argument type: struct ipv6_mreq 901 The argument type of both of these options is the ipv6_mreq structure, 902 defined as a result of including the header; 904 struct ipv6_mreq { 905 struct in6_addr ipv6mr_multiaddr; /* IPv6 multicast addr */ 906 unsigned int ipv6mr_interface; /* interface index */ 907 }; 909 Note that to receive multicast datagrams a process must join the 910 multicast group to which datagrams will be sent. UDP applications must 911 also bind the UDP port to which datagrams will be sent. Some processes 912 also bind the multicast group address to the socket, in addition to the 913 port, to prevent other datagrams destined to that same port from being 914 delivered to the socket. 916 5.3 IPV6_V6ONLY option for AF_INET6 Sockets 918 This socket option restricts AF_INET6 sockets to IPv6 communications 919 only. As stated in section <3.7 Compatibility with IPv4 Nodes>, 920 AF_INET6 sockets may be used for both IPv4 and IPv6 communications. Some 921 applications may want to restrict their use of an AF_INET6 socket to 922 IPv6 communications only. For these applications the IPV6_V6ONLY socket 923 option is defined. When this option is turned on, the socket can be 924 used to send and receive IPv6 packets only. This is an IPPROTO_IPV6 925 level option. This option takes an int value. This is a boolean 926 option. By default this option is turned off. 928 Here is an example of setting this option: 930 int on = 1; 932 if (setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY, 933 (char *)&on, sizeof(on)) == -1) 934 perror("setsockopt IPV6_V6ONLY"); 935 else 936 printf("IPV6_V6ONLY set\n"); 938 Note - This option has no effect on the use of IPv4 Mapped addresses 939 which enter a node as a valid IPv6 addresses for IPv6 communications as 940 defined by Stateless IP/ICMP Translation Algorithm (SIIT) [5]. 942 An example use of this option is to allow two versions of the same 943 server process to run on the same port, one providing service over IPv6, 944 the other providing the same service over IPv4. 946 6. Library Functions 948 New library functions are needed to perform a variety of operations with 949 IPv6 addresses. Functions are needed to lookup IPv6 addresses in the 950 Domain Name System (DNS). Both forward lookup (nodename-to-address 951 translation) and reverse lookup (address-to-nodename translation) need 952 to be supported. Functions are also needed to convert IPv6 addresses 953 between their binary and textual form. 955 We note that the two existing functions, gethostbyname() and 956 gethostbyaddr(), are left as-is. New functions are defined to handle 957 both IPv4 and IPv6 addresses. 959 The commonly used function gethostbyname() is inadequate for many 960 applications, first because it provides no way for the caller to specify 961 anything about the types of addresses desired (IPv4 only, IPv6 only, 962 IPv4-mapped IPv6 are OK, etc.), and second because many implementations 963 of this function are not thread safe. RFC 2133 defined a function named 964 gethostbyname2() but this function was also inadequate, first because 965 its use required setting a global option (RES_USE_INET6) when IPv6 966 addresses were required, and second because a flag argument is needed to 967 provide the caller with additional control over the types of addresses 968 required. The gethostbyname2() function was deprecated in RFC 2553 and 969 is no longer part of the basic API. 971 6.1 Protocol-Independent Nodename and Service Name Translation 973 Nodename-to-address translation is done in a protocol-independent 974 fashion using the getaddrinfo() function. 976 #include 977 #include 979 int getaddrinfo(const char *nodename, const char *servname, 980 const struct addrinfo *hints, struct addrinfo **res); 982 void freeaddrinfo(struct addrinfo *ai); 984 struct addrinfo { 985 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, .. */ 986 int ai_family; /* AF_xxx */ 987 int ai_socktype; /* SOCK_xxx */ 988 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 989 socklen_t ai_addrlen; /* length of ai_addr */ 990 char *ai_canonname; /* canonical name for nodename */ 991 struct sockaddr *ai_addr; /* binary address */ 992 struct addrinfo *ai_next; /* next structure in linked list */ 993 }; 995 The getaddrinfo() function translates the name of a service location 996 (for example, a host name) and/or a service name and returns a set of 997 socket addresses and associated information to be used in creating a 998 socket with which to address the specified service. 1000 The nodename and servname arguments are either null pointers or 1001 pointers to null-terminated strings. One or both of these two 1002 arguments must be a non-null pointer. 1004 The format of a valid name depends on the address family or families. 1005 If a specific family is not given and the name could be interpreted 1006 as valid within multiple supported families, the implementation will 1007 attempt to resolve the name in all supported families and, in absence 1008 of errors, one or more results shall be returned. 1010 If the nodename argument is not null, it can be a descriptive name or 1011 can be an address string. If the specified address family is AF_INET, 1012 AF_INET6, or AF_UNSPEC, valid descriptive names include host names. 1013 If the specified address family is AF_INET or AF_UNSPEC, address 1014 strings using Internet standard dot notation as specified in 1015 inet_addr() are valid. If the specified address family is AF_INET6 1016 or AF_UNSPEC, standard IPv6 text forms described in inet_pton() are 1017 valid. 1019 If nodename is not null, the requested service location is named by 1020 nodename; otherwise, the requested service location is local to the 1021 caller. 1023 If servname is null, the call shall return network-level addresses 1024 for the specified nodename. If servname is not null, it is a null- 1025 terminated character string identifying the requested service. This 1026 can be either a descriptive name or a numeric representation suitable 1027 for use with the address family or families. If the specified address 1028 family is AF_INET, AF_INET6 or AF_UNSPEC, the service can be 1029 specified as a string specifying a decimal port number. 1031 If the argument hints is not null, it refers to a structure 1032 containing input values that may direct the operation by providing 1033 options and by limiting the returned information to a specific socket 1034 type, address family and/or protocol. In this hints structure every 1035 member other than ai_flags, ai_family, ai_socktype and ai_protocol 1036 shall be set to zero or a null pointer. A value of AF_UNSPEC for 1037 ai_family means that the caller shall accept any address family. A 1038 value of zero for ai_socktype means that the caller shall accept any 1039 socket type. A value of zero for ai_protocol means that the caller 1040 shall accept any protocol. If hints is a null pointer, the behavior 1041 shall be as if it referred to a structure containing the value zero 1042 for the ai_flags, ai_socktype and ai_protocol fields, and AF_UNSPEC 1043 for the ai_family field. 1045 Note: 1047 1. If the caller handles only TCP and not UDP, for example, then the 1048 ai_protocol member of the hints structure should be set to 1049 IPPROTO_TCP when getaddrinfo() is called. 1051 2. If the caller handles only IPv4 and not IPv6, then the ai_family 1052 member of the hints structure should be set to AF_INET when 1053 getaddrinfo() is called. 1055 The ai_flags field to which hints parameter points shall be set to 1056 zero or be the bitwise-inclusive OR of one or more of the values 1057 AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, 1058 AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG. 1060 If the AI_PASSIVE flag is specified, the returned address information 1061 shall be suitable for use in binding a socket for accepting incoming 1062 connections for the specified service (i.e. a call to bind()). In 1063 this case, if the nodename argument is null, then the IP address 1064 portion of the socket address structure shall be set to INADDR_ANY 1065 for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address. If the 1066 AI_PASSIVE flag is not specified, the returned address information 1067 shall be suitable for a call to connect() (for a connection-mode 1068 protocol) or for a call to connect(), sendto() or sendmsg() (for a 1069 connectionless protocol). In this case, if the nodename argument is 1070 null, then the IP address portion of the socket address structure 1071 shall be set to the loopback address. This flag is ignored if the 1072 nodename argument is not null. 1074 If the AI_CANONNAME flag is specified and the nodename argument is 1075 not null, the function shall attempt to determine the canonical name 1076 corresponding to nodename (for example, if nodename is an alias or 1077 shorthand notation for a complete name). 1079 If the AI_NUMERICHOST flag is specified, then a non-null nodename 1080 string supplied shall be a numeric host address string. Otherwise, an 1081 [EAI_NONAME] error is returned. This flag shall prevent any type of 1082 name resolution service (for example, the DNS) from being invoked. 1084 If the AI_NUMERICSERV flag is specified, then a non-null servname 1085 string supplied shall be a numeric port string. Otherwise, an 1087 [EAI_NONAME] error shall be returned. This flag shall prevent any 1088 type of name resolution service (for example, NIS+) from being 1089 invoked. 1091 If the AI_V4MAPPED flag is specified along with an ai_family of 1092 AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6 addresses 1093 on finding no matching IPv6 addresses (ai_addrlen shall be 16). 1095 For example, when using the DNS, if no AAAA records are found 1096 then a query is made for A records and any found are returned as 1097 IPv4-mapped IPv6 addresses. 1099 The AI_V4MAPPED flag shall be ignored unless ai_family equals 1100 AF_INET6. 1102 If the AI_ALL flag is used with the AI_V4MAPPED flag, then 1103 getaddrinfo() shall return all matching IPv6 and IPv4 addresses. 1105 For example, when using the DNS, queries are made for both AAAA 1106 records and A records, and getaddrinfo() returns the combined 1107 results of both queries. Any IPv4 addresses found are returned 1108 as IPv4-mapped IPv6 addresses. 1110 The AI_ALL flag without the AI_V4MAPPED flag is ignored. 1112 Note: 1114 When ai_family is not specified (AF_UNSPEC), AI_V4MAPPED and 1115 AI_ALL flags will only be used if AF_INET6 is supported. 1117 If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be 1118 returned only if an IPv4 address is configured on the local system, 1119 and IPv6 addresses shall be returned only if an IPv6 address is 1120 configured on the local system. The loopback address is not 1121 considered for this case as valid as a configured address. 1123 For example, when using the DNS, a query for AAAA records 1124 should occur only if the node has at least one IPv6 address 1125 configured (other than IPv6 loopback) and a query for A records 1126 should occur only if the node has at least one IPv4 address 1127 configured (other than the IPv4 loopback). 1129 The ai_socktype field to which argument hints points specifies the 1130 socket type for the service, as defined for socket(). If a specific 1131 socket type is not given (for example, a value of zero) and the 1132 service name could be interpreted as valid with multiple supported 1133 socket types, the implementation shall attempt to resolve the service 1134 name for all supported socket types and, in the absence of errors, 1135 all possible results shall be returned. A non-zero socket type value 1136 shall limit the returned information to values with the specified 1137 socket type. 1139 If the ai_family field to which hints points has the value AF_UNSPEC, 1140 addresses shall be returned for use with any address family that can 1141 be used with the specified nodename and/or servname. Otherwise, 1142 addresses shall be returned for use only with the specified address 1143 family. If ai_family is not AF_UNSPEC and ai_protocol is not zero, 1144 then addresses are returned for use only with the specified address 1145 family and protocol; the value of ai_protocol shall be interpreted as 1146 in a call to the socket() function with the corresponding values of 1147 ai_family and ai_protocol . 1149 The freeaddrinfo() function frees one or more addrinfo structures 1150 returned by getaddrinfo(), along with any additional storage 1151 associated with those structures (for example, storage pointed to by 1152 the ai_canonname and ai_addr fields; an application must not 1153 reference this storage after the associated addrinfo structure has 1154 been freed). If the ai_next field of the structure is not null, the 1155 entire list of structures is freed. The freeaddrinfo() function must 1156 support the freeing of arbitrary sublists of an addrinfo list 1157 originally returned by getaddrinfo(). 1159 Functions getaddrinfo() and freeaddrinfo() must be thread-safe. 1161 A zero return value for getaddrinfo() indicates successful 1162 completion; a non-zero return value indicates failure. The possible 1163 values for the failures are listed below under Error Return Values. 1165 Upon successful return of getaddrinfo(), the location to which res 1166 points shall refer to a linked list of addrinfo structures, each of 1167 which shall specify a socket address and information for use in 1168 creating a socket with which to use that socket address. The list 1169 shall include at least one addrinfo structure. The ai_next field of 1170 each structure contains a pointer to the next structure on the list, 1171 or a null pointer if it is the last structure on the list. Each 1172 structure on the list shall include values for use with a call to the 1173 socket() function, and a socket address for use with the connect() 1174 function or, if the AI_PASSIVE flag was specified, for use with the 1175 bind() function. The fields ai_family, ai_socktype, and ai_protocol 1176 shall be usable as the arguments to the socket() function to create a 1177 socket suitable for use with the returned address. The fields ai_addr 1178 and ai_addrlen are usable as the arguments to the connect() or bind() 1179 functions with such a socket, according to the AI_PASSIVE flag. 1181 If nodename is not null, and if requested by the AI_CANONNAME flag, 1182 the ai_canonname field of the first returned addrinfo structure shall 1183 point to a null-terminated string containing the canonical name 1184 corresponding to the input nodename; if the canonical name is not 1185 available, then ai_canonname shall refer to the nodename argument or 1186 a string with the same contents. The contents of the ai_flags field 1187 of the returned structures are undefined. 1189 All fields in socket address structures returned by getaddrinfo() 1190 that are not filled in through an explicit argument (for example, 1191 sin6_flowinfo) shall be set to zero. 1193 Note: This makes it easier to compare socket address structures. 1195 Error Return Values: 1197 The getaddrinfo() function shall fail and return the corresponding 1198 value if: 1200 [EAI_AGAIN] The name could not be resolved at this time. Future 1201 attempts may succeed. 1203 [EAI_BADFLAGS] The flags parameter had an invalid value. 1205 [EAI_FAIL] A non-recoverable error occurred when attempting to 1206 resolve the name. 1208 [EAI_FAMILY] The address family was not recognized. 1210 [EAI_MEMORY] There was a memory allocation failure when trying to 1211 allocate storage for the return value. 1213 [EAI_NONAME] The name does not resolve for the supplied parameters. 1214 Neither nodename nor servname were supplied. At least one 1215 of these must be supplied. 1217 [EAI_SERVICE] The service passed was not recognized for the specified 1218 socket type. 1220 [EAI_SOCKTYPE] The intended socket type was not recognized. 1222 [EAI_SYSTEM] A system error occurred; the error code can be found in 1223 errno. 1225 The gai_strerror() function provides a descriptive text string 1226 corresponding to an EAI_xxx error value. 1228 #include 1230 const char *gai_strerror(int ecode); 1232 The argument is one of the EAI_xxx values defined for the getaddrinfo() 1233 and getnameinfo() functions. The return value points to a string 1234 describing the error. If the argument is not one of the EAI_xxx values, 1235 the function still returns a pointer to a string whose contents indicate 1236 an unknown error. 1238 6.2 Socket Address Structure to Node Name and Service Name 1240 The getnameinfo() function is used to translate the contents of a socket 1241 address structure to a node name and/or service name. 1243 #include 1244 #include 1246 int getnameinfo(const struct sockaddr *sa, socklen_t salen, 1247 char *node, socklen_t nodelen, 1248 char *service, socklen_t servicelen, 1249 int flags); 1251 The getnameinfo() function shall translate a socket address to a node 1252 name and service location, all of which are defined as in getaddrinfo(). 1254 The sa argument points to a socket address structure to be translated. 1256 The salen argument holds the size of the socket address structure 1257 pointed to by sa. 1259 If the socket address structure contains an IPv4-mapped IPv6 address or 1260 an IPv4-compatible IPv6 address, the implementation shall extract the 1261 embedded IPv4 address and lookup the node name for that IPv4 address. 1263 Note: The IPv6 unspecified address ("::") and the IPv6 1264 loopback address ("::1") are not IPv4-compatible addresses. 1265 If the address is the IPv6 unspecified address ("::"), a 1266 lookup is not performed, and the [EAI_NONAME] error is returned. 1268 If the node argument is non-NULL and the nodelen argument is nonzero, 1269 then the node argument points to a buffer able to contain up to nodelen 1270 characters that receives the node name as a null-terminated string. If 1271 the node argument is NULL or the nodelen argument is zero, the node name 1272 shall not be returned. If the node's name cannot be located, the numeric 1273 form of the node's address is returned instead of its name. 1275 If the service argument is non-NULL and the servicelen argument is non- 1276 zero, then the service argument points to a buffer able to contain up to 1277 servicelen bytes that receives the service name as a null-terminated 1278 string. If the service argument is NULL or the servicelen argument is 1279 zero, the service name shall not be returned. If the service's name 1280 cannot be located, the numeric form of the service address (for example, 1281 its port number) shall be returned instead of its name. 1283 The arguments node and service cannot both be NULL. 1285 The flags argument is a flag that changes the default actions of the 1286 function. By default the fully-qualified domain name (FQDN) for the host 1287 shall be returned, but: 1289 - If the flag bit NI_NOFQDN is set, only the node name portion of the 1290 FQDN shall be returned for local hosts. 1292 - If the flag bit NI_NUMERICHOST is set, the numeric form of the 1293 host's address shall be returned instead of its name, under all 1294 circumstances. 1296 - If the flag bit NI_NAMEREQD is set, an error shall be returned if the 1297 host's name cannot be located. 1299 - If the flag bit NI_NUMERICSERV is set, the numeric form of the 1300 service address shall be returned (for example, its port number) 1301 instead of its name, under all circumstances. 1303 - If the flag bit NI_NUMERICSCOPE is set, the numeric form of the 1304 scope identifier shall be returned (for example, interface index) 1305 instead of its name. This flag is ignored if the sa argument is 1306 not an IPv6 address. 1308 - If the flag bit NI_DGRAM is set, this indicates that the service is 1309 a datagram service (SOCK_DGRAM). The default behavior shall assume that 1310 the service is a stream service (SOCK_STREAM). 1312 Note: 1314 1. The three NI_NUMERICxxx flags are required to support the "-n" 1315 flags that many commands provide. 1316 2. The NI_DGRAM flag is required for the few AF_INET and AF_INET6 port 1317 numbers (for example, [512,514]) that represent different services 1318 for UDP and TCP. 1320 The getnameinfo() function shall be thread safe. 1322 A zero return value for getnameinfo() indicates successful completion; a 1323 non-zero return value indicates failure. 1325 Upon successful completion, getnameinfo() shall return the node and 1326 service names, if requested, in the buffers provided. The returned names 1327 are always null-terminated strings. 1329 Error Return Values: 1331 The getnameinfo() function shall fail and return the corresponding value 1332 if: 1334 [EAI_AGAIN] The name could not be resolved at this time. 1335 Future attempts may succeed. 1337 [EAI_BADFLAGS] The flags had an invalid value. 1339 [EAI_FAIL] A non-recoverable error occurred. 1341 [EAI_FAMILY] The address family was not recognized or the address 1342 length was invalid for the specified family. 1344 [EAI_MEMORY] There was a memory allocation failure. 1346 [EAI_NONAME] The name does not resolve for the supplied parameters. 1347 NI_NAMEREQD is set and the host's name cannot be located, or 1348 both nodename and servname were null. 1350 [EAI_OVERFLOW] An argument buffer overflowed. 1352 [EAI_SYSTEM] A system error occurred. The error code can be found in 1353 errno. 1355 6.3 Address Conversion Functions 1357 The two IPv4 functions inet_addr() and inet_ntoa() convert an IPv4 1358 address between binary and text form. IPv6 applications need similar 1359 functions. The following two functions convert both IPv6 and IPv4 1360 addresses: 1362 #include 1364 int inet_pton(int af, const char *src, void *dst); 1366 const char *inet_ntop(int af, const void *src, 1367 char *dst, socklen_t size); 1369 The inet_pton() function shall convert an address in its standard text 1370 presentation form into its numeric binary form. The af argument shall 1371 specify the family of the address. The AF_INET and AF_INET6 address 1372 families shall be supported. The src argument points to the string 1373 being passed in. The dst argument points to a buffer into which the 1374 function stores the numeric address; this shall be large enough to hold 1375 the numeric address (32 bits for AF_INET, 128 bits for AF_INET6). The 1376 inet_pton() function shall return 1 if the conversion succeeds, with the 1377 address pointed to by dst in network byte order. It shall return 0 if 1378 the input is not a valid IPv4 dotted-decimal string or a valid IPv6 1379 address string, or -1 with errno set to EAFNOSUPPORT if the af argument 1380 is unknown. 1382 If the af argument of inet_pton() is AF_INET, the src string shall be in 1383 the standard IPv4 dotted-decimal form: 1385 ddd.ddd.ddd.ddd 1387 where "ddd" is a one to three digit decimal number between 0 and 255. 1388 The inet_pton() function does not accept other formats (such as the 1389 octal numbers, hexadecimal numbers, and fewer than four numbers that 1390 inet_addr() accepts). 1392 If the af argument of inet_pton() is AF_INET6, the src string shall be 1393 in one of the standard IPv6 text forms defined in Section 2.2 of the 1394 addressing architecture specification [2]. 1396 The inet_ntop() function shall convert a numeric address into a text 1397 string suitable for presentation. The af argument shall specify the 1398 family of the address. This can be AF_INET or AF_INET6. The src 1399 argument points to a buffer holding an IPv4 address if the af argument 1400 is AF_INET, or an IPv6 address if the af argument is AF_INET6; the 1401 address must be in network byte order. The dst argument points to a 1402 buffer where the function stores the resulting text string; it shall not 1403 be NULL. The size argument specifies the size of this buffer, which 1404 shall be large enough to hold the text string (INET_ADDRSTRLEN 1405 characters for IPv4, INET6_ADDRSTRLEN characters for IPv6). 1407 In order to allow applications to easily declare buffers of the proper 1408 size to store IPv4 and IPv6 addresses in string form, the following two 1409 constants are defined in : 1411 #define INET_ADDRSTRLEN 16 1412 #define INET6_ADDRSTRLEN 46 1414 The inet_ntop() function shall return a pointer to the buffer containing 1415 the text string if the conversion succeeds, and NULL otherwise. Upon 1416 failure, errno is set to EAFNOSUPPORT if the af argument is invalid or 1417 ENOSPC if the size of the result buffer is inadequate. 1419 6.4 Address Testing Macros 1421 The following macros can be used to test for special IPv6 addresses. 1423 #include 1425 int IN6_IS_ADDR_UNSPECIFIED (const struct in6_addr *); 1426 int IN6_IS_ADDR_LOOPBACK (const struct in6_addr *); 1427 int IN6_IS_ADDR_MULTICAST (const struct in6_addr *); 1428 int IN6_IS_ADDR_LINKLOCAL (const struct in6_addr *); 1429 int IN6_IS_ADDR_SITELOCAL (const struct in6_addr *); 1430 int IN6_IS_ADDR_V4MAPPED (const struct in6_addr *); 1431 int IN6_IS_ADDR_V4COMPAT (const struct in6_addr *); 1433 int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); 1434 int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); 1435 int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); 1436 int IN6_IS_ADDR_MC_ORGLOCAL (const struct in6_addr *); 1437 int IN6_IS_ADDR_MC_GLOBAL (const struct in6_addr *); 1439 The first seven macros return true if the address is of the specified 1440 type, or false otherwise. The last five test the scope of a multicast 1441 address and return true if the address is a multicast address of the 1442 specified scope or false if the address is either not a multicast 1443 address or not of the specified scope. 1445 Note that IN6_IS_ADDR_LINKLOCAL and IN6_IS_ADDR_SITELOCAL return true 1446 only for the two types of local-use IPv6 unicast addresses (Link-Local 1447 and Site-Local) defined in [2], and that by this definition, the 1448 IN6_IS_ADDR_LINKLOCAL macro returns false for the IPv6 loopback address 1449 (::1). These two macros do not return true for IPv6 multicast addresses 1450 of either link-local scope or site-local scope. 1452 7. Summary of New Definitions 1454 The following list summarizes the constants, structure, and extern 1455 definitions discussed in this memo, sorted by header. 1457 IF_NAMESIZE 1458 struct if_nameindex{}; 1460 AI_ADDRCONFIG 1461 AI_ALL 1462 AI_CANONNAME 1463 AI_NUMERICHOST 1464 AI_NUMERICSERV 1465 AI_PASSIVE 1466 AI_V4MAPPED 1467 EAI_AGAIN 1468 EAI_BADFLAGS 1469 EAI_FAIL 1470 EAI_FAMILY 1471 EAI_MEMORY 1472 EAI_NONAME 1473 EAI_OVERFLOW 1474 EAI_SERVICE 1475 EAI_SOCKTYPE 1476 EAI_SYSTEM 1477 NI_DGRAM 1478 NI_NAMEREQD 1479 NI_NOFQDN 1480 NI_NUMERICHOST 1481 NI_NUMERICSERV 1482 struct addrinfo{}; 1484 IN6ADDR_ANY_INIT 1485 IN6ADDR_LOOPBACK_INIT 1486 INET6_ADDRSTRLEN 1487 INET_ADDRSTRLEN 1488 IPPROTO_IPV6 1489 IPV6_JOIN_GROUP 1490 IPV6_LEAVE_GROUP 1491 IPV6_MULTICAST_HOPS 1492 IPV6_MULTICAST_IF 1493 IPV6_MULTICAST_LOOP 1494 IPV6_UNICAST_HOPS 1495 IPV6_V6ONLY 1496 SIN6_LEN 1497 extern const struct in6_addr in6addr_any; 1498 extern const struct in6_addr in6addr_loopback; 1499 struct in6_addr{}; 1500 struct ipv6_mreq{}; 1501 struct sockaddr_in6{}; 1503 AF_INET6 1504 PF_INET6 1505 struct sockaddr_storage; 1507 The following list summarizes the function and macro prototypes 1508 discussed in this memo, sorted by header. 1510 int inet_pton(int, const char *, void *); 1511 const char *inet_ntop(int, const void *, 1512 char *, socklen_t); 1514 char *if_indextoname(unsigned int, char *); 1515 unsigned int if_nametoindex(const char *); 1516 void if_freenameindex(struct if_nameindex *); 1517 struct if_nameindex *if_nameindex(void); 1519 int getaddrinfo(const char *, const char *, 1520 const struct addrinfo *, 1521 struct addrinfo **); 1522 int getnameinfo(const struct sockaddr *, socklen_t, 1523 char *, socklen_t, char *, socklen_t, int); 1524 void freeaddrinfo(struct addrinfo *); 1525 const char *gai_strerror(int); 1527 int IN6_IS_ADDR_LINKLOCAL(const struct in6_addr *); 1528 int IN6_IS_ADDR_LOOPBACK(const struct in6_addr *); 1529 int IN6_IS_ADDR_MC_GLOBAL(const struct in6_addr *); 1530 int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); 1531 int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); 1532 int IN6_IS_ADDR_MC_ORGLOCAL(const struct in6_addr *); 1533 int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); 1534 int IN6_IS_ADDR_MULTICAST(const struct in6_addr *); 1535 int IN6_IS_ADDR_SITELOCAL(const struct in6_addr *); 1536 int IN6_IS_ADDR_UNSPECIFIED(const struct in6_addr *); 1537 int IN6_IS_ADDR_V4COMPAT(const struct in6_addr *); 1538 int IN6_IS_ADDR_V4MAPPED(const struct in6_addr *); 1540 8. Security Considerations 1542 IPv6 provides a number of new security mechanisms, many of which need to 1543 be accessible to applications. Companion memos detailing the extensions 1544 to the socket interfaces to support IPv6 security are being written. 1546 Changes from RFC 2553 1548 1. Add brief description of the history of this API and its 1549 relation to the Open Group/IEEE/ISO standards. 1551 2. Alignments with [3]. 1553 3. Removed all references to getipnodebyname() and 1554 getipnodebyaddr(), which are deprecated in favor 1555 of getaddrinfo() and getnameinfo(). 1557 4. Added IPV6_V6ONLY IP level socket option to permit nodes 1558 to not process IPv4 packets as IPv4 Mapped addresses 1559 in implementations. 1561 5. Added SIIT to references and added new contributors. 1563 Acknowledgments 1565 This specification's evolution and completeness were significantly 1566 influenced by the efforts of Richard Stevens, who has passed on. 1567 Richard's wisdom and talent made the specification what it is today. 1568 The co-authors will long think of Richard with great respect. 1570 Thanks to the many people who made suggestions and provided feedback to 1571 this document, including: 1573 Werner Almesberger, Ran Atkinson, Fred Baker, Dave Borman, Andrew 1574 Cherenson, Alex Conta, Alan Cox, Steve Deering, Richard Draves, Francis 1575 Dupont, Robert Elz, Brian Haberman, Jun-ichiro itojun Hagino, Marc 1576 Hasson, Tom Herbert, Bob Hinden, Wan-Yen Hsu, Christian Huitema, Koji 1577 Imada, Markus Jork, Ron Lee, Alan Lloyd, Charles Lynn, Dan McDonald, 1578 Dave Mitton, Finnbarr Murphy, Thomas Narten, Josh Osborne, Craig 1579 Partridge, Jean-Luc Richier, Bill Sommerfield, Erik Scoredos, Keith 1580 Sklower, JINMEI Tatuya, Dave Thaler, Matt Thomas, Harvey Thompson, Dean 1581 D. Throop, Karen Tracey, Glenn Trewitt, Paul Vixie, David Waitzman, Carl 1582 Williams, Kazu Yamamoto, Vlad Yasevich, Stig Venaas, and Brian Zill. 1584 The getaddrinfo() and getnameinfo() functions are taken from an earlier 1585 Internet Draft by Keith Sklower. As noted in that draft, William Durst, 1586 Steven Wise, Michael Karels, and Eric Allman provided many useful 1587 discussions on the subject of protocol-independent name-to-address 1588 translation, and reviewed early versions of Keith Sklower's original 1589 proposal. Eric Allman implemented the first prototype of getaddrinfo(). 1590 The observation that specifying the pair of name and service would 1591 suffice for connecting to a service independent of protocol details was 1592 made by Marshall Rose in a proposal to X/Open for a "Uniform Network 1593 Interface". 1595 Craig Metz, Jack McCann, Erik Nordmark, Tim Hartrick, and Mukesh Kacker 1596 made many contributions to this document. Ramesh Govindan made a number 1597 of contributions and co-authored an earlier version of this memo. 1599 References 1601 [1] S. Deering, R. Hinden, "Internet Protocol, Version 6 (IPv6) 1602 Specification", RFC 2460 Draft Standard. 1604 [2] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture", 1605 RFC 2373, July 1998 Draft Standard. 1607 [3] IEEE Std. 1003.1-2001 Standard for Information Technology -- 1608 Portable Operating System Interface (POSIX) 1610 Open Group Technical Standard: Base Specifications, Issue 6 1611 December 2001 1613 ISO 9945 (pending final approval by ISO) 1615 http://www.opengroup.org/austin 1617 [4] W. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 1618 RFC 2292, February 1998. 1620 [5] E. Nordmark "Stateless IP/ICMP Translation Algorithm (SIIT)" 1621 RFC 2765, February 2000. 1623 [6] The Open Group Base Working Group 1624 http://www.opengroup.org/platform/base.html 1626 Authors' Addresses 1628 Bob Gilligan 1629 Cacheflow, Inc. 1630 650 Almanor Ave. 1631 Sunnyvale, CA 94086 1632 Telephone: 408-220-2084 (voice) 1633 408-220-2250 (fax) 1634 Email: gilligan@cacheflow.com 1636 Susan Thomson 1637 Cisco Systems 1638 499 Thornall Street, 8th floor 1639 Edison, NJ 08837 1640 Telephone: 732-635-3086 1641 Email: sethomso@cisco.com 1643 Jim Bound 1644 Hewlett-Packard Company 1645 110 Spitbrook Road ZKO3-3/W20 1646 Nashua, NH 03062 1647 Telephone: 603-884-0062 1648 Email: Jim.Bound@hp.com 1650 Jack McCann 1651 Hewlett-Packard Company 1652 110 Spitbrook Road ZKO3-3/W20 1653 Nashua, NH 03062 1654 Telephone: 603-884-2608 1655 Email: Jack.McCann@hp.com