idnits 2.17.1 draft-ietf-ipngwg-rfc2553bis-06.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. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 339: '...field SHOULD be set to zero by an impl...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 711 has weird spacing: '...ned int if_na...' == Line 743 has weird spacing: '...ned int if_i...' == Line 769 has weird spacing: '... void if_fr...' == Line 799 has weird spacing: '... int hoplim...' == Line 820 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 (July 2002) is 7949 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 295, but not defined == Missing Reference: '512' is mentioned on line 1320, but not defined == Missing Reference: '514' is mentioned on line 1320, 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: 12 errors (**), 0 flaws (~~), 13 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IPNG Working Group R.E. Gilligan 3 INTERNET-DRAFT: draft-ietf-ipngwg-rfc2553bis-06.txt Cache Flow 4 Obsoletes RFC 2553 S. Thomson 5 Cisco 6 J. Bound 7 J. McCann 8 Hewlett-Packard 9 W. R. Stevens 10 July 2002 12 Basic Socket Interface Extensions for IPv6 14 16 Status of this Memo 18 This document is an Internet-Draft and is in full conformance with 19 all provisions of Section 10 of RFC2026. 21 This document is a submission by the Internet Protocol IPv6 Working 22 Group of the Internet Engineering Task Force (IETF). Comments should 23 be submitted to the ipng@sunroof.eng.sun.com mailing list. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as Internet- 28 Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet- Drafts as reference 33 material or to cite them other than as "work in progress." 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 Abstract 43 The de facto standard application program interface (API) for TCP/IP 44 applications is the "sockets" interface. Although this API was 45 developed for Unix in the early 1980s it has also been implemented on 46 a wide variety of non-Unix systems. TCP/IP applications written 47 using the sockets API have in the past enjoyed a high degree of 48 portability and we would like the same portability with IPv6 49 applications. But changes are required to the sockets API to support 50 IPv6 and this memo describes these changes. These include a new 51 socket address structure to carry IPv6 addresses, new address 52 conversion functions, and some new socket options. These extensions 53 are designed to provide access to the basic IPv6 features required by 54 TCP and UDP applications, including multicasting, while introducing a 55 minimum of change into the system and providing complete 56 compatibility for existing IPv4 applications. Additional extensions 57 for advanced IPv6 features (raw sockets and access to the IPv6 58 extension headers) are defined in another document [4]. 60 Table of Contents: 62 1. Introduction.................................................3 63 2. Design Considerations........................................3 64 2.1 What Needs to be Changed....................................4 65 2.2 Data Types..................................................5 66 2.3 Headers.....................................................5 67 2.4 Structures..................................................5 68 3. Socket Interface.............................................5 69 3.1 IPv6 Address Family and Protocol Family.....................6 70 3.2 IPv6 Address Structure......................................6 71 3.3 Socket Address Structure for 4.3BSD-Based Systems...........6 72 3.4 Socket Address Structure for 4.4BSD-Based Systems...........7 73 3.5 The Socket Functions........................................8 74 3.6 Compatibility with IPv4 Applications........................9 75 3.7 Compatibility with IPv4 Nodes...............................9 76 3.8 IPv6 Wildcard Address......................................10 77 3.9 IPv6 Loopback Address......................................11 78 3.10 Portability Additions.....................................11 79 4. Interface Identification....................................13 80 4.1 Name-to-Index..............................................14 81 4.2 Index-to-Name..............................................14 82 4.3 Return All Interface Names and Indexes.....................14 83 4.4 Free Memory................................................15 84 5. Socket Options..............................................15 85 5.1 Unicast Hop Limit..........................................15 86 5.2 Sending and Receiving Multicast Packets....................16 87 5.3 IPV6_V6ONLY option for AF_INET6 Sockets....................18 88 6. Library Functions...........................................18 89 6.1 Protocol-Independent Nodename and Service Name Translation.19 90 6.2 Socket Address Structure to Node Name and Service Name.....23 91 6.3 Address Conversion Functions...............................25 92 6.4 Address Testing Macros.....................................26 93 7. Summary of New Definitions..................................27 94 8. Security Considerations.....................................29 95 Changes from RFC 2553..........................................29 96 Acknowledgments................................................29 97 References.....................................................30 98 Authors' Addresses.............................................31 99 1. Introduction 101 While IPv4 addresses are 32 bits long, IPv6 addresses are 128 bits long. 102 The socket interface makes the size of an IP address quite visible to an 103 application; virtually all TCP/IP applications for BSD-based systems 104 have knowledge of the size of an IP address. Those parts of the API 105 that expose the addresses must be changed to accommodate the larger IPv6 106 address size. IPv6 also introduces new features (e.g., traffic class 107 and flowlabel), some of which must be made visible to applications via 108 the API. This memo defines a set of extensions to the socket interface 109 to support the larger address size and new features of IPv6. It defines 110 "basic" extensions that are of use to a broad range of applications. A 111 companion document, the "advanced" API [4], covers extensions that are 112 of use to more specialized applications, examples of which include 113 routing daemons, and the "ping" and "traceroute" utilities. 115 The development of this API was started in 1994 in the IETF IPng working 116 group. The API has evolved over the years, published first in RFC 2133, 117 then again in RFC 2553, and reaching its final form in this document. 119 As the API matured and stabilized, it was incorporated into the Open 120 Group's Networking Services (XNS) specification, issue 5.2, which was 121 subsequently incorporated into a joint Open Group/IEEE/ISO standard [3]. 123 Effort has been made to ensure that this document and [3] contain the 124 same information with regard to the API definitions. However, the 125 reader should note that this document is for informational purposes 126 only, and that the official standard specification of the sockets API is 127 [3]. 129 It is expected that any future standardization work on this API would be 130 done by the Open Group Base Working Group [6]. 132 It should also be noted that this document describes only those portions 133 of the API needed for IPv4 and IPv6 communications. Other potential 134 uses of the API, for example the use of getaddrinfo() and getnameinfo() 135 with the AF_UNIX address family, are beyond the scope of this document. 137 2. Design Considerations 139 There are a number of important considerations in designing changes to 140 this well-worn API: 142 - The API changes should provide both source and binary 143 compatibility for programs written to the original API. That 144 is, existing program binaries should continue to operate when 145 run on a system supporting the new API. In addition, existing 146 applications that are re-compiled and run on a system supporting 147 the new API should continue to operate. Simply put, the API 148 changes for IPv6 should not break existing programs. An additional 149 mechanism for implementations to verify this is to verify the new 150 symbols are protected by Feature Test Macros as described in [3]. 151 (Such Feature Test Macros are not defined by this RFC.) 153 - The changes to the API should be as small as possible in order 154 to simplify the task of converting existing IPv4 applications to 155 IPv6. 157 - Where possible, applications should be able to use this 158 API to interoperate with both IPv6 and IPv4 hosts. Applications 159 should not need to know which type of host they are 160 communicating with. 162 - IPv6 addresses carried in data structures should be 64-bit 163 aligned. This is necessary in order to obtain optimum 164 performance on 64-bit machine architectures. 166 Because of the importance of providing IPv4 compatibility in the API, 167 these extensions are explicitly designed to operate on machines that 168 provide complete support for both IPv4 and IPv6. A subset of this API 169 could probably be designed for operation on systems that support only 170 IPv6. However, this is not addressed in this memo. 172 2.1 What Needs to be Changed 174 The socket interface API consists of a few distinct components: 176 - Core socket functions. 178 - Address data structures. 180 - Name-to-address translation functions. 182 - Address conversion functions. 184 The core socket functions -- those functions that deal with such things 185 as setting up and tearing down TCP connections, and sending and 186 receiving UDP packets -- were designed to be transport independent. 187 Where protocol addresses are passed as function arguments, they are 188 carried via opaque pointers. A protocol-specific address data structure 189 is defined for each protocol that the socket functions support. 190 Applications must cast pointers to these protocol-specific address 191 structures into pointers to the generic "sockaddr" address structure 192 when using the socket functions. These functions need not change for 193 IPv6, but a new IPv6-specific address data structure is needed. 195 The "sockaddr_in" structure is the protocol-specific data structure for 196 IPv4. This data structure actually includes 8-octets of unused space, 197 and it is tempting to try to use this space to adapt the sockaddr_in 198 structure to IPv6. Unfortunately, the sockaddr_in structure is not 199 large enough to hold the 16-octet IPv6 address as well as the other 200 information (address family and port number) that is needed. So a new 201 address data structure must be defined for IPv6. 203 IPv6 addresses are scoped [2] so they could be link-local, site, 204 organization, global, or other scopes at this time undefined. To 205 support applications that want to be able to identify a set of 206 interfaces for a specific scope, the IPv6 sockaddr_in structure must 207 support a field that can be used by an implementation to identify a set 208 of interfaces identifying the scope for an IPv6 address. 210 The IPv4 name-to-address translation functions in the socket interface 211 are gethostbyname() and gethostbyaddr(). These are left as is, and new 212 functions are defined which support both IPv4 and IPv6. 214 The IPv4 address conversion functions -- inet_ntoa() and inet_addr() -- 215 convert IPv4 addresses between binary and printable form. These 216 functions are quite specific to 32-bit IPv4 addresses. We have designed 217 two analogous functions that convert both IPv4 and IPv6 addresses, and 218 carry an address type parameter so that they can be extended to other 219 protocol families as well. 221 Finally, a few miscellaneous features are needed to support IPv6. New 222 interfaces are needed to support the IPv6 traffic class, flow label, and 223 hop limit header fields. New socket options are needed to control the 224 sending and receiving of IPv6 multicast packets. 226 The socket interface will be enhanced in the future to provide access to 227 other IPv6 features. These extensions are described in [4]. 229 2.2 Data Types 231 The data types of the structure elements given in this memo are intended 232 to track the relevant standards. uintN_t means an unsigned integer of 233 exactly N bits (e.g., uint16_t). The sa_family_t and in_port_t types 234 are defined in [3]. 236 2.3 Headers 238 When function prototypes and structures are shown we show the headers 239 that must be #included to cause that item to be defined. 241 2.4 Structures 243 When structures are described the members shown are the ones that must 244 appear in an implementation. Additional, nonstandard members may also 245 be defined by an implementation. As an additional precaution 246 nonstandard members could be verified by Feature Test Macros as 247 described in [3]. (Such Feature Test Macros are not defined by this 248 RFC.) 250 The ordering shown for the members of a structure is the recommended 251 ordering, given alignment considerations of multibyte members, but an 252 implementation may order the members differently. 254 3. Socket Interface 256 This section specifies the socket interface changes for IPv6. 258 3.1 IPv6 Address Family and Protocol Family 260 A new address family name, AF_INET6, is defined in . The 261 AF_INET6 definition distinguishes between the original sockaddr_in 262 address data structure, and the new sockaddr_in6 data structure. 264 A new protocol family name, PF_INET6, is defined in . 265 Like most of the other protocol family names, this will usually be 266 defined to have the same value as the corresponding address family name: 268 #define PF_INET6 AF_INET6 270 The AF_INET6 is used in the first argument to the socket() function to 271 indicate that an IPv6 socket is being created. 273 3.2 IPv6 Address Structure 275 A new in6_addr structure holds a single IPv6 address and is defined as a 276 result of including : 278 struct in6_addr { 279 uint8_t s6_addr[16]; /* IPv6 address */ 280 }; 282 This data structure contains an array of sixteen 8-bit elements, which 283 make up one 128-bit IPv6 address. The IPv6 address is stored in network 284 byte order. 286 The structure in6_addr above is usually implemented with an embedded 287 union with extra fields that force the desired alignment level in a 288 manner similar to BSD implementations of "struct in_addr". Those 289 additional implementation details are omitted here for simplicity. 291 An example is as follows: 293 struct in6_addr { 294 union { 295 uint8_t _S6_u8[16]; 296 uint32_t _S6_u32[4]; 297 uint64_t _S6_u64[2]; 298 } _S6_un; 299 }; 300 #define s6_addr _S6_un._S6_u8 302 3.3 Socket Address Structure for 4.3BSD-Based Systems 304 In the socket interface, a different protocol-specific data structure is 305 defined to carry the addresses for each protocol suite. Each protocol- 306 specific data structure is designed so it can be cast into a protocol- 307 independent data structure -- the "sockaddr" structure. Each has a 308 "family" field that overlays the "sa_family" of the sockaddr data 309 structure. This field identifies the type of the data structure. 311 The sockaddr_in structure is the protocol-specific address data 312 structure for IPv4. It is used to pass addresses between applications 313 and the system in the socket functions. The following sockaddr_in6 314 structure holds IPv6 addresses and is defined as a result of including 315 the header: 317 struct sockaddr_in6 { 318 sa_family_t sin6_family; /* AF_INET6 */ 319 in_port_t sin6_port; /* transport layer port # */ 320 uint32_t sin6_flowinfo; /* IPv6 traffic class & flow info */ 321 struct in6_addr sin6_addr; /* IPv6 address */ 322 uint32_t sin6_scope_id; /* set of interfaces for a scope */ 323 }; 325 This structure is designed to be compatible with the sockaddr data 326 structure used in the 4.3BSD release. 328 The sin6_family field identifies this as a sockaddr_in6 structure. This 329 field overlays the sa_family field when the buffer is cast to a sockaddr 330 data structure. The value of this field must be AF_INET6. 332 The sin6_port field contains the 16-bit UDP or TCP port number. This 333 field is used in the same way as the sin_port field of the sockaddr_in 334 structure. The port number is stored in network byte order. 336 The sin6_flowinfo field is a 32-bit field that contains two pieces of 337 information: the traffic class and the flow label. The contents and 338 interpretation of this member is specified in [1]. The sin6_flowinfo 339 field SHOULD be set to zero by an implementation prior to using the 340 sockaddr_in6 structure by an application on receive operations. 342 The sin6_addr field is a single in6_addr structure (defined in the 343 previous section). This field holds one 128-bit IPv6 address. The 344 address is stored in network byte order. 346 The ordering of elements in this structure is specifically designed so 347 that when sin6_addr field is aligned on a 64-bit boundary, the start of 348 the structure will also be aligned on a 64-bit boundary. This is done 349 for optimum performance on 64-bit architectures. 351 The sin6_scope_id field is a 32-bit integer that identifies a set of 352 interfaces as appropriate for the scope [2] of the address carried in 353 the sin6_addr field. The mapping of sin6_scope_id to an interface or 354 set of interfaces is left to implementation and future specifications on 355 the subject of scoped addresses. 357 Notice that the sockaddr_in6 structure will normally be larger than the 358 generic sockaddr structure. On many existing implementations the 359 sizeof(struct sockaddr_in) equals sizeof(struct sockaddr), with both 360 being 16 bytes. Any existing code that makes this assumption needs to 361 be examined carefully when converting to IPv6. 363 3.4 Socket Address Structure for 4.4BSD-Based Systems 365 The 4.4BSD release includes a small, but incompatible change to the 366 socket interface. The "sa_family" field of the sockaddr data structure 367 was changed from a 16-bit value to an 8-bit value, and the space saved 368 used to hold a length field, named "sa_len". The sockaddr_in6 data 369 structure given in the previous section cannot be correctly cast into 370 the newer sockaddr data structure. For this reason, the following 371 alternative IPv6 address data structure is provided to be used on 372 systems based on 4.4BSD. It is defined as a result of including the 373 header. 375 struct sockaddr_in6 { 376 uint8_t sin6_len; /* length of this struct */ 377 sa_family_t sin6_family; /* AF_INET6 */ 378 in_port_t sin6_port; /* transport layer port # */ 379 uint32_t sin6_flowinfo; /* IPv6 flow information */ 380 struct in6_addr sin6_addr; /* IPv6 address */ 381 uint32_t sin6_scope_id; /* set of interfaces for a scope */ 382 }; 384 The only differences between this data structure and the 4.3BSD variant 385 are the inclusion of the length field, and the change of the family 386 field to a 8-bit data type. The definitions of all the other fields are 387 identical to the structure defined in the previous section. 389 Systems that provide this version of the sockaddr_in6 data structure 390 must also declare SIN6_LEN as a result of including the 391 header. This macro allows applications to determine whether they are 392 being built on a system that supports the 4.3BSD or 4.4BSD variants of 393 the data structure. 395 3.5 The Socket Functions 397 Applications call the socket() function to create a socket descriptor 398 that represents a communication endpoint. The arguments to the socket() 399 function tell the system which protocol to use, and what format address 400 structure will be used in subsequent functions. For example, to create 401 an IPv4/TCP socket, applications make the call: 403 s = socket(AF_INET, SOCK_STREAM, 0); 405 To create an IPv4/UDP socket, applications make the call: 407 s = socket(AF_INET, SOCK_DGRAM, 0); 409 Applications may create IPv6/TCP and IPv6/UDP sockets (which may also 410 handle IPv4 communication as described in section 3.7) by simply using 411 the constant AF_INET6 instead of AF_INET in the first argument. For 412 example, to create an IPv6/TCP socket, applications make the call: 414 s = socket(AF_INET6, SOCK_STREAM, 0); 416 To create an IPv6/UDP socket, applications make the call: 418 s = socket(AF_INET6, SOCK_DGRAM, 0); 420 Once the application has created a AF_INET6 socket, it must use the 421 sockaddr_in6 address structure when passing addresses in to the system. 422 The functions that the application uses to pass addresses into the 423 system are: 425 bind() 426 connect() 427 sendmsg() 428 sendto() 430 The system will use the sockaddr_in6 address structure to return 431 addresses to applications that are using AF_INET6 sockets. The 432 functions that return an address from the system to an application are: 434 accept() 435 recvfrom() 436 recvmsg() 437 getpeername() 438 getsockname() 440 No changes to the syntax of the socket functions are needed to support 441 IPv6, since all of the "address carrying" functions use an opaque 442 address pointer, and carry an address length as a function argument. 444 3.6 Compatibility with IPv4 Applications 446 In order to support the large base of applications using the original 447 API, system implementations must provide complete source and binary 448 compatibility with the original API. This means that systems must 449 continue to support AF_INET sockets and the sockaddr_in address 450 structure. Applications must be able to create IPv4/TCP and IPv4/UDP 451 sockets using the AF_INET constant in the socket() function, as 452 described in the previous section. Applications should be able to hold 453 a combination of IPv4/TCP, IPv4/UDP, IPv6/TCP and IPv6/UDP sockets 454 simultaneously within the same process. 456 Applications using the original API should continue to operate as they 457 did on systems supporting only IPv4. That is, they should continue to 458 interoperate with IPv4 nodes. 460 3.7 Compatibility with IPv4 Nodes 462 The API also provides a different type of compatibility: the ability for 463 IPv6 applications to interoperate with IPv4 applications. This feature 464 uses the IPv4-mapped IPv6 address format defined in the IPv6 addressing 465 architecture specification [2]. This address format allows the IPv4 466 address of an IPv4 node to be represented as an IPv6 address. The IPv4 467 address is encoded into the low-order 32 bits of the IPv6 address, and 468 the high-order 96 bits hold the fixed prefix 0:0:0:0:0:FFFF. IPv4- 469 mapped addresses are written as follows: 471 ::FFFF: 473 These addresses can be generated automatically by the getaddrinfo() 474 function, as described in Section 6.1. 476 Applications may use AF_INET6 sockets to open TCP connections to IPv4 477 nodes, or send UDP packets to IPv4 nodes, by simply encoding the 478 destination's IPv4 address as an IPv4-mapped IPv6 address, and passing 479 that address, within a sockaddr_in6 structure, in the connect() or 480 sendto() call. When applications use AF_INET6 sockets to accept TCP 481 connections from IPv4 nodes, or receive UDP packets from IPv4 nodes, the 482 system returns the peer's address to the application in the accept(), 483 recvfrom(), or getpeername() call using a sockaddr_in6 structure encoded 484 this way. 486 Few applications will likely need to know which type of node they are 487 interoperating with. However, for those applications that do need to 488 know, the IN6_IS_ADDR_V4MAPPED() macro, defined in Section 6.7, is 489 provided. 491 3.8 IPv6 Wildcard Address 493 While the bind() function allows applications to select the source IP 494 address of UDP packets and TCP connections, applications often want the 495 system to select the source address for them. With IPv4, one specifies 496 the address as the symbolic constant INADDR_ANY (called the "wildcard" 497 address) in the bind() call, or simply omits the bind() entirely. 499 Since the IPv6 address type is a structure (struct in6_addr), a symbolic 500 constant can be used to initialize an IPv6 address variable, but cannot 501 be used in an assignment. Therefore systems provide the IPv6 wildcard 502 address in two forms. 504 The first version is a global variable named "in6addr_any" that is an 505 in6_addr structure. The extern declaration for this variable is defined 506 in : 508 extern const struct in6_addr in6addr_any; 510 Applications use in6addr_any similarly to the way they use INADDR_ANY in 511 IPv4. For example, to bind a socket to port number 23, but let the 512 system select the source address, an application could use the following 513 code: 515 struct sockaddr_in6 sin6; 516 . . . 517 sin6.sin6_family = AF_INET6; 518 sin6.sin6_flowinfo = 0; 519 sin6.sin6_port = htons(23); 520 sin6.sin6_addr = in6addr_any; /* structure assignment */ 521 . . . 522 if (bind(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 523 . . . 525 The other version is a symbolic constant named IN6ADDR_ANY_INIT and is 526 defined in . This constant can be used to initialize an 527 in6_addr structure: 529 struct in6_addr anyaddr = IN6ADDR_ANY_INIT; 531 Note that this constant can be used ONLY at declaration time. It can 532 not be used to assign a previously declared in6_addr structure. For 533 example, the following code will not work: 535 /* This is the WRONG way to assign an unspecified address */ 536 struct sockaddr_in6 sin6; 537 . . . 538 sin6.sin6_addr = IN6ADDR_ANY_INIT; /* will NOT compile */ 540 Be aware that the IPv4 INADDR_xxx constants are all defined in host byte 541 order but the IPv6 IN6ADDR_xxx constants and the IPv6 in6addr_xxx 542 externals are defined in network byte order. 544 3.9 IPv6 Loopback Address 546 Applications may need to send UDP packets to, or originate TCP 547 connections to, services residing on the local node. In IPv4, they can 548 do this by using the constant IPv4 address INADDR_LOOPBACK in their 549 connect(), sendto(), or sendmsg() call. 551 IPv6 also provides a loopback address to contact local TCP and UDP 552 services. Like the unspecified address, the IPv6 loopback address is 553 provided in two forms -- a global variable and a symbolic constant. 555 The global variable is an in6_addr structure named "in6addr_loopback." 556 The extern declaration for this variable is defined in : 558 extern const struct in6_addr in6addr_loopback; 560 Applications use in6addr_loopback as they would use INADDR_LOOPBACK in 561 IPv4 applications (but beware of the byte ordering difference mentioned 562 at the end of the previous section). For example, to open a TCP 563 connection to the local telnet server, an application could use the 564 following code: 566 struct sockaddr_in6 sin6; 567 . . . 568 sin6.sin6_family = AF_INET6; 569 sin6.sin6_flowinfo = 0; 570 sin6.sin6_port = htons(23); 571 sin6.sin6_addr = in6addr_loopback; /* structure assignment */ 572 . . . 573 if (connect(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 574 . . . 576 The symbolic constant is named IN6ADDR_LOOPBACK_INIT and is defined in 577 . It can be used at declaration time ONLY; for example: 579 struct in6_addr loopbackaddr = IN6ADDR_LOOPBACK_INIT; 581 Like IN6ADDR_ANY_INIT, this constant cannot be used in an assignment to 582 a previously declared IPv6 address variable. 584 3.10 Portability Additions 586 One simple addition to the sockets API that can help application writers 587 is the "struct sockaddr_storage". This data structure can simplify 588 writing code that is portable across multiple address families and 589 platforms. This data structure is designed with the following goals. 591 - Large enough to accommodate all supported protocol-specific address 592 structures. 594 - Aligned at an appropriate boundary so that pointers to it can be cast 595 as pointers to protocol specific address structures and used to 596 access the fields of those structures without alignment problems. 598 The sockaddr_storage structure contains field ss_family which is of type 599 sa_family_t. When a sockaddr_storage structure is cast to a sockaddr 600 structure, the ss_family field of the sockaddr_storage structure maps 601 onto the sa_family field of the sockaddr structure. When a 602 sockaddr_storage structure is cast as a protocol specific address 603 structure, the ss_family field maps onto a field of that structure that 604 is of type sa_family_t and that identifies the protocol's address 605 family. 607 An example implementation design of such a data structure would be as 608 follows. 610 /* 611 * Desired design of maximum size and alignment 612 */ 613 #define _SS_MAXSIZE 128 /* Implementation specific max size */ 614 #define _SS_ALIGNSIZE (sizeof (int64_t)) 615 /* Implementation specific desired alignment */ 616 /* 617 * Definitions used for sockaddr_storage structure paddings design. 618 */ 619 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof (sa_family_t)) 620 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 621 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 622 struct sockaddr_storage { 623 sa_family_t ss_family; /* address family */ 624 /* Following fields are implementation specific */ 625 char __ss_pad1[_SS_PAD1SIZE]; 626 /* 6 byte pad, this is to make implementation 627 /* specific pad up to alignment field that */ 628 /* follows explicit in the data structure */ 629 int64_t __ss_align; /* field to force desired structure */ 630 /* storage alignment */ 631 char __ss_pad2[_SS_PAD2SIZE]; 632 /* 112 byte pad to achieve desired size, */ 633 /* _SS_MAXSIZE value minus size of ss_family */ 634 /* __ss_pad1, __ss_align fields is 112 */ 635 }; 637 The above example implementation illustrates a data structure which will 638 align on a 64-bit boundary. An implementation-specific field "_ss_align" 639 along with "_ss_pad1" is used to force a 64-bit alignment which covers 640 proper alignment good enough for the needs of sockaddr_in6 (IPv6), 641 sockaddr_in (IPv4) address data structures. The size of padding field 642 _ss_pad1 depends on the chosen alignment boundary. The size of padding 643 field _ss_pad2 depends on the value of overall size chosen for the total 644 size of the structure. This size and alignment are represented in the 645 above example by implementation specific (not required) constants 646 _SS_MAXSIZE (chosen value 128) and _SS_ALIGNMENT (with chosen value 8). 647 Constants _SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 648 112) are also for illustration and not required. The derived values 649 assume sa_family_t is 2 bytes. The implementation specific definitions 650 and structure field names above start with an underscore to denote 651 implementation private namespace. Portable code is not expected to 652 access or reference those fields or constants. 654 On implementations where sockaddr data structure includes a "sa_len", 655 field this data structure would look like this: 657 /* 658 * Definitions used for sockaddr_storage structure paddings design. 659 */ 660 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - 661 (sizeof (uint8_t) + sizeof (sa_family_t)) 662 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 663 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 664 struct sockaddr_storage { 665 uint8_t ss_len; /* address length */ 666 sa_family_t ss_family; /* address family */ 667 /* Following fields are implementation specific */ 668 char __ss_pad1[_SS_PAD1SIZE]; 669 /* 6 byte pad, this is to make implementation 670 /* specific pad up to alignment field that */ 671 /* follows explicit in the data structure */ 672 int64_t __ss_align; /* field to force desired structure */ 673 /* storage alignment */ 674 char __ss_pad2[_SS_PAD2SIZE]; 675 /* 112 byte pad to achieve desired size, */ 676 /* _SS_MAXSIZE value minus size of ss_len, */ 677 /* __ss_family, __ss_pad1, __ss_align fields is 112 */ 678 }; 680 4. Interface Identification 682 This API uses an interface index (a small positive integer) to identify 683 the local interface on which a multicast group is joined (Section 5.3). 684 Additionally, the advanced API [4] uses these same interface indexes to 685 identify the interface on which a datagram is received, or to specify 686 the interface on which a datagram is to be sent. 688 Interfaces are normally known by names such as "le0", "sl1", "ppp2", and 689 the like. On Berkeley-derived implementations, when an interface is 690 made known to the system, the kernel assigns a unique positive integer 691 value (called the interface index) to that interface. These are small 692 positive integers that start at 1. (Note that 0 is never used for an 693 interface index.) There may be gaps so that there is no current 694 interface for a particular positive interface index. 696 This API defines two functions that map between an interface name and 697 index, a third function that returns all the interface names and 698 indexes, and a fourth function to return the dynamic memory allocated by 699 the previous function. How these functions are implemented is left up 700 to the implementation. 4.4BSD implementations can implement these 701 functions using the existing sysctl() function with the NET_RT_IFLIST 702 command. Other implementations may wish to use ioctl() for this 703 purpose. 705 4.1 Name-to-Index 707 The first function maps an interface name into its corresponding index. 709 #include 711 unsigned int if_nametoindex(const char *ifname); 713 If ifname is the name of an interface, the if_nametoindex() function 714 shall return the interface index corresponding to name ifname; 715 otherwise, it shall return zero. No errors are defined. 717 4.2 Index-to-Name 719 The second function maps an interface index into its corresponding name. 721 #include 723 char *if_indextoname(unsigned int ifindex, char *ifname); 725 When this function is called, the ifname argument shall point to a 726 buffer of at least IF_NAMESIZE bytes. The function shall place in this 727 buffer the name of the interface with index ifindex. (IF_NAMESIZE is 728 also defined in and its value includes a terminating null 729 byte at the end of the interface name.) If ifindex is an interface 730 index, then the function shall return the value supplied in ifname, 731 which points to a buffer now containing the interface name. Otherwise, 732 the function shall return a NULL pointer and set errno to indicate the 733 error. If there is no interface corresponding to the specified index, 734 errno is set to ENXIO. If there was a system error (such as running out 735 of memory), errno would be set to the proper value (e.g., ENOMEM). 737 4.3 Return All Interface Names and Indexes 739 The if_nameindex structure holds the information about a single 740 interface and is defined as a result of including the header. 742 struct if_nameindex { 743 unsigned int if_index; /* 1, 2, ... */ 744 char *if_name; /* null terminated name: "le0", ... */ 745 }; 747 The final function returns an array of if_nameindex structures, one 748 structure per interface. 750 #include 752 struct if_nameindex *if_nameindex(void); 754 The end of the array of structures is indicated by a structure with an 755 if_index of 0 and an if_name of NULL. The function returns a NULL 756 pointer upon an error, and would set errno to the appropriate value. 758 The memory used for this array of structures along with the interface 759 names pointed to by the if_name members is obtained dynamically. This 760 memory is freed by the next function. 762 4.4 Free Memory 764 The following function frees the dynamic memory that was allocated by 765 if_nameindex(). 767 #include 769 void if_freenameindex(struct if_nameindex *ptr); 771 The ptr argument shall be a pointer that was returned by if_nameindex(). 772 After if_freenameindex() has been called, the application shall not use 773 the array of which ptr is the address. 775 Currently net/if.h doesn't have prototype definitions for functions and 776 it is recommended that these definitions be defined in net/if.h as well 777 as the struct if_nameindex{}. 779 5. Socket Options 781 A number of new socket options are defined for IPv6. All of these new 782 options are at the IPPROTO_IPV6 level. That is, the "level" parameter 783 in the getsockopt() and setsockopt() calls is IPPROTO_IPV6 when using 784 these options. The constant name prefix IPV6_ is used in all of the new 785 socket options. This serves to clearly identify these options as 786 applying to IPv6. 788 The declaration for IPPROTO_IPV6, the new IPv6 socket options, and 789 related constants defined in this section are obtained by including the 790 header . 792 5.1 Unicast Hop Limit 794 A new setsockopt() option controls the hop limit used in outgoing 795 unicast IPv6 packets. The name of this option is IPV6_UNICAST_HOPS, and 796 it is used at the IPPROTO_IPV6 layer. The following example illustrates 797 how it is used: 799 int hoplimit = 10; 801 if (setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 802 (char *) &hoplimit, sizeof(hoplimit)) == -1) 803 perror("setsockopt IPV6_UNICAST_HOPS"); 805 When the IPV6_UNICAST_HOPS option is set with setsockopt(), the option 806 value given is used as the hop limit for all subsequent unicast packets 807 sent via that socket. If the option is not set, the system selects a 808 default value. The integer hop limit value (called x) is interpreted as 809 follows: 811 x < -1: return an error of EINVAL 812 x == -1: use kernel default 813 0 <= x <= 255: use x 814 x >= 256: return an error of EINVAL 816 The IPV6_UNICAST_HOPS option may be used with getsockopt() to determine 817 the hop limit value that the system will use for subsequent unicast 818 packets sent via that socket. For example: 820 int hoplimit; 821 socklen_t len = sizeof(hoplimit); 823 if (getsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 824 (char *) &hoplimit, &len) == -1) 825 perror("getsockopt IPV6_UNICAST_HOPS"); 826 else 827 printf("Using %d for hop limit.\n", hoplimit); 829 5.2 Sending and Receiving Multicast Packets 831 IPv6 applications may send multicast packets by simply specifying an 832 IPv6 multicast address as the destination address, for example in the 833 destination address argument of the sendto() function. 835 Three socket options at the IPPROTO_IPV6 layer control some of the 836 parameters for sending multicast packets. Setting these options is not 837 required: applications may send multicast packets without using these 838 options. The setsockopt() options for controlling the sending of 839 multicast packets are summarized below. These three options can also be 840 used with getsockopt(). 842 IPV6_MULTICAST_IF 844 Set the interface to use for outgoing multicast packets. 845 The argument is the index of the interface to use. 846 If the interface index is specified as zero, the system 847 selects the interface (for example, by looking up the 848 address in a routing table and using the resulting interface). 850 Argument type: unsigned int 852 IPV6_MULTICAST_HOPS 854 Set the hop limit to use for outgoing multicast packets. 855 (Note a separate option - IPV6_UNICAST_HOPS - is 856 provided to set the hop limit to use for outgoing 857 unicast packets.) 859 The interpretation of the argument is the same 860 as for the IPV6_UNICAST_HOPS option: 862 x < -1: return an error of EINVAL 863 x == -1: use kernel default 864 0 <= x <= 255: use x 865 x >= 256: return an error of EINVAL 867 If IPV6_MULTICAST_HOPS is not set, the default is 1 868 (same as IPv4 today) 870 Argument type: int 872 IPV6_MULTICAST_LOOP 874 If a multicast datagram is sent to a group to which the sending host 875 itself belongs (on the outgoing interface), a copy of the datagram is 876 looped back by the IP layer for local delivery if this option is set to 877 1. If this option is set to 0 a copy is not looped back. Other option 878 values return an error of EINVAL. 880 If IPV6_MULTICAST_LOOP is not set, the default is 1 (loopback; same as 881 IPv4 today). 883 Argument type: unsigned int 885 The reception of multicast packets is controlled by the two setsockopt() 886 options summarized below. An error of EOPNOTSUPP is returned if these 887 two options are used with getsockopt(). 889 IPV6_JOIN_GROUP 891 Join a multicast group on a specified local interface. 892 If the interface index is specified as 0, 893 the kernel chooses the local interface. 894 For example, some kernels look up the multicast group 895 in the normal IPv6 routing table and use the resulting interface. 897 Argument type: struct ipv6_mreq 899 IPV6_LEAVE_GROUP 901 Leave a multicast group on a specified interface. 902 If the interface index is specified as 0, the system 903 may choose a multicast group membership to drop by 904 matching the multicast address only. 906 Argument type: struct ipv6_mreq 908 The argument type of both of these options is the ipv6_mreq structure, 909 defined as a result of including the header; 911 struct ipv6_mreq { 912 struct in6_addr ipv6mr_multiaddr; /* IPv6 multicast addr */ 913 unsigned int ipv6mr_interface; /* interface index */ 914 }; 916 Note that to receive multicast datagrams a process must join the 917 multicast group to which datagrams will be sent. UDP applications must 918 also bind the UDP port to which datagrams will be sent. Some processes 919 also bind the multicast group address to the socket, in addition to the 920 port, to prevent other datagrams destined to that same port from being 921 delivered to the socket. 923 5.3 IPV6_V6ONLY option for AF_INET6 Sockets 925 This socket option restricts AF_INET6 sockets to IPv6 communications 926 only. As stated in section <3.7 Compatibility with IPv4 Nodes>, 927 AF_INET6 sockets may be used for both IPv4 and IPv6 communications. Some 928 applications may want to restrict their use of an AF_INET6 socket to 929 IPv6 communications only. For these applications the IPV6_V6ONLY socket 930 option is defined. When this option is turned on, the socket can be 931 used to send and receive IPv6 packets only. This is an IPPROTO_IPV6 932 level option. This option takes an int value. This is a boolean 933 option. By default this option is turned off. 935 Here is an example of setting this option: 937 int on = 1; 939 if (setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY, 940 (char *)&on, sizeof(on)) == -1) 941 perror("setsockopt IPV6_V6ONLY"); 942 else 943 printf("IPV6_V6ONLY set0); 945 Note - This option has no effect on the use of IPv4 Mapped addresses 946 which enter a node as a valid IPv6 addresses for IPv6 communications as 947 defined by Stateless IP/ICMP Translation Algorithm (SIIT) [5]. 949 An example use of this option is to allow two versions of the same 950 server process to run on the same port, one providing service over IPv6, 951 the other providing the same service over IPv4. 953 6. Library Functions 955 New library functions are needed to perform a variety of operations with 956 IPv6 addresses. Functions are needed to lookup IPv6 addresses in the 957 Domain Name System (DNS). Both forward lookup (nodename-to-address 958 translation) and reverse lookup (address-to-nodename translation) need 959 to be supported. Functions are also needed to convert IPv6 addresses 960 between their binary and textual form. 962 We note that the two existing functions, gethostbyname() and 963 gethostbyaddr(), are left as-is. New functions are defined to handle 964 both IPv4 and IPv6 addresses. 966 The commonly used function gethostbyname() is inadequate for many 967 applications, first because it provides no way for the caller to specify 968 anything about the types of addresses desired (IPv4 only, IPv6 only, 969 IPv4-mapped IPv6 are OK, etc.), and second because many implementations 970 of this function are not thread safe. RFC 2133 defined a function named 971 gethostbyname2() but this function was also inadequate, first because 972 its use required setting a global option (RES_USE_INET6) when IPv6 973 addresses were required, and second because a flag argument is needed to 974 provide the caller with additional control over the types of addresses 975 required. The gethostbyname2() function was deprecated in RFC 2553 and 976 is no longer part of the basic API. 978 6.1 Protocol-Independent Nodename and Service Name Translation 980 Nodename-to-address translation is done in a protocol-independent 981 fashion using the getaddrinfo() function. 983 #include 984 #include 986 int getaddrinfo(const char *nodename, const char *servname, 987 const struct addrinfo *hints, struct addrinfo **res); 989 void freeaddrinfo(struct addrinfo *ai); 991 struct addrinfo { 992 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, .. */ 993 int ai_family; /* AF_xxx */ 994 int ai_socktype; /* SOCK_xxx */ 995 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 996 socklen_t ai_addrlen; /* length of ai_addr */ 997 char *ai_canonname; /* canonical name for nodename */ 998 struct sockaddr *ai_addr; /* binary address */ 999 struct addrinfo *ai_next; /* next structure in linked list */ 1000 }; 1002 The getaddrinfo() function translates the name of a service location 1003 (for example, a host name) and/or a service name and returns a set of 1004 socket addresses and associated information to be used in creating a 1005 socket with which to address the specified service. 1007 The nodename and servname arguments are either null pointers or 1008 pointers to null-terminated strings. One or both of these two 1009 arguments must be a non-null pointer. 1011 The format of a valid name depends on the address family or families. 1012 If a specific family is not given and the name could be interpreted 1013 as valid within multiple supported families, the implementation will 1014 attempt to resolve the name in all supported families and, in absence 1015 of errors, one or more results shall be returned. 1017 If the nodename argument is not null, it can be a descriptive name or 1018 can be an address string. If the specified address family is AF_INET, 1019 AF_INET6, or AF_UNSPEC, valid descriptive names include host names. 1020 If the specified address family is AF_INET or AF_UNSPEC, address 1021 strings using Internet standard dot notation as specified in 1022 inet_addr() are valid. If the specified address family is AF_INET6 1023 or AF_UNSPEC, standard IPv6 text forms described in inet_ntop() are 1024 valid. 1026 If nodename is not null, the requested service location is named by 1027 nodename; otherwise, the requested service location is local to the 1028 caller. 1030 If servname is null, the call shall return network-level addresses 1031 for the specified nodename. If servname is not null, it is a null- 1032 terminated character string identifying the requested service. This 1033 can be either a descriptive name or a numeric representation suitable 1034 for use with the address family or families. If the specified address 1035 family is AF_INET, AF_INET6 or AF_UNSPEC, the service can be 1036 specified as a string specifying a decimal port number. 1038 If the argument hints is not null, it refers to a structure 1039 containing input values that may direct the operation by providing 1040 options and by limiting the returned information to a specific socket 1041 type, address family and/or protocol. In this hints structure every 1042 member other than ai_flags, ai_family, ai_socktype and ai_protocol 1043 shall be set to zero or a null pointer. A value of AF_UNSPEC for 1044 ai_family means that the caller shall accept any address family. A 1045 value of zero for ai_socktype means that the caller shall accept any 1046 socket type. A value of zero for ai_protocol means that the caller 1047 shall accept any protocol. If hints is a null pointer, the behavior 1048 shall be as if it referred to a structure containing the value zero 1049 for the ai_flags, ai_socktype and ai_protocol fields, and AF_UNSPEC 1050 for the ai_family field. 1052 Note: 1054 1. If the caller handles only TCP and not UDP, for example, then the 1055 ai_protocol member of the hints structure should be set to 1056 IPPROTO_TCP when getaddrinfo() is called. 1058 2. If the caller handles only IPv4 and not IPv6, then the ai_family 1059 member of the hints structure should be set to AF_INET when 1060 getaddrinfo() is called. 1062 The ai_flags field to which hints parameter points shall be set to 1063 zero or be the bitwise-inclusive OR of one or more of the values 1064 AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, 1065 AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG. 1067 If the AI_PASSIVE flag is specified, the returned address information 1068 shall be suitable for use in binding a socket for accepting incoming 1069 connections for the specified service (i.e. a call to bind()). In 1070 this case, if the nodename argument is null, then the IP address 1071 portion of the socket address structure shall be set to INADDR_ANY 1072 for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address. If the 1073 AI_PASSIVE flag is not specified, the returned address information 1074 shall be suitable for a call to connect() (for a connection-mode 1075 protocol) or for a call to connect(), sendto() or sendmsg() (for a 1076 connectionless protocol). In this case, if the nodename argument is 1077 null, then the IP address portion of the socket address structure 1078 shall be set to the loopback address. This flag is ignored if the 1079 nodename argument is not null. 1081 If the AI_CANONNAME flag is specified and the nodename argument is 1082 not null, the function shall attempt to determine the canonical name 1083 corresponding to nodename (for example, if nodename is an alias or 1084 shorthand notation for a complete name). 1086 If the AI_NUMERICHOST flag is specified, then a non-null nodename 1087 string supplied shall be a numeric host address string. Otherwise, an 1088 [EAI_NONAME] error is returned. This flag shall prevent any type of 1089 name resolution service (for example, the DNS) from being invoked. 1091 If the AI_NUMERICSERV flag is specified, then a non-null servname 1092 string supplied shall be a numeric port string. Otherwise, an 1093 [EAI_NONAME] error shall be returned. This flag shall prevent any 1094 type of name resolution service (for example, NIS+) from being 1095 invoked. 1097 If the AI_V4MAPPED flag is specified along with an ai_family of 1098 AF_INET6, then getaddrinfo() shall return IPv4-mapped IPv6 addresses 1099 on finding no matching IPv6 addresses (ai_addrlen shall be 16). 1101 For example, when using the DNS, if no AAAA records are found 1102 then a query is made for A records and any found are returned as 1103 IPv4-mapped IPv6 addresses. 1105 The AI_V4MAPPED flag shall be ignored unless ai_family equals 1106 AF_INET6. 1108 If the AI_ALL flag is used with the AI_V4MAPPED flag, then 1109 getaddrinfo() shall return all matching IPv6 and IPv4 addresses. 1111 For example, when using the DNS, queries are made for both AAAA 1112 records and A records, and getaddrinfo() returns the combined 1113 results of both queries. Any IPv4 addresses found are returned 1114 as IPv4-mapped IPv6 addresses. 1116 The AI_ALL flag without the AI_V4MAPPED flag is ignored. 1118 Note: 1120 When ai_family is not specified (AF_UNSPEC), AI_V4MAPPED and 1121 AI_ALL flags will only be used if AF_INET6 is supported. 1123 If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be 1124 returned only if an IPv4 address is configured on the local system, 1125 and IPv6 addresses shall be returned only if an IPv6 address is 1126 configured on the local system. The loopback address is not 1127 considered for this case as valid as a configured address. 1129 For example, when using the DNS, a query for AAAA records 1130 should occur only if the node has at least one IPv6 address 1131 configured (other than IPv6 loopback) and a query for A records 1132 should occur only if the node has at least one IPv4 address 1133 configured (other than the IPv4 loopback). 1135 The ai_socktype field to which argument hints points specifies the 1136 socket type for the service, as defined for socket(). If a specific 1137 socket type is not given (for example, a value of zero) and the 1138 service name could be interpreted as valid with multiple supported 1139 socket types, the implementation shall attempt to resolve the service 1140 name for all supported socket types and, in the absence of errors, 1141 all possible results shall be returned. A non-zero socket type value 1142 shall limit the returned information to values with the specified 1143 socket type. 1145 If the ai_family field to which hints points has the value AF_UNSPEC, 1146 addresses shall be returned for use with any address family that can 1147 be used with the specified nodename and/or servname. Otherwise, 1148 addresses shall be returned for use only with the specified address 1149 family. If ai_family is not AF_UNSPEC and ai_protocol is not zero, 1150 then addresses are returned for use only with the specified address 1151 family and protocol; the value of ai_protocol shall be interpreted as 1152 in a call to the socket() function with the corresponding values of 1153 ai_family and ai_protocol . 1155 The freeaddrinfo() function frees one or more addrinfo structures 1156 returned by getaddrinfo(), along with any additional storage 1157 associated with those structures. If the ai_next field of the 1158 structure is not null, the entire list of structures is freed. The 1159 freeaddrinfo() function must support the freeing of arbitrary 1160 sublists of an addrinfo list originally returned by getaddrinfo(). 1162 Functions getaddrinfo() and freeaddrinfo() must be thread-safe. 1164 A zero return value for getaddrinfo() indicates successful 1165 completion; a non-zero return value indicates failure. The possible 1166 values for the failures are listed below under Error Return Values. 1168 Upon successful return of getaddrinfo(), the location to which res 1169 points shall refer to a linked list of addrinfo structures, each of 1170 which shall specify a socket address and information for use in 1171 creating a socket with which to use that socket address. The list 1172 shall include at least one addrinfo structure. The ai_next field of 1173 each structure contains a pointer to the next structure on the list, 1174 or a null pointer if it is the last structure on the list. Each 1175 structure on the list shall include values for use with a call to the 1176 socket() function, and a socket address for use with the connect() 1177 function or, if the AI_PASSIVE flag was specified, for use with the 1178 bind() function. The fields ai_family, ai_socktype, and ai_protocol 1179 shall be usable as the arguments to the socket() function to create a 1180 socket suitable for use with the returned address. The fields ai_addr 1181 and ai_addrlen are usable as the arguments to the connect() or bind() 1182 functions with such a socket, according to the AI_PASSIVE flag. 1184 If nodename is not null, and if requested by the AI_CANONNAME flag, 1185 the ai_canonname field of the first returned addrinfo structure shall 1186 point to a null-terminated string containing the canonical name 1187 corresponding to the input nodename; if the canonical name is not 1188 available, then ai_canonname shall refer to the nodename argument or 1189 a string with the same contents. The contents of the ai_flags field 1190 of the returned structures are undefined. 1192 All fields in socket address structures returned by getaddrinfo() 1193 that are not filled in through an explicit argument (for example, 1194 sin6_flowinfo) shall be set to zero. 1196 Note: This makes it easier to compare socket address structures. 1198 Error Return Values: 1200 The getaddrinfo() function shall fail and return the corresponding 1201 value if: 1203 [EAI_AGAIN] The name could not be resolved at this time. Future 1204 attempts may succeed. 1206 [EAI_BADFLAGS] The flags parameter had an invalid value. 1208 [EAI_FAIL] A non-recoverable error occurred when attempting to 1209 resolve the name. 1211 [EAI_FAMILY] The address family was not recognized. 1213 [EAI_MEMORY] There was a memory allocation failure when trying to 1214 allocate storage for the return value. 1216 [EAI_NONAME] The name does not resolve for the supplied parameters. 1217 Neither nodename nor servname were supplied. At least one 1218 of these must be supplied. 1220 [EAI_SERVICE] The service passed was not recognized for the specified 1221 socket type. 1223 [EAI_SOCKTYPE] The intended socket type was not recognized. 1225 [EAI_SYSTEM] A system error occurred; the error code can be found in 1226 errno. 1228 The gai_strerror() function provides a descriptive text string 1229 corresponding to an EAI_xxx error value. 1231 #include 1233 const char *gai_strerror(int ecode); 1235 The argument is one of the EAI_xxx values defined for the getaddrinfo() 1236 and getnameinfo() functions. The return value points to a string 1237 describing the error. If the argument is not one of the EAI_xxx values, 1238 the function still returns a pointer to a string whose contents indicate 1239 an unknown error. 1241 6.2 Socket Address Structure to Node Name and Service Name 1243 The getnameinfo() function is used to translate the contents of a socket 1244 address structure to a node name and/or service name. 1246 #include 1247 #include 1249 int getnameinfo(const struct sockaddr *sa, socklen_t salen, 1250 char *node, socklen_t nodelen, 1251 char *service, socklen_t servicelen, 1252 int flags); 1254 The getnameinfo() function shall translate a socket address to a node 1255 name and service location, all of which are defined as in getaddrinfo(). 1257 The sa argument points to a socket address structure to be translated. 1259 The salen argument holds the size of the socket address structure 1260 pointed to by sa. 1262 If the socket address structure contains an IPv4-mapped IPv6 address or 1263 an IPv4-compatible IPv6 address, the implementation shall extract the 1264 embedded IPv4 address and lookup the node name for that IPv4 address. 1266 Note: The IPv6 unspecified address ("::") and the IPv6 1267 loopback address ("::1") are not IPv4-compatible addresses. 1268 If the address is the IPv6 unspecified address ("::"), a 1269 lookup is not performed, and the [EAI_NONAME] error is returned. 1271 If the node argument is non-NULL and the nodelen argument is nonzero, 1272 then the node argument points to a buffer able to contain up to nodelen 1273 characters that receives the node name as a null-terminated string. If 1274 the node argument is NULL or the nodelen argument is zero, the node name 1275 shall not be returned. If the node's name cannot be located, the numeric 1276 form of the node's address is returned instead of its name. 1278 If the service argument is non-NULL and the servicelen argument is non- 1279 zero, then the service argument points to a buffer able to contain up to 1280 servicelen bytes that receives the service name as a null-terminated 1281 string. If the service argument is NULL or the servicelen argument is 1282 zero, the service name shall not be returned. If the service's name 1283 cannot be located, the numeric form of the service address (for example, 1284 its port number) shall be returned instead of its name. 1286 The arguments node and service cannot both be NULL. 1288 The flags argument is a flag that changes the default actions of the 1289 function. By default the fully-qualified domain name (FQDN) for the host 1290 shall be returned, but: 1292 - If the flag bit NI_NOFQDN is set, only the node name portion of the 1293 FQDN shall be returned for local hosts. 1295 - If the flag bit NI_NUMERICHOST is set, the numeric form of the 1296 host's address shall be returned instead of its name, under all 1297 circumstances. 1299 - If the flag bit NI_NAMEREQD is set, an error shall be returned if the 1300 host's name cannot be located. 1302 - If the flag bit NI_NUMERICSERV is set, the numeric form of the 1303 service address shall be returned (for example, its port number) 1304 instead of its name, under all circumstances. 1306 - If the flag bit NI_NUMERICSCOPE is set, the numeric form of the 1307 scope identifier shall be returned (for example, interface index) 1308 instead of its name. This flag is ignored if the sa argument is 1309 not an IPv6 address. 1311 - If the flag bit NI_DGRAM is set, this indicates that the service is 1312 a datagram service (SOCK_DGRAM). The default behavior shall assume that 1313 the service is a stream service (SOCK_STREAM). 1315 Note: 1317 1. The three NI_NUMERICxxx flags are required to support the "-n" 1318 flags that many commands provide. 1319 2. The NI_DGRAM flag is required for the few AF_INET and AF_INET6 port 1320 numbers (for example, [512,514]) that represent different services 1321 for UDP and TCP. 1323 The getnameinfo() function shall be thread safe. 1325 A zero return value for getnameinfo() indicates successful completion; a 1326 non-zero return value indicates failure. 1328 Upon successful completion, getnameinfo() shall return the node and 1329 service names, if requested, in the buffers provided. The returned names 1330 are always null-terminated strings. 1332 Error Return Values: 1334 The getnameinfo() function shall fail and return the corresponding value 1335 if: 1337 [EAI_AGAIN] The name could not be resolved at this time. 1338 Future attempts may succeed. 1340 [EAI_BADFLAGS] The flags had an invalid value. 1342 [EAI_FAIL] A non-recoverable error occurred. 1344 [EAI_FAMILY] The address family was not recognized or the address 1345 length was invalid for the specified family. 1347 [EAI_MEMORY] There was a memory allocation failure. 1349 [EAI_NONAME] The name does not resolve for the supplied parameters. 1350 NI_NAMEREQD is set and the host's name cannot be located, or 1351 both nodename and servname were null. 1353 [EAI_OVERFLOW] An argument buffer overflowed. 1355 [EAI_SYSTEM] A system error occurred. The error code can be found in 1356 errno. 1358 6.3 Address Conversion Functions 1360 The two IPv4 functions inet_addr() and inet_ntoa() convert an IPv4 1361 address between binary and text form. IPv6 applications need similar 1362 functions. The following two functions convert both IPv6 and IPv4 1363 addresses: 1365 #include 1367 int inet_pton(int af, const char *src, void *dst); 1369 const char *inet_ntop(int af, const void *src, 1370 char *dst, socklen_t size); 1372 The inet_pton() function shall convert an address in its standard text 1373 presentation form into its numeric binary form. The af argument shall 1374 specify the family of the address. The AF_INET and AF_INET6 address 1375 families shall be supported. The src argument points to the string 1376 being passed in. The dst argument points to a buffer into which the 1377 function stores the numeric address; this shall be large enough to hold 1378 the numeric address (32 bits for AF_INET, 128 bits for AF_INET6). The 1379 inet_pton() function shall return 1 if the conversion succeeds, with the 1380 address pointed to by dst in network byte order. It shall return 0 if 1381 the input is not a valid IPv4 dotted-decimal string or a valid IPv6 1382 address string, or -1 with errno set to EAFNOSUPPORT if the af argument 1383 is unknown. 1385 If the af argument of inet_pton() is AF_INET, the src string shall be in 1386 the standard IPv4 dotted-decimal form: 1388 ddd.ddd.ddd.ddd 1390 where "ddd" is a one to three digit decimal number between 0 and 255. 1391 The inet_pton() function does not accept other formats (such as the 1392 octal numbers, hexadecimal numbers, and fewer than four numbers that 1393 inet_addr() accepts). 1395 If the af argument of inet_pton() is AF_INET6, the src string shall be 1396 in one of the standard IPv6 text forms defined in Section 2.2 of the 1397 addressing architecture specification [2]. 1399 The inet_ntop() function shall convert a numeric address into a text 1400 string suitable for presentation. The af argument shall specify the 1401 family of the address. This can be AF_INET or AF_INET6. The src 1402 argument points to a buffer holding an IPv4 address if the af argument 1403 is AF_INET, or an IPv6 address if the af argument is AF_INET6; the 1404 address must be in network byte order. The dst argument points to a 1405 buffer where the function stores the resulting text string; it shall not 1406 be NULL. The size argument specifies the size of this buffer, which 1407 shall be large enough to hold the text string (INET_ADDRSTRLEN 1408 characters for IPv4, INET6_ADDRSTRLEN characters for IPv6). 1410 In order to allow applications to easily declare buffers of the proper 1411 size to store IPv4 and IPv6 addresses in string form, the following two 1412 constants are defined in : 1414 #define INET_ADDRSTRLEN 16 1415 #define INET6_ADDRSTRLEN 46 1417 The inet_ntop() function shall return a pointer to the buffer containing 1418 the text string if the conversion succeeds, and NULL otherwise. Upon 1419 failure, errno is set to EAFNOSUPPORT if the af argument is invalid or 1420 ENOSPC if the size of the result buffer is inadequate. 1422 6.4 Address Testing Macros 1424 The following macros can be used to test for special IPv6 addresses. 1426 #include 1428 int IN6_IS_ADDR_UNSPECIFIED (const struct in6_addr *); 1429 int IN6_IS_ADDR_LOOPBACK (const struct in6_addr *); 1430 int IN6_IS_ADDR_MULTICAST (const struct in6_addr *); 1431 int IN6_IS_ADDR_LINKLOCAL (const struct in6_addr *); 1432 int IN6_IS_ADDR_SITELOCAL (const struct in6_addr *); 1433 int IN6_IS_ADDR_V4MAPPED (const struct in6_addr *); 1434 int IN6_IS_ADDR_V4COMPAT (const struct in6_addr *); 1436 int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); 1437 int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); 1438 int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); 1439 int IN6_IS_ADDR_MC_ORGLOCAL (const struct in6_addr *); 1440 int IN6_IS_ADDR_MC_GLOBAL (const struct in6_addr *); 1442 The first seven macros return true if the address is of the specified 1443 type, or false otherwise. The last five test the scope of a multicast 1444 address and return true if the address is a multicast address of the 1445 specified scope or false if the address is either not a multicast 1446 address or not of the specified scope. 1448 Note that IN6_IS_ADDR_LINKLOCAL and IN6_IS_ADDR_SITELOCAL return true 1449 only for the two types of local-use IPv6 unicast addresses (Link-Local 1450 and Site-Local) defined in [2], and that by this definition, the 1451 IN6_IS_ADDR_LINKLOCAL macro returns false for the IPv6 loopback address 1452 (::1). These two macros do not return true for IPv6 multicast addresses 1453 of either link-local scope or site-local scope. 1455 7. Summary of New Definitions 1457 The following list summarizes the constants, structure, and extern 1458 definitions discussed in this memo, sorted by header. 1460 IF_NAMESIZE 1461 struct if_nameindex{}; 1463 AI_ADDRCONFIG 1464 AI_ALL 1465 AI_CANONNAME 1466 AI_NUMERICHOST 1467 AI_NUMERICSERV 1468 AI_PASSIVE 1469 AI_V4MAPPED 1470 EAI_AGAIN 1471 EAI_BADFLAGS 1472 EAI_FAIL 1473 EAI_FAMILY 1474 EAI_MEMORY 1475 EAI_NONAME 1476 EAI_OVERFLOW 1477 EAI_SERVICE 1478 EAI_SOCKTYPE 1479 EAI_SYSTEM 1480 NI_DGRAM 1481 NI_NAMEREQD 1482 NI_NOFQDN 1483 NI_NUMERICHOST 1484 NI_NUMERICSERV 1485 struct addrinfo{}; 1487 IN6ADDR_ANY_INIT 1488 IN6ADDR_LOOPBACK_INIT 1489 INET6_ADDRSTRLEN 1490 INET_ADDRSTRLEN 1491 IPPROTO_IPV6 1492 IPV6_JOIN_GROUP 1493 IPV6_LEAVE_GROUP 1494 IPV6_MULTICAST_HOPS 1495 IPV6_MULTICAST_IF 1496 IPV6_MULTICAST_LOOP 1497 IPV6_UNICAST_HOPS 1498 IPV6_V6ONLY 1499 SIN6_LEN 1500 extern const struct in6_addr in6addr_any; 1501 extern const struct in6_addr in6addr_loopback; 1502 struct in6_addr{}; 1503 struct ipv6_mreq{}; 1504 struct sockaddr_in6{}; 1506 AF_INET6 1507 PF_INET6 1508 struct sockaddr_storage; 1510 The following list summarizes the function and macro prototypes 1511 discussed in this memo, sorted by header. 1513 int inet_pton(int, const char *, void *); 1514 const char *inet_ntop(int, const void *, 1515 char *, socklen_t); 1517 char *if_indextoname(unsigned int, char *); 1518 unsigned int if_nametoindex(const char *); 1519 void if_freenameindex(struct if_nameindex *); 1520 struct if_nameindex *if_nameindex(void); 1522 int getaddrinfo(const char *, const char *, 1523 const struct addrinfo *, 1524 struct addrinfo **); 1525 int getnameinfo(const struct sockaddr *, socklen_t, 1526 char *, socklen_t, char *, socklen_t, int); 1527 void freeaddrinfo(struct addrinfo *); 1528 const char *gai_strerror(int); 1530 int IN6_IS_ADDR_LINKLOCAL(const struct in6_addr *); 1531 int IN6_IS_ADDR_LOOPBACK(const struct in6_addr *); 1532 int IN6_IS_ADDR_MC_GLOBAL(const struct in6_addr *); 1533 int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); 1534 int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); 1535 int IN6_IS_ADDR_MC_ORGLOCAL(const struct in6_addr *); 1536 int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); 1537 int IN6_IS_ADDR_MULTICAST(const struct in6_addr *); 1538 int IN6_IS_ADDR_SITELOCAL(const struct in6_addr *); 1539 int IN6_IS_ADDR_UNSPECIFIED(const struct in6_addr *); 1540 int IN6_IS_ADDR_V4COMPAT(const struct in6_addr *); 1541 int IN6_IS_ADDR_V4MAPPED(const struct in6_addr *); 1543 8. Security Considerations 1545 IPv6 provides a number of new security mechanisms, many of which need to 1546 be accessible to applications. Companion memos detailing the extensions 1547 to the socket interfaces to support IPv6 security are being written. 1549 Changes from RFC 2553 1551 1. Add brief description of the history of this API and its 1552 relation to the Open Group/IEEE/ISO standards. 1554 2. Alignments with [3]. 1556 3. Removed all references to getipnodebyname() and 1557 getipnodebyaddr(), which are deprecated in favor 1558 of getaddrinfo() and getnameinfo(). 1560 4. Added IPV6_V6ONLY IP level socket option to permit nodes 1561 to not process IPv4 packets as IPv4 Mapped addresses 1562 in implementations. 1564 5. Added SIIT to references and added new contributors. 1566 Acknowledgments 1568 This specification's evolution and completeness were significantly 1569 influenced by the efforts of Richard Stevens, who has passed on. Rich's 1570 wisdom and talent made the specification what it is today. The co- 1571 authors will long think of Richard with great respect. 1573 Thanks to the many people who made suggestions and provided feedback to 1574 this document, including: 1576 Werner Almesberger, Ran Atkinson, Fred Baker, Dave Borman, Andrew 1577 Cherenson, Alex Conta, Alan Cox, Steve Deering, Richard Draves, Francis 1578 Dupont, Robert Elz, Brian Haberman, Jun-ichiro itojun Hagino, Marc 1579 Hasson, Tom Herbert, Bob Hinden, Wan-Yen Hsu, Christian Huitema, Koji 1580 Imada, Markus Jork, Ron Lee, Alan Lloyd, Charles Lynn, Dan McDonald, 1581 Dave Mitton, Finnbarr Murphy, Thomas Narten, Josh Osborne, Craig 1582 Partridge, Jean-Luc Richier, Bill Sommerfield, Erik Scoredos, Keith 1583 Sklower, JINMEI Tatuya, Dave Thaler, Matt Thomas, Harvey Thompson, Dean 1584 D. Throop, Karen Tracey, Glenn Trewitt, Paul Vixie, David Waitzman, Carl 1585 Williams, Kazu Yamamoto, Vlad Yasevich, Stig Venaas, and Brian Zill. 1587 The getaddrinfo() and getnameinfo() functions are taken from an earlier 1588 Internet Draft by Keith Sklower. As noted in that draft, William Durst, 1589 Steven Wise, Michael Karels, and Eric Allman provided many useful 1590 discussions on the subject of protocol-independent name-to-address 1591 translation, and reviewed early versions of Keith Sklower's original 1592 proposal. Eric Allman implemented the first prototype of getaddrinfo(). 1593 The observation that specifying the pair of name and service would 1594 suffice for connecting to a service independent of protocol details was 1595 made by Marshall Rose in a proposal to X/Open for a "Uniform Network 1596 Interface". 1598 Craig Metz, Jack McCann, Erik Nordmark, Tim Hartrick, and Mukesh Kacker 1599 made many contributions to this document. Ramesh Govindan made a number 1600 of contributions and co-authored an earlier version of this memo. 1602 References 1604 [1] S. Deering, R. Hinden, "Internet Protocol, Version 6 (IPv6) 1605 Specification", RFC 2460 Draft Standard. 1607 [2] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture", 1608 RFC 2373, July 1998 Draft Standard. 1610 [3] IEEE Std. 1003.1-2001 Standard for Information Technology -- 1611 Portable Operating System Interface (POSIX) 1613 Open Group Technical Standard: Base Specifications, Issue 6 1614 December 2001 1616 ISO 9945 (pending final approval by ISO) 1618 http://www.opengroup.org/austin 1620 [4] W. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 1621 RFC 2292, February 1998. 1623 [5] E. Nordmark "Stateless IP/ICMP Translation Algorithm (SIIT)" 1624 RFC 2765, February 2000. 1626 [6] The Open Group Base Working Group 1627 http://www.opengroup.org/platform/base.html 1629 Authors' Addresses 1631 Bob Gilligan 1632 Cacheflow, Inc. 1633 650 Almanor Ave. 1634 Sunnyvale, CA 94086 1635 Telephone: 408-220-2084 (voice) 1636 408-220-2250 (fax) 1637 Email: gilligan@cacheflow.com 1639 Susan Thomson 1640 Cisco Systems 1641 499 Thornall Street, 8th floor 1642 Edison, NJ 08837 1643 Telephone: 732-635-3086 1644 Email: sethomso@cisco.com 1646 Jim Bound 1647 Hewlett-Packard Company 1648 110 Spitbrook Road ZKO3-3/W20 1649 Nashua, NH 03062 1650 Telephone: 603-884-0062 1651 Email: Jim.Bound@hp.com 1653 Jack McCann 1654 Hewlett-Packard Company 1655 110 Spitbrook Road ZKO3-3/W20 1656 Nashua, NH 03062 1657 Telephone: 603-884-2608 1658 Email: Jack.McCann@hp.com