1LWRES_GETADDRINFO(3)                 BIND9                LWRES_GETADDRINFO(3)
2
3
4

NAME

6       lwres_getaddrinfo, lwres_freeaddrinfo - socket address structure to
7       host and service name
8

SYNOPSIS

10       #include <lwres/netdb.h>
11
12       int lwres_getaddrinfo(const char *hostname, const char *servname,
13                             const struct addrinfo *hints,
14                             struct addrinfo **res);
15
16       void lwres_freeaddrinfo(struct addrinfo *ai);
17
18       If the operating system does not provide a struct addrinfo, the
19       following structure is used:
20
21           struct  addrinfo {
22                   int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
23                   int             ai_family;      /* PF_xxx */
24                   int             ai_socktype;    /* SOCK_xxx */
25                   int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
26                   size_t          ai_addrlen;     /* length of ai_addr */
27                   char            *ai_canonname;  /* canonical name for hostname */
28                   struct sockaddr *ai_addr;       /* binary address */
29                   struct addrinfo *ai_next;       /* next structure in linked list */
30           };
31
32

DESCRIPTION

34       lwres_getaddrinfo() is used to get a list of IP addresses and port
35       numbers for host hostname and service servname. The function is the
36       lightweight resolver's implementation of getaddrinfo() as defined in
37       RFC2133.  hostname and servname are pointers to null-terminated strings
38       or NULL.  hostname is either a host name or a numeric host address
39       string: a dotted decimal IPv4 address or an IPv6 address.  servname is
40       either a decimal port number or a service name as listed in
41       /etc/services.
42
43       hints is an optional pointer to a struct addrinfo. This structure can
44       be used to provide hints concerning the type of socket that the caller
45       supports or wishes to use. The caller can supply the following
46       structure elements in *hints:
47
48       ai_family
49           The protocol family that should be used. When ai_family is set to
50           PF_UNSPEC, it means the caller will accept any protocol family
51           supported by the operating system.
52
53       ai_socktype
54           denotes the type of socket — SOCK_STREAM, SOCK_DGRAM or SOCK_RAW 
55           that is wanted. When ai_socktype is zero the caller will accept any
56           socket type.
57
58       ai_protocol
59           indicates which transport protocol is wanted: IPPROTO_UDP or
60           IPPROTO_TCP. If ai_protocol is zero the caller will accept any
61           protocol.
62
63       ai_flags
64           Flag bits. If the AI_CANONNAME bit is set, a successful call to
65           lwres_getaddrinfo() will return a null-terminated string containing
66           the canonical name of the specified hostname in ai_canonname of the
67           first addrinfo structure returned. Setting the AI_PASSIVE bit
68           indicates that the returned socket address structure is intended
69           for used in a call to bind(2). In this case, if the hostname
70           argument is a NULL pointer, then the IP address portion of the
71           socket address structure will be set to INADDR_ANY for an IPv4
72           address or IN6ADDR_ANY_INIT for an IPv6 address.
73
74           When ai_flags does not set the AI_PASSIVE bit, the returned socket
75           address structure will be ready for use in a call to connect(2) for
76           a connection-oriented protocol or connect(2), sendto(2), or
77           sendmsg(2) if a connectionless protocol was chosen. The IP address
78           portion of the socket address structure will be set to the loopback
79           address if hostname is a NULL pointer and AI_PASSIVE is not set in
80           ai_flags.
81
82           If ai_flags is set to AI_NUMERICHOST it indicates that hostname
83           should be treated as a numeric string defining an IPv4 or IPv6
84           address and no name resolution should be attempted.
85
86       All other elements of the struct addrinfo passed via hints must be
87       zero.
88
89       A hints of NULL is treated as if the caller provided a struct addrinfo
90       initialized to zero with ai_familyset to PF_UNSPEC.
91
92       After a successful call to lwres_getaddrinfo(), *res is a pointer to a
93       linked list of one or more addrinfo structures. Each struct addrinfo in
94       this list cn be processed by following the ai_next pointer, until a
95       NULL pointer is encountered. The three members ai_family, ai_socktype,
96       and ai_protocol in each returned addrinfo structure contain the
97       corresponding arguments for a call to socket(2). For each addrinfo
98       structure in the list, the ai_addr member points to a filled-in socket
99       address structure of length ai_addrlen.
100
101       All of the information returned by lwres_getaddrinfo() is dynamically
102       allocated: the addrinfo structures, and the socket address structures
103       and canonical host name strings pointed to by the addrinfostructures.
104       Memory allocated for the dynamically allocated structures created by a
105       successful call to lwres_getaddrinfo() is released by
106       lwres_freeaddrinfo().  ai is a pointer to a struct addrinfo created by
107       a call to lwres_getaddrinfo().
108

RETURN VALUES

110       lwres_getaddrinfo() returns zero on success or one of the error codes
111       listed in gai_strerror(3) if an error occurs. If both hostname and
112       servname are NULL lwres_getaddrinfo() returns EAI_NONAME.
113

SEE ALSO

115       lwres(3), lwres_getaddrinfo(3), lwres_freeaddrinfo(3),
116       lwres_gai_strerror(3), RFC2133(), getservbyname(3), bind(2),
117       connect(2), sendto(2), sendmsg(2), socket(2).
118
120       Copyright © 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
121       Copyright © 2000, 2001, 2003 Internet Software Consortium.
122
123
124
125BIND9                            Jun 30, 2000             LWRES_GETADDRINFO(3)
Impressum