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:
|
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, gethostbyaddr returns a null pointer.
|
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
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
*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 a 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 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.
|
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 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.
|
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. |