idnits 2.17.1 draft-ietf-ipngwg-bsd-api-06.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-04-19) 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 6 months document validity. ** 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. == No 'Intended status' indicated for this document; assuming Proposed Standard 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 67 instances of too long lines in the document, the longest one being 4 characters in excess of 72. ** The abstract seems to contain references ([5]), 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. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 236 has weird spacing: '... u_char s6_ad...' == Line 472 has weird spacing: '... int recv_...' == Line 473 has weird spacing: '... int recv_...' == Line 512 has weird spacing: '... int send_...' == Line 525 has weird spacing: '... int send_...' == (14 more instances...) -- 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 (November 23, 1996) is 10009 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 236, but not defined ** Obsolete normative reference: RFC 1883 (ref. '1') (Obsoleted by RFC 2460) ** Obsolete normative reference: RFC 1884 (ref. '2') (Obsoleted by RFC 2373) -- Possible downref: Non-RFC (?) normative reference: ref. '3' -- Possible downref: Non-RFC (?) normative reference: ref. '4' -- Possible downref: Non-RFC (?) normative reference: ref. '5' Summary: 12 errors (**), 0 flaws (~~), 9 warnings (==), 6 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 J. Bound (Digital) 5 W. R. Stevens (Consultant) 6 November 23, 1996 8 Basic Socket Interface Extensions for IPv6 9 11 Abstract 13 The de facto standard application program interface (API) for TCP/IP 14 applications is the "sockets" interface. Although this API was 15 developed for Unix in the early 1980s it has also been implemented on 16 a wide variety of non-Unix systems. TCP/IP applications written 17 using the sockets API have in the past enjoyed a high degree of 18 portability and we would like the same portability with IPv6 19 applications. But changes are required to the sockets API to support 20 IPv6 and this memo describes these changes. These include a new 21 socket address structure to carry IPv6 addresses, new address 22 conversion functions, and some new socket options. These extensions 23 are designed to provide access to the basic IPv6 features required by 24 TCP and UDP applications, including multicasting, while introducing a 25 minimum of change into the system and providing complete 26 compatibility for existing IPv4 applications. Additional extensions 27 for advanced IPv6 features (raw sockets and access to the IPv6 28 extension headers) are defined in another document [5]. 30 Status of this Memo 32 This document is an Internet Draft. Internet Drafts are working 33 documents of the Internet Engineering Task Force (IETF), its Areas, 34 and its Working Groups. Note that other groups may also distribute 35 working documents as Internet Drafts. 37 Internet Drafts are draft documents valid for a maximum of six 38 months. This Internet Draft expires on May 23, 1997. Internet 39 Drafts may be updated, replaced, or obsoleted by other documents at 40 any time. It is not appropriate to use Internet Drafts as reference 41 material or to cite them other than as a "working draft" or "work in 42 progress." 44 To learn the current status of any Internet-Draft, please check the 45 1id-abstracts.txt listing contained in the Internet-Drafts Shadow 46 Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or 47 munnari.oz.au. 49 Distribution of this memo is unlimited. 51 Table of Contents 53 1. Introduction ..................................................... 3 55 2. Design Considerations ............................................ 3 56 2.1. What Needs to be Changed ....................................... 3 57 2.2. Data Types ..................................................... 5 59 3. Socket Interface ................................................. 5 60 3.1. IPv6 Address Family and Protocol Family ........................ 5 61 3.2. IPv6 Address Structure ......................................... 5 62 3.3. Socket Address Structure for 4.3BSD-Based Systems .............. 6 63 3.4. Socket Address Structure for 4.4BSD-Based Systems .............. 7 64 3.5. The Socket Functions ........................................... 8 65 3.6. Compatibility with IPv4 Applications ........................... 9 66 3.7. Compatibility with IPv4 Nodes .................................. 9 67 3.8. Flow Information ............................................... 10 68 3.9. IPv6 Wildcard Address .......................................... 12 69 3.10. IPv6 Loopback Address ......................................... 13 71 4. Interface Identification ......................................... 14 72 4.1. Name-to-Index .................................................. 15 73 4.2. Index-to-Name .................................................. 15 74 4.3. Return All Interface Names and Indexes ......................... 15 76 5. Socket Options ................................................... 16 77 5.1. Changing Socket Type ........................................... 16 78 5.2. Unicast Hop Limit .............................................. 17 79 5.3. Sending and Receiving Multicast Packets ........................ 18 81 6. Library Functions ................................................ 20 82 6.1. Hostname-to-Address Translation ................................ 20 83 6.2. Address To Hostname Translation ................................ 22 84 6.3. Protocol-Independent Hostname and Service Name Translation ..... 23 85 6.4. Socket Address Structure to Hostname and Service Name .......... 26 86 6.5. Address Conversion Functions ................................... 27 87 6.6. IPv4-Mapped Addresses .......................................... 28 89 7. Security Considerations .......................................... 29 91 8. Change History ................................................... 29 93 9. Acknowledgments .................................................. 33 95 10. References ...................................................... 33 97 11. Authors' Addresses .............................................. 34 99 1. Introduction 101 While IPv4 addresses are 32 bits long, IPv6 nodes are identified by 102 128-bit addresses. The socket interface make the size of an IP 103 address quite visible to an application; virtually all TCP/IP 104 applications for BSD-based systems have knowledge of the size of an 105 IP address. Those parts of the API that expose the addresses must be 106 changed to accommodate the larger IPv6 address size. IPv6 also 107 introduces new features (e.g., flow label and priority), some of 108 which must be made visible to applications via the API. This memo 109 defines a set of extensions to the socket interface to support the 110 larger address size and new features of IPv6. 112 2. Design Considerations 114 There are a number of important considerations in designing changes 115 to this well-worn API: 117 - The API changes should provide both source and binary 118 compatibility for programs written to the original API. That is, 119 existing program binaries should continue to operate when run on 120 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. 125 - The changes to the API should be as small as possible in order to 126 simplify the task of converting existing IPv4 applications to 127 IPv6. 129 - Where possible, applications should be able to use this API to 130 interoperate with both IPv6 and IPv4 hosts. Applications should 131 not need to know which type of host they are 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 140 API could probably be designed for operation on systems that support 141 only IPv6. However, this is not addressed in this memo. 143 2.1. What Needs to be Changed 144 The socket interface API consists of a few distinct components: 146 - Core socket functions. 148 - Address data structures. 150 - Name-to-address translation functions. 152 - Address conversion functions. 154 The core socket functions -- those functions that deal with such 155 things as setting up and tearing down TCP connections, and sending 156 and receiving UDP packets -- were designed to be transport 157 independent. Where protocol addresses are passed as function 158 arguments, they are carried via opaque pointers. A protocol-specific 159 address data structure is defined for each protocol that the socket 160 functions support. Applications must cast pointers to these 161 protocol-specific address structures into pointers to the generic 162 "sockaddr" address structure when using the socket functions. These 163 functions need not change for IPv6, but a new IPv6-specific address 164 data structure is needed. 166 The "sockaddr_in" structure is the protocol-specific data structure 167 for IPv4. This data structure actually includes 8-octets of unused 168 space, and it is tempting to try to use this space to adapt the 169 sockaddr_in structure to IPv6. Unfortunately, the sockaddr_in 170 structure is not large enough to hold the 16-octet IPv6 address as 171 well as the other information (address family and port number) that 172 is needed. So a new address data structure must be defined for IPv6. 174 The name-to-address translation functions in the socket interface are 175 gethostbyname() and gethostbyaddr(). These must be modified to 176 support IPv6 and the semantics defined must provide 100% backward 177 compatibility for all existing IPv4 applications, along with IPv6 178 support for new applications. Additionally, the POSIX 1003.g draft 179 [4] specifies a new hostname-to-address translation function which is 180 protocol independent. This function can also be used with IPv6. 182 The address conversion functions -- inet_ntoa() and inet_addr() -- 183 convert IPv4 addresses between binary and printable form. These 184 functions are quite specific to 32-bit IPv4 addresses. We have 185 designed two analogous functions that convert both IPv4 and IPv6 186 addresses, and carry an address type parameter so that they can be 187 extended to other protocol families as well. 189 Finally, a few miscellaneous features are needed to support IPv6. 190 New interfaces are needed to support the IPv6 flow label, priority, 191 and hop limit header fields. New socket options are needed to 192 control the sending and receiving of IPv6 multicast packets. 194 The socket interface may be enhanced in the future to provide access 195 to other IPv6 features. These extensions are described in [5]. 197 2.2. Data Types 199 The data types of the structure elements given in this memo are 200 intended to be examples, not absolute requirements. Whenever 201 possible, POSIX 1003.1g data types are used: u_intN_t means an 202 unsigned integer of exactly N bits (e.g., u_int16_t) and u_intNm_t 203 means an unsigned integer of at least N bits (e.g., u_int32m_t). We 204 also assume the argument data types from 1003.1g when possible (e.g., 205 the final argument to setsockopt() is a size_t value). Whenever 206 buffer sizes are specified, the POSIX 1003.1 size_t data type is used 207 (e.g., the two length arguments to getnameinfo()). 209 3. Socket Interface 211 This section specifies the socket interface changes for IPv6. 213 3.1. IPv6 Address Family and Protocol Family 215 A new address family name, AF_INET6, is defined in . 216 The AF_INET6 definition distinguishes between the original 217 sockaddr_in address data structure, and the new sockaddr_in6 data 218 structure. 220 A new protocol family name, PF_INET6, is defined in . 221 Like most of the other protocol family names, this will usually be 222 defined to have the same value as the corresponding address family 223 name: 225 #define PF_INET6 AF_INET6 227 The PF_INET6 is used in the first argument to the socket() function 228 to indicate that an IPv6 socket is being created. 230 3.2. IPv6 Address Structure 232 A new data structure to hold a single IPv6 address is defined as 233 follows: 235 struct in6_addr { 236 u_char s6_addr[16]; /* IPv6 address */ 237 } 239 This data structure contains an array of sixteen 8-bit elements, 240 which make up one 128-bit IPv6 address. The IPv6 address is stored 241 in network byte order. 243 Applications obtain the declaration for this structure by including 244 the header . 246 3.3. Socket Address Structure for 4.3BSD-Based Systems 248 In the socket interface, a different protocol-specific data structure 249 is defined to carry the addresses for each protocol suite. Each 250 protocol-specific data structure is designed so it can be cast into a 251 protocol-independent data structure -- the "sockaddr" structure. 252 Each has a "family" field that overlays the "sa_family" of the 253 sockaddr data structure. This field identifies the type of the data 254 structure. 256 The sockaddr_in structure is the protocol-specific address data 257 structure for IPv4. It is used to pass addresses between 258 applications and the system in the socket functions. The following 259 structure is defined to carry IPv6 addresses: 261 struct sockaddr_in6 { 262 u_int16m_t sin6_family; /* AF_INET6 */ 263 u_int16m_t sin6_port; /* transport layer port # */ 264 u_int32m_t sin6_flowinfo; /* IPv6 flow information */ 265 struct in6_addr sin6_addr; /* IPv6 address */ 266 }; 268 This structure is designed to be compatible with the sockaddr data 269 structure used in the 4.3BSD release. 271 The sin6_family field identifies this as a sockaddr_in6 structure. 272 This field overlays the sa_family field when the buffer is cast to a 273 sockaddr data structure. The value of this field must be AF_INET6. 275 The sin6_port field contains the 16-bit UDP or TCP port number. This 276 field is used in the same way as the sin_port field of the 277 sockaddr_in structure. The port number is stored in network byte 278 order. 280 The sin6_flowinfo field is a 32-bit field that contains two pieces of 281 information: the 24-bit IPv6 flow label and the 4-bit priority field. 282 The IPv6 flow label is represented as the low-order 24 bits of the 283 32-bit field. The priority is represented in the next 4 bits above 284 this. The high-order 4 bits of this field are reserved. The 285 sin6_flowinfo field is stored in network byte order. The use of the 286 flow label and priority fields are explained in Section 3.8. 288 The sin6_addr field is a single in6_addr structure (defined in the 289 previous section). This field holds one 128-bit IPv6 address. The 290 address is stored in network byte order. 292 The ordering of elements in this structure is specifically designed 293 so that the sin6_addr field will be aligned on a 64-bit boundary. 294 This is done for optimum performance on 64-bit architectures. 296 Applications obtain the declaration of the sockaddr_in6 structure by 297 including the header . 299 3.4. Socket Address Structure for 4.4BSD-Based Systems 301 The 4.4BSD release includes a small, but incompatible change to the 302 socket interface. The "sa_family" field of the sockaddr data 303 structure was changed from a 16-bit value to an 8-bit value, and the 304 space saved used to hold a length field, named "sa_len". The 305 sockaddr_in6 data structure given in the previous section cannot be 306 correctly cast into the newer sockaddr data structure. For this 307 reason, the following alternative IPv6 address data structure is 308 provided to be used on systems based on 4.4BSD: 310 #define SIN6_LEN 312 struct sockaddr_in6 { 313 u_char sin6_len; /* length of this struct */ 314 u_char sin6_family; /* AF_INET6 */ 315 u_int16m_t sin6_port; /* Transport layer port # */ 316 u_int32m_t sin6_flowinfo; /* IPv6 flow information */ 317 struct in6_addr sin6_addr; /* IPv6 address */ 318 }; 320 The only differences between this data structure and the 4.3BSD 321 variant are the inclusion of the length field, and the change of the 322 family field to a 8-bit data type. The definitions of all the other 323 fields are identical to the structure defined in the previous 324 section. 326 Systems that provide this version of the sockaddr_in6 data structure 327 must also declare SIN6_LEN as a result of including the 328 header. This macro allows applications to determine 329 whether they are being built on a system that supports the 4.3BSD or 330 4.4BSD variants of the data structure. 332 Note that the size of the sockaddr_in6 structure is larger than the 333 size of the sockaddr structure. Applications that use the 334 sockaddr_in6 structure need to be aware that they cannot use 335 sizeof(sockaddr) to allocate a buffer to hold a sockaddr_in6 336 structure. They should use sizeof(sockaddr_in6) instead. 338 3.5. The Socket Functions 340 Applications call the socket() function to create a socket descriptor 341 that represents a communication endpoint. The arguments to the 342 socket() function tell the system which protocol to use, and what 343 format address structure will be used in subsequent functions. For 344 example, to create an IPv4/TCP socket, applications make the call: 346 s = socket(PF_INET, SOCK_STREAM, 0); 348 To create an IPv4/UDP socket, applications make the call: 350 s = socket(PF_INET, SOCK_DGRAM, 0); 352 Applications may create IPv6/TCP and IPv6/UDP sockets by simply using 353 the constant PF_INET6 instead of PF_INET in the first argument. For 354 example, to create an IPv6/TCP socket, applications make the call: 356 s = socket(PF_INET6, SOCK_STREAM, 0); 358 To create an IPv6/UDP socket, applications make the call: 360 s = socket(PF_INET6, SOCK_DGRAM, 0); 362 Once the application has created a PF_INET6 socket, it must use the 363 sockaddr_in6 address structure when passing addresses in to the 364 system. The functions that the application uses to pass addresses 365 into the system are: 367 bind() 368 connect() 369 sendmsg() 370 sendto() 372 The system will use the sockaddr_in6 address structure to return 373 addresses to applications that are using PF_INET6 sockets. The 374 functions that return an address from the system to an application 375 are: 377 accept() 378 recvfrom() 379 recvmsg() 380 getpeername() 381 getsockname() 383 No changes to the syntax of the socket functions are needed to 384 support IPv6, since the all of the "address carrying" functions use 385 an opaque address pointer, and carry an address length as a function 386 argument. 388 3.6. Compatibility with IPv4 Applications 390 In order to support the large base of applications using the original 391 API, system implementations must provide complete source and binary 392 compatibility with the original API. This means that systems must 393 continue to support PF_INET sockets and the sockaddr_in address 394 structure. Applications must be able to create IPv4/TCP and IPv4/UDP 395 sockets using the PF_INET constant in the socket() function, as 396 described in the previous section. Applications should be able to 397 hold a combination of IPv4/TCP, IPv4/UDP, IPv6/TCP and IPv6/UDP 398 sockets simultaneously within the same process. 400 Applications using the original API should continue to operate as 401 they did on systems supporting only IPv4. That is, they should 402 continue to interoperate with IPv4 nodes. 404 3.7. Compatibility with IPv4 Nodes 406 The API also provides a different type of compatibility: the ability 407 for IPv6 applications to interoperate with IPv4 applications. This 408 feature uses the IPv4-mapped IPv6 address format defined in the IPv6 409 addressing architecture specification [2]. This address format 410 allows the IPv4 address of an IPv4 node to be represented as an IPv6 411 address. The IPv4 address is encoded into the low-order 32 bits of 412 the IPv6 address, and the high-order 96 bits hold the fixed prefix 413 0:0:0:0:0:FFFF. IPv4-mapped addresses are written as follows: 415 ::FFFF: 417 These addresses are often generated automatically by the 418 gethostbyname() function when the specified host has only IPv4 419 addresses (as described in Section 6.1). 421 Applications may use PF_INET6 sockets to open TCP connections to IPv4 422 nodes, or send UDP packets to IPv4 nodes, by simply encoding the 423 destination's IPv4 address as an IPv4-mapped IPv6 address, and 424 passing that address, within a sockaddr_in6 structure, in the 425 connect() or sendto() call. When applications use PF_INET6 sockets 426 to accept TCP connections from IPv4 nodes, or receive UDP packets 427 from IPv4 nodes, the system returns the peer's address to the 428 application in the accept(), recvfrom(), or getpeername() call using 429 a sockaddr_in6 structure encoded this way. 431 Few applications will likely need to know which type of node they are 432 interoperating with. However, for those applications that do need to 433 know, the inet6_isipv4mapped() function, defined in Section 6.6, is 434 provided. 436 3.8. Flow Information 438 The IPv6 header has a 24-bit field to hold a "flow label", and a 4- 439 bit field to hold a "priority" value. Applications must have control 440 over what values for these fields are used in packets that they 441 originate, and must have access to the field values of packets that 442 they receive. 444 The sin6_flowinfo field of the sockaddr_in6 structure encodes two 445 pieces of information: IPv6 flow label and IPv6 priority. 446 Applications use this field to set the flow label and priority in 447 IPv6 headers of packets they generate, and to retrieve the flow label 448 and priority from the packets they receive. The header fields of an 449 actively opened TCP connection are set by assigning in the 450 sin6_flowinfo field of the destination address sockaddr_in6 structure 451 passed in the connect() function. The same technique can be used 452 with the sockaddr_in6 structure passed to the sendto() or sendmsg() 453 function to set the flow label and priority fields of UDP packets. 454 Similarly, the flow label and priority values of received UDP packets 455 and accepted TCP connections are reflected in the sin6_flowinfo field 456 of the sockaddr_in6 structure returned to the application by the 457 recvfrom(), recvmsg(), and accept() functions. An application may 458 specify the flow label and priority to use in transmitted packets of 459 a passively accepted TCP connection, by setting the sin6_flowinfo 460 field of the address passed to the bind() function. 462 Implementations provide two bitmask constant declarations to help 463 applications select out the flow label and priority fields. These 464 constants are: 466 IPV6_FLOWINFO_FLOWLABEL 467 IPV6_FLOWINFO_PRIORITY 469 These constants can be applied to the sin6_flowinfo field of 470 addresses returned to the application, for example: 472 int recv_flow; /* host byte ordered, 0-0x00ffffff */ 473 int recv_prio; /* host byte ordered, 0-15 */ 474 struct sockaddr_in6 sin6; 475 . . . 476 recvfrom(s, buf, buflen, flags, (struct sockaddr *) &sin6, &fromlen); 477 . . . 478 recv_flow = ntohl(sin6.sin6_flowinfo & IPV6_FLOWINFO_FLOWLABEL); 479 recv_prio = ntohl(sin6.sin6_flowinfo & IPV6_FLOWINFO_PRIORITY) >> 24; 480 printf("flow = %d, prio = %d\n", recv_flow, recv_prio); 482 Recall that sin6_flowinfo is network byte ordered, as are the two 483 IPV6_FLOWINFO_xxx constants. 485 On the sending side, applications are responsible for selecting the 486 flow label value and specifying a priority. The headers provide 487 constant declarations for the 16 IPv6 priority values defined in the 488 IPv6 specification [1]. These constants are: 490 IPV6_PRIORITY_UNCHARACTERIZED 491 IPV6_PRIORITY_FILLER 492 IPV6_PRIORITY_UNATTENDED 493 IPV6_PRIORITY_RESERVED1 494 IPV6_PRIORITY_BULK 495 IPV6_PRIORITY_RESERVED2 496 IPV6_PRIORITY_INTERACTIVE 497 IPV6_PRIORITY_CONTROL 498 IPV6_PRIORITY_8 499 IPV6_PRIORITY_9 500 IPV6_PRIORITY_10 501 IPV6_PRIORITY_11 502 IPV6_PRIORITY_12 503 IPV6_PRIORITY_13 504 IPV6_PRIORITY_14 505 IPV6_PRIORITY_15 507 Most applications will use these constants (e.g., 508 IPV6_PRIORITY_INTERACTIVE can be built into Telnet clients and 509 servers). Since these constants are defined in network byte order an 510 example is: 512 int send_flow; /* host byte ordered, 0-0x00ffffff */ 513 struct sockaddr_in6 sin6; 515 send_flow = /* undefined at this time; perhaps a system call */ 516 sin6.sin6_flowinfo = htonl(send_flow) & IPV6_FLOWINFO_FLOWLABEL | 517 IPV6_PRIORITY_INTERACTIVE; 518 . . . 519 connect( ... ) 521 Some applications may specify the priority as a value between 0 and 522 15 (perhaps a command-line argument) and the following example shows 523 the required byte ordering and shifting: 525 int send_flow; /* host byte ordered, 0-0x00ffffff */ 526 int send_prio; /* host byte ordered, 0-15 */ 527 struct sockaddr_in6 sin6; 529 send_flow = /* undefined at this time; perhaps a system call */ 530 send_prio = 12; /* or some other host byte ordered value, 0-15 */ 531 sin6.sin6_flowinfo = htonl(send_flow) & IPV6_FLOWINFO_FLOWLABEL | 532 htonl(send_prio << 24) & IPV6_FLOWINFO_PRIORITY; 533 . . . 534 sendto( ... ) 536 The declarations for these constants are obtained by including the 537 header . 539 3.9. IPv6 Wildcard Address 541 While the bind() function allows applications to select the source IP 542 address of UDP packets and TCP connections, applications often want 543 the system select the source address for them. With IPv4, one 544 specifies the address as the symbolic constant INADDR_ANY (called the 545 "wildcard" address) in the bind() call, or simply omits the bind() 546 entirely. 548 Since the IPv6 address type is a structure (struct in6_addr), a 549 symbolic constant can be used to initialize an IPv6 address variable, 550 but cannot be used in an assignment. Therefore systems provide the 551 IPv6 wildcard address in two forms. 553 The first version is a global variable named "in6addr_any" that is an 554 in6_addr structure. The extern declaration for this variable is: 556 extern const struct in6_addr in6addr_any; 558 Applications use in6addr_any similarly to the way they use INADDR_ANY 559 in IPv4. For example, to bind a socket to port number 23, but let 560 the system select the source address, an application could use the 561 following code: 563 struct sockaddr_in6 sin6; 564 . . . 565 sin6.sin6_family = AF_INET6; 566 sin6.sin6_flowinfo = 0; 567 sin6.sin6_port = htons(23); 568 sin6.sin6_addr = in6addr_any; /* structure assignment */ 569 . . . 570 if (bind(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 571 . . . 573 The other version is a symbolic constant named IN6ADDR_ANY_INIT. 574 This constant can be used to initialize an in6_addr structure: 576 struct in6_addr anyaddr = IN6ADDR_ANY_INIT; 578 Note that this constant can be used ONLY at declaration type. It can 579 not be used to assign a previously declared in6_addr structure. For 580 example, the following code will not work: 582 /* This is the WRONG way to assign an unspecified address */ 583 struct sockaddr_in6 sin6; 584 . . . 585 sin6.sin6_addr = IN6ADDR_ANY_INIT; /* Will NOT compile */ 587 The extern declaration for in6addr_any and the declaration for 588 IN6ADDR_ANY_INIT are obtained by including the header . 590 Be aware that the IPv4 INADDR_xxx constants are all defined in host 591 byte order but the IPv6 IN6ADDR_xxx constants and the IPv6 592 in6addr_xxx externals are defined in network byte order. 594 3.10. IPv6 Loopback Address 596 Applications may need to send UDP packets to, or originate TCP 597 connections to, services residing on the local node. In IPv4, they 598 can do this by using the constant IPv4 address INADDR_LOOPBACK in 599 their connect(), sendto(), or sendmsg() call. 601 IPv6 also provides a loopback address to contact local TCP and UDP 602 services. Like the unspecified address, the IPv6 loopback address is 603 provided in two forms -- a global variable and a symbolic constant. 605 The global variable is an in6_addr structure named 606 "in6addr_loopback." The extern declaration for this variable is: 608 extern const struct in6_addr in6addr_loopback; 610 Applications use in6addr_loopback as they would use INADDR_LOOPBACK 611 in IPv4 applications (but beware of the byte ordering difference 612 mentioned at the end of the previous section). For example, to open 613 a TCP connection to the local telnet server, an application could use 614 the following code: 616 struct sockaddr_in6 sin6; 617 . . . 618 sin6.sin6_family = AF_INET6; 619 sin6.sin6_flowinfo = 0; 620 sin6.sin6_port = htons(23); 621 sin6.sin6_addr = in6addr_loopback; /* structure assignment */ 622 . . . 623 if (connect(s, (struct sockaddr *) &sin6, sizeof(sin6)) == -1) 624 . . . 626 The symbolic constant is named IN6ADDR_LOOPBACK_INIT. It can be used 627 at declaration time ONLY; for example: 629 struct in6_addr loopbackaddr = IN6ADDR_LOOPBACK_INIT; 631 Like IN6ADDR_ANY_INIT, this constant cannot be used in an assignment 632 to a previously declared IPv6 address variable. 634 The extern declaration for in6addr_loopback and the declaration for 635 IN6ADDR_LOOPBACK_INIT are obtained by including the header 636 . 638 4. Interface Identification 640 This API uses an interface index (a small positive integer) to 641 identify the local interface on which a multicast group is joined 642 (Section 5.3). Additionally, the advanced API [5] uses these same 643 interface indexes to identify the interface on which a datagram is 644 received, or to specify the interface on which a datagram is to be 645 sent. 647 Interfaces are normally known by names such as "le0", "sl1", "ppp2", 648 and the like. On Berkeley-derived implementations, when an interface 649 is made known to the system, the kernel assigns a unique positive 650 integer value (called the interface index) to that interface. These 651 are small positive integers that start at 1. (Note that 0 is never 652 used for an interface index.) There may be gaps so that there is no 653 current interface for a particular positive interface index. 655 This API defines two functions that map between an interface name and 656 index, and a third function that returns all the interface names and 657 indexes. How these three functions are implemented is left up to the 658 implementation. 4.4BSD implementations can implement all three 659 functions using the existing sysctl() function with the NET_RT_LIST 660 command. Other implementations may wish to use ioctl() for this 661 purpose. The function prototypes for these three functions, the 662 constant IF_MAXNAME, and the if_nameindex structure are defined as a 663 result of including the header. 665 4.1. Name-to-Index 667 The first function maps an interface names into its corresponding 668 index. 670 unsigned int if_nametoindex(const char *ifname); 672 If the specified interface does not exist, the return value is 0. 674 4.2. Index-to-Name 676 The second function maps an interface index into its corresponding 677 name. 679 char *if_indextoname(unsigned int ifindex, char *ifname); 681 The ifname argument must point to a buffer of at least IF_MAXNAME 682 bytes into which the interface name corresponding to the specified 683 index is returned. This pointer is also the return value of the 684 function. If there is no interface corresponding to the specified 685 index, NULL is returned and the buffer pointed to by ifname is not 686 modified. 688 4.3. Return All Interface Names and Indexes 690 The final function returns an array of if_nameindex structures, one 691 structure per interface. 693 struct if_nameindex { 694 unsigned int if_index; /* 1, 2, ... */ 695 char *if_name; /* null terminated name: "le0", ... */ 696 }; 698 struct if_nameindex *if_nameindex(void); 700 The end of the array of structures is indicated by a structure with 701 an if_index of 0 and an if_name of NULL. The memory used for this 702 array of structures along with the interface names pointed to by the 703 if_name members is obtained using one call to malloc() and can be 704 returned by calling free() with an argument that is the pointer 705 returned by if_nameindex(). 707 5. Socket Options 709 A number of new socket options are defined for IPv6. All of these 710 new options are at the IPPROTO_IPV6 level. That is, the "level" 711 parameter in the getsockopt() and setsockopt() calls is IPPROTO_IPV6 712 when using these options. The constant name prefix IPV6_ is used in 713 all of the new socket options. This serves to clearly identify these 714 options as applying to IPv6. 716 The declaration for IPPROTO_IPV6, the new IPv6 socket options, and 717 related constants defined in this section are obtained by including 718 the header . 720 5.1. Changing Socket Type 722 Unix allows open sockets to be passed between processes via the 723 exec() call and other means. It is a relatively common application 724 practice to pass open sockets across exec() calls. Thus it is 725 possible for an application using the original API to pass an open 726 PF_INET socket to an application that is expecting to receive a 727 PF_INET6 socket. Similarly, it is possible for an application using 728 the extended API to pass an open PF_INET6 socket to an application 729 using the original API, which would be equipped only to deal with 730 PF_INET sockets. Either of these cases could cause problems, because 731 the application that is passed the open socket might not know how to 732 decode the address structures returned in subsequent socket 733 functions. 735 To remedy this problem, a new setsockopt() option is defined that 736 allows an application to "convert" a PF_INET6 socket into a PF_INET 737 socket and vice versa. 739 An IPv6 application that is passed an open socket from an unknown 740 process may use the IPV6_ADDRFORM setsockopt() option to "convert" 741 the socket to PF_INET6. Once that has been done, the system will 742 return sockaddr_in6 address structures in subsequent socket 743 functions. 745 An IPv6 application that is about to pass an open PF_INET6 socket to 746 a program that is not be IPv6 capable can "downgrade" the socket to 747 PF_INET before calling exec(). After that, the system will return 748 sockaddr_in address structures to the application that was exec()'ed. 749 Be aware that you cannot downgrade an IPv6 socket to an IPv4 socket 750 unless all nonwildcard addresses already associated with the IPv6 751 socket are IPv4-mapped IPv6 addresses. 753 The IPV6_ADDRFORM option is valid at both the IPPROTO_IP and 754 IPPROTO_IPV6 levels. The only valid option values are PF_INET6 and 755 PF_INET. For example, to convert a PF_INET6 socket to PF_INET, a 756 program would call: 758 int addrform = PF_INET; 760 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDRFORM, 761 (char *) &addrform, sizeof(addrform)) == -1) 762 perror("setsockopt IPV6_ADDRFORM"); 764 An application may use IPV6_ADDRFORM with getsockopt() to learn 765 whether an open socket is a PF_INET of PF_INET6 socket. For example: 767 int addrform; 768 size_t len = sizeof(addrform); 770 if (getsockopt(s, IPPROTO_IPV6, IPV6_ADDRFORM, 771 (char *) &addrform, &len) == -1) 772 perror("getsockopt IPV6_ADDRFORM"); 773 else if (addrform == PF_INET) 774 printf("This is an IPv4 socket.\n"); 775 else if (addrform == PF_INET6) 776 printf("This is an IPv6 socket.\n"); 777 else 778 printf("This system is broken.\n"); 780 5.2. Unicast Hop Limit 782 A new setsockopt() option controls the hop limit used in outgoing 783 unicast IPv6 packets. The name of this option is IPV6_UNICAST_HOPS, 784 and it is used at the IPPROTO_IPV6 layer. The following example 785 illustrates how it is used: 787 int hoplimit = 10; 789 if (setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 790 (char *) &hoplimit, sizeof(hoplimit)) == -1) 791 perror("setsockopt IPV6_UNICAST_HOPS"); 793 When the IPV6_UNICAST_HOPS option is set with setsockopt(), the 794 option value given is used as the hop limit for all subsequent 795 unicast packets sent via that socket. If the option is not set, the 796 system selects a default value. 798 The IPV6_UNICAST_HOPS option may be used with getsockopt() to 799 determine the hop limit value that the system will use for subsequent 800 unicast packets sent via that socket. For example: 802 int hoplimit; 803 size_t len = sizeof(hoplimit); 805 if (getsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, 806 (char *) &hoplimit, &len) == -1) 807 perror("getsockopt IPV6_UNICAST_HOPS"); 808 else 809 printf("Using %d for hop limit.\n", hoplimit); 811 5.3. Sending and Receiving Multicast Packets 813 IPv6 applications may send UDP multicast packets by simply specifying 814 an IPv6 multicast address in the address argument of the sendto() 815 function. 817 Three socket options at the IPPROTO_IPV6 layer control some of the 818 parameters for sending multicast packets. Setting these options is 819 not required: applications may send multicast packets without using 820 these options. The setsockopt() options for controlling the sending 821 of multicast packets are summarized below: 823 IPV6_MULTICAST_IF 825 Set the interface to use for outgoing multicast packets. The 826 argument is the index of the interface to use. 828 Argument type: unsigned int 830 IPV6_MULTICAST_HOPS 832 Set the hop limit to use for outgoing multicast packets. 833 (Note a separate option - IPV6_UNICAST_HOPS - is provided to 834 set the hop limit to use for outgoing unicast packets.) 836 Argument type: unsigned int 838 IPV6_MULTICAST_LOOP 840 Controls whether outgoing multicast packets sent should be 841 delivered back to the local application. A toggle. If the 842 option is set to 1, multicast packets are looped back. If it 843 is set to 0, they are not. 845 Argument type: unsigned int 847 The reception of multicast packets is controlled by the two 848 setsockopt() options summarized below: 850 IPV6_ADD_MEMBERSHIP 852 Join a multicast group on a specified local interface. If 853 the interface index is specified as 0, the kernel chooses the 854 local interface by looking up the multicast group in the 855 normal IPv6 routing table and using the resulting interface. 857 Argument type: struct ipv6_mreq 859 IPV6_DROP_MEMBERSHIP 861 Leave a multicast group on a specified interface. 863 Argument type: struct ipv6_mreq 865 The argument type of both of these options is the ipv6_mreq 866 structure, defined as follows: 868 struct ipv6_mreq { 869 struct in6_addr ipv6mr_multiaddr; /* IPv6 multicast addr */ 870 unsigned int ipv6mr_interface; /* interface index */ 871 }; 873 Note that to receive multicast datagrams a process must join the 874 multicast group and bind the UDP port to which datagrams will be 875 sent. Some processes also bind the multicast group address to the 876 socket, in addition to the port, to prevent other datagrams destined 877 to that same port from being delivered to the socket. 879 6. Library Functions 881 New library functions are needed to perform a variety of operations 882 with IPv6 addresses. Functions are needed to lookup IPv6 addresses 883 in the Domain Name System (DNS). Both forward lookup (hostname-to- 884 address translation) and reverse lookup (address-to-hostname 885 translation) need to be supported. Functions are also needed to 886 convert IPv6 addresses between their binary and textual form. 888 6.1. Hostname-to-Address Translation 890 The commonly used function gethostbyname() remains unchanged as does 891 the hostent structure to which it returns a pointer. Existing 892 applications that call this function continue to receive only IPv4 893 addresses that are the result of a query in the DNS for A records. 894 (We assume the DNS is being used; some environments may be using a 895 hosts file or some other name resolution system, either of which may 896 impede renumbering.) 898 Two new changes are made to support IPv6 addresses. First the 899 following function is new: 901 struct hostent *gethostbyname2(const char *name, int af); 903 The af argument specifies the address family. The default operation 904 of this function is simple: 906 - If the af argument is AF_INET, then a query is made for A 907 records. If successful, IPv4 addresses are returned and the 908 h_length member of the hostent structure will be 4, else the 909 function returns a NULL pointer. 911 - If the af argument is AF_INET6, then a query is made for AAAA 912 records. If successful, IPv6 addresses are returned and the 913 h_length member of the hostent structure will be 16, else the 914 function returns a NULL pointer. 916 The second change, that provides additional functionality, is a new 917 resolver option RES_USE_INET6, which is defined as a result of 918 including the header. (This option is provided starting 919 with the BIND 4.9.4 release.) There are three ways to set this 920 option. 922 - The first way is 924 res_init(); 925 _res.options |= RES_USE_INET6; 927 and then call either gethostbyname() or gethostbyname2(). This 928 option then affects only the process that is calling the 929 resolver. 931 - The second way to set this option is to set the environment 932 variable RES_OPTIONS, as in RES_OPTIONS=inet6. This method 933 affects any processes that see this environment variable. 935 - The third way is to set this option in the resolver configuration 936 file (normally /etc/resolv.conf) and the option then affects all 937 applications on the host. This final method should not be done 938 until all applications on the host are capable of dealing with 939 IPv6 addresses. 941 When the RES_USE_INET6 option is set, two changes occur: 943 - gethostbyname(host) first calls gethostbyname2(host, AF_INET6) 944 looking for AAAA records, and if this fails it then calls 945 gethostbyname2(host, AF_INET) looking for A records. 947 - gethostbyname2(host, AF_INET) always returns IPv4-mapped IPv6 948 addresses with the h_length member of the hostent structure set 949 to 16. 951 An application must not enable the RES_USE_INET6 option until it is 952 prepared to deal with 16-byte addresses in the returned hostent 953 structure. 955 The following table summarizes the operation of the existing 956 gethostbyname() function, the new function gethostbyname2(), along 957 with the new resolver option RES_USE_INET6. 959 +------------------+---------------------------------------------------+ 960 | | RES_USE_INET6 option | 961 | +-------------------------+-------------------------+ 962 | | off | on | 963 +------------------+-------------------------+-------------------------+ 964 | |Search for A records. |Search for AAAA records. | 965 | gethostbyname | If found, return IPv4 | If found, return IPv6 | 966 | (host) | addresses (h_length=4). | addresses (h_length=16).| 967 | | Else error. | Else search for A | 968 | | | records. If found, | 969 | |Provides backward | return IPv4-mapped IPv6 | 970 | | compatibility with all | addresses (h_length=16).| 971 | | existing IPv4 appls. | Else error. | 972 +------------------+-------------------------+-------------------------+ 973 | |Search for A records. |Search for A records. | 974 | gethostbyname2 | If found, return IPv4 | If found, return | 975 | (host, AF_INET) | addresses (h_length=4). | IPv4-mapped IPv6 | 976 | | Else error. | addresses (h_length=16).| 977 | | | Else error. | 978 +------------------+-------------------------+-------------------------+ 979 | |Search for AAAA records. |Search for AAAA records. | 980 | gethostbyname2 | If found, return IPv6 | If found, return IPv6 | 981 | (host, AF_INET6) | addresses (h_length=16).| addresses (h_length=16).| 982 | | Else error. | Else error. | 983 +------------------+-------------------------+-------------------------+ 985 It is expected that when a typical naive application that calls 986 gethostbyname() today is modified to use IPv6, it simply changes the 987 program to use IPv6 sockets and then enables the RES_USE_INET6 988 resolver option before calling gethostbyname(). This application 989 will then work with either IPv4 or IPv6 peers. 991 Note that gethostbyname() and gethostbyname2() are not thread-safe, 992 since both return a pointer to a static hostent structure. But 993 several vendors have defined a thread-safe gethostbyname_r() function 994 that requires four additional arguments. We expect these vendors to 995 also define a gethostbyname2_r() function. 997 6.2. Address To Hostname Translation 999 The existing gethostbyaddr() function already requires an address 1000 family argument and can therefore work with IPv6 addresses: 1002 struct hostent *gethostbyaddr(const char *src, int len, int af); 1004 One possible source of confusion is the handling of IPv4-mapped IPv6 1005 addresses and IPv4-compatible IPv6 addresses. Current thinking 1006 involves the following logic: 1008 - If af is AF_INET6, and if len equals 16, and if the IPv6 address 1009 is an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 1010 address, then skip over the first 12 bytes of the IPv6 address, 1011 set af to AF_INET, and set len to 4. 1013 - If af is AF_INET, then query for a PTR record in the in-addr.arpa 1014 domain. 1016 - If af is AF_INET6, then query for a PTR record in the ip6.int 1017 domain. 1019 - If the function is returning success, and if af equals AF_INET, 1020 and if the RES_USE_INET6 option was set, then the single address 1021 that is returned in the hostent structure (a copy of the first 1022 argument to the function) is returned as an IPv4-mapped IPv6 1023 address and the h_length member is set to 16. 1025 The same caveats regarding a thread-safe version of gethostbyname() 1026 that were made at the end of the previous section apply here as well. 1028 6.3. Protocol-Independent Hostname and Service Name Translation 1030 Hostname-to-address translation is done in a protocol-independent 1031 fashion using the getaddrinfo() function that is taken from the 1032 Institute of Electrical and Electronic Engineers (IEEE) POSIX 1003.1g 1033 (Protocol Independent Interfaces) draft specification [4]. 1035 The official specification for this function will be the final POSIX 1036 standard. We are providing this independent description of the 1037 function because POSIX standards are not freely available (as are 1038 IETF documents). Should there be any discrepancies between this 1039 description and the POSIX description, the POSIX description takes 1040 precedence. 1042 #include 1043 #include 1045 int getaddrinfo(const char *hostname, const char *servname, 1046 const struct addrinfo *hints, 1047 struct addrinfo **res); 1049 The addrinfo structure is defined as: 1051 struct addrinfo { 1052 int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ 1053 int ai_family; /* PF_xxx */ 1054 int ai_socktype; /* SOCK_xxx */ 1055 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 1056 size_t ai_addrlen; /* length of ai_addr */ 1057 char *ai_canonname; /* canonical name for hostname */ 1058 struct sockaddr *ai_addr; /* binary address */ 1059 struct addrinfo *ai_next; /* next structure in linked list */ 1060 }; 1062 The return value from the function is 0 upon success or a nonzero 1063 error code. The following names are the nonzero error codes from 1064 getaddrinfo(): 1066 EAI_ADDRFAMILY address family for hostname not supported 1067 EAI_AGAIN temporary failure in name resolution 1068 EAI_BADFLAGS invalid value for ai_flags 1069 EAI_FAIL non-recoverable failure in name resolution 1070 EAI_FAMILY ai_family not supported 1071 EAI_MEMORY memory allocation failure 1072 EAI_NODATA no address associated with hostname 1073 EAI_NONAME hostname nor servname provided, or not known 1074 EAI_SERVICE servname not supported for ai_socktype 1075 EAI_SOCKTYPE ai_socktype not supported 1076 EAI_SYSTEM system error returned in errno 1078 The hostname and servname arguments are pointers to null-terminated 1079 strings or NULL. One or both of these two arguments must be a non- 1080 NULL pointer. In the normal client scenario, both the hostname and 1081 servname are specified. In the normal server scenario, only the 1082 servname is specified. A non-NULL hostname string can be either a 1083 host name or a numeric host address string (i.e., a dotted-decimal 1084 IPv4 address or an IPv6 hex address). A non-NULL servname string can 1085 be either a service name or a decimal port number. 1087 The caller can optionally pass an addrinfo structure, pointed to by 1088 the third argument, to provide hints concerning the type of socket 1089 that the caller supports. In this hints structure all members other 1090 than ai_flags, ai_family, ai_socktype, and ai_protocol must be zero 1091 or a NULL pointer. A value of PF_UNSPEC for ai_family means the 1092 caller will accept any protocol family. A value of 0 for ai_socktype 1093 means the caller will accept any socket type. A value of 0 for 1094 ai_protocol means the caller will accept any protocol. For example, 1095 if the caller handles only TCP and not UDP, then the ai_socktype 1096 member of the hints structure should be set to SOCK_STREAM when 1097 getaddrinfo() is called. If the caller handles only IPv4 and not 1098 IPv6, then the ai_family member of the hints structure should be set 1099 to PF_INET when getaddrinfo() is called. If the third argument to 1100 getaddrinfo() is a NULL pointer, this is the same as if the caller 1101 had filled in an addrinfo structure initialized to zero with 1102 ai_family set to PF_UNSPEC. 1104 Upon successful return a pointer to a linked list of one or more 1105 addrinfo structures is returned through the final argument. The 1106 caller can process each addrinfo structure in this list by following 1107 the ai_next pointer, until a NULL pointer is encountered. In each 1108 returned addrinfo structure the three members ai_family, ai_socktype, 1109 and ai_protocol are the corresponding arguments for a call to the 1110 socket() function. In each addrinfo structure the ai_addr member 1111 points to a filled-in socket address structure whose length is 1112 specified by the ai_addrlen member. 1114 If the AI_PASSIVE bit is set in the ai_flags member of the hints 1115 structure, then the caller plans to use the returned socket address 1116 structure in a call to bind(). In this case, if the hostname 1117 argument is a NULL pointer, then the IP address portion of the socket 1118 address structure will be set to INADDR_ANY for an IPv4 address or 1119 IN6ADDR_ANY_INIT for an IPv6 address. Notice that if the AI_PASSIVE 1120 bit is set and the hostname argument is a NULL pointer then the 1121 caller must also specify a nonzero ai_family, otherwise getaddrinfo() 1122 is unable to allocate and initialize a socket address structure of 1123 the correct type. 1125 If the AI_PASSIVE bit is not set in the ai_flags member of the hints 1126 structure, then the returned socket address structure will be ready 1127 for a call to connect() (for a connection-oriented protocol) or 1128 either connect(), sendto(), or sendmsg() (for a connectionless 1129 protocol). In this case, if the hostname argument is a NULL pointer, 1130 then the IP address portion of the socket address structure will be 1131 set to the loopback address. 1133 If the AI_CANONNAME bit is set in the ai_flags member of the hints 1134 structure, then upon successful return the ai_canonname member of the 1135 first addrinfo structure in the linked list will point to a null- 1136 terminated string containing the canonical name of the specified 1137 hostname. 1139 All of the information returned by getaddrinfo() is dynamically 1140 allocated: the addrinfo structures, and the socket address structures 1141 and canonical host name strings pointed to by the addrinfo 1142 structures. To return this information to the system the function 1143 freeaddrinfo() is called: 1145 #include 1146 #include 1148 void freeaddrinfo(struct addrinfo *ai); 1150 The addrinfo structure pointed to by the ai argument is freed, along 1151 with any dynamic storage pointed to by the structure. This operation 1152 is repeated until a NULL ai_next pointer is encountered. 1154 6.4. Socket Address Structure to Hostname and Service Name 1156 The POSIX 1003.1g specification includes no function to perform the 1157 reverse conversion from getaddrinfo(): to look up a hostname and 1158 service name, given the binary address and port. Therefore, we 1159 define the following function: 1161 #include 1162 #include 1164 int getnameinfo(const struct sockaddr *sa, size_t salen, 1165 char *host, size_t hostlen, 1166 char *serv, size_t servlen); 1168 This function looks up an IP address and port number provided by the 1169 caller in the DNS and system-specific database, and returns text 1170 strings for both in buffers provided by the caller. The first 1171 argument, sa, points to either a sockaddr_in structure (for IPv4) or 1172 a sockaddr_in6 structure (for IPv6) that holds the IP address and 1173 port number. The salen argument gives the length of the sockaddr_in 1174 or sockaddr_in6 structure. The function returns the hostname 1175 associated with the IP address in the buffer pointed to by the host 1176 argument. The caller provides the size of this buffer via the 1177 hostlen argument. The service name associated with the port number 1178 is returned in the buffer pointed to by serv, and the servlen 1179 argument gives the length of this buffer. The caller specifies not 1180 to return either string by providing a zero value for the hostlen or 1181 servlen arguments. Otherwise, the caller must provide buffers large 1182 enough to hold the fully qualified domain hostname, and the full 1183 service name, including the terminating null character. The function 1184 indicates successful completion by a zero return value; a non-zero 1185 return value indicates failure. 1187 Note that this function does not know the protocol of the socket 1188 address structure. Normally this is not a problem because the same 1189 port is assigned to a given service for both TCP and UDP. But there 1190 exist historical artifacts that violate this rule (e.g., ports 512, 1191 513, and 514). 1193 6.5. Address Conversion Functions 1195 The two functions inet_addr() and inet_ntoa() convert an IPv4 address 1196 between binary and text form. IPv6 applications need similar 1197 functions. The following two functions convert both IPv6 and IPv4 1198 addresses: 1200 int inet_pton(int af, const char *src, void *dst); 1202 and 1204 const char *inet_ntop(int af, const void *src, 1205 char *dst, size_t size); 1207 The inet_pton() function converts an address in its standard text 1208 presentation form into its numeric binary form. The af argument 1209 specifies the family of the address. Currently the AF_INET and 1210 AF_INET6 address families are supported. The src argument points to 1211 the string being passed in. The dst argument points to a buffer into 1212 which the function stores the numeric address. The address is 1213 returned in network byte order. Inet_pton() returns 1 if the 1214 conversion succeeds, 0 if the input is not a valid IPv4 dotted- 1215 decimal string or a valid IPv6 address string, or -1 with errno set 1216 to EAFNOSUPPORT if the af argument is unknown. The function does not 1217 modify the buffer pointed to by dst if the conversion fails. The 1218 calling application must ensure that the buffer referred to by dst is 1219 large enough to hold the numeric address (e.g., 4 bytes for AF_INET 1220 or 16 bytes for AF_INET6). 1222 If the af argument is AF_INET, the function accepts a string in the 1223 standard IPv4 dotted-decimal form: 1225 ddd.ddd.ddd.ddd 1227 where ddd is a one to three digit decimal number between 0 and 255. 1229 If the af argument is AF_INET6, then the function accepts a string in 1230 one of the standard IPv6 text forms defined in Section 2.2 of the 1231 addressing architecture specification [2]. 1233 The inet_ntop() function converts a numeric address into a text 1234 string suitable for presentation. The af argument specifies the 1235 family of the address. This can be AF_INET or AF_INET6. The src 1236 argument points to a buffer holding an IPv4 address if the af 1237 argument is AF_INET, or an IPv6 address if the af argument is 1238 AF_INET6. The dst argument points to a buffer where the function 1239 will store the resulting text string. The size argument specifies 1240 the size of this buffer. The application must specify a non-NULL dst 1241 argument. For IPv6 addresses, the buffer must be at least 46-octets. 1242 For IPv4 addresses, the buffer must be at least 16-octets. In order 1243 to allow applications to easily declare buffers of the proper size to 1244 store IPv4 and IPv6 addresses in string form, implementations should 1245 provide the following constants, made available to applications that 1246 include : 1248 #define INET_ADDRSTRLEN 16 1249 #define INET6_ADDRSTRLEN 46 1251 The inet_ntop() function returns a pointer to the buffer containing 1252 the text string if the conversion succeeds, and NULL otherwise. Upon 1253 failure, errno is set to EAFNOSUPPORT if the af argument is invalid 1254 or ENOSPC if the size of the result buffer is inadequate. The 1255 function does not modify the storage pointed to by dst if the 1256 conversion fails. 1258 Applications obtain the prototype declarations for inet_ntop() and 1259 inet_pton() by including the header . 1261 6.6. IPv4-Mapped Addresses 1263 The IPv4-mapped IPv6 address format represents IPv4 addresses as IPv6 1264 addresses. Most applications should be able to manipulate IPv6 1265 addresses as opaque 16-octet quantities, without needing to know 1266 whether they represent IPv4 addresses. However, a few applications 1267 may need to determine whether an IPv6 address is an IPv4-mapped 1268 address or not. The following function is provided for those 1269 applications: 1271 int inet6_isipv4mapped(const struct in6_addr *addr); 1273 The "addr" argument to this function points to a buffer holding an 1274 IPv6 address in network byte order. The function returns non-zero if 1275 that address is an IPv4-mapped address, and returns 0 otherwise. 1277 This function could be used by server applications to determine 1278 whether the peer is an IPv4 node or an IPv6 node. After accepting a 1279 TCP connection via accept(), or receiving a UDP packet via 1280 recvfrom(), the application can apply the inet6_isipv4mapped() 1281 function to the returned address. 1283 Applications obtain the prototype for this function by including the 1284 header . 1286 7. Security Considerations 1288 IPv6 provides a number of new security mechanisms, many of which need 1289 to be accessible to applications. A companion memo detailing the 1290 extensions to the socket interfaces to support IPv6 security is being 1291 written [3]. 1293 8. Change History 1295 Changes from the April 1996 Edition (-05 draft) 1297 - Rewrote Abstract. 1299 - Added Table of Contents. 1301 - New Section 2.2 (Data Types). 1303 - Removed the example from Section 3.4 (Socket Address Structure 1304 for 4.4BSD-Based Systems) implying that the process must set the 1305 sin6_len field. This field need not be set by the process before 1306 passing a socket address structure to the kernel: bind(), 1307 connect(), sendto(), and sendmsg(). 1309 - The examples in Section 3.8 (Flow Information) on setting and 1310 fetching the flow label and priority have been expanded, since 1311 the byte ordering and shifting required to set and fetch these 1312 fields can be confusing. It is also explicitly stated that the 1313 two IPV6_FLOWLABEL_xxx constants and the 16 IPV6_PRIORITY_xxx 1314 constants are all network byte ordered. 1316 - Warning placed at the end of Section 3.9 concerning the byte 1317 ordering of the IPv4 INADDR_xxx constants versus the IPv6 1318 IN6ADDR_xxx constants and in6addr_xxx externals. 1320 - Added a new Section 4 (Interface Identification). This provides 1321 functions to map between an interface name and an interface 1322 index. 1324 - In Section 5.1 (Changing Socket Type) the qualifier was added 1325 that you cannot downgrade an IPv6 socket to an IPv4 socket unless 1326 all nonwildcard addresses already associated with the IPv6 socket 1327 are IPv4-mapped IPv6 addresses. 1329 - In Section 5.3 (Sending and Receiving Multicast Packets) the 1330 method of specifying the local interface was changed from using a 1331 local IPv6 address to using the interface index. This changes 1332 the argument type for IPV6_MULTICAST_IF and the second member of 1333 the ipv6_mreq structure. 1335 - In Section 5.3 (Sending and Receiving Multicast Packets) the 1336 IPV6_ADD_MEMBERSHIP socket option description was corrected. A 1337 note was also added at the end of this section concerning joining 1338 the group versus binding the group address to the socket. 1340 - The old Sections 5.1, 5.2, and 5.3 are gone, and new Sections 1341 6.1, 6.2, 6.3, 6.4, and 6.5 are provided. The new sections 1342 describe the BIND 4.9.4 implementation of the name-to-address 1343 functions (which support IPv6), a POSIX-free description of the 1344 getaddrinfo() function, a description of the new getnameinfo() 1345 function, and the inet_ntop() and inet_pton() functions. The old 1346 Section 5.4 (Embedded IPv4 addresses) is now Section 6.6 (IPv4- 1347 Mapped Addresses). 1349 - Renamed inet6_isipv4addr() to inet6_isipv4mapped() so the name 1350 better describes the function. 1352 - Section 8 (Open Issues) was removed. 1354 Changes from the January 1996 Edition (-04 draft) 1356 - Re-arranged the ipv6_hostent_addr structure, placing the IPv6 1357 address element first. 1359 Changes from the November 1995 Edition (-03 draft) 1361 - Added the symbolic constants IN6ADDR_ANY_INIT and 1362 IN6ADDR_LOOPBACK_INIT for applications to use for 1363 initializations. 1365 - Eliminated restrictions on the value of ipv6addr_any. Systems 1366 may now choose any value, including all-zeros. 1368 - Added a mechanism for returning time to live with the address in 1369 the name-to-address translation functions. 1371 - Added a mechanism for applications to specify the interface in 1372 the setsockopt() options to join and leave a multicast group. 1374 Changes from the July 1995 Edition 1376 - Changed u_long and u_short types in structures to u_int32_t and 1377 u_int16_t for consistency and clarity. 1379 - Added implementation-provided constants for IPv4 and IPv6 text 1380 address buffer length. 1382 - Defined a set of constants for subfields of sin6_flowid and for 1383 priority values. 1385 - Defined constants for getting and setting the source route flag. 1387 - Define where ansi prototypes for hostname2addr(), 1388 addr2hostname(), addr2ascii(), ascii2addr(), and 1389 ipv6_isipv4addr() reside. 1391 - Clarified the include file requirements. Say that the structure 1392 definitions are defined as a result of including the header 1393 , not that the structures are necessarily defined 1394 there. 1396 - Removed underscore chars from is_ipv4_addr() function name for 1397 BSD compatibility. 1399 - Added inet6_ prefix to is_ipv4_addr() function name to avoid name 1400 space conflicts. 1402 - Changes setsockopt option naming convention to use IPV6_ prefix 1403 instead of IP_ so that there is clearly no ambiguity with IPv4 1404 options. Also, use level IPPROTO_IPV6 for these options. 1406 - Made hostname2addr() and addr2hostname() functions thread-safe. 1408 - Added support for sendmsg() and recvmsg() in source routing 1409 section. 1411 - Changed in_addr6 to in6_addr for consistency. 1413 - Re-structured document into sub-sections. 1415 - Deleted the implementation experience section. It was too wordy. 1417 - Added argument types to multicast socket options. 1419 - Added constant for largest source route array buffer. 1421 - Added the freehostent() function. 1423 - Added receiving interface determination and sending interface 1424 selection options. 1426 - Added definitions of ipv6addr_any and ipv6addr_loopback. 1428 - Added text making the lookup of IPv4 addresses by hostname2addr() 1429 optional. 1431 Changes from the June 1995 Edition 1433 - Added capability for application to select loose or strict source 1434 routing. 1436 Changes from the March 1995 Edition 1438 - Changed the definition of the ipv6_addr structure to be an array 1439 of sixteen chars instead of four longs. This change is necessary 1440 to support machines that implement the socket interface, but do 1441 not have a 32-bit addressable word. Virtually all machines that 1442 provide the socket interface do support an 8-bit addressable data 1443 type. 1445 - Added a more detailed explanation that the data types defined in 1446 this documented are not intended to be hard and fast 1447 requirements. Systems may use other data types if they wish. 1449 - Added a note flagging the fact that the sockaddr_in6 structure is 1450 not the same size as the sockaddr structure. 1452 - Changed the sin6_flowlabel field to sin6_flowinfo to accommodate 1453 the addition of the priority field to the IPv6 header. 1455 Changes from the October 1994 Edition 1457 - Added variant of sockaddr_in6 for 4.4BSD-based systems (sa_len 1458 compatibility). 1460 - Removed references to SIT transition specification, and added 1461 reference to addressing architecture document, for definition of 1462 IPv4-mapped addresses. 1464 - Added a solution to the problem of the application not providing 1465 enough buffer space to hold a received source route. 1467 - Moved discussion of IPv4 applications interoperating with IPv6 1468 nodes to open issues section. 1470 - Added length parameter to addr2ascii() function to be consistent 1471 with addr2hostname(). 1473 - Changed IP_MULTICAST_TTL to IP_MULTICAST_HOPS to match IPv6 1474 terminology, and added IP_UNICAST_HOPS option to match 1475 IP_MULTICAST_HOPS. 1477 - Removed specification of numeric values for AF_INET6, 1478 IP_ADDRFORM, and IP_RCVSRCRT, since they need not be the same on 1479 different implementations. 1481 - Added a definition for the in_addr6 IPv6 address data structure. 1482 Added this so that applications could use sizeof(struct in_addr6) 1483 to get the size of an IPv6 address, and so that a structured type 1484 could be used in the is_ipv4_addr(). 1486 9. Acknowledgments 1488 Thanks to the many people who made suggestions and provided feedback 1489 to to the numerous revisions of this document, including: Werner 1490 Almesberger, Ran Atkinson, Fred Baker, Dave Borman, Andrew Cherenson, 1491 Alex Conta, Alan Cox, Steve Deering, Francis Dupont, Robert Elz, Marc 1492 Hasson, Tom Herbert, Christian Huitema, Wan-Yen Hsu, Alan Lloyd, 1493 Charles Lynn, Dan McDonald, Craig Metz, Erik Nordmark, Josh Osborne, 1494 Craig Partridge, Matt Thomas, Dean D. Throop, Glenn Trewitt, Paul 1495 Vixie, David Waitzman, and Carl Williams. 1497 The getaddrinfo() and getnameinfo() functions are taken from an 1498 earlier Internet Draft by Keith Sklower. As noted in that draft, 1499 William Durst, Steven Wise, Michael Karels, and Eric Allman provided 1500 many useful discussions on the subject of protocol-independent name- 1501 to-address translation, and reviewed early versions of Keith 1502 Sklower's original proposal. Eric Allman implemented the first 1503 prototype of getaddrinfo(). The observation that specifying the pair 1504 of name and service would suffice for connecting to a service 1505 independent of protocol details was made by Marshall Rose in a 1506 proposal to X/Open for a "Uniform Network Interface". 1508 Ramesh Govindan made a number of contributions and co-authored an 1509 earlier version of this memo. 1511 10. References 1513 [1] S. Deering, R. Hinden, "Internet Protocol, Version 6 (IPv6) 1514 Specification", RFC 1883, December 1995. 1516 [2] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture", 1517 RFC 1884, December 1995. 1519 [3] D. McDonald, "A Simple IP Security API Extension to BSD Sockets", 1520 Internet-Draft, , 1521 November 1996. 1523 [4] IEEE, "Protocol Independent Interfaces", IEEE Std 1003.1g, DRAFT 1524 6.3, November 1995. 1526 [5] W. R. Stevens, M. Thomas, "Advanced Sockets API for IPv6", 1527 Internet-Draft, , October 1528 1996. 1530 11. Authors' Addresses 1532 Robert E. Gilligan 1533 Freegate Corporation 1534 710 Lakeway Dr. STE 230 1535 Sunnyvale, CA 94086 1536 Phone: +1 408 524 4804 1537 Email: gilligan@freegate.net 1539 Susan Thomson 1540 Bell Communications Research 1541 MRE 2P-343, 445 South Street 1542 Morristown, NJ 07960 1543 Telephone: +1 201 829 4514 1544 Email: set@thumper.bellcore.com 1546 Jim Bound 1547 Digital Equipment Corporation 1548 110 Spitbrook Road ZK3-3/U14 1549 Nashua, NH 03062-2698 1550 Phone: +1 603 881 0400 1551 Email: bound@zk3.dec.com 1553 W. Richard Stevens 1554 1202 E. Paseo del Zorro 1555 Tucson, AZ 85718-2826 1556 Phone: +1 520 297 9416 1557 Email: rstevens@kohala.com