300 lines
8.5 KiB
HTML
300 lines
8.5 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>getnameinfo--Get Name Information for Socket Address 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>getnameinfo()--Get Name
|
||
|
|
Information for Socket Address</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 80%;"><br>
|
||
|
|
Syntax
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <sys/socket.h>
|
||
|
|
#include <netdb.h>
|
||
|
|
|
||
|
|
int getnameinfo(const struct sockaddr *sa, socklen_t salen,
|
||
|
|
char *nodename, socklen_t nodenamelen,
|
||
|
|
char *servname, socklen_t servnamelen,
|
||
|
|
int flags);
|
||
|
|
</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><em>getnameinfo()</em></strong> function translates a socket
|
||
|
|
address to a node name and service location, all of which are defined as with
|
||
|
|
<a href="getaddrinfo.htm">getaddrinfo()</a>.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>sa</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) The pointer to a socket address structure to be translated.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>salen</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) The length of the socket address structure pointed to by
|
||
|
|
<em>sa</em>.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>nodename</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Output) If the <em>nodename</em> parameter is non-NULL and the
|
||
|
|
<em>nodenamelen</em> parameter is nonzero, then the <em>nodename</em> parameter
|
||
|
|
must point to a buffer able to contain up to <em>nodenamelen</em> characters
|
||
|
|
that will receive the node name as a null-terminated string. If the
|
||
|
|
<em>nodename</em> parameter is NULL or the <em>nodenamelen</em> parameter is
|
||
|
|
zero, the node name will not be returned. If the node's name cannot be located,
|
||
|
|
the numeric form of the nodes address is returned instead of its name.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>nodenamelen</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) The length of the buffer pointed to by <em>nodename</em><br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><em>servname</em></strong></dt>
|
||
|
|
|
||
|
|
<dd>(Output) If the <em>servname</em> parameter is non-NULL and the
|
||
|
|
<em>servnamelen</em> parameter is nonzero, then the <em>servname</em> parameter
|
||
|
|
must point to a buffer able to contain up to <em>servnamelen</em> characters
|
||
|
|
that will receive the service name as a null-terminated string. If the
|
||
|
|
<em>servname</em> parameter is NULL or the <em>servnamelen</em> parameter is
|
||
|
|
zero, the service name will not be returned. If the service name cannot be
|
||
|
|
located, the numeric form of the service address (for example, its port number)
|
||
|
|
is returned instead of its name.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>servnamelen</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) The length of the buffer pointed to by <em>servname</em><br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>flags</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) A flag that changes the default actions of the function. By default
|
||
|
|
the fully-qualified domain name (FQDN) for the host is returned, unless one of
|
||
|
|
the following is true:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>If the flag bit NI_NOFQDN is set, only the nodename portion of the FQDN is
|
||
|
|
returned for local hosts.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the flag bit NI_NUMERICHOST is set, the numeric form of the host's
|
||
|
|
address is returned instead of its name, under all circumstances.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the flag bit NI_NAMEREQD is set, an error is returned if the host's name
|
||
|
|
cannot be located.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the flag bit NI_NUMERICSERV is set, the numeric form of the service
|
||
|
|
address is returned (for example, its port number) instead of its name, under
|
||
|
|
all circumstances.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the flag bit NI_DGRAM is set, this indicates that the service is a
|
||
|
|
datagram service (SOCK_DGRAM). The default behavior is to assume that the
|
||
|
|
service is a stream service (SOCK_STREAM).</li>
|
||
|
|
</ul>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<p>No authorization required.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<p><em>getnameinfo()</em> returns an integer. Possible values are:</p>
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>0 (successful)<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>non-zero (unsuccessful)</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>On successful completion, function <strong><em>getnameinfo()</em></strong>
|
||
|
|
returns the node and service names, if requested, in the buffers provided. The
|
||
|
|
returned names are always null-terminated strings, and may be truncated if the
|
||
|
|
actual values are longer than can be stored in the buffers provided. If the
|
||
|
|
returned values are to be used as part of any further name resolution (for
|
||
|
|
example, passed to <a href="getaddrinfo.htm">getaddrinfo()</a>, callers must
|
||
|
|
either provide buffers large enough to store any result possible on the system
|
||
|
|
or must check for truncation and handle that case appropriately.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
When <em>getnameinfo()</em> fails, the error return value can be set to one
|
||
|
|
of the following:
|
||
|
|
<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.</p></dd>
|
||
|
|
|
||
|
|
|
||
|
|
<dt><em>[EAI_FAMILY]</em></dt>
|
||
|
|
<dd><p>The address family was not recognized or the
|
||
|
|
address length was invalid for the specified family.</p></dd>
|
||
|
|
|
||
|
|
|
||
|
|
<dt><em>[EAI_MEMORY]</em></dt>
|
||
|
|
<dd><p>There was a memory allocation failure.</p></dd>
|
||
|
|
|
||
|
|
|
||
|
|
<dt><em>[EAI_NONAME]</em></dt>
|
||
|
|
<dd><p>The name does not resolve for the supplied
|
||
|
|
parameters. NI_NAMEREQD is set and the host's name cannot be located, or both
|
||
|
|
<em>nodename</em> and <em>servname</em> were null.</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>
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>The <em>nodename</em> and <em>servname</em> parameters cannot both be
|
||
|
|
NULL.<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>If the node and service information is obtained from the domain name
|
||
|
|
server, the information is returned in the default coded character set
|
||
|
|
identifier (CCSID) currently in effect for the job. (The default CCSID is the
|
||
|
|
same as the job CCSID unless 65535 is requested, in which case the default
|
||
|
|
CCSID is set based on the language ID of the job. See <a href=
|
||
|
|
"../nls/rbagsglobalmain.htm">Globalization</a> for more information.) If the
|
||
|
|
node and service information is retrieved from the host database file, the
|
||
|
|
default CCSID of the job is not used. To request conversion of the host
|
||
|
|
information when it is retrieved from the host database file, you must use a
|
||
|
|
job CCSID of something other than 65535.<br>
|
||
|
|
<br>
|
||
|
|
</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>getnameinfo()</em> API is mapped to <em>qetnameinfo98()</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="getaddrinfo.htm">getaddrinfo()</a>--Get 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="ghosta.htm">gethostbyaddr()</a>--Get Host Information for IP
|
||
|
|
Address<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><a href="gsrvprt.htm">getservbyport()</a>--Get Service Name for Port
|
||
|
|
Number<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><a href="inet_ntop.htm">inet_ntop()</a>--Convert IPv4 and IPv6 Addresses
|
||
|
|
Between Binary and Text Form</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>
|
||
|
|
|