Format
X/Open: #define _XOPEN_SOURCE_EXTENDED 1
#include <netdb.h>
extern int h_errno;
struct hostent *gethostbyaddr(const void *address, size_t len, int type);
Berkeley
sockets: #define _OE_SOCKETS
#include <netdb.h>
struct hostent *gethostbyaddr(char *address, int address_len, int domain);
General description
The gethostbyaddr()
call tries to resolve the host address through a name server, if one
is present. gethostbyaddr() searches the
local host tables until
a matching host address is found or an EOF marker is reached.
- Parameter
- Description
- address
- The pointer to a structure containing the address of the host.
(An unsigned long for AF_INET.)
- address_len
- The size of address in bytes.
- domain
- The address domain supported (AF_INET).
If you want gethostbyaddr() to bypass the name
server and instead resolve the host address using the local host tables,
you must define the RESOLVE_VIA_LOOKUP symbol before including any
sockets-related include files in your source program.
You can
use the
X_ADDR environment variable to specify different local
host tables and override those supplied by the
z/OS global
resolver during initialization.
The
gethostbyaddr() call returns a pointer to a hostent structure
for the host address specified on the call.
gethostent(), gethostbyaddr(),
and gethostbyname() all use the same static area to return the hostent structure.
This static area is only valid until the next one of these functions
is called on the same thread.
The
netdb.h include file
defines the
hostent structure and contains the following
elements:
- Element
- Description
- h_addr_list
- A pointer to a NULL-terminated list of host network addresses.
- h_addrtype
- The type of address returned; currently, it is always set to AF_INET.
- h_aliases
- A zero-terminated array of alternative names for the host.
- h_length
- The length of the address in bytes.
- h_name
- The official name of the host.
The following function (X/Open sockets only)
is defined in
netdb.h and should be used by multithreaded applications
when attempting to reference
h_errno return
on error:
int *__h_errno(void);
Also
use this function when you invoke gethostbyaddr() in a DLL.
This
function returns a pointer to a thread-specific value for the h_errno variable.
Special
behavior for C++: To
use this function with
C++, you
must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.
Note: The gethostbyaddr() and gethostbyname() functions
have been moved to obsolescence in Single UNIX Specification, Version 3 and may be withdrawn
in a future version. The getaddrinfo() and getnameinfo() functions
are preferred for portability.
Returned value
The return value points
to static data that is overwritten by subsequent calls. A pointer
to a hostent structure indicates success. A NULL
pointer indicates an error or End Of File (EOF).
If unsuccessful
in X/Open, gethostbyaddr() sets
h_errno to
indicate the error as follows:
- Error Code
- Description
- HOST_NOT_FOUND
- No such host is known.
- NO_DATA
- The server recognized the request and the name but no address
is available. Another type of request to the name server might return
an answer.
- NO_RECOVERY
- An unexpected server failure occurred from which there is no recovery.
- TRY_AGAIN
- A temporary error such as no response from a server, indicating
the information is not available now but may be at a later time.