Remove tm.h and xm.h handling, as it wasn't used. Use nm.h only when needed.
[dragonfly.git] / lib / libc / net / if_indextoname.3
blob4ebd6cae0ae9f69a7c8ff3d1ca426f84395c8ea1
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
50 The
51 .Fn if_nametoindex
52 function maps the interface name specified in
53 .Ar ifname
54 to its corresponding index.
55 If the specified interface does not exist, it returns 0.
56 .Pp
57 The
58 .Fn if_indextoname
59 function maps the interface index specified in
60 .Ar ifindex
61 to it corresponding name, which is copied into the
62 buffer pointed to by
63 .Ar ifname ,
64 which must be of at least IFNAMSIZ bytes.
65 This pointer is also the return value of the function.
66 If there is no interface corresponding to the specified
67 index, NULL is returned.
68 .Pp
69 The
70 .Fn if_nameindex
71 function returns an array of
72 .Nm if_nameindex
73 structures, one structure per interface, as
74 defined in the include file
75 .In net/if.h .
76 The
77 .Nm if_nameindex
78 structure 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
84 The end of the array of structures is indicated by a structure with an
85 .Nm if_index
86 of 0 and an
87 .Nm if_name
88 of NULL.
89 A NULL pointer is returned upon an error.
90 .Pp
91 The
92 .Fn if_freenameindex
93 function frees the dynamic memory that was
94 allocated by
95 .Fn if_nameindex .
96 .Sh RETURN VALUES
97 Upon successful completion,
98 .Fn if_nametoindex
99 returns the index number of the interface.
100 If the interface is not found, a value of 0 is returned and
101 .Va errno
102 is set to
103 .Er ENXIO .
104 A value of 0 is also returned if an error
105 occurs while retrieving the list of interfaces via
106 .Xr getifaddrs 3 .
108 Upon successful completion,
109 .Fn if_indextoname
110 returns
111 .Ar ifname .
112 If the interface is not found, a NULL pointer is returned and
113 .Va errno
114 is set to
115 .Er ENXIO .
116 A NULL pointer is also returned if an error
117 occurs while retrieving the list of interfaces via
118 .Xr getifaddrs 3 .
121 .Fn if_nameindex
122 returns a NULL pointer if an error
123 occurs while retrieving the list of interfaces via
124 .Xr getifaddrs 3 ,
125 or if sufficient memory cannot be allocated.
126 .Sh SEE ALSO
127 .Xr getifaddrs 3 ,
128 .Xr networking 4
129 .Sh STANDARDS
131 .Fn if_nametoindex ,
132 .Fn if_indextoname ,
133 .Fn if_nameindex ,
135 .Fn if_freenameindex
136 functions conform to RFC 2553.
137 .Sh HISTORY
138 The implementation first appeared in BSDI
139 .Bsx .