gethostbyname(2)                                       gethostbyname(2)

  gethostbyname()

  NAME

    gethostbyname(), gethostbyaddr(), gethostent(), sethostent(),
    endhostent(), herror() - get network host entry (and h_errno variable)

  SYNOPSIS

    #include 
    extern int h_errno;

    struct hostent *gethostbyname (const char *name)
    struct hostent *gethostbyaddr (const void *addr, int len, int type)
    struct hostent *gethostent (void)
    void sethostent (int stayopen)
    void endhostent (void)
    void herror (char *string)

  DESCRIPTION

    The gethostbyname(2) and gethostbyaddr(2) functions each return a pointer
    to an object with the following structure describing an Internet host
    referenced by name or by address, respectively.

    The gethostbyname(2) function searches for information on a host named
    name, and returns a pointer to a struct hostent.

    The gethostbyaddr(2) function searches for information about a host with
    the host address addr. The address is a string, in the dot-separated
    Internet Protocol (IP) format. The buffer specified by addr is len bytes
    in size. The type is the supported network type (always AF_INET in this
    implementation).

    The struct hostent structure contains the information obtained from the
    Winsock dynamic-link library (DLL) configuration on the local computer
    (regardless of how your Windows networking system is configured):

    struct hostent {
       char * h_name;       /* official name of host */
       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 */
    };

    For backwards compatibility, the address is also defined as:

    #define   h_addr  h_addr_list[0]

    The members of this structure are:

    h_name
        Official name of the host. Argument supplied for gethostbyname(2).

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

    h_addrtype
        The type of address being returned; currently always AF_INET.

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

    The calls gethostent(2), sethostent(2), and endhostent(2) search the hosts
    file (%WINDIR%/system32/drivers/etc/hosts) instead of the name server. The
    gethostent(2) function reads the next line of the hosts file, opening the
    file if necessary.

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

    The endhostent(2) function closes the file.

  RETURN VALUES

    Error return status from gethostbyname(2) and gethostbyaddr(2) is
    indicated by return of a null pointer. The external integer h_errno can
    then be checked to determine whether this is a temporary failure or an
    invalid or unknown host. The routine herror(3) can be used to print an
    error message describing the failure. If its argument string is non-NULL,
    string is printed, followed by a colon and a space. The error message is
    printed with a trailing newline.

    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 authoritative server. A retry at some
        later time might succeed.

    NO_RECOVERY
        Some unexpected server failure was encountered. This is a
        nonrecoverable 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 can be registered for this
        domain.

  NOTES

    The sockets mechanism in Interix is built around the Microsoft Winsock
    DLL. Configuring the network information for sockets depends upon your
    Winsock configuration; see the appropriate system documentation.

    These functions use static data storage; if the data is needed for future
    use, it should be copied before any subsequent calls overwrite it.
    Currently the functions only understand the Internet address format.

  SEE ALSO

    hosts(5)

    hostname(1)

  USAGE NOTES

    None of these functions are thread safe.

    None of these functions are async-signal safe.