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.\" $FreeBSD: src/lib/libc/net/if_indextoname.3,v 1.2.2.6 2002/07/29 18:33:18 ume Exp $ 26.\" $DragonFly: src/lib/libc/net/if_indextoname.3,v 1.4 2007/05/12 21:22:10 swildner Exp $ 27.\" 28.Dd "July 11, 1997" 29.Dt IF_NAMETOINDEX 3 30.Os 31.Sh NAME 32.Nm if_nametoindex , 33.Nm if_indextoname , 34.Nm if_nameindex , 35.Nm if_freenameindex 36.Nd provide mappings between interface names and indexes 37.Sh SYNOPSIS 38.In net/if.h 39.Ft unsigned int 40.Fn if_nametoindex "const char *ifname" 41.Ft char * 42.Fn if_indextoname "unsigned int ifindex" "char *ifname" 43.Ft struct if_nameindex * 44.Fn if_nameindex "void" 45.Ft void 46.Fn if_freenameindex "struct if_nameindex *ptr" 47.Sh DESCRIPTION 48The 49.Fn if_nametoindex 50function maps the interface name specified in 51.Ar ifname 52to its corresponding index. 53If the specified interface does not exist, it returns 0. 54.Pp 55The 56.Fn if_indextoname 57function maps the interface index specified in 58.Ar ifindex 59to it corresponding name, which is copied into the 60buffer pointed to by 61.Ar ifname , 62which must be of at least IFNAMSIZ bytes. 63This pointer is also the return value of the function. 64If there is no interface corresponding to the specified 65index, NULL is returned. 66.Pp 67The 68.Fn if_nameindex 69function returns an array of 70.Nm if_nameindex 71structures, one structure per interface, as 72defined in the include file 73.In net/if.h . 74The 75.Nm if_nameindex 76structure contains at least the following entries: 77.Bd -literal 78 unsigned int if_index; /* 1, 2, ... */ 79 char *if_name; /* null terminated name: "le0", ... */ 80.Ed 81.Pp 82The end of the array of structures is indicated by a structure with an 83.Nm if_index 84of 0 and an 85.Nm if_name 86of NULL. 87A NULL pointer is returned upon an error. 88.Pp 89The 90.Fn if_freenameindex 91function frees the dynamic memory that was 92allocated by 93.Fn if_nameindex . 94.Sh RETURN VALUES 95Upon successful completion, 96.Fn if_nametoindex 97returns the index number of the interface. 98If the interface is not found, a value of 0 is returned and 99.Va errno 100is set to 101.Er ENXIO . 102A value of 0 is also returned if an error 103occurs while retrieving the list of interfaces via 104.Xr getifaddrs 3 . 105.Pp 106Upon successful completion, 107.Fn if_indextoname 108returns 109.Ar ifname . 110If the interface is not found, a NULL pointer is returned and 111.Va errno 112is set to 113.Er ENXIO . 114A NULL pointer is also returned if an error 115occurs while retrieving the list of interfaces via 116.Xr getifaddrs 3 . 117.Pp 118The 119.Fn if_nameindex 120returns a NULL pointer if an error 121occurs while retrieving the list of interfaces via 122.Xr getifaddrs 3 , 123or if sufficient memory cannot be allocated. 124.Sh SEE ALSO 125.Xr getifaddrs 3 , 126.Xr networking 4 127.Sh STANDARDS 128The 129.Fn if_nametoindex , 130.Fn if_indextoname , 131.Fn if_nameindex , 132and 133.Fn if_freenameindex 134functions conform to RFC 2553. 135.Sh HISTORY 136The implementation first appeared in BSDI 137.Bsx . 138