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