BIND define this constant to be 256) and the second is a guess based
on the services listed in the current Assigned Numbers RFC.
The final argument is a flag that changes the default actions of this
function. By default the fully-qualified domain name (FQDN) for the
host is looked up in the DNS and returned. If the flag bit NI_NOFQDN
is set, only the hostname portion of the FQDN is returned for local
hosts.
If the flag bit NI_NUMERICHOST is set, or if the host's name cannot
be located in the DNS, the numeric form of the host's address is
returned instead of its name (e.g., by calling inet_ntop() instead of
gethostbyaddr()). If the flag bit NI_NAMEREQD is set, an error is
returned if the host's name cannot be located in the DNS.
If the flag bit NI_NUMERICSERV is set, the numeric form of the
service address is returned (e.g., its port number) instead of its
name. The two NI_NUMERICxxx flags are required to support the "-n"
flag that many commands provide.
A fifth flag bit, NI_DGRAM, specifies that the service is a datagram
service, and causes getservbyport() to be called with a second
argument of "udp" instead of its default of "tcp". This is required
for the few ports (512-514) that have different services for UDP and
TCP.
These NI_xxx flags are defined in <netdb.h> along with the AI_xxx
flags already defined for getaddrinfo().
6.5. Address Conversion Functions
The two functions inet_addr() and inet_ntoa() convert an IPv4 address
between binary and text form. IPv6 applications need similar
functions. The following two functions convert both IPv6 and IPv4
addresses:
#include <sys/socket.h>
#include <arpa/inet.h>
int inet_pton(int af, const char *src, void *dst);
const char *inet_ntop(int af, const void *src,
char *dst, size_t size);
The inet_pton() function converts an address in its standard text
presentation form into its numeric binary form. The af argument
specifies the family of the address. Currently the AF_INET and
AF_INET6 address families are supported. The src argument points to
the string being passed in. The dst argument points to a buffer into
which the function stores the numeric address. The address is
returned in network byte order. Inet_pton() returns 1 if the
conversion succeeds, 0 if the input is not a valid IPv4 dotted-
decimal string or a valid IPv6 address string, or -1 with errno set
to EAFNOSUPPORT if the af argument is unknown. The calling
application must ensure that the buffer referred to by dst is large
enough to hold the numeric address (e.g., 4 bytes for AF_INET or 16
bytes for AF_INET6).
If the af argument is AF_INET, the function accepts a string in the
standard IPv4 dotted-decimal form:
ddd.ddd.ddd.ddd
where ddd is a one to three digit decimal number between 0 and 255.
Note that many implementations of the existing inet_addr() and
inet_aton() functions accept nonstandard input: octal numbers,
hexadecimal numbers, and fewer than four numbers. inet_pton() does
not accept these formats.
If the af argument is AF_INET6, then the function accepts a string in
one of the standard IPv6 text forms defined in Section 2.2 of the
addressing architecture specification [2].
The inet_ntop() function converts a numeric address into a text
string suitable for presentation. The af argument specifies the
family of the address. This can be AF_INET or AF_INET6. The src
argument points to a buffer holding an IPv4 address if the af
argument is AF_INET, or an IPv6 address if the af argument is
AF_INET6. The dst argument points to a buffer where the function
will store the resulting text string. The size argument specifies
the size of this buffer. The application must specify a non-NULL dst
argument. For IPv6 addresses, the buffer must be at least 46-octets.
For IPv4 addresses, the buffer must be at least 16-octets. In order
to allow applications to easily declare buffers of the proper size to
store IPv4 and IPv6 addresses in string form, the following two
constants are defined in <netinet/in.h>:
#define INET_ADDRSTRLEN 16
#define INET6_ADDRSTRLEN 46
The inet_ntop() function returns a pointer to the buffer containing
the text string if the conversion succeeds, and NULL otherwise. Upon
failure, errno is set to EAFNOSUPPORT if the af argument is invalid
or ENOSPC if the size of the result buffer is inadequate.
6.6. Address Testing Macros
The following macros can be used to test for special IPv6 addresses.
#include <netinet/in.h>
int IN6_IS_ADDR_UNSPECIFIED (const struct in6_addr *);
int IN6_IS_ADDR_LOOPBACK (const struct in6_addr *);
int IN6_IS_ADDR_MULTICAST (const struct in6_addr *);
int IN6_IS_ADDR_LINKLOCAL (const struct in6_addr *);
int IN6_IS_ADDR_SITELOCAL (const struct in6_addr *);
int IN6_IS_ADDR_V4MAPPED (const struct in6_addr *);
int IN6_IS_ADDR_V4COMPAT (const struct in6_addr *);
int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *);
int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *);
int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *);
int IN6_IS_ADDR_MC_ORGLOCAL (const struct in6_addr *);
int IN6_IS_ADDR_MC_GLOBAL (const struct in6_addr *);
The first seven macros return true if the address is of the specified
type, or false otherwise. The last five test the scope of a
multicast address and return true if the address is a multicast
address of the specified scope or false if the address is either not
a multicast address or not of the specified scope.
7. Summary of New Definitions
The following list summarizes the constants, structure, and extern
definitions discussed in this memo, sorted by header.
<net/if.h> IFNAMSIZ
<net/if.h> struct if_nameindex{};
<netdb.h> AI_CANONNAME
<netdb.h> AI_PASSIVE
<netdb.h> EAI_ADDRFAMILY
<netdb.h> EAI_AGAIN
<netdb.h> EAI_BADFLAGS
<netdb.h> EAI_FAIL
<netdb.h> EAI_FAMILY
<netdb.h> EAI_MEMORY
<netdb.h> EAI_NODATA
<netdb.h> EAI_NONAME
<netdb.h> EAI_SERVICE
<netdb.h> EAI_SOCKTYPE
<netdb.h> EAI_SYSTEM
<netdb.h> NI_DGRAM
<netdb.h> NI_MAXHOST
<netdb.h> NI_MAXSERV
<netdb.h> NI_NAMEREQD
<netdb.h> NI_NOFQDN
<netdb.h> NI_NUMERICHOST
<netdb.h> NI_NUMERICSERV
<netdb.h> struct addrinfo{};
<netinet/in.h> IN6ADDR_ANY_INIT
<netinet/in.h> IN6ADDR_LOOPBACK_INIT
<netinet/in.h> INET6_ADDRSTRLEN
<netinet/in.h> INET_ADDRSTRLEN
<netinet/in.h> IPPROTO_IPV6
<netinet/in.h> IPV6_ADDRFORM
<netinet/in.h> IPV6_ADD_MEMBERSHIP
<netinet/in.h> IPV6_DROP_MEMBERSHIP
<netinet/in.h> IPV6_MULTICAST_HOPS
<netinet/in.h> IPV6_MULTICAST_IF
<netinet/in.h> IPV6_MULTICAST_LOOP
<netinet/in.h> IPV6_UNICAST_HOPS
<netinet/in.h> SIN6_LEN
<netinet/in.h> extern const struct in6_addr in6addr_any;
<netinet/in.h> extern const struct in6_addr in6addr_loopback;
<netinet/in.h> struct in6_addr{};
<netinet/in.h> struct ipv6_mreq{};
<netinet/in.h> struct sockaddr_in6{};
<resolv.h> RES_USE_INET6
<sys/socket.h> AF_INET6
<sys/socket.h> PF_INET6
The following list summarizes the function and macro prototypes
discussed in this memo, sorted by header.
<arpa/inet.h> int inet_pton(int, const char *, void *);
<arpa/inet.h> const char *inet_ntop(int, const void *,
char *, size_t);
<net/if.h> char *if_indextoname(unsigned int, char *);
<net/if.h> unsigned int if_nametoindex(const char *);
<net/if.h> void if_freenameindex(struct if_nameindex *);
<net/if.h> struct if_nameindex *if_nameindex(void);
<netdb.h> int getaddrinfo(const char *, const char *,
const struct addrinfo *,
struct addrinfo **);
<netdb.h> int getnameinfo(const struct sockaddr *, size_t,
char *, size_t, char *, size_t, int);
<netdb.h> void freeaddrinfo(struct addrinfo *);
<netdb.h> char *gai_strerror(int);
<netdb.h> struct hostent *gethostbyname(const char *);
<netdb.h> struct hostent *gethostbyaddr(const char *, int, int);
<netdb.h> struct hostent *gethostbyname2(const char *, int);
<netinet/in.h> int IN6_IS_ADDR_LINKLOCAL(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_LOOPBACK(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_MC_GLOBAL(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_MC_LINKLOCAL(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_MC_NODELOCAL(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_MC_ORGLOCAL(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_MC_SITELOCAL(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_MULTICAST(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_SITELOCAL(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_UNSPECIFIED(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_V4COMPAT(const struct in6_addr *);
<netinet/in.h> int IN6_IS_ADDR_V4MAPPED(const struct in6_addr *);
8. Security Considerations
IPv6 provides a number of new security mechanisms, many of which need
to be accessible to applications. A companion memo detailing the
extensions to the socket interfaces to support IPv6 security is being
written [3].
9. Acknowledgments
Thanks to the many people who made suggestions and provided feedback
to to the numerous revisions of this document, including: Werner
Almesberger, Ran Atkinson, Fred Baker, Dave Borman, Andrew Cherenson,
Alex Conta, Alan Cox, Steve Deering, Richard Draves, Francis Dupont,
Robert Elz, Marc Hasson, Tim Hartrick, Tom Herbert, Bob Hinden, Wan-
Yen Hsu, Christian Huitema, Koji Imada, Markus Jork, Ron Lee, Alan
Lloyd, Charles Lynn, Jack McCann, Dan McDonald, Dave Mitton, Thomas
Narten, Erik Nordmark, Josh Osborne, Craig Partridge, Jean-Luc
Richier, Erik Scoredos, Keith Sklower, Matt Thomas, Harvey Thompson,
Dean D. Throop, Karen Tracey, Glenn Trewitt, Paul Vixie, David
Waitzman, Carl Williams, and Kazuhiko Yamamoto,
The getaddrinfo() and getnameinfo() functions are taken from an
earlier Work in Progress by Keith Sklower. As noted in that
document, William Durst, Steven Wise, Michael Karels, and Eric Allman
provided many useful discussions on the subject of protocol-
independent name-to-address translation, and reviewed early versions
of Keith Sklower's original proposal. Eric Allman implemented the
first prototype of getaddrinfo(). The observation that specifying
the pair of name and service would suffice for connecting to a
service independent of protocol details was made by Marshall Rose in
a proposal to X/Open for a "Uniform Network Interface".
Craig Metz made many contributions to this document. Ramesh Govindan
made a number of contributions and co-authored an earlier version of
this memo.
10. References
[1] Deering, S., and R. Hinden, "Internet Protocol, Version 6 (IPv6)
Specification", RFC1883, December 1995.
[2] Hinden, R., and S. Deering, "IP Version 6 Addressing Architecture",
RFC1884, December 1995.
[3] McDonald, D., "A Simple IP Security API Extension to BSD Sockets",
Work in Progress.
[4] IEEE, "Protocol Independent Interfaces", IEEE Std 1003.1g, DRAFT
6.3, November 1995.
[5] Stevens, W., and M. Thomas, "Advanced Sockets API for IPv6",
Work in Progress.
[6] Vixie, P., "Reverse Name Lookups of Encapsulated IPv4 Addresses in
IPv6", Work in Progress.
11. Authors' Addresses
Robert E. Gilligan
Freegate Corporation
710 Lakeway Dr. STE 230
Sunnyvale, CA 94086
Phone: +1 408 524 4804
EMail: gilligan@freegate.net
Susan Thomson
Bell Communications Research
MRE 2P-343, 445 South Street
Morristown, NJ 07960
Phone: +1 201 829 4514
EMail: set@thumper.bellcore.com
Jim Bound
Digital Equipment Corporation
110 Spitbrook Road ZK3-3/U14
Nashua, NH 03062-2698
Phone: +1 603 881 0400
Email: bound@zk3.dec.com
W. Richard Stevens
1202 E. Paseo del Zorro
Tucson, AZ 85718-2826
Phone: +1 520 297 9416
EMail: rstevens@kohala.com