kernel: Remove some old ISA only drivers.
[dragonfly.git] / lib / libc / net / if_indextoname.3
CommitLineData
984263bc
MD
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.\"
12b71966 25.\" $FreeBSD: src/lib/libc/net/if_indextoname.3,v 1.11 2005/11/23 10:49:07 ru Exp $
984263bc 26.\"
12b71966 27.Dd November 23, 2005
984263bc
MD
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
770899e9
SW
36.Sh LIBRARY
37.Lb libc
984263bc 38.Sh SYNOPSIS
12b71966
PA
39.In sys/types.h
40.In sys/socket.h
984263bc 41.In net/if.h
12b71966 42.Ft "unsigned int"
984263bc 43.Fn if_nametoindex "const char *ifname"
12b71966 44.Ft "char *"
984263bc 45.Fn if_indextoname "unsigned int ifindex" "char *ifname"
12b71966 46.Ft "struct if_nameindex *"
984263bc
MD
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
12b71966 54.Fa ifname
984263bc
MD
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
12b71966 61.Fa ifindex
984263bc
MD
62to it corresponding name, which is copied into the
63buffer pointed to by
12b71966
PA
64.Fa ifname ,
65which must be of at least
66.Dv IFNAMSIZ
67bytes.
984263bc
MD
68This pointer is also the return value of the function.
69If there is no interface corresponding to the specified
12b71966
PA
70index,
71.Dv NULL
72is returned.
984263bc
MD
73.Pp
74The
75.Fn if_nameindex
76function returns an array of
12b71966 77.Vt if_nameindex
984263bc
MD
78structures, one structure per interface, as
79defined in the include file
44cb301e 80.In net/if.h .
984263bc 81The
12b71966 82.Vt if_nameindex
984263bc
MD
83structure contains at least the following entries:
84.Bd -literal
85 unsigned int if_index; /* 1, 2, ... */
ad9f8794 86 char *if_name; /* null terminated name: "lnc0", ... */
984263bc
MD
87.Ed
88.Pp
89The end of the array of structures is indicated by a structure with an
12b71966 90.Va if_index
984263bc 91of 0 and an
12b71966
PA
92.Va if_name
93of
94.Dv NULL .
95A
96.Dv NULL
97pointer is returned upon an error.
984263bc
MD
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
12b71966
PA
119.Fa ifname .
120If the interface is not found, a
121.Dv NULL
122pointer is returned and
984263bc
MD
123.Va errno
124is set to
125.Er ENXIO .
12b71966
PA
126A
127.Dv NULL
128pointer is also returned if an error
984263bc
MD
129occurs while retrieving the list of interfaces via
130.Xr getifaddrs 3 .
131.Pp
132The
133.Fn if_nameindex
12b71966
PA
134returns a
135.Dv NULL
136pointer if an error
984263bc
MD
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
12b71966
PA
150functions conform to
151.%T "RFC 2553" .
984263bc 152.Sh HISTORY
12b71966 153The implementation first appeared in BSDi
b5ac91c1 154.Bsx .