UNIX环境编程学习笔记------编程实例----域名解析函数的函数原型即getaddrinfo()函数原型

港控/mmm° 2022-08-17 14:28 197阅读 0赞

域名解析函数的函数原型：  
（这个函数内部调用了DNS服务，访问了DNS服务器）  
  
  
：  
  
  
man 3 getaddrinfo  
GETADDRINFO(3) Linux Programmer’s Manual GETADDRINFO(3)  
  
  
NAME  
getaddrinfo, freeaddrinfo, gai\_strerror - network address and service transla-  
tion  
  
  
SYNOPSIS  
\#include <sys/types.h>  
\#include <sys/socket.h>  
\#include <netdb.h>  
  
  
int getaddrinfo(const char \*node, const char \*service,  
const struct addrinfo \*hints,  
struct addrinfo \*\*res);  
  
  
void freeaddrinfo(struct addrinfo \*res);  
  
  
const char \*gai\_strerror(int errcode);  
  
  
Feature Test Macro Requirements for glibc (see feature\_test\_macros(7)):  
  
  
getaddrinfo(), freeaddrinfo(), gai\_strerror(): \_POSIX\_C\_SOURCE >= 1 ||  
\_XOPEN\_SOURCE || \_POSIX\_SOURCE  
  
  
DESCRIPTION  
Given node and service, which identify an Internet host and a service, getad-  
drinfo() returns one or more addrinfo structures, each of which contains an  
Internet address that can be specified in a call to bind(2) or connect(2).  
The getaddrinfo() function combines the functionality provided by the get-  
servbyname(3) and getservbyport(3) functions into a single interface, but  
unlike the latter functions, getaddrinfo() is reentrant and allows programs to  
eliminate IPv4-versus-IPv6 dependencies.  
  
  
The addrinfo structure used by getaddrinfo() contains the following fields:  
  
  
struct addrinfo \{  
int ai\_flags;  
int ai\_family;  
int ai\_socktype;  
int ai\_protocol;  
size\_t ai\_addrlen;  
struct sockaddr \*ai\_addr;  
char \*ai\_canonname;  
struct addrinfo \*ai\_next;  
\};  
  
  
The hints argument points to an addrinfo structure that specifies criteria for  
selecting the socket address structures returned in the list pointed to by  
res. If hints is not NULL it points to an addrinfo structure whose ai\_family,  
ai\_socktype, and ai\_protocol specify criteria that limit the set of socket  
addresses returned by getaddrinfo(), as follows:  
  
  
ai\_family This field specifies the desired address family for the returned  
addresses. Valid values for this field include AF\_INET and  
AF\_INET6. The value AF\_UNSPEC indicates that getaddrinfo() should  
return socket addresses for any address family (either IPv4 or  
IPv6, for example) that can be used with node and service.  
  
  
ai\_socktype This field specifies the preferred socket type, for example  
SOCK\_STREAM or SOCK\_DGRAM. Specifying 0 in this field indicates  
that socket addresses of any type can be returned by getad-  
drinfo().  
  
  
ai\_protocol This field specifies the protocol for the returned socket  
addresses. Specifying 0 in this field indicates that socket  
addresses with any protocol can be returned by getaddrinfo().  
  
  
ai\_flags This field specifies additional options, described below. Multi-  
ple flags are specified by logically OR-ing them together.  
  
  
All the other fields in the structure pointed to by hints must contain either  
0 or a null pointer, as appropriate. Specifying hints as NULL is equivalent  
to setting ai\_socktype and ai\_protocol to 0; ai\_family to AF\_UNSPEC; and  
ai\_flags to (AI\_V4MAPPED | AI\_ADDRCONFIG).  
  
  
node specifies either a numerical network address (for IPv4, numbers-and-dots  
notation as supported by inet\_aton(3); for IPv6, hexadecimal string format as  
supported by inet\_pton(3)), or a network hostname, whose network addresses are  
looked up and resolved. If hints.ai\_flags contains the AI\_NUMERICHOST flag  
then node must be a numerical network address. The AI\_NUMERICHOST flag sup-  
presses any potentially lengthy network host address lookups.  
  
  
If the AI\_PASSIVE flag is specified in hints.ai\_flags, and node is NULL, then  
the returned socket addresses will be suitable for bind(2)ing a socket that  
will accept(2) connections. The returned socket address will contain the  
"wildcard address" (INADDR\_ANY for IPv4 addresses, IN6ADDR\_ANY\_INIT for IPv6  
address). The wildcard address is used by applications (typically servers)  
that intend to accept connections on any of the hosts’s network addresses. If  
node is not NULL, then the AI\_PASSIVE flag is ignored.  
  
  
If the AI\_PASSIVE flag is not set in hints.ai\_flags, then the returned socket  
addresses will be suitable for use with connect(2), sendto(2), or sendmsg(2).  
If node is NULL, then the network address will be set to the loopback inter-  
face address (INADDR\_LOOPBACK for IPv4 addresses, IN6ADDR\_LOOPBACK\_INIT for  
IPv6 address); this is used by applications that intend to communicate with  
peers running on the same host.  
  
  
service sets the port in each returned address structure. If this argument is  
a service name (see services(5)), it is translated to the corresponding port  
number. This argument can also be specified as a decimal number, which is  
simply converted to binary. If service is NULL, then the port number of the  
returned socket addresses will be left uninitialized. If AI\_NUMERICSERV is  
specified in hints.ai\_flags and service is not NULL, then service must point  
to a string containing a numeric port number. This flag is used to inhibit  
the invocation of a name resolution service in cases where it is known not to  
be required.  
  
  
Either node or service, but not both, may be NULL.  
  
  
The getaddrinfo() function allocates and initializes a linked list of addrinfo  
structures, one for each network address that matches node and service, sub-  
ject to any restrictions imposed by hints, and returns a pointer to the start  
of the list in res. The items in the linked list are linked by the ai\_next  
field.  
  
  
There are several reasons why the linked list may have more than one addrinfo  
structure, including: the network host is multi-homed, accessible over multi-  
ple protocols (e.g. both AF\_INET and AF\_INET6); or the same service is avail-  
able from multiple socket types (one SOCK\_STREAM address and another  
SOCK\_DGRAM address, for example). Normally, the application should try using  
the addresses in the order in which they are returned. The sorting function  
used within getaddrinfo() is defined in RFC 3484; the order can be tweaked for  
a particular system by editing /etc/gai.conf (available since glibc 2.5).  
  
  
If hints.ai\_flags includes the AI\_CANONNAME flag, then the ai\_canonname field  
of the first of the addrinfo structures in the returned list is set to point  
to the official name of the host.  
  
  
The remaining fields of each returned addrinfo structure are initialized as  
follows:  
  
  
\* The ai\_family, ai\_socktype, and ai\_protocol fields return the socket cre-  
ation parameters (i.e., these fields have the same meaning as the corre-  
sponding arguments of socket(2)). For example, ai\_family might return  
AF\_INET or AF\_INET6; ai\_socktype might return SOCK\_DGRAM or SOCK\_STREAM; and  
ai\_protocol returns the protocol for the socket.  
  
  
\* A pointer to the socket address is placed in the ai\_addr field, and the  
length of the socket address, in bytes, is placed in the ai\_addrlen field.  
  
  
If hints.ai\_flags includes the AI\_ADDRCONFIG flag, then IPv4 addresses are  
returned in the list pointed to by result only if the local system has at  
least one IPv4 address configured, and IPv6 addresses are only returned if the  
local system has at least one IPv6 address configured.  
  
  
If hint.ai\_flags specifies the AI\_V4MAPPED flag, and hints.ai\_family was spec-  
ified as AF\_INET6, and no matching IPv6 addresses could be found, then return  
IPv4-mapped IPv6 addresses in the list pointed to by result. If both  
AI\_V4MAPPED and AI\_ALL are specified in hints.ai\_family, then return both IPv6  
and IPv4-mapped IPv6 addresses in the list pointed to by result. AI\_ALL is  
ignored if AI\_V4MAPPED is not also specified.  
  
  
The freeaddrinfo() function frees the memory that was allocated for the dynam-  
ically allocated linked list res.  
  
  
Extensions to getaddrinfo() for Internationalized Domain Names  
Starting with glibc 2.3.4, getaddrinfo() has been extended to selectively  
allow the incoming and outgoing hostnames to be transparently converted to and  
from the Internationalized Domain Name (IDN) format (see RFC 3490, Interna-  
tionalizing Domain Names in Applications (IDNA)). Four new flags are defined:  
  
  
AI\_IDN If this flag is specified, then the node name given in node is con-  
verted to IDN format if necessary. The source encoding is that of the  
current locale.  
  
  
If the input name contains non-ASCII characters, then the IDN encoding  
is used. Those parts of the node name (delimited by dots) that contain  
non-ASCII characters are encoded using ASCII Compatible Encoding (ACE)  
before being passed to the name resolution functions.  
  
  
AI\_CANONIDN  
After a successful name lookup, and if the AI\_CANONNAME flag was speci-  
fied, getaddrinfo() will return the canonical name of the node corre-  
sponding to the addrinfo structure value passed back. The return value  
is an exact copy of the value returned by the name resolution function.  
  
  
If the name is encoded using ACE, then it will contain the xn-- prefix  
for one or more components of the name. To convert these components  
into a readable form the AI\_CANONIDN flag can be passed in addition to  
AI\_CANONNAME. The resulting string is encoded using the current  
locale’s encoding.  
  
  
AI\_IDN\_ALLOW\_UNASSIGNED, AI\_IDN\_USE\_STD3\_ASCII\_RULES  
Setting these flags will enable the IDNA\_ALLOW\_UNASSIGNED (allow unas-  
signed Unicode code points) and IDNA\_USE\_STD3\_ASCII\_RULES (check output  
to make sure it is a STD3 conforming hostname) flags respectively to be  
used in the IDNA handling.  
  
  
RETURN VALUE  
getaddrinfo() returns 0 if it succeeds, or one of the following non-zero error  
codes:  
  
  
EAI\_ADDRFAMILY  
The specified network host does not have any network addresses in the  
requested address family.  
  
  
EAI\_AGAIN  
The name server returned a temporary failure indication. Try again  
later.  
  
  
EAI\_BADFLAGS  
hints.ai\_flags contains invalid flags; or, hints.ai\_flags included  
AI\_CANONNAME and name was NULL.  
  
  
EAI\_FAIL  
The name server returned a permanent failure indication.  
  
  
EAI\_FAMILY  
The requested address family is not supported.  
  
  
EAI\_MEMORY  
Out of memory.  
  
  
EAI\_NODATA  
The specified network host exists, but does not have any network  
addresses defined.  
  
  
EAI\_NONAME  
The node or service is not known; or both node and service are NULL; or  
AI\_NUMERICSERV was specified in hints.ai\_flags and service was not a  
numeric port-number string.  
  
  
EAI\_SERVICE  
The requested service is not available for the requested socket type.  
It may be available through another socket type. For example, this  
error could occur if service was "shell" (a service only available on  
stream sockets), and either hints.ai\_protocol was IPPROTO\_UDP, or  
hints.ai\_socktype was SOCK\_DGRAM; or the error could occur if service  
was not NULL, and hints.ai\_socktype was SOCK\_RAW (a socket type that  
does not support the concept of services).  
  
  
EAI\_SOCKTYPE  
The requested socket type is not supported. This could occur, for  
example, if hints.ai\_socktype and hints.ai\_protocol are inconsistent  
(e.g., SOCK\_DGRAM and IPPROTO\_TCP, repectively).  
  
  
EAI\_SYSTEM  
Other system error, check errno for details.  
  
  
The gai\_strerror() function translates these error codes to a human readable  
string, suitable for error reporting.  
  
  
FILES  
/etc/gai.conf  
  
  
CONFORMING TO  
POSIX.1-2001. The getaddrinfo() function is documented in RFC 2553.  
  
  
NOTES  
getaddrinfo() supports the address%scope-id notation for specifying the IPv6  
scope-ID.  
  
  
AI\_ADDRCONFIG, AI\_ALL, and AI\_V4MAPPED are available since glibc 2.3.3.  
AI\_NUMERICSERV is available since glibc 2.3.4.  
  
  
EXAMPLE  
The following programs demonstrate the use of getaddrinfo(), gai\_strerror(),  
freeaddrinfo(), and getnameinfo(3). The programs are an echo server and  
client for UDP datagrams.  
  
  
Server program  
  
  
\#include <sys/types.h>  
\#include <stdio.h>  
\#include <stdlib.h>  
\#include <unistd.h>  
\#include <string.h>  
\#include <sys/socket.h>  
\#include <netdb.h>  
  
  
\#define BUF\_SIZE 500  
  
  
int  
main(int argc, char \*argv\[\])  
\{  
struct addrinfo hints;  
struct addrinfo \*result, \*rp;  
int sfd, s;  
struct sockaddr\_storage peer\_addr;  
socklen\_t peer\_addr\_len;  
ssize\_t nread;  
char buf\[BUF\_SIZE\];  
  
  
if (argc != 2) \{  
fprintf(stderr, "Usage: %s port\\n", argv\[0\]);  
exit(EXIT\_FAILURE);  
\}  
  
  
memset(&hints, 0, sizeof(struct addrinfo));  
hints.ai\_family = AF\_UNSPEC; /\* Allow IPv4 or IPv6 \*/  
hints.ai\_socktype = SOCK\_DGRAM; /\* Datagram socket \*/  
hints.ai\_flags = AI\_PASSIVE; /\* For wildcard IP address \*/  
hints.ai\_protocol = 0; /\* Any protocol \*/  
hints.ai\_canonname = NULL;  
hints.ai\_addr = NULL;  
hints.ai\_next = NULL;  
  
  
s = getaddrinfo(NULL, argv\[1\], &hints, &result);  
if (s != 0) \{  
fprintf(stderr, "getaddrinfo: %s\\n", gai\_strerror(s));  
exit(EXIT\_FAILURE);  
\}  
  
  
/\* getaddrinfo() returns a list of address structures.  
Try each address until we successfully bind(2).  
If socket(2) (or bind(2)) fails, we (close the socket  
and) try the next address. \*/  
  
  
for (rp = result; rp != NULL; rp = rp->ai\_next) \{  
sfd = socket(rp->ai\_family, rp->ai\_socktype,  
rp->ai\_protocol);  
if (sfd == -1)  
continue;  
  
  
if (bind(sfd, rp->ai\_addr, rp->ai\_addrlen) == 0)  
break; /\* Success \*/  
  
  
close(sfd);  
\}  
  
  
if (rp == NULL) \{ /\* No address succeeded \*/  
fprintf(stderr, "Could not bind\\n");  
exit(EXIT\_FAILURE);  
\}  
  
  
freeaddrinfo(result); /\* No longer needed \*/  
  
  
/\* Read datagrams and echo them back to sender \*/  
  
  
for (;;) \{  
peer\_addr\_len = sizeof(struct sockaddr\_storage);  
nread = recvfrom(sfd, buf, BUF\_SIZE, 0,  
(struct sockaddr \*) &peer\_addr, &peer\_addr\_len);  
if (nread == -1)  
continue; /\* Ignore failed request \*/  
  
  
char host\[NI\_MAXHOST\], service\[NI\_MAXSERV\];  
  
  
s = getnameinfo((struct sockaddr \*) &peer\_addr,  
peer\_addr\_len, host, NI\_MAXHOST,  
service, NI\_MAXSERV, NI\_NUMERICSERV);  
if (s == 0)  
printf("Received %ld bytes from %s:%s\\n",  
(long) nread, host, service);  
else  
fprintf(stderr, "getnameinfo: %s\\n", gai\_strerror(s));  
  
  
if (sendto(sfd, buf, nread, 0,  
(struct sockaddr \*) &peer\_addr,  
peer\_addr\_len) != nread)  
fprintf(stderr, "Error sending response\\n");  
\}  
\}  
  
  
Client program  
  
  
\#include <sys/types.h>  
\#include <sys/socket.h>  
\#include <netdb.h>  
\#include <stdio.h>  
\#include <stdlib.h>  
\#include <unistd.h>  
\#include <string.h>  
  
  
\#define BUF\_SIZE 500  
  
  
int  
main(int argc, char \*argv\[\])  
\{  
struct addrinfo hints;  
struct addrinfo \*result, \*rp;  
int sfd, s, j;  
size\_t len;  
ssize\_t nread;  
char buf\[BUF\_SIZE\];  
  
  
if (argc < 3) \{  
fprintf(stderr, "Usage: %s host port msg...\\n", argv\[0\]);  
exit(EXIT\_FAILURE);  
\}  
  
  
/\* Obtain address(es) matching host/port \*/  
  
  
memset(&hints, 0, sizeof(struct addrinfo));  
hints.ai\_family = AF\_UNSPEC; /\* Allow IPv4 or IPv6 \*/  
hints.ai\_socktype = SOCK\_DGRAM; /\* Datagram socket \*/  
hints.ai\_flags = 0;  
hints.ai\_protocol = 0; /\* Any protocol \*/  
  
  
s = getaddrinfo(argv\[1\], argv\[2\], &hints, &result);  
if (s != 0) \{  
fprintf(stderr, "getaddrinfo: %s\\n", gai\_strerror(s));  
exit(EXIT\_FAILURE);  
\}  
  
  
/\* getaddrinfo() returns a list of address structures.  
Try each address until we successfully connect(2).  
If socket(2) (or connect(2)) fails, we (close the socket  
and) try the next address. \*/  
  
  
for (rp = result; rp != NULL; rp = rp->ai\_next) \{  
sfd = socket(rp->ai\_family, rp->ai\_socktype,  
rp->ai\_protocol);  
if (sfd == -1)  
continue;  
  
  
if (connect(sfd, rp->ai\_addr, rp->ai\_addrlen) != -1)  
break; /\* Success \*/  
  
  
close(sfd);  
\}  
  
  
if (rp == NULL) \{ /\* No address succeeded \*/  
fprintf(stderr, "Could not connect\\n");  
exit(EXIT\_FAILURE);  
\}  
  
  
freeaddrinfo(result); /\* No longer needed \*/  
  
  
/\* Send remaining command-line arguments as separate  
datagrams, and read responses from server \*/  
  
  
for (j = 3; j < argc; j++) \{  
len = strlen(argv\[j\]) + 1;  
/\* +1 for terminating null byte \*/  
  
  
if (len + 1 > BUF\_SIZE) \{  
fprintf(stderr,  
"Ignoring long message in argument %d\\n", j);  
continue;  
\}  
  
  
if (write(sfd, argv\[j\], len) != len) \{  
fprintf(stderr, "partial/failed write\\n");  
exit(EXIT\_FAILURE);  
\}  
  
  
nread = read(sfd, buf, BUF\_SIZE);  
if (nread == -1) \{  
perror("read");  
exit(EXIT\_FAILURE);  
\}  
  
  
printf("Received %ld bytes: %s\\n", (long) nread, buf);  
\}  
  
  
exit(EXIT\_SUCCESS);  
\}  
  
  
SEE ALSO  
gethostbyname(3), getnameinfo(3), inet(3), hostname(7), ip(7)  
  
  
COLOPHON  
This page is part of release 3.22 of the Linux man-pages project. A descrip-  
tion of the project, and information about reporting bugs, can be found at  
http://www.kernel.org/doc/man-pages/.