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