tcpip-manpages.sgml

ecos实时嵌入式操作系统

             char    **h_aliases;    /* alias list */
             int     h_addrtype;     /* host address type */
             int     h_length;       /* length of address */
             char    **h_addr_list;  /* list of addresses from name server */
     };
     #define h_addr  h_addr_list[0]  /* address, for backward compatibility */

     The members of this structure are:

     h_name       Official name of the host.

     h_aliases    A zero-terminated array of alternate names for the host.

     h_addrtype   The type of address being returned.

     h_length     The length, in bytes, of the address.

     h_addr_list  A zero-terminated array of network addresses for the host.
                  Host addresses are returned in network byte order.

     h_addr       The first address in h_addr_list; this is for backward com-
                  patibility.

     The function gethostbyname() will search for the named host in the cur-
     rent domain and its parents using the search lookup semantics detailed in
     resolv.conf(5) and hostname(7).

     gethostbyname2() is an advanced form of gethostbyname() which allows
     lookups in address families other than AF_INET, for example AF_INET6.

     The gethostbyaddr() function will search for the specified address of
     length len in the address family af.  The only address family currently
     supported is AF_INET.

     The sethostent() function may be used to request the use of a connected
     TCP socket for queries.  If the stayopen flag is non-zero, this sets the
     option to send all queries to the name server using TCP and to retain the
     connection after each call to gethostbyname() or gethostbyaddr().  Other-
     wise, queries are performed using UDP datagrams.

     The endhostent() function closes the TCP connection.

     The herror() function prints an error message describing the failure.  If
     its argument string is non-null, it is prepended to the message string
     and separated from it by a colon (`:') and a space.  The error message is
     printed with a trailing newline.  The contents of the error message is
     the same as that returned by hstrerror() with argument h_errno.

FILES
     /etc/hosts
     /etc/resolv.conf

DIAGNOSTICS
     Error return status from gethostbyname(), gethostbyname2(), and
     gethostbyaddr() is indicated by return of a null pointer.  The external
     integer h_errno may then be checked to see whether this is a temporary
     failure or an invalid or unknown host.

     The variable h_errno can have the following values:

     HOST_NOT_FOUND  No such host is known.

     TRY_AGAIN       This is usually a temporary error and means that the
                     local server did not receive a response from an authori-
                     tative server.  A retry at some later time may succeed.

     NO_RECOVERY     Some unexpected server failure was encountered.  This is
                     a non-recoverable error.

     NO_DATA         The requested name is valid but does not have an IP
                     address; this is not a temporary error.  This means that
                     the name is known to the name server but there is no
                     address associated with this name.  Another type of
                     request to the name server using this domain name will
                     result in an answer; for example, a mail-forwarder may be
                     registered for this domain.

SEE ALSO
     resolver(3), getaddrinfo(3), getnameinfo(3), hosts(5), resolv.conf(5),
     hostname(7), named(8)

CAVEAT
     If the search routines in resolv.conf(5) decide to read the /etc/hosts
     file, gethostent() and other functions will read the next line of the
     file, re-opening the file if necessary.

     The sethostent() function opens and/or rewinds the file /etc/hosts.  If
     the stayopen argument is non-zero, the file will not be closed after each
     call to gethostbyname(), gethostbyname2(), or gethostbyaddr().

     The endhostent() function closes the file.

HISTORY
     The herror() function appeared in 4.3BSD.  The endhostent(),
     gethostbyaddr(), gethostbyname(), gethostent(), and sethostent() func-
     tions appeared in 4.2BSD.

BUGS
     These functions use static data storage; if the data is needed for future
     use, it should be copied before any subsequent calls overwrite it.  Only
     the Internet address formats are currently understood.

     YP does not support any address families other than AF_INET and uses the
     traditional database format.

BSD                             March 13, 1997                             BSD
    </screen>
  </sect1>

  <sect1 id="net-common-tcpip-manpages-getifaddrs">
    <title>getifaddrs</title>
    <screen>
GETIFADDRS(3)           System Library Functions Manual          GETIFADDRS(3)

NAME
     getifaddrs - get interface addresses

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>
     #include &lt;ifaddrs.h>

     int
     getifaddrs(struct ifaddrs **ifap);

     void
     freeifaddrs(struct ifaddrs *ifap);

DESCRIPTION
     The getifaddrs() function stores a reference to a linked list of the net-
     work interfaces on the local machine in the memory referenced by ifap.
     The list consists of ifaddrs structures, as defined in the include file
     &lt;ifaddrs.h>.  The ifaddrs structure contains at least the following
     entries:

         struct ifaddrs   *ifa_next;         /* Pointer to next struct */
         char             *ifa_name;         /* Interface name */
         u_int             ifa_flags;        /* Interface flags */
         struct sockaddr  *ifa_addr;         /* Interface address */
         struct sockaddr  *ifa_netmask;      /* Interface netmask */
         struct sockaddr  *ifa_broadaddr;    /* Interface broadcast address */
         struct sockaddr  *ifa_dstaddr;      /* P2P interface destination */
         void             *ifa_data;         /* Address specific data */

     ifa_next
             Contains a pointer to the next structure on the list.  This field
             is set to NULL in last structure on the list.

     ifa_name
             Contains the interface name.

     ifa_flags
             Contains the interface flags, as set by ifconfig(8).

     ifa_addr
             References either the address of the interface or the link level
             address of the interface, if one exists, otherwise it is NULL.
             (The sa_family field of the ifa_addr field should be consulted to
             determine the format of the ifa_addr address.)

     ifa_netmask
             References the netmask associated with ifa_addr, if one is set,
             otherwise it is NULL.

     ifa_broadaddr
             This field, which should only be referenced for non-P2P inter-
             faces, references the broadcast address associated with ifa_addr,
             if one exists, otherwise it is NULL.

     ifa_dstaddr
             References the destination address on a P2P interface, if one
             exists, otherwise it is NULL.

     ifa_data
             References address family specific data.  For AF_LINK addresses
             it contains a pointer to the struct if_data (as defined in
             include file &lt;net/if.h>) which contains various interface
             attributes and statistics.  For all other address families, it
             contains a pointer to the struct ifa_data (as defined in include
             file &lt;net/if.h>) which contains per-address interface statistics.

     The data returned by getifaddrs() is dynamically allocated and should be
     freed using freeifaddrs() when no longer needed.

RETURN VALUES
     Upon successful completion, a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.

ERRORS
     The getifaddrs() may fail and set errno for any of the errors specified
     for the library routines ioctl(2), socket(2), malloc(3), or sysctl(3).

BUGS
     If both &lt;net/if.h> and &lt;ifaddrs.h> are being included, &lt;net/if.h> must be
     included before &lt;ifaddrs.h>.

SEE ALSO
     ioctl(2), socket(2), sysctl(3), networking(4), ifconfig(8)

HISTORY
     The getifaddrs() function first appeared in BSDI BSD/OS.  The function is
     supplied on OpenBSD since OpenBSD 2.7.

BSD                            February 24, 2003                           BSD
    </screen>
  </sect1>

  <sect1 id="net-common-tcpip-manpages-getnameinfo">
    <title>getnameinfo</title>
    <screen>
GETNAMEINFO(3)          System Library Functions Manual         GETNAMEINFO(3)

NAME
     getnameinfo - address-to-nodename translation in protocol-independent
     manner

SYNOPSIS
     #include &lt;sys/types.h>
     #include &lt;sys/socket.h>
     #include &lt;netdb.h>

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

DESCRIPTION
     The getnameinfo() function is defined for protocol-independent address-
     to-nodename translation.  Its functionality is a reverse conversion of
     getaddrinfo(3), and implements similar functionality with
     gethostbyaddr(3) and getservbyport(3) in more sophisticated manner.

     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 suc-
     cessful completion by a zero return value; a non-zero return value indi-
     cates failure.

     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 nodename 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 nodename and the service name, including the terminat-
     ing null characters.

     Unfortunately most systems do not provide constants that specify the max-
     imum 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 &lt;netdb.h>:

     #define NI_MAXHOST    MAXHOSTNAMELEN
     #define NI_MAXSERV    32

     The first value is actually defined as the constant MAXDNAME in recent
     versions of BIND's &lt;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 nodename 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 com-
     mands provide.

     A fifth flag bit, NI_DGRAM, specifies that the service is a datagram ser-
     vice, 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 &lt;netdb.h>.

   Extension for scoped IPv6 address
     The implementation allows experimental numeric IPv6 address notation with
     scope identifier.  IPv6 link-local address will appear as string like
     ``fe80::1%ne0'', if NI_WITHSCOPEID bit is enabled in flags argument.
     Refer to getaddrinfo(3) for the notation.

EXAMPLES
     The following code tries to get numeric hostname, and service name, for
     given socket address.  Observe that there is no hardcoded reference to
     particular address family.

           struct sockaddr *sa;    /* input */
           char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];

           if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
               sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
                   errx(1, "could not get numeric hostname");
                   /*NOTREACHED*/
           }
           printf("host=%s, serv=%s\n", hbuf, sbuf);

     The following version checks if the socket address has reverse address
     mapping.

           struct sockaddr *sa;    /* input */
           char hbuf[NI_MAXHOST];

           if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
               NI_NAMEREQD)) {
                   errx(1, "could not resolve hostname");
                   /*NOTREACHED*/
           }
           printf("host=%s\n", hbuf);

DIAGNOSTICS
     The function indicates successful completion by a zero return value; a
     non-zero return value indicates failure.  Error codes are as below:

     EAI_AGAIN          The name could not be resolved at this time.  Future
                        attempts may succeed.

     EAI_BADFLAGS       The flags had an invalid value.

     EAI_FAIL           A non-recoverable error occurred.

     EAI_FAMILY         The address family was not recognized or the address
                        length was invalid for the specified family.