svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
getipnodebyname(3c)
Standard C Library Functions getipnodebyname(3C)
NAME
getipnodebyname, getipnodebyaddr, freehostent - get IP node entry
SYNOPSIS
#include <sys/socket.h>
#include <netdb.h>
struct hostent *getipnodebyname(const char *name, int af,
int flags, int *error_num);
struct hostent *getipnodebyaddr(const void *src, size_t len,
int af, int *error_num);
void freehostent(struct hostent *ptr);
PARAMETERS
af Address family
flags Various flags
name Name of host
error_num Error storage
src Address for lookup
len Length of address
ptr Pointer to hostent structure
DESCRIPTION
These functions provide a rudimentary lookup by name or address of
entries in the hosts(5) database. The getaddrinfo(3C) function is pre‐
ferred over these functions.
The getipnodebyname() function searches the ipnodes database from the
beginning. The function finds the first h_name member that matches the
hostname specified by name. The function takes an af argument that
specifies the address family. The address family can be AF_INET for
IPv4 addresses or AF_INET6 for IPv6 addresses. The flags argument
determines what results are returned based on the value of flags. If
the flags argument is set to 0 (zero), the default operation of the
function is specified as follows:
o If the af argument is AF_INET, a query is made for an IPv4
address. If successful, IPv4 addresses are returned and the
h_length member of the hostent structure is 4. Otherwise,
the function returns a NULL pointer.
o If the af argument is AF_INET6, a query is made for an IPv6
address. If successful, IPv6 addresses are returned and the
h_length member of the hostent structure is 16. Otherwise,
the function returns a NULL pointer.
The flags argument changes the default actions of the function. Set the
flags argument with a logical OR operation on any of combination of the
following values:
o AI_V4MAPPED
o AI_ALL
o AI_ADDRCONFIG
The special flags value, AI_DEFAULT, should handle most applications.
Porting simple applications to use IPv6 replaces the call
hptr = gethostbyname(name);
with
hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
The flags value 0 (zero) implies a strict interpretation of the af
argument:
o If flags is 0 and af is AF_INET, the caller wants only IPv4
addresses. A query is made for A records. If successful,
IPv4 addresses are returned and the h_length member of the
hostent structure is 4. Otherwise, the function returns a
NULL pointer.
o If flags is 0 and af is AF_INET6, the caller wants only IPv6
addresses. A query is made for AAAA records. If successful,
IPv6 addresses are returned and the h_length member of the
hostent structure is 16. Otherwise, the function returns a
NULL pointer.
Logically OR other constants into the flags argument to modify the
behavior of the getipnodebyname() function.
o If the AI_V4MAPPED flag is specified with af set to
AF_INET6, the caller can accept IPv4-mapped IPv6 addresses.
If no AAAA records are found, a query is made for A records.
Any A records found are returned as IPv4-mapped IPv6
addresses and the h_length is 16. The AI_V4MAPPED flag is
ignored unless af equals AF_INET6.
o The AI_ALL flag is used in conjunction with the AI_V4MAPPED
flag, exclusively with the IPv6 address family. When AI_ALL
is logically ORed with AI_V4MAPPED flag, the caller wants
all addresses: IPv6 and IPv4-mapped IPv6 addresses. A query
is first made for AAAA records and, if successful, IPv6
addresses are returned. Another query is then made for A
records. Any A records found are returned as IPv4-mapped
IPv6 addresses and the h_length is 16. Only when both
queries fail does the function return a NULL pointer. The
AI_ALL flag is ignored unless af is set to AF_INET6.
o The AI_ADDRCONFIG flag specifies that a query for AAAA
records should occur only when the node is configured with
at least one IPv6 source address. A query for A records
should occur only when the node is configured with at least
one IPv4 source address. For example, if a node is config‐
ured with no IPv6 source addresses, af equals AF_INET6, and
the node name queried has both AAAA and A records, then:
o A NULL pointer is returned when only the AI_ADDRCONFIG
value is specified.
o The A records are returned as IPv4-mapped IPv6 addresses
when the AI_ADDRCONFIG and AI_V4MAPPED values are speci‐
fied.
The special flags value, AI_DEFAULT, is defined as
#define AI_DEFAULT (AI_V4MAPPED | AI_ADDRCONFIG)
The getipnodebyname() function allows the name argument to be a node
name or a literal address string: a dotted-decimal IPv4 address or an
IPv6 hex address. Applications do not have to call inet_pton(3C) to
handle literal address strings.
Four scenarios arise based on the type of literal address string and
the value of the af argument. The two simple cases occur when name is a
dotted-decimal IPv4 address and af equals AF_INET and when name is an
IPv6 hex address and af equals AF_INET6. The members of the returned
hostent structure are:
h_name Pointer to a copy of the name argument
h_aliases NULL pointer.
h_addrtype Copy of the af argument.
h_length 4 for AF_INET or 16 for AF_INET6.
h_addr_list Array of pointers to 4-byte or 16-byte binary addresses.
The array is terminated by a NULL pointer.
The getipnodebyaddr() function has the same arguments as the existing
gethostbyaddr(3C) function, but adds an error number. As with getipn‐
odebyname(), getipnodebyaddr() is thread-safe. The error_num value is
returned to the caller with the appropriate error code to support
thread-safe error code returns.
RETURN VALUES
Upon successful completion, getipnodebyname() and getipnodebyaddr()
return a hostent structure. Otherwise they return NULL.
The hostent structure does not change from the existing definition when
used with gethostbyname(3C). For example, 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 */
};
This structure, and the information pointed to by this structure, are
dynamically allocated by getipnodebyname() and getipnodebyaddr(). The
freehostent() function frees this memory.
One possible source of confusion is the handling of IPv4-mapped IPv6
addresses and IPv4-compatible IPv6 addresses, but the following logic
should apply:
1. If af is AF_INET6, and if len equals 16, and if the IPv6
address is an IPv4-mapped IPv6 address or an IPv4-compatible
IPv6 address, then skip over the first 12 bytes of the IPv6
address, set af to AF_INET, and set len to 4.
2. If af is AF_INET, lookup the name for the given IPv4
address.
3. If af is AF_INET6, lookup the name for the given IPv6
address.
4. If the function is returning success, then the single
address that is returned in the hostent structure is a copy
of the first argument to the function with the same address
family that was passed as an argument to this function.
All four steps listed are performed in order.
ERRORS
The following error conditions can be returned in error_num:
HOST_NOT_FOUND Host is unknown, or name is an IPv6 hex address and
af equals AF_INET.
NO_DATA No address is available for the name specified in the
server request. This error is not a soft error.
Another type of name server request might be success‐
ful.
NO_RECOVERY An unexpected server failure occurred, which is a
non-recoverable error.
TRY_AGAIN This error is a soft error that indicates that the
local server did not receive a response from an
authoritative server. A retry at some later time
might be successful.
EXAMPLES
Example 1 Getting information for a Given Hostname
The following is a sample program that retrieves the canonical name,
aliases, and all Internet IP addresses, both version 6 and version 4,
for a given hostname.
#include <stdio.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)
{
char abuf[INET6_ADDRSTRLEN];
int error_num;
struct hostent *hp;
if (argc != 2) {
(void) printf("usage: %s hostname\n", argv[0]);
exit (1);
}
/* argv[1] can be a pointer to a hostname or literal IP address */
hp = getipnodebyname(argv[1], AF_INET6, AI_ALL | AI_ADDRCONFIG |
AI_V4MAPPED, &error_num);
if (hp == NULL) {
if (error_num == TRY_AGAIN) {
printf("%s: unknown host or invalid literal address "
"(try again later)\n", argv[1]);
} else {
printf("%s: unknown host or invalid literal address\n",
argv[1]);
}
exit (1);
}
for (char **p = hp->h_addr_list; *p != 0; p++) {
struct in6_addr in6;
bcopy(*p, &in6, hp->h_length);
(void) printf("%s\t%s",
inet_ntop(AF_INET6, &in6, abuf, sizeof(abuf)),
hp->h_name);
for (char **q = hp->h_aliases; *q != 0; q++) {
(void) printf(" %s", *q);
}
(void) putchar('\n');
}
freehostent(hp);
exit (0);
}
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-LevelSafe
SEE ALSO
getaddrinfo(3C), gethostbyname(3C), htonl(3C), inet(3C),
netdb.h(3HEAD), hosts(5), nsswitch.conf(5), attributes(7)
NOTES
No enumeration functions are provided for IPv6. Existing enumeration
functions such as sethostent(3C) do not work in combination with the
getipnodebyname() and getipnodebyaddr() functions.
All the functions that return a struct hostent must always return the
canonical in the h_name field. This name, by definition, is the well-
known and official hostname shared between all aliases and all
addresses. The underlying source that satisfies the request determines
the mapping of the input name or address into the set of names and
addresses in hostent. Different sources might make such as determina‐
tion in different ways. If more than one alias and more than one
address in hostent exist, no pairing is implied between the alias and
address.
The current implementations of these functions return or accept only
addresses for the Internet address family (type AF_INET) or the Inter‐
net address family Version 6 (type AF_INET6).
IPv4-mapped addresses are not recommended. The getaddrinfo(3C) function
is preferred over getipnodebyaddr() because it allows applications to
lookup IPv4 and IPv6 addresses without relying on IPv4-mapped
addresses.
The form for an address of type AF_INET is a struct in_addr defined in
<netinet/in.h>. The form for an address of type AF_INET6 is a struct
in6_addr, also defined in <netinet/in.h>. The functions described in
inet_ntop(3C) and inet_pton(3C) that are illustrated in the EXAMPLES
section are helpful in constructing and manipulating addresses in
either of these forms.
HISTORY
These functions were added to Oracle Solaris in the Solaris 8 release.
Oracle Solaris 11.4 2 Feb 2021 getipnodebyname(3C)