share/man/man4/ieee80211.4

   1 .\" Copyright (c) 2001
   2 .\"     The Aerospace Corporation.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AEROSPACE CORPORATION ``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 AEROSPACE CORPORATION 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$
  29 .\"
  30 .Dd February 23, 2001
  31 .Dt IEEE80211 4
  32 .Os
  33 .Sh NAME
  34 .Nm ieee80211
  35 .Nd standard interface to IEEE 802.11 devices
  36 .Sh SYNOPSIS
  37 .In sys/types.h
  38 .In sys/socket.h
  39 .In net/if.h
  40 .In net/ethernet.h
  41 .In net/if_ieee80211.h
  42 .Sh DESCRIPTION
  43 This section describes the standard interface to configuration
  44 and status information on IEEE 802.11 devices.
  45 Most devices support options not configurable by this interface.
  46 They must be set by their respective, specific control program.
  47 The interface is via one
  48 of the following
  49 .Xr ioctl 2
  50 calls on a socket:
  51 .Bl -tag -width ".Dv SIOCG80211"
  52 .It Dv SIOCG80211
  53 Get configuration or status information.
  54 .It Dv SIOCS80211
  55 Set configuration information.
  56 .El
  57 .Pp
  58 These requests are made via a modified
  59 .Vt ifreq
  60 structure.
  61 This structure is defined as follows:
  62 .Bd -literal
  63 struct ieee80211req {
  64         char            i_name[IFNAMSIZ];       /* if_name, e.g. "wi0" */
  65         u_int16_t       i_type;                 /* req type */
  66         int16_t         i_val;                  /* Index or simple value */
  67         int16_t         i_len;                  /* Index or simple value */
  68         void            *i_data;                /* Extra data */
  69 };
  70 .Ed
  71 .Pp
  72 For
  73 .Dv SIOCG80211
  74 the following values of
  75 .Va i_type
  76 are valid:
  77 .Bl -tag -width indent
  78 .It Dv IEEE80211_IOC_SSID
  79 Returns the requested SSID by copying it into the buffer pointed to by
  80 .Va i_data
  81 and setting
  82 .Va i_len
  83 to the length.
  84 If
  85 .Va i_val
  86 is \(>= 0 then the request refers to the configured value for that slot.
  87 Generally, 0 is the only valid value, but some interfaces support more
  88 SSIDs.
  89 If
  90 .Va i_val
  91 is \-1 then the request refers to the currently active value.
  92 .It Dv IEEE80211_IOC_NUMSSIDS
  93 Returns the number of SSIDs this card supports.
  94 In most cases, this is
  95 1, but some devices such as
  96 .Xr an 4
  97 support more.
  98 .It Dv IEEE80211_IOC_WEP
  99 Returns the current WEP status in
 100 .Va i_val .
 101 Valid values are
 102 .Dv IEEE80211_WEP_NOSUP , IEEE80211_WEP_ON , IEEE80211_WEP_OFF ,
 103 and
 104 .Dv IEEE80211_WEP_MIXED .
 105 Respectively, these values mean unsupported, mandatory for all devices,
 106 off, and on, but not required for all devices.
 107 .It Dv IEEE80211_IOC_WEPKEY
 108 Returns the requested WEP key via
 109 .Va i_data
 110 and its length via
 111 .Va i_len .
 112 If the device does not support returning the WEP key or the user is not
 113 root then the key may be returned as all zeros.
 114 Technically this is a
 115 valid key, but it is the kind of key an idiot would put on his luggage so
 116 we use it as a special value.
 117 Generally, only four WEP keys are allowed, but some devices support more.
 118 If so, the first four (0-3) are
 119 the standard keys stored in volatile storage and the others are device
 120 specific.
 121 .It Dv IEEE80211_IOC_NUMWEPKEYS
 122 Returns the number of WEP keys supported by this device, generally 4.
 123 A device that does not support WEP may either report 0 or simply return
 124 .Er EINVAL .
 125 .It Dv IEEE80211_IOC_WEPTXKEY
 126 Returns the WEP key used for transmission.
 127 .It Dv IEEE80211_IOC_AUTHMODE
 128 Returns the current authentication mode in
 129 .Va i_val .
 130 Valid values are
 131 .Dv IEEE80211_AUTH_NONE , IEEE80211_AUTH_OPEN ,
 132 and
 133 .Dv IEEE80211_AUTH_SHARED .
 134 .It Dv IEEE80211_IOC_STATIONNAME
 135 Returns the station name via
 136 .Va i_data
 137 and its length via
 138 .Va i_len .
 139 While all known devices seem to support this in some way or another,
 140 they all do it differently and it appears to not have anything to do
 141 with the actual IEEE 802.11 standard so making up an answer may be
 142 necessary for future devices.
 143 .It Dv IEEE80211_IOC_CHANNEL
 144 Returns the current direct sequence spread spectrum channel in use.
 145 .It Dv IEEE80211_IOC_POWERSAVE
 146 Returns the current powersaving mode.
 147 Valid values are
 148 .Dv IEEE80211_POWERSAVE_NOSUP , IEEE80211_POWERSAVE_OFF ,
 149 .Dv IEEE80211_POWERSAVE_ON , IEEE80211_POWERSAVE_CAM ,
 150 .Dv IEEE80211_POWERSAVE_PSP ,
 151 and
 152 .Dv IEEE80211_POWERSAVE_PSP_CAM .
 153 Currently,
 154 .Dv IEEE80211_POWERSAVE_ON
 155 is defined to be equal to
 156 .Dv IEEE80211_POWERSAVE_CAM ,
 157 but this may be incorrect.
 158 .It Dv IEEE80211_IOC_POWERSAVESLEEP
 159 Returns the powersave sleep time in msec in
 160 .Va i_val .
 161 .El
 162 .Pp
 163 For
 164 .Dv SIOCS80211
 165 the following values of
 166 .Va i_type
 167 are valid:
 168 .Bl -tag -width indent
 169 .It Dv IEEE80211_IOC_SSID
 170 Set the desired SSID for infrastructure and ad-hoc modes to value given
 171 by
 172 .Va i_data
 173 and
 174 .Va i_len .
 175 The length should be no longer than 32 characters.
 176 .It Dv IEEE80211_IOC_WEP
 177 Set the current WEP mode to the value given in
 178 .Va i_val .
 179 Valid values are the same as those for this value above.
 180 Devices which
 181 do not support all modes may choose to either return
 182 .Er EINVAL
 183 or choose a reasonable alternate (supported) setting.
 184 .It Dv IEEE80211_IOC_WEPKEY
 185 Set the WEP key indicated by
 186 .Va i_val
 187 to the value given by
 188 .Va i_data
 189 and
 190 .Va i_len .
 191 Generally, valid values of
 192 .Va i_len
 193 are 0, 5, and 13 though not all devices with WEP support have support
 194 for 13-byte keys.
 195 .It Dv IEEE80211_IOC_WEPTXKEY
 196 Set the WEP key used for transmission to the value in
 197 .Va i_val .
 198 Not all values which are valid for setting keys may be valid for setting
 199 transmit keys due to strange device interfaces.
 200 .It Dv IEEE80211_IOC_AUTHMODE
 201 Set the current authorization mode to the value given in
 202 .Va i_val .
 203 Valid values are given above.
 204 Not all devices support this.
 205 .It Dv IEEE80211_IOC_STATIONNAME
 206 Set the station name to the value given by
 207 .Va i_data
 208 and
 209 .Va i_len .
 210 The standard does not appear to deal with this feature so the range of
 211 valid values may vary from device to device.
 212 .It Dv IEEE80211_IOC_CHANNEL
 213 Set the desired ad-hoc channel to the value given by
 214 .Va i_val .
 215 On some devices this has an impact on infrastructure mode as well.
 216 Valid values are 1-14, but 0 should be allowed and should return the
 217 device to the default value.
 218 May devices support this directly by
 219 converting any invalid value to the default value.
 220 .It Dv IEEE80211_IOC_POWERSAVE
 221 Set the current powersaving mode to the value given in
 222 .Va i_val .
 223 Valid values are the same as those for this value above.
 224 Devices which
 225 do not support all modes may choose to either return
 226 .Er EINVAL
 227 or choose a reasonable alternate (supported) setting.
 228 Most devices only
 229 support CAM mode.
 230 .It Dv IEEE80211_IOC_POWERSAVESLEEP
 231 Set the powersave sleep time in msec to the value in
 232 .Va i_val .
 233 .El
 234 .Sh SEE ALSO
 235 .Xr ioctl 2 ,
 236 .Xr an 4 ,
 237 .Xr ray 4 ,
 238 .Xr wi 4 ,
 239 .Xr ancontrol 8 ,
 240 .Xr ifconfig 8 ,
 241 .Xr raycontrol 8 ,
 242 .Sh HISTORY
 243 The
 244 .Nm
 245 manual appeared in
 246 .Fx 4.3 .