idnits 2.17.1 draft-ietf-ipngwg-rfc2553bis-03.txt: -(1282): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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? == There are 3 instances of lines with non-ascii characters in the document. == 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 34 instances of too long lines in the document, the longest one being 5 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 318: '...field SHOULD be set to zero by an impl...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 690 has weird spacing: '...ned int if_na...' == Line 721 has weird spacing: '...ned int if_i...' == Line 745 has weird spacing: '... void if_fr...' == Line 774 has weird spacing: '... int hoplim...' == Line 795 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 (February 2001) is 8464 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 274, 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) -- Possible downref: Non-RFC (?) normative reference: ref. '5' -- Possible downref: Non-RFC (?) normative reference: ref. '6' -- Possible downref: Non-RFC (?) normative reference: ref. '7' ** Obsolete normative reference: RFC 2765 (ref. '8') (Obsoleted by RFC 6145) Summary: 12 errors (**), 0 flaws (~~), 12 warnings (==), 7 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-03.txt Cache Flow 3 Obsoletes RFC 2553 S. Thomson 4 Cisco 5 J. Bound 6 Nokia Networks 7 W. R. Stevens 8 February 2001 10 Basic Socket Interface Extensions for IPv6 12 14 Status of this Memo 16 This document is an Internet-Draft and is in full conformance with 17 all provisions of Section 10 of RFC2026. 19 This document is a submission by the Internet Protocol IPv6 Working 20 Group of the Internet Engineering Task Force (IETF). Comments should 21 be submitted to the ipng@sunroof.eng.sun.com mailing list. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF), its areas, and its working groups. Note that 25 other groups may also distribute working documents as Internet- 26 Drafts. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet- Drafts as reference 31 material or to cite them other than as "work in progress." 33 The list of current Internet-Drafts can be accessed at 34 http://www.ietf.org/ietf/1id-abstracts.txt 36 The list of Internet-Draft Shadow Directories can be accessed at 37 http://www.ietf.org/shadow.html. 39 Abstract 41 The de facto standard application program interface (API) for TCP/IP 42 applications is the "sockets" interface. Although this API was 43 developed for Unix in the early 1980s it has also been implemented on a 44 wide variety of non-Unix systems. TCP/IP applications written using the 45 sockets API have in the past enjoyed a high degree of portability and we 46 would like the same portability with IPv6 applications. But changes are 47 required to the sockets API to support IPv6 and this memo describes 48 these changes. These include a new socket address structure to carry 49 IPv6 addresses, new address conversion functions, and some new socket 50 options. These extensions are designed to provide access to the basic 51 IPv6 features required by TCP and UDP applications, including 52 multicasting, while introducing a minimum of change into the system and 53 providing complete compatibility for existing IPv4 applications. 55 Additional extensions for advanced IPv6 features (raw sockets and access 56 to the IPv6 extension headers) are defined in another document [4]. 58 Table of Contents: 60 1. Introduction.................................................4 61 2. Design Considerations........................................4 62 2.1 What Needs to be Changed....................................4 63 2.2 Data Types..................................................6 64 2.3 Headers.....................................................6 65 2.4 Structures..................................................6 66 3. Socket Interface.............................................6 67 3.1 IPv6 Address Family and Protocol Family.....................6 68 3.2 IPv6 Address Structure......................................6 69 3.3 Socket Address Structure for 4.3BSD-Based Systems...........7 70 3.4 Socket Address Structure for 4.4BSD-Based Systems...........8 71 3.5 The Socket Functions........................................9 72 3.6 Compatibility with IPv4 Applications.......................10 73 3.7 Compatibility with IPv4 Nodes..............................10 74 3.8 IPv6 Wildcard Address......................................10 75 3.9 IPv6 Loopback Address......................................11 76 3.10 Portability Additions.....................................12 77 4. Interface Identification....................................14 78 4.1 Name-to-Index..............................................14 79 4.2 Index-to-Name..............................................15 80 4.3 Return All Interface Names and Indexes.....................15 81 4.4 Free Memory................................................15 82 5. Socket Options..............................................16 83 5.1 Unicast Hop Limit..........................................16 84 5.2 Sending and Receiving Multicast Packets....................17 85 5.3 IPV6_V6ONLY option for AF_INET6 Sockets....................18 86 6. Library Functions...........................................19 87 6.1 Protocol-Independent Nodename and Service Name Translation.19 88 6.2 Socket Address Structure to Nodename and Service Name......23 89 6.3 Address Conversion Functions...............................25 90 6.4 Address Testing Macros.....................................26 91 7. Summary of New Definitions..................................27 92 8. Security Considerations.....................................28 93 9. Year 2000 Considerations....................................28 94 Changes made to rfc2553bis-02 to rfc2553bis-03.................29 95 Changes made to rfc2553bis-01 to rfc2553bis-02.................29 96 Changes made to rfc2553bis-00 to rfc2553bis-01.................29 97 Changes made rfc2553 to rfc2553bis-00:.........................29 98 Acknowledgments................................................30 99 References.....................................................30 100 Authors' Addresses.............................................31 101 1. Introduction 103 While IPv4 addresses are 32 bits long, IPv6 interfaces are identified by 104 128-bit addresses. The socket interface makes the size of an IP address 105 quite visible to an application; virtually all TCP/IP applications for 106 BSD-based systems have knowledge of the size of an IP address. Those 107 parts of the API that expose the addresses must be changed to 108 accommodate the larger IPv6 address size. IPv6 also introduces new 109 features (e.g., traffic class and flowlabel), some of which must be made 110 visible to applications via the API. This memo defines a set of 111 extensions to the socket interface to support the larger address size 112 and new features of IPv6. 114 2. Design Considerations 116 There are a number of important considerations in designing changes to 117 this well-worn API: 119 - The API changes should provide both source and binary 120 compatibility for programs written to the original API. That 121 is, existing program binaries should continue to operate when 122 run on a system supporting the new API. In addition, existing 123 applications that are re-compiled and run on a system supporting 124 the new API should continue to operate. Simply put, the API 125 changes for IPv6 should not break existing programs. An additional 126 mechanism for implementations to verify this is to verify the new 127 symbols are protected by Feature Test Macros as described in IEEE Std 128 1003.1-200x. (Such Feature Test Macros are not defined by this RFC.) 130 - The changes to the API should be as small as possible in order 131 to simplify the task of converting existing IPv4 applications to 132 IPv6. 134 - Where possible, applications should be able to use this 135 API to interoperate with both IPv6 and IPv4 hosts. Applications 136 should not need to know which type of host they are 137 communicating with. 139 - IPv6 addresses carried in data structures should be 64-bit 140 aligned. This is necessary in order to obtain optimum 141 performance on 64-bit machine architectures. 143 Because of the importance of providing IPv4 compatibility in the API, 144 these extensions are explicitly designed to operate on machines that 145 provide complete support for both IPv4 and IPv6. A subset of this API 146 could probably be designed for operation on systems that support only 147 IPv6. However, this is not addressed in this memo. 149 2.1 What Needs to be Changed 151 The socket interface API consists of a few distinct components: 153 - Core socket functions. 155 - Address data structures. 157 - Name-to-address translation functions. 159 - Address conversion functions. 161 The core socket functions -- those functions that deal with such things 162 as setting up and tearing down TCP connections, and sending and 163 receiving UDP packets -- were designed to be transport independent. 164 Where protocol addresses are passed as function arguments, they are 165 carried via opaque pointers. A protocol-specific address data structure 166 is defined for each protocol that the socket functions support. 167 Applications must cast pointers to these protocol-specific address 168 structures into pointers to the generic "sockaddr" address structure 169 when using the socket functions. These functions need not change for 170 IPv6, but a new IPv6-specific address data structure is needed. 172 The "sockaddr_in" structure is the protocol-specific data structure for 173 IPv4. This data structure actually includes 8-octets of unused space, 174 and it is tempting to try to use this space to adapt the sockaddr_in 175 structure to IPv6. Unfortunately, the sockaddr_in structure is not 176 large enough to hold the 16-octet IPv6 address as well as the other 177 information (address family and port number) that is needed. So a new 178 address data structure must be defined for IPv6. 180 IPv6 addresses are scoped [2] so they could be link-local, site, 181 organization, global, or other scopes at this time undefined. To 182 support applications that want to be able to identify a set of 183 interfaces for a specific scope, the IPv6 sockaddr_in structure must 184 support a field that can be used by an implementation to identify a set 185 of interfaces identifying the scope for an IPv6 address. 187 The name-to-address translation functions in the socket interface are 188 gethostbyname() and gethostbyaddr(). These are left as is and new 189 functions are defined to support IPv4 and IPv6. The new API is based on 190 the IEEE Std 1003.1-200x draft [3] and specifies a new nodename-to- 191 address translation function which is protocol independent. This 192 function can also be used with IPv4 and IPv6. 194 The address conversion functions -- inet_ntoa() and inet_addr() -- 195 convert IPv4 addresses between binary and printable form. These 196 functions are quite specific to 32-bit IPv4 addresses. We have designed 197 two analogous functions that convert both IPv4 and IPv6 addresses, and 198 carry an address type parameter so that they can be extended to other 199 protocol families as well. 201 Finally, a few miscellaneous features are needed to support IPv6. New 202 interfaces are needed to support the IPv6 traffic class, flow label, and 203 hop limit header fields. New socket options are needed to control the 204 sending and receiving of IPv6 multicast packets. 206 The socket interface will be enhanced in the future to provide access to 207 other IPv6 features. These extensions are described in [4]. 209 2.2 Data Types 211 The data types of the structure elements given in this memo are intended 212 to track the relevant standards. uintN_t means an unsigned integer of 213 exactly N bits (e.g., uint16_t). 215 2.3 Headers 217 When function prototypes and structures are shown we show the headers 218 that must be #included to cause that item to be defined. 220 2.4 Structures 222 When structures are described the members shown are the ones that must 223 appear in an implementation. Additional, nonstandard members may also 224 be defined by an implementation. As an additional precaution 225 nonstandard members could be verified by Feature Test Macros as 226 described in IEEE Std 1003.1-200x. (Such Feature Test Macros are not 227 defined by this RFC.) 229 The ordering shown for the members of a structure is the recommended 230 ordering, given alignment considerations of multibyte members, but an 231 implementation may order the members differently. 233 3. Socket Interface 235 This section specifies the socket interface changes for IPv6. 237 3.1 IPv6 Address Family and Protocol Family 239 A new address family name, AF_INET6, is defined in . The 240 AF_INET6 definition distinguishes between the original sockaddr_in 241 address data structure, and the new sockaddr_in6 data structure. 243 A new protocol family name, PF_INET6, is defined in . 244 Like most of the other protocol family names, this will usually be 245 defined to have the same value as the corresponding address family name: 247 #define PF_INET6 AF_INET6 249 The PF_INET6 is used in the first argument to the socket() function to 250 indicate that an IPv6 socket is being created. 252 3.2 IPv6 Address Structure 254 A new in6_addr structure holds a single IPv6 address and is defined as a 255 result of including : 257 struct in6_addr { 258 uint8_t s6_addr[16]; /* IPv6 address */ 259 }; 261 This data structure contains an array of sixteen 8-bit elements, which 262 make up one 128-bit IPv6 address. The IPv6 address is stored in network 263 byte order. 265 The structure in6_addr above is usually implemented with an embedded 266 union with extra fields that force the desired alignment level in a 267 manner similar to BSD implementations of "struct in_addr". Those 268 additional implementation details are omitted here for simplicity. 270 An example is as follows: 272 struct in6_addr { 273 union { 274 uint8_t _S6_u8[16]; 275 uint32_t _S6_u32[4]; 276 uint64_t _S6_u64[2]; 277 } _S6_un; 278 }; 279 #define s6_addr _S6_un._S6_u8 281 3.3 Socket Address Structure for 4.3BSD-Based Systems 283 In the socket interface, a different protocol-specific data structure is 284 defined to carry the addresses for each protocol suite. Each protocol- 285 specific data structure is designed so it can be cast into a protocol- 286 independent data structure -- the "sockaddr" structure. Each has a 287 "family" field that overlays the "sa_family" of the sockaddr data 288 structure. This field identifies the type of the data structure. 290 The sockaddr_in structure is the protocol-specific address data 291 structure for IPv4. It is used to pass addresses between applications 292 and the system in the socket functions. The following sockaddr_in6 293 structure holds IPv6 addresses and is defined as a result of including 294 the header: 296 struct sockaddr_in6 { 297 sa_family_t sin6_family; /* AF_INET6 */ 298 in_port_t sin6_port; /* transport layer port # */ 299 uint32_t sin6_flowinfo; /* IPv6 traffic class & flow info */ 300 struct in6_addr sin6_addr; /* IPv6 address */ 301 uint32_t sin6_scope_id; /* set of interfaces for a scope */ 302 }; 304 This structure is designed to be compatible with the sockaddr data 305 structure used in the 4.3BSD release. 307 The sin6_family field identifies this as a sockaddr_in6 structure. This 308 field overlays the sa_family field when the buffer is cast to a sockaddr 309 data structure. The value of this field must be AF_INET6. 311 The sin6_port field contains the 16-bit UDP or TCP port number. This 312 field is used in the same way as the sin_port field of the sockaddr_in 313 structure. The port number is stored in network byte order. 315 The sin6_flowinfo field is a 32-bit field that contains two pieces of 316 information: the traffic class and the flow label. The contents and 317 interpretation of this member is specified in [1]. The sin6_flowinfo 318 field SHOULD be set to zero by an implementation prior to using the 319 sockaddr_in6 structure by an application on receive operations. 321 The sin6_addr field is a single in6_addr structure (defined in the 322 previous section). This field holds one 128-bit IPv6 address. The 323 address is stored in network byte order. 325 The ordering of elements in this structure is specifically designed so 326 that when sin6_addr field is aligned on a 64-bit boundary, the start of 327 the structure will also be aligned on a 64-bit boundary. This is done 328 for optimum performance on 64-bit architectures. 330 The sin6_scope_id field is a 32-bit integer that identifies a set of 331 interfaces as appropriate for the scope of the address carried in the 332 sin6_addr field [2,5,6,7]. For a link scope sin6_addr, sin6_scope_id 333 would be an interface index. For a site scope sin6_addr, sin6_scope_id 334 would be a site identifier. The mapping of sin6_scope_id to an 335 interface or set of interfaces is left to implementation and future 336 specifications on the subject of site identifiers. 338 Notice that the sockaddr_in6 structure will normally be larger than the 339 generic sockaddr structure. On many existing implementations the 340 sizeof(struct sockaddr_in) equals sizeof(struct sockaddr), with both 341 being 16 bytes. Any existing code that makes this assumption needs to 342 be examined carefully when converting to IPv6. 344 3.4 Socket Address Structure for 4.4BSD-Based Systems 346 The 4.4BSD release includes a small, but incompatible change to the 347 socket interface. The "sa_family" field of the sockaddr data structure 348 was changed from a 16-bit value to an 8-bit value, and the space saved 349 used to hold a length field, named "sa_len". The sockaddr_in6 data 350 structure given in the previous section cannot be correctly cast into 351 the newer sockaddr data structure. For this reason, the following 352 alternative IPv6 address data structure is provided to be used on 353 systems based on 4.4BSD. It is defined as a result of including the 354 header. 356 struct sockaddr_in6 { 357 uint8_t sin6_len; /* length of this struct */ 358 sa_family_t sin6_family; /* AF_INET6 */ 359 in_port_t sin6_port; /* transport layer port # */ 360 uint32_t sin6_flowinfo; /* IPv6 flow information */ 361 struct in6_addr sin6_addr; /* IPv6 address */ 362 uint32_t sin6_scope_id; /* set of interfaces for a scope */ 363 }; 365 The only differences between this data structure and the 4.3BSD variant 366 are the inclusion of the length field, and the change of the family 367 field to a 8-bit data type. The definitions of all the other fields are 368 identical to the structure defined in the previous section. 370 Systems that provide this version of the sockaddr_in6 data structure 371 must also declare SIN6_LEN as a result of including the 372 header. This macro allows applications to determine whether they are 373 being built on a system that supports the 4.3BSD or 4.4BSD variants of 374 the data structure. 376 3.5 The Socket Functions 378 Applications call the socket() function to create a socket descriptor 379 that represents a communication endpoint. The arguments to the socket() 380 function tell the system which protocol to use, and what format address 381 structure will be used in subsequent functions. For example, to create 382 an IPv4/TCP socket, applications make the call: 384 s = socket(PF_INET, SOCK_STREAM, 0); 386 To create an IPv4/UDP socket, applications make the call: 388 s = socket(PF_INET, SOCK_DGRAM, 0); 390 Applications may create IPv6/TCP and IPv6/UDP sockets by simply using 391 the constant PF_INET6 instead of PF_INET in the first argument. For 392 example, to create an IPv6/TCP socket, applications make the call: 394 s = socket(PF_INET6, SOCK_STREAM, 0); 396 To create an IPv6/UDP socket, applications make the call: 398 s = socket(PF_INET6, SOCK_DGRAM, 0); 400 Once the application has created a PF_INET6 socket, it must use the 401 sockaddr_in6 address structure when passing addresses in to the system. 402 The functions that the application uses to pass addresses into the 403 system are: 405 bind() 406 connect() 407 sendmsg() 408 sendto() 410 The system will use the sockaddr_in6 address structure to return 411 addresses to applications that are using PF_INET6 sockets. The 412 functions that return an address from the system to an application are: 414 accept() 415 recvfrom() 416 recvmsg() 417 getpeername() 418 getsockname() 420 No changes to the syntax of the socket functions are needed to support 421 IPv6, since all of the "address carrying" functions use an opaque 422 address pointer, and carry an address length as a function argument. 424 3.6 Compatibility with IPv4 Applications 426 In order to support the large base of applications using the original 427 API, system implementations must provide complete source and binary 428 compatibility with the original API. This means that systems must 429 continue to support PF_INET sockets and the sockaddr_in address 430 structure. Applications must be able to create IPv4/TCP and IPv4/UDP 431 sockets using the PF_INET constant in the socket() function, as 432 described in the previous section. Applications should be able to hold 433 a combination of IPv4/TCP, IPv4/UDP, IPv6/TCP and IPv6/UDP sockets 434 simultaneously within the same process. 436 Applications using the original API should continue to operate as they 437 did on systems supporting only IPv4. That is, they should continue to 438 interoperate with IPv4 nodes. 440 3.7 Compatibility with IPv4 Nodes 442 The API also provides a different type of compatibility: the ability for 443 IPv6 applications to interoperate with IPv4 applications. This feature 444 uses the IPv4-mapped IPv6 address format defined in the IPv6 addressing 445 architecture specification [2]. This address format allows the IPv4 446 address of an IPv4 node to be represented as an IPv6 address. The IPv4 447 address is encoded into the low-order 32 bits of the IPv6 address, and 448 the high-order 96 bits hold the fixed prefix 0:0:0:0:0:FFFF. IPv4- 449 mapped addresses are written as follows: 451 ::FFFF: 453 These addresses can be generated automatically by the getaddrinfo() 454 function, when the specified host has only IPv4 addresses (as described 455 in Section 6.1 and 6.2). 457 Applications may use PF_INET6 sockets to open TCP connections to IPv4 458 nodes, or send UDP packets to IPv4 nodes, by simply encoding the 459 destination's IPv4 address as an IPv4-mapped IPv6 address, and passing 460 that address, within a sockaddr_in6 structure, in the connect() or 461 sendto() call. When applications use PF_INET6 sockets to accept TCP 462 connections from IPv4 nodes, or receive UDP packets from IPv4 nodes, the 463 system returns the peer's address to the application in the accept(), 464 recvfrom(), or getpeername() call using a sockaddr_in6 structure encoded 465 this way. 467 Few applications will likely need to know which type of node they are 468 interoperating with. However, for those applications that do need to 469 know, the IN6_IS_ADDR_V4MAPPED() macro, defined in Section 6.7, is 470 provided. 472 3.8 IPv6 Wildcard Address 474 While the bind() function allows applications to select the source IP 475 address of UDP packets and TCP connections, applications often want the 476 system to select the source address for them. With IPv4, one specifies 477 the address as the symbolic constant INADDR_ANY (called the "wildcard" 478 address) in the bind() call, or simply omits the bind() entirely. 480 Since the IPv6 address type is a structure (struct in6_addr), a symbolic 481 constant can be used to initialize an IPv6 address variable, but cannot 482 be used in an assignment. Therefore systems provide the IPv6 wildcard 483 address in two forms. 485 The first version is a global variable named "in6addr_any" that is an 486 in6_addr structure. The extern declaration for this variable is defined 487 in : 489 extern const struct in6_addr in6addr_any; 491 Applications use in6addr_any similarly to the way they use INADDR_ANY in 492 IPv4. For example, to bind a socket to port number 23, but let the 493 system select the source address, an application could use the following 494 code: 496 struct sockaddr_in6 sin6; 497 . . . 498 sin6.sin6_family = AF_INET6; 499 sin6.sin6_flowinfo = 0; 500 sin6.sin6_port = htons(23); 501 sin6.sin6_addr = in6addr_any; /* structure assignment */ 502 . . . 503 if (bind(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 504 . . . 506 The other version is a symbolic constant named IN6ADDR_ANY_INIT and is 507 defined in . This constant can be used to initialize an 508 in6_addr structure: 510 struct in6_addr anyaddr = IN6ADDR_ANY_INIT; 512 Note that this constant can be used ONLY at declaration time. It can 513 not be used to assign a previously declared in6_addr structure. For 514 example, the following code will not work: 516 /* This is the WRONG way to assign an unspecified address */ 517 struct sockaddr_in6 sin6; 518 . . . 519 sin6.sin6_addr = IN6ADDR_ANY_INIT; /* will NOT compile */ 521 Be aware that the IPv4 INADDR_xxx constants are all defined in host byte 522 order but the IPv6 IN6ADDR_xxx constants and the IPv6 in6addr_xxx 523 externals are defined in network byte order. 525 3.9 IPv6 Loopback Address 527 Applications may need to send UDP packets to, or originate TCP 528 connections to, services residing on the local node. In IPv4, they can 529 do this by using the constant IPv4 address INADDR_LOOPBACK in their 530 connect(), sendto(), or sendmsg() call. 532 IPv6 also provides a loopback address to contact local TCP and UDP 533 services. Like the unspecified address, the IPv6 loopback address is 534 provided in two forms -- a global variable and a symbolic constant. 536 The global variable is an in6_addr structure named "in6addr_loopback." 537 The extern declaration for this variable is defined in : 539 extern const struct in6_addr in6addr_loopback; 541 Applications use in6addr_loopback as they would use INADDR_LOOPBACK in 542 IPv4 applications (but beware of the byte ordering difference mentioned 543 at the end of the previous section). For example, to open a TCP 544 connection to the local telnet server, an application could use the 545 following code: 547 struct sockaddr_in6 sin6; 548 . . . 549 sin6.sin6_family = AF_INET6; 550 sin6.sin6_flowinfo = 0; 551 sin6.sin6_port = htons(23); 552 sin6.sin6_addr = in6addr_loopback; /* structure assignment */ 553 . . . 554 if (connect(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 555 . . . 557 The symbolic constant is named IN6ADDR_LOOPBACK_INIT and is defined in 558 . It can be used at declaration time ONLY; for example: 560 struct in6_addr loopbackaddr = IN6ADDR_LOOPBACK_INIT; 562 Like IN6ADDR_ANY_INIT, this constant cannot be used in an assignment to 563 a previously declared IPv6 address variable. 565 3.10 Portability Additions 567 One simple addition to the sockets API that can help application writers 568 is the "struct sockaddr_storage". This data structure can simplify 569 writing portable code across multiple address families and platforms. 570 This data structure is designed with the following goals. 572 - Large enough to accommodate all supported protocol-specific address 573 structures. 574 - Aligned at an appropriate boundary so that pointers to it can be cast 575 as pointers to protocol specific address structures and used to 576 access the fields of those structures without alignment problems. 578 The sockaddr_storage structure contains field ss_family which is of type 579 sa_family_t. When a sockaddr_storage structure is cast to a sockaddr 580 structure, the ss_family field of the sockaddr_storage structure maps 581 onto the sa_family field of the sockaddr structure. When a 582 sockaddr_storage structure is cast as a protocol specific address 583 structure, the ss_family field maps onto a field of that structure that 584 is of type sa_family_t and that identifies the protocol's address 585 family. 587 An example implementation design of such a data structure would be as 588 follows. 590 /* 591 * Desired design of maximum size and alignment 592 */ 593 #define _SS_MAXSIZE 128 /* Implementation specific max size */ 594 #define _SS_ALIGNSIZE (sizeof (int64_t)) 595 /* Implementation specific desired alignment */ 596 /* 597 * Definitions used for sockaddr_storage structure paddings design. 598 */ 599 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof (sa_family_t)) 600 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 601 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 602 struct sockaddr_storage { 603 sa_family_t ss_family; /* address family */ 604 /* Following fields are implementation specific */ 605 char __ss_pad1[_SS_PAD1SIZE]; 606 /* 6 byte pad, this is to make implementation 607 /* specific pad up to alignment field that */ 608 /* follows explicit in the data structure */ 609 int64_t __ss_align; /* field to force desired structure */ 610 /* storage alignment */ 611 char __ss_pad2[_SS_PAD2SIZE]; 612 /* 112 byte pad to achieve desired size, */ 613 /* _SS_MAXSIZE value minus size of ss_family */ 614 /* __ss_pad1, __ss_align fields is 112 */ 615 }; 617 The above example implementation illustrates a data structure which 618 will align on a 64-bit boundary. An implementation-specific field 619 "_ss_align" along "_ss_pad1" is used to force a 64-bit alignment which 620 covers proper alignment good enough for needs of sockaddr_in6 (IPv6), 621 sockaddr_in (IPv4) address data structures. The size of padding fields 622 _ss_pad1 depends on the chosen alignment boundary. The size of padding 623 field _ss_pad2 depends on the value of overall size chosen for the total 624 size of the structure. This size and alignment are represented in the 625 above example by implementation specific (not required) constants 626 _SS_MAXSIZE (chosen value 128) and _SS_ALIGNMENT (with chosen value 8). 627 Constants _SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 628 112) are also for illustration and not required. The implementation specific 629 definitions and structure field names above start with an underscore to 630 denote implementation private namespace. Portable code is not expected to 631 access or reference those fields or constants. 633 On implementations where sockaddr data structure includes a "sa_len", 634 field this data structure would look like this: 636 /* 637 * Definitions used for sockaddr_storage structure paddings design. 638 */ 639 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - 640 (sizeof (uint8_t) + sizeof (sa_family_t)) 641 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 642 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 643 struct sockaddr_storage { 644 uint8_t ss_len; /* address length */ 645 sa_family_t ss_family; /* address family */ 646 /* Following fields are implementation specific */ 647 char __ss_pad1[_SS_PAD1SIZE]; 648 /* 6 byte pad, this is to make implementation 649 /* specific pad up to alignment field that */ 650 /* follows explicit in the data structure */ 651 int64_t __ss_align; /* field to force desired structure */ 652 /* storage alignment */ 653 char __ss_pad2[_SS_PAD2SIZE]; 654 /* 112 byte pad to achieve desired size, */ 655 /* _SS_MAXSIZE value minus size of ss_len, */ 656 /* __ss_family, __ss_pad1, __ss_align fields is 112 */ 657 }; 659 4. Interface Identification 661 This API uses an interface index (a small positive integer) to identify 662 the local interface on which a multicast group is joined (Section 5.3). 663 Additionally, the advanced API [4] uses these same interface indexes to 664 identify the interface on which a datagram is received, or to specify 665 the interface on which a datagram is to be sent. 667 Interfaces are normally known by names such as "le0", "sl1", "ppp2", and 668 the like. On Berkeley-derived implementations, when an interface is 669 made known to the system, the kernel assigns a unique positive integer 670 value (called the interface index) to that interface. These are small 671 positive integers that start at 1. (Note that 0 is never used for an 672 interface index.) There may be gaps so that there is no current 673 interface for a particular positive interface index. 675 This API defines two functions that map between an interface name and 676 index, a third function that returns all the interface names and 677 indexes, and a fourth function to return the dynamic memory allocated by 678 the previous function. How these functions are implemented is left up 679 to the implementation. 4.4BSD implementations can implement these 680 functions using the existing sysctl() function with the NET_RT_IFLIST 681 command. Other implementations may wish to use ioctl() for this 682 purpose. 684 4.1 Name-to-Index 686 The first function maps an interface name into its corresponding index. 688 #include 690 unsigned int if_nametoindex(const char *ifname); 692 If the specified interface name does not exist, the return value is 0, 693 and errno is set to ENXIO. If there was a system error (such as 694 running out of memory), the return value is 0 and errno is set to the 695 proper value (e.g., ENOMEM). 697 4.2 Index-to-Name 699 The second function maps an interface index into its corresponding name. 701 #include 703 char *if_indextoname(unsigned int ifindex, char *ifname); 705 The ifname argument must point to a buffer of at least IF_NAMESIZE bytes 706 into which the interface name corresponding to the specified index is 707 returned. (IF_NAMESIZE is also defined in and its value 708 includes a terminating null byte at the end of the interface name.) This 709 pointer is also the return value of the function. If there is no 710 interface corresponding to the specified index, NULL is returned, and 711 errno is set to ENXIO, if there was a system error (such as running out 712 of memory), if_indextoname returns NULL and errno would be set to the 713 proper value (e.g., ENOMEM). 715 4.3 Return All Interface Names and Indexes 717 The if_nameindex structure holds the information about a single 718 interface and is defined as a result of including the header. 720 struct if_nameindex { 721 unsigned int if_index; /* 1, 2, ... */ 722 char *if_name; /* null terminated name: "le0", ... */ 723 }; 725 The final function returns an array of if_nameindex structures, one 726 structure per interface. 728 struct if_nameindex *if_nameindex(void); 730 The end of the array of structures is indicated by a structure with an 731 if_index of 0 and an if_name of NULL. The function returns a NULL 732 pointer upon an error, and would set errno to the appropriate value. 734 The memory used for this array of structures along with the interface 735 names pointed to by the if_name members is obtained dynamically. This 736 memory is freed by the next function. 738 4.4 Free Memory 740 The following function frees the dynamic memory that was allocated by 741 if_nameindex(). 743 #include 745 void if_freenameindex(struct if_nameindex *ptr); 747 The argument to this function must be a pointer that was returned by 748 if_nameindex(). 750 Currently net/if.h doesn't have prototype definitions for functions and 751 it is recommended that these definitions be defined in net/if.h as well 752 as the struct if_nameindex{}. 754 5. Socket Options 756 A number of new socket options are defined for IPv6. All of these new 757 options are at the IPPROTO_IPV6 level. That is, the "level" parameter 758 in the getsockopt() and setsockopt() calls is IPPROTO_IPV6 when using 759 these options. The constant name prefix IPV6_ is used in all of the new 760 socket options. This serves to clearly identify these options as 761 applying to IPv6. 763 The declaration for IPPROTO_IPV6, the new IPv6 socket options, and 764 related constants defined in this section are obtained by including the 765 header . 767 5.1 Unicast Hop Limit 769 A new setsockopt() option controls the hop limit used in outgoing 770 unicast IPv6 packets. The name of this option is IPV6_UNICAST_HOPS, and 771 it is used at the IPPROTO_IPV6 layer. The following example illustrates 772 how it is used: 774 int hoplimit = 10; 776 if (setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 777 (char *) &hoplimit, sizeof(hoplimit)) == -1) 778 perror("setsockopt IPV6_UNICAST_HOPS"); 780 When the IPV6_UNICAST_HOPS option is set with setsockopt(), the option 781 value given is used as the hop limit for all subsequent unicast packets 782 sent via that socket. If the option is not set, the system selects a 783 default value. The integer hop limit value (called x) is interpreted as 784 follows: 786 x < -1: return an error of EINVAL 787 x == -1: use kernel default 788 0 <= x <= 255: use x 789 x >= 256: return an error of EINVAL 791 The IPV6_UNICAST_HOPS option may be used with getsockopt() to determine 792 the hop limit value that the system will use for subsequent unicast 793 packets sent via that socket. For example: 795 int hoplimit; 796 socklen_t len = sizeof(hoplimit); 798 if (getsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 799 (char *) &hoplimit, &len) == -1) 800 perror("getsockopt IPV6_UNICAST_HOPS"); 801 else 802 printf("Using %d for hop limit.\n", hoplimit); 804 5.2 Sending and Receiving Multicast Packets 806 IPv6 applications may send UDP multicast packets by simply specifying an 807 IPv6 multicast address in the address argument of the sendto() function. 809 Three socket options at the IPPROTO_IPV6 layer control some of the 810 parameters for sending multicast packets. Setting these options is not 811 required: applications may send multicast packets without using these 812 options. The setsockopt() options for controlling the sending of 813 multicast packets are summarized below. These three options can also be 814 used with getsockopt(). 816 IPV6_MULTICAST_IF 818 Set the interface to use for outgoing multicast packets. 819 The argument is the index of the interface to use. 821 Argument type: unsigned int 823 IPV6_MULTICAST_HOPS 825 Set the hop limit to use for outgoing multicast packets. 826 (Note a separate option - IPV6_UNICAST_HOPS - is 827 provided to set the hop limit to use for outgoing 828 unicast packets.) 830 The interpretation of the argument is the same 831 as for the IPV6_UNICAST_HOPS option: 833 x < -1: return an error of EINVAL 834 x == -1: use kernel default 835 0 <= x <= 255: use x 836 x >= 256: return an error of EINVAL 838 If IPV6_MULTICAST_HOPS is not set, the default is 1 839 (same as IPv4 today) 841 Argument type: int 843 IPV6_MULTICAST_LOOP 845 If a multicast datagram is sent to a group to which the sending host 846 itself belongs (on the outgoing interface), a copy of the datagram is 847 looped back by the IP layer for local delivery if this option is set to 848 1. If this option is set to 0 a copy is not looped back. Other option 849 values return an error of EINVAL. 851 If IPV6_MULTICAST_LOOP is not set, the default is 1 (loopback; same as 852 IPv4 today). 854 Argument type: unsigned int 856 The reception of multicast packets is controlled by the two setsockopt() 857 options summarized below. An error of EOPNOTSUPP is returned if these 858 two options are used with getsockopt(). 860 IPV6_JOIN_GROUP 861 Join a multicast group on a specified local interface. 862 If the interface index is specified as 0, 863 the kernel chooses the local interface. 864 For example, some kernels look up the multicast group 865 in the normal IPv6 routing table and use the resulting interface. 867 Argument type: struct ipv6_mreq 869 IPV6_LEAVE_GROUP 871 Leave a multicast group on a specified interface. 873 Argument type: struct ipv6_mreq 875 The argument type of both of these options is the ipv6_mreq structure, 876 defined as a result of including the header; 878 struct ipv6_mreq { 879 struct in6_addr ipv6mr_multiaddr; /* IPv6 multicast addr */ 880 unsigned int ipv6mr_interface; /* interface index */ 881 }; 883 Note that to receive multicast datagrams a process must join the 884 multicast group and bind the UDP port to which datagrams will be sent. 885 Some processes also bind the multicast group address to the socket, in 886 addition to the port, to prevent other datagrams destined to that same 887 port from being delivered to the socket. 889 5.3 IPV6_V6ONLY option for AF_INET6 Sockets 891 This socket option restricts AF_INET6 sockets to IPv6 communications 892 only. As stated in section <3.7 Compatibility with IPv4 Nodes>, 893 AF_INET6 sockets may be used for both IPv4 and IPv6 communications. Some 894 applications may want to restrict their use of an AF_INET6 socket to 895 IPv6 communications only. For these applications the IPV6_V6ONLY socket 896 option is defined. When this option is turned on, the socket can be 897 used to send and receive IPv6 packets only. This is an IPPROTO_IPV6 898 level option. This option takes an int value. This is a boolean 899 option. By default this option is turned off. 901 Here is an example of setting this option: 903 int on = 1; 905 if (setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY, 906 (char *)&on, sizeof(on)) == -1) 907 perror("setsockopt IPV6_V6ONLY"); 908 else 909 printf("IPV6_V6ONLY set0); 911 Note - This option has no effect on the use of IPv4 Mapped addresses 912 which enter a node as a valid IPv6 addresses for IPv6 communications as 913 defined by Stateless IP/ICMP Translation Algorithm (SIIT) [8]. 915 6. Library Functions 917 New library functions are needed to perform a variety of operations with 918 IPv6 addresses. Functions are needed to lookup IPv6 addresses in the 919 Domain Name System (DNS). Both forward lookup (nodename-to-address 920 translation) and reverse lookup (address-to-nodename translation) need 921 to be supported. Functions are also needed to convert IPv6 addresses 922 between their binary and textual form. 924 We note that the two existing functions, gethostbyname() and 925 gethostbyaddr(), are left as-is. New functions are defined to handle 926 both IPv4 and IPv6 addresses. 928 The commonly used function gethostbyname() is inadequate for many 929 applications, first because it provides no way for the caller to specify 930 anything about the types of addresses desired (IPv4 only, IPv6 only, 931 IPv4-mapped IPv6 are OK, etc.), and second because many implementations 932 of this function are not thread safe. RFC 2133 defined a function named 933 gethostbyname2() but this function was also inadequate, first because 934 its use required setting a global option (RES_USE_INET6) when IPv6 935 addresses were required, and second because a flag argument is needed to 936 provide the caller with additional control over the types of addresses 937 required. 939 6.1 Protocol-Independent Nodename and Service Name Translation 941 Nodename-to-address translation is done in a protocol-independent 942 fashion using the getaddrinfo() function that is taken from the 943 Institute of Electrical and Electronic Engineers IEEE 1003.1-200x 944 (POSIX) draft specification [3]. 946 The official specification for this function will be the final IEEE 947 standard. In addition this specification is not specifying all 948 parameter possibilities for this function, but only the parameters that 949 can be provided to support IPv4 and IPv6 communications to support this 950 specification. This is beyond the scope of this document and additional 951 work on this function will be done by the Austin (IEEE/ISO/TOG) Group. 952 #include 953 #include 955 int getaddrinfo(const char *nodename, const char *servname, 956 const struct addrinfo *hints, struct addrinfo **res); 958 void freeaddrinfo(struct addrinfo *ai); 960 struct addrinfo { 961 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, .. */ 962 int ai_family; /* PF_xxx */ 963 int ai_socktype; /* SOCK_xxx */ 964 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 965 socklen_t ai_addrlen; /* length of ai_addr */ 966 char *ai_canonname; /* canonical name for nodename */ 967 struct sockaddr *ai_addr; /* binary address */ 968 struct addrinfo *ai_next; /* next structure in linked list */ 969 }; 970 The getaddrinfo ( ) function translates the name of a service 971 location (for example, a host name) and/or a service name and returns 972 a set of socket addresses and associated information to be used in 973 creating a socket with which to address the specified service. 975 The nodename and servname arguments are either null pointers or 976 pointers to null-terminated strings. One or both of these two 977 arguments must be a non-null pointer. 979 The format of a valid name depends on the protocol family or 980 families. If a specific family is not given and the name could be 981 interpreted as valid within multiple supported families, the 982 implementation will attempt to resolve the name in all supported 983 families and, all successful results will be returned. 985 If the nodename argument is not null, it can be a descriptive name or 986 can be an address string. If the specified address family is AF_INET, 987 or AF_UNSPEC, the permissable nodename argument is specified as 988 defined in inet_pton(). If the specified address family is AF_INET6 989 or AF_UNSPEC, the permissable nodename argument is specified as 990 defined in [5]. 992 If nodename is not null, the requested service location is named by 993 nodename; otherwise, the requested service location is local to the 994 caller. 996 If servname is null, the call returns network-level addresses for the 997 specified nodename. If servname is not null, it is a null-terminated 998 character string identifying the requested service. This can be 999 either a descriptive name or a numeric representation suitable for 1000 use with the address family or families. If the specified address 1001 family is AF_INET, AF_INET6 or AF_UNSPEC, the service can be 1002 specified as a string specifying a decimal port number. 1004 If the argument hints is not null, it refers to a structure 1005 containing input values that may direct the operation by providing 1006 options and by limiting the returned information to a specific socket 1007 type, address family and/or protocol. In this hints structure every 1008 member other than ai_flags, ai_family, ai_socktype and ai_protocol 1009 must be zero or a null pointer. A value of AF_UNSPEC for ai_family 1010 means that the caller will accept any protocol family. A value of 1011 zero for ai_socktype means that the caller will accept any socket 1012 type. A value of zero for ai_protocol means that the caller will 1013 accept any protocol. If hints is a null pointer, the behavior must be 1014 as if it referred to a structure containing the value zero for the 1015 ai_flags, ai_socktype and ai_protocol fields, and AF_UNSPEC for the 1016 ai_family field. 1018 Note: 1020 1. If the caller handles only TCP and not UDP, for example, then the 1021 ai_protocol member of the hints structure should be set to 1022 IPPROTO_TCP when getaddrinfo ( ) is called. 1024 2. If the caller handles only IPv4 and not IPv6, then the ai_family 1025 member of the hints structure should be set to PF_INET when 1026 getaddrinfo ( ) is called. 1028 The ai_flags field to which hints parameter points must have the 1029 value zero or be the bitwise OR of one or more of the values 1030 AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, 1031 AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG. 1033 The AI_PASSIVE flag in the ai_flags member of the hints structure 1034 specifies how to fill in the IP address portion of the socket address 1035 structure. If the AI_PASSIVE flag is specified, then the returned 1036 address information must be suitable for use in binding a socket for 1037 accepting incoming connections for the specified service (i.e. a call 1038 to bind()). In this case, if the nodename argument is null, then the 1039 IP address portion of the socket address structure will be set to 1040 INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 1041 address. If the AI_PASSIVE bit is not set, the returned address 1042 information must be suitable for a call to connect( ) (for a 1043 connection-mode protocol) or for a call to connect(), sendto() or 1044 sendmsg( ) (for a connectionless protocol). In this case, if the 1045 nodename argument is null, then the IP address portion of the socket 1046 address structure will be set to the loopback address. This flag is 1047 ignored if the nodename argument is not null. 1049 If the flag AI_CANONNAME is specified and the nodename argument is 1050 not null, the function attempts to determine the canonical name 1051 corresponding to nodename (for example, if nodename is an alias or 1052 shorthand notation for a complete name). 1054 If the flag AI_NUMERICHOST is specified then a non-null nodename 1055 string must be a numeric host address string. Otherwise an error of 1056 [EAI_NONAME] is returned. This flag prevents any type of name 1057 resolution service (for example, the DNS) from being invoked. 1059 If the flag AI_NUMERICSERV is specified then a non-null servname 1060 string must be a numeric port string. Otherwise an error [EAI_NONAME] 1061 is returned. This flag prevents any type of name resolution service 1062 (for example, NIS+) from being invoked. 1064 If the AI_V4MAPPED flag is specified along with an ai_family of 1065 AF_INET6, then the caller will accept IPv4-mapped IPv6 addresses. 1066 That is, if no AAAA or A6, records are found then a query is made for 1067 A records and any found are returned as IPv4-mapped IPv6 addresses 1068 (ai_addrlen will be 16). The AI_V4MAPPED flag is ignored unless 1069 ai_family equals AF_INET6. 1071 The AI_ALL flag is used in conjunction with the AI_V4MAPPED flag, and 1072 is only used with an ai_family of AF_INET6. When AI_ALL is logically 1073 or'd with AI_V4MAPPED flag then the caller will accept all addresses: 1074 IPv6 and IPv4-mapped IPv6. A query is first made for AAAA/A6 records 1075 and if successful, the IPv6 addresses are returned. Another query is 1076 then made for A records and any found are returned as IPv4-mapped 1077 IPv6 addresses (ai_addrlen will be 16). This flag is ignored unless 1078 ai_family equals AF_INET6. 1080 Note: 1082 When ai_family is not specified (AF_UNSPEC), AI_V4MAPPED and 1083 AI_ALL flags will only be used if AF_INET6 is supported. 1085 If the AI_ADDRCONFIG flag is specified then a query for AAAA or A6 1086 records should occur only if the node has at least one IPv6 source 1087 address configured and a query for A records should occur only if the 1088 node has at least one IPv4 source address configured. The loopback 1089 address is not considered for this case as valid as a configured 1090 sources address. 1092 The ai_socktype field to which argument hints points specifies the 1093 socket type for the service. If a specific socket type is not given 1094 (for example, a value of zero) and the service name could be 1095 interpreted as valid with multiple supported socket types, the 1096 implementation will attempt to resolve the service name for all 1097 supported socket types and, all successful results will be returned. 1098 A non-zero socket type value will limit the returned information to 1099 values with the specified socket type. 1101 The freeaddrinfo ( ) function frees one or more addrinfo structures 1102 returned by getaddrinfo ( ), along with any additional storage 1103 associated with those structures. If the ai_next field of the 1104 structure is not null, the entire list of structures is freed. The 1105 freeaddrinfo () function must support the freeing of arbitrary 1106 sublists of an addrinfo list originally returned by getaddrinfo (). 1108 Functions getaddrinfo ( ) and freeaddrinfo ( ) must be thread-safe. 1110 A zero return value for getaddrinfo ( ) indicates successful 1111 completion; a non-zero return value indicates failure. 1113 Upon successful return of getaddrinfo ( ), the location to which res 1114 points refers to a linked list of addrinfo structures, each of which 1115 specifies a socket address and information for use in creating a 1116 socket with which to use that socket address. The list must include 1117 at least one addrinfo structure. The ai_next field of each structure 1118 contains a pointer to the next structure on the list, or a null 1119 pointer if it is the last structure on the list. Each structure on 1120 the list includes values for use with a call to the socket( ) 1121 function, and a socket address for use with the connect() function 1122 or, if the AI_PASSIVE flag was specified, for use with the bind( ) 1123 function. The fields ai_family, ai_socktype, and ai_protocol are 1124 usable as the arguments to the socket() function to create a socket 1125 suitable for use with the returned address. The fields ai_addr and 1126 ai_addrlen are usable as the arguments to the connect() or bind( ) 1127 functions with such a socket, according to the AI_PASSIVE flag. 1129 If nodename is not null, and if requested by the AI_CANONNAME flag, 1130 the ai_canonname field of the first returned addrinfo structure 1131 points to a null-terminated string containing the canonical name 1132 corresponding to the input nodename; if the canonical name is not 1133 available, then ai_canonname refers to the argument nodename or a 1134 string with the same contents. The contents of the ai_flags field of 1135 the returned structures is undefined. 1137 All fields in socket address structures returned by getaddrinfo ( ) 1138 that are not filled in through an explicit argument (for example, 1139 sin6_flowinfo) must be set to zero. 1141 Note: This makes it easier to compare socket address structures. 1143 Error Return Values: 1145 [EAI_AGAIN] The name could not be resolved at this time. Future 1146 attempts may succeed. 1148 [EAI_BADFLAGS] The flags parameter had an invalid value. 1150 [EAI_FAIL] A non-recoverable error occurred when attempting to 1151 resolve the name. 1153 [EAI_FAMILY] The address family was not recognized. 1155 [EAI_MEMORY] There was a memory allocation failure when trying to 1156 allocate storage for the return value. 1158 [EAI_NONAME] The name does not resolve for the supplied parameters. 1159 Neither nodename nor servname were passed. At least one 1160 of these must be passed. 1162 [EAI_SERVICE] The service passed was not recognized for the specified 1163 socket type. 1165 [EAI_SOCKTYPE] The intended socket type was not recognized. 1167 [EAI_SYSTEM] A system error occurred; the error code can be found in 1168 errno. 1170 #include 1172 #include 1174 char *gai_strerror(int ecode); 1176 The argument is one of the EAI_xxx values defined earlier and the return 1177 value points to a string describing the error. If the argument is not 1178 one of the EAI_xxx values, the function still returns a pointer to a 1179 string whose contents indicate an unknown error. 1181 6.2 Socket Address Structure to Nodename and Service Name 1183 The official specification for this function will be the final Austin 1184 Group standard update to getaddrinfo(), and will incorporate this 1185 function. In addition this specification is not specifying all 1186 parameter possibilities for this function, but only the parameters that 1187 can be provided to support IPv4 and IPv6 communications to support this 1188 specification. This is beyond the scope of this document and additional 1189 work on this function will be done by the Austin group. 1191 #include 1192 #include 1194 int getnameinfo(const struct sockaddr *sa, socklen_t salen, 1195 char *host, socklen_t hostlen, 1196 char *serv, socklen_t servlen, 1197 int flags); 1199 The getnameinfo( ) translates a socket address to a node name and 1200 service location, all of which are defined as with getaddrinfo (). 1202 The argument sa points to a socket address structure to be translated. 1204 If the argument node is non-NULL and the argument nodelen is nonzero, 1205 then the argument node points to a buffer able to contain up to nodelen 1206 characters that will receive the node name as a null-terminated string. 1207 If the argument node is NULL or the argument nodelen is zero, the node 1208 name will not be returned. If the node�s name cannot be located, the 1209 numeric form of the nodes address is returned instead of its name. If 1210 the sa argument is an IPv6 address the returned nodename may be in the 1211 format as defined in [5]. 1213 If the argument service is non-NULL and the argument servicelen is 1214 nonzero, then the argument service points to a buffer able to contain up 1215 to servicelen characters that will receive the service name as a null- 1216 terminated string. If the argument service is NULL or the argument 1217 servicelen is zero, the service name will not be returned. If the 1218 service name cannot be located, the numeric form of the service address 1219 (for example, its port number) is returned instead of its name. 1221 The arguments node and service cannot both be NULL. 1223 The flags argument is a flag that changes the default actions of the 1224 function. By default the fully-qualified domain name (FQDN) for the host 1225 is returned, but 1227 - If the flag bit NI_NOFQDN is set, only the nodename portion of the 1228 FQDN is returned for local hosts. 1230 - If the flag bit NI_NUMERICHOST is set, the numeric form of the 1231 host's address is returned instead of its name, under all 1232 circumstances. 1234 - If the flag bit NI_NAMEREQD is set, an error is returned if the 1235 host�s name cannot be located. 1237 - If the flag bit NI_NUMERICSERV is set, the numeric form of the 1238 service address is returned (for example, its port number) instead of 1239 its name, under all circumstances. 1241 - If the flag bit NI_NUMERICSCOPE is set, the numeric form of the 1242 scope identifier is returned (for example, interface index) 1243 instead of its name. This flag is ignored if the sa argument is 1244 not an IPv6 address. 1246 - If the flag bit NI_DGRAM is set, this indicates that the service is 1247 a datagram service (SOCK_DGRAM). The default behavior is to assume that 1248 the service is a stream service (SOCK_STREAM). 1250 Note: 1252 1. The three NI_NUMERICxxx flags are required to support the "-n" 1253 flags that many commands support. 1254 2. The NI_DGRAM flag is required for the new AF_INET/AF_INET6 port 1255 numbers (for example, 512-514) that represent different services 1256 for UDP and TCP. 1258 Function getnameinfo() must be thread safe. 1260 A zero return value for getnameinfo( ) indicates successful completion; 1261 a non-zero return value indicates failure. 1263 On successful completion, function getnameinfo( ) returns the node and 1264 service names, if requested, in the buffers provided. The returned names 1265 are always null-terminated strings. 1267 Error Return Values: 1269 [EAI_AGAIN] The name could not be resolved at this time. 1270 Future attempts may succeed. 1272 [EAI_BADFLAGS] The flags had an invalid value. 1274 [EAI_FAIL] A non-recoverable error occurred. 1276 [EAI_FAMILY] The address family was not recognized or the address 1277 length was invalid for the specified family. 1279 [EAI_MEMORY] There was a memory allocation failure. 1281 [EAI_NONAME] The name does not resolve for the supplied parameters. 1282 NI_NAMEREQD is set and the host�s name cannot be located, or 1283 both nodename and servname were null. 1285 [EAI_SYSTEM] A system error occurred. The error code can be found in 1286 errno. 1288 6.3 Address Conversion Functions 1290 The two functions inet_addr() and inet_ntoa() convert an IPv4 address 1291 between binary and text form. IPv6 applications need similar functions. 1292 The following two functions convert both IPv6 and IPv4 addresses: 1294 #include 1295 #include 1297 int inet_pton(int af, const char *src, void *dst); 1299 const char *inet_ntop(int af, const void *src, 1300 char *dst, socklen_t size); 1302 The inet_pton() function converts an address in its standard text 1303 presentation form into its numeric binary form. The af argument 1304 specifies the family of the address. Currently the AF_INET and AF_INET6 1305 address families are supported. The src argument points to the string 1306 being passed in. The dst argument points to a buffer into which the 1307 function stores the numeric address. The address is returned in network 1308 byte order. Inet_pton() returns 1 if the conversion succeeds, 0 if the 1309 input is not a valid IPv4 dotted-decimal string or a valid IPv6 address 1310 string, or -1 with errno set to EAFNOSUPPORT if the af argument is 1311 unknown. The calling application must ensure that the buffer referred 1312 to by dst is large enough to hold the numeric address (e.g., 4 bytes for 1313 AF_INET or 16 bytes for AF_INET6). 1315 If the af argument is AF_INET, the function accepts a string in the 1316 standard IPv4 dotted-decimal form: 1318 ddd.ddd.ddd.ddd 1320 where ddd is a one to three digit decimal number between 0 and 255. 1321 Note that many implementations of the existing inet_addr() and 1322 inet_aton() functions accept nonstandard input: octal numbers, 1323 hexadecimal numbers, and fewer than four numbers. inet_pton() does not 1324 accept these formats. 1326 If the af argument is AF_INET6, then the function accepts a string in 1327 one of the standard IPv6 text forms defined in Section 2.2 of the 1328 addressing architecture specification [2]. 1330 The inet_ntop() function converts a numeric address into a text string 1331 suitable for presentation. The af argument specifies the family of the 1332 address. This can be AF_INET or AF_INET6. The src argument points to a 1333 buffer holding an IPv4 address if the af argument is AF_INET, or an IPv6 1334 address if the af argument is AF_INET6, the address must be in network 1335 byte order. The dst argument points to a buffer where the function will 1336 store the resulting text string. The size argument specifies the size 1337 of this buffer. The application must specify a non-NULL dst argument. 1338 For IPv6 addresses, the buffer must be at least 46-octets. For IPv4 1339 addresses, the buffer must be at least 16-octets. In order to allow 1340 applications to easily declare buffers of the proper size to store IPv4 1341 and IPv6 addresses in string form, the following two constants are 1342 defined in : 1344 #define INET_ADDRSTRLEN 16 1345 #define INET6_ADDRSTRLEN 46 1347 The inet_ntop() function returns a pointer to the buffer containing the 1348 text string if the conversion succeeds, and NULL otherwise. Upon 1349 failure, errno is set to EAFNOSUPPORT if the af argument is invalid or 1350 ENOSPC if the size of the result buffer is inadequate. 1352 6.4 Address Testing Macros 1354 The following macros can be used to test for special IPv6 addresses. 1356 #include 1358 int IN6_IS_ADDR_UNSPECIFIED (const struct in6_addr *); 1359 int IN6_IS_ADDR_LOOPBACK (const struct in6_addr *); 1360 int IN6_IS_ADDR_MULTICAST (const struct in6_addr *); 1361 int IN6_IS_ADDR_LINKLOCAL (const struct in6_addr *); 1362 int IN6_IS_ADDR_SITELOCAL (const struct in6_addr *); 1363 int IN6_IS_ADDR_V4MAPPED (const struct in6_addr *); 1364 int IN6_IS_ADDR_V4COMPAT (const struct in6_addr *); 1366 int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); 1367 int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); 1368 int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); 1369 int IN6_IS_ADDR_MC_ORGLOCAL (const struct in6_addr *); 1370 int IN6_IS_ADDR_MC_GLOBAL (const struct in6_addr *); 1372 The first seven macros return true if the address is of the specified 1373 type, or false otherwise. The last five test the scope of a multicast 1374 address and return true if the address is a multicast address of the 1375 specified scope or false if the address is either not a multicast 1376 address or not of the specified scope. Note that IN6_IS_ADDR_LINKLOCAL 1377 and IN6_IS_ADDR_SITELOCAL return true only for the two local-use IPv6 1378 unicast addresses. These two macros do not return true for IPv6 1379 multicast addresses of either link-local scope or site-local scope. 1381 7. Summary of New Definitions 1383 The following list summarizes the constants, structure, and extern 1384 definitions discussed in this memo, sorted by header. 1386 IF_NAMESIZE 1387 struct if_nameindex{}; 1389 AI_ADDRCONFIG 1390 AI_DEFAULT 1391 AI_ALL 1392 AI_CANONNAME 1393 AI_NUMERICHOST 1394 AI_PASSIVE 1395 AI_V4MAPPED 1396 EAI_AGAIN 1397 EAI_BADFLAGS 1398 EAI_FAIL 1399 EAI_FAMILY 1400 EAI_MEMORY 1401 EAI_NONAME 1402 EAI_SERVICE 1403 EAI_SOCKTYPE 1404 EAI_SYSTEM 1405 NI_DGRAM 1406 NI_MAXHOST 1407 NI_MAXSERV 1408 NI_NAMEREQD 1409 NI_NOFQDN 1410 NI_NUMERICHOST 1411 NI_NUMERICSERV 1412 struct addrinfo{}; 1414 IN6ADDR_ANY_INIT 1415 IN6ADDR_LOOPBACK_INIT 1416 INET6_ADDRSTRLEN 1417 INET_ADDRSTRLEN 1418 IPPROTO_IPV6 1419 IPV6_JOIN_GROUP 1420 IPV6_LEAVE_GROUP 1421 IPV6_MULTICAST_HOPS 1422 IPV6_MULTICAST_IF 1423 IPV6_MULTICAST_LOOP 1424 IPV6_UNICAST_HOPS 1425 SIN6_LEN 1426 extern const struct in6_addr in6addr_any; 1427 extern const struct in6_addr in6addr_loopback; 1428 struct in6_addr{}; 1429 struct ipv6_mreq{}; 1430 struct sockaddr_in6{}; 1432 AF_INET6 1433 PF_INET6 1434 struct sockaddr_storage; 1436 The following list summarizes the function and macro prototypes 1437 discussed in this memo, sorted by header. 1439 int inet_pton(int, const char *, void *); 1440 const char *inet_ntop(int, const void *, 1441 char *, socklen_t); 1443 char *if_indextoname(unsigned int, char *); 1444 unsigned int if_nametoindex(const char *); 1445 void if_freenameindex(struct if_nameindex *); 1446 struct if_nameindex *if_nameindex(void); 1448 int getaddrinfo(const char *, const char *, 1449 const struct addrinfo *, 1450 struct addrinfo **); 1451 int getnameinfo(const struct sockaddr *, socklen_t, 1452 char *, socklen_t, char *, socklen_t, int); 1453 void freeaddrinfo(struct addrinfo *); 1454 char *gai_strerror(int); 1456 int IN6_IS_ADDR_LINKLOCAL(const struct in6_addr *); 1457 int IN6_IS_ADDR_LOOPBACK(const struct in6_addr *); 1458 int IN6_IS_ADDR_MC_GLOBAL(const struct in6_addr *); 1459 int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); 1460 int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); 1461 int IN6_IS_ADDR_MC_ORGLOCAL(const struct in6_addr *); 1462 int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); 1463 int IN6_IS_ADDR_MULTICAST(const struct in6_addr *); 1464 int IN6_IS_ADDR_SITELOCAL(const struct in6_addr *); 1465 int IN6_IS_ADDR_UNSPECIFIED(const struct in6_addr *); 1466 int IN6_IS_ADDR_V4COMPAT(const struct in6_addr *); 1467 int IN6_IS_ADDR_V4MAPPED(const struct in6_addr *); 1469 8. Security Considerations 1471 IPv6 provides a number of new security mechanisms, many of which need to 1472 be accessible to applications. Companion memos detailing the extensions 1473 to the socket interfaces to support IPv6 security are being written. 1475 9. Year 2000 Considerations 1477 There are no issues for this draft concerning the Year 2000 issue 1478 regarding the use of dates. 1480 Changes made to rfc2553bis-02 to rfc2553bis-03 1482 1. Edits only. 1484 Changes made to rfc2553bis-01 to rfc2553bis-02 1486 1. Updated all references to comply with latest IEEEE work on 1487 socket APIs and changed all remaining size_t to socklen_t. 1489 2. Edits caught. 1491 Changes made to rfc2553bis-00 to rfc2553bis-01 1493 1. Removed all references to getipnodebyname() and 1494 getipnodebyaddr(). 1496 2. Added IPV6_V6ONLY Socket IP level option to permit nodes 1497 to not process IPv4 packets as IPv4 Mapped addresses 1498 in implementations. 1500 3. Added note to getaddrinfo() and getnameinfo() 1501 that final specification of parameter associations for 1502 these functions will be done by Austin. 1504 4. Added SIIT to references and added new contributors. 1506 Changes made rfc2553 to rfc2553bis-00: 1508 1. Updated Portability Section 3.10 to conform to XNS 5.2. 1510 2. Updated getaddrinfo(), getnameinfo(), to conform to XNS 5.2. 1512 3. Added references to Scope Architecture, Scope Routing, and 1513 Extension Format for Scoped Addresses work in progress. 1515 4. Added NI_NUMERICSCOPE flag to getnameinfo(). 1517 5. Added qualification to getipnodebyname/addr() functions that 1518 they will not work as is with scope identifiers with IPv6, and 1519 getaddrinfo/getnameinfo should be used. 1521 6. Added DNS A6 record notation to AAAA and added ip6.arpa as new 1522 PTR record domain. 1524 Acknowledgments 1526 This specification's evolution and completeness were significantly 1527 influenced by the efforts of Richard Stevens, who has passed on. Rich's 1528 wisdom and talent made the specification what it is today. The co- 1529 authors will long think of Richard with great respect. 1531 Thanks to the many people who made suggestions and provided feedback to 1532 this document, including: Werner Almesberger, Ran Atkinson, Fred Baker, 1533 Dave Borman, Andrew Cherenson, Alex Conta, Alan Cox, Steve Deering, 1534 Richard Draves, Francis Dupont, Robert Elz, Brian Haberman, Jun-ichiro 1535 itojun Hagino, Marc Hasson, Tom Herbert, Bob Hinden, Wan-Yen Hsu, 1536 Christian Huitema, Koji Imada, Markus Jork, Ron Lee, Alan Lloyd, Charles 1537 Lynn, Dan McDonald, Dave Mitton, Thomas Narten, Josh Osborne, Craig 1538 Partridge, Jean-Luc Richier, Bill Sommerfield, Erik Scoredos, Keith 1539 Sklower, JINMEI Tatuya, Dave Thaler, Matt Thomas, Harvey Thompson, Dean 1540 D. Throop, Karen Tracey, Glenn Trewitt, Paul Vixie, David Waitzman, Carl 1541 Williams, Kazu Yamamoto, Vlad Yasevich, Stig Venaas, and Brian Zill 1543 The getaddrinfo() and getnameinfo() functions are taken from an earlier 1544 Internet Draft by Keith Sklower. As noted in that draft, William Durst, 1545 Steven Wise, Michael Karels, and Eric Allman provided many useful 1546 discussions on the subject of protocol-independent name-to-address 1547 translation, and reviewed early versions of Keith Sklower's original 1548 proposal. Eric Allman implemented the first prototype of getaddrinfo(). 1549 The observation that specifying the pair of name and service would 1550 suffice for connecting to a service independent of protocol details was 1551 made by Marshall Rose in a proposal to X/Open for a "Uniform Network 1552 Interface". 1554 Craig Metz, Jack McCann, Erik Nordmark, Tim Hartrick, and Mukesh Kacker 1555 made many contributions to this document. Ramesh Govindan made a number 1556 of contributions and co-authored an earlier version of this memo. 1558 References 1560 [1] S. Deering, R. Hinden, "Internet Protocol, Version 6 (IPv6) 1561 Specification", RFC 2460 Draft Standard. 1563 [2] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture", 1564 RFC 2373, July 1998 Draft Standard. 1566 [3] IEEE Std. 1003.1-200x (Portable Operating System Interface (POSIX)) 1567 DRAFT 6, July 2000. 1569 [4] W. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 1570 RFC 2292, February 1998. 1572 [5] T. Jinmei, A. Onoe, "An Extension of Format for IPv6 Scoped 1573 Addresses", Work-in-Progress. 1575 [6] S. Deering, B. Haberman, B. Zill "IP Version 6 Scoped Address 1576 Architecture", Work-in-Progress. 1578 [7] B. Haberman " Routing of Scoped Addresses in the Internet Protocol 1579 Version 6 (IPv6)", Work-in-Progress. 1581 [8] E. Nordmark "Stateless IP/ICMP Translation Algorithm (SIIT)" 1582 RFC 2765, February 2000. 1584 Authors' Addresses 1586 Bob Gilligan 1587 Cacheflow, Inc. 1588 650 Almanor Ave.. 1589 Sunnyvale, CA 94086 1590 Telephone: 408-220-2084 (voice) 1591 408-220-2250 (fax) 1592 Email: gilligan@cacheflow.com 1594 Susan Thomson 1595 Cisco Systems 1596 499 Thornall Street, 8th floor 1597 Edison, NJ 08837 1598 Telephone: 732-635-3086 1599 Email: sethomso@cisco.com 1601 Jim Bound 1602 Nokia Networks 1603 5 Wayside Road 1604 Burlington, MA 01803 1605 Phone: +1 781 492 6013 1606 Email: Jim.Bound@nokia.com