289 lines
16 KiB
HTML
289 lines
16 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>freeaddrinfo</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="freeaddrinfo"></a> <a name="tag_03_187"></a><!-- freeaddrinfo -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_187_01"></a>NAME</h4>
|
|
|
|
<blockquote>freeaddrinfo, getaddrinfo - get address information</blockquote>
|
|
|
|
<h4><a name="tag_03_187_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<p><code><tt>#include <<a href="../basedefs/sys/socket.h.html">sys/socket.h</a>><br>
|
|
#include <<a href="../basedefs/netdb.h.html">netdb.h</a>><br>
|
|
<br>
|
|
void freeaddrinfo(struct addrinfo *</tt><i>ai</i><tt>);<br>
|
|
int getaddrinfo(const char *restrict</tt> <i>nodename</i><tt>,<br>
|
|
const char *restrict</tt> <i>servname</i><tt>,<br>
|
|
const struct addrinfo *restrict</tt> <i>hints</i><tt>,<br>
|
|
struct addrinfo **restrict</tt> <i>res</i><tt>);<br>
|
|
</tt></code></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_187_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>freeaddrinfo</i>() function shall free one or more <b>addrinfo</b> structures returned by <i>getaddrinfo</i>(), along
|
|
with any additional storage associated with those structures. If the <i>ai_next</i> field of the structure is not null, the entire
|
|
list of structures shall be freed. The <i>freeaddrinfo</i>() function shall support the freeing of arbitrary sublists of an
|
|
<b>addrinfo</b> list originally returned by <i>getaddrinfo</i>().</p>
|
|
|
|
<p>The <i>getaddrinfo</i>() function shall translate the name of a service location (for example, a host name) and/or a service
|
|
name and shall return a set of socket addresses and associated information to be used in creating a socket with which to address
|
|
the specified service.</p>
|
|
|
|
<p>The <i>freeaddrinfo</i>() and <i>getaddrinfo</i>() functions shall be thread-safe.</p>
|
|
|
|
<p>The <i>nodename</i> and <i>servname</i> arguments are either null pointers or pointers to null-terminated strings. One or both
|
|
of these two arguments shall be supplied by the application as a non-null pointer.</p>
|
|
|
|
<p>The format of a valid name depends on the address family or families. If a specific family is not given and the name could be
|
|
interpreted as valid within multiple supported families, the implementation shall attempt to resolve the name in all supported
|
|
families and, in absence of errors, one or more results shall be returned.</p>
|
|
|
|
<p>If the <i>nodename</i> argument is not null, it can be a descriptive name or can be an address string. If the specified address
|
|
family is AF_INET, <sup>[<a href="javascript:open_code('IP6')">IP6</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> AF_INET6, <img src="../images/opt-end.gif" alt="[Option End]" border="0"> or AF_UNSPEC, valid
|
|
descriptive names include host names. If the specified address family is AF_INET or AF_UNSPEC, address strings using Internet
|
|
standard dot notation as specified in <a href="inet_addr.html"><i>inet_addr</i>()</a> are valid.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('IP6')">IP6</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6 text forms described in <a href=
|
|
"inet_ntop.html"><i>inet_ntop</i>()</a> are valid. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
|
|
|
|
<p>If <i>nodename</i> is not null, the requested service location is named by <i>nodename</i>; otherwise, the requested service
|
|
location is local to the caller.</p>
|
|
|
|
<p>If <i>servname</i> is null, the call shall return network-level addresses for the specified <i>nodename.</i> If <i>servname</i>
|
|
is not null, it is a null-terminated character string identifying the requested service. This can be either a descriptive name or a
|
|
numeric representation suitable for use with the address family or families. If the specified address family is AF_INET, <sup>[<a
|
|
href="javascript:open_code('IP6')">IP6</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
AF_INET6, <img src="../images/opt-end.gif" alt="[Option End]" border="0"> or AF_UNSPEC, the service can be specified as a
|
|
string specifying a decimal port number.</p>
|
|
|
|
<p>If the <i>hints</i> argument is not null, it refers to a structure containing input values that may direct the operation by
|
|
providing options and by limiting the returned information to a specific socket type, address family, and/or protocol. In this
|
|
<i>hints</i> structure every member other than <i>ai_flags</i>, <i>ai_family</i>, <i>ai_socktype</i>, and <i>ai_protocol</i> shall
|
|
be set to zero or a null pointer. A value of AF_UNSPEC for <i>ai_family</i> means that the caller shall accept any address family.
|
|
A value of zero for <i>ai_socktype</i> means that the caller shall accept any socket type. A value of zero for <i>ai_protocol</i>
|
|
means that the caller shall accept any protocol. If <i>hints</i> is a null pointer, the behavior shall be as if it referred to a
|
|
structure containing the value zero for the <i>ai_flags</i>, <i>ai_socktype</i>, and <i>ai_protocol</i> fields, and AF_UNSPEC for
|
|
the <i>ai_family</i> field.</p>
|
|
|
|
<p>The <i>ai_flags</i> field to which the <i>hints</i> parameter points shall be set to zero or be the bitwise-inclusive OR of one
|
|
or more of the values AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, and AI_NUMERICSERV.</p>
|
|
|
|
<p>If the AI_PASSIVE flag is specified, the returned address information shall be suitable for use in binding a socket for
|
|
accepting incoming connections for the specified service. In this case, if the <i>nodename</i> argument is null, then the IP
|
|
address portion of the socket address structure shall be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
|
|
address. If the AI_PASSIVE flag is not specified, the returned address information shall be suitable for a call to <a href=
|
|
"../functions/connect.html"><i>connect</i>()</a> (for a connection-mode protocol) or for a call to <a href=
|
|
"../functions/connect.html"><i>connect</i>()</a>, <a href="../functions/sendto.html"><i>sendto</i>()</a>, or <a href=
|
|
"../functions/sendmsg.html"><i>sendmsg</i>()</a> (for a connectionless protocol). In this case, if the <i>nodename</i> argument is
|
|
null, then the IP address portion of the socket address structure shall be set to the loopback address.</p>
|
|
|
|
<p>If the AI_CANONNAME flag is specified and the <i>nodename</i> argument is not null, the function shall attempt to determine the
|
|
canonical name corresponding to <i>nodename</i> (for example, if <i>nodename</i> is an alias or shorthand notation for a complete
|
|
name).</p>
|
|
|
|
<p>If the AI_NUMERICHOST flag is specified, then a non-null <i>nodename</i> string supplied shall be a numeric host address string.
|
|
Otherwise, an [EAI_NONAME] error is returned. This flag shall prevent any type of name resolution service (for example, the DNS)
|
|
from being invoked.</p>
|
|
|
|
<p>If the AI_NUMERICSERV flag is specified, then a non-null <i>servname</i> string supplied shall be a numeric port string.
|
|
Otherwise, an [EAI_NONAME] error shall be returned. This flag shall prevent any type of name resolution service (for example, NIS+)
|
|
from being invoked.</p>
|
|
|
|
<p><sup>[<a href="javascript:open_code('IP6')">IP6</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
If the AI_V4MAPPED flag is specified along with an <i>ai_family</i> of AF_INET6, then <i>getaddrinfo</i>() shall return IPv4-mapped
|
|
IPv6 addresses on finding no matching IPv6 addresses ( <i>ai_addrlen</i> shall be 16). The AI_V4MAPPED flag shall be ignored unless
|
|
<i>ai_family</i> equals AF_INET6. If the AI_ALL flag is used with the AI_V4MAPPED flag, then <i>getaddrinfo</i>() shall return all
|
|
matching IPv6 and IPv4 addresses. The AI_ALL flag without the AI_V4MAPPED flag is ignored. <img src="../images/opt-end.gif" alt=
|
|
"[Option End]" border="0"></p>
|
|
|
|
<p>The <i>ai_socktype</i> field to which argument <i>hints</i> points specifies the socket type for the service, as defined in <a
|
|
href="socket.html"><i>socket</i>()</a> . If a specific socket type is not given (for example, a value of zero) and the service name
|
|
could be interpreted as valid with multiple supported socket types, the implementation shall attempt to resolve the service name
|
|
for all supported socket types and, in the absence of errors, all possible results shall be returned. A non-zero socket type value
|
|
shall limit the returned information to values with the specified socket type.</p>
|
|
|
|
<p>If the <i>ai_family</i> field to which <i>hints</i> points has the value AF_UNSPEC, addresses shall be returned for use with any
|
|
address family that can be used with the specified <i>nodename</i> and/or <i>servname</i>. Otherwise, addresses shall be returned
|
|
for use only with the specified address family. If <i>ai_family</i> is not AF_UNSPEC and <i>ai_protocol</i> is not zero, then
|
|
addresses are returned for use only with the specified address family and protocol; the value of <i>ai_protocol</i> shall be
|
|
interpreted as in a call to the <a href="../functions/socket.html"><i>socket</i>()</a> function with the corresponding values of
|
|
<i>ai_family</i> and <i>ai_protocol</i>.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_187_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>A zero return value for <i>getaddrinfo</i>() indicates successful completion; a non-zero return value indicates failure. The
|
|
possible values for the failures are listed in the ERRORS section.</p>
|
|
|
|
<p>Upon successful return of <i>getaddrinfo</i>(), the location to which <i>res</i> points shall refer to a linked list of
|
|
<b>addrinfo</b> structures, each of which shall specify a socket address and information for use in creating a socket with which to
|
|
use that socket address. The list shall include at least one <b>addrinfo</b> structure. The <i>ai_next</i> field of each structure
|
|
contains a pointer to the next structure on the list, or a null pointer if it is the last structure on the list. Each structure on
|
|
the list shall include values for use with a call to the <a href="../functions/socket.html"><i>socket</i>()</a> function, and a
|
|
socket address for use with the <a href="../functions/connect.html"><i>connect</i>()</a> function or, if the AI_PASSIVE flag was
|
|
specified, for use with the <a href="../functions/bind.html"><i>bind</i>()</a> function. The fields <i>ai_family</i>,
|
|
<i>ai_socktype</i>, and <i>ai_protocol</i> shall be usable as the arguments to the <a href=
|
|
"../functions/socket.html"><i>socket</i>()</a> function to create a socket suitable for use with the returned address. The fields
|
|
<i>ai_addr</i> and <i>ai_addrlen</i> are usable as the arguments to the <a href="../functions/connect.html"><i>connect</i>()</a> or
|
|
<a href="../functions/bind.html"><i>bind</i>()</a> functions with such a socket, according to the AI_PASSIVE flag.</p>
|
|
|
|
<p>If <i>nodename</i> is not null, and if requested by the AI_CANONNAME flag, the <i>ai_canonname</i> field of the first returned
|
|
<b>addrinfo</b> structure shall point to a null-terminated string containing the canonical name corresponding to the input
|
|
<i>nodename</i>; if the canonical name is not available, then <i>ai_canonname</i> shall refer to the <i>nodename</i> argument or a
|
|
string with the same contents. The contents of the <i>ai_flags</i> field of the returned structures are undefined.</p>
|
|
|
|
<p>All fields in socket address structures returned by <i>getaddrinfo</i>() that are not filled in through an explicit argument
|
|
(for example, <i>sin6_flowinfo</i>) shall be set to zero. <basefont size="2"></p>
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>This makes it easier to compare socket address structures.</dd>
|
|
</dl>
|
|
|
|
<basefont size="3"></blockquote>
|
|
|
|
<h4><a name="tag_03_187_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>getaddrinfo</i>() function shall fail and return the corresponding value if:</p>
|
|
|
|
<dl compact>
|
|
<dt>[EAI_AGAIN]</dt>
|
|
|
|
<dd>The name could not be resolved at this time. Future attempts may succeed.</dd>
|
|
|
|
<dt>[EAI_BADFLAGS]</dt>
|
|
|
|
<dd><br>
|
|
The <i>flags</i> parameter had an invalid value.</dd>
|
|
|
|
<dt>[EAI_FAIL]</dt>
|
|
|
|
<dd>A non-recoverable error occurred when attempting to resolve the name.</dd>
|
|
|
|
<dt>[EAI_FAMILY]</dt>
|
|
|
|
<dd>The address family was not recognized.</dd>
|
|
|
|
<dt>[EAI_MEMORY]</dt>
|
|
|
|
<dd>There was a memory allocation failure when trying to allocate storage for the return value.</dd>
|
|
|
|
<dt>[EAI_NONAME]</dt>
|
|
|
|
<dd>The name does not resolve for the supplied parameters.
|
|
|
|
<p>Neither <i>nodename</i> nor <i>servname</i> were supplied. At least one of these shall be supplied.</p>
|
|
</dd>
|
|
|
|
<dt>[EAI_SERVICE]</dt>
|
|
|
|
<dd>The service passed was not recognized for the specified socket type.</dd>
|
|
|
|
<dt>[EAI_SOCKTYPE]</dt>
|
|
|
|
<dd><br>
|
|
The intended socket type was not recognized.</dd>
|
|
|
|
<dt>[EAI_SYSTEM]</dt>
|
|
|
|
<dd>A system error occurred; the error code can be found in <i>errno</i>.</dd>
|
|
|
|
<dt>[EAI_OVERFLOW]</dt>
|
|
|
|
<dd><br>
|
|
An argument buffer overflowed.</dd>
|
|
</dl>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_187_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_187_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>If the caller handles only TCP and not UDP, for example, then the <i>ai_protocol</i> member of the <i>hints</i> structure should
|
|
be set to IPPROTO_TCP when <i>getaddrinfo</i>() is called.</p>
|
|
|
|
<p>If the caller handles only IPv4 and not IPv6, then the <i>ai_family</i> member of the <i>hints</i> structure should be set to
|
|
AF_INET when <i>getaddrinfo</i>() is called.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_187_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_187_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_187_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="connect.html"><i>connect</i>()</a> , <a href="gai_strerror.html"><i>gai_strerror</i>()</a> , <a href=
|
|
"gethostbyaddr.html"><i>gethostbyaddr</i>()</a> , <a href="getnameinfo.html"><i>getnameinfo</i>()</a> , <a href=
|
|
"getservbyname.html"><i>getservbyname</i>()</a> , <a href="socket.html"><i>socket</i>()</a> , the Base Definitions volume of
|
|
IEEE Std 1003.1-2001, <a href="../basedefs/netdb.h.html"><i><netdb.h></i></a>, <a href=
|
|
"../basedefs/sys/socket.h.html"><i><sys/socket.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_187_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 6. Derived from the XNS, Issue 5.2 specification.</p>
|
|
|
|
<p>The <b>restrict</b> keyword is added to the <i>getaddrinfo</i>() prototype for alignment with the ISO/IEC 9899:1999
|
|
standard.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|