📄 getaddrinfo.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-2004 IEEE and 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, 2004 Edition<br>Copyright © 2001-2004 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>(), alongwith any additional storage associated with those structures. If the <i>ai_next</i> field of the structure is not null, the entirelist 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 servicename and shall return a set of socket addresses and associated information to be used in creating a socket with which to addressthe specified service. <basefont size="2"></p><dl><dt><b>Note:</b></dt><dd>In many cases it is implemented by the Domain Name System, as documented in RFC 1034, RFC 1035, andRFC 1886.</dd></dl><basefont size="3"> <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 bothof 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 beinterpreted as valid within multiple supported families, the implementation shall attempt to resolve the name in all supportedfamilies 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 addressfamily 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, validdescriptive names include host names. If the specified address family is AF_INET or AF_UNSPEC, address strings using Internetstandard 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 servicelocation 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 anumeric representation suitable for use with the address family or families. If the specified address family is AF_INET, <sup>[<ahref="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 astring 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 byproviding 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> shallbe 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 astructure containing the value zero for the <i>ai_flags</i>, <i>ai_socktype</i>, and <i>ai_protocol</i> fields, and AF_UNSPEC forthe <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 oneor more of the values AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG.</p><p>If the AI_PASSIVE flag is specified, the returned address information shall be suitable for use in binding a socket foraccepting incoming connections for the specified service. In this case, if the <i>nodename</i> argument is null, then the IPaddress portion of the socket address structure shall be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6address. 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 isnull, then the IP address portion of the socket address structure shall be set to the loopback address. The AI_PASSIVE flag shallbe ignored if the <i>nodename</i> argument is not null.</p><p>If the AI_CANONNAME flag is specified and the <i>nodename</i> argument is not null, the function shall attempt to determine thecanonical name corresponding to <i>nodename</i> (for example, if <i>nodename</i> is an alias or shorthand notation for a completename). <basefont size="2"></p><dl><dt><b>Note:</b></dt><dd>Since different implementations use different conceptual models, the terms ``canonical name'' and ``alias'' cannot be preciselydefined for the general case. However, Domain Name System implementations are expected to interpret them as they are used inRFC 1034. <p>A numeric host address string is not a ``name'', and thus does not have a ``canonical name'' form; no address to host nametranslation is performed. See below for handling of the case where a canonical name cannot be obtained.</p></dd></dl><basefont size="3"> <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-mappedIPv6 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 allmatching 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>If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be returned only if an IPv4 address is configured on the localsystem, <sup>[<a href="javascript:open_code('IP6')">IP6</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> and IPv6 addresses shall be returned only if an IPv6 address is configured on the local system. <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 <ahref="socket.html"><i>socket</i>()</a>. If a specific socket type is not given (for example, a value of zero) and the service namecould be interpreted as valid with multiple supported socket types, the implementation shall attempt to resolve the service namefor all supported socket types and, in the absence of errors, all possible results shall be returned. A non-zero socket type valueshall 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 anyaddress family that can be used with the specified <i>nodename</i> and/or <i>servname</i>. Otherwise, addresses shall be returnedfor use only with the specified address family. If <i>ai_family</i> is not AF_UNSPEC and <i>ai_protocol</i> is not zero, thenaddresses are returned for use only with the specified address family and protocol; the value of <i>ai_protocol</i> shall beinterpreted 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. Thepossible 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 touse that socket address. The list shall include at least one <b>addrinfo</b> structure. The <i>ai_next</i> field of each structure⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -