463 lines
17 KiB
HTML
463 lines
17 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>getaddrinfo--Get Address Information API</title>
|
|
<!-- Begin Header Records -->
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Change History: -->
|
|
<!-- Created for V5R2 by Chris Gloe -->
|
|
<!-- Edited by Kersten Feb 02 -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<!-- End Header Records -->
|
|
<!-- Java sync-link -->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<a name="Top_Of_Page"></a>
|
|
|
|
<h2>getaddrinfo()--Get Address
|
|
Information</h2>
|
|
|
|
<div class="box" style="width: 80%;">
|
|
<br>
|
|
Syntax
|
|
|
|
<pre>
|
|
#include <sys/socket.h>
|
|
#include <netdb.h>
|
|
|
|
int getaddrinfo(const char *nodename, const char *servname,
|
|
const struct addrinfo *hints,
|
|
struct addrinfo **res);
|
|
|
|
</pre>
|
|
|
|
<br>
|
|
Service Program Name: QSOSRV2<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The <strong>getaddrinfo()</strong> function translates the name of a service
|
|
location (for example, a host name) and/or a service name and returns a set of
|
|
socket addresses and associated information to be used in creating a socket
|
|
with which to address the specified service.</p>
|
|
|
|
<br>
|
|
<h3>Parameters</h3>
|
|
|
|
<p>The <em>nodename</em> and <em>servname</em> parameters are either null
|
|
pointers or pointers to null-terminated strings. One or both of these two
|
|
parameters must be a non-null pointer.</p>
|
|
|
|
<p>The format of a valid name depends on the protocol family or families. If a
|
|
specific family is not given and the name could be interpreted as valid within
|
|
multiple supported families, the implementation will attempt to resolve the
|
|
name in all supported families and, in the absence of errors, one or more
|
|
results shall be returned.</p>
|
|
|
|
<dl>
|
|
<dt><strong>nodename</strong></dt>
|
|
|
|
<dd>(Input) The pointer to the null-terminated character string that contains
|
|
the descriptive name or address string for which the address information is to
|
|
be retrieved. If the <strong>servname</strong> parameter is null, a
|
|
<strong>nodename</strong> must be specified and the requested network-level
|
|
address will be returned. If the <strong>nodename</strong> parameter is null, a
|
|
<strong>servname</strong> must be specified and the requested service location
|
|
will be assumed to be local to the caller. If the specified address family is
|
|
AF_INET, AF_INET6, or AF_UNSPEC, valid descriptive names include host names. If
|
|
the specified address family is AF_INET, AF_INET6, or AF_UNSPEC, the
|
|
permissable address string formats for the <em>nodename</em> parameter are
|
|
specified as defined in <a href="inet_pton.htm">inet_pton().</a><br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>servname</strong></dt>
|
|
|
|
<dd>(Input) The pointer to the null-terminated character string that contains
|
|
the descriptive name or numeric representation suitable for use with the
|
|
address family or families for which the requested service information is to be
|
|
retrieved. If nodename is not null, the requested service location is named by
|
|
<strong>nodename</strong>; otherwise, the requested service location is local
|
|
to the caller. If the specified address family is AF_INET, AF_INET6, or
|
|
AF_UNSPEC, the service can be specified as a string specifying a decimal port
|
|
number.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>hints</strong><br>
|
|
</dt>
|
|
|
|
<dd>(Input) The pointer to a <strong>struct addrinfo</strong>. If the parameter
|
|
<strong>hints</strong> 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 hints structure every member other than <em>ai_flags</em>,
|
|
<em>ai_family</em>, <em>ai_socktype</em> and <em>ai_protocol</em> must be zero
|
|
or a null pointer. If hints is a null pointer, the behavior will be as if it
|
|
referred to a structure containing the value zero for the <em>ai_flags</em>,
|
|
<em>ai_socktype</em> and <em>ai_protocol</em> fields, and AF_UNSPEC for the
|
|
<em>ai_family</em> field.
|
|
|
|
<p>The structure <strong>struct addrinfo</strong> is defined in
|
|
<strong><netdb.h></strong>.</p>
|
|
|
|
<pre>
|
|
struct addrinfo {
|
|
int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, .. */
|
|
int ai_family; /* PF_xxx */
|
|
int ai_socktype; /* SOCK_xxx */
|
|
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
|
|
socklen_t ai_addrlen; /* length of ai_addr */
|
|
char *ai_canonname; /* canonical name for nodename */
|
|
struct sockaddr *ai_addr; /* binary address */
|
|
struct addrinfo *ai_next; /* next structure in linked list */
|
|
};
|
|
</pre>
|
|
|
|
<p>A value of AF_UNSPEC for <em>ai_family</em> means that the caller will
|
|
accept any protocol family. A value of zero for <em>ai_socktype</em> means that
|
|
the caller will accept any socket type. A value of zero for
|
|
<em>ai_protocol</em> means that the caller will accept any protocol.</p>
|
|
|
|
<p>If the caller handles only IPv4 and not IPv6, then the <em>ai_family</em>
|
|
member of the hints structure should be set to PF_INET when
|
|
<strong>getaddrinfo()</strong> is called.</p>
|
|
|
|
<p>If the caller handles only TCP and not UDP, for example, then the
|
|
<em>ai_protocol</em> member of the hints structure should be set to IPPROTO_TCP
|
|
when <strong>getaddrinfo()</strong> is called.</p>
|
|
|
|
<p>The <em>ai_flags</em> field to which hints parameter points must have the
|
|
value zero or be the bitwise OR of one or more of the values AI_PASSIVE,
|
|
AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED, AI_ALL, and
|
|
AI_ADDRCONFIG.</p>
|
|
|
|
<p>The AI_PASSIVE flag in the <em>ai_flags</em> member of the hints structure
|
|
specifies how to fill in the IP address portion of the socket address
|
|
structure. If the AI_PASSIVE flag is specified, then the returned address
|
|
information will be suitable for use in binding a socket for accepting incoming
|
|
connections for the specified service (that is, a call to <a href=
|
|
"bind.htm">bind()</a>). In this case, if the <strong>nodename</strong>
|
|
parameter is null, then the IP address portion of the socket address structure
|
|
will be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
|
|
address. If the AI_PASSIVE bit is not set, the returned address information
|
|
will be suitable for a call to <a href="connec.htm">connect()</a> (for a
|
|
connection-oriented protocol) or for a call to <a href=
|
|
"connec.htm">connect()</a>, <a href="sendto.htm">sendto()</a> or <a href=
|
|
"sendms.htm">sendmsg()</a> (for a connectionless protocol). In this case, if
|
|
the <strong>nodename</strong> parameter is null, then the IP address portion of
|
|
the socket address structure will be set to the loopback address. This flag is
|
|
ignored if the <strong>nodename</strong> parameter is not null.</p>
|
|
|
|
<p>If the flag AI_CANONNAME is specified and the <strong>nodename</strong>
|
|
parameter is not null, the function attempts to determine the canonical name
|
|
corresponding to nodename (for example, if <strong>nodename</strong> is an
|
|
alias or shorthand notation for a complete name).</p>
|
|
|
|
<p>If the flag AI_NUMERICHOST is specified then a non-null
|
|
<strong>nodename</strong> string must be a numeric host address string.
|
|
Otherwise an error of [EAI_NONAME] is returned. This flag prevents any type of
|
|
name resolution service (for example, the DNS) from being called.</p>
|
|
|
|
<p>If the flag AI_NUMERICSERV is specified then a non-null
|
|
<strong>servname</strong> string must be a numeric port string. Otherwise an
|
|
error [EAI_NONAME] is returned. This flag prevents any type of name resolution
|
|
service (for example, NIS+) from being called.</p>
|
|
|
|
<p>If the AI_V4MAPPED flag is specified along with an <em>ai_family</em> of
|
|
AF_INET6, then the caller will accept IPv4-mapped IPv6 addresses. That is, if
|
|
no AAAA records are found then a query is made for A records and any found are
|
|
returned as IPv4-mapped IPv6 addresses (<em>ai_addrlen</em> will be 28). The
|
|
AI_V4MAPPED flag is ignored unless <em>ai_family</em> equals AF_INET6.</p>
|
|
|
|
<p>The AI_ALL flag is used in conjunction with the AI_V4MAPPED flag, and is
|
|
only used with an <em>ai_family</em> of AF_INET6. When AI_ALL is logically or'd
|
|
with AI_V4MAPPED flag then the caller will accept all addresses: IPv6 and
|
|
IPv4-mapped IPv6. A query is first made for AAAA records and if successful, the
|
|
IPv6 addresses are returned. Another query is then made for A records and any
|
|
found are returned as IPv4-mapped IPv6 addresses (<em>ai_addrlen</em> will be
|
|
28). This flag is ignored unless <em>ai_family</em> equals AF_INET6.</p>
|
|
|
|
<p>If the AI_ADDRCONFIG flag is specified then a query for AAAA records will
|
|
occur only if the node has at least one IPv6 source address configured and a
|
|
query for A records will occur only if the node has at least one IPv4 source
|
|
address configured. The loopback address is not considered for this case as
|
|
valid as a configured source address.</p>
|
|
|
|
<p>The <em>ai_socktype</em> field to which argument hints points specifies the
|
|
socket type for the service. 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 will attempt to
|
|
resolve the service name for all supported socket types and, all successful
|
|
results will be returned. A non-zero socket type value will limit the returned
|
|
information to values with the specified socket type.</p>
|
|
</dd>
|
|
|
|
<dt><strong>res</strong></dt>
|
|
|
|
<dd>(Output) The pointer to a linked list of <strong>addrinfo</strong>
|
|
structures, each of which specifies a socket address and information for use in
|
|
creating a socket with which to use that socket address. The list will include
|
|
at least one <strong>addrinfo</strong> structure. The <em>ai_next</em> 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
|
|
includes values for use with a call to the <a href="socket.htm">socket()</a>
|
|
function, and a socket address for use with the <a href=
|
|
"connec.htm">connect()</a> function or, if the AI_PASSIVE flag was specified,
|
|
for use with the <a href="bind.htm">bind()</a> function. The fields
|
|
<em>ai_family</em>, <em>ai_socktype</em>, and <em>ai_protocol</em> are usable
|
|
as the arguments to the <a href="socket.htm">socket()</a> function to create a
|
|
socket suitable for use with the returned address. The fields <em>ai_addr</em>
|
|
and <em>ai_addrlen</em> are usable as the arguments to the <a href=
|
|
"connec.htm">connect()</a> or <a href="bind.htm">bind()</a> functions with such
|
|
a socket, according to the AI_PASSIVE flag.
|
|
|
|
<p>If nodename is not null, and if requested by the AI_CANONNAME flag, the
|
|
<em>ai_canonname</em> field of the first returned addrinfo structure points to
|
|
a null-terminated string containing the canonical name corresponding to the
|
|
input nodename; if the canonical name is not available, then
|
|
<em>ai_canonname</em> refers to the argument nodename or a string with the same
|
|
contents. The contents of the <em>ai_flags</em> field of the returned
|
|
structures is undefined.</p>
|
|
|
|
<p>All fields in socket address structures returned by
|
|
<strong>getaddrinfo()</strong> that are not filled in through an explicit
|
|
argument (for example, <em>sin6_flowinfo</em> and <em>sin_zero</em>) will be
|
|
set to zero.</p>
|
|
|
|
<p>Note: This makes it easier to compare socket address structures.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Authorities</h3>
|
|
|
|
<p>Authorization of *R (allow access to the object) to the host aliases file
|
|
specified by the <em>HOSTALIASES</em> environment variable.</p>
|
|
|
|
<p>You also need *X authority to each directory in the path of the host aliases
|
|
file.</p>
|
|
|
|
<br>
|
|
<h3>Return Value</h3>
|
|
|
|
<p><em>getaddrinfo()</em> returns an integer. Possible values are:</p>
|
|
|
|
|
|
<ul>
|
|
<li>0 (successful)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>non-zero (unsuccessful)<br>
|
|
<br>
|
|
</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Conditions</h3>
|
|
<p>When <em>getaddrinfo()</em> fails, the error return value can be set to one
|
|
of the following:</p>
|
|
<dl>
|
|
<dt><em>[EAI_AGAIN]</em></dt>
|
|
<dd><p>The name could not be resolved at this time. Future attempts may succeed.</p></dd>
|
|
|
|
<dt><em>[EAI_BADFLAGS]</em></dt>
|
|
<dd><p>The flags parameter had an invalid value.</p></dd>
|
|
|
|
|
|
<dt><em>[EAI_FAIL]</em></dt>
|
|
<dd><p>A non-recoverable error occurred when attempting
|
|
to resolve the name.</p></dd>
|
|
|
|
<dt><em>[EAI_FAMILY]</em></dt>
|
|
<dd><p>The address family was not recognized.</p></dd>
|
|
|
|
|
|
<dt><em>[EAI_MEMORY]</em></dt>
|
|
<dd><p>There was a memory allocation failure when trying
|
|
to allocate storage for the return value.</p></dd>
|
|
|
|
|
|
<dt><em>[EAI_NONAME]</em></dt>
|
|
<dd><p>The name does not resolve for the supplied
|
|
parameters. Neither <strong>nodename</strong> nor <strong>servname</strong>
|
|
were passed. At least one of these must be passed.</p></dd>
|
|
|
|
|
|
<dt><em>[EAI_SERVICE]</em></dt>
|
|
<dd><p>The service passed was not recognized for the
|
|
specified socket type.</p></dd>
|
|
|
|
|
|
<dt><em>[EAI_SOCKTYPE]</em></dt>
|
|
<dd><p>The intended socket type was not recognized.</p></dd>
|
|
|
|
|
|
<dt><em>[EAI_SYSTEM]</em></dt>
|
|
<dd><p>A system error occurred; the error code can be
|
|
found in <em>errno</em></p></dd>
|
|
|
|
</dl>
|
|
|
|
|
|
<h3>Usage Notes</h3>
|
|
|
|
<ol>
|
|
<li>The <a href="freeaddrinfo.htm">freeaddrinfo()</a> API <strong>must</strong>
|
|
be used to free the <em>addrinfo</em> structures returned by
|
|
<strong>getaddrinfo()</strong>.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The <a href="gai_strerror.htm">gai_strerror()</a> API may be used to
|
|
retrieve an error message associated with one of the error return values
|
|
described above.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>A job has a coded character set identifier (CCSID) and a default CCSID. The
|
|
default CCSID is the same as the job CCSID unless the job CCSID specifies
|
|
65535, which requests that no database translation be performed. In this case,
|
|
the default CCSID is set by the system based on the language ID in effect for
|
|
the job.
|
|
|
|
<p>If the address information is retrieved from the domain name server, sockets
|
|
converts the address information specified by the <em>nodename</em> and
|
|
<em>servname</em> parameters from the default (CCSID) to ASCII before
|
|
communicating with the domain name server. If the address information is
|
|
retrieved from the host database file, no conversion is done on the node and
|
|
service names specified by the <em>nodename</em> and <em>servname</em>
|
|
parameters unless the CCSID of the job is something other than 65535.</p>
|
|
|
|
<p>In addition, the canonical names for nodename returned in the addrinfo
|
|
structures will be returned in the default CCSID of the job if they are
|
|
obtained from the domain name server. For conversion to occur for the canonical
|
|
names returned in the addrinfo structures when they are obtained from the host
|
|
database file, you must use a job CCSID of something other than 65535.</p>
|
|
</li>
|
|
|
|
<li>The host database file currently only supports IPv4 addresses.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>
|
|
<img src="delta.gif" alt="Start of change">
|
|
<em>getaddrinfo()</em> has been extended to allow scope zone name or scope zone
|
|
index to be appended to <em>nodename</em>. For example:
|
|
|
|
<pre>
|
|
www.ibm.com%8 or www.ibm.com%ethline
|
|
FE80::1%8 or FE80::1%ethline
|
|
</pre>
|
|
If appended, the <em>sin6_scope_id</em> field in the <em>sockaddr_in6</em> structure
|
|
pointed to by <em>ai_addr</em> will be
|
|
set to the interger value associated with the appended value.<br>
|
|
<br>
|
|
<img src="deltaend.gif" alt="End of change">
|
|
</li>
|
|
|
|
<li>When you develop in C-based languages and an application is compiled with
|
|
the _XOPEN_SOURCE macro defined to the value 520 or greater, the
|
|
<em>getaddrinfo()</em> API is mapped to <em>qetaddrinfo98()</em>.</li>
|
|
</ol>
|
|
|
|
<br>
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li><a href="_xopen_source.htm">_XOPEN_SOURCE</a>--Using _XOPEN_SOURCE for the
|
|
UNIX 98 compatible interface<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="bind.htm">bind()</a>--Set a Local Address for the Socket<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="connec.htm">connect()</a>--Establish Connection or Destination
|
|
Address<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="freeaddrinfo.htm">freeaddrinfo()</a>--Free Address Information<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="gai_strerror.htm">gai_strerror()</a>--Retrieve Address Information
|
|
Runtime Error Message<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="ghostnm.htm">gethostbyname()</a>--Get Host Information for Host
|
|
Name<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="getnameinfo.htm">getnameinfo()</a>--Get Name Information for Socket
|
|
Address<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="gsrvnm.htm">getservbyname()</a>--Get Port Number for Service
|
|
Name<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="gsrvprt.htm">getservbyport()</a>--Get Service Name for Port
|
|
Number<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="inet_pton.htm">inet_pton()</a>--Convert IPv4 and IPv6 Addresses
|
|
Between Text and Binary Form<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="sendto.htm">sendto()</a>--Send Data<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="sendms.htm">sendmsg()</a>--Send Data or Descriptors or Both<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="socket.htm">socket()</a>--Create a Socket<br>
|
|
<br>
|
|
</li>
|
|
</ul>
|
|
|
|
<br>
|
|
<hr>
|
|
API introduced: V5R2
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a> </td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|