logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

freeaddrinfo.3p (16574B)


  1. '\" et
  2. .TH FREEADDRINFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. freeaddrinfo,
  12. getaddrinfo
  13. \(em get address information
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <sys/socket.h>
  18. #include <netdb.h>
  19. .P
  20. void freeaddrinfo(struct addrinfo *\fIai\fP);
  21. int getaddrinfo(const char *restrict \fInodename\fP,
  22. const char *restrict \fIservname\fP,
  23. const struct addrinfo *restrict \fIhints\fP,
  24. struct addrinfo **restrict \fIres\fP);
  25. .fi
  26. .SH DESCRIPTION
  27. The
  28. \fIfreeaddrinfo\fR()
  29. function shall free one or more
  30. .BR addrinfo
  31. structures returned by
  32. \fIgetaddrinfo\fR(),
  33. along with any additional storage associated with those structures. If
  34. the
  35. .IR ai_next
  36. field of the structure is not null, the entire list of structures shall
  37. be freed. The
  38. \fIfreeaddrinfo\fR()
  39. function shall support the freeing of arbitrary sublists of an
  40. .BR addrinfo
  41. list originally returned by
  42. \fIgetaddrinfo\fR().
  43. .P
  44. The
  45. \fIgetaddrinfo\fR()
  46. function shall translate the name of a service location (for example, a
  47. host name) and/or a service name
  48. and shall return a set of socket addresses and associated information
  49. to be used in creating a socket with which to address the specified
  50. service.
  51. .TP 10
  52. .BR Note:
  53. In many cases it is implemented by the Domain Name System,
  54. as documented in RFC\ 1034, RFC\ 1035, and RFC\ 1886.
  55. .P
  56. .P
  57. The
  58. \fIfreeaddrinfo\fR()
  59. and
  60. \fIgetaddrinfo\fR()
  61. functions shall be thread-safe.
  62. .P
  63. The
  64. .IR nodename
  65. and
  66. .IR servname
  67. arguments are either null pointers or pointers to null-terminated
  68. strings. One or both of these two arguments shall be supplied by the
  69. application as a non-null pointer.
  70. .P
  71. The format of a valid name depends on the address family or families.
  72. If a specific family is not given and the name could be interpreted as
  73. valid within multiple supported families, the implementation shall
  74. attempt to resolve the name in all supported families and, in absence
  75. of errors, one or more results shall be returned.
  76. .P
  77. If the
  78. .IR nodename
  79. argument is not null, it can be a descriptive name or can be an address
  80. string.
  81. If the specified address family is AF_INET,
  82. AF_INET6,
  83. or AF_UNSPEC, valid descriptive names include host names. If the
  84. specified address family is AF_INET or AF_UNSPEC, address strings using
  85. Internet standard dot notation as specified in
  86. .IR "\fIinet_addr\fR\^(\|)"
  87. are valid.
  88. .P
  89. If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
  90. text forms described in
  91. .IR "\fIinet_ntop\fR\^(\|)"
  92. are valid.
  93. .P
  94. If
  95. .IR nodename
  96. is not null, the requested service location is named by
  97. .IR nodename ;
  98. otherwise, the requested service location is local to the caller.
  99. .P
  100. If
  101. .IR servname
  102. is null, the call shall return network-level addresses for the
  103. specified
  104. .IR nodename.
  105. If
  106. .IR servname
  107. is not null, it is a null-terminated character string identifying the
  108. requested service. This can be either a descriptive name or a numeric
  109. representation suitable for use with the address family or families.
  110. If the specified address family is AF_INET,
  111. AF_INET6,
  112. or AF_UNSPEC, the service can be specified as a string specifying a
  113. decimal port number.
  114. .P
  115. If the
  116. .IR hints
  117. argument is not null, it refers to a structure containing input values
  118. that directs the operation by providing options and by limiting the
  119. returned information to a specific socket type, address family, and/or
  120. protocol, as described below. The application shall ensure that each of the
  121. .IR ai_addrlen ,
  122. .IR ai_addr ,
  123. .IR ai_canonname ,
  124. and
  125. .IR ai_next
  126. members, as well as each of the non-standard additional members,
  127. if any, of this
  128. .IR hints
  129. structure is initialized. If any of these members has a value
  130. other than the value that would result from default initialization,
  131. the behavior is implementation-defined. A value of AF_UNSPEC for
  132. .IR ai_family
  133. means that the caller shall accept any address family. A value of zero
  134. for
  135. .IR ai_socktype
  136. means that the caller shall accept any socket type. A value of zero for
  137. .IR ai_protocol
  138. means that the caller shall accept any protocol. If
  139. .IR hints
  140. is a null pointer, the behavior shall be as if it referred to a
  141. structure containing the value zero for the
  142. .IR ai_flags ,
  143. .IR ai_socktype ,
  144. and
  145. .IR ai_protocol
  146. fields, and AF_UNSPEC for the
  147. .IR ai_family
  148. field.
  149. .P
  150. The
  151. .IR ai_flags
  152. field to which the
  153. .IR hints
  154. parameter points shall be set to zero or be the bitwise-inclusive
  155. OR of one or more of the values AI_PASSIVE, AI_CANONNAME,
  156. AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG.
  157. .P
  158. If the AI_PASSIVE flag is specified, the returned address information
  159. shall be suitable for use in binding a socket for accepting incoming
  160. connections for the specified service. In this case, if the
  161. .IR nodename
  162. argument is null, then the IP address portion of the socket address
  163. structure shall be set to INADDR_ANY for an IPv4 address or
  164. IN6ADDR_ANY_INIT for an IPv6 address. If the AI_PASSIVE flag is not
  165. specified, the returned address information shall be suitable for a call
  166. to
  167. \fIconnect\fR()
  168. (for a connection-mode protocol) or for a call to
  169. \fIconnect\fR(),
  170. \fIsendto\fR(),
  171. or
  172. \fIsendmsg\fR()
  173. (for a connectionless protocol). In this case, if the
  174. .IR nodename
  175. argument is null, then the IP address portion of the socket address
  176. structure shall be set to the loopback address. The AI_PASSIVE flag shall
  177. be ignored if the
  178. .IR nodename
  179. argument is not null.
  180. .P
  181. If the AI_CANONNAME flag is specified and the
  182. .IR nodename
  183. argument is not null, the function shall attempt to determine the
  184. canonical name corresponding to
  185. .IR nodename
  186. (for example, if
  187. .IR nodename
  188. is an alias or shorthand notation for a complete name).
  189. .TP 10
  190. .BR Note:
  191. Since different implementations use different conceptual models, the
  192. terms ``canonical name'' and ``alias'' cannot be precisely defined for
  193. the general case. However, Domain Name System implementations are
  194. expected to interpret them as they are used in RFC\ 1034.
  195. .RS 10
  196. .P
  197. A numeric host address string is not a ``name'', and thus does not have
  198. a ``canonical name'' form; no address to host name translation is
  199. performed. See below for handling of the case where a canonical name
  200. cannot be obtained.
  201. .RE
  202. .P
  203. .P
  204. If the AI_NUMERICHOST flag is specified, then a non-null
  205. .IR nodename
  206. string supplied shall be a numeric host address string. Otherwise, an
  207. .BR [EAI_NONAME]
  208. error is returned. This flag shall prevent any type of name resolution
  209. service (for example, the DNS) from being invoked.
  210. .P
  211. If the AI_NUMERICSERV flag is specified, then a non-null
  212. .IR servname
  213. string supplied shall be a numeric port string. Otherwise, an
  214. .BR [EAI_NONAME]
  215. error shall be returned. This flag shall prevent any type of name
  216. resolution service (for example, NIS+) from being invoked.
  217. .P
  218. By default, with an
  219. .IR ai_family
  220. of AF_INET6,
  221. \fIgetaddrinfo\fR()
  222. shall return only IPv6 addresses. If the AI_V4MAPPED flag is
  223. specified along with an
  224. .IR ai_family
  225. of AF_INET6, then
  226. \fIgetaddrinfo\fR()
  227. shall return IPv4-mapped IPv6 addresses on finding no matching IPv6
  228. addresses. The AI_V4MAPPED flag shall be ignored unless
  229. .IR ai_family
  230. equals AF_INET6. If the AI_ALL flag is used with the AI_V4MAPPED flag,
  231. then
  232. \fIgetaddrinfo\fR()
  233. shall return all matching IPv6 and IPv4 addresses. The AI_ALL flag
  234. without the AI_V4MAPPED flag shall be ignored.
  235. .P
  236. If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be
  237. returned only if an IPv4 address is configured on the local system,
  238. and IPv6 addresses shall be returned only if an IPv6 address is
  239. configured on the local system.
  240. .P
  241. The
  242. .IR ai_socktype
  243. field to which argument
  244. .IR hints
  245. points specifies the socket type for the service, as defined in
  246. .IR "\fIsocket\fR\^(\|)".
  247. If a specific socket type is not given (for example, a value of zero)
  248. and the service name could be interpreted as valid with multiple
  249. supported socket types, the implementation shall attempt to resolve the
  250. service name for all supported socket types and, in the absence of
  251. errors, all possible results shall be returned. A non-zero socket type
  252. value shall limit the returned information to values with the specified
  253. socket type.
  254. .P
  255. If the
  256. .IR ai_family
  257. field to which
  258. .IR hints
  259. points has the value AF_UNSPEC, addresses shall be returned for use
  260. with any address family that can be used with the specified
  261. .IR nodename
  262. and/or
  263. .IR servname .
  264. Otherwise, addresses shall be returned for use only with the specified
  265. address family. If
  266. .IR ai_family
  267. is not AF_UNSPEC and
  268. .IR ai_protocol
  269. is not zero, then addresses shall be returned for use only with the
  270. specified address family and protocol; the value of
  271. .IR ai_protocol
  272. shall be interpreted as in a call to the
  273. \fIsocket\fR()
  274. function with the corresponding values of
  275. .IR ai_family
  276. and
  277. .IR ai_protocol .
  278. .SH "RETURN VALUE"
  279. A zero return value for
  280. \fIgetaddrinfo\fR()
  281. indicates successful completion; a non-zero return value indicates
  282. failure. The possible values for the failures are listed in the
  283. ERRORS section.
  284. .P
  285. Upon successful return of
  286. \fIgetaddrinfo\fR(),
  287. the location to which
  288. .IR res
  289. points shall refer to a linked list of
  290. .BR addrinfo
  291. structures, each of which shall specify a socket address and
  292. information for use in creating a socket with which to use that socket
  293. address. The list shall include at least one
  294. .BR addrinfo
  295. structure. The
  296. .IR ai_next
  297. field of each structure contains a pointer to the next structure on the
  298. list, or a null pointer if it is the last structure on the list. Each
  299. structure on the list shall include values for use with a call to the
  300. \fIsocket\fR()
  301. function, and a socket address for use with the
  302. \fIconnect\fR()
  303. function or, if the AI_PASSIVE flag was specified, for use with the
  304. \fIbind\fR()
  305. function. The fields
  306. .IR ai_family ,
  307. .IR ai_socktype ,
  308. and
  309. .IR ai_protocol
  310. shall be usable as the arguments to the
  311. \fIsocket\fR()
  312. function to create a socket suitable for use with the returned
  313. address. The fields
  314. .IR ai_addr
  315. and
  316. .IR ai_addrlen
  317. are usable as the arguments to the
  318. \fIconnect\fR()
  319. or
  320. \fIbind\fR()
  321. functions with such a socket, according to the AI_PASSIVE flag.
  322. .P
  323. If
  324. .IR nodename
  325. is not null, and if requested by the AI_CANONNAME flag, the
  326. .IR ai_canonname
  327. field of the first returned
  328. .BR addrinfo
  329. structure shall point to a null-terminated string containing the
  330. canonical name corresponding to the input
  331. .IR nodename ;
  332. if the canonical name is not available, then
  333. .IR ai_canonname
  334. shall refer to the
  335. .IR nodename
  336. argument or a string with the same contents. The contents of the
  337. .IR ai_flags
  338. field of the returned structures are undefined.
  339. .P
  340. All fields in socket address structures returned by
  341. \fIgetaddrinfo\fR()
  342. that are not filled in through an explicit argument (for example,
  343. .IR sin6_flowinfo )
  344. shall be set to zero.
  345. .TP 10
  346. .BR Note:
  347. This makes it easier to compare socket address structures.
  348. .P
  349. .SH ERRORS
  350. The
  351. \fIgetaddrinfo\fR()
  352. function shall fail and return the corresponding error value if:
  353. .IP [EAI_AGAIN] 12
  354. The name could not be resolved at this time. Future attempts may
  355. succeed.
  356. .IP [EAI_BADFLAGS] 12
  357. .br
  358. The
  359. .IR flags
  360. parameter had an invalid value.
  361. .IP [EAI_FAIL] 12
  362. A non-recoverable error occurred when attempting to resolve the name.
  363. .IP [EAI_FAMILY] 12
  364. The address family was not recognized.
  365. .IP [EAI_MEMORY] 12
  366. There was a memory allocation failure when trying to allocate storage
  367. for the return value.
  368. .IP [EAI_NONAME] 12
  369. The name does not resolve for the supplied parameters.
  370. .RS 12
  371. .P
  372. Neither
  373. .IR nodename
  374. nor
  375. .IR servname
  376. were supplied. At least one of these shall be supplied.
  377. .RE
  378. .IP [EAI_SERVICE] 12
  379. The service passed was not recognized for the specified socket type.
  380. .IP [EAI_SOCKTYPE] 12
  381. .br
  382. The intended socket type was not recognized.
  383. .IP [EAI_SYSTEM] 12
  384. A system error occurred; the error code can be found in
  385. .IR errno .
  386. .LP
  387. .IR "The following sections are informative."
  388. .SH "EXAMPLES"
  389. The following (incomplete) program demonstrates the use of
  390. \fIgetaddrinfo\fR()
  391. to obtain the socket address structure(s) for the service named in the
  392. program's command-line argument. The program then loops through each
  393. of the address structures attempting to create and bind a socket to the
  394. address, until it performs a successful
  395. \fIbind\fR().
  396. .sp
  397. .RS 4
  398. .nf
  399. #include <stdio.h>
  400. #include <stdlib.h>
  401. #include <unistd.h>
  402. #include <string.h>
  403. #include <sys/socket.h>
  404. #include <netdb.h>
  405. .P
  406. int
  407. main(int argc, char *argv[])
  408. {
  409. struct addrinfo *result, *rp;
  410. int sfd, s;
  411. .P
  412. if (argc != 2) {
  413. fprintf(stderr, "Usage: %s port\en", argv[0]);
  414. exit(EXIT_FAILURE);
  415. }
  416. .P
  417. struct addrinfo hints = {0};
  418. hints.ai_family = AF_UNSPEC;
  419. hints.ai_socktype = SOCK_DGRAM;
  420. hints.ai_flags = AI_PASSIVE;
  421. hints.ai_protocol = 0;
  422. .P
  423. s = getaddrinfo(NULL, argv[1], &hints, &result);
  424. if (s != 0) {
  425. fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s));
  426. exit(EXIT_FAILURE);
  427. }
  428. .P
  429. /* getaddrinfo() returns a list of address structures.
  430. Try each address until a successful bind().
  431. If socket(2) (or bind(2)) fails, close the socket
  432. and try the next address. */
  433. .P
  434. for (rp = result; rp != NULL; rp = rp->ai_next) {
  435. sfd = socket(rp->ai_family, rp->ai_socktype,
  436. rp->ai_protocol);
  437. if (sfd == -1)
  438. continue;
  439. .P
  440. if (bind(sfd, rp->ai_addr, rp->ai_addrlen) == 0)
  441. break; /* Success */
  442. .P
  443. close(sfd);
  444. }
  445. .P
  446. if (rp == NULL) { /* No address succeeded */
  447. fprintf(stderr, "Could not bind\en");
  448. exit(EXIT_FAILURE);
  449. }
  450. .P
  451. freeaddrinfo(result); /* No longer needed */
  452. .P
  453. /* ... use socket bound to sfd ... */
  454. }
  455. .fi
  456. .P
  457. .RE
  458. .SH "APPLICATION USAGE"
  459. If the caller handles only TCP and not UDP, for example, then the
  460. .IR ai_protocol
  461. member of the
  462. .IR hints
  463. structure should be set to IPPROTO_TCP when
  464. \fIgetaddrinfo\fR()
  465. is called.
  466. .P
  467. If the caller handles only IPv4 and not IPv6, then the
  468. .IR ai_family
  469. member of the
  470. .IR hints
  471. structure should be set to AF_INET when
  472. \fIgetaddrinfo\fR()
  473. is called.
  474. .P
  475. Although it is common practice to initialize the
  476. .IR hints
  477. structure using:
  478. .sp
  479. .RS 4
  480. .nf
  481. struct addrinfo hints;
  482. memset(&hints, 0, sizeof hints);
  483. .fi
  484. .P
  485. .RE
  486. .P
  487. this method is not portable according to this standard, because
  488. the structure can contain pointer or floating-point members that
  489. are not required to have an all-bits-zero representation after
  490. default initialization. Portable methods make use of default
  491. initialization; for example:
  492. .sp
  493. .RS 4
  494. .nf
  495. struct addrinfo hints = { 0 };
  496. .fi
  497. .P
  498. .RE
  499. .P
  500. or:
  501. .sp
  502. .RS 4
  503. .nf
  504. static struct addrinfo hints_init;
  505. struct addrinfo hints = hints_init;
  506. .fi
  507. .P
  508. .RE
  509. .P
  510. A future version of this standard may require that a pointer object
  511. with an all-bits-zero representation is a null pointer, and that
  512. .BR addrinfo
  513. does not have any floating-point members if a floating-point
  514. object with an all-bits-zero representation does not have the value 0.0.
  515. .P
  516. The term ``canonical name'' is misleading; it is taken from the Domain
  517. Name System (RFC\ 2181). It should be noted that the canonical name is
  518. a result of alias processing, and not necessarily a unique attribute of
  519. a host, address, or set of addresses. See RFC\ 2181 for more discussion
  520. of this in the Domain Name System context.
  521. .SH "RATIONALE"
  522. None.
  523. .SH "FUTURE DIRECTIONS"
  524. None.
  525. .SH "SEE ALSO"
  526. .IR "\fIconnect\fR\^(\|)",
  527. .IR "\fIendservent\fR\^(\|)",
  528. .IR "\fIgai_strerror\fR\^(\|)",
  529. .IR "\fIgetnameinfo\fR\^(\|)",
  530. .IR "\fIsocket\fR\^(\|)"
  531. .P
  532. The Base Definitions volume of POSIX.1\(hy2017,
  533. .IR "\fB<netdb.h>\fP",
  534. .IR "\fB<sys_socket.h>\fP"
  535. .\"
  536. .SH COPYRIGHT
  537. Portions of this text are reprinted and reproduced in electronic form
  538. from IEEE Std 1003.1-2017, Standard for Information Technology
  539. -- Portable Operating System Interface (POSIX), The Open Group Base
  540. Specifications Issue 7, 2018 Edition,
  541. Copyright (C) 2018 by the Institute of
  542. Electrical and Electronics Engineers, Inc and The Open Group.
  543. In the event of any discrepancy between this version and the original IEEE and
  544. The Open Group Standard, the original IEEE and The Open Group Standard
  545. is the referee document. The original Standard can be obtained online at
  546. http://www.opengroup.org/unix/online.html .
  547. .PP
  548. Any typographical or formatting errors that appear
  549. in this page are most likely
  550. to have been introduced during the conversion of the source files to
  551. man page format. To report such errors, see
  552. https://www.kernel.org/doc/man-pages/reporting_bugs.html .