idnits 2.17.1 draft-ietf-ipngwg-bsd-api-new-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-29) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. 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 Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == Mismatching filename: the document gives the document name as 'draft-ietf-ipngwg-bsd-api-new-02', but the file name used is 'draft-ietf-ipngwg-bsd-api-new-03' == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 33 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 33 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 32 instances of too long lines in the document, the longest one being 7 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 314: '...field SHOULD be set to zero by an impl...' RFC 2119 keyword, line 1124: '...s "::" and "::1" MUST NOT be treated a...' RFC 2119 keyword, line 1125: '... "::", HOST_NOT_FOUND MUST be returned...' RFC 2119 keyword, line 1128: '...IN6_IS_ADDR_V4COMPAT MUST return false...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 713 has weird spacing: '...ned int if_na...' == Line 744 has weird spacing: '...ned int if_i...' == Line 768 has weird spacing: '... void if_fr...' == Line 797 has weird spacing: '... int hoplim...' == Line 818 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 (October 19, 1998) is 9293 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 270, but not defined == Missing Reference: '0' is mentioned on line 1061, but not defined == Missing Reference: '7' is mentioned on line 1687, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. '1' ** 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) Summary: 12 errors (**), 0 flaws (~~), 14 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force R.E. Gilligan (FreeGate) 3 INTERNET-DRAFT S. Thomson (Bellcore) 4 Obsoletes draft-ietf-ipngwg-bsd-api-new-02.txt Jim Bound (Compaq) 5 W. R. Stevens (Consultant) 6 October 19, 1998 8 Basic Socket Interface Extensions for IPv6 10 12 Status of this Memo 14 This document is a submission by the Internet Protocol IPv6 15 Working Group of the Internet Engineering Task Force (IETF). 16 Comments should be submitted to the ipng@sunroof.eng.sun.com 17 mailing list. 19 This document is an Internet-Draft. Internet-Drafts are working 20 documents of the Internet Engineering Task Force (IETF), its 21 areas, and its working groups. Note that other groups may also 22 distribute working documents as Internet-Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six 25 months and may be updated, replaced, or obsoleted by other 26 documents at any time. It is inappropriate to use Internet- 27 Drafts as reference material or to cite them other than as 28 "work in progress." 30 To view the entire list of current Internet-Drafts, please check 31 the "1id-abstracts.txt" listing contained in the Internet-Drafts 32 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 33 (Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East 34 Coast), or ftp.isi.edu (US West Coast). 36 Distribution of this memo is unlimited. 38 Abstract 40 The de facto standard application program interface (API) for TCP/IP 41 applications is the "sockets" interface. Although this API was 42 developed for Unix in the early 1980s it has also been implemented on a 43 wide variety of non-Unix systems. TCP/IP applications written using the 44 sockets API have in the past enjoyed a high degree of portability and we 45 would like the same portability with IPv6 applications. But changes are 46 required to the sockets API to support IPv6 and this memo describes 47 these changes. These include a new socket address structure to carry 48 IPv6 addresses, new address conversion functions, and some new socket 49 options. These extensions are designed to provide access to the basic 50 IPv6 features required by TCP and UDP applications, including 51 multicasting, while introducing a minimum of change into the system and 52 providing complete compatibility for existing IPv4 applications. 53 Additional extensions for advanced IPv6 features (raw sockets and access 54 to the IPv6 extension headers) are defined in another document [4]. 56 Table of Contents: 58 1. Introduction.................................................3 59 2. Design Considerations........................................3 60 2.1 What Needs to be Changed....................................3 61 2.2 Data Types..................................................4 62 2.3 Headers.....................................................5 63 2.4 Structures..................................................5 64 3. Socket Interface.............................................5 65 3.1 IPv6 Address Family and Protocol Family.....................5 66 3.2 IPv6 Address Structure......................................5 67 3.3 Socket Address Structure for 4.3BSD-Based Systems...........6 68 3.4 Socket Address Structure for 4.4BSD-Based Systems...........7 69 3.5 The Socket Functions........................................8 70 3.6 Compatibility with IPv4 Applications........................9 71 3.7 Compatibility with IPv4 Nodes...............................9 72 3.8 IPv6 Wildcard Address.......................................9 73 3.9 IPv6 Loopback Address......................................10 74 3.10 Portability Additions.....................................11 75 4. Interface Identification....................................13 76 4.1 Name-to-Index..............................................14 77 4.2 Index-to-Name..............................................14 78 4.3 Return All Interface Names and Indexes.....................14 79 4.4 Free Memory................................................15 80 5. Socket Options..............................................15 81 5.1 Unicast Hop Limit..........................................15 82 5.2 Sending and Receiving Multicast Packets....................16 83 6. Library Functions...........................................17 84 6.1 Nodename-to-Address Translation............................18 85 6.2 Address-To-Nodename Translation............................20 86 6.3 Freeing memory for getipnodebyname and getipnodebyaddr.....21 87 6.4 Protocol-Independent Nodename and Service Name Translation.22 88 6.5 Socket Address Structure to Nodename and Service Name......24 89 6.6 Address Conversion Functions...............................26 90 6.7 Address Testing Macros.....................................27 91 7. Summary of New Definitions..................................27 92 8. Security Considerations.....................................29 93 9. Year 2000 Considerations....................................29 94 Changes From RFC 2133..........................................29 95 Acknowledgments................................................32 96 References.....................................................32 97 Authors' Addresses.............................................33 98 1. Introduction 100 While IPv4 addresses are 32 bits long, IPv6 interfaces are identified by 101 128-bit addresses. The socket interface makes the size of an IP address 102 quite visible to an application; virtually all TCP/IP applications for 103 BSD-based systems have knowledge of the size of an IP address. Those 104 parts of the API that expose the addresses must be changed to 105 accommodate the larger IPv6 address size. IPv6 also introduces new 106 features (e.g., traffic class and flowlabel). some of which must be made 107 visible to applications via the API. This memo defines a set of 108 extensions to the socket interface to support the larger address size 109 and new features of IPv6. 111 2. Design Considerations 113 There are a number of important considerations in designing changes to 114 this well-worn API: 116 - The API changes should provide both source and binary 117 compatibility for programs written to the original API. That 118 is, existing program binaries should continue to operate when 119 run on a system supporting the new API. In addition, existing 120 applications that are re-compiled and run on a system supporting 121 the new API should continue to operate. Simply put, the API 122 changes for IPv6 should not break existing programs. 124 - The changes to the API should be as small as possible in order 125 to simplify the task of converting existing IPv4 applications to 126 IPv6. 128 - Where possible, applications should be able to use this 129 API to interoperate with both IPv6 and IPv4 hosts. Applications 130 should not need to know which type of host they are 131 communicating with. 133 - IPv6 addresses carried in data structures should be 64-bit 134 aligned. This is necessary in order to obtain optimum 135 performance on 64-bit machine architectures. 137 Because of the importance of providing IPv4 compatibility in the API, 138 these extensions are explicitly designed to operate on machines that 139 provide complete support for both IPv4 and IPv6. A subset of this API 140 could probably be designed for operation on systems that support only 141 IPv6. However, this is not addressed in this memo. 143 2.1 What Needs to be Changed 145 The socket interface API consists of a few distinct components: 147 - Core socket functions. 149 - Address data structures. 151 - Name-to-address translation functions. 153 - Address conversion functions. 155 The core socket functions -- those functions that deal with such things 156 as setting up and tearing down TCP connections, and sending and 157 receiving UDP packets -- were designed to be transport independent. 158 Where protocol addresses are passed as function arguments, they are 159 carried via opaque pointers. A protocol-specific address data structure 160 is defined for each protocol that the socket functions support. 161 Applications must cast pointers to these protocol-specific address 162 structures into pointers to the generic "sockaddr" address structure 163 when using the socket functions. These functions need not change for 164 IPv6, but a new IPv6-specific address data structure is needed. 166 The "sockaddr_in" structure is the protocol-specific data structure for 167 IPv4. This data structure actually includes 8-octets of unused space, 168 and it is tempting to try to use this space to adapt the sockaddr_in 169 structure to IPv6. Unfortunately, the sockaddr_in structure is not 170 large enough to hold the 16-octet IPv6 address as well as the other 171 information (address family and port number) that is needed. So a new 172 address data structure must be defined for IPv6. 174 IPv6 addresses are scoped [2] so they could be link-local, site, 175 organization, global, or other scopes at this time undefined. To 176 support applications that want to be able to identify a set of 177 interfaces for a specific scope, the IPv6 sockaddr_in structure must 178 support a field that can be used by an implementation to identify a set 179 of interfaces identifying the scope for an IPv6 address. 181 The name-to-address translation functions in the socket interface are 182 gethostbyname() and gethostbyaddr(). These are left as is and new 183 functions are defined to support IPv4 and IPv6. Additionally, the POSIX 184 1003.g draft [3] specifies a new nodename-to-address translation 185 function which is protocol independent. This function can also be used 186 with IPv4 and IPv6. 188 The address conversion functions -- inet_ntoa() and inet_addr() -- 189 convert IPv4 addresses between binary and printable form. These 190 functions are quite specific to 32-bit IPv4 addresses. We have designed 191 two analogous functions that convert both IPv4 and IPv6 addresses, and 192 carry an address type parameter so that they can be extended to other 193 protocol families as well. 195 Finally, a few miscellaneous features are needed to support IPv6. New 196 interfaces are needed to support the IPv6 traffic class, flow label, and 197 hop limit header fields. New socket options are needed to control the 198 sending and receiving of IPv6 multicast packets. 200 The socket interface will be enhanced in the future to provide access to 201 other IPv6 features. These extensions are described in [4]. 203 2.2 Data Types 205 The data types of the structure elements given in this memo are intended 206 to be examples, not absolute requirements. Whenever possible, data 207 types from Draft 6.6 (March 1997) of POSIX 1003.1g are used: uintN_t 208 means an unsigned integer of exactly N bits (e.g., uint16_t). We also 209 assume the argument data types from 1003.1g when possible (e.g., the 210 final argument to setsockopt() is a size_t value). Whenever buffer 211 sizes are specified, the POSIX 1003.1 size_t data type is used (e.g., 212 the two length arguments to getnameinfo()). 214 2.3 Headers 216 When function prototypes and structures are shown we show the headers 217 that must be #included to cause that item to be defined. 219 2.4 Structures 221 When structures are described the members shown are the ones that must 222 appear in an implementation. Additional, nonstandard members may also 223 be defined by an implementation. 225 The ordering shown for the members of a structure is the recommended 226 ordering, given alignment considerations of multibyte members, but an 227 implementation may order the members differently. 229 3. Socket Interface 231 This section specifies the socket interface changes for IPv6. 233 3.1 IPv6 Address Family and Protocol Family 235 A new address family name, AF_INET6, is defined in . The 236 AF_INET6 definition distinguishes between the original sockaddr_in 237 address data structure, and the new sockaddr_in6 data structure. 239 A new protocol family name, PF_INET6, is defined in . 240 Like most of the other protocol family names, this will usually be 241 defined to have the same value as the corresponding address family name: 243 #define PF_INET6 AF_INET6 245 The PF_INET6 is used in the first argument to the socket() function to 246 indicate that an IPv6 socket is being created. 248 3.2 IPv6 Address Structure 250 A new in6_addr structure holds a single IPv6 address and is defined as a 251 result of including : 253 struct in6_addr { 254 uint8_t s6_addr[16]; /* IPv6 address */ 255 } 257 This data structure contains an array of sixteen 8-bit elements, which 258 make up one 128-bit IPv6 address. The IPv6 address is stored in network 259 byte order. 261 The structure in6_addr above is usually implemented with an embedded 262 union with extra fields that force the desired alignment level in a 263 manner similar to BSD implementations of "struct in_addr". Those 264 additional implementation details are omitted here for simplicity. 266 An example is as follows: 268 struct in6_addr { 269 union { 270 uint8_t _S6_u8[16]; 271 uint32_t _S6_u32[4]; 272 uint64_t _S6_u64[2]; 273 } _S6_un; 274 }; 275 #define s6_addr _S6_un._S6_u8 277 3.3 Socket Address Structure for 4.3BSD-Based Systems 279 In the socket interface, a different protocol-specific data structure is 280 defined to carry the addresses for each protocol suite. Each protocol- 281 specific data structure is designed so it can be cast into a protocol- 282 independent data structure -- the "sockaddr" structure. Each has a 283 "family" field that overlays the "sa_family" of the sockaddr data 284 structure. This field identifies the type of the data structure. 286 The sockaddr_in structure is the protocol-specific address data 287 structure for IPv4. It is used to pass addresses between applications 288 and the system in the socket functions. The following sockaddr_in6 289 structure holds IPv6 addresses and is defined as a result of including 290 the header: 292 struct sockaddr_in6 { 293 sa_family_t sin6_family; /* AF_INET6 */ 294 in_port_t sin6_port; /* transport layer port # */ 295 uint32_t sin6_flowinfo; /* IPv6 traffic class & flow info */ 296 struct in6_addr sin6_addr; /* IPv6 address */ 297 uint32_t sin6_scope_id; /* set of interfaces for a scope */ 298 }; 300 This structure is designed to be compatible with the sockaddr data 301 structure used in the 4.3BSD release. 303 The sin6_family field identifies this as a sockaddr_in6 structure. This 304 field overlays the sa_family field when the buffer is cast to a sockaddr 305 data structure. The value of this field must be AF_INET6. 307 The sin6_port field contains the 16-bit UDP or TCP port number. This 308 field is used in the same way as the sin_port field of the sockaddr_in 309 structure. The port number is stored in network byte order. 311 The sin6_flowinfo field is a 32-bit field that contains two pieces of 312 information: the traffic class and the flow label. The contents and 313 interpretation of this member is specified in [1]. The sin6_flowinfo 314 field SHOULD be set to zero by an implementation prior to using the 315 sockaddr_in6 structure by an application on receive operations. 317 The sin6_addr field is a single in6_addr structure (defined in the 318 previous section). This field holds one 128-bit IPv6 address. The 319 address is stored in network byte order. 321 The ordering of elements in this structure is specifically designed so 322 that when sin6_addr field is aligned on a 64-bit boundary, the start of 323 the structure will also be aligned on a 64-bit boundary. This is done 324 for optimum performance on 64-bit architectures. 326 The sin6_scope_id field is a 32bit integer that identifies a set of 327 interfaces as appropriate for the scope of the address carried in the 328 sin6_addr field. For a link scope sin6_addr sin6_scope_id would be an 329 interface index. For a site scope sin6_addr, sin6_scope_id would be a 330 site identifier. The mapping of sin6_scope_id to an interface or set of 331 interfaces is left to implementation and future specifications on the 332 subject of site identifiers. 334 Notice that the sockaddr_in6 structure will normally be larger than the 335 generic sockaddr structure. On many existing implementations the 336 sizeof(struct sockaddr_in) equals sizeof(struct sockaddr), with both 337 being 16 bytes. Any existing code that makes this assumption needs to 338 be examined carefully when converting to IPv6. 340 3.4 Socket Address Structure for 4.4BSD-Based Systems 342 The 4.4BSD release includes a small, but incompatible change to the 343 socket interface. The "sa_family" field of the sockaddr data structure 344 was changed from a 16-bit value to an 8-bit value, and the space saved 345 used to hold a length field, named "sa_len". The sockaddr_in6 data 346 structure given in the previous section cannot be correctly cast into 347 the newer sockaddr data structure. For this reason, the following 348 alternative IPv6 address data structure is provided to be used on 349 systems based on 4.4BSD. It is defined as a result of including the 350 header. 352 struct sockaddr_in6 { 353 uint8_t sin6_len; /* length of this struct */ 354 sa_family_t sin6_family; /* AF_INET6 */ 355 in_port_t sin6_port; /* transport layer port # */ 356 uint32_t sin6_flowinfo; /* IPv6 flow information */ 357 struct in6_addr sin6_addr; /* IPv6 address */ 358 uint32_t sin6_scope_id; /* set of interfaces for a scope */ 359 }; 361 The only differences between this data structure and the 4.3BSD variant 362 are the inclusion of the length field, and the change of the family 363 field to a 8-bit data type. The definitions of all the other fields are 364 identical to the structure defined in the previous section. 366 Systems that provide this version of the sockaddr_in6 data structure 367 must also declare SIN6_LEN as a result of including the 368 header. This macro allows applications to determine whether they are 369 being built on a system that supports the 4.3BSD or 4.4BSD variants of 370 the data structure. 372 3.5 The Socket Functions 374 Applications call the socket() function to create a socket descriptor 375 that represents a communication endpoint. The arguments to the socket() 376 function tell the system which protocol to use, and what format address 377 structure will be used in subsequent functions. For example, to create 378 an IPv4/TCP socket, applications make the call: 380 s = socket(PF_INET, SOCK_STREAM, 0); 382 To create an IPv4/UDP socket, applications make the call: 384 s = socket(PF_INET, SOCK_DGRAM, 0); 386 Applications may create IPv6/TCP and IPv6/UDP sockets by simply using 387 the constant PF_INET6 instead of PF_INET in the first argument. For 388 example, to create an IPv6/TCP socket, applications make the call: 390 s = socket(PF_INET6, SOCK_STREAM, 0); 392 To create an IPv6/UDP socket, applications make the call: 394 s = socket(PF_INET6, SOCK_DGRAM, 0); 396 Once the application has created a PF_INET6 socket, it must use the 397 sockaddr_in6 address structure when passing addresses in to the system. 398 The functions that the application uses to pass addresses into the 399 system are: 401 bind() 402 connect() 403 sendmsg() 404 sendto() 406 The system will use the sockaddr_in6 address structure to return 407 addresses to applications that are using PF_INET6 sockets. The 408 functions that return an address from the system to an application are: 410 accept() 411 recvfrom() 412 recvmsg() 413 getpeername() 414 getsockname() 416 No changes to the syntax of the socket functions are needed to support 417 IPv6, since all of the "address carrying" functions use an opaque 418 address pointer, and carry an address length as a function argument. 420 3.6 Compatibility with IPv4 Applications 422 In order to support the large base of applications using the original 423 API, system implementations must provide complete source and binary 424 compatibility with the original API. This means that systems must 425 continue to support PF_INET sockets and the sockaddr_in address 426 structure. Applications must be able to create IPv4/TCP and IPv4/UDP 427 sockets using the PF_INET constant in the socket() function, as 428 described in the previous section. Applications should be able to hold 429 a combination of IPv4/TCP, IPv4/UDP, IPv6/TCP and IPv6/UDP sockets 430 simultaneously within the same process. 432 Applications using the original API should continue to operate as they 433 did on systems supporting only IPv4. That is, they should continue to 434 interoperate with IPv4 nodes. 436 3.7 Compatibility with IPv4 Nodes 438 The API also provides a different type of compatibility: the ability for 439 IPv6 applications to interoperate with IPv4 applications. This feature 440 uses the IPv4-mapped IPv6 address format defined in the IPv6 addressing 441 architecture specification [2]. This address format allows the IPv4 442 address of an IPv4 node to be represented as an IPv6 address. The IPv4 443 address is encoded into the low-order 32 bits of the IPv6 address, and 444 the high-order 96 bits hold the fixed prefix 0:0:0:0:0:FFFF. IPv4- 445 mapped addresses are written as follows: 447 ::FFFF: 449 These addresses can be generated automatically by the getipnodebyname() 450 function when the specified host has only IPv4 addresses (as described 451 in Section 6.1). 453 Applications may use PF_INET6 sockets to open TCP connections to IPv4 454 nodes, or send UDP packets to IPv4 nodes, by simply encoding the 455 destination's IPv4 address as an IPv4-mapped IPv6 address, and passing 456 that address, within a sockaddr_in6 structure, in the connect() or 457 sendto() call. When applications use PF_INET6 sockets to accept TCP 458 connections from IPv4 nodes, or receive UDP packets from IPv4 nodes, the 459 system returns the peer's address to the application in the accept(), 460 recvfrom(), or getpeername() call using a sockaddr_in6 structure encoded 461 this way. 463 Few applications will likely need to know which type of node they are 464 interoperating with. However, for those applications that do need to 465 know, the IN6_IS_ADDR_V4MAPPED() macro, defined in Section 6.6, is 466 provided. 468 3.8 IPv6 Wildcard Address 470 While the bind() function allows applications to select the source IP 471 address of UDP packets and TCP connections, applications often want the 472 system to select the source address for them. With IPv4, one specifies 473 the address as the symbolic constant INADDR_ANY (called the "wildcard" 474 address) in the bind() call, or simply omits the bind() entirely. 476 Since the IPv6 address type is a structure (struct in6_addr), a symbolic 477 constant can be used to initialize an IPv6 address variable, but cannot 478 be used in an assignment. Therefore systems provide the IPv6 wildcard 479 address in two forms. 481 The first version is a global variable named "in6addr_any" that is an 482 in6_addr structure. The extern declaration for this variable is defined 483 in : 485 extern const struct in6_addr in6addr_any; 487 Applications use in6addr_any similarly to the way they use INADDR_ANY in 488 IPv4. For example, to bind a socket to port number 23, but let the 489 system select the source address, an application could use the following 490 code: 492 struct sockaddr_in6 sin6; 493 . . . sin6.sin6_family = AF_INET6; sin6.sin6_flowinfo = 0; 494 sin6.sin6_port = htons(23); sin6.sin6_addr = in6addr_any; /* 495 structure assignment */ 496 . . . if (bind(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 497 . . . 499 The other version is a symbolic constant named IN6ADDR_ANY_INIT and is 500 defined in . This constant can be used to initialize an 501 in6_addr structure: 503 struct in6_addr anyaddr = IN6ADDR_ANY_INIT; 505 Note that this constant can be used ONLY at declaration time. It can 506 not be used to assign a previously declared in6_addr structure. For 507 example, the following code will not work: 509 /* This is the WRONG way to assign an unspecified address */ 510 struct sockaddr_in6 sin6; 511 . . . 512 sin6.sin6_addr = IN6ADDR_ANY_INIT; /* will NOT compile */ 514 Be aware that the IPv4 INADDR_xxx constants are all defined in host byte 515 order but the IPv6 IN6ADDR_xxx constants and the IPv6 in6addr_xxx 516 externals are defined in network byte order. 518 3.9 IPv6 Loopback Address 520 Applications may need to send UDP packets to, or originate TCP 521 connections to, services residing on the local node. In IPv4, they can 522 do this by using the constant IPv4 address INADDR_LOOPBACK in their 523 connect(), sendto(), or sendmsg() call. 525 IPv6 also provides a loopback address to contact local TCP and UDP 526 services. Like the unspecified address, the IPv6 loopback address is 527 provided in two forms -- a global variable and a symbolic constant. 529 The global variable is an in6_addr structure named "in6addr_loopback." 530 The extern declaration for this variable is defined in : 532 extern const struct in6_addr in6addr_loopback; 534 Applications use in6addr_loopback as they would use INADDR_LOOPBACK in 535 IPv4 applications (but beware of the byte ordering difference mentioned 536 at the end of the previous section). For example, to open a TCP 537 connection to the local telnet server, an application could use the 538 following code: 540 struct sockaddr_in6 sin6; 541 . . . 542 sin6.sin6_family = AF_INET6; 543 sin6.sin6_flowinfo = 0; 544 sin6.sin6_port = htons(23); 545 sin6.sin6_addr = in6addr_loopback; /* structure assignment */ 546 . . . 547 if (connect(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 548 . . . 550 The symbolic constant is named IN6ADDR_LOOPBACK_INIT and is defined in 551 . It can be used at declaration time ONLY; for example: 553 struct in6_addr loopbackaddr = IN6ADDR_LOOPBACK_INIT; 555 Like IN6ADDR_ANY_INIT, this constant cannot be used in an assignment to 556 a previously declared IPv6 address variable. 558 3.10 Portability Additions 560 One simple addition to the sockets API can help application writers is 561 the "struct sockaddr_storage". This data structure can simplify writing 562 code portable across multiple address families and platforms. This data 563 structure is designed with the following goals. 565 - It has a large enough implementation specific maximum size to store 566 the desired set of protocol specific socket address data structures 567 Specifically, it is at least large enough to accommodate sockaddr_in 568 and sockaddr_in6 and possibly other protocol specific socket 569 addresses too. 570 - It is aligned at an appropriate boundary so protocol specific socket 571 address data structure pointers can be cast to it and access their 572 fields without alignment problems. (e.g. pointers to sockaddr_in6 573 and/or sockaddr_in can be cast to it and access fields without alignment 574 problems). 575 - It has the initial field(s) isomorphic to the fields of the 576 "struct sockaddr" data structure on that implementation which 577 can be used as a discriminants for deriving the protocol in use. 578 These initial field(s) would on most implementations either be a 579 single field of type "sa_family_t" (isomorphic to sa_family field, 580 16 bits) or two fields of type uint8_t and sa_family_t respectively, 581 (isomorphic to sa_len and sa_family_t, 8 bits each). 583 An example implementation design of such a data structure would be as 584 follows. 586 /* 587 * Desired design of maximum size and alignment 588 */ 589 #define _SS_MAXSIZE 128 /* Implementation specific max size */ 590 #define _SS_ALIGNSIZE (sizeof (int64_t)) 591 /* Implementation specific desired alignment */ 592 /* 593 * Definitions used for sockaddr_storage structure paddings design. 594 */ 595 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof (sa_family_t)) 596 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 597 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 598 struct sockaddr_storage { 599 sa_family_t ss_family; /* address family */ 600 /* Following fields are implementation specific */ 601 char _ss_pad1[_SS_PAD1SIZE]; 602 /* 6 byte pad, this is to make implementation 603 /* specific pad up to alignment field that */ 604 /* follows explicit in the data structure */ 605 int64_t _ss_align; /* field to force desired structure */ 606 /* storage alignment */ 607 char _ss_pad2[_SS_PAD2SIZE]; 608 /* 112 byte pad to achieve desired size, */ 609 /* _SS_MAXSIZE value minus size of ss_family */ 610 /* _ss_pad1, _ss_align fields is 112 */ 611 }; 613 On implementations where sockaddr data structure includes a "sa_len", 614 field this data structure would look like 616 /* 617 * Definitions used for sockaddr_storage structure paddings design. 618 */ 619 #define _SS_PAD1SIZE (_SS_ALIGNSIZE - 620 (sizeof (uint8_t) + sizeof (sa_family_t)) 621 #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof (sa_family_t)+ 622 _SS_PAD1SIZE + _SS_ALIGNSIZE)) 623 struct sockaddr_storage { 624 uint8_t ss_len /* address length */ 625 sa_family_t ss_family; /* address family */ 626 /* Following fields are implementation specific */ 627 char _ss_pad1[_SS_PAD1SIZE]; 628 /* 6 byte pad, this is to make implementation 629 /* specific pad up to alignment field that */ 630 /* follows explicit in the data structure */ 631 int64_t _ss_align; /* field to force desired structure */ 632 /* storage alignment */ 633 char _ss_pad2[_SS_PAD2SIZE]; 634 /* 112 byte pad to achieve desired size, */ 635 /* _SS_MAXSIZE value minus size of ss_len, */ 636 /* ss_family,_ss_pad1, _ss_align fields is 112 */ 637 }; 639 The above example implementation illustrates a data structure which will 640 align on a 64 bit boundary. An implementation specific field "_ss_align" 641 along "_ss_pad1" is used to force a 64-bit alignment which covers proper 642 alignment good enough for needs of sockaddr_in6 (IPv6), sockaddr_in 643 (IPv4) address data structures. The size of padding fields _ss_pad1 644 depends on the chosen alignment boundary. The size of padding field 645 _ss_pad2 depends on the value of overall size chosen for the total size 646 of the structure. This size and alignment are represented in the above 647 example by implementation specific (not required) constants _SS_MAXSIZE 648 (chosen value 128) and _SS_ALIGNMENT (with chosen value 8). Constants 649 _SS_PAD1SIZE (derived value 6) and _SS_PAD2SIZE (derived value 112) are 650 also for illustration and not required. The implementation specific 651 definitions and structure field names above start with an underscore to 652 denote implementation private namespace. Portable code is not expected 653 to access or reference those fields or constants. 655 The sockaddr_storage structure solves the problem of declaring storage 656 for automatic variables which is large enough and aligned enough for 657 storing socket address data structure of any family. For example, code 658 with a file descriptor and without the context of the address family can 659 pass a pointer to a variable of this type where a pointer to a socket 660 address structure is expected in calls such as getpeername() and 661 determine the address family by accessing the received content after the 662 call. 664 The sockaddr_storage structure may also be useful and applied to certain 665 other interfaces where a generic socket address large enough and aligned 666 for use with multiple address families may be needed. A discussion of 667 those interfaces is outside the scope of this document. 669 Also, much existing code assumes that any socket address structure can 670 fit in a generic sockaddr structure. While this has been true for IPv4 671 socket address structures, it has always been false for Unix domain 672 socket address structures (but in practice this has not been a problem) 673 and it is also false for IPv6 socket address structures (which can be a 674 problem). 676 So now an application can do the following: 678 struct sockaddr_storage ss; 679 struct sockaddr_in6 *sin6; 680 sin6 = (struct sockaddr_in6 *) &ss; 682 4. Interface Identification 684 This API uses an interface index (a small positive integer) to identify 685 the local interface on which a multicast group is joined (Section 5.3). 686 Additionally, the advanced API [4] uses these same interface indexes to 687 identify the interface on which a datagram is received, or to specify 688 the interface on which a datagram is to be sent. 690 Interfaces are normally known by names such as "le0", "sl1", "ppp2", and 691 the like. On Berkeley-derived implementations, when an interface is 692 made known to the system, the kernel assigns a unique positive integer 693 value (called the interface index) to that interface. These are small 694 positive integers that start at 1. (Note that 0 is never used for an 695 interface index.) There may be gaps so that there is no current 696 interface for a particular positive interface index. 698 This API defines two functions that map between an interface name and 699 index, a third function that returns all the interface names and 700 indexes, and a fourth function to return the dynamic memory allocated by 701 the previous function. How these functions are implemented is left up 702 to the implementation. 4.4BSD implementations can implement these 703 functions using the existing sysctl() function with the NET_RT_IFLIST 704 command. Other implementations may wish to use ioctl() for this 705 purpose. 707 4.1 Name-to-Index 709 The first function maps an interface name into its corresponding index. 711 #include 713 unsigned int if_nametoindex(const char *ifname); 715 If the specified interface name does not exist, the return value is 0, 716 and errno is set to ENXIO. If there was a system error (such as 717 running out of memory), the return value is 0 and errno is set to the 718 proper value (e.g., ENOMEM). 720 4.2 Index-to-Name 722 The second function maps an interface index into its corresponding name. 724 #include 726 char *if_indextoname(unsigned int ifindex, char *ifname); 728 The ifname argument must point to a buffer of at least IFNAMSIZ bytes 729 into which the interface name corresponding to the specified index is 730 returned. (IFNAMSIZ is also defined in and its value 731 includes a terminating null byte at the end of the interface name.) This 732 pointer is also the return value of the function. If there is no 733 interface corresponding to the specified index, NULL is returned, and 734 errno is set to ENXIO, if there was a system error (such as running out 735 of memory), if_indextoname returns NULL and errno would be set to the 736 proper value (e.g., ENOMEM). 738 4.3 Return All Interface Names and Indexes 740 The if_nameindex structure holds the information about a single 741 interface and is defined as a result of including the header. 743 struct if_nameindex { 744 unsigned int if_index; /* 1, 2, ... */ 745 char *if_name; /* null terminated name: "le0", ... */ 746 }; 748 The final function returns an array of if_nameindex structures, one 749 structure per interface. 751 struct if_nameindex *if_nameindex(void); 753 The end of the array of structures is indicated by a structure with an 754 if_index of 0 and an if_name of NULL. The function returns a NULL 755 pointer upon an error, and would set errno to the appropriate value. 757 The memory used for this array of structures along with the interface 758 names pointed to by the if_name members is obtained dynamically. This 759 memory is freed by the next function. 761 4.4 Free Memory 763 The following function frees the dynamic memory that was allocated by 764 if_nameindex(). 766 #include 768 void if_freenameindex(struct if_nameindex *ptr); 770 The argument to this function must be a pointer that was returned by 771 if_nameindex(). 773 Currently net/if.h doesn't have prototype definitions for functions and 774 it is recommended that these definitions be defined in net/if.h as well 775 and the struct if_nameindex{}. 777 5. Socket Options 779 A number of new socket options are defined for IPv6. All of these new 780 options are at the IPPROTO_IPV6 level. That is, the "level" parameter 781 in the getsockopt() and setsockopt() calls is IPPROTO_IPV6 when using 782 these options. The constant name prefix IPV6_ is used in all of the new 783 socket options. This serves to clearly identify these options as 784 applying to IPv6. 786 The declaration for IPPROTO_IPV6, the new IPv6 socket options, and 787 related constants defined in this section are obtained by including the 788 header . 790 5.1 Unicast Hop Limit 792 A new setsockopt() option controls the hop limit used in outgoing 793 unicast IPv6 packets. The name of this option is IPV6_UNICAST_HOPS, and 794 it is used at the IPPROTO_IPV6 layer. The following example illustrates 795 how it is used: 797 int hoplimit = 10; 799 if (setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 800 (char *) &hoplimit, sizeof(hoplimit)) == -1) 801 perror("setsockopt IPV6_UNICAST_HOPS"); 803 When the IPV6_UNICAST_HOPS option is set with setsockopt(), the option 804 value given is used as the hop limit for all subsequent unicast packets 805 sent via that socket. If the option is not set, the system selects a 806 default value. The integer hop limit value (called x) is interpreted as 807 follows: 809 x < -1: return an error of EINVAL 810 x == -1: use kernel default 811 0 <= x <= 255: use x 812 x >= 256: return an error of EINVAL 814 The IPV6_UNICAST_HOPS option may be used with getsockopt() to determine 815 the hop limit value that the system will use for subsequent unicast 816 packets sent via that socket. For example: 818 int hoplimit; 819 size_t len = sizeof(hoplimit); 821 if (getsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 822 (char *) &hoplimit, &len) == -1) 823 perror("getsockopt IPV6_UNICAST_HOPS"); 824 else 825 printf("Using %d for hop limit.\n", hoplimit); 827 5.2 Sending and Receiving Multicast Packets 829 IPv6 applications may send UDP multicast packets by simply specifying an 830 IPv6 multicast address in the address argument of the sendto() function. 832 Three socket options at the IPPROTO_IPV6 layer control some of the 833 parameters for sending multicast packets. Setting these options is not 834 required: applications may send multicast packets without using these 835 options. The setsockopt() options for controlling the sending of 836 multicast packets are summarized below. These three options can also be 837 used with getsockopt(). 839 IPV6_MULTICAST_IF 841 Set the interface to use for outgoing multicast packets. 842 The argument is the index of the interface to use. 844 Argument type: unsigned int 846 IPV6_MULTICAST_HOPS 848 Set the hop limit to use for outgoing multicast packets. 849 (Note a separate option - IPV6_UNICAST_HOPS - is 850 provided to set the hop limit to use for outgoing 851 unicast packets.) 852 The interpretation of the argument is the same 853 as for the IPV6_UNICAST_HOPS option: 855 x < -1: return an error of EINVAL 856 x == -1: use kernel default 857 0 <= x <= 255: use x 858 x >= 256: return an error of EINVAL 860 If IPV6_MULTICAST_HOPS is not set, the default is 1 (same as IPv4 today) 862 Argument type: int 864 IPV6_MULTICAST_LOOP 866 If a multicast datagram is sent to a group to which the sending host 867 itself belongs (on the outgoing interface), a copy of the datagram is 868 looped back by the IP layer for local delivery if this option is set to 869 1. If this option is set to 0 a copy is not looped back. Other option 870 values return an error of EINVAL. 872 If IPV6_MULTICAST_LOOP is not set, the default is 1 (loopback; same as 873 IPv4 today). 875 Argument type: unsigned int 877 The reception of multicast packets is controlled by the two setsockopt() 878 options summarized below. An error of EOPNOTSUPP is returned if these 879 two options are used with getsockopt(). 881 IPV6_JOIN_GROUP 883 Join a multicast group on a specified local interface. 884 If the interface index is specified as 0, 885 the kernel chooses the local interface. 886 For example, some kernels look up the multicast group 887 in the normal IPv6 routing table and using the resulting interface. 889 Argument type: struct ipv6_mreq 891 IPV6_LEAVE_GROUP 893 Leave a multicast group on a specified interface. 895 Argument type: struct ipv6_mreq 897 The argument type of both of these options is the ipv6_mreq structure, 898 defined as as a result of including the header; 900 struct ipv6_mreq { 901 struct in6_addr ipv6mr_multiaddr; /* IPv6 multicast addr */ 902 unsigned int ipv6mr_interface; /* interface index */ 903 }; 905 Note that to receive multicast datagrams a process must join the 906 multicast group and bind the UDP port to which datagrams will be sent. 907 Some processes also bind the multicast group address to the socket, in 908 addition to the port, to prevent other datagrams destined to that same 909 port from being delivered to the socket. 911 6. Library Functions 913 New library functions are needed to perform a variety of operations with 914 IPv6 addresses. Functions are needed to lookup IPv6 addresses in the 915 Domain Name System (DNS). Both forward lookup (nodename-to-address 916 translation) and reverse lookup (address-to-nodename translation) need 917 to be supported. Functions are also needed to convert IPv6 addresses 918 between their binary and textual form. 920 We note that the two existing functions, gethostbyname() and 921 gethostbyaddr(), are left as-is. New functions are defined to handle 922 both IPv4 and IPv6 addresses. 924 6.1 Nodename-to-Address Translation 926 The commonly used function gethostbyname() is inadequate for many 927 applications, first because it provides no way for the caller to specify 928 anything about the types of addresses desired (IPv4 only, IPv6 only, 929 IPv4-mapped IPv6 are OK, etc.), and second many implementations of this 930 function are not thread safe. RFC 2133 defined a function named 931 gethostbyname2() but this function was also inadequate, first because 932 its use required setting a global option (RES_USE_INET6) when IPv6 933 addresses were required, and second because a flag argument is needed to 934 provide the caller with additional control over the types of addresses 935 required. 937 The following function is new and must be thread safe: 939 #include 940 #include 942 struct hostent *getipnodebyname(const char *name, int af, int flags 943 int *error_num); 945 The name argument can be either a node name or a numeric address string 946 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address). The af 947 argument specifies the address family, either AF_INET or AF_INET6. The 948 error_num value is returned to the caller, via a pointer, with the 949 appropriate error code in error_num, to support thread safe error code 950 returns. error_num will be set to one of the following values: 952 HOST_NOT_FOUND 954 No such host is known. 956 NO_ADDRESS 958 The server recognised the request and the name but no address 959 is available. Another type of request to the name server for 960 the domain might return an answer. 962 NO_RECOVERY 964 An unexpected server failure occurred which can not be recovered. 966 TRY_AGAIN 968 A temporary and possibly transient error occurred, such as a 969 failure of a server to respond. 971 The flags argument specifies the types of addresses that are searched 972 for, and the types of addresses that are returned. We note that a 973 special flags value of AI_DEFAULT (defined below) should handle most 974 applications. That is, porting simple applications to use IPv6 replaces 975 the call 977 hptr = gethostbyname(name); 979 with 981 hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num); 983 Applications desiring finer control over the types of addresses searched 984 for and returned, can specify other combinations of the flags argument. 986 A flags of 0 implies a strict interpretation of the af argument: 988 - If flags is 0 and af is AF_INET, then the caller wants only IPv4 989 addresses. A query is made for A records. If successful, the IPv4 990 addresses are returned and the h_length member of the hostent 991 structure will be 4, else the function returns a NULL pointer. 993 - If flags is 0 and if af is AF_INET6, then the caller wants only 994 IPv6 addresses. A query is made for AAAA records. If successful, 995 the IPv6 addresses are returned and the h_length member of the 996 hostent structure will be 16, else the function returns a NULL 997 pointer. 999 Other constants can be logically-ORed into the flags argument, to modify 1000 the behavior of the function. 1002 - If the AI_V4MAPPED flag is specified along with an af of 1003 AF_INET6, then the caller will accept IPv4-mapped IPv6 1004 addresses. That is, if no AAAA records are found then a query 1005 is made for A records and any found are returned as IPv4-mapped 1006 IPv6 addresses (h_length will be 16). The AI_V4MAPPED flag is 1007 ignored unless af equals AF_INET6. 1009 - The AI_ALL flag is used in conjunction with the AI_V4MAPPED 1010 flag, and is only used with the IPv6 address family. When AI_ALL 1011 is logically or'd with AI_V4MAPPED flag then the caller wants 1012 all addresses: IPv6 and IPv4-mapped IPv6. A query is first made 1013 for AAAA records and if successful, the IPv6 addresses are returned. 1014 Another query is then made for A records and any found are returned 1015 as IPv4-mapped IPv6 addresses. h_length will be 16. Only if both 1016 queries fail does the function return a NULL pointer. This flag is 1017 ignored unless af equals AF_INET6. 1019 - The AI_ADDRCONFIG flag specifies that a query for AAAA records 1020 should occur only if the node has at least one IPv6 source address 1021 configured and a query for A records should occur only if the 1022 node has at least one IPv4 source address configured. 1024 For example, if the node has no IPv6 source addresses configured, 1025 and af equals AF_INET6, and the node name being looked up has both 1026 AAAA and A records, then: 1028 (a) if only AI_ADDRCONFIG is specified, the function returns a 1029 NULL pointer; 1031 (b) if AI_ADDRCONFIG | AI_V4MAPPED is specified, the A records 1032 are returned as IPv4-mapped IPv6 addresses; 1034 The special flags value of AI_DEFAULT is defined as 1036 #define AI_DEFAULT (AI_V4MAPPED | AI_ADDRCONFIG) 1038 We noted that the getipnodebyname() function must allow the name 1039 argument to be either a node name or a literal address string (i.e., a 1040 dotted-decimal IPv4 address or an IPv6 hex address). This saves 1041 applications from having to call inet_pton() to handle literal address 1042 strings. 1044 There are four scenarios based on the type of literal address string and 1045 the value of the af argument. 1047 The two simple cases are: 1049 When name is a dotted-decimal IPv4 address and af equals AF_INET, or 1050 when name is an IPv6 hex address and af equals AF_INET6. The members of 1051 the returned hostent structure are: h_name points to a copy of the name 1052 argument, h_aliases is a NULL pointer, h_addrtype is a copy of the af 1053 argument, h_length is either 4 (for AF_INET) or 16 (for AF_INET6), 1054 h_addr_list[0] is a pointer to the 4-byte or 16-byte binary address, and 1055 h_addr_list[1] is a NULL pointer. 1057 When name is a dotted-decimal IPv4 address and af equals AF_INET6, and 1058 flags equals AI_V4MAPPED, an IPv4-mapped IPv6 address is returned: 1059 h_name points to an IPv6 hex address containing the IPv4-mapped IPv6 1060 address, h_aliases is a NULL pointer, h_addrtype is AF_INET6, h_length 1061 is 16, h_addr_list[0] is a pointer to the 16-byte binary address, and 1062 h_addr_list[1] is a NULL pointer. If AI_V4MAPPED is set (with or 1063 without AI_ALL) return IPv4-mapped otherwise return NULL. 1065 It is an error when name is an IPv6 hex address and af equals AF_INET. 1066 The function's return value is a NULL pointer and error_num equals 1067 HOST_NOT_FOUND. 1069 6.2 Address-To-Nodename Translation 1071 The following function has the same arguments as the existing 1072 gethostbyaddr() function, but adds an error number. 1074 #include 1075 #include 1077 struct hostent *getipnodebyaddr(const void *src, size_t len, int af, 1078 int *error_num); 1080 As with getipnodebyname(), getipnodebyaddr() must be thread safe. The 1081 error_num value is returned to the caller with the appropriate error 1082 code, to support thread safe error code returns. The following error 1083 conditions may be returned for error_num: 1085 HOST_NOT_FOUND 1086 No such host is known. 1088 NO_ADDRESS 1090 The server recognised the request and the name but no address 1091 is available. Another type of request to the name server for 1092 the domain might return an answer. 1094 NO_RECOVERY 1096 An unexpected server failure occurred which can not be recovered. 1098 TRY_AGAIN 1100 A temporary and possibly transient error occurred, such as a 1101 failure of a server to respond. 1103 One possible source of confusion is the handling of IPv4-mapped IPv6 1104 addresses and IPv4-compatible IPv6 addresses, but the following logic 1105 should apply. 1107 1. If af is AF_INET6, and if len equals 16, and if the IPv6 address 1108 is an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, 1109 then skip over the first 12 bytes of the IPv6 address, set af to 1110 AF_INET, and set len to 4. 1112 2. If af is AF_INET, lookup the name for the given IPv4 address 1113 (e.g., query for a PTR record in the in-addr.arpa domain). 1115 3. If af is AF_INET6, lookup the name for the given IPv6 address 1116 (e.g., query for a PTR record in the ip6.int domain). 1118 4. If the function is returning success, then the single address that 1119 is returned in the hostent structure is a copy of the first argument 1120 to the function with with the same address family that was passed as 1121 an argument to this function. 1123 All four steps listed are performed, in order. Also note that the IPv6 1124 hex addresses "::" and "::1" MUST NOT be treated as IPv4-compatible 1125 addresses, and if the address is "::", HOST_NOT_FOUND MUST be returned 1126 and a query of the address not performed. 1128 Also for the macro in section 6.7 IN6_IS_ADDR_V4COMPAT MUST return false 1129 for "::" and "::1". 1131 6.3 Freeing memory for getipnodebyname and getipnodebyaddr 1133 The hostent structure does not change from its existing definition. 1134 This structure, and the information pointed to by this structure, are 1135 dynamically allocated by getipnodebyname and getipnodebyaddr. The 1136 following function frees this memory: 1138 #include 1139 #include 1140 void freehostent(struct hostent *ptr); 1142 6.4 Protocol-Independent Nodename and Service Name Translation 1144 Nodename-to-address translation is done in a protocol-independent 1145 fashion using the getaddrinfo() function that is taken from the 1146 Institute of Electrical and Electronic Engineers (IEEE) POSIX 1003.1g 1147 (Protocol Independent Interfaces) draft specification [3]. 1149 The official specification for this function will be the final POSIX 1150 standard, with the following additional requirements: 1152 - getaddrinfo() (along with the getnameinfo() function described in 1153 the next section) must be thread safe. 1155 - The AI_NUMERICHOST is new with this document. 1157 - All fields in socket address structures returned by getaddrinfo() 1158 that are not filled in through an explicit argument (e.g., 1159 sin6_flowinfo and sin_zero) must be set to 0. (This makes it easier 1160 to compare socket address structures.) 1162 - getaddrinfo() must fill in the length field of a socket address structure 1163 (e.g., sin6_len) on systems that support this field. 1165 We are providing this independent description of the function because 1166 POSIX standards are not freely available (as are IETF documents). 1168 #include 1169 #include 1171 int getaddrinfo(const char *nodename, const char *servname, 1172 const struct addrinfo *hints, 1173 struct addrinfo **res); 1175 The addrinfo structure is defined as a result of including the 1176 header. 1178 struct addrinfo { 1179 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ 1180 int ai_family; /* PF_xxx */ 1181 int ai_socktype; /* SOCK_xxx */ 1182 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 1183 size_t ai_addrlen; /* length of ai_addr */ 1184 char *ai_canonname; /* canonical name for nodename */ 1185 struct sockaddr *ai_addr; /* binary address */ 1186 struct addrinfo *ai_next; /* next structure in linked list */ 1187 }; 1189 The return value from the function is 0 upon success or a nonzero error 1190 code. The following names are the nonzero error codes from 1191 getaddrinfo(), and are defined in : 1193 EAI_ADDRFAMILY address family for nodename not supported 1194 EAI_AGAIN temporary failure in name resolution 1195 EAI_BADFLAGS invalid value for ai_flags 1196 EAI_FAIL non-recoverable failure in name resolution 1197 EAI_FAMILY ai_family not supported 1198 EAI_MEMORY memory allocation failure 1199 EAI_NODATA no address associated with nodename 1200 EAI_NONAME nodename nor servname provided, or not known 1201 EAI_SERVICE servname not supported for ai_socktype 1202 EAI_SOCKTYPE ai_socktype not supported 1203 EAI_SYSTEM system error returned in errno 1205 The nodename and servname arguments are pointers to null-terminated 1206 strings or NULL. One or both of these two arguments must be a non-NULL 1207 pointer. In the normal client scenario, both the nodename and servname 1208 are specified. In the normal server scenario, only the servname is 1209 specified. A non-NULL nodename string can be either a node name or a 1210 numeric host address string (i.e., a dotted-decimal IPv4 address or an 1211 IPv6 hex address). A non-NULL servname string can be either a service 1212 name or a decimal port number. 1214 The caller can optionally pass an addrinfo structure, pointed to by the 1215 third argument, to provide hints concerning the type of socket that the 1216 caller supports. In this hints structure all members other than 1217 ai_flags, ai_family, ai_socktype, and ai_protocol must be zero or a NULL 1218 pointer. A value of PF_UNSPEC for ai_family means the caller will 1219 accept any protocol family. A value of 0 for ai_socktype means the 1220 caller will accept any socket type. A value of 0 for ai_protocol means 1221 the caller will accept any protocol. For example, if the caller handles 1222 only TCP and not UDP, then the ai_socktype member of the hints structure 1223 should be set to SOCK_STREAM when getaddrinfo() is called. If the 1224 caller handles only IPv4 and not IPv6, then the ai_family member of the 1225 hints structure should be set to PF_INET when getaddrinfo() is called. 1226 If the third argument to getaddrinfo() is a NULL pointer, this is the 1227 same as if the caller had filled in an addrinfo structure initialized to 1228 zero with ai_family set to PF_UNSPEC. 1230 Upon successful return a pointer to a linked list of one or more 1231 addrinfo structures is returned through the final argument. The caller 1232 can process each addrinfo structure in this list by following the 1233 ai_next pointer, until a NULL pointer is encountered. In each returned 1234 addrinfo structure the three members ai_family, ai_socktype, and 1235 ai_protocol are the corresponding arguments for a call to the socket() 1236 function. In each addrinfo structure the ai_addr member points to a 1237 filled-in socket address structure whose length is specified by the 1238 ai_addrlen member. 1240 If the AI_PASSIVE bit is set in the ai_flags member of the hints 1241 structure, then the caller plans to use the returned socket address 1242 structure in a call to bind(). In this case, if the nodename argument 1243 is a NULL pointer, then the IP address portion of the socket address 1244 structure will be set to INADDR_ANY for an IPv4 address or 1245 IN6ADDR_ANY_INIT for an IPv6 address. 1247 If the AI_PASSIVE bit is not set in the ai_flags member of the hints 1248 structure, then the returned socket address structure will be ready for 1249 a call to connect() (for a connection-oriented protocol) or either 1250 connect(), sendto(), or sendmsg() (for a connectionless protocol). In 1251 this case, if the nodename argument is a NULL pointer, then the IP 1252 address portion of the socket address structure will be set to the 1253 loopback address. 1255 If the AI_CANONNAME bit is set in the ai_flags member of the hints 1256 structure, then upon successful return the ai_canonname member of the 1257 first addrinfo structure in the linked list will point to a null- 1258 terminated string containing the canonical name of the specified 1259 nodename. 1261 If the AI_NUMERICHOST bit is set in the ai_flags member of the hints 1262 structure, then a non-NULL nodename string must be a numeric host 1263 address string. Otherwise an error of EAI_NONAME is returned. This 1264 flag prevents any type of name resolution service (e.g., the DNS) from 1265 being called. 1267 All of the information returned by getaddrinfo() is dynamically 1268 allocated: the addrinfo structures, and the socket address structures 1269 and canonical node name strings pointed to by the addrinfo structures. 1270 To return this information to the system the function freeaddrinfo() is 1271 called: 1273 #include 1274 #include 1276 void freeaddrinfo(struct addrinfo *ai); 1278 The addrinfo structure pointed to by the ai argument is freed, along 1279 with any dynamic storage pointed to by the structure. This operation is 1280 repeated until a NULL ai_next pointer is encountered. 1282 To aid applications in printing error messages based on the EAI_xxx 1283 codes returned by getaddrinfo(), the following function is defined. 1285 #include 1286 #include 1288 char *gai_strerror(int ecode); 1290 The argument is one of the EAI_xxx values defined earlier and the return 1291 value points to a string describing the error. If the argument is not 1292 one of the EAI_xxx values, the function still returns a pointer to a 1293 string whose contents indicate an unknown error. 1295 6.5 Socket Address Structure to Nodename and Service Name 1297 The POSIX 1003.1g specification includes no function to perform the 1298 reverse conversion from getaddrinfo(): to look up a nodename and service 1299 name, given the binary address and port. Therefore, we define the 1300 following function: 1302 #include 1303 #include 1305 int getnameinfo(const struct sockaddr *sa, socklen_t salen, 1306 char *host, size_t hostlen, 1307 char *serv, size_t servlen, 1308 int flags); 1310 This function looks up an IP address and port number provided by the 1311 caller in the DNS and system-specific database, and returns text strings 1312 for both in buffers provided by the caller. The function indicates 1313 successful completion by a zero return value; a non-zero return value 1314 indicates failure. 1316 The first argument, sa, points to either a sockaddr_in structure (for 1317 IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP address 1318 and port number. The salen argument gives the length of the sockaddr_in 1319 or sockaddr_in6 structure. 1321 The function returns the nodename associated with the IP address in the 1322 buffer pointed to by the host argument. The caller provides the size of 1323 this buffer via the hostlen argument. The service name associated with 1324 the port number is returned in the buffer pointed to by serv, and the 1325 servlen argument gives the length of this buffer. The caller specifies 1326 not to return either string by providing a zero value for the hostlen or 1327 servlen arguments. Otherwise, the caller must provide buffers large 1328 enough to hold the nodename and the service name, including the 1329 terminating null characters. 1331 Unfortunately most systems do not provide constants that specify the 1332 maximum size of either a fully-qualified domain name or a service name. 1333 Therefore to aid the application in allocating buffers for these two 1334 returned strings the following constants are defined in : 1336 #define NI_MAXHOST 1025 1337 #define NI_MAXSERV 32 1339 The first value is actually defined as the constant MAXDNAME in recent 1340 versions of BIND's header (older versions of BIND 1341 define this constant to be 256) and the second is a guess based on the 1342 services listed in the current Assigned Numbers RFC. 1344 The final argument is a flag that changes the default actions of this 1345 function. By default the fully-qualified domain name (FQDN) for the 1346 host is looked up in the DNS and returned. If the flag bit NI_NOFQDN is 1347 set, only the nodename portion of the FQDN is returned for local hosts. 1349 If the flag bit NI_NUMERICHOST is set, or if the host's name cannot be 1350 located in the DNS, the numeric form of the host's address is returned 1351 instead of its name (e.g., by calling inet_ntop() instead of 1352 getipnodebyaddr()). If the flag bit NI_NAMEREQD is set, an error is 1353 returned if the host's name cannot be located in the DNS. 1355 If the flag bit NI_NUMERICSERV is set, the numeric form of the service 1356 address is returned (e.g., its port number) instead of its name. The 1357 two NI_NUMERICxxx flags are required to support the "-n" flag that many 1358 commands provide. 1360 A fifth flag bit, NI_DGRAM, specifies that the service is a datagram 1361 service, and causes getservbyport() to be called with a second argument 1362 of "udp" instead of its default of "tcp". This is required for the few 1363 ports (512-514) that have different services for UDP and TCP. 1365 These NI_xxx flags are defined in along with the AI_xxx flags 1366 already defined for getaddrinfo(). 1368 6.6 Address Conversion Functions 1370 The two functions inet_addr() and inet_ntoa() convert an IPv4 address 1371 between binary and text form. IPv6 applications need similar functions. 1372 The following two functions convert both IPv6 and IPv4 addresses: 1374 #include 1375 #include 1377 int inet_pton(int af, const char *src, void *dst); 1379 const char *inet_ntop(int af, const void *src, 1380 char *dst, size_t size); 1382 The inet_pton() function converts an address in its standard text 1383 presentation form into its numeric binary form. The af argument 1384 specifies the family of the address. Currently the AF_INET and AF_INET6 1385 address families are supported. The src argument points to the string 1386 being passed in. The dst argument points to a buffer into which the 1387 function stores the numeric address. The address is returned in network 1388 byte order. Inet_pton() returns 1 if the conversion succeeds, 0 if the 1389 input is not a valid IPv4 dotted-decimal string or a valid IPv6 address 1390 string, or -1 with errno set to EAFNOSUPPORT if the af argument is 1391 unknown. The calling application must ensure that the buffer referred 1392 to by dst is large enough to hold the numeric address (e.g., 4 bytes for 1393 AF_INET or 16 bytes for AF_INET6). 1395 If the af argument is AF_INET, the function accepts a string in the 1396 standard IPv4 dotted-decimal form: 1398 ddd.ddd.ddd.ddd 1400 where ddd is a one to three digit decimal number between 0 and 255. 1401 Note that many implementations of the existing inet_addr() and 1402 inet_aton() functions accept nonstandard input: octal numbers, 1403 hexadecimal numbers, and fewer than four numbers. inet_pton() does not 1404 accept these formats. 1406 If the af argument is AF_INET6, then the function accepts a string in 1407 one of the standard IPv6 text forms defined in Section 2.2 of the 1408 addressing architecture specification [2]. 1410 The inet_ntop() function converts a numeric address into a text string 1411 suitable for presentation. The af argument specifies the family of the 1412 address. This can be AF_INET or AF_INET6. The src argument points to a 1413 buffer holding an IPv4 address if the af argument is AF_INET, or an IPv6 1414 address if the af argument is AF_INET6. The dst argument points to a 1415 buffer where the function will store the resulting text string. The 1416 size argument specifies the size of this buffer. The application must 1417 specify a non-NULL dst argument. For IPv6 addresses, the buffer must be 1418 at least 46-octets. For IPv4 addresses, the buffer must be at least 1419 16-octets. In order to allow applications to easily declare buffers of 1420 the proper size to store IPv4 and IPv6 addresses in string form, the 1421 following two constants are defined in : 1423 #define INET_ADDRSTRLEN 16 1424 #define INET6_ADDRSTRLEN 46 1426 The inet_ntop() function returns a pointer to the buffer containing the 1427 text string if the conversion succeeds, and NULL otherwise. Upon 1428 failure, errno is set to EAFNOSUPPORT if the af argument is invalid or 1429 ENOSPC if the size of the result buffer is inadequate. 1431 6.7 Address Testing Macros 1433 The following macros can be used to test for special IPv6 addresses. 1435 #include 1437 int IN6_IS_ADDR_UNSPECIFIED (const struct in6_addr *); 1438 int IN6_IS_ADDR_LOOPBACK (const struct in6_addr *); 1439 int IN6_IS_ADDR_MULTICAST (const struct in6_addr *); 1440 int IN6_IS_ADDR_LINKLOCAL (const struct in6_addr *); 1441 int IN6_IS_ADDR_SITELOCAL (const struct in6_addr *); 1442 int IN6_IS_ADDR_V4MAPPED (const struct in6_addr *); 1443 int IN6_IS_ADDR_V4COMPAT (const struct in6_addr *); 1445 int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); 1446 int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); 1447 int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); 1448 int IN6_IS_ADDR_MC_ORGLOCAL (const struct in6_addr *); 1449 int IN6_IS_ADDR_MC_GLOBAL (const struct in6_addr *); 1451 The first seven macros return true if the address is of the specified 1452 type, or false otherwise. The last five test the scope of a multicast 1453 address and return true if the address is a multicast address of the 1454 specified scope or false if the address is either not a multicast 1455 address or not of the specified scope. Note that IN6_IS_ADDR_LINKLOCAL 1456 and IN6_IS_ADDR_SITELOCAL return true only for the two local-use IPv6 1457 unicast addresses. These two macros do not return true for IPv6 1458 multicast addresses of either link-local scope or site-local scope. 1460 7. Summary of New Definitions 1462 The following list summarizes the constants, structure, and extern 1463 definitions discussed in this memo, sorted by header. 1465 IFNAMSIZ 1466 struct if_nameindex{}; 1468 AI_ADDRCONFIG 1469 AI_ALL 1470 AI_CANONNAME 1471 AI_NUMERICHOST 1472 AI_PASSIVE 1473 AI_V4MAPPED 1474 EAI_ADDRFAMILY 1475 EAI_AGAIN 1476 EAI_BADFLAGS 1477 EAI_FAIL 1478 EAI_FAMILY 1479 EAI_MEMORY 1480 EAI_NODATA 1481 EAI_NONAME 1482 EAI_SERVICE 1483 EAI_SOCKTYPE 1484 EAI_SYSTEM 1485 NI_DGRAM 1486 NI_MAXHOST 1487 NI_MAXSERV 1488 NI_NAMEREQD 1489 NI_NOFQDN 1490 NI_NUMERICHOST 1491 NI_NUMERICSERV 1492 struct addrinfo{}; 1494 IN6ADDR_ANY_INIT 1495 IN6ADDR_LOOPBACK_INIT 1496 INET6_ADDRSTRLEN 1497 INET_ADDRSTRLEN 1498 IPPROTO_IPV6 1499 IPV6_JOIN_GROUP 1500 IPV6_LEAVE_GROUP 1501 IPV6_MULTICAST_HOPS 1502 IPV6_MULTICAST_IF 1503 IPV6_MULTICAST_LOOP 1504 IPV6_UNICAST_HOPS 1505 SIN6_LEN 1506 extern const struct in6_addr in6addr_any; 1507 extern const struct in6_addr in6addr_loopback; 1508 struct in6_addr{}; 1509 struct ipv6_mreq{}; 1510 struct sockaddr_in6{}; 1512 AF_INET6 1513 PF_INET6 1514 union sockaddr_storage; 1516 The following list summarizes the function and macro prototypes 1517 discussed in this memo, sorted by header. 1519 int inet_pton(int, const char *, void *); 1520 const char *inet_ntop(int, const void *, 1521 char *, size_t); 1523 char *if_indextoname(unsigned int, char *); 1524 unsigned int if_nametoindex(const char *); 1525 void if_freenameindex(struct if_nameindex *); 1526 struct if_nameindex *if_nameindex(void); 1528 int getaddrinfo(const char *, const char *, 1529 const struct addrinfo *, 1530 struct addrinfo **); 1531 int getnameinfo(const struct sockaddr *, socklen_t, 1532 char *, size_t, char *, size_t, int); 1533 void freeaddrinfo(struct addrinfo *); 1534 char *gai_strerror(int); 1535 struct hostent *getipnodebyname(const char *, int, int, 1536 int *); 1537 struct hostent *getipnodebyaddr(const void *, size_t, int, 1538 int *); 1539 void freehostent(struct hostent *); 1541 int IN6_IS_ADDR_LINKLOCAL(const struct in6_addr *); 1542 int IN6_IS_ADDR_LOOPBACK(const struct in6_addr *); 1543 int IN6_IS_ADDR_MC_GLOBAL(const struct in6_addr *); 1544 int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *); 1545 int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *); 1546 int IN6_IS_ADDR_MC_ORGLOCAL(const struct in6_addr *); 1547 int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *); 1548 int IN6_IS_ADDR_MULTICAST(const struct in6_addr *); 1549 int IN6_IS_ADDR_SITELOCAL(const struct in6_addr *); 1550 int IN6_IS_ADDR_UNSPECIFIED(const struct in6_addr *); 1551 int IN6_IS_ADDR_V4COMPAT(const struct in6_addr *); 1552 int IN6_IS_ADDR_V4MAPPED(const struct in6_addr *); 1554 8. Security Considerations 1556 IPv6 provides a number of new security mechanisms, many of which need to 1557 be accessible to applications. Companion memos detailing the extensions 1558 to the socket interfaces to support IPv6 security are being written. 1560 9. Year 2000 Considerations 1562 There are no issues for this draft concerning the Year 2000 issue 1563 regarding the use of dates. 1565 Changes From RFC 2133 1567 Changes made in the March 1998 Edition (-01 draft): 1569 Changed all "hostname" to "nodename" for consistency with other IPv6 1570 documents. 1572 Section 3.3: changed comment for sin6_flowinfo to be "traffic class & 1573 flow info" and updated corresponding text description to current 1574 definition of these two fields. 1576 Section 3.10 ("Portability Additions") is new. 1578 Section 6: a new paragraph was added reiterating that the existing 1579 gethostbyname() and gethostbyaddr() are not changed. 1581 Section 6.1: change gethostbyname3() to getnodebyname(). Add 1582 AI_DEFAULT to handle majority of applications. Renamed 1583 AI_V6ADDRCONFIG to AI_ADDRCONFIG and define it for A records and IPv4 1584 addresses too. Defined exactly what getnodebyname() must return if 1585 the name argument is a numeric address string. 1587 Section 6.2: change gethostbyaddr() to getnodebyaddr(). Reword items 1588 2 and 3 in the description of how to handle IPv4-mapped and IPv4- 1589 compatible addresses to "lookup a name" for a given address, instead 1590 of specifying what type of DNS query to issue. 1592 Section 6.3: added two more requirements to getaddrinfo(). 1594 Section 7: added the following constants to the list for : 1595 AI_ADDRCONFIG, AI_ALL, and AI_V4MAPPED. Add union sockaddr_union and 1596 SA_LEN to the lists for . 1598 Updated references. 1600 Changes made in the November 1997 Edition (-00 draft): 1602 The data types have been changed to conform with Draft 6.6 of the 1603 Posix 1003.1g standard. 1605 Section 3.2: data type of s6_addr changed to "uint8_t". 1607 Section 3.3: data type of sin6_family changed to "sa_family_t". data 1608 type of sin6_port changed to "in_port_t", data type of sin6_flowinfo 1609 changed to "uint32_t". 1611 Section 3.4: same as Section 3.3, plus data type of sin6_len changed 1612 to "uint8_t". 1614 Section 6.2: first argument of gethostbyaddr() changed from "const 1615 char *" to "const void *" and second argument changed from "int" to 1616 "size_t". 1618 Section 6.4: second argument of getnameinfo() changed from "size_t" 1619 to "socklen_t". 1621 The wording was changed when new structures were defined, to be more 1622 explicit as to which header must be included to define the structure: 1624 Section 3.2 (in6_addr{}), Section 3.3 (sockaddr_in6{}), Section 3.4 1625 (sockaddr_in6{}), Section 4.3 (if_nameindex{}), Section 5.3 1626 (ipv6_mreq{}), and Section 6.3 (addrinfo{}). 1628 Section 4: NET_RT_LIST changed to NET_RT_IFLIST. 1630 Section 5.1: The IPV6_ADDRFORM socket option was removed. 1632 Section 5.3: Added a note that an option value other than 0 or 1 for 1633 IPV6_MULTICAST_LOOP returns an error. Added a note that 1634 IPV6_MULTICAST_IF, IPV6_MULTICAST_HOPS, and IPV6_MULTICAST_LOOP can 1635 also be used with getsockopt(), but IPV6_ADD_MEMBERSHIP and 1636 IPV6_DROP_MEMBERSHIP cannot be used with getsockopt(). 1638 Section 6.1: Removed the description of gethostbyname2() and its 1639 associated RES_USE_INET6 option, replacing it with gethostbyname3(). 1641 Section 6.2: Added requirement that gethostbyaddr() be thread safe. 1642 Reworded step 4 to avoid using the RES_USE_INET6 option. 1644 Section 6.3: Added the requirement that getaddrinfo() and 1645 getnameinfo() be thread safe. Added the AI_NUMERICHOST flag. 1647 Section 6.6: Added clarification about IN6_IS_ADDR_LINKLOCAL and 1648 IN6_IS_ADDR_SITELOCAL macros. 1650 Changes made to the draft -01 specification Sept 98 1652 Changed priority to traffic class in the spec. 1654 Added the need for scope identification in section 2.1. 1656 Added sin6_scope_id to struct sockaddr_in6 in sections 3.3 and 3.4. 1658 Changed 3.10 to use generic storage structure to support holding IPv6 1659 addresses and removed the SA_LEN macro. 1661 Distinguished between invalid input parameters and system failures 1662 for Interface Identification in Section 4.1 and 4.2. 1664 Added defaults for multicast operations in section 5.2 and changed 1665 the names from ADD to JOIN and DROP to LEAVE to be consistent with 1666 IPv6 multicast terminology. 1668 Changed getnodebyname to getipnodebyname, getnodebyaddr to 1669 getipnodebyaddr, and added MT safe error code to function parameters 1670 in section 6. 1672 Moved freehostent to its own sub-section after getipnodebyaddr now 1673 6.3 (so this bumps all remaining sections in section 6. 1675 Clarified the use of AI_ALL and AI_V4MAPPED that these are dependent 1676 on the AF parameter and must be used as a conjunction in section 6.1. 1678 Removed the restriction that literal addresses cannot be used with a 1679 flags argument in section 6.1. 1681 Added Year 2000 Section to the draft 1683 Deleted Reference to the following because the attached is deleted from 1684 the ID directory and has expired. But the logic from the aforementioned 1685 draft still applies, so that was kept in Section 6.2 bullets after 3rd 1686 paragraph. 1687 [7] P. Vixie, "Reverse Name Lookups of Encapsulated IPv4 Addresses 1688 in IPv6", Internet-Draft, , 1689 May 1996. 1691 Deleted the following reference as it is no longer referenced. 1692 And the draft has expired. 1693 [3] D. McDonald, "A Simple IP Security API Extension to BSD Sockets", 1694 Internet-Draft, , 1695 March 1997. 1697 Deleted the following reference as it is no longer referenced. 1698 [4] C. Metz, "Network Security API for Sockets", 1699 Internet-Draft, , 1700 January 1998. 1702 Update current references to current status. 1704 Added alignment notes for in6_addr and sin6_addr. 1706 Clarified further that AI_V4MAPPED must be used with a dotted IPv4 1707 literal address for getipnodebyname(), when address family is 1708 AF_INET6. 1710 Added text to clarify "::" and "::1" when used by getipnodebyaddr(). 1712 Acknowledgments 1714 Thanks to the many people who made suggestions and provided feedback to 1715 this document, including: Werner Almesberger, Ran Atkinson, Fred Baker, 1716 Dave Borman, Andrew Cherenson, Alex Conta, Alan Cox, Steve Deering, 1717 Richard Draves, Francis Dupont, Robert Elz, Marc Hasson, Tom Herbert, 1718 Bob Hinden, Wan-Yen Hsu, Christian Huitema, Koji Imada, Markus Jork, Ron 1719 Lee, Alan Lloyd, Charles Lynn, Dan McDonald, Dave Mitton, Thomas Narten, 1720 Josh Osborne, Craig Partridge, Jean-Luc Richier, Erik Scoredos, Keith 1721 Sklower, Matt Thomas, Harvey Thompson, Dean D. Throop, Karen Tracey, 1722 Glenn Trewitt, Paul Vixie, David Waitzman, Carl Williams, and Kazu 1723 Yamamoto, 1725 The getaddrinfo() and getnameinfo() functions are taken from an earlier 1726 Internet Draft by Keith Sklower. As noted in that draft, William Durst, 1727 Steven Wise, Michael Karels, and Eric Allman provided many useful 1728 discussions on the subject of protocol-independent name-to-address 1729 translation, and reviewed early versions of Keith Sklower's original 1730 proposal. Eric Allman implemented the first prototype of getaddrinfo(). 1731 The observation that specifying the pair of name and service would 1732 suffice for connecting to a service independent of protocol details was 1733 made by Marshall Rose in a proposal to X/Open for a "Uniform Network 1734 Interface". 1736 Craig Metz, Jack McCann, Erik Nordmark, Tim Hartrick, and Mukesh Kacker 1737 made many contributions to this document. Ramesh Govindan made a number 1738 of contributions and co-authored an earlier version of this memo. 1740 References 1742 [1] S. Deering, R. Hinden, "Internet Protocol, Version 6 (IPv6) 1743 Specification", Internet Draft, 1744 , November 1997. 1746 [2] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture", 1747 RFC 2373, July 1998 Draft Standard. 1749 [3] IEEE, "Protocol Independent Interfaces", 1750 IEEE Std 1003.1g, DRAFT 6.6, 1751 March 1997. 1753 [4] W. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 1754 RFC 2292, February 1998. 1756 Authors' Addresses 1758 Robert E. Gilligan 1759 FreeGate Corporation 1760 1208 E. Arques Ave. 1761 Sunnyvale, CA 94086 1762 Phone: +1 408 617 1004 1763 Email: gilligan@freegate.net 1765 Susan Thomson 1766 Bell Communications Research 1767 MRE 2P-343, 445 South Street 1768 Morristown, NJ 07960 1769 Telephone: +1 201 829 4514 1770 Email: set@thumper.bellcore.com 1772 Jim Bound 1773 Compaq Computer Corporation 1774 110 Spitbrook Road ZK3-3/U14 1775 Nashua, NH 03062-2698 1776 Phone: +1 603 884 0400 1777 Email: bound@zk3.dec.com 1779 W. Richard Stevens 1780 1202 E. Paseo del Zorro 1781 Tucson, AZ 85718-2826 1782 Phone: +1 520 297 9416 1783 Email: rstevens@kohala.com