svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
gethostent(3c)
gethostbyname(3C) Standard C Library Functions gethostbyname(3C)
NAME
gethostbyname, gethostbyname_r, gethostbyaddr, gethostbyaddr_r, gethos‐
tent, 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 the host database specified in the
nsswitch.conf(5) configuration. These functions have been superseded by
getaddrinfo(3C), which provides 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 ad‐
dress. 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 parame‐
ter. 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, ntohl(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 begin‐
ning of the set of host entries. This function should be called before
the first call to gethostent(). Calls to gethostbyname() and gethost‐
byaddr() 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 ex‐
pects to do no further host entry retrieval operations; the system can
then deallocate resources it was using. It is still allowed, but possi‐
bly less efficient, for the process to call more host retrieval func‐
tions after calling endhostent().
Reentrant Interfaces
The gethostbyname(), gethostbyaddr(), and gethostent() functions use
static storage that is reused in each call, making these functions un‐
safe 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-reen‐
trant counterpart, named by removing the _r suffix. The reentrant in‐
terfaces, 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 para‐
meter 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 ER‐
RORS 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 gethost‐
byaddr_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 gethost‐
byaddr_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 geth‐
ostent_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 multi‐
threaded 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 gethost‐
byaddr() 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 er‐
ror occurs before gethostbyname() is resolved, then gethostbyname() re‐
turns 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 ((int)(addr = inet_addr(argv[1])) == -1) {
(void) printf("IP-address must be of the form a.b.c.d\n");
exit (2);
}
hp = gethostbyaddr((char *)&addr, 4, AF_INET);
if (hp == NULL) {
(void) printf("host information for %s not found\n", argv[1]);
exit (3);
}
for (p = hp->h_addr_list; *p != 0; p++) {
struct in_addr in;
char **q;
(void) memcpy(&in.s_addr, *p, sizeof (in.s_addr));
(void) printf("%s %s", inet_ntoa(in), hp−>h_name);
for (q = hp->h_aliases; *q != 0; q++)
(void) printf(" %s", *q);
(void) putchar('\n');
}
exit (0);
}
Note that the preceding sample program is unsafe for use in multi‐
threaded applications.
FILES
/etc/netconfig network configuration database
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelT{ See Reentrant
Interfaces in the DESCRIPTION section. T}
SEE ALSO
Intro(2), getaddrinfo(3C), inet(3C), netdir(3C), ntohl(3C),
netdb.h(3HEAD), hosts(5), netconfig(5), nss(5), nsswitch.conf(5), at‐
tributes(7)
WARNINGS
The reentrant interfaces gethostbyname_r(), gethostbyaddr_r(), and
gethostent_r() are included in this release on an uncommitted basis
only and are subject to change or removal in future minor releases.
NOTES
To ensure that they all return consistent results, gethostbyname(),
gethostbyname_r(), and netdir_getbyname() are implemented in terms of
the same internal library function. This function obtains the system-
wide source lookup policy based on the inet family entries in netcon‐
fig(5) and the hosts: entry in nsswitch.conf(5). Similarly, gethost‐
byaddr(), gethostbyaddr_r(), and netdir_getbyaddr() are implemented in
terms of the same internal library function. If the inet family entries
in netconfig(5) have a '-' in the last column for nametoaddr libraries,
then the entry for hosts in nsswitch.conf will be used; nametoaddr li‐
braries in that column will be used, and nsswitch.conf will not be con‐
sulted.
There is no analogue of gethostent() and gethostent_r() in the netdir
functions, so these enumeration functions go straight to the hosts en‐
try in nsswitch.conf. Thus enumeration can return results from a dif‐
ferent source than that used by gethostbyname(), gethostbyname_r(),
gethostbyaddr(), and gethostbyaddr_r().
All the functions that return a struct hostent must always return the
canonical name in the h_name field. This name, by definition, is the
well-known and official hostname shared between all aliases and all ad‐
dresses. The underlying source that satisfies the request determines
the mapping of the input name or address into the set of names and ad‐
dresses in hostent. Different sources might do that in different ways.
If there is more than one alias and more than one address in hostent,
no pairing is implied between them.
By default, the system attempts to put those addresses that are on the
same subnet as the caller before addresses that are on different sub‐
nets. Alternative options are available. See nss(5) for more informa‐
tion.
Use of the enumeration interfaces gethostent() and gethostent_r() is
discouraged; enumeration might not be supported for all database
sources. The semantics of enumeration are discussed further in nss‐
witch.conf(5).
The current implementations of these functions only return or accept
addresses for the Internet address family (type AF_INET).
The form for an address of type AF_INET is a struct in_addr defined in
<netinet/in.h>. The functions described in inet(3C), and illustrated in
the EXAMPLES section, are helpful in constructing and manipulating ad‐
dresses in this form.
When the caller provides the IP address (the addr argument of gethost‐
byaddr() and gethostbyaddr_r()), the addr argument should be aligned on
a word boundary or the code must be changed to memcpy(3C) the argument
to an aligned area; otherwise an error such as a SIGBUS may result.
HISTORY
The reentrant interfaces gethostbyname_r(), gethostbyaddr_r(), and
gethostent_r() were added to Oracle Solaris in the Solaris 2.3 release.
The functions gethostbyname(), gethostbyaddr(), gethostent(), sethos‐
tent(), and addthostent() have been present since the initial release
of Solaris.
Oracle Solaris 11.4 6 Oct 2022 gethostbyname(3C)