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