231 lines
6.4 KiB
HTML
231 lines
6.4 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>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>
|
||
|
Syntax
|
||
|
|
||
|
<pre>
|
||
|
#include <sys/socket.h>
|
||
|
#include <arpa/inet.h>
|
||
|
|
||
|
int inet_pton(int af, const char *src, void *dst);
|
||
|
</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>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>
|
||
|
|