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

231 lines
6.4 KiB
HTML
Raw Permalink 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>inet_pton--Convert IPv4 and IPv6 Addresses Between Text and Binary Form
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: -->
<!-- YYMMDD USERID Change description -->
<!-- Created for V5R2 by Chris Gloe -->
<!-- Edited by Kersten Feb 02 -->
<!-- 040405 MULLENBA Added a usage note. -->
<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>inet_pton()--Convert IPv4
and IPv6 Addresses Between Text and Binary Form</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax
<pre>
#include &lt;sys/socket.h&gt;
#include &lt;arpa/inet.h&gt;
int inet_pton(int af, const char *src, void *dst);
</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><em>inet_pton()</em></strong> function converts an address in
its standard text presentation form into its numeric binary form.</p>
<h3>Parameters</h3>
<dl>
<dt><strong>af</strong></dt>
<dd>(Input) Specifies the family of the address to be converted. Currently the
AF_INET and AF_INET6 address families are supported.<br>
<br>
</dd>
<dt><strong>src</strong></dt>
<dd>(Input) The pointer to the null-terminated character string that contains
the text presentation form of an IPv4 address if the <em>af</em> parameter is
AF_INET, or the text presentation form of an IPv6 address if the <em>af</em>
parameter is AF_INET6. See usage notes for the supported formats.<br>
<br>
</dd>
<dt><strong>dst</strong></dt>
<dd>(Output) The pointer to a buffer into which the function stores the
numeric address. The calling application must ensure that the buffer referred
to by <em>dst</em> is large enough to hold the numeric address (4 bytes
for AF_INET or 16 bytes for AF_INET6).</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>No authorization is required.</p>
<br>
<h3>Return Value</h3>
<p><em>inet_pton()</em> returns an integer. Possible values are: </p>
<ul>
<li>1 (successful)<br>
<br>
</li>
<li>0 (unsuccessful--input is not a valid IPv4 dotted-decimal string or a valid
IPv6 address string)<br>
<br>
</li>
<li>-1 (unsuccessful--see <em>errno</em>)</li>
</ul>
<p>If successful, the buffer pointed at by <em>dst</em> will be updated with
the numeric address.</p>
<br>
<h3>Error Conditions</h3>
<p>When <em>inet_pton()</em> fails with a -1, <em>errno</em> will be set
to:</p>
<dl>
<dt><em>[EAFNOSUPPORT]</em></dt>
<dd><p>The address family is not supported.</p></dd>
<dt><em>[EINVAL]</em></dt>
<dd><p>Parameter is not valid.</p></dd>
<dt><em>[EFAULT]</em></dt>
<dd><p>The system detected an address which was not
valid while attempting to access the <em>src</em> or <em>dst</em>
parameter.</p></dd>
</dl>
<br>
<h3>Usage Notes</h3>
<ol>
<li>If the <em>af</em> parameter of <strong><em>inet_pton()</em></strong> is
AF_INET, the <em>src</em> string must be in the standard IPv4 dotted-decimal
form:<br>
<br>
<dl>
<dd><strong>ddd.ddd.ddd.ddd</strong></dd>
</dl>
<p>where ddd is a one to three digit decimal number between 0 and 255 (see the
<a href="inaddr.htm">inet_addr()</a> definition). The
<strong><em>inet_pton</em></strong> function does not accept other formats
(such as the octal numbers, hexadecimal numbers, and fewer than four numbers
that <a href="inaddr.htm">inet_addr()</a> accepts).</p>
</li>
<li>
<p>If the <em>af</em> parameter of <strong><em>inet_pton</em></strong> is
AF_INET6, the <em>src</em> string must be in one of the following IPv6
text forms:</p>
<ol>
<li>The preferred form is <strong>x:x:x:x:x:x:x:x</strong>, where the 'x's are
the hexadecimal values of the eight 16-bit pieces of the address. Leading zeros
in individual fields can be omitted, but there must be at least one value in
every field.<br>
<br>
</li>
<li>A string of contiguous zero fields in the preferred form can be shown as
"::". The "::" can only appear once in an address. Unspecified addresses
(<strong>0:0:0:0:0:0:0:0</strong>) may be represented simply as "::".<br>
<br>
</li>
<li>A third form that is sometimes more convenient when dealing with a mixed
environment of IPv4 and IPv6 nodes is <strong>x:x:x:x:x:x:d.d.d.d</strong>,
where the "x"s are the hexadecimal values of the six high-order 16-bit pieces
of the address, and the "d"s are the decimal values of the four low-order 8-bit
pieces of the address (standard IPv4 representation).</li>
</ol>
<br>
<br>
</li>
<li><img src="delta.gif" alt="Start of change">
The above IPv6 text forms may include an appended zone
indicator (if preceded by a % character) and/or an appended prefix length
(if preceded by a / character). In these cases, the % or / will be treated
the same as a null terminator.<br>
<br></li>
<li>A trailing space will be treated the same as a null terminator.<br>
<br></li>
<li>The default coded character set identifier (CCSID) currently in effect for the job
<img src="deltaend.gif" alt="End of change"> will be
used to convert the characters found at <em>src</em> (to allow the hexadecimal
values to be entered in lower case).</li>
</ol>
<br>
<br>
<h3>Related Information</h3>
<ul>
<li><a href="inaddr.htm">inet_addr()</a>--Translate Full Address to 32-bit IP
Address<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>
<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>