xref: /netbsd/lib/libc/net/if_indextoname.3 (revision bf9ec67e)
1.\"	$NetBSD: if_indextoname.3,v 1.9 2002/02/07 07:00:21 ross Exp $
2.\"	$KAME: if_indextoname.3,v 1.10 2000/11/24 08:13:51 itojun Exp $
3.\"	BSDI	Id: if_indextoname.3,v 2.2 2000/04/17 22:38:05 dab Exp
4.\"
5.\" Copyright (c) 1997, 2000
6.\"	Berkeley Software Design, Inc.  All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY Berkeley Software Design, Inc. ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL Berkeley Software Design, Inc. BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.Dd July 11, 1997
27.Dt IF_NAMETOINDEX 3
28.Os
29.Sh NAME
30.Nm if_nametoindex ,
31.Nm if_indextoname ,
32.Nm if_nameindex ,
33.Nm if_freenameindex
34.Nd provide mappings between interface names and indexes
35.Sh SYNOPSIS
36.Fd #include \*[Lt]net/if.h\*[Gt]
37.Ft unsigned int
38.Fn if_nametoindex "const char *ifname"
39.Ft char *
40.Fn if_indextoname "unsigned int ifindex" "char *ifname"
41.Ft struct if_nameindex *
42.Fn if_nameindex "void"
43.Ft void
44.Fn if_freenameindex "struct if_nameindex *ptr"
45.Sh DESCRIPTION
46The
47.Fn if_nametoindex
48function maps the interface name specified in
49.Ar ifname
50to its corresponding index.
51If the specified interface does not exist, it returns 0.
52.Pp
53The
54.Fn if_indextoname
55function maps the interface index specified in
56.Ar ifindex
57to it corresponding name, which is copied into the
58buffer pointed to by
59.Ar ifname ,
60which must be of at least IFNAMSIZ bytes.
61This pointer is also the return value of the function.
62If there is no interface corresponding to the specified
63index, NULL is returned.
64.Pp
65The
66.Fn if_nameindex
67function returns an array of
68.Nm if_nameindex
69structures, one structure per interface, as
70defined in the include file
71.Aq Pa net/if.h .
72The
73.Nm if_nameindex
74structure contains at least the following entries:
75.Bd -literal
76    unsigned int   if_index;  /* 1, 2, ... */
77    char          *if_name;   /* null terminated name: "le0", ... */
78.Ed
79.Pp
80The end of the array of structures is indicated by a structure with an
81.Nm if_index
82of 0 and an
83.Nm if_name
84of NULL.
85A NULL pointer is returned upon an error.
86.Pp
87The
88.Fn if_freenameindex
89function frees the dynamic memory that was
90allocated by
91.Fn if_nameindex .
92.Sh RETURN VALUES
93Upon successful completion,
94.Fn if_nametoindex
95returns the index number of the interface.
96If the interface is not found, a value of 0 is returned and
97.Va errno
98is set to
99.Er ENXIO .
100A value of 0 is also returned if an error
101occurs while retrieving the list of interfaces via
102.Xr getifaddrs 3 .
103.Pp
104Upon successful completion,
105.Fn if_indextoname
106returns
107.Ar ifname .
108If the interface is not found, a NULL pointer is returned and
109.Va errno
110is set to
111.Er ENXIO .
112A NULL pointer is also returned if an error
113occurs while retrieving the list of interfaces via
114.Xr getifaddrs 3 .
115.Pp
116The
117.Fn if_nameindex
118returns a NULL pointer if an error
119occurs while retrieving the list of interfaces via
120.Xr getifaddrs 3 ,
121or if sufficient memory cannot be allocated.
122.Sh SEE ALSO
123.Xr getifaddrs 3 ,
124.Xr networking 4
125.Sh STANDARDS
126The
127.Fn if_nametoindex ,
128.Fn if_indextoname ,
129.Fn if_nameindex ,
130and
131.Fn if_freenameindex
132functions conform to RFC 2553.
133.Sh HISTORY
134The implementation first appeared in
135.Bsx .
136