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$ 26.\" 27.Dd November 23, 2005 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 sys/types.h 38.In sys/socket.h 39.In net/if.h 40.Ft "unsigned int" 41.Fn if_nametoindex "const char *ifname" 42.Ft "char *" 43.Fn if_indextoname "unsigned int ifindex" "char *ifname" 44.Ft "struct if_nameindex *" 45.Fn if_nameindex "void" 46.Ft void 47.Fn if_freenameindex "struct if_nameindex *ptr" 48.Sh DESCRIPTION 49The 50.Fn if_nametoindex 51function maps the interface name specified in 52.Fa ifname 53to its corresponding index. 54If the specified interface does not exist, it returns 0. 55.Pp 56The 57.Fn if_indextoname 58function maps the interface index specified in 59.Fa ifindex 60to it corresponding name, which is copied into the 61buffer pointed to by 62.Fa ifname , 63which must be of at least 64.Dv IFNAMSIZ 65bytes. 66This pointer is also the return value of the function. 67If there is no interface corresponding to the specified 68index, 69.Dv NULL 70is returned. 71.Pp 72The 73.Fn if_nameindex 74function returns an array of 75.Vt if_nameindex 76structures, one structure per interface, as 77defined in the include file 78.In net/if.h . 79The 80.Vt if_nameindex 81structure contains at least the following entries: 82.Bd -literal 83 unsigned int if_index; /* 1, 2, ... */ 84 char *if_name; /* null terminated name: "le0", ... */ 85.Ed 86.Pp 87The end of the array of structures is indicated by a structure with an 88.Va if_index 89of 0 and an 90.Va if_name 91of 92.Dv NULL . 93A 94.Dv NULL 95pointer is returned upon an error. 96.Pp 97The 98.Fn if_freenameindex 99function frees the dynamic memory that was 100allocated by 101.Fn if_nameindex . 102.Sh RETURN VALUES 103Upon successful completion, 104.Fn if_nametoindex 105returns the index number of the interface. 106If the interface is not found, a value of 0 is returned and 107.Va errno 108is set to 109.Er ENXIO . 110A value of 0 is also returned if an error 111occurs while retrieving the list of interfaces via 112.Xr getifaddrs 3 . 113.Pp 114Upon successful completion, 115.Fn if_indextoname 116returns 117.Fa ifname . 118If the interface is not found, a 119.Dv NULL 120pointer is returned and 121.Va errno 122is set to 123.Er ENXIO . 124A 125.Dv NULL 126pointer is also returned if an error 127occurs while retrieving the list of interfaces via 128.Xr getifaddrs 3 . 129.Pp 130The 131.Fn if_nameindex 132returns a 133.Dv NULL 134pointer if an error 135occurs while retrieving the list of interfaces via 136.Xr getifaddrs 3 , 137or if sufficient memory cannot be allocated. 138.Sh SEE ALSO 139.Xr getifaddrs 3 , 140.Xr networking 4 141.Sh STANDARDS 142The 143.Fn if_nametoindex , 144.Fn if_indextoname , 145.Fn if_nameindex , 146and 147.Fn if_freenameindex 148functions conform to 149.%T "RFC 2553" . 150.Sh HISTORY 151The implementation first appeared in BSDi 152.Bsx . 153