xref: /dflybsd-src/share/man/man9/ieee80211_output.9 (revision 1102a27e1141baf846d4f8ced2aecee4870b4260)

.\"
.\" 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$
.\" $DragonFly: src/share/man/man9/ieee80211_output.9,v 1.4 2006/06/28 19:41:59 swildner Exp $
.\" $Id: ieee80211_output.9,v 1.2 2004/07/07 12:59:39 ru Exp $
.\"
.Dd June 28, 2006
.Dt IEEE80211_OUTPUT 9
.Os
.Sh NAME
.Nm ieee80211_encap ,
.Nm ieee80211_send_mgmt,
.Nm ieee80211_add_ssid ,
.Nm ieee80211_add_rates ,
.Nm ieee80211_add_xrates
.Nd software 802.11 stack output functions
.Sh SYNOPSIS
.In netproto/802_11/ieee80211_var.h
.In netproto/802_11/ieee80211_proto.h
.Ft struct mbuf *
.Fo ieee80211_encap
.Fa "struct ieee80211com *ic" "struct mbuf *m" "struct ieee80211_node *ni"
.Fc
.Ft int
.Fo ieee80211_send_mgmt
.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "int type" "int arg"
.Fc
.Ft uint8_t *
.Fn ieee80211_add_ssid "uint8_t *frm" "const uint8_t *ssid" "int ssid_len"
.Ft uint8_t *
.Fn ieee80211_add_rates "uint8_t *frm" "const struct ieee80211_rateset *rs"
.Ft uint8_t *
.Fn ieee80211_add_xrates "uint8_t *frm" "const struct ieee80211_rateset *rs"
.Sh DESCRIPTION
These functions handle the encapsulation and transmission of 802.11 frames
within the software 802.11 stack.
.Pp
The
.Fn ieee80211_encap
function encapsulates an outbound data frame contained within the
mbuf chain
.Fa m
from the interface
.Fa ic .
The argument
.Fa ni
is a reference to the destination node.
.Pp
.\"
The
.Fn ieee80211_send_mgmt
function transmits a management frame on the interface
.Fa ic
to the destination node
.Fa ni
of type
.Fa type .
The node entry
.Fa ni
must not be
.Dv NULL
and is typically the non-NULL return value of
.Xr ieee80211_find_txnode 9 .
This function is typically called through
.Fn IEEE80211_SEND_MGMT ,
which is a wrapper for the invocation of
.Va ic_send_mgmt .
.Pp
The argument
.Fa arg
specifies either a sequence number for authentication operations,
a status code for (re)association operations,
or a reason for deauthentication and deassociation operations.
.Pp
The destination node
.Fa ni
will have its reference count incremented to reflect its use for an
indeterminate amount of time.
This reference is freed either in
.Va if_start
or,
during the interrupt service routine for transmission completing
if certain transmission rate control algorithms are used.
.Pp
.\"
The
.Fn ieee80211_add_ssid
utility function is used to add the service set ID element
.Fa ssid
to the frame
.Fa frm .
The
.Fa ssid_len
argument indicates the length of the
.Fa ssid
to be added.
.Pp
.\"
The
.Fn ieee80211_add_rates
utility function is used to add the rate set element
.Fa rs
to the frame
.Fa frm .
.Pp
.\"
The
.Fn ieee80211_add_xrates
utility function is used to add the extended rate set element
.Fa rs
to the frame
.Fa frm .
.Pp
.\"
The functions
.Fn ieee80211_add_ssid ,
.Fn ieee80211_add_rate
and
.Fn ieee80211_add_xrate
are typically used when constructing management frames from within the
software 802.11 stack in 802.11g mode.
.Pp
.\"
.Sh RETURN VALUES
If the function
.Fn ieee80211_encap
is successful,
the mbuf chain
.Fa m
is updated with the 802.11 frame header prepended,
and a pointer to the head of the updated mbuf chain is returned.
If an error occurs,
.Dv NULL
will be returned,
and
.Fa m
will be freed.
.Pp
.\"
The function
.Fn ieee80211_send_mgmt
returns 0 if successful;
if temporary buffer space is not available,
it returns
.Er ENOMEM .
.Pp
.\"
The functions
.Fn ieee80211_add_ssid ,
.Fn ieee80211_add_rate
and
.Fn ieee80211_add_xrate
return a pointer to the location in the
.Fa frm
after the addition of the second argument.
.\"
.Sh SEE ALSO
.Xr ieee80211 9 ,
.Xr ifnet 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 .