GNU Info

(libc.info)Host Names

---

Prev: Host Address Functions Up: Host Addresses

---

Enter node , (file) or (file)node

Host Names
..........

   Besides the standard numbers-and-dots notation for Internet
addresses, you can also refer to a host by a symbolic name.  The
advantage of a symbolic name is that it is usually easier to remember.
For example, the machine with Internet address `158.121.106.19' is also
known as `alpha.gnu.org'; and other machines in the `gnu.org' domain
can refer to it simply as `alpha'.

   Internally, the system uses a database to keep track of the mapping
between host names and host numbers.  This database is usually either
the file `/etc/hosts' or an equivalent provided by a name server.  The
functions and other symbols for accessing this database are declared in
`netdb.h'.  They are BSD features, defined unconditionally if you
include `netdb.h'.

 - Data Type: struct hostent
     This data type is used to represent an entry in the hosts
     database.  It has the following members:

    `char *h_name'
          This is the "official" name of the host.

    `char **h_aliases'
          These are alternative names for the host, represented as a
          null-terminated vector of strings.

    `int h_addrtype'
          This is the host address type; in practice, its value is
          always either `AF_INET' or `AF_INET6', with the latter being
          used for IPv6 hosts.  In principle other kinds of addresses
          could be represented in the database as well as Internet
          addresses; if this were done, you might find a value in this
          field other than `AF_INET' or `AF_INET6'.  Note: Socket
          Addresses.

    `int h_length'
          This is the length, in bytes, of each address.

    `char **h_addr_list'
          This is the vector of addresses for the host.  (Recall that
          the host might be connected to multiple networks and have
          different addresses on each one.)  The vector is terminated
          by a null pointer.

    `char *h_addr'
          This is a synonym for `h_addr_list[0]'; in other words, it is
          the first host address.

   As far as the host database is concerned, each address is just a
block of memory `h_length' bytes long.  But in other contexts there is
an implicit assumption that you can convert IPv4 addresses to a `struct
in_addr' or an `uint32_t'.  Host addresses in a `struct hostent'
structure are always given in network byte order; see Note: Byte
Order.

   You can use `gethostbyname', `gethostbyname2' or `gethostbyaddr' to
search the hosts database for information about a particular host.  The
information is returned in a statically-allocated structure; you must
copy the information if you need to save it across calls.  You can also
use `getaddrinfo' and `getnameinfo' to obtain this information.

 - Function: struct hostent * gethostbyname (const char *NAME)
     The `gethostbyname' function returns information about the host
     named NAME.  If the lookup fails, it returns a null pointer.

 - Function: struct hostent * gethostbyname2 (const char *NAME, int AF)
     The `gethostbyname2' function is like `gethostbyname', but allows
     the caller to specify the desired address family (e.g.  `AF_INET'
     or `AF_INET6') of the result.

 - Function: struct hostent * gethostbyaddr (const char *ADDR, size_t
          LENGTH, int FORMAT)
     The `gethostbyaddr' function returns information about the host
     with Internet address ADDR.  The parameter ADDR is not really a
     pointer to char - it can be a pointer to an IPv4 or an IPv6
     address. The LENGTH argument is the size (in bytes) of the address
     at ADDR.  FORMAT specifies the address format; for an IPv4
     Internet address, specify a value of `AF_INET'; for an IPv6
     Internet address, use `AF_INET6'.

     If the lookup fails, `gethostbyaddr' returns a null pointer.

   If the name lookup by `gethostbyname' or `gethostbyaddr' fails, you
can find out the reason by looking at the value of the variable
`h_errno'.  (It would be cleaner design for these functions to set
`errno', but use of `h_errno' is compatible with other systems.)

   Here are the error codes that you may find in `h_errno':

`HOST_NOT_FOUND'
     No such host is known in the database.

`TRY_AGAIN'
     This condition happens when the name server could not be
     contacted.  If you try again later, you may succeed then.

`NO_RECOVERY'
     A non-recoverable error occurred.

