endhostent(), gethostbyaddr(), gethostbyname(), gethostent(), sethostent() -- manipulate network host database

SYNOPSIS

#include <netdb.h>

extern int h_errno;

void endhostent();

struct hostent *gethostbyaddr(const char *addr, size_t len, int type);

struct hostent *gethostbyname(const char *name);

struct hostent *gethostent(void);

void sethostent(int stayopen);

The gethostent(), gethostbyaddr() and gethostbyname() functions each return a pointer to a hostent structure, the members of which contain the fields of an entry in the network host database, as follows:

h_name: Official name of the host (PC).
h_aliases: A null-terminated array of alternate names.
h_addrtype: The type of address being returned.
h_length: The length, in bytes, of each address.
h_addr_list: A null-terminated list of addresses for the host. Addresses are returned in network byte order.

The gethostent() function reads the next entry of the database, opening a connection to the database if necessary.

The gethostbyaddr() function searches the database and finds an entry which matches the specified address family and which matches the specified address, opening a connection to the database if necessary.

The gethostbyname() function searches the database and finds an entry which matches the specified host name, opening a connection to the database if necessary. If the specified name is an alias for a valid host, the function returns information about the host name to which the alias refers, and the specified name is included in the list of aliases returned.

The sethostent() function opens a connection to the network host database, and sets the position of the next entry to the first entry. If its parameter is non-zero, the connection to the database is not closed after each call to gethostent().

The endhostent() function closes the connection to the database.

PARAMETERS

addr: Points to the binary-format (that is, not null-terminated) address in network byte order. The data type of the address depends on the address family. For an address of type AF_INET, this is an in_addr structure.
len: Is the length of the address in bytes.
type: Is the type (address family) of the address.
name: Is the host name or alias for the host whose address is to be returned.
stayopen: When non-zero, the connection to the database is not closed after each call to gethostent().

RETURN VALUES

If successful, gethostbyaddr(), gethostbyname(), and gethostent() return a pointer to the hostent structure described in the DESCRIPTION section. On failure, they return a null pointer and set h_errno to one of the following values:

HOST_NOT_FOUND: No such host is known.
NO_DATA: No data record found for the specified address.
NO_RECOVERY: An unexpected server failure occurred; no recovery is possible.
TRY_AGAIN: A temporary and possibly transient error occurred, such as the failure of a server to respond.

For some failures, they return a null pointer and set errno to one of the following values:

EINTR: A signal interrupted the call.
ENETDOWN: The network subsystem was down.
EFAULT: addr is an invalid pointer.

The pointer that is returned points to a structure that is allocated by the NuTCRACKER Platform. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread; therefore, the application should copy any information it needs before issuing any other socket calls.

CONFORMANCE

UNIX 98, with exceptions.

MULTITHREAD SAFETY LEVEL

endhostent(), gethostent(), sethostent(): Unsafe.

gethostbyaddr(), gethostbyname(): MT-Safe.

PORTING ISSUES

On 8.1/2012R2/10/2016/2019/11/2022, the hosts file is in the drivers/etc directory under the 8.1/2012R2/10/2016/2019/11/2022 system directory. The _NutQueryWinNetFileDir() function returns the path where the network database files are located, regardless of platform.

Windows networking does not assign individual network names to physical network interfaces. Calling gethostbyname() or gethostbyaddr() does not necessarily return deterministic answers for a multi-homed Windows machine.

The gethostent() function searches only the hosts file, not the Domain Name Service (DNS) database, as DNS cannot be linearly traversed (this is true on UNIX platforms as well). Because Windows networking always uses DNS in preference to the hosts file, the gethostent() function is even less useful on Windows than it is on UNIX, where the host file is often searched before DNS.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

endhostent(), gethostbyaddr(), gethostbyname(), gethostent(), sethostent()
manipulate network host database

Function