<!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>if_indextoname--Map an Interface index to its Corresponding Name 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 V5R4 by Tim Mullenbach --> <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><img src="delta.gif" ALT="Start of change">if_indextoname()--Map an Interface index to its Corresponding Name</h2> <div class="box" style="width: 80%;"> <br> <br> Syntax <pre> #include <net/if.h> char *if_indextoname(unsigned int ifindex, char *ifname); </pre> Service Program Name: QSOSRV2 <br> Default Public Authority: *USE <br> Threadsafe: Yes<br><br> </div> <p>The <strong><em>if_indextoname()</em></strong> function places the name of the interface with index <em>ifindex</em> into the buffer pointed at by <em>ifname</em>. When this function is called, <em>ifname</em> must point to a buffer of at least IFNAMSIZ bytes.</p> <br> <h3><a name="Header_2">Parameters</a></h3> <dl> <dt><strong><em>ifindex</em></strong> (Input) </dt> <dd>Interface index.<br><br></dd> <dt><strong><em>ifname</em></strong> (Output) </dt> <dd>Pointer to a null terminated string containing the interface (line description) name returned.<br><br></dd> </dl> <br> <h3><a name="Header_3">Authorities</a></h3> <p> No authorization is required.</p> <br> <h3><a name="Header_4">Return Value</a></h3> <p><em>if_indextoname()</em> returns a pointer to a null terminated string containing the interface (line description) name. Possible values are:</p> <ul> <li>The value supplied in <em>ifname</em>. (successful)</li> <li>NULL (unsuccessful)</li> </ul> <br> <h3><a name="Header_5">Error Conditions</a></h3> <p>When <em>if_indextoname()</em> fails, <em>errno</em> can be set to one of the following:</p> <dl compact> <dt><em>[ENXIO]</em></dt> <dd>The specified interface index does not exist.</dd> <dt><em>[EFAULT]</em></dt> <dd>The buffer pointed to by <em>ifname</em> can not be accessed.</dd> </dl> <br> <h3>Usage Notes</h3> <ol> <li> <p>The interface (line description) name stored at <em>ifname</em> will be returned in the default coded character set identifier (CCSID) currently in effect for the job. If this is not a single byte CCSID, then storage greater than IFNAMSIZ (16) bytes may be needed. 22 bytes is large enough for all CCSIDs.</p></li> <li><p>It is important to note that the term "Interface" refers to the name on a line description (i.e. a physical interface) for this API. Other parts of the operating system, when refering to "Interface," mean an IP address. </p></li> </ol> <br> <h3><a name="Header_8">Related Information</a></h3> <ul> <li><a href="gsocko.htm">getsockopt()</a>--Retrieve Information about Socket Options</li> <li><a href="if_freenameindex.htm">if_freenameindex()</a>--Free Memory Allocated by if_nameindex()</li> <li><a href="if_nameindex.htm">if_nameindex()</a>--Return All Interface Names and Indexes</li> <li><a href="if_nametoindex.htm">if_nametoindex()</a>--Map an Interface Name to its Corresponding Index</li> <li><a href="ssocko.htm">setsockopt()</a>--Set Socket Options</li> </ul> <br> <h3><a name="Header_9">Example</a></h3> <p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a> for information pertaining to code examples.</p> <p>The following example shows how <strong>if_indextoname()</strong> is used:</p> <pre> #include <net/if.h> #include <sys/types.h> #include <errno.h> ref void main() { char interfaceName[IFNAMSIZ]; <strong>char *interface = if_indextoname(1, &interfaceName); /* retrieve the name of interface 1 */</strong> if (interface == NULL) { printf("if_indextoname() failed with errno = %d %s \n", errno,strerror(errno)); return; } ... }</pre> <img src="deltaend.gif" ALT="End of change"> <br> <hr> API introduced: V5R4 <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>