rfc2553.txt

RFC 的详细文档！

        For example, if the node has no IPv6 source addresses
        configured, and af equals AF_INET6, and the node name being
        looked up has both AAAA and A records, then:

            (a) if only AI_ADDRCONFIG is specified, the function
                returns a NULL pointer;
            (b) if AI_ADDRCONFIG | AI_V4MAPPED is specified, the A
                records are returned as IPv4-mapped IPv6 addresses;




Gilligan, et. al.            Informational                     [Page 23]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


   The special flags value of AI_DEFAULT is defined as

      #define  AI_DEFAULT  (AI_V4MAPPED | AI_ADDRCONFIG)

   We noted that the getipnodebyname() function must allow the name
   argument to be either a node name or a literal address string (i.e.,
   a dotted-decimal IPv4 address or an IPv6 hex address).  This saves
   applications from having to call inet_pton() to handle literal
   address strings.

   There are four scenarios based on the type of literal address string
   and the value of the af argument.

   The two simple cases are:

   When name is a dotted-decimal IPv4 address and af equals AF_INET, or
   when name is an IPv6 hex address and af equals AF_INET6.  The members
   of the returned hostent structure are: h_name points to a copy of the
   name argument, h_aliases is a NULL pointer, h_addrtype is a copy of
   the af argument, h_length is either 4 (for AF_INET) or 16 (for
   AF_INET6), h_addr_list[0] is a pointer to the 4-byte or 16-byte
   binary address, and h_addr_list[1] is a NULL pointer.

   When name is a dotted-decimal IPv4 address and af equals AF_INET6,
   and flags equals AI_V4MAPPED, an IPv4-mapped IPv6 address is
   returned:  h_name points to an IPv6 hex address containing the IPv4-
   mapped IPv6 address, h_aliases is a NULL pointer, h_addrtype is
   AF_INET6, h_length is 16, h_addr_list[0] is a pointer to the 16-byte
   binary address, and h_addr_list[1] is a NULL pointer.  If AI_V4MAPPED
   is set (with or without AI_ALL) return IPv4-mapped otherwise return
   NULL.

   It is an error when name is an IPv6 hex address and af equals
   AF_INET.  The function's return value is a NULL pointer and error_num
   equals HOST_NOT_FOUND.

6.2 Address-To-Nodename Translation

   The following function has the same arguments as the existing
   gethostbyaddr() function, but adds an error number.

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

      struct hostent *getipnodebyaddr(const void *src, size_t len,
                                          int af, int *error_num);






Gilligan, et. al.            Informational                     [Page 24]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


   As with getipnodebyname(), getipnodebyaddr() must be thread safe.
   The error_num value is returned to the caller with the appropriate
   error code, to support thread safe error code returns.  The following
   error conditions may be returned for error_num:

      HOST_NOT_FOUND

         No such host is known.

      NO_ADDRESS

         The server recognized the request and the name but no address
         is available.  Another type of request to the name server for
         the domain might return an answer.

      NO_RECOVERY

         An unexpected server failure occurred which cannot be
         recovered.

      TRY_AGAIN

         A temporary and possibly transient error occurred, such as a
         failure of a server to respond.

   One possible source of confusion is the handling of IPv4-mapped IPv6
   addresses and IPv4-compatible IPv6 addresses, but the following logic
   should apply.

      1.  If af is AF_INET6, and if len equals 16, and if the IPv6
          address is an IPv4-mapped IPv6 address or an IPv4-compatible
          IPv6 address, then skip over the first 12 bytes of the IPv6
          address, set af to AF_INET, and set len to 4.

      2.  If af is AF_INET, lookup the name for the given IPv4 address
          (e.g., query for a PTR record in the in-addr.arpa domain).

      3.  If af is AF_INET6, lookup the name for the given IPv6 address
          (e.g., query for a PTR record in the ip6.int domain).

      4.  If the function is returning success, then the single address
          that is returned in the hostent structure is a copy of the
          first argument to the function with the same address family
          that was passed as an argument to this function.







Gilligan, et. al.            Informational                     [Page 25]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


   All four steps listed are performed, in order.  Also note that the
   IPv6 hex addresses "::" and "::1" MUST NOT be treated as IPv4-
   compatible addresses, and if the address is "::", HOST_NOT_FOUND MUST
   be returned and a query of the address not performed.

   Also for the macro in section 6.7 IN6_IS_ADDR_V4COMPAT MUST return
   false for "::" and "::1".

6.3 Freeing memory for getipnodebyname and getipnodebyaddr

   The hostent structure does not change from its existing definition.
   This structure, and the information pointed to by this structure, are
   dynamically allocated by getipnodebyname and getipnodebyaddr.  The
   following function frees this memory:

      #include <netdb.h>

      void freehostent(struct hostent *ptr);

