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