246 lines
6.9 KiB
Groff
246 lines
6.9 KiB
Groff
.\" $NetBSD: ieee80211_node.9,v 1.5 2006/09/17 12:15:20 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
|
|
.\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD: src/share/man/man9/ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $
|
|
.\"
|
|
.Dd September 12, 2006
|
|
.Dt IEEE80211_NODE 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ieee80211_node_attach ,
|
|
.Nm ieee80211_node_lateattach ,
|
|
.Nm ieee80211_node_detach ,
|
|
.Nm ieee80211_begin_scan ,
|
|
.Nm ieee80211_next_scan ,
|
|
.Nm ieee80211_end_scan ,
|
|
.Nm ieee80211_create_ibss ,
|
|
.Nm ieee80211_alloc_node ,
|
|
.Nm ieee80211_dup_bss ,
|
|
.Nm ieee80211_find_node ,
|
|
.Nm ieee80211_free_node ,
|
|
.Nm ieee80211_free_allnodes ,
|
|
.Nm ieee80211_iterate_nodes
|
|
.Nd software 802.11 stack node management functions
|
|
.Sh SYNOPSIS
|
|
.In net80211/ieee80211_var.h
|
|
.In net80211/ieee80211_proto.h
|
|
.In net80211/ieee80211_node.h
|
|
.Ft void
|
|
.Fn ieee80211_node_attach "struct ieee80211com *ic"
|
|
.Ft void
|
|
.Fn ieee80211_node_lateattach "struct ieee80211com *ic"
|
|
.Ft void
|
|
.Fn ieee80211_node_detach "struct ieee80211com *ic"
|
|
.Ft void
|
|
.Fn ieee80211_begin_scan "struct ieee80211com *ic" "int reset"
|
|
.Ft void
|
|
.Fn ieee80211_next_scan "struct ieee80211com *ic"
|
|
.Ft void
|
|
.Fn ieee80211_end_scan "struct ieee80211com *ic"
|
|
.Ft void
|
|
.Fo ieee80211_create_ibss
|
|
.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
|
|
.Fc
|
|
.Ft struct ieee80211_node *
|
|
.Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr"
|
|
.Ft struct ieee80211_node *
|
|
.Fo ieee80211_dup_bss
|
|
.Fa "struct ieee80211_node_table *nt" "const u_int8_t *macaddr"
|
|
.Fc
|
|
.Ft struct ieee80211_node *
|
|
.Fo ieee80211_find_node
|
|
.Fa "struct ieee80211_node_table *nt" "const u_int8_t *macaddr"
|
|
.Fc
|
|
.Ft void
|
|
.Fn ieee80211_free_node "struct ieee80211_node *ni"
|
|
.Ft void
|
|
.Fn ieee80211_free_allnodes "struct ieee80211_node_table *nt"
|
|
.Ft void
|
|
.Fo ieee80211_iterate_nodes
|
|
.Fa "struct ieee80211_node_table *nt" "ieee80211_iter_func *f" "void *arg"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
These functions are used to manage node lists within the software
|
|
802.11 stack.
|
|
These lists are typically used for implementing host-mode AP functionality,
|
|
or providing signal quality information about neighbouring nodes.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_node_attach
|
|
function is called from
|
|
.Xr ieee80211_ifattach 9
|
|
to initialize node database management callbacks for the interface
|
|
.Fa ic
|
|
(specifically for memory allocation, node copying and node
|
|
signal inspection).
|
|
These functions may be overridden in special circumstances,
|
|
as long as this is done after calling
|
|
.Xr ieee80211_ifattach 9
|
|
and prior to any other call which may allocate a node.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_node_lateattach
|
|
function initialises the
|
|
.Va ic_bss
|
|
node element of the interface
|
|
.Fa ic
|
|
during
|
|
.Xr ieee80211_media_init 9 .
|
|
This late attachment is to account for certain special cases described under
|
|
.Fn ieee80211_node_attach .
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_node_detach
|
|
function destroys all node database state associated with the interface
|
|
.Fa ic ,
|
|
and is usually called during device detach.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_begin_scan
|
|
function initialises the node database in preparation of a
|
|
scan for an access point on the interface
|
|
.Fa ic
|
|
and begins the scan.
|
|
The parameter
|
|
.Fa reset
|
|
controls if a previously built node list should be cleared.
|
|
The actual scanning for an access point is not fully automated:
|
|
the device driver itself controls stepping through the channels, usually
|
|
by a periodical callback.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_next_scan
|
|
function is used to inform the
|
|
.Xr ieee80211 9
|
|
layer that the next channel for interface
|
|
.Fa ic
|
|
should be scanned.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_create_ibss
|
|
function sets up the net80211-specific portion of an interface's softc,
|
|
.Fa ic ,
|
|
for use in IBSS mode.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_end_scan
|
|
function is called by
|
|
.Fn ieee80211_next_scan
|
|
when the state machine has peformed a full cycle of scanning on
|
|
all available radio channels.
|
|
Internally,
|
|
.Fn ieee80211_end_scan
|
|
will inspect the node cache associated with the interface
|
|
.Fa ic
|
|
for suitable access points found during scanning, and associate with one,
|
|
should the parameters of the node match those of the configuration
|
|
requested.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_alloc_node
|
|
function allocates an instance of
|
|
.Vt "struct ieee80211_node"
|
|
for a node having the MAC address
|
|
.Fa macaddr ,
|
|
and associates it with the node table
|
|
.Fa nt .
|
|
If the allocation is successful, the node structure is initialised by
|
|
.Fn ieee80211_setup_node ;
|
|
otherwise,
|
|
.Dv NULL
|
|
is returned.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_dup_bss
|
|
function is similar to
|
|
.Fn ieee80211_alloc_node ,
|
|
but is instead used to create a node database entry for the BSSID
|
|
.Fa macaddr
|
|
associated with the note table
|
|
.Fa nt .
|
|
If the allocation is successful, the node structure is initialised by
|
|
.Fn ieee80211_setup_node ;
|
|
otherwise,
|
|
.Dv NULL
|
|
is returned.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_find_node
|
|
function will iterate through the node table
|
|
.Fa nt ,
|
|
searching for a node entry which matches
|
|
.Fa macaddr .
|
|
If the entry is found, its reference count is incremented, and
|
|
a pointer to the node is returned; otherwise,
|
|
.Dv NULL
|
|
is returned.
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_free_allnodes
|
|
function will iterate through the node list calling
|
|
.Fn ieee80211_free_node
|
|
for all the nodes in table
|
|
.Fa nt .
|
|
.Pp
|
|
.\"
|
|
The
|
|
.Fn ieee80211_iterate_nodes
|
|
function will call the user-defined callback function
|
|
.Fa f
|
|
for all nodes in the table
|
|
.Fa nt .
|
|
The callback is invoked with the with the user-supplied value
|
|
.Fa arg
|
|
and a pointer to the current node.
|
|
.\"
|
|
.Sh SEE ALSO
|
|
.Xr ieee80211 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm ieee80211
|
|
series of functions first appeared in
|
|
.Nx 1.5 ,
|
|
and were later ported to
|
|
.Fx 4.6 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
This man page was written by
|
|
.An Bruce M. Simpson Aq bms@FreeBSD.org
|
|
and
|
|
.An Darron Broad Aq darron@kewl.org .
|