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