getaddrinfo.html

posix标准英文,html格式

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 error 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>
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>
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>
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>

<p>The term ``canonical name'' is misleading; it is taken from the Domain Name System (RFC&nbsp;2181). It should be noted that the
canonical name is a result of alias processing, and not necessarily a unique attribute of a host, address, or set of addresses. See
RFC&nbsp;2181 for more discussion of this in the Domain Name System context.</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&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/netdb.h.html"><i>&lt;netdb.h&gt;</i></a>, <a href=
"../basedefs/sys/socket.h.html"><i>&lt;sys/socket.h&gt;</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&nbsp;9899:1999
standard.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XSH/TC1/D6/19 is applied, adding three notes to the DESCRIPTION and adding text
to the APPLICATION USAGE related to the term ``canonical name''. A reference to RFC&nbsp;2181 is also added to the Informative
References.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XSH/TC1/D6/20 is applied, making changes for alignment with IPv6. These include
the following:</p>

<ul>
<li>
<p>Adding AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG to the allowed values for the <i>ai_flags</i> field</p>
</li>

<li>
<p>Adding a description of AI_ADDRCONFIG</p>
</li>

<li>
<p>Adding a description of the consequences of ignoring the AI_PASSIVE flag.</p>
</li>
</ul>

<p>IEEE&nbsp;Std&nbsp;1003.1-2001/Cor&nbsp;2-2004, item XSH/TC2/D6/39 is applied, changing ``corresponding value'' to
``corresponding error value'' in the ERRORS section.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; 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>