share/man/man9/ieee80211_output.9

   1 .\"
   2 .\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
   3 .\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\" $DragonFly: src/share/man/man9/ieee80211_output.9,v 1.7 2007/04/09 21:20:37 swildner Exp $
  29 .\" $Id: ieee80211_output.9,v 1.2 2004/07/07 12:59:39 ru Exp $
  30 .\"
  31 .Dd June 28, 2006
  32 .Dt IEEE80211_OUTPUT 9
  33 .Os
  34 .Sh NAME
  35 .Nm ieee80211_encap ,
  36 .Nm ieee80211_send_mgmt ,
  37 .Nm ieee80211_add_ssid ,
  38 .Nm ieee80211_add_rates ,
  39 .Nm ieee80211_add_xrates
  40 .Nd software 802.11 stack output functions
  41 .Sh SYNOPSIS
  42 .In netproto/802_11/ieee80211_var.h
  43 .In netproto/802_11/ieee80211_proto.h
  44 .Ft struct mbuf *
  45 .Fo ieee80211_encap
  46 .Fa "struct ieee80211com *ic" "struct mbuf *m" "struct ieee80211_node *ni"
  47 .Fc
  48 .Ft int
  49 .Fo ieee80211_send_mgmt
  50 .Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "int type" "int arg"
  51 .Fc
  52 .Ft uint8_t *
  53 .Fn ieee80211_add_ssid "uint8_t *frm" "const uint8_t *ssid" "int ssid_len"
  54 .Ft uint8_t *
  55 .Fn ieee80211_add_rates "uint8_t *frm" "const struct ieee80211_rateset *rs"
  56 .Ft uint8_t *
  57 .Fn ieee80211_add_xrates "uint8_t *frm" "const struct ieee80211_rateset *rs"
  58 .Sh DESCRIPTION
  59 These functions handle the encapsulation and transmission of 802.11 frames
  60 within the software 802.11 stack.
  61 .Pp
  62 The
  63 .Fn ieee80211_encap
  64 function encapsulates an outbound data frame contained within the
  65 mbuf chain
  66 .Fa m
  67 from the interface
  68 .Fa ic .
  69 The argument
  70 .Fa ni
  71 is a reference to the destination node.
  72 .Pp
  73 .\"
  74 The
  75 .Fn ieee80211_send_mgmt
  76 function transmits a management frame on the interface
  77 .Fa ic
  78 to the destination node
  79 .Fa ni
  80 of type
  81 .Fa type .
  82 The node entry
  83 .Fa ni
  84 must not be
  85 .Dv NULL
  86 and is typically the non-NULL return value of
  87 .Xr ieee80211_find_txnode 9 .
  88 This function is typically called through
  89 .Fn IEEE80211_SEND_MGMT ,
  90 which is a wrapper for the invocation of
  91 .Va ic_send_mgmt .
  92 .Pp
  93 The argument
  94 .Fa arg
  95 specifies either a sequence number for authentication operations,
  96 a status code for (re)association operations,
  97 or a reason for deauthentication and deassociation operations.
  98 .Pp
  99 The destination node
 100 .Fa ni
 101 will have its reference count incremented to reflect its use for an
 102 indeterminate amount of time.
 103 This reference is freed either in
 104 .Va if_start
 105 or,
 106 during the interrupt service routine for transmission completing
 107 if certain transmission rate control algorithms are used.
 108 .Pp
 109 .\"
 110 The
 111 .Fn ieee80211_add_ssid
 112 utility function is used to add the service set ID element
 113 .Fa ssid
 114 to the frame
 115 .Fa frm .
 116 The
 117 .Fa ssid_len
 118 argument indicates the length of the
 119 .Fa ssid
 120 to be added.
 121 .Pp
 122 .\"
 123 The
 124 .Fn ieee80211_add_rates
 125 utility function is used to add the rate set element
 126 .Fa rs
 127 to the frame
 128 .Fa frm .
 129 .Pp
 130 .\"
 131 The
 132 .Fn ieee80211_add_xrates
 133 utility function is used to add the extended rate set element
 134 .Fa rs
 135 to the frame
 136 .Fa frm .
 137 .Pp
 138 .\"
 139 The functions
 140 .Fn ieee80211_add_ssid ,
 141 .Fn ieee80211_add_rates
 142 and
 143 .Fn ieee80211_add_xrates
 144 are typically used when constructing management frames from within the
 145 software 802.11 stack in 802.11g mode.
 146 .\"
 147 .Sh RETURN VALUES
 148 If the function
 149 .Fn ieee80211_encap
 150 is successful,
 151 the mbuf chain
 152 .Fa m
 153 is updated with the 802.11 frame header prepended,
 154 and a pointer to the head of the updated mbuf chain is returned.
 155 If an error occurs,
 156 .Dv NULL
 157 will be returned,
 158 and
 159 .Fa m
 160 will be freed.
 161 .Pp
 162 .\"
 163 The function
 164 .Fn ieee80211_send_mgmt
 165 returns 0 if successful;
 166 if temporary buffer space is not available,
 167 it returns
 168 .Er ENOMEM .
 169 .Pp
 170 .\"
 171 The functions
 172 .Fn ieee80211_add_ssid ,
 173 .Fn ieee80211_add_rates
 174 and
 175 .Fn ieee80211_add_xrates
 176 return a pointer to the location in the
 177 .Fa frm
 178 after the addition of the second argument.
 179 .\"
 180 .Sh SEE ALSO
 181 .Xr ieee80211 9 ,
 182 .Xr ifnet 9
 183 .Sh HISTORY
 184 The
 185 .Nm ieee80211
 186 series of functions first appeared in
 187 .Nx 1.5 ,
 188 and were later ported to
 189 .Fx 4.6 .
 190 .Sh AUTHORS
 191 .An -nosplit
 192 This man page was written by
 193 .An Bruce M. Simpson Aq bms@FreeBSD.org
 194 and
 195 .An Darron Broad Aq darron@kewl.org .