endhostent(), gethostbyaddr(), gethostbyname(), gethostent(), sethostent()

manipulate network host database 

Function


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);


DESCRIPTION

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 7/2008R2/8/2012/10/2016/2019, the hosts file is in the drivers/etc directory under the 7/2008R2/8/2012/10/2016/2019 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


SEE ALSO

Functions:
_NutQueryWinNetFileDir(), endnetent(), endprotoent(), endservent(), getnetbyaddr(), getnetbyname(), getnetent(), getprotobyname(), getprotobynumber(), getprotoent(), getservbyname(), getservbyport(), getservent(), htonl(), inet_addr(), inet_ntoa(), ntohl(), setnetent(), setprotoent(), setservent()

Miscellaneous:
h_errno


PTC MKS Toolkit 10.2 Documentation Build 28.