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