1.\" $OpenBSD: if_indextoname.3,v 1.16 2015/11/21 07:48:10 jmc 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 $Mdocdate: November 21 2015 $ 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.In sys/types.h 42.In sys/socket.h 43.In net/if.h 44.Ft "unsigned int" 45.Fn if_nametoindex "const char *ifname" 46.Ft "char *" 47.Fn if_indextoname "unsigned int ifindex" "char *ifname" 48.Ft "struct if_nameindex *" 49.Fn if_nameindex "void" 50.Ft "void" 51.Fn if_freenameindex "struct if_nameindex *ptr" 52.Sh DESCRIPTION 53These functions map interface indexes to interface names (such as 54.Dq lo0 ) , 55and vice versa. 56.Pp 57The 58.Fn if_nametoindex 59function converts an interface name specified by the 60.Fa ifname 61argument to an interface index (positive integer value). 62If the specified interface does not exist, 0 will be returned. 63.Pp 64.Fn if_indextoname 65converts an interface index specified by the 66.Fa ifindex 67argument to an interface name. 68The 69.Fa ifname 70argument must point to a buffer of at least 71.Dv IF_NAMESIZE 72bytes into which the interface name corresponding to the specified index is 73returned. 74.Pf ( Dv IF_NAMESIZE 75is also defined in 76.In net/if.h 77and its value includes a terminating NUL byte at the end of the 78interface name.) 79This pointer is also the return value of the function. 80If there is no interface corresponding to the specified index, 81.Dv NULL 82is returned. 83.Pp 84.Fn if_nameindex 85returns an array of 86.Vt if_nameindex 87structures. 88.Vt if_nameindex 89is also defined in 90.In net/if.h , 91and is as follows: 92.Bd -literal -offset indent 93struct if_nameindex { 94 unsigned int if_index; /* 1, 2, ... */ 95 char *if_name; /* NUL-terminated name */ 96}; 97.Ed 98.Pp 99The end of the array of structures is indicated by a structure with 100an 101.Fa if_index 102of 0 and an 103.Fa if_name 104of 105.Dv NULL . 106The function returns a null pointer on error. 107The memory used for this array of structures along with the interface 108names pointed to by the 109.Fa if_name 110members is obtained dynamically. 111This memory is freed by the 112.Fn if_freenameindex 113function. 114.Pp 115.Fn if_freenameindex 116takes a pointer that was returned by 117.Fn if_nameindex 118as argument 119.Pq Fa ptr , 120and it reclaims the region allocated. 121.Sh DIAGNOSTICS 122.Fn if_nametoindex 123returns 0 on error, positive integer on success. 124.Fn if_indextoname 125and 126.Fn if_nameindex 127return 128.Dv NULL 129on errors. 130.Sh SEE ALSO 131.Xr getifaddrs 3 , 132.Xr netintro 4 133.Sh STANDARDS 134.Rs 135.%A R. Gilligan 136.%A S. Thomson 137.%A J. Bound 138.%A J. McCann 139.%A W. Stevens 140.%D February 2003 141.%R RFC 3493 142.%T Basic Socket Interface Extensions for IPv6 143.Re 144