`NO_ADDRESS'
     The host database contains an entry for the name, but it doesn't
     have an associated Internet address.

   The lookup functions above all have one in common: they are not
reentrant and therefore unusable in multi-threaded applications.
Therefore provides the GNU C library a new set of functions which can be
used in this context.

 - Function: int gethostbyname_r (const char *restrict NAME, struct
          hostent *restrict RESULT_BUF, char *restrict BUF, size_t
          BUFLEN, struct hostent **restrict RESULT, int *restrict
          H_ERRNOP)
     The `gethostbyname_r' function returns information about the host
     named NAME.  The caller must pass a pointer to an object of type
     `struct hostent' in the RESULT_BUF parameter.  In addition the
     function may need extra buffer space and the caller must pass an
     pointer and the size of the buffer in the BUF and BUFLEN
     parameters.

     A pointer to the buffer, in which the result is stored, is
     available in `*RESULT' after the function call successfully
     returned.  If an error occurs or if no entry is found, the pointer
     `*RESULT' is a null pointer.  Success is signalled by a zero
     return value.  If the function failed the return value is an error
     number.  In addition to the errors defined for `gethostbyname' it
     can also be `ERANGE'.  In this case the call should be repeated
     with a larger buffer.  Additional error information is not stored
     in the global variable `h_errno' but instead in the object pointed
     to by H_ERRNOP.

     Here's a small example:
          struct hostent *
          gethostname (char *host)
          {
            struct hostent hostbuf, *hp;
            size_t hstbuflen;
            char *tmphstbuf;
            int res;
            int herr;
          
            hstbuflen = 1024;
            /* Allocate buffer, remember to free it to avoid memory leakage.  */
            tmphstbuf = malloc (hstbuflen);
          
            while ((res = gethostbyname_r (host, &hostbuf, tmphstbuf, hstbuflen,
                                           &hp, &herr)) == ERANGE)
              {
                /* Enlarge the buffer.  */
                hstbuflen *= 2;
                tmphstbuf = realloc (tmphstbuf, hstbuflen);
              }
            /*  Check for errors.  */
            if (res || hp == NULL)
              return NULL;
            return hp;
          }

 - Function: int gethostbyname2_r (const char *NAME, int AF, struct
          hostent *restrict RESULT_BUF, char *restrict BUF, size_t
          BUFLEN, struct hostent **restrict RESULT, int *restrict
          H_ERRNOP)
     The `gethostbyname2_r' function is like `gethostbyname_r', but
     allows the caller to specify the desired address family (e.g.
     `AF_INET' or `AF_INET6') for the result.

 - Function: int gethostbyaddr_r (const char *ADDR, size_t LENGTH, int
          FORMAT, struct hostent *restrict RESULT_BUF, char *restrict
          BUF, size_t BUFLEN, struct hostent **restrict RESULT, int
          *restrict H_ERRNOP)
     The `gethostbyaddr_r' function returns information about the host
     with Internet address ADDR.  The parameter ADDR is not really a
     pointer to char - it can be a pointer to an IPv4 or an IPv6
     address. The LENGTH argument is the size (in bytes) of the address
     at ADDR.  FORMAT specifies the address format; for an IPv4
     Internet address, specify a value of `AF_INET'; for an IPv6
     Internet address, use `AF_INET6'.

     Similar to the `gethostbyname_r' function, the caller must provide
     buffers for the result and memory used internally.  In case of
     success the function returns zero.  Otherwise the value is an
     error number where `ERANGE' has the special meaning that the
     caller-provided buffer is too small.

   You can also scan the entire hosts database one entry at a time using
`sethostent', `gethostent' and `endhostent'.  Be careful when using
these functions because they are not reentrant.

 - Function: void sethostent (int STAYOPEN)
     This function opens the hosts database to begin scanning it.  You
     can then call `gethostent' to read the entries.

     If the STAYOPEN argument is nonzero, this sets a flag so that
     subsequent calls to `gethostbyname' or `gethostbyaddr' will not
     close the database (as they usually would).  This makes for more
     efficiency if you call those functions several times, by avoiding
     reopening the database for each call.

 - Function: struct hostent * gethostent (void)
     This function returns the next entry in the hosts database.  It
     returns a null pointer if there are no more entries.

 - Function: void endhostent (void)
     This function closes the hosts database.