No empty .Rs/.Re
[netbsd-mini2440.git] / share / man / man9 / ieee80211_node.9
blobb3dbe2a5e4e73723b74d7898993989fc42f9cd89
1 .\" $NetBSD: ieee80211_node.9,v 1.4 2006/09/12 13:05:17 pooka Exp $
2 .\"
3 .\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
4 .\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
5 .\" 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 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\" $FreeBSD: src/share/man/man9/ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $
29 .\"
30 .Dd September 12, 2006
31 .Dt IEEE80211_NODE 9
32 .Os
33 .Sh NAME
34 .Nm ieee80211_node_attach ,
35 .Nm ieee80211_node_lateattach ,
36 .Nm ieee80211_node_detach ,
37 .Nm ieee80211_begin_scan ,
38 .Nm ieee80211_next_scan ,
39 .Nm ieee80211_end_scan ,
40 .Nm ieee80211_create_ibss ,
41 .Nm ieee80211_alloc_node ,
42 .Nm ieee80211_dup_bss ,
43 .Nm ieee80211_find_node ,
44 .Nm ieee80211_free_node ,
45 .Nm ieee80211_free_allnodes ,
46 .Nm ieee80211_iterate_nodes
47 .Nd software 802.11 stack node management functions
48 .Sh SYNOPSIS
49 .In net80211/ieee80211_var.h
50 .In net80211/ieee80211_proto.h
51 .In net80211/ieee80211_node.h
52 .Ft void
53 .Fn ieee80211_node_attach "struct ieee80211com *ic"
54 .Ft void
55 .Fn ieee80211_node_lateattach "struct ieee80211com *ic"
56 .Ft void
57 .Fn ieee80211_node_detach "struct ieee80211com *ic"
58 .Ft void
59 .Fn ieee80211_begin_scan "struct ieee80211com *ic" "int reset"
60 .Ft void
61 .Fn ieee80211_next_scan "struct ieee80211com *ic"
62 .Ft void
63 .Fn ieee80211_end_scan "struct ieee80211com *ic"
64 .Ft void
65 .Fo ieee80211_create_ibss
66 .Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
67 .Fc
68 .Ft struct ieee80211_node *
69 .Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr"
70 .Ft struct ieee80211_node *
71 .Fo ieee80211_dup_bss
72 .Fa "struct ieee80211_node_table *nt" "const u_int8_t *macaddr"
73 .Fc
74 .Ft struct ieee80211_node *
75 .Fo ieee80211_find_node
76 .Fa "struct ieee80211_node_table *nt" "const u_int8_t *macaddr"
77 .Fc
78 .Ft void
79 .Fn ieee80211_free_node "struct ieee80211_node *ni"
80 .Ft void
81 .Fn ieee80211_free_allnodes "struct ieee80211_node_table *nt"
82 .Ft void
83 .Fo ieee80211_iterate_nodes
84 .Fa "struct ieee80211_node_table *nt" "ieee80211_iter_func *f" "void *arg"
85 .Fc
86 .Sh DESCRIPTION
87 These functions are used to manage node lists within the software
88 802.11 stack.
89 These lists are typically used for implementing host-mode AP functionality,
90 or providing signal quality information about neighbouring nodes.
91 .Pp
92 .\"
93 The
94 .Fn ieee80211_node_attach
95 function is called from
96 .Xr ieee80211_ifattach 9
97 to initialize node database management callbacks for the interface
98 .Fa ic
99 (specifically for memory allocation, node copying and node
100 signal inspection).
101 These functions may be overridden in special circumstances,
102 as long as this is done after calling
103 .Xr ieee80211_ifattach 9
104 and prior to any other call which may allocate a node.
108 .Fn ieee80211_node_lateattach
109 function initialises the
110 .Va ic_bss
111 node element of the interface
112 .Fa ic
113 during
114 .Xr ieee80211_media_init 9 .
115 This late attachment is to account for certain special cases described under
116 .Fn ieee80211_node_attach .
120 .Fn ieee80211_node_detach
121 function destroys all node database state associated with the interface
122 .Fa ic ,
123 and is usually called during device detach.
127 .Fn ieee80211_begin_scan
128 function initialises the node database in preparation of a
129 scan for an access point on the interface
130 .Fa ic
131 and begins the scan.
132 The parameter
133 .Fa reset
134 controls if a previously built node list should be cleared.
135 The actual scanning for an access point is not fully automated:
136 the device driver itself controls stepping through the channels, usually
137 by a periodical callback.
141 .Fn ieee80211_next_scan
142 function is used to inform the
143 .Xr ieee80211 9
144 layer that the next channel for interface
145 .Fa ic
146 should be scanned.
150 .Fn ieee80211_create_ibss
151 function sets up the net80211-specific portion of an interface's softc,
152 .Fa ic ,
153 for use in IBSS mode.
157 .Fn ieee80211_end_scan
158 function is called by
159 .Fn ieee80211_next_scan
160 when the state machine has peformed a full cycle of scanning on
161 all available radio channels.
162 Internally,
163 .Fn ieee80211_end_scan
164 will inspect the node cache associated with the interface
165 .Fa ic
166 for suitable access points found during scanning, and associate with one,
167 should the parameters of the node match those of the configuration
168 requested.
172 .Fn ieee80211_alloc_node
173 function allocates an instance of
174 .Vt "struct ieee80211_node"
175 for a node having the MAC address
176 .Fa macaddr ,
177 and associates it with the node table
178 .Fa nt .
179 If the allocation is successful, the node structure is initialised by
180 .Fn ieee80211_setup_node ;
181 otherwise,
182 .Dv NULL
183 is returned.
187 .Fn ieee80211_dup_bss
188 function is similar to
189 .Fn ieee80211_alloc_node ,
190 but is instead used to create a node database entry for the BSSID
191 .Fa macaddr
192 associated with the note table
193 .Fa nt .
194 If the allocation is successful, the node structure is initialised by
195 .Fn ieee80211_setup_node ;
196 otherwise,
197 .Dv NULL
198 is returned.
202 .Fn ieee80211_find_node
203 function will iterate through the node table
204 .Fa nt ,
205 searching for a node entry which matches
206 .Fa macaddr .
207 If the entry is found, its reference count is incremented, and
208 a pointer to the node is returned; otherwise,
209 .Dv NULL
210 is returned.
214 .Fn ieee80211_free_allnodes
215 function will iterate through the node list calling
216 .Fn ieee80211_free_node
217 for all the nodes in table
218 .Fa nt .
222 .Fn ieee80211_iterate_nodes
223 function will call the user-defined callback function
224 .Fa f
225 for all nodes in the table
226 .Fa nt .
227 The callback is invoked with the with the user-supplied value
228 .Fa arg
229 and a pointer to the current node.
231 .Sh SEE ALSO
232 .Xr ieee80211 9
233 .Sh HISTORY
235 .Nm ieee80211
236 series of functions first appeared in
237 .Nx 1.5 ,
238 and were later ported to
239 .Fx 4.6 .
240 .Sh AUTHORS
241 .An -nosplit
242 This man page was written by
243 .An Bruce M. Simpson Aq bms@FreeBSD.org
245 .An Darron Broad Aq darron@kewl.org .