1.\" $KAME: if_indextoname.3,v 1.10 2000/11/24 08:13:51 itojun Exp $ 2.\" BSDI Id: if_indextoname.3,v 2.2 2000/04/17 22:38:05 dab Exp 3.\" 4.\" Copyright (c) 1997, 2000 5.\" Berkeley Software Design, Inc. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY Berkeley Software Design, Inc. ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL Berkeley Software Design, Inc. BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd November 23, 2005 26.Dt IF_NAMETOINDEX 3 27.Os 28.Sh NAME 29.Nm if_nametoindex , 30.Nm if_indextoname , 31.Nm if_nameindex , 32.Nm if_freenameindex 33.Nd provide mappings between interface names and indexes 34.Sh SYNOPSIS 35.In sys/types.h 36.In sys/socket.h 37.In net/if.h 38.Ft "unsigned int" 39.Fn if_nametoindex "const char *ifname" 40.Ft "char *" 41.Fn if_indextoname "unsigned int ifindex" "char *ifname" 42.Ft "struct if_nameindex *" 43.Fn if_nameindex "void" 44.Ft void 45.Fn if_freenameindex "struct if_nameindex *ptr" 46.Sh DESCRIPTION 47The 48.Fn if_nametoindex 49function maps the interface name specified in 50.Fa ifname 51to its corresponding index. 52If the specified interface does not exist, it returns 0. 53.Pp 54The 55.Fn if_indextoname 56function maps the interface index specified in 57.Fa ifindex 58to it corresponding name, which is copied into the 59buffer pointed to by 60.Fa ifname , 61which must be of at least 62.Dv IFNAMSIZ 63bytes. 64This pointer is also the return value of the function. 65If there is no interface corresponding to the specified 66index, 67.Dv NULL 68is returned. 69.Pp 70The 71.Fn if_nameindex 72function returns an array of 73.Vt if_nameindex 74structures, one structure per interface, as 75defined in the include file 76.In net/if.h . 77The 78.Vt if_nameindex 79structure contains at least the following entries: 80.Bd -literal 81 unsigned int if_index; /* 1, 2, ... */ 82 char *if_name; /* null terminated name: "le0", ... */ 83.Ed 84.Pp 85The end of the array of structures is indicated by a structure with an 86.Va if_index 87of 0 and an 88.Va if_name 89of 90.Dv NULL . 91A 92.Dv NULL 93pointer is returned upon an error. 94.Pp 95The 96.Fn if_freenameindex 97function frees the dynamic memory that was 98allocated by 99.Fn if_nameindex . 100.Sh RETURN VALUES 101Upon successful completion, 102.Fn if_nametoindex 103returns the index number of the interface. 104If the interface is not found, a value of 0 is returned and 105.Va errno 106is set to 107.Er ENXIO . 108A value of 0 is also returned if an error 109occurs while retrieving the list of interfaces via 110.Xr getifaddrs 3 . 111.Pp 112Upon successful completion, 113.Fn if_indextoname 114returns 115.Fa ifname . 116If the interface is not found, a 117.Dv NULL 118pointer is returned and 119.Va errno 120is set to 121.Er ENXIO . 122A 123.Dv NULL 124pointer is also returned if an error 125occurs while retrieving the list of interfaces via 126.Xr getifaddrs 3 . 127.Pp 128The 129.Fn if_nameindex 130returns a 131.Dv NULL 132pointer if an error 133occurs while retrieving the list of interfaces via 134.Xr getifaddrs 3 , 135or if sufficient memory cannot be allocated. 136.Sh SEE ALSO 137.Xr getifaddrs 3 , 138.Xr networking 4 139.Sh STANDARDS 140The 141.Fn if_nametoindex , 142.Fn if_indextoname , 143.Fn if_nameindex , 144and 145.Fn if_freenameindex 146functions conform to 147.%T "RFC 2553" . 148.Sh HISTORY 149The implementation first appeared in BSDi 150.Bsx . 151