1freeaddrinfo(3XNETX)/Open Networking Services Library Functionfsreeaddrinfo(3XNET)
2
6 freeaddrinfo, getaddrinfo - get address information
7
9 cc [ flag ... ] file ... -lxnet [ library ... ]
10 #include <sys/socket.h>
11 #include <netdb.h>
12 void freeaddrinfo(struct addrinfo *ai);
14 int getaddrinfo(const char *restrict nodename,
17 const char *restrict servname, const struct addrinfo *restrict hints,
18 struct addrinfo **restrict res);
19
22 The freeaddrinfo() function frees one or more addrinfo structures
23 returned by getaddrinfo(), along with any additional storage associated
24 with those structures. If the ai_next member of the structure is not
25 null, the entire list of structures is freed. The freeaddrinfo() func‐
26 tion supports the freeing of arbitrary sublists of an addrinfo list
27 originally returned by getaddrinfo().
28 The getaddrinfo() function translates the name of a service location
31 (for example, a host name) and/or a service name and returns a set of
32 socket addresses and associated information to be used in creating a
33 socket with which to address the specified service.
34 The nodename and servname arguments are either null pointers or point‐
37 ers to null-terminated strings. One or both of these two arguments are
38 supplied by the application as a non-null pointer.
39 The format of a valid name depends on the address family or families.
42 If a specific family is not given and the name could be interpreted as
43 valid within multiple supported families, the implementation attempts
44 to resolve the name in all supported families and, in absence of
45 errors, one or more results are returned.
46 If the nodename argument is not null, it can be a descriptive name or
49 can be an address string. If the specified address family is AF_INET,
50 AF_INET6, or AF_UNSPEC, valid descriptive names include host names. If
51 the specified address family is AF_INET or AF_UNSPEC, address strings
52 using Internet standard dot notation as specified in inet_addr(3XNET)
53 are valid.
54 If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
57 text forms described in inet_ntop(3XNET) are valid.
58 If nodename is not null, the requested service location is named by
61 nodename; otherwise, the requested service location is local to the
62 caller.
63 If servname is null, the call returns network-level addresses for the
66 specified nodename. If servname is not null, it is a null-terminated
67 character string identifying the requested service. This string can be
68 either a descriptive name or a numeric representation suitable for use
69 with the address family or families. If the specified address family is
70 AF_INET, AF_INET6, or AF_UNSPEC, the service can be specified as a
71 string specifying a decimal port number.
72 If the hints argument is not null, it refers to a structure containing
75 input values that can direct the operation by providing options and by
76 limiting the returned information to a specific socket type, address
77 family and/or protocol. In this hints structure every member other than
78 ai_flags, ai_family , ai_socktype, and ai_protocol is set to 0 or a
79 null pointer. A value of AF_UNSPEC for ai_family means that the caller
80 accepts any address family. A value of 0 for ai_socktype means that the
81 caller accepts any socket type. A value of 0 for ai_protocol means that
82 the caller accepts any protocol. If hints is a null pointer, the behav‐
83 ior is as if it referred to a structure containing the value 0 for the
84 ai_flags, ai_socktype, and ai_protocol members, and AF_UNSPEC for the
85 ai_family member.
86 The ai_flags member to which the hints parameter points is set to 0 or
89 be the bitwise-inclusive OR of one or more of the values AI_PASSIVE,
90 AI_CANONNAME, AI_NUMERICHOST, and AI_NUMERICSERV.
91 If the AI_PASSIVE flag is specified, the returned address information
94 is suitable for use in binding a socket for accepting incoming connec‐
95 tions for the specified service. In this case, if the nodename argument
96 is null, then the IP address portion of the socket address structure is
97 set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
98 address. If the AI_PASSIVE flag is not specified, the returned address
99 information is suitable for a call to connect(3XNET) (for a connection-
100 mode protocol) or for a call to connect(), sendto(3XNET), or
101 sendmsg(3XNET) (for a connectionless protocol). In this case, if the
102 nodename argument is null, then the IP address portion of the socket
103 address structure is set to the loopback address.
104 If the AI_CANONNAME flag is specified and the nodename argument is not
107 null, the function attempts to determine the canonical name correspond‐
108 ing to nodename (for example, if nodename is an alias or shorthand
109 notation for a complete name).
110 If the AI_NUMERICHOST flag is specified, then a non-null nodename
113 string supplied is a numeric host address string. Otherwise, an EAI_NO‐
114 NAME error is returned. This flag prevents any type of name resolution
115 service (for example, the DNS) from being invoked.
116 If the AI_NUMERICSERV flag is specified, then a non-null servname
119 string supplied is a numeric port string. Otherwise, an EAI_NONAME
120 error is returned. This flag prevents any type of name resolution ser‐
121 vice (for example, NIS+) from being invoked.
122 If the AI_V4MAPPED flag is specified along with an ai_family of
125 AF_INET6, then getaddrinfo() returns IPv4-mapped IPv6 addresses on
126 finding no matching IPv6 addresses (ai_addrlen is 16). The AI_V4MAPPED
127 flag is ignored unless ai_family equals AF_INET6. If the AI_ALL flag is
128 used with the AI_V4MAPPED flag, then getaddrinfo() returns all matching
129 IPv6 and IPv4 addresses. The AI_ALL flag without the AI_V4MAPPED flag
130 is ignored.
131 The ai_socktype member to which argument hints points specifies the
134 socket type for the service, as defined in socket(3XNET). If a specific
135 socket type is not given (for example, a value of 0) and the service
136 name could be interpreted as valid with multiple supported socket
137 types, the implementation attempts to resolve the service name for all
138 supported socket types and, in the absence of errors, all possible
139 results are returned. A non-zero socket type value limits the returned
140 information to values with the specified socket type.
141 If the ai_family member to which hints points has the value AF_UNSPEC,
144 addresses are returned for use with any address family that can be used
145 with the specified nodename and/or servname. Otherwise, addresses are
146 returned for use only with the specified address family. If ai_family
147 is not AF_UNSPEC and ai_protocol is not 0, then addresses are returned
148 for use only with the specified address family and protocol; the value
149 of ai_protocol is interpreted as in a call to the socket() function
150 with the corresponding values of ai_family and ai_protocol.
151
153 A 0 return value for getaddrinfo() indicates successful completion; a
154 non-zero return value indicates failure. The possible values for the
155 failures are listed in the ERRORS section.
156 Upon successful return of getaddrinfo(), the location to which res
159 points refers to a linked list of addrinfo structures, each of which
160 specifies a socket address and information for use in creating a socket
161 with which to use that socket address. The list includes at least one
162 addrinfo structure. The ai_next member of each structure contains a
163 pointer to the next structure on the list, or a null pointer if it is
164 the last structure on the list. Each structure on the list includes
165 values for use with a call to the socket function, and a socket address
166 for use with the connect function or, if the AI_PASSIVE flag was speci‐
167 fied, for use with the bind(3XNET) function. The ai_family , ai_sock‐
168 type, and ai_protocol members are usable as the arguments to the
169 socket() function to create a socket suitable for use with the returned
170 address. The ai_addr and ai_addrlen members are usable as the arguments
171 to the connect() or bind() functions with such a socket, according to
172 the AI_PASSIVE flag.
173 If nodename is not null, and if requested by the AI_CANONNAME flag, the
176 ai_canonname member of the first returned addrinfo structure points to
177 a null-terminated string containing the canonical name corresponding to
178 the input nodename. If the canonical name is not available, then
179 ai_canonname refers to the nodename argument or a string with the same
180 contents. The contents of the ai_flags member of the returned struc‐
181 tures are undefined.
182 All members in socket address structures returned by getaddrinfo() that
185 are not filled in through an explicit argument (for example, sin6_flow‐
186 info) are set to 0, making it easier to compare socket address struc‐
187 tures.
188
190 The getaddrinfo() function will fail if:
191 EAI_AGAIN The name could not be resolved at this time. Future
193 attempts might succeed.
194 EAI_BADFLAGS The ai_flags member of the addrinfo structure had an
197 invalid value.
198 EAI_FAIL A non-recoverable error occurred when attempting to
201 resolve the name.
202 EAI_FAMILY The address family was not recognized.
205 EAI_MEMORY There was a memory allocation failure when trying to
208 allocate storage for the return value.
209 EAI_NONAME he name does not resolve for the supplied parameters.
212 Neither nodename nor servname were supplied. At least
213 one of these must be supplied.
214 EAI_SERVICE The service passed was not recognized for the specified
217 socket type.
218 EAI_SOCKTYPE The intended socket type was not recognized.
221 EAI_SYSTEM A system error occurred. The error code can be found in
224 errno.
225 EAI_OVERFLOW An argument buffer overflowed.
228
231 If the caller handles only TCP and not UDP, for example, then the
232 ai_protocol member of the hints structure should be set to IPPROTO_TCP
233 when getaddrinfo() is called.
234 If the caller handles only IPv4 and not IPv6, then the ai_family member
237 of the hints structure should be set to AF_INET when getaddrinfo() is
238 called.
239
241 See attributes(5) for descriptions of the following attributes:
242 ┌─────────────────────────────┬─────────────────────────────┐
247 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
248 ├─────────────────────────────┼─────────────────────────────┤
249 │Interface Stability │Standard │
250 ├─────────────────────────────┼─────────────────────────────┤
251 │MT-Level │MT-Safe │
252 └─────────────────────────────┴─────────────────────────────┘
253
255 connect(3XNET), gai_strerror(3XNET), gethostbyname(3XNET), getname‐
256 info(3XNET), getservbyname(3XNET), inet_addr(3XNET), inet_ntop(3XNET),
257 socket(3XNET), attributes(5), standards(5)
258SunOS 5.11 1 Nov 2003 freeaddrinfo(3XNET)