1.\" $NetBSD: if_indextoname.3,v 1.5 2000/04/24 10:24:47 itojun Exp $ 2.\" $KAME: if_indextoname.3,v 1.8 2000/04/24 10:12:36 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 <net/if.h> 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. A NULL pointer is returned upon an error. 85.Pp 86The 87.Fn if_freenameindex 88function frees the dynamic memory that was 89allocated by 90.Fn if_nameindex . 91.Sh RETURN VALUES 92Upon successful completion, 93.Fn if_nametoindex 94returns the index number of the interface. 95A value of 0 is returned if the interface is not found or an error 96occurs while retrieving the list of interfaces via 97.Xr getifaddrs 3 . 98.Pp 99Upon successful completion, 100.Fn if_indextoname 101returns 102.Ar ifname . 103A NULL pointer is returned if the interface is not found or an error 104occurs while retrieving the list of interfaces via 105.Xr getifaddrs 3 . 106.Pp 107The 108.Fn if_nameindex 109returns a NULL pointer if an error 110occurs while retrieving the list of interfaces via 111.Xr getifaddrs 3 , 112or if sufficient memory cannot be allocated. 113.Sh SEE ALSO 114.Xr getifaddrs 3 , 115.Xr networking 4 116.Sh STANDARDS 117The 118.Fn if_nametoindex , 119.Fn if_indextoname , 120.Fn if_nameindex , 121and 122.Fn if_freenameindex 123functions conform to RFC 2553. 124.Sh HISTORY 125The implementation first appeared in BSDI BSD/OS. 126