6.4 Protocol-Independent Nodename and Service Name Translation

   Nodename-to-address translation is done in a protocol-independent
   fashion using the getaddrinfo() function that is taken from the
   Institute of Electrical and Electronic Engineers (IEEE) POSIX 1003.1g
   (Protocol Independent Interfaces) draft specification [3].

   The official specification for this function will be the final POSIX
   standard, with the following additional requirements:

      -  getaddrinfo() (along with the getnameinfo() function described
         in the next section) must be thread safe.

      -  The AI_NUMERICHOST is new with this document.

      -  All fields in socket address structures returned by
         getaddrinfo() that are not filled in through an explicit
         argument (e.g., sin6_flowinfo and sin_zero) must be set to 0.
         (This makes it easier to compare socket address structures.)

      -  getaddrinfo() must fill in the length field of a socket address
         structure (e.g., sin6_len) on systems that support this field.

   We are providing this independent description of the function because
   POSIX standards are not freely available (as are IETF documents).

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




Gilligan, et. al.            Informational                     [Page 26]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


      int getaddrinfo(const char *nodename, const char *servname,
                      const struct addrinfo *hints,
                      struct addrinfo **res);

   The addrinfo structure is defined as a result of including the
   <netdb.h> header.

  struct addrinfo {
    int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
    int     ai_family;    /* PF_xxx */
    int     ai_socktype;  /* SOCK_xxx */
    int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
    size_t  ai_addrlen;   /* length of ai_addr */
    char   *ai_canonname; /* canonical name for nodename */
    struct sockaddr  *ai_addr; /* binary address */
    struct addrinfo  *ai_next; /* next structure in linked list */
  };

   The return value from the function is 0 upon success or a nonzero
   error code.  The following names are the nonzero error codes from
   getaddrinfo(), and are defined in <netdb.h>:

      EAI_ADDRFAMILY  address family for nodename not supported
      EAI_AGAIN       temporary failure in name resolution
      EAI_BADFLAGS    invalid value for ai_flags
      EAI_FAIL        non-recoverable failure in name resolution
      EAI_FAMILY      ai_family not supported
      EAI_MEMORY      memory allocation failure
      EAI_NODATA      no address associated with nodename
      EAI_NONAME      nodename nor servname provided, or not known
      EAI_SERVICE     servname not supported for ai_socktype
      EAI_SOCKTYPE    ai_socktype not supported
      EAI_SYSTEM      system error returned in errno

   The nodename and servname arguments are pointers to null-terminated
   strings or NULL.  One or both of these two arguments must be a non-
   NULL pointer.  In the normal client scenario, both the nodename and
   servname are specified.  In the normal server scenario, only the
   servname is specified.  A non-NULL nodename string can be either a
   node name or a numeric host address string (i.e., a dotted-decimal
   IPv4 address or an IPv6 hex address).  A non-NULL servname string can
   be either a service name or a decimal port number.

   The caller can optionally pass an addrinfo structure, pointed to by
   the third argument, to provide hints concerning the type of socket
   that the caller supports.  In this hints structure all members other
   than ai_flags, ai_family, ai_socktype, and ai_protocol must be zero
   or a NULL pointer.  A value of PF_UNSPEC for ai_family means the



Gilligan, et. al.            Informational                     [Page 27]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


   caller will accept any protocol family.  A value of 0 for ai_socktype
   means the caller will accept any socket type.  A value of 0 for
   ai_protocol means the caller will accept any protocol.  For example,
   if the caller handles only TCP and not UDP, then the ai_socktype
   member of the hints structure should be set to SOCK_STREAM when
   getaddrinfo() is called.  If the caller handles only IPv4 and not
   IPv6, then the ai_family member of the hints structure should be set
   to PF_INET when getaddrinfo() is called.  If the third argument to
   getaddrinfo() is a NULL pointer, this is the same as if the caller
   had filled in an addrinfo structure initialized to zero with
   ai_family set to PF_UNSPEC.

   Upon successful return a pointer to a linked list of one or more
   addrinfo structures is returned through the final argument.  The
   caller can process each addrinfo structure in this list by following
   the ai_next pointer, until a NULL pointer is encountered.  In each
   returned addrinfo structure the three members ai_family, ai_socktype,
   and ai_protocol are the corresponding arguments for a call to the
   socket() function.  In each addrinfo structure the ai_addr member
   points to a filled-in socket address structure whose length is
   specified by the ai_addrlen member.

   If the AI_PASSIVE bit is set in the ai_flags member of the hints
   structure, then the caller plans to use the returned socket address
   structure in a call to bind().  In this case, if the nodename
   argument is a NULL pointer, then the IP address portion of the socket
   address structure will be set to INADDR_ANY for an IPv4 address or
   IN6ADDR_ANY_INIT for an IPv6 address.

   If the AI_PASSIVE bit is not set in the ai_flags member of the hints
   structure, then the returned socket address structure will be ready
   for a call to connect() (for a connection-oriented protocol) or
   either connect(), sendto(), or sendmsg() (for a connectionless
   protocol).  In this case, if the nodename argument is a NULL pointer,
   then the IP address portion of the socket address structure will be
   set to the loopback address.

   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
   nodename.

   If the AI_NUMERICHOST bit is set in the ai_flags member of the hints
   structure, then a non-NULL nodename string must be a numeric host
   address string.  Otherwise an error of EAI_NONAME is returned.  This
   flag prevents any type of name resolution service (e.g., the DNS)
   from being called.



Gilligan, et. al.            Informational                     [Page 28]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


   All of the information returned by getaddrinfo() is dynamically
   allocated: the addrinfo structures, and the socket address structures
   and canonical node 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(