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