1.\" $OpenBSD: if_indextoname.3,v 1.9 2005/07/22 04:50:51 jaredy Exp $ 2.\" Copyright (c) 1983, 1991, 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. Neither the name of the University nor the names of its contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" From: @(#)rcmd.3 8.1 (Berkeley) 6/4/93 30.\" 31.Dd May 21, 1998 32.Dt IF_NAMETOINDEX 3 33.Os 34.Sh NAME 35.Nm if_nametoindex , 36.Nm if_indextoname , 37.Nm if_nameindex , 38.Nm if_freenameindex 39.Nd convert interface index to name, and vice versa 40.Sh SYNOPSIS 41.Fd #include <sys/socket.h> 42.Fd #include <net/if.h> 43.Ft "unsigned int" 44.Fn if_nametoindex "const char *ifname" 45.Ft "char *" 46.Fn if_indextoname "unsigned int ifindex" "char *ifname" 47.Ft "struct if_nameindex *" 48.Fn if_nameindex "void" 49.Ft "void" 50.Fn if_freenameindex "struct if_nameindex *ptr" 51.Sh DESCRIPTION 52These functions map interface indexes to interface names (such as 53.Dq lo0 ) , 54and vice versa. 55.Pp 56The 57.Fn if_nametoindex 58function converts an interface name specified by the 59.Fa ifname 60argument to an interface index (positive integer value). 61If the specified interface does not exist, 0 will be returned. 62.Pp 63.Fn if_indextoname 64converts an interface index specified by the 65.Fa ifindex 66argument to an interface name. 67The 68.Fa ifname 69argument must point to a buffer of at least 70.Dv IF_NAMESIZE 71bytes into which the interface name corresponding to the specified index is 72returned. 73.Pf ( Dv IF_NAMESIZE 74is also defined in 75.Aq Pa net/if.h 76and its value includes a terminating NUL byte at the end of the 77interface name.) 78This pointer is also the return value of the function. 79If there is no interface corresponding to the specified index, 80.Dv NULL 81is returned. 82.Pp 83.Fn if_nameindex 84returns an array of 85.Vt if_nameindex 86structures. 87.Vt if_nameindex 88is also defined in 89.Aq Pa net/if.h , 90and is as follows: 91.Bd -literal -offset indent 92struct if_nameindex { 93 unsigned int if_index; /* 1, 2, ... */ 94 char *if_name; /* NUL-terminated name */ 95}; 96.Ed 97.Pp 98The end of the array of structures is indicated by a structure with 99an 100.Fa if_index 101of 0 and an 102.Fa if_name 103of 104.Dv NULL . 105The function returns a null pointer on error. 106The memory used for this array of structures along with the interface 107names pointed to by the 108.Fa if_name 109members is obtained dynamically. 110This memory is freed by the 111.Fn if_freenameindex 112function. 113.Pp 114.Fn if_freenameindex 115takes a pointer that was returned by 116.Fn if_nameindex 117as argument 118.Pq Fa ptr , 119and it reclaims the region allocated. 120.Sh DIAGNOSTICS 121.Fn if_nametoindex 122returns 0 on error, positive integer on success. 123.Fn if_indextoname 124and 125.Fn if_nameindex 126return 127.Dv NULL 128on errors. 129.Sh SEE ALSO 130.Xr getifaddrs 3 , 131.Xr networking 4 132.Rs 133.%A R. Gilligan 134.%A S. Thomson 135.%A J. Bound 136.%A W. Stevens 137.%T Basic Socket Interface Extensions for IPv6 138.%R RFC 2553 139.%D March 1999 140.Re 141.Sh STANDARDS 142These functions are defined in ``Basic Socket Interface Extensions for IPv6'' 143.Pq RFC 2533 . 144