1 .\" $NetBSD: ieee80211_node.9,v 1.4 2006/09/12 13:05:17 pooka Exp $
3 .\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
4 .\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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
28 .\" $FreeBSD: src/share/man/man9/ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $
30 .Dd September 12, 2006
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
49 .In net80211/ieee80211_var.h
50 .In net80211/ieee80211_proto.h
51 .In net80211/ieee80211_node.h
53 .Fn ieee80211_node_attach "struct ieee80211com *ic"
55 .Fn ieee80211_node_lateattach "struct ieee80211com *ic"
57 .Fn ieee80211_node_detach "struct ieee80211com *ic"
59 .Fn ieee80211_begin_scan "struct ieee80211com *ic" "int reset"
61 .Fn ieee80211_next_scan "struct ieee80211com *ic"
63 .Fn ieee80211_end_scan "struct ieee80211com *ic"
65 .Fo ieee80211_create_ibss
66 .Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
68 .Ft struct ieee80211_node *
69 .Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr"
70 .Ft struct ieee80211_node *
72 .Fa "struct ieee80211_node_table *nt" "const u_int8_t *macaddr"
74 .Ft struct ieee80211_node *
75 .Fo ieee80211_find_node
76 .Fa "struct ieee80211_node_table *nt" "const u_int8_t *macaddr"
79 .Fn ieee80211_free_node "struct ieee80211_node *ni"
81 .Fn ieee80211_free_allnodes "struct ieee80211_node_table *nt"
83 .Fo ieee80211_iterate_nodes
84 .Fa "struct ieee80211_node_table *nt" "ieee80211_iter_func *f" "void *arg"
87 These functions are used to manage node lists within the software
89 These lists are typically used for implementing host-mode AP functionality,
90 or providing signal quality information about neighbouring nodes.
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
99 (specifically for memory allocation, node copying and node
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
111 node element of the interface
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
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
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
144 layer that the next channel for interface
150 .Fn ieee80211_create_ibss
151 function sets up the net80211-specific portion of an interface's softc,
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.
163 .Fn ieee80211_end_scan
164 will inspect the node cache associated with the interface
166 for suitable access points found during scanning, and associate with one,
167 should the parameters of the node match those of the configuration
172 .Fn ieee80211_alloc_node
173 function allocates an instance of
174 .Vt "struct ieee80211_node"
175 for a node having the MAC address
177 and associates it with the node table
179 If the allocation is successful, the node structure is initialised by
180 .Fn ieee80211_setup_node ;
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
192 associated with the note table
194 If the allocation is successful, the node structure is initialised by
195 .Fn ieee80211_setup_node ;
202 .Fn ieee80211_find_node
203 function will iterate through the node table
205 searching for a node entry which matches
207 If the entry is found, its reference count is incremented, and
208 a pointer to the node is returned; otherwise,
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
222 .Fn ieee80211_iterate_nodes
223 function will call the user-defined callback function
225 for all nodes in the table
227 The callback is invoked with the with the user-supplied value
229 and a pointer to the current node.
236 series of functions first appeared in
238 and were later ported to
242 This man page was written by
243 .An Bruce M. Simpson Aq bms@FreeBSD.org
245 .An Darron Broad Aq darron@kewl.org .