Node:Host Names, Previous:Host Address Functions, Up:Host Addresses
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
.
struct hostent | Data Type |
This data type is used to represent an entry in the hosts database. It
has the following members:
|
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 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.
struct hostent * gethostbyname (const char *name) | Function |
The gethostbyname function returns information about the host
named name. If the lookup fails, it returns a null pointer.
|
struct hostent * gethostbyname2 (const char *name, int af) | Function |
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.
|
struct hostent * gethostbyaddr (const char *addr, size_t length, int format) | Function |
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, |
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
TRY_AGAIN
NO_RECOVERY
NO_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.
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) | Function |
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
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; } |
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) | Function |
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.
|
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) | Function |
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 |
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.
void sethostent (int stayopen) | Function |
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 |
struct hostent * gethostent (void) | Function |
This function returns the next entry in the hosts database. It returns a null pointer if there are no more entries. |
void endhostent (void) | Function |
This function closes the hosts database. |