idnits 2.17.1 draft-ietf-ipngwg-rfc2553bis-00.txt: -(1474): 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 34 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 34 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 44 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 322: '...field SHOULD be set to zero by an impl...' RFC 2119 keyword, line 909: '...ion at this time MUST not be used by a...' RFC 2119 keyword, line 1120: '...s "::" and "::1" MUST NOT be treated a...' RFC 2119 keyword, line 1121: '... "::", HOST_NOT_FOUND MUST be returned...' RFC 2119 keyword, line 1124: '...IN6_IS_ADDR_V4COMPAT MUST return false...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 695 has weird spacing: '...ned int if_na...' == Line 726 has weird spacing: '...ned int if_i...' == Line 749 has weird spacing: '... void if_fr...' == Line 778 has weird spacing: '... int hoplim...' == Line 799 has weird spacing: '... int hoplim...' == (1 more instance...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Note: This function at this time MUST not be used by any applications that will want to support scope_ids [5,6,7] within an application, and for those applications the getaddrinfo() function should be used as specified in section 6.4 of this specification. -- 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 (May 2000) is 8746 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 278, but not defined == Missing Reference: '0' is mentioned on line 1051, 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' Summary: 11 errors (**), 0 flaws (~~), 14 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-00.txt Freegate 3 Obsoletes RFC 2553 S. Thomson 4 Bellcore 5 J. Bound 6 Compaq 7 W. R. Stevens 8 Consultant 9 May 2000 11 Basic Socket Interface Extensions for IPv6 13 15 Status of this Memo 17 This document is an Internet-Draft and is in full conformance with 18 all provisions of Section 10 of RFC2026. 20 This document is a submission by the Internet Protocol IPv6 Working 21 Group of the Internet Engineering Task Force (IETF). Comments should 22 be submitted to the ipng@sunroof.eng.sun.com mailing list. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF), its areas, and its working groups. Note that 26 other groups may also distribute working documents as Internet- 27 Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet- Drafts as reference 32 material or to cite them other than as "work in progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 Abstract 42 The de facto standard application program interface (API) for TCP/IP 43 applications is the "sockets" interface. Although this API was 44 developed for Unix in the early 1980s it has also been implemented on a 45 wide variety of non-Unix systems. TCP/IP applications written using the 46 sockets API have in the past enjoyed a high degree of portability and we 47 would like the same portability with IPv6 applications. But changes are 48 required to the sockets API to support IPv6 and this memo describes 49 these changes. These include a new socket address structure to carry 50 IPv6 addresses, new address conversion functions, and some new socket 51 options. These extensions are designed to provide access to the basic 52 IPv6 features required by TCP and UDP applications, including 53 multicasting, while introducing a minimum of change into the system and 54 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......................................7 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......................................11 75 3.9 IPv6 Loopback Address......................................12 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 6. Library Functions...........................................18 86 6.1 Nodename-to-Address Translation............................18 87 6.2 Address-To-Nodename Translation............................21 88 6.3 Freeing memory for getipnodebyname and getipnodebyaddr.....22 89 6.4 Protocol-Independent Nodename and Service Name Translation.23 90 6.5 Socket Address Structure to Nodename and Service Name......27 91 6.6 Address Conversion Functions...............................29 92 6.7 Address Testing Macros.....................................30 93 7. Summary of New Definitions..................................30 94 8. Security Considerations.....................................32 95 9. Year 2000 Considerations....................................32 96 Changes made rfc2553 to rfc2553bis-00:.........................32 97 Acknowledgments................................................33 98 References.....................................................33 99 Authors' Addresses.............................................34 100 1. Introduction 102 While IPv4 addresses are 32 bits long, IPv6 interfaces are identified by 103 128-bit addresses. The socket interface makes the size of an IP address 104 quite visible to an application; virtually all TCP/IP applications for 105 BSD-based systems have knowledge of the size of an IP address. Those 106 parts of the API that expose the addresses must be changed to 107 accommodate the larger IPv6 address size. IPv6 also introduces new 108 features (e.g., traffic class and flowlabel), some of which must be made 109 visible to applications via the API. This memo defines a set of 110 extensions to the socket interface to support the larger address size 111 and new features of IPv6. 113 2. Design Considerations 115 There are a number of important considerations in designing changes to 116 this well-worn API: 118 - The API changes should provide both source and binary 119 compatibility for programs written to the original API. That 120 is, existing program binaries should continue to operate when 121 run on a system supporting the new API. In addition, existing 122 applications that are re-compiled and run on a system supporting 123 the new API should continue to operate. Simply put, the API 124 changes for IPv6 should not break existing programs. An additonal 125 mechanism for implementations to verify this is to verify the new 126 symbols are protected by Feature Test Macros as described in IEEE Std 127 1003.1. (Such Feature Test Macros are not defined by this RFC.) 129 - The changes to the API should be as small as possible in order 130 to simplify the task of converting existing IPv4 applications to 131 IPv6. 133 - Where possible, applications should be able to use this 134 API to interoperate with both IPv6 and IPv4 hosts. Applications 135 should not need to know which type of host they are 136 communicating with. 138 - IPv6 addresses carried in data structures should be 64-bit 139 aligned. This is necessary in order to obtain optimum 140 performance on 64-bit machine architectures. 142 Because of the importance of providing IPv4 compatibility in the API, 143 these extensions are explicitly designed to operate on machines that 144 provide complete support for both IPv4 and IPv6. A subset of this API 145 could probably be designed for operation on systems that support only 146 IPv6. However, this is not addressed in this memo. 148 2.1 What Needs to be Changed 150 The socket interface API consists of a few distinct components: 152 - Core socket functions. 154 - Address data structures. 156 - Name-to-address translation functions. 158 - Address conversion functions. 160 The core socket functions -- those functions that deal with such things 161 as setting up and tearing down TCP connections, and sending and 162 receiving UDP packets -- were designed to be transport independent. 163 Where protocol addresses are passed as function arguments, they are 164 carried via opaque pointers. A protocol-specific address data structure 165 is defined for each protocol that the socket functions support. 166 Applications must cast pointers to these protocol-specific address 167 structures into pointers to the generic "sockaddr" address structure 168 when using the socket functions. These functions need not change for 169 IPv6, but a new IPv6-specific address data structure is needed. 171 The "sockaddr_in" structure is the protocol-specific data structure for 172 IPv4. This data structure actually includes 8-octets of unused space, 173 and it is tempting to try to use this space to adapt the sockaddr_in 174 structure to IPv6. Unfortunately, the sockaddr_in structure is not 175 large enough to hold the 16-octet IPv6 address as well as the other 176 information (address family and port number) that is needed. So a new 177 address data structure must be defined for IPv6. 179 IPv6 addresses are scoped [2] so they could be link-local, site, 180 organization, global, or other scopes at this time undefined. To 181 support applications that want to be able to identify a set of 182 interfaces for a specific scope, the IPv6 sockaddr_in structure must 183 support a field that can be used by an implementation to identify a set 184 of interfaces identifying the scope for an IPv6 address. 186 The name-to-address translation functions in the socket interface are 187 gethostbyname() and gethostbyaddr(). These are left as is and new 188 functions are defined to support IPv4 and IPv6. Additionally, the POSIX 189 1003.g draft [3] specifies a new nodename-to-address translation 190 function which is protocol independent. This function can also be used 191 with IPv4 and IPv6. 193 The address conversion functions -- inet_ntoa() and inet_addr() -- 194 convert IPv4 addresses between binary and printable form. These 195 functions are quite specific to 32-bit IPv4 addresses. We have designed 196 two analogous functions that convert both IPv4 and IPv6 addresses, and 197 carry an address type parameter so that they can be extended to other 198 protocol families as well. 200 Finally, a few miscellaneous features are needed to support IPv6. New 201 interfaces are needed to support the IPv6 traffic class, flow label, and 202 hop limit header fields. New socket options are needed to control the 203 sending and receiving of IPv6 multicast packets. 205 The socket interface will be enhanced in the future to provide access to 206 other IPv6 features. These extensions are described in [4]. 208 2.2 Data Types 210 The data types of the structure elements given in this memo are intended 211 to be examples, not absolute requirements. Whenever possible, data 212 types from Draft 6.6 (March 1997) of POSIX 1003.1g are used: uintN_t 213 means an unsigned integer of exactly N bits (e.g., uint16_t). We also 214 assume the argument data types from 1003.1g when possible (e.g., the 215 final argument to setsockopt() is a size_t value). Whenever buffer 216 sizes are specified, the POSIX 1003.1 size_t data type is used (e.g., 217 the two length arguments to getnameinfo()). 219 2.3 Headers 221 When function prototypes and structures are shown we show the headers 222 that must be #included to cause that item to be defined. 224 2.4 Structures 226 When structures are described the members shown are the ones that must 227 appear in an implementation. Additional, nonstandard members may also 228 be defined by an implementation. As an additional precaution 229 nonstandard members could be verified by Feature Test Macros as 230 described in IEEE Std 1003.1. (Such Feature Test Macros are not defined 231 by this RFC.) 233 The ordering shown for the members of a structure is the recommended 234 ordering, given alignment considerations of multibyte members, but an 235 implementation may order the members differently. 237 3. Socket Interface 239 This section specifies the socket interface changes for IPv6. 241 3.1 IPv6 Address Family and Protocol Family 243 A new address family name, AF_INET6, is defined in . The 244 AF_INET6 definition distinguishes between the original sockaddr_in 245 address data structure, and the new sockaddr_in6 data structure. 247 A new protocol family name, PF_INET6, is defined in . 248 Like most of the other protocol family names, this will usually be 249 defined to have the same value as the corresponding address family name: 251 #define PF_INET6 AF_INET6 253 The PF_INET6 is used in the first argument to the socket() function to 254 indicate that an IPv6 socket is being created. 256 3.2 IPv6 Address Structure 258 A new in6_addr structure holds a single IPv6 address and is defined as a 259 result of including : 261 struct in6_addr { 262 uint8_t s6_addr[16]; /* IPv6 address */ 263 }; 265 This data structure contains an array of sixteen 8-bit elements, which 266 make up one 128-bit IPv6 address. The IPv6 address is stored in network 267 byte order. 269 The structure in6_addr above is usually implemented with an embedded 270 union with extra fields that force the desired alignment level in a 271 manner similar to BSD implementations of "struct in_addr". Those 272 additional implementation details are omitted here for simplicity. 274 An example is as follows: 276 struct in6_addr { 277 union { 278 uint8_t _S6_u8[16]; 279 uint32_t _S6_u32[4]; 280 uint64_t _S6_u64[2]; 281 } _S6_un; 282 }; 283 #define s6_addr _S6_un._S6_u8 285 3.3 Socket Address Structure for 4.3BSD-Based Systems 287 In the socket interface, a different protocol-specific data structure is 288 defined to carry the addresses for each protocol suite. Each protocol- 289 specific data structure is designed so it can be cast into a protocol- 290 independent data structure -- the "sockaddr" structure. Each has a 291 "family" field that overlays the "sa_family" of the sockaddr data 292 structure. This field identifies the type of the data structure. 294 The sockaddr_in structure is the protocol-specific address data 295 structure for IPv4. It is used to pass addresses between applications 296 and the system in the socket functions. The following sockaddr_in6 297 structure holds IPv6 addresses and is defined as a result of including 298 the header: 300 struct sockaddr_in6 { 301 sa_family_t sin6_family; /* AF_INET6 */ 302 in_port_t sin6_port; /* transport layer port # */ 303 uint32_t sin6_flowinfo; /* IPv6 traffic class & flow info */ 304 struct in6_addr sin6_addr; /* IPv6 address */ 305 uint32_t sin6_scope_id; /* set of interfaces for a scope */ 306 }; 308 This structure is designed to be compatible with the sockaddr data 309 structure used in the 4.3BSD release. 311 The sin6_family field identifies this as a sockaddr_in6 structure. This 312 field overlays the sa_family field when the buffer is cast to a sockaddr 313 data structure. The value of this field must be AF_INET6. 315 The sin6_port field contains the 16-bit UDP or TCP port number. This 316 field is used in the same way as the sin_port field of the sockaddr_in 317 structure. The port number is stored in network byte order. 319 The sin6_flowinfo field is a 32-bit field that contains two pieces of 320 information: the traffic class and the flow label. The contents and 321 interpretation of this member is specified in [1]. The sin6_flowinfo 322 field SHOULD be set to zero by an implementation prior to using the 323 sockaddr_in6 structure by an application on receive operations. 325 The sin6_addr field is a single in6_addr structure (defined in the 326 previous section). This field holds one 128-bit IPv6 address. The 327 address is stored in network byte order. 329 The ordering of elements in this structure is specifically designed so 330 that when sin6_addr field is aligned on a 64-bit boundary, the start of 331 the structure will also be aligned on a 64-bit boundary. This is done 332 for optimum performance on 64-bit architectures. 334 The sin6_scope_id field is a 32-bit integer that identifies a set of 335 interfaces as appropriate for the scope of the address carried in the 336 sin6_addr field [2,5,6,7]. For a link scope sin6_addr, sin6_scope_id 337 would be an interface index. For a site scope sin6_addr, sin6_scope_id 338 would be a site identifier. The mapping of sin6_scope_id to an 339 interface or set of interfaces is left to implementation and future 340 specifications on the subject of site identifiers. 342 Notice that the sockaddr_in6 structure will normally be larger than the 343 generic sockaddr structure. On many existing implementations the 344 sizeof(struct sockaddr_in) equals sizeof(struct sockaddr), with both 345 being 16 bytes. Any existing code that makes this assumption needs to 346 be examined carefully when converting to IPv6. 348 3.4 Socket Address Structure for 4.4BSD-Based Systems 350 The 4.4BSD release includes a small, but incompatible change to the 351 socket interface. The "sa_family" field of the sockaddr data structure 352 was changed from a 16-bit value to an 8-bit value, and the space saved 353 used to hold a length field, named "sa_len". The sockaddr_in6 data 354 structure given in the previous section cannot be correctly cast into 355 the newer sockaddr data structure. For this reason, the following 356 alternative IPv6 address data structure is provided to be used on 357 systems based on 4.4BSD. It is defined as a result of including the 358 header. 360 struct sockaddr_in6 { 361 uint8_t sin6_len; /* length of this struct */ 362 sa_family_t sin6_family; /* AF_INET6 */ 363 in_port_t sin6_port; /* transport layer port # */ 364 uint32_t sin6_flowinfo; /* IPv6 flow information */ 365 struct in6_addr sin6_addr; /* IPv6 address */ 366 uint32_t sin6_scope_id; /* set of interfaces for a scope */ 367 }; 369 The only differences between this data structure and the 4.3BSD variant 370 are the inclusion of the length field, and the change of the family 371 field to a 8-bit data type. The definitions of all the other fields are 372 identical to the structure defined in the previous section. 374 Systems that provide this version of the sockaddr_in6 data structure 375 must also declare SIN6_LEN as a result of including the 376 header. This macro allows applications to determine whether they are 377 being built on a system that supports the 4.3BSD or 4.4BSD variants of 378 the data structure. 380 3.5 The Socket Functions 382 Applications call the socket() function to create a socket descriptor 383 that represents a communication endpoint. The arguments to the socket() 384 function tell the system which protocol to use, and what format address 385 structure will be used in subsequent functions. For example, to create 386 an IPv4/TCP socket, applications make the call: 388 s = socket(PF_INET, SOCK_STREAM, 0); 390 To create an IPv4/UDP socket, applications make the call: 392 s = socket(PF_INET, SOCK_DGRAM, 0); 394 Applications may create IPv6/TCP and IPv6/UDP sockets by simply using 395 the constant PF_INET6 instead of PF_INET in the first argument. For 396 example, to create an IPv6/TCP socket, applications make the call: 398 s = socket(PF_INET6, SOCK_STREAM, 0); 400 To create an IPv6/UDP socket, applications make the call: 402 s = socket(PF_INET6, SOCK_DGRAM, 0); 404 Once the application has created a PF_INET6 socket, it must use the 405 sockaddr_in6 address structure when passing addresses in to the system. 406 The functions that the application uses to pass addresses into the 407 system are: 409 bind() 410 connect() 411 sendmsg() 412 sendto() 414 The system will use the sockaddr_in6 address structure to return 415 addresses to applications that are using PF_INET6 sockets. The 416 functions that return an address from the system to an application are: 418 accept() 419 recvfrom() 420 recvmsg() 421 getpeername() 422 getsockname() 424 No changes to the syntax of the socket functions are needed to support 425 IPv6, since all of the "address carrying" functions use an opaque 426 address pointer, and carry an address length as a function argument. 428 3.6 Compatibility with IPv4 Applications 430 In order to support the large base of applications using the original 431 API, system implementations must provide complete source and binary 432 compatibility with the original API. This means that systems must 433 continue to support PF_INET sockets and the sockaddr_in address 434 structure. Applications must be able to create IPv4/TCP and IPv4/UDP 435 sockets using the PF_INET constant in the socket() function, as 436 described in the previous section. Applications should be able to hold 437 a combination of IPv4/TCP, IPv4/UDP, IPv6/TCP and IPv6/UDP sockets 438 simultaneously within the same process. 440 Applications using the original API should continue to operate as they 441 did on systems supporting only IPv4. That is, they should continue to 442 interoperate with IPv4 nodes. 444 3.7 Compatibility with IPv4 Nodes 446 The API also provides a different type of compatibility: the ability for 447 IPv6 applications to interoperate with IPv4 applications. This feature 448 uses the IPv4-mapped IPv6 address format defined in the IPv6 addressing 449 architecture specification [2]. This address format allows the IPv4 450 address of an IPv4 node to be represented as an IPv6 address. The IPv4 451 address is encoded into the low-order 32 bits of the IPv6 address, and 452 the high-order 96 bits hold the fixed prefix 0:0:0:0:0:FFFF. IPv4- 453 mapped addresses are written as follows: 455 ::FFFF: 457 These addresses can be generated automatically by the getipnodebyname() 458 and getaddrinfo() functions, when the specified host has only IPv4 459 addresses (as described in Section 6.1 and 6.4). 461 Applications may use PF_INET6 sockets to open TCP connections to IPv4 462 nodes, or send UDP packets to IPv4 nodes, by simply encoding the 463 destination's IPv4 address as an IPv4-mapped IPv6 address, and passing 464 that address, within a sockaddr_in6 structure, in the connect() or 465 sendto() call. When applications use PF_INET6 sockets to accept TCP 466 connections from IPv4 nodes, or receive UDP packets from IPv4 nodes, the 467 system returns the peer's address to the application in the accept(), 468 recvfrom(), or getpeername() call using a sockaddr_in6 structure encoded 469 this way. 471 Few applications will likely need to know which type of node they are 472 interoperating with. However, for those applications that do need to 473 know, the IN6_IS_ADDR_V4MAPPED() macro, defined in Section 6.7, is 474 provided. 476 3.8 IPv6 Wildcard Address 478 While the bind() function allows applications to select the source IP 479 address of UDP packets and TCP connections, applications often want the 480 system to select the source address for them. With IPv4, one specifies 481 the address as the symbolic constant INADDR_ANY (called the "wildcard" 482 address) in the bind() call, or simply omits the bind() entirely. 484 Since the IPv6 address type is a structure (struct in6_addr), a symbolic 485 constant can be used to initialize an IPv6 address variable, but cannot 486 be used in an assignment. Therefore systems provide the IPv6 wildcard 487 address in two forms. 489 The first version is a global variable named "in6addr_any" that is an 490 in6_addr structure. The extern declaration for this variable is defined 491 in : 493 extern const struct in6_addr in6addr_any; 495 Applications use in6addr_any similarly to the way they use INADDR_ANY in 496 IPv4. For example, to bind a socket to port number 23, but let the 497 system select the source address, an application could use the following 498 code: 500 struct sockaddr_in6 sin6; 501 . . . 502 sin6.sin6_family = AF_INET6; 503 sin6.sin6_flowinfo = 0; 504 sin6.sin6_port = htons(23); 505 sin6.sin6_addr = in6addr_any; /* structure assignment */ 506 . . . 507 if (bind(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 508 . . . 510 The other version is a symbolic constant named IN6ADDR_ANY_INIT and is 511 defined in . This constant can be used to initialize an 512 in6_addr structure: 514 struct in6_addr anyaddr = IN6ADDR_ANY_INIT; 516 Note that this constant can be used ONLY at declaration time. It can 517 not be used to assign a previously declared in6_addr structure. For 518 example, the following code will not work: 520 /* This is the WRONG way to assign an unspecified address */ 521 struct sockaddr_in6 sin6; 522 . . . 523 sin6.sin6_addr = IN6ADDR_ANY_INIT; /* will NOT compile */ 525 Be aware that the IPv4 INADDR_xxx constants are all defined in host byte 526 order but the IPv6 IN6ADDR_xxx constants and the IPv6 in6addr_xxx 527 externals are defined in network byte order. 529 3.9 IPv6 Loopback Address 531 Applications may need to send UDP packets to, or originate TCP 532 connections to, services residing on the local node. In IPv4, they can 533 do this by using the constant IPv4 address INADDR_LOOPBACK in their 534 connect(), sendto(), or sendmsg() call. 536 IPv6 also provides a loopback address to contact local TCP and UDP 537 services. Like the unspecified address, the IPv6 loopback address is 538 provided in two forms -- a global variable and a symbolic constant. 540 The global variable is an in6_addr structure named "in6addr_loopback." 541 The extern declaration for this variable is defined in : 543 extern const struct in6_addr in6addr_loopback; 545 Applications use in6addr_loopback as they would use INADDR_LOOPBACK in 546 IPv4 applications (but beware of the byte ordering difference mentioned 547 at the end of the previous section). For example, to open a TCP 548 connection to the local telnet server, an application could use the 549 following code: 551 struct sockaddr_in6 sin6; 552 . . . 553 sin6.sin6_family = AF_INET6; 554 sin6.sin6_flowinfo = 0; 555 sin6.sin6_port = htons(23); 556 sin6.sin6_addr = in6addr_loopback; /* structure assignment */ 557 . . . 558 if (connect(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 559 . . . 561 The symbolic constant is named IN6ADDR_LOOPBACK_INIT and is defined in 562 . It can be used at declaration time ONLY; for example: 564 struct in6_addr loopbackaddr = IN6ADDR_LOOPBACK_INIT; 566 Like IN6ADDR_ANY_INIT, this constant cannot be used in an assignment to 567 a previously declared IPv6 address variable. 569 3.10 Portability Additions 571 One simple addition to the sockets API that can help application writers 572 is the "struct sockaddr_storage". This data structure can simplify 573 writing portable code across multiple address families and platforms. 574 This data structure is designed with the following goals. 576 - Large enough to accomodate all supported protocol-specific address 577 structures. 578 - Aligned at an appropriate boundary so that pointers to it can be cast 579 as pointers to protocol specific address structures and used to 580 access the fields of those structures without alignment problems. 582 The sockaddr_storage structure contains field ss_family which is of type 583 sa_family_t. When a sockaddr_storage structure is cast to a sockaddr 584 structure, the ss_family field of the sockaddr_storage structure maps 585 onto the sa_family field of the sockaddr structure. When a 586 sockaddr_storage structure is cast as a protocol specific address 587 structure, the ss_family field maps onto a field of that structure that 588 is of type sa_family_t and that identifies the protocol's address 589 family. 591 An example implementation design of such a data structure would be as 592 follows. 594 /* 595 * Desired design of maximum size and alignment 596 */ 597 #define _SS_MAXSIZE 128 /* Implementation specific max size */ 598 #define _SS_ALIGNSIZE (sizeof (int64_t)) 599 /* Implementation specific desired alignment */ 600 /* 601 * Definitions used for sockaddr_storage structure paddings design. 602 */ 603 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof (sa_family_t)) 604 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 605 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 606 struct sockaddr_storage { 607 sa_family_t ss_family; /* address family */ 608 /* Following fields are implementation specific */ 609 char __ss_pad1[_SS_PAD1SIZE]; 610 /* 6 byte pad, this is to make implementation 611 /* specific pad up to alignment field that */ 612 /* follows explicit in the data structure */ 613 int64_t __ss_align; /* field to force desired structure */ 614 /* storage alignment */ 615 char __ss_pad2[_SS_PAD2SIZE]; 616 /* 112 byte pad to achieve desired size, */ 617 /* _SS_MAXSIZE value minus size of ss_family */ 618 /* __ss_pad1, __ss_align fields is 112 */ 619 }; 621 The above example implementation illustrates a data structure which 622 will align on a 64-bit boundary. An implementation-specific field 623 "_ss_align" along "_ss_pad1" is used to force a 64-bit alignment which 624 covers proper alignment good enough for needs of sockaddr_in6 (IPv6), 625 sockaddr_in (IPv4) address data structures. The size of padding fields 626 _ss_pad1 depends on the chosen alignment boundary. The size of padding 627 field _ss_pad2 depends on the value of overall size chosen for the total 628 size of the structure. This size and alignment are represented in the 629 above example by implementation specific (not required) constants 630 _SS_MAXSIZE (chosen value 128) and _SS_ALIGNMENT (with chosen value 8). 631 Constants _SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 632 112) are also for illustration and not required. The implementation specific 633 definitions and structure field names above start with an underscore to 634 denote implementation private namespace. Portable code is not expected to 635 access or reference those fields or constants. 637 On implementations where sockaddr data structure includes a "sa_len", 638 field this data structure would look like this: 640 /* 641 * Definitions used for sockaddr_storage structure paddings design. 643 */ 644 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - 645 (sizeof (uint8_t) + sizeof (sa_family_t)) 646 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 647 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 648 struct sockaddr_storage { 649 uint8_t ss_len; /* address length */ 650 sa_family_t ss_family; /* address family */ 651 /* Following fields are implementation specific */ 652 char __ss_pad1[_SS_PAD1SIZE]; 653 /* 6 byte pad, this is to make implementation 654 /* specific pad up to alignment field that */ 655 /* follows explicit in the data structure */ 656 int64_t __ss_align; /* field to force desired structure */ 657 /* storage alignment */ 658 char __ss_pad2[_SS_PAD2SIZE]; 659 /* 112 byte pad to achieve desired size, */ 660 /* _SS_MAXSIZE value minus size of ss_len, */ 661 /* __ss_family, __ss_pad1, __ss_align fields is 112 */ 662 }; 664 4. Interface Identification 666 This API uses an interface index (a small positive integer) to identify 667 the local interface on which a multicast group is joined (Section 5.3). 668 Additionally, the advanced API [4] uses these same interface indexes to 669 identify the interface on which a datagram is received, or to specify 670 the interface on which a datagram is to be sent. 672 Interfaces are normally known by names such as "le0", "sl1", "ppp2", and 673 the like. On Berkeley-derived implementations, when an interface is 674 made known to the system, the kernel assigns a unique positive integer 675 value (called the interface index) to that interface. These are small 676 positive integers that start at 1. (Note that 0 is never used for an 677 interface index.) There may be gaps so that there is no current 678 interface for a particular positive interface index. 680 This API defines two functions that map between an interface name and 681 index, a third function that returns all the interface names and 682 indexes, and a fourth function to return the dynamic memory allocated by 683 the previous function. How these functions are implemented is left up 684 to the implementation. 4.4BSD implementations can implement these 685 functions using the existing sysctl() function with the NET_RT_IFLIST 686 command. Other implementations may wish to use ioctl() for this 687 purpose. 689 4.1 Name-to-Index 691 The first function maps an interface name into its corresponding index. 693 #include 695 unsigned int if_nametoindex(const char *ifname); 697 If the specified interface name does not exist, the return value is 0, 698 and errno is set to ENXIO. If there was a system error (such as 699 running out of memory), the return value is 0 and errno is set to the 700 proper value (e.g., ENOMEM). 702 4.2 Index-to-Name 704 The second function maps an interface index into its corresponding name. 706 #include 708 char *if_indextoname(unsigned int ifindex, char *ifname); 710 The ifname argument must point to a buffer of at least IF_NAMESIZE bytes 711 into which the interface name corresponding to the specified index is 712 returned. (IF_NAMESIZE is also defined in and its value 713 includes a terminating null byte at the end of the interface name.) This 714 pointer is also the return value of the function. If there is no 715 interface corresponding to the specified index, NULL is returned, and 716 errno is set to ENXIO, if there was a system error (such as running out 717 of memory), if_indextoname returns NULL and errno would be set to the 718 proper value (e.g., ENOMEM). 720 4.3 Return All Interface Names and Indexes 722 The if_nameindex structure holds the information about a single 723 interface and is defined as a result of including the header. 725 struct if_nameindex { 726 unsigned int if_index; /* 1, 2, ... */ 727 char *if_name; /* null terminated name: "le0", ... */ 728 }; 730 The final function returns an array of if_nameindex structures, one 731 structure per interface. 733 struct if_nameindex *if_nameindex(void); 735 The end of the array of structures is indicated by a structure with an 736 if_index of 0 and an if_name of NULL. The function returns a NULL 737 pointer upon an error, and would set errno to the appropriate value. 739 The memory used for this array of structures along with the interface 740 names pointed to by the if_name members is obtained dynamically. This 741 memory is freed by the next function. 743 4.4 Free Memory 745 The following function frees the dynamic memory that was allocated by 746 if_nameindex(). 748 #include 749 void if_freenameindex(struct if_nameindex *ptr); 751 The argument to this function must be a pointer that was returned by 752 if_nameindex(). 754 Currently net/if.h doesn't have prototype definitions for functions and 755 it is recommended that these definitions be defined in net/if.h as well 756 and the struct if_nameindex{}. 758 5. Socket Options 760 A number of new socket options are defined for IPv6. All of these new 761 options are at the IPPROTO_IPV6 level. That is, the "level" parameter 762 in the getsockopt() and setsockopt() calls is IPPROTO_IPV6 when using 763 these options. The constant name prefix IPV6_ is used in all of the new 764 socket options. This serves to clearly identify these options as 765 applying to IPv6. 767 The declaration for IPPROTO_IPV6, the new IPv6 socket options, and 768 related constants defined in this section are obtained by including the 769 header . 771 5.1 Unicast Hop Limit 773 A new setsockopt() option controls the hop limit used in outgoing 774 unicast IPv6 packets. The name of this option is IPV6_UNICAST_HOPS, and 775 it is used at the IPPROTO_IPV6 layer. The following example illustrates 776 how it is used: 778 int hoplimit = 10; 780 if (setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 781 (char *) &hoplimit, sizeof(hoplimit)) == -1) 782 perror("setsockopt IPV6_UNICAST_HOPS"); 784 When the IPV6_UNICAST_HOPS option is set with setsockopt(), the option 785 value given is used as the hop limit for all subsequent unicast packets 786 sent via that socket. If the option is not set, the system selects a 787 default value. The integer hop limit value (called x) is interpreted as 788 follows: 790 x < -1: return an error of EINVAL 791 x == -1: use kernel default 792 0 <= x <= 255: use x 793 x >= 256: return an error of EINVAL 795 The IPV6_UNICAST_HOPS option may be used with getsockopt() to determine 796 the hop limit value that the system will use for subsequent unicast 797 packets sent via that socket. For example: 799 int hoplimit; 800 size_t len = sizeof(hoplimit); 802 if (getsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 803 (char *) &hoplimit, &len) == -1) 804 perror("getsockopt IPV6_UNICAST_HOPS"); 805 else 806 printf("Using %d for hop limit.\n", hoplimit); 808 5.2 Sending and Receiving Multicast Packets 810 IPv6 applications may send UDP multicast packets by simply specifying an 811 IPv6 multicast address in the address argument of the sendto() function. 813 Three socket options at the IPPROTO_IPV6 layer control some of the 814 parameters for sending multicast packets. Setting these options is not 815 required: applications may send multicast packets without using these 816 options. The setsockopt() options for controlling the sending of 817 multicast packets are summarized below. These three options can also be 818 used with getsockopt(). 820 IPV6_MULTICAST_IF 822 Set the interface to use for outgoing multicast packets. 823 The argument is the index of the interface to use. 825 Argument type: unsigned int 827 IPV6_MULTICAST_HOPS 829 Set the hop limit to use for outgoing multicast packets. 830 (Note a separate option - IPV6_UNICAST_HOPS - is 831 provided to set the hop limit to use for outgoing 832 unicast packets.) 834 The interpretation of the argument is the same 835 as for the IPV6_UNICAST_HOPS option: 837 x < -1: return an error of EINVAL 838 x == -1: use kernel default 839 0 <= x <= 255: use x 840 x >= 256: return an error of EINVAL 842 If IPV6_MULTICAST_HOPS is not set, the default is 1 843 (same as IPv4 today) 845 Argument type: int 847 IPV6_MULTICAST_LOOP 849 If a multicast datagram is sent to a group to which the sending host 850 itself belongs (on the outgoing interface), a copy of the datagram is 851 looped back by the IP layer for local delivery if this option is set to 852 1. If this option is set to 0 a copy is not looped back. Other option 853 values return an error of EINVAL. 855 If IPV6_MULTICAST_LOOP is not set, the default is 1 (loopback; same as 856 IPv4 today). 858 Argument type: unsigned int 860 The reception of multicast packets is controlled by the two setsockopt() 861 options summarized below. An error of EOPNOTSUPP is returned if these 862 two options are used with getsockopt(). 864 IPV6_JOIN_GROUP 866 Join a multicast group on a specified local interface. 867 If the interface index is specified as 0, 868 the kernel chooses the local interface. 869 For example, some kernels look up the multicast group 870 in the normal IPv6 routing table and use the resulting interface. 872 Argument type: struct ipv6_mreq 874 IPV6_LEAVE_GROUP 876 Leave a multicast group on a specified interface. 878 Argument type: struct ipv6_mreq 880 The argument type of both of these options is the ipv6_mreq structure, 881 defined as a result of including the header; 883 struct ipv6_mreq { 884 struct in6_addr ipv6mr_multiaddr; /* IPv6 multicast addr */ 885 unsigned int ipv6mr_interface; /* interface index */ 886 }; 888 Note that to receive multicast datagrams a process must join the 889 multicast group and bind the UDP port to which datagrams will be sent. 890 Some processes also bind the multicast group address to the socket, in 891 addition to the port, to prevent other datagrams destined to that same 892 port from being delivered to the socket. 894 6. Library Functions 896 New library functions are needed to perform a variety of operations with 897 IPv6 addresses. Functions are needed to lookup IPv6 addresses in the 898 Domain Name System (DNS). Both forward lookup (nodename-to-address 899 translation) and reverse lookup (address-to-nodename translation) need 900 to be supported. Functions are also needed to convert IPv6 addresses 901 between their binary and textual form. 903 We note that the two existing functions, gethostbyname() and 904 gethostbyaddr(), are left as-is. New functions are defined to handle 905 both IPv4 and IPv6 addresses. 907 6.1 Nodename-to-Address Translation 909 Note: This function at this time MUST not be used by any applications 910 that will want to support scope_ids [5,6,7] within an application, and 911 for those applications the getaddrinfo() function should be used as 912 specified in section 6.4 of this specification. 914 The commonly used function gethostbyname() is inadequate for many 915 applications, first because it provides no way for the caller to specify 916 anything about the types of addresses desired (IPv4 only, IPv6 only, 917 IPv4-mapped IPv6 are OK, etc.), and second because many implementations 918 of this function are not thread safe. RFC 2133 defined a function named 919 gethostbyname2() but this function was also inadequate, first because 920 its use required setting a global option (RES_USE_INET6) when IPv6 921 addresses were required, and second because a flag argument is needed to 922 provide the caller with additional control over the types of addresses 923 required. 925 The following function is new and must be thread safe: 927 #include 928 #include 930 struct hostent *getipnodebyname(const char *name, int af, int flags 931 int *error_num); 933 The name argument can be either a node name or a numeric address string 934 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address). The af 935 argument specifies the address family, either AF_INET or AF_INET6. The 936 error_num value is returned to the caller, via a pointer, with the 937 appropriate error code in error_num, to support thread safe error code 938 returns. error_num will be set to one of the following values: 940 HOST_NOT_FOUND 942 No such host is known. 944 NO_ADDRESS 946 The server recognised the request and the name but no address 947 is available. Another type of request to the name server for 948 the domain might return an answer. 950 NO_RECOVERY 952 An unexpected server failure occurred which cannot be recovered. 954 TRY_AGAIN 956 A temporary and possibly transient error occurred, such as a 957 failure of a server to respond. 959 The flags argument specifies the types of addresses that are searched 960 for, and the types of addresses that are returned. We note that a 961 special flags value of AI_DEFAULT (defined below) should handle most 962 applications. 964 That is, porting simple applications to use IPv6 replaces the call 966 hptr = gethostbyname(name); 968 with 970 hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num); 972 and changes any subsequent error diagnosis code to use error_num instead 973 of externally declared variables, such as h_errno. 975 Applications desiring finer control over the types of addresses searched 976 for and returned, can specify other combinations of the flags argument. 978 A flags of 0 implies a strict interpretation of the af argument: 980 - If flags is 0 and af is AF_INET, then the caller wants only IPv4 981 addresses. A query is made for A records. If successful, the IPv4 982 addresses are returned and the h_length member of the hostent 983 structure will be 4, else the function returns a NULL pointer. 985 - If flags is 0 and if af is AF_INET6, then the caller wants only 986 IPv6 addresses. A query is made for AAAA/A6 records. If successful, 987 the IPv6 addresses are returned and the h_length member of the 988 hostent structure will be 16, else the function returns a NULL 989 pointer. 991 Other constants can be logically-ORed into the flags argument, to modify 992 the behavior of the function. 994 - If the AI_V4MAPPED flag is specified along with an af of 995 AF_INET6, then the caller will accept IPv4-mapped IPv6 996 addresses. That is, if no AAAA or A6 records are found then a query 997 is made for A records and any found are returned as IPv4-mapped 998 IPv6 addresses (h_length will be 16). The AI_V4MAPPED flag is 999 ignored unless af equals AF_INET6. 1001 - The AI_ALL flag is used in conjunction with the AI_V4MAPPED 1002 flag, and is only used with the IPv6 address family. When AI_ALL 1003 is logically or'd with AI_V4MAPPED flag then the caller wants 1004 all addresses: IPv6 and IPv4-mapped IPv6. A query is first made 1005 for AAAA/A6 records and if successful, the IPv6 addresses are returned. 1006 Another query is then made for A records and any found are returned 1007 as IPv4-mapped IPv6 addresses. h_length will be 16. Only if both 1008 queries fail does the function return a NULL pointer. This flag is 1009 ignored unless af equals AF_INET6. 1011 - The AI_ADDRCONFIG flag specifies that a query for AAAA/A6 records 1012 should occur only if the node has at least one IPv6 source address 1013 configured and a query for A records should occur only if the 1014 node has at least one IPv4 source address configured. 1016 For example, if the node has no IPv6 source addresses configured, 1017 and af equals AF_INET6, and the node name being looked up has both 1018 AAAA/A6 and A records, then: 1020 (a) if only AI_ADDRCONFIG is specified, the function returns a 1021 NULL pointer; 1022 (b) if AI_ADDRCONFIG | AI_V4MAPPED is specified, the A records 1023 are returned as IPv4-mapped IPv6 addresses; 1025 The special flags value of AI_DEFAULT is defined as 1027 #define AI_DEFAULT (AI_V4MAPPED | AI_ADDRCONFIG) 1029 We noted that the getipnodebyname() function must allow the name 1030 argument to be either a node name or a literal address string (i.e., a 1031 dotted-decimal IPv4 address or an IPv6 hex address). This saves 1032 applications from having to call inet_pton() to handle literal address 1033 strings. 1035 There are four scenarios based on the type of literal address string and 1036 the value of the af argument. 1038 The two simple cases are: 1040 When name is a dotted-decimal IPv4 address and af equals AF_INET, or 1041 when name is an IPv6 hex address and af equals AF_INET6. The members of 1042 the returned hostent structure are: h_name points to a copy of the name 1043 argument, h_aliases is a NULL pointer, h_addrtype is a copy of the af 1044 argument, h_length is either 4 (for AF_INET) or 16 (for AF_INET6), 1045 h_addr_list[0] is a pointer to the 4-byte or 16-byte binary address, and 1046 h_addr_list[1] is a NULL pointer. 1048 When name is a dotted-decimal IPv4 address and af equals AF_INET6, and 1049 flags equals AI_V4MAPPED, an IPv4-mapped IPv6 address is returned: 1050 h_name points to a copy of the name argument, h_aliases is a NULL 1051 pointer, h_addrtype is AF_INET6, h_length is 16, h_addr_list[0] is a 1052 pointer to the 16-byte binary address, and h_addr_list[1] is a NULL 1053 pointer. 1055 If AI_V4MAPPED is set (with or without AI_ALL) return IPv4-mapped 1056 otherwise return NULL. 1058 It is an error when name is an IPv6 hex address and af equals AF_INET. 1059 The function's return value is a NULL pointer and error_num equals 1060 HOST_NOT_FOUND. 1062 6.2 Address-To-Nodename Translation 1064 Note: Applications using scope identifiers should use getnameinfo() as 1065 spepcified in section 6.5. 1067 The following function has the same arguments as the existing 1068 gethostbyaddr() function, but adds an error number. 1070 #include 1071 #include 1073 struct hostent *getipnodebyaddr(const void *src, size_t len, int af, 1074 int *error_num); 1076 As with getipnodebyname(), getipnodebyaddr() must be thread safe. The 1077 error_num value is returned to the caller with the appropriate error 1078 code, to support thread safe error code returns. The following error 1079 conditions may be returned for error_num: 1081 HOST_NOT_FOUND 1083 No such host is known. 1085 NO_ADDRESS 1086 The server recognized the request and the name but no address 1087 is available. Another type of request to the name server for 1088 the domain might return an answer. 1090 NO_RECOVERY 1092 An unexpected server failure occurred which cannot be recovered. 1094 TRY_AGAIN 1096 A temporary and possibly transient error occurred, such as a 1097 failure of a server to respond. 1099 One possible source of confusion is the handling of IPv4-mapped IPv6 1100 addresses and IPv4-compatible IPv6 addresses, but the following logic 1101 should apply. 1103 1. If af is AF_INET6, and if len equals 16, and if the IPv6 address 1104 is an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, 1105 then skip over the first 12 bytes of the IPv6 address, set af to 1106 AF_INET, and set len to 4. 1108 2. If af is AF_INET, lookup the name for the given IPv4 address 1109 (e.g., query for a PTR record in the in-addr.arpa domain). 1111 3. If af is AF_INET6, lookup the name for the given IPv6 address 1112 (e.g., query for a PTR record in the ip6.int and ip6.arpa domains). 1114 4. If the function is returning success, then the single address that 1115 is returned in the hostent structure is a copy of the first argument 1116 to the function with the same address family that was passed as 1117 an argument to this function. 1119 All four steps listed are performed, in order. Also note that the IPv6 1120 hex addresses "::" and "::1" MUST NOT be treated as IPv4-compatible 1121 addresses, and if the address is "::", HOST_NOT_FOUND MUST be returned 1122 and a query of the address not performed. 1124 Also for the macro in section 6.7 IN6_IS_ADDR_V4COMPAT MUST return false 1125 for "::" and "::1". 1127 6.3 Freeing memory for getipnodebyname and getipnodebyaddr 1129 The hostent structure does not change from its existing definition. 1130 This structure, and the information pointed to by this structure, are 1131 dynamically allocated by getipnodebyname and getipnodebyaddr. The 1132 following function frees this memory: 1134 #include 1136 void freehostent(struct hostent *ptr); 1138 6.4 Protocol-Independent Nodename and Service Name Translation 1140 Nodename-to-address translation is done in a protocol-independent 1141 fashion using the getaddrinfo() function that is taken from the 1142 Institute of Electrical and Electronic Engineers (IEEE) POSIX 1003.1g 1143 (Protocol Independent Interfaces) draft specification [3]. 1145 The official specification for this function will be the final POSIX 1146 standard. 1148 #include 1149 #include 1151 int getaddrinfo(const char *nodename, const char *servname, 1152 const struct addrinfo *hints, struct addrinfo **res); 1154 void freeaddrinfo(struct addrinfo *ai); 1156 struct addrinfo { 1157 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, .. */ 1158 int ai_family; /* PF_xxx */ 1159 int ai_socktype; /* SOCK_xxx */ 1160 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 1161 size_t ai_addrlen; /* length of ai_addr */ 1162 char *ai_canonname; /* canonical name for nodename */ 1163 struct sockaddr *ai_addr; /* binary address */ 1164 struct addrinfo *ai_next; /* next structure in linked list */ 1165 }; 1167 The getaddrinfo ( ) function translates the name of a service 1168 location (for example, a host name) and/or a service name and returns 1169 a set of socket addresses and associated information to be used in 1170 creating a socket with which to address the specified service. 1172 The nodename and servname arguments are either null pointers or 1173 pointers to null-terminated strings. One or both of these two 1174 arguments must be a non-null pointer. 1176 The format of a valid name depends on the protocol family or 1177 families. If a specific family is not given and the name could be 1178 interpreted as valid within multiple supported families, the 1179 implementation will attempt to resolve the name in all supported 1180 families and, all successful results will be returned. 1182 If the nodename argument is not null, it can be a descriptive name or 1183 can be an address string. If the specified address family is AF_INET, 1184 or AF_UNSPEC, the permisssable nodename argument is specified as 1185 defined in inet_pton(). If the specified address family is AF_INET6 1186 or AF_UNSPEC, the permisssable nodename argument is specified as 1187 defined in [5]. 1189 If nodename is not null, the requested service location is named by 1190 nodename; otherwise, the requested service location is local to the 1191 caller. 1193 If servname is null, the call returns network-level addresses for the 1194 specified nodename. If servname is not null, it is a null-terminated 1195 character string identifying the requested service. This can be 1196 either a descriptive name or a numeric representation suitable for 1197 use with the address family or families. If the specified address 1198 family is AF_INET, AF_INET6 or AF_UNSPEC, the service can be 1199 specified as a string specifying a decimal port number. 1201 If the argument hints is not null, it refers to a structure 1202 containing input values that may direct the operation by providing 1203 options and by limiting the returned information to a specific socket 1204 type, address family and/or protocol. In this hints structure every 1205 member other than ai_flags, ai_family, ai_socktype and ai_protocol 1206 must be zero or a null pointer. A value of AF_UNSPEC for ai_family 1207 means that the caller will accept any protocol family. A value of 1208 zero for ai_socktype means that the caller will accept any socket 1209 type. A value of zero for ai_protocol means that the caller will 1210 accept any protocol. If hints is a null pointer, the behavior must be 1211 as if it referred to a structure containing the value zero for the 1212 ai_flags, ai_socktype and ai_protocol fields, and AF_UNSPEC for the 1213 ai_family field. 1215 Note: 1217 1. If the caller handles only TCP and not UDP, for example, then the 1218 ai_protocol member of the hints structure should be set to 1219 IPPROTO_TCP when getaddrinfo ( ) is called. 1221 2. If the caller handles only IPv4 and not IPv6, then the ai_family 1222 member of the hints structure should be set to PF_INET when 1223 getaddrinfo ( ) is called. 1225 The ai_flags field to which hints parameter points must have the 1226 value zero or be the bitwise OR of one or more of the values 1227 AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, 1228 AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG. 1230 The AI_PASSIVE flag in the ai_flags member of the hints structure 1231 specifies how to fill in the IP address portion of the socket address 1232 structure. If the AI_PASSIVE flag is specified, then the returned 1233 address information must be suitable for use in binding a socket for 1234 accepting incoming connections for the specified service (i.e. a call 1235 to bind()). In this case, if the nodename argument is null, then the 1236 IP address portion of the socket address structure will be set to 1237 INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 1238 address. If the AI_PASSIVE bit is not set, the returned address 1239 information must be suitable for a call to connect( ) (for a 1240 connection-mode protocol) or for a call to connect(), sendto() or 1241 sendmsg( ) (for a connectionless protocol). In this case, if the 1242 nodename argument is null, then the IP address portion of the socket 1243 address structure will be set to the loopback address. This flag is 1244 ignored if the nodename argument is not null. 1246 If the flag AI_CANONNAME is specified and the nodename argument is 1247 not null, the function attempts to determine the canonical name 1248 corresponding to nodename (for example, if nodename is an alias or 1249 shorthand notation for a complete name). 1251 If the flag AI_NUMERICHOST is specified then a non-null nodename 1252 string must be a numeric host address string. Otherwise an error of 1254 [EAI_NONAME] is returned. This flag prevents any type of name 1255 resolution service (for example, the DNS) from being invoked. 1257 If the flag AI_NUMERICSERV is specified then a non-null servname 1258 string must be a numeric port string. Otherwise an error [EAI_NONAME] 1259 is returned. This flag prevents any type of name resolution service 1260 (for example, NIS+) from being invoked. 1262 If the AI_V4MAPPED flag is specified along with an ai_family of 1263 AF_INET6, then the caller will accept IPv4-mapped IPv6 addresses. 1264 That is, if no AAAA or A6, records are found then a query is made for 1265 A records and any found are returned as IPv4-mapped IPv6 addresses 1266 (ai_addrlen will be 16). The AI_V4MAPPED flag is ignored unless 1267 ai_family equals AF_INET6. 1269 The AI_ALL flag is used in conjunction with the AI_V4MAPPED flag, and 1270 is only used with an ai_family of AF_INET6. When AI_ALL is logically 1271 or'd with AI_V4MAPPED flag then the caller will accept all addresses: 1272 IPv6 and IPv4-mapped IPv6. A query is first made for AAAA/A6 records 1273 and if successful, the IPv6 addresses are returned. Another query is 1274 then made for A records and any found are returned as IPv4-mapped 1275 IPv6 addresses (ai_addrlen will be 16). This flag is ignored unless 1276 ai_family equals AF_INET6. 1278 Note: 1280 When ai_family is not specified (AF_UNSPEC), AI_V4MAPPED and 1281 AI_ALL flags will only be used if AF_INET6 is supported. 1283 If the AI_ADDRCONFIG flag is specified then a query for AAAA or A6 1284 records should occur only if the node has at least one IPv6 source 1285 address configured and a query for A records should occur only if the 1286 node has at least one IPv4 source address configured. The loopback 1287 address is not considered for this case as valid as a configured 1288 sources address. 1290 The ai_socktype field to which argument hints points specifies the 1291 socket type for the service. If a specific socket type is not given 1292 (for example, a value of zero) and the service name could be 1293 interpreted as valid with multiple supported socket types, the 1294 implementation will attempt to resolve the service name for all 1295 supported socket types and, all successful results will be returned. 1296 A non-zero socket type value will limit the returned information to 1297 values with the specified socket type. 1299 The freeaddrinfo ( ) function frees one or more addrinfo structures 1300 returned by getaddrinfo ( ), along with any additional storage 1301 associated with those structures. If the ai_next field of the 1302 structure is not null, the entire list of structures is freed. The 1303 freeaddrinfo () function must support the freeing of arbitrary 1304 sublists of an addrinfo list originally returned by getaddrinfo (). 1306 Functions getaddrinfo ( ) and freeaddrinfo ( ) must be thread-safe. 1308 A zero return value for getaddrinfo ( ) indicates successful 1309 completion; a non-zero return value indicates failure. 1311 Upon successful return of getaddrinfo ( ), the location to which res 1312 points refers to a linked list of addrinfo structures, each of which 1313 specifies a socket address and information for use in creating a 1314 socket with which to use that socket address. The list must include 1315 at least one addrinfo structure. The ai_next field of each structure 1316 contains a pointer to the next structure on the list, or a null 1317 pointer if it is the last structure on the list. Each structure on 1318 the list includes values for use with a call to the socket( ) 1319 function, and a socket address for use with the connect() function 1320 or, if the AI_PASSIVE flag was specified, for use with the bind( ) 1321 function. The fields ai_family, ai_socktype, and ai_protocol are 1322 usable as the arguments to the socket() function to create a socket 1323 suitable for use with the returned address. The fields ai_addr and 1324 ai_addrlen are usable as the arguments to the connect() or bind( ) 1325 functions with such a socket, according to the AI_PASSIVE flag. 1327 If nodename is not null, and if requested by the AI_CANONNAME flag, 1328 the ai_canonname field of the first returned addrinfo structure 1329 points to a null-terminated string containing the canonical name 1330 corresponding to the input nodename; if the canonical name is not 1331 available, then ai_canonname refers to the argument nodename or a 1332 string with the same contents. The contents of the ai_flags field of 1333 the returned structures is undefined. 1335 All fields in socket address structures returned by getaddrinfo ( ) 1336 that are not filled in through an explicit argument (for example, 1337 sin6_flowinfo) must be set to zero. 1339 Note: This makes it easier to compare socket address structures. 1341 Error Return Values: 1343 [EAI_AGAIN] The name could not be resolved at this time. Future 1344 attempts may succeed. 1346 [EAI_BADFLAGS] The flags parameter had an invalid value. 1348 [EAI_FAIL] A non-recoverable error occurred when attempting to 1349 resolve the name. 1351 [EAI_FAMILY] The address family was not recognized. 1353 [EAI_MEMORY] There was a memory allocation failure when trying to 1354 allocate storage for the return value. 1356 [EAI_NONAME] The name does not resolve for the supplied parameters. 1357 Neither nodename nor servname were passed. At least one 1358 of these must be passed. 1360 [EAI_SERVICE] The service passed was not recognized for the specified 1361 socket type. 1363 [EAI_SOCKTYPE] The intended socket type was not recognized. 1365 [EAI_SYSTEM] A system error occurred; the error code can be found in 1366 errno. 1368 #include 1369 #include 1371 char *gai_strerror(int ecode); 1373 The argument is one of the EAI_xxx values defined earlier and the return 1374 value points to a string describing the error. If the argument is not 1375 one of the EAI_xxx values, the function still returns a pointer to a 1376 string whose contents indicate an unknown error. 1378 6.5 Socket Address Structure to Nodename and Service Name 1380 The official specification for this function will be the final POSIX 1381 standard update to getaddrinfo(), and will incorporate this function. 1383 #include 1384 #include 1386 int getnameinfo(const struct sockaddr *sa, socklen_t salen, 1387 char *host, size_t hostlen, 1388 char *serv, size_t servlen, 1389 int flags); 1391 The getnameinfo( ) translates a socket address to a node name and 1392 service location, all of which are defined as with getaddrinfo (). 1394 The argument sa points to a socket address structure to be translated. 1396 If the argument node is non-NULL and the argument nodelen is nonzero, 1397 then the argument node points to a buffer able to contain up to nodelen 1398 characters that will receive the node name as a null-terminated string. 1399 If the argument node is NULL or the argument nodelen is zero, the node 1400 name will not be returned. If the node�s name cannot be located, the 1401 numeric form of the nodes address is returned instead of its name. If 1402 the sa argument is an IPv6 address the returned nodename may be in the 1403 format as defined in [5]. 1405 If the argument service is non-NULL and the argument servicelen is 1406 nonzero, then the argument service points to a buffer able to contain up 1407 to servicelen characters that will receive the service name as a null- 1408 terminated string. If the argument service is NULL or the argument 1409 servicelen is zero, the service name will not be returned. If the 1410 service name cannot be located, the numeric form of the service address 1411 (for example, its port number) is returned instead of its name. 1413 The arguments node and service cannot both be NULL. 1415 The flags argument is a flag that changes the default actions of the 1416 function. By default the fully-qualified domain name (FQDN) for the host 1417 is returned, but 1419 - If the flag bit NI_NOFQDN is set, only the nodename portion of the 1420 FQDN is returned for local hosts. 1422 - If the flag bit NI_NUMERICHOST is set, the numeric form of the 1423 host's address is returned instead of its name, under all 1424 circumstances. 1426 - If the flag bit NI_NAMEREQD is set, an error is returned if the 1427 host�s name cannot be located. 1429 - If the flag bit NI_NUMERICSERV is set, the numeric form of the 1430 service address is returned (for example, its port number) instead of 1431 its name, under all circumstances. 1433 - If the flag bit NI_NUMERICSCOPE is set, the numeric form of the 1434 scope identifier is returned (for example, interface index) 1435 instead of its name. This flag is ignored if the sa argument is 1436 not an IPv6 address. 1438 - If the flag bit NI_DGRAM is set, this indicates that the service is 1439 a datagram service (SOCK_DGRAM). The default behavior is to assume that 1440 the service is a stream service (SOCK_STREAM). 1442 Note: 1444 1. The three NI_NUMERICxxx flags are required to support the "-n" 1445 flags that many commands support. 1446 2. The NI_DGRAM flag is required for the new AF_INET/AF_INET6 port 1447 numbers (for example, 512-514) that represent different services 1448 for UDP and TCP. 1450 Function getnameinfo() must be thread safe. 1452 A zero return value for getnameinfo( ) indicates successful completion; 1453 a non-zero return value indicates failure. 1455 On successful completion, function getnameinfo( ) returns the node and 1456 service names, if requested, in the buffers provided. The returned names 1457 are always null-terminated strings. 1459 Error Return Values: 1461 [EAI_AGAIN] The name could not be resolved at this time. 1462 Future attempts may succeed. 1464 [EAI_BADFLAGS] The flags had an invalid value. 1466 [EAI_FAIL] A non-recoverable error occurred. 1468 [EAI_FAMILY] The address family was not recognized or the address 1469 length was invalid for the specified family. 1471 [EAI_MEMORY] There was a memory allocation failure. 1473 [EAI_NONAME] The name does not resolve for the supplied parameters. 1474 NI_NAMEREQD is set and the host�s name cannot be located, or 1475 both nodename and servname were null. 1477 [EAI_SYSTEM] A system error occurred. The error code can be found in 1478 errno. 1480 6.6 Address Conversion Functions 1482 The two functions inet_addr() and inet_ntoa() convert an IPv4 address 1483 between binary and text form. IPv6 applications need similar functions. 1484 The following two functions convert both IPv6 and IPv4 addresses: 1486 #include 1487 #include 1489 int inet_pton(int af, const char *src, void *dst); 1491 const char *inet_ntop(int af, const void *src, 1492 char *dst, size_t size); 1494 The inet_pton() function converts an address in its standard text 1495 presentation form into its numeric binary form. The af argument 1496 specifies the family of the address. Currently the AF_INET and AF_INET6 1497 address families are supported. The src argument points to the string 1498 being passed in. The dst argument points to a buffer into which the 1499 function stores the numeric address. The address is returned in network 1500 byte order. Inet_pton() returns 1 if the conversion succeeds, 0 if the 1501 input is not a valid IPv4 dotted-decimal string or a valid IPv6 address 1502 string, or -1 with errno set to EAFNOSUPPORT if the af argument is 1503 unknown. The calling application must ensure that the buffer referred 1504 to by dst is large enough to hold the numeric address (e.g., 4 bytes for 1505 AF_INET or 16 bytes for AF_INET6). 1507 If the af argument is AF_INET, the function accepts a string in the 1508 standard IPv4 dotted-decimal form: 1510 ddd.ddd.ddd.ddd 1512 where ddd is a one to three digit decimal number between 0 and 255. 1513 Note that many implementations of the existing inet_addr() and 1514 inet_aton() functions accept nonstandard input: octal numbers, 1515 hexadecimal numbers, and fewer than four numbers. inet_pton() does not 1516 accept these formats. 1518 If the af argument is AF_INET6, then the function accepts a string in 1519 one of the standard IPv6 text forms defined in Section 2.2 of the 1520 addressing architecture specification [2]. 1522 The inet_ntop() function converts a numeric address into a text string 1523 suitable for presentation. The af argument specifies the family of the 1524 address. This can be AF_INET or AF_INET6. The src argument points to a 1525 buffer holding an IPv4 address if the af argument is AF_INET, or an IPv6 1526 address if the af argument is AF_INET6, the address must be in network 1527 byte order. The dst argument points to a buffer where the function will 1528 store the resulting text string. The size argument specifies the size 1529 of this buffer. The application must specify a non-NULL dst argument. 1530 For IPv6 addresses, the buffer must be at least 46-octets. For IPv4 1531 addresses, the buffer must be at least 16-octets. In order to allow 1532 applications to easily declare buffers of the proper size to store IPv4 1533 and IPv6 addresses in string form, the following two constants are 1534 defined in : 1536 #define INET_ADDRSTRLEN 16 1537 #define INET6_ADDRSTRLEN 46 1539 The inet_ntop() function returns a pointer to the buffer containing the 1540 text string if the conversion succeeds, and NULL otherwise. Upon 1541 failure, errno is set to EAFNOSUPPORT if the af argument is invalid or 1542 ENOSPC if the size of the result buffer is inadequate. 1544 6.7 Address Testing Macros 1546 The following macros can be used to test for special IPv6 addresses. 1548 #include 1550 int IN6_IS_ADDR_UNSPECIFIED (const struct in6_addr *); 1551 int IN6_IS_ADDR_LOOPBACK (const struct in6_addr *); 1552 int IN6_IS_ADDR_MULTICAST (const struct in6_addr *); 1553 int IN6_IS_ADDR_LINKLOCAL (const struct in6_addr *); 1554 int IN6_IS_ADDR_SITELOCAL (const struct in6_addr *); 1555 int IN6_IS_ADDR_V4MAPPED (const struct in6_addr *); 1556 int IN6_IS_ADDR_V4COMPAT (const struct in6_addr *); 1558 int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); 1559 int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); 1560 int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); 1561 int IN6_IS_ADDR_MC_ORGLOCAL (const struct in6_addr *); 1562 int IN6_IS_ADDR_MC_GLOBAL (const struct in6_addr *); 1564 The first seven macros return true if the address is of the specified 1565 type, or false otherwise. The last five test the scope of a multicast 1566 address and return true if the address is a multicast address of the 1567 specified scope or false if the address is either not a multicast 1568 address or not of the specified scope. Note that IN6_IS_ADDR_LINKLOCAL 1569 and IN6_IS_ADDR_SITELOCAL return true only for the two local-use IPv6 1570 unicast addresses. These two macros do not return true for IPv6 1571 multicast addresses of either link-local scope or site-local scope. 1573 7. Summary of New Definitions 1575 The following list summarizes the constants, structure, and extern 1576 definitions discussed in this memo, sorted by header. 1578 IF_NAMESIZE 1579 struct if_nameindex{}; 1581 AI_ADDRCONFIG 1582 AI_DEFAULT 1583 AI_ALL 1584 AI_CANONNAME 1585 AI_NUMERICHOST 1586 AI_PASSIVE 1587 AI_V4MAPPED 1588 EAI_ADDRFAMILY 1589 EAI_AGAIN 1590 EAI_BADFLAGS 1591 EAI_FAIL 1592 EAI_FAMILY 1593 EAI_MEMORY 1594 EAI_NODATA 1595 EAI_NONAME 1596 EAI_SERVICE 1597 EAI_SOCKTYPE 1598 EAI_SYSTEM 1599 NI_DGRAM 1600 NI_MAXHOST 1601 NI_MAXSERV 1602 NI_NAMEREQD 1603 NI_NOFQDN 1604 NI_NUMERICHOST 1605 NI_NUMERICSERV 1606 struct addrinfo{}; 1608 IN6ADDR_ANY_INIT 1609 IN6ADDR_LOOPBACK_INIT 1610 INET6_ADDRSTRLEN 1611 INET_ADDRSTRLEN 1612 IPPROTO_IPV6 1613 IPV6_JOIN_GROUP 1614 IPV6_LEAVE_GROUP 1615 IPV6_MULTICAST_HOPS 1616 IPV6_MULTICAST_IF 1617 IPV6_MULTICAST_LOOP 1618 IPV6_UNICAST_HOPS 1619 SIN6_LEN 1620 extern const struct in6_addr in6addr_any; 1621 extern const struct in6_addr in6addr_loopback; 1622 struct in6_addr{}; 1623 struct ipv6_mreq{}; 1624 struct sockaddr_in6{}; 1626 AF_INET6 1627 PF_INET6 1628 struct sockaddr_storage; 1630 The following list summarizes the function and macro prototypes 1631 discussed in this memo, sorted by header. 1633 int inet_pton(int, const char *, void *); 1634 const char *inet_ntop(int, const void *, 1635 char *, size_t); 1637 char *if_indextoname(unsigned int, char *); 1638 unsigned int if_nametoindex(const char *); 1639 void if_freenameindex(struct if_nameindex *); 1640 struct if_nameindex *if_nameindex(void); 1642 int getaddrinfo(const char *, const char *, 1643 const struct addrinfo *, 1644 struct addrinfo **); 1645 int getnameinfo(const struct sockaddr *, socklen_t, 1646 char *, size_t, char *, size_t, int); 1647 void freeaddrinfo(struct addrinfo *); 1648 char *gai_strerror(int); 1649 struct hostent *getipnodebyname(const char *, int, int, 1650 int *); 1652 struct hostent *getipnodebyaddr(const void *, size_t, int, 1653 int *); 1654 void freehostent(struct hostent *); 1656 int IN6_IS_ADDR_LINKLOCAL(const struct in6_addr *); 1657 int IN6_IS_ADDR_LOOPBACK(const struct in6_addr *); 1658 int IN6_IS_ADDR_MC_GLOBAL(const struct in6_addr *); 1659 int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); 1660 int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); 1661 int IN6_IS_ADDR_MC_ORGLOCAL(const struct in6_addr *); 1662 int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); 1663 int IN6_IS_ADDR_MULTICAST(const struct in6_addr *); 1664 int IN6_IS_ADDR_SITELOCAL(const struct in6_addr *); 1665 int IN6_IS_ADDR_UNSPECIFIED(const struct in6_addr *); 1666 int IN6_IS_ADDR_V4COMPAT(const struct in6_addr *); 1667 int IN6_IS_ADDR_V4MAPPED(const struct in6_addr *); 1669 8. Security Considerations 1671 IPv6 provides a number of new security mechanisms, many of which need to 1672 be accessible to applications. Companion memos detailing the extensions 1673 to the socket interfaces to support IPv6 security are being written. 1675 9. Year 2000 Considerations 1677 There are no issues for this draft concerning the Year 2000 issue 1678 regarding the use of dates. 1680 Changes made rfc2553 to rfc2553bis-00: 1682 1. Updated Portability Section 3.10 to conform to XNS 5.2. 1684 2. Updated getaddrinfo(), getnameinfo(), to conform to XNS 5.2. 1686 3. Added references to Scope Architecture, Scope Routing, and 1687 Extension Format for Scoped Addresses work in progress. 1689 4. Added NI_NUMERICSCOPE flag to getnameinfo(). 1691 5. Added qualification to getipnodebyname/addr() functions that 1692 they will not work as is with scope identifiers with IPv6, and 1693 getaddrinfo/getnameinfo should be used. 1695 6. Added DNS A6 record notation to AAAA and added ip6.arpa as new 1696 PTR record domain. 1698 Acknowledgments 1700 Thanks to the many people who made suggestions and provided feedback to 1701 this document, including: Werner Almesberger, Ran Atkinson, Fred Baker, 1702 Dave Borman, Andrew Cherenson, Alex Conta, Alan Cox, Steve Deering, 1703 Richard Draves, Francis Dupont, Robert Elz, Brian Haberman, Jun-ichiro 1704 itojun Hagino, Marc Hasson, Tom Herbert, Bob Hinden, Wan-Yen Hsu, 1705 Christian Huitema, Koji Imada, Markus Jork, Ron Lee, Alan Lloyd, Charles 1706 Lynn, Dan McDonald, Dave Mitton, Thomas Narten, Josh Osborne, Craig 1707 Partridge, Jean-Luc Richier, Erik Scoredos, Keith Sklower, JINMEI 1708 Tatuya, Matt Thomas, Harvey Thompson, Dean D. Throop, Karen Tracey, 1709 Glenn Trewitt, Paul Vixie, David Waitzman, Carl Williams, Kazu Yamamoto, 1710 Vlad Yasevich, and Brian Zill 1712 The getaddrinfo() and getnameinfo() functions are taken from an earlier 1713 Internet Draft by Keith Sklower. As noted in that draft, William Durst, 1714 Steven Wise, Michael Karels, and Eric Allman provided many useful 1715 discussions on the subject of protocol-independent name-to-address 1716 translation, and reviewed early versions of Keith Sklower's original 1717 proposal. Eric Allman implemented the first prototype of getaddrinfo(). 1718 The observation that specifying the pair of name and service would 1719 suffice for connecting to a service independent of protocol details was 1720 made by Marshall Rose in a proposal to X/Open for a "Uniform Network 1721 Interface". 1723 Craig Metz, Jack McCann, Erik Nordmark, Tim Hartrick, and Mukesh Kacker 1724 made many contributions to this document. Ramesh Govindan made a number 1725 of contributions and co-authored an earlier version of this memo. 1727 References 1729 [1] S. Deering, R. Hinden, "Internet Protocol, Version 6 (IPv6) 1730 Specification", RFC 2460 Draft Standard. 1732 [2] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture", 1733 RFC 2373, July 1998 Draft Standard. 1735 [3] IEEE, "Protocol Independent Interfaces", 1736 IEEE Std 1003.1g, DRAFT 6.6, 1737 March 1997. 1739 [4] W. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 1740 RFC 2292, February 1998. 1742 [5] T. Jinmei, A. Onoe, "An Extension of Format for IPv6 Scoped 1743 Addresses", Work-in-Progress. 1745 [6] S. Deering, B. Haberman, B. Zill "IP Version 6 Scoped Address 1746 Architecture", Work-in-Progress. 1748 [7] B. Haberman " Routing of Scoped Addresses in the Internet Protocol 1749 Version 6 (IPv6)", Work-in-Progress. 1751 Authors' Addresses 1753 Robert E. Gilligan 1754 FreeGate Corporation 1755 1208 E. Arques Ave. 1756 Sunnyvale, CA 94086 1757 Phone: +1 408 617 1004 1758 Email: gilligan@freegate.net 1760 Susan Thomson 1761 Bell Communications Research 1762 MRE 2P-343, 445 South Street 1763 Morristown, NJ 07960 1764 Telephone: +1 201 829 4514 1765 Email: set@thumper.bellcore.com 1767 Jim Bound 1768 Compaq Computer Corporation 1769 110 Spitbrook Road ZK3-3/U14 1770 Nashua, NH 03062-2698 1771 Phone: +1 603 884 0400 1772 Email: bound@zk3.dec.com 1774 W. Richard Stevens 1775 1202 E. Paseo del Zorro 1776 Tucson, AZ 85718-2826 1777 Phone: +1 520 297 9416 1778 Email: rstevens@kohala.com