Host Names (The GNU C Library) (2024)

Previous: Host Address Functions, Up: Host Addresses [Contents][Index]

16.6.2.4 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 asymbolic 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 mappingbetween host names and host numbers. This database is usually eitherthe file /etc/hosts or an equivalent provided by a name server.The functions and other symbols for accessing this database are declaredin netdb.h. They are BSD features, defined unconditionally ifyou include netdb.h.

Data Type: struct hostent ¶

This data type is used to represent an entry in the hosts database. Ithas 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-terminatedvector of strings.

int h_addrtype

This is the host address type; in practice, its value is always eitherAF_INET or AF_INET6, with the latter being used for IPv6hosts. In principle other kinds of addresses could be represented inthe database as well as Internet addresses; if this were done, youmight find a value in this field other than AF_INET orAF_INET6. See 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 hostmight be connected to multiple networks and have different addresses oneach 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 thefirst host address.

HOST_NOT_FOUND ¶: No such host is known in the database.
TRY_AGAIN ¶: This condition happens when the name server could not be contacted. Ifyou 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 anassociated Internet address.

The lookup functions above all have one thing in common: they are notreentrant and therefore unusable in multi-threaded applications.Therefore provides the GNU C Library a new set of functions which can beused 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) ¶

Preliminary:| MT-Safe env locale| AS-Unsafe dlopen plugin corrupt heap lock| AC-Unsafe lock corrupt mem fd| See POSIX Safety Concepts.

The gethostbyname_r function returns information about the hostnamed name. The caller must pass a pointer to an object of typestruct hostent in the result_buf parameter. In additionthe function may need extra buffer space and the caller must pass apointer and the size of the buffer in the buf and buflenparameters.

A pointer to the buffer, in which the result is stored, is available in*result after the function call successfully returned. Thebuffer passed as the buf parameter can be freed only once the callerhas finished with the result hostent struct, or has copied it including allthe other memory that it points to. If an error occurs or if no entry isfound, the pointer *result is a null pointer. Success issignalled by a zero return value. If the function failed the return valueis an error number. In addition to the errors defined forgethostbyname it can also be ERANGE. In this case the callshould be repeated with a larger buffer. Additional error information isnot stored in the global variable h_errno but instead in the objectpointed 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; hostbuf = malloc (sizeof (struct hostent)); hstbuflen = 1024; tmphstbuf = malloc (hstbuflen); while ((res = gethostbyname_r (host, hostbuf, tmphstbuf, hstbuflen, &hp, &herr)) == ERANGE) { /* Enlarge the buffer. */ tmphstbuf = reallocarray (tmphstbuf, hstbuflen, 2); hstbuflen *= 2; } free (tmphstbuf); /* 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) ¶

Preliminary:| MT-Safe env locale| AS-Unsafe dlopen plugin corrupt heap lock| AC-Unsafe lock corrupt mem fd| See POSIX Safety Concepts.

The gethostbyname2_r function is like gethostbyname_r, butallows the caller to specify the desired address family (e.g.AF_INET or AF_INET6) for the result.

Function: int gethostbyaddr_r (const void *addr, socklen_t length, int format, struct hostent *restrict result_buf, char *restrict buf, size_t buflen, struct hostent **restrict result, int *restrict h_errnop) ¶

Preliminary:| MT-Safe env locale| AS-Unsafe dlopen plugin corrupt heap lock| AC-Unsafe lock corrupt mem fd| See POSIX Safety Concepts.

The gethostbyaddr_r function returns information about the hostwith Internet address addr. The parameter addr is notreally a pointer to char - it can be a pointer to an IPv4 or an IPv6address. The length argument is the size (in bytes) of the addressat addr. format specifies the address format; for an IPv4Internet address, specify a value of AF_INET; for an IPv6Internet address, use AF_INET6.

Similar to the gethostbyname_r function, the caller must providebuffers for the result and memory used internally. In case of successthe function returns zero. Otherwise the value is an error number whereERANGE has the special meaning that the caller-provided buffer istoo small.

You can also scan the entire hosts database one entry at a time usingsethostent, gethostent and endhostent. Be carefulwhen using these functions because they are not reentrant.

Function: void sethostent (int stayopen) ¶

Preliminary:| MT-Unsafe race:hostent env locale| AS-Unsafe dlopen plugin heap lock| AC-Unsafe corrupt lock fd mem| See POSIX Safety Concepts.

This function opens the hosts database to begin scanning it. You canthen call gethostent to read the entries.

If the stayopen argument is nonzero, this sets a flag so thatsubsequent calls to gethostbyname or gethostbyaddr willnot close the database (as they usually would). This makes for moreefficiency if you call those functions several times, by avoidingreopening the database for each call.

Function: struct hostent * gethostent (void) ¶

Preliminary:| MT-Unsafe race:hostent race:hostentbuf env locale| AS-Unsafe dlopen plugin heap lock| AC-Unsafe corrupt lock fd mem| See POSIX Safety Concepts.

This function returns the next entry in the hosts database. Itreturns a null pointer if there are no more entries.

Function: void endhostent (void) ¶

Preliminary:| MT-Unsafe race:hostent env locale| AS-Unsafe dlopen plugin heap lock| AC-Unsafe corrupt lock fd mem| See POSIX Safety Concepts.

This function closes the hosts database.