ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/getaddrinfo.htm

463 lines
17 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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>
&nbsp;&nbsp;Syntax
<pre>
#include &lt;sys/socket.h&gt;
#include &lt;netdb.h&gt;
int getaddrinfo(const char *nodename, const char *servname,
const struct addrinfo *hints,
struct addrinfo **res);
</pre>
<br>
&nbsp;&nbsp;Service Program Name: QSOSRV2<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;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>&lt;netdb.h&gt;</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>