User Tools

Site Tools


solaris:gethostbyname.3c

gethostbyname


NAME

gethostbyname, gethostbyname_r, gethostbyaddr, gethostbyaddr_r, gethostent, gethostent_r, sethostent, endhostent - get network host entry

SYNOPSIS

#include <netdb.h>

struct hostent *gethostbyname(const char *name);

struct hostent *gethostbyname_r(const char *name,
struct hostent
*result, char *buffer, int buflen,
int
*h_errnop);

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

struct hostent *gethostbyaddr_r(const char *addr, int length,
int
type, struct hostent *result, char *buffer,
int
buflen, int *h_errnop);

struct hostent *gethostent(void);

struct hostent *gethostent_r(struct hostent *result,
char
*buffer, int buflen, int *h_errnop);

int sethostent(int stayopen);

int endhostent(void);

DESCRIPTION

These functions are used to obtain entries describing hosts. An entry can come from any of the sources for hosts specified in the /etc/nsswitch.conf file. See nsswitch.conf(5). These functions have been superseded by getipnodebyname(3C), getipnodebyaddr(3C), and getaddrinfo(3C), which provide greater portability to applications when multithreading is performed or technologies such as IPv6 are used. For example, the functions described in the following cannot be used with applications targeted to work with IPv6.

The gethostbyname() function searches for information for a host with the hostname specified by the character-string parameter name.

The gethostbyaddr() function searches for information for a host with a given host address. The parameter type specifies the family of the address. This should be one of the address families defined in <sys/socket.h>. See the NOTES section for more information. Also see the EXAMPLES section for information on how to convert an Internet IP address notation that is separated by periods (.) into an addr parameter. The parameter len specifies the length of the buffer indicated by addr.

All addresses are returned in network order. In order to interpret the addresses, byteorder(3C) must be used for byte order conversion.

The sethostent(), gethostent(), and endhostent() functions are used to enumerate host entries from the database.

The sethostent() function sets or resets the enumeration to the beginning of the set of host entries. This function should be called before the first call to gethostent(). Calls to gethostbyname() and gethostbyaddr() leave the enumeration position in an indeterminate state. If the stayopen flag is non-zero, the system can keep allocated resources such as open file descriptors until a subsequent call to endhostent().

Successive calls to the gethostent() function return either successive entries or NULL, indicating the end of the enumeration.

The endhostent() function can be called to indicate that the caller expects to do no further host entry retrieval operations; the system can then deallocate resources it was using. It is still allowed, but possibly less efficient, for the process to call more host retrieval functions after calling endhostent().

Reentrant Interfaces
The gethostbyname(), gethostbyaddr(), and gethostent() functions use static storage that is reused in each call, making these functions unsafe for use in multithreaded applications.

The gethostbyname_r(), gethostbyaddr_r(), and gethostent_r() functions provide reentrant interfaces for these operations.

Each reentrant interface performs the same operation as its non-reentrant counterpart, named by removing the _r suffix. The reentrant interfaces, however, use buffers supplied by the caller to store returned results and the interfaces are safe for use in both single-threaded and multithreaded applications.

Each reentrant interface takes the same parameters as its non-reentrant counterpart, as well as the following additional parameters. The parameter result must be a pointer to a struct hostent structure allocated by the caller. On successful completion, the function returns the host entry in this structure. The parameter buffer must be a pointer to a buffer supplied by the caller. This buffer is used as storage space for the host data. All of the pointers within the returned struct hostent result point to data stored within this buffer. See the RETURN VALUES section for more information. The buffer must be large enough to hold all of the data associated with the host entry. The parameter buflen should give the size in bytes of the buffer indicated by buffer. The parameter h_errnop should be a pointer to an integer. An integer error status value is stored there on certain error conditions. See the ERRORS section for more information.

For enumeration in multithreaded applications, the position within the enumeration is a process-wide property shared by all threads. The sethostent() function can be used in a multithreaded application but resets the enumeration position for all threads. If multiple threads interleave calls to gethostent_r(), the threads will enumerate disjoint subsets of the host database.

Like their non-reentrant counterparts, gethostbyname_r() and gethostbyaddr_r() leave the enumeration position in an indeterminate state.

RETURN VALUES

Host entries are represented by the struct hostent structure defined in <netdb.h>:

struct hostent {
char *h_name; /* canonical name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
};

See the EXAMPLES section for information about how to retrieve a ’’.’’ separated Internet IP address string from the h_addr_list field of struct hostent.

The gethostbyname(), gethostbyname_r(), gethostbyaddr(), and gethostbyaddr_r() functions each return a pointer to a struct hostent if they successfully locate the requested entry; otherwise they return NULL.

The gethostent() and gethostent_r() functions each return a pointer to a struct hostent if they successfully enumerate an entry; otherwise they return NULL, indicating the end of the enumeration.

The gethostbyname(), gethostbyaddr(), and gethostent() functions use static storage, so returned data must be copied before a subsequent call to any of these functions if the data is to be saved.

When the pointer returned by the reentrant functions gethostbyname_r(), gethostbyaddr_r(), and gethostent_r() is not NULL, it is always equal to the result pointer that was supplied by the caller.

The sethostent() and endhostent() functions return 0 on success.

ERRORS

The reentrant functions gethostbyname_r(), gethostbyaddr_r(), and gethostent_r() will return NULL and set errno to ERANGE if the length of the buffer supplied by caller is not large enough to store the result. See Intro(2) for the proper usage and interpretation of errno in multithreaded applications.

The reentrant functions gethostbyname_r() and gethostbyaddr_r() set the integer pointed to by h_errnop to one of these values in case of error.

On failures, the non-reentrant functions gethostbyname() and gethostbyaddr() set a global integer h_errno to indicate one of these error codes (defined in <netdb.h>): HOST_NOT_FOUND, TRY_AGAIN, NO_RECOVERY, NO_DATA, and NO_ADDRESS.

If a resolver is provided with a malformed address, or if any other error occurs before gethostbyname() is resolved, then gethostbyname() returns an internal error with a value of −1.

The gethostbyname() function will set h_errno to NETDB_INTERNAL when it returns a NULL value.

EXAMPLES

Example 1 Using gethostbyaddr()

Here is a sample program that gets the canonical name, aliases, and ’’.’’ separated Internet IP addresses for a given ’’.’’ separated IP address:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <netdb.h>
int main(int argc, const char **argv)
{

in_addr_t addr;
struct hostent *hp;
char **p;
if (argc != 2) {
(void) printf(“usage: %s IP-address\n”, argv[0]);
exit (1);
}
if 1) == -1) {
(void) printf(“IP-address must be of the form a.b.c.d\n”);
exit (2);
}
1)
int)(addr = inet_addr(argv[1]
solaris/gethostbyname.3c.txt · Last modified: 2023/07/19 08:58 by A User Not Logged in