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