rfc2133.txt

bind-3.2.

   If the AI_CANONNAME bit is set in the ai_flags member of the hints
   structure, then upon successful return the ai_canonname member of the
   first addrinfo structure in the linked list will point to a null-
   terminated string containing the canonical name of the specified
   hostname.




Gilligan, et. al.            Informational                     [Page 24]

RFC 2133            IPv6 Socket Interface Extensions          April 1997


   All of the information returned by getaddrinfo() is dynamically
   allocated: the addrinfo structures, and the socket address structures
   and canonical host name strings pointed to by the addrinfo
   structures.  To return this information to the system the function
   freeaddrinfo() is called:

       #include <sys/socket.h>
       #include <netdb.h>

       void freeaddrinfo(struct addrinfo *ai);

   The addrinfo structure pointed to by the ai argument is freed, along
   with any dynamic storage pointed to by the structure.  This operation
   is repeated until a NULL ai_next pointer is encountered.

   To aid applications in printing error messages based on the EAI_xxx
   codes returned by getaddrinfo(), the following function is defined.

       #include <sys/socket.h>
       #include <netdb.h>

       char *gai_strerror(int ecode);

   The argument is one of the EAI_xxx values defined earlier and the
   eturn value points to a string describing the error.  If the argument
   is not one of the EAI_xxx values, the function still returns a
   pointer to a string whose contents indicate an unknown error.

6.4.  Socket Address Structure to Hostname and Service Name

   The POSIX 1003.1g specification includes no function to perform the
   reverse conversion from getaddrinfo():  to look up a hostname and
   service name, given the binary address and port.  Therefore, we
   define the following function:

       #include <sys/socket.h>
       #include <netdb.h>

       int getnameinfo(const struct sockaddr *sa, size_t salen,
                       char *host, size_t hostlen,
                       char *serv, size_t servlen,
                       int flags);

   This function looks up an IP address and port number provided by the
   caller in the DNS and system-specific database, and returns text
   strings for both in buffers provided by the caller.  The function
   indicates successful completion by a zero return value; a non-zero
   return value indicates failure.



Gilligan, et. al.            Informational                     [Page 25]

RFC 2133            IPv6 Socket Interface Extensions          April 1997


   The first argument, sa, points to either a sockaddr_in structure (for
   IPv4) or a sockaddr_in6 structure (for IPv6) that holds the IP
   address and port number.  The salen argument gives the length of the
   sockaddr_in or sockaddr_in6 structure.

   The function returns the hostname associated with the IP address in
   the buffer pointed to by the host argument.  The caller provides the
   size of this buffer via the hostlen argument.  The service name
   associated with the port number is returned in the buffer pointed to
   by serv, and the servlen argument gives the length of this buffer.
   The caller specifies not to return either string by providing a zero
   value for the hostlen or servlen arguments.  Otherwise, the caller
   must provide buffers large enough to hold the hostname and the
   service name, including the terminating null characters.

   Unfortunately most systems do not provide constants that specify the
   maximum size of either a fully-qualified domain name or a service
   name.  Therefore to aid the application in allocating buffers for
   these two returned strings the following constants are defined in
   <netdb.h>:

       #define NI_MAXHOST  1025
       #define NI_MAXSERV    32

   The first value is actually defined as the constant MAXDNAME in
   recent versions of BIND's <arpa/nameser.h> header (older versions of
   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.






Gilligan, et. al.            Informational                     [Page 26]

RFC 2133            IPv6 Socket Interface Extensions          April 1997


   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.



Gilligan, et. al.            Informational                     [Page 27]

RFC 2133            IPv6 Socket Interface Extensions          April 1997


   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 *);






Gilligan, et. al.            Informational                     [Page 28]

RFC 2133            IPv6 Socket Interface Extensions          April 1997


   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



Gilligan, et. al.            Informational                     [Page 29]

RFC 2133            IPv6 Socket Interface Extensions          April 1997


     <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 *