]>
Commit | Line | Data |
---|---|---|
189935b1 | 1 | WHO documentation, updated on 02 Jan 1999. |
2 | ||
3 | Since ircu2.10.02 the WHO command had been changed from what described in | |
4 | RFC1459, while still keeping backward compatibility, actually it has been | |
5 | changed again in u2.10.05 so that since this release the format of the who | |
6 | query is now: | |
7 | ||
8 | [:source] WHO <mask1> [<options> [<mask2>]] | |
9 | ||
10 | <mask2> is optional, if mask2 is present it's used for matching and mask1 is | |
11 | ignored, otherwise mask1 is used for matching, since mask2 is the last | |
12 | parameter it *can* contain a space and this can help when trying to match a | |
13 | "realname". | |
14 | ||
15 | When matching IP numbers the <mask> can be in 3 forms: | |
16 | ||
17 | - The old and well known IRC masks using * and ? as wanted | |
18 | - The IPmask form a.b.c.d/e.f.g.h as used in most firewalls and | |
19 | system configurations, where what is before the / are the bits we expect | |
20 | in the IP number and what is after the / is the "filter mask" telling wich | |
21 | bits whould be considered and wich should be ignored. | |
22 | - The IPmask form a.b.c.d/bitcount where bitcount is an integer between 0 | |
23 | and 31 (inclusive), the matching will be for the IPs whose first | |
24 | "bitcount" bits are equal to those in a.b.c.d | |
25 | ||
26 | Note that: | |
27 | . The bitcount must be between 0 and 31, 32 is NOT good (and | |
28 | makes no sense to use it... just match against the static IP a.b.c.d) | |
29 | . The missing pieces of both the bitmask and the ipnumber in the forms | |
30 | ipnumber/bitmask and ipnumber/bitcount default to zero from right to left, | |
31 | this is NOT what inet_aton and most tools do but makes more sense here | |
32 | IMO, in example /who 194.243/16 is taken as /who 194.243.0.0/255.255.0.0 | |
33 | (inet_aton whould take 194.243 as 194.0.0.243). | |
34 | . For the above reason and specified validity limits 1.2.3.4/31 becomes | |
35 | 1.2.3.4/255.255.255.254 while 1.2.3.4/32 becomes 1.2.3.4/32.0.0.0 :) | |
36 | ||
37 | For all the other fields th match happens as has always been, i.e. it's only | |
38 | considered the IRC mask with * and ? (that is: don't expect to catch an user | |
39 | with "realname" = "1.2.3.4" when doing "/who 1.2/16 h" :) | |
40 | ||
41 | For both the masks and the options (and thus for all flags) case is NOT | |
42 | significative (so "/who <any> o" is exactly the same as "/who <ANY> O". | |
43 | ||
9f8856e9 | 44 | The "options" part can be as follows: |
189935b1 | 45 | |
46 | [<flags>][%[<fields>[,<querytype>]]] | |
47 | ||
48 | in which: | |
49 | ||
50 | <flags>: can be a sequence of field matching flags, use mode matching flags | |
51 | and special purpose flags | |
52 | ||
53 | Field matching flags, when one of these is specified the field in | |
54 | question is matched against the mask, otherwise it's not matched. | |
55 | ||
56 | n Nick (in nick!user@host) | |
57 | u Username (in nick!user@host) | |
58 | h Hostname (in nick!user@host) | |
59 | i Numeric IP (the unresolved host) | |
60 | s Servername (the canonic name of the server the guy is on) | |
61 | r Info text (formerly "Realname") | |
62 | a Account name | |
63 | ||
64 | If no field-matching flags are specified they default to what old servers | |
65 | used to do: nuhsr (= everything except the numeric IP) | |
66 | ||
67 | User mode matching flags (specifying one of these means that only clients | |
68 | with that umode are considered, what is not specified is always matched): | |
69 | ||
7e3a3d58 | 70 | d Join-delayed channel members |
189935b1 | 71 | o Irc operator |
72 | [In the future more flags will be supported, basically all | |
73 | usermodes plus the +/- specificators to revert the filtering] | |
74 | ||
75 | Special purpose flags: | |
76 | ||
77 | x If this is specified the extended visibility of information for opers | |
78 | is applied, what this means depends on the fact that you are local or | |
79 | global operator and on how the admin configured the server (global | |
80 | and eventually local irc opers might be allowed with this flag to see | |
81 | +i local users, to see all +i users, to see users into +p and/or +s | |
82 | channels, and so on). Using the 'x' flag while not being an irc | |
83 | operator is meaningless (it will be ignored), using it while oper'd | |
84 | means that the query is almost certainly logged and the admin might | |
85 | (rightfully) ask you an explanation on why you did. | |
86 | ||
87 | The rest, what follows the %, that is [%[fields[,<querytype>]]], is as it | |
88 | has always been since the first who.patch, the <fields> part specifies | |
89 | wich fields to include in the output as: | |
90 | ||
91 | c : Include (first) channel name | |
92 | d : Include "distance" in hops (hopcount) | |
93 | f : Include flags (all of them) | |
94 | h : Include hostname | |
95 | i : Include IP | |
96 | l : Include idle time (0 for remote users) [2.10.11+] | |
97 | n : Include nick | |
98 | r : Include real name | |
99 | s : Include server name | |
100 | t : Include the querytype in the reply | |
101 | u : Include userID with eventual ~ | |
102 | a : Include account name | |
dd9731c9 | 103 | o : Include oplevel (shows 999 to users without ops in the channel) |
189935b1 | 104 | |
105 | And the ,<querytype> final option can be used to specify what you want the | |
106 | server to say in the querytype field of the output, useful to filter the | |
107 | output in scripts that do a kind of "on 354 ..." | |
108 | ||
109 | If no %fields are specified the reply is _exactly_ the same as has always | |
110 | been, numeric 352, same fields, same order. | |
111 | ||
112 | If one or more %fields are specified the reply uses a new numeric, since an | |
113 | out-of-standard 352 crashes EPIC and confuses several other clients. I used | |
114 | 354. | |
115 | ||
116 | :"source" 354 "target" ["querytype"] ["channel"] ["user"] | |
117 | ["IP"] ["host"] ["server"] ["nick"] | |
118 | ["flags"] ["hops"] ["idle"] ["account"] | |
119 | [:"realname"] | |
120 | ||
121 | Where only the fields specified in the %fields options are present. | |
122 | ||
123 | "querytype" is the same value passed in the /who command, it is provided to | |
124 | simplify scripting, in example one could pass a certain value in the query | |
125 | and have that value "signal" back what is to be done with those replies. | |
126 | ||
127 | The number of lines in the reply is still limited to avoid self-flooding and | |
128 | sooner or later another limitation will be added: you will be forced to do | |
129 | no more than one /who query every 'n' seconds where 'n' depends on the | |
130 | number of fields you actually match (the field-match flags specified before | |
131 | % in the option, defaulting to 6 if you don't specify an option at all), | |
132 | infact matching against many fields as the default query does severely | |
133 | affects the CPU usage of the server and is *much* better to specify with the | |
134 | field-matching flags what you are looking for, in example when you are | |
135 | looking for all french users a "/who *.fr h" is A LOT better than just "/who | |
136 | *.fr" (and actually you want users that have the | |
137 | _hostname_ matching *.fr, you wouldn't want to match a japanese user | |
138 | that has the realname "ku fung-kay aj.fr" in example...) | |
139 | ||
140 | Note that: | |
141 | ||
142 | - An user doing a "/who whatever" or a "/who whatever o" | |
143 | will not see any change (except for the anti-flood limit and sooner or | |
144 | later the CPU usage limit) | |
145 | ||
146 | - An user doing a "/who #wasteland %n" will get just a list of nicks (lame, | |
147 | very lame way of doing it :-) | |
148 | ||
149 | - An user doing a "/who 0 o%nuhs" will get a list of the opers with Nick, | |
150 | userID, server and hostname like: | |
151 | ||
152 | :Amst* 354 Nemesi #wasteland nbakker pc73.a.sn.no Oslo*.org Niels | |
153 | ||
154 | - An user doing a "/who 0 o%tnuhs,166" will get a list of the opers | |
155 | with Nick, userID, server and hostname like the above but with a | |
156 | request type field of 166 like: | |
157 | ||
158 | :Amst* 354 Nemesi 166 #wasteland nbakker pc73.a.sn.no | |
159 | Oslo-R.NO.EU.Undernet.org Niels | |
160 | ||
161 | So that he can have in example a script that does | |
162 | on ^354 "% 166" display "There is an oper ..." | |
163 | ||
164 | - The client will have to sort/format the fields by itself, | |
165 | the _order_ in which flags are passed is not significant, the fields in the | |
166 | reply will always have the same order. | |
167 | ||
168 | - The maximum number of _lines_ reported as reply for a query | |
169 | is 2048/(n+4) where 'n' is the number of flags "enabled" that is the | |
170 | number of fields included in each reply. | |
171 | ||
172 | Actually: 1 field returned = maximum 409 replies | |
173 | 2 fields returned = maximum 341 replies | |
174 | 3 fields returned = maximum 292 replies | |
175 | 4 fields returned = maximum 256 replies | |
176 | 5 fields returned = maximum 227 replies | |
177 | 6 fields returned = maximum 204 replies | |
178 | 7 fields returned = maximum 186 replies (default query) | |
179 | 8 fields returned = maximum 170 replies | |
180 | 9 fields returned = maximum 157 replies | |
181 | 10 fields returned = maximum 146 replies | |
182 | ||
183 | If the limit is reached before completing the query the reply is truncated | |
184 | and a new numeric error is issued after the "End of WHO", anyway the "end | |
185 | of" numeric is _always_ sent (otherwise some scripts and clients go | |
186 | crazy). | |
187 | ||
188 | The actual "mask" to match can have one of the two following forms: | |
189 | ||
190 | - A comma-separated list of elements: in this case each element | |
191 | is treated as a flat channel or nick name and is not matched to the other | |
192 | elements. Nicks do count in the limit of output lines (they should not be | |
193 | that many anyway), channels count if who asks the query is not on the | |
194 | channel. (That is: a /who #channel gives unlimited output if you are in | |
195 | there). | |
196 | ||
197 | - A _single_ mask: in this case (no commas, only one element) the mask is | |
198 | first checked to be a full channel or nickname, then it is matched against | |
199 | all relevant fiels as already known. These happens in different steps | |
200 | with replicates-removal so that if one has (?) something like "#wasteland" | |
201 | as "real name" or is on a channel named "#***MyChan***" it all works | |
202 | nicely. | |
203 | ||
204 | Miscellaneous bug fixes / "undocumented feature" changes: | |
205 | ||
206 | - /who NickName did not show the user with nick = NickName when it was | |
207 | invisible, even if the nick was given completely (without wildchars) now | |
208 | it does, since one could always see him as /whois NickName. It does not | |
209 | report him twice if he also has in example the userID == NickName and is | |
210 | -i. | |
211 | ||
212 | - ":source WHO :The Black Hacker" did not report an user having "The Black | |
213 | Hacker" as real name, now it does. Since this can only be done without the | |
214 | flags/format specificator because that would become the "last parameter" | |
215 | an escape has been provided: if you pass to m_who _3_ parameters the first | |
216 | one will be ignored and the last one used for matching, like in example | |
217 | ":source WHO foo %nuh :*Black Hacker*" where "foo" will not be used and | |
218 | the match will happen on "*Black Hacker*". (It was passed through | |
219 | clean_channelname() that prevented the mask from containing spaces and | |
220 | such...) | |
221 | ||
222 | - When one user was umode -i he was shown or not depending on the | |
223 | fact he was on a +p or +s channel... since we are doing a lookup on the | |
224 | _user_ this makes no sense to me, example: | |
225 | Neme1 : umode -i, on no channels, was SEEN with a /who 0 | |
226 | Neme2 : umode -i, on channel #p with chmode +p, was NOT SEEN by /who 0 | |
227 | Neme3 : umode -i, on channel #s with chmode +s, was NOT SEEN by /who 0 | |
228 | ||
229 | Now all users "-i" are matched with a "/who mask", the +i users instead | |
230 | must be on a _common_ channel to be seen. | |
231 | ||
232 | Basically being on "one" +s|p channel "forced" a +i status while one might | |
233 | want to be on #secret (mode +s) and have nobody know that he is in there | |
234 | but on the other side stay -i so others can find him. Of course a +s|p | |
235 | channel is never shown in the reply unless who asks the query is in there, | |
236 | if no "visible" channels are available for a -i user he is shown on | |
237 | "channel *". | |
238 | ||
239 | - When one user is +i is shown _only_ if there is a common channel, | |
240 | the first common channel found is shown in the reply. | |
241 | ||
242 | - As requested by many persons an escape has been provided for opers, | |
243 | when #defined SHOW_ALL_CHANNELS opers can /who #channel from outside | |
244 | and see users in there even if the channel is +s|+p | |
245 | Each admin decides locally if this feature is enabled to his opers. | |
246 | ||
247 | - As requested by many admins an escape from the query-size limit | |
248 | has been provided for opers, by #defining UNLIMIT_OPER_QUERY opers | |
249 | can do unlimited sized /who-s (until they get disconnected by max | |
250 | SendQ exceeded ;) | |
251 | Again admins will decide if enable or not this feature. | |
252 | ||
253 | - A /who a,c,b,d,e,f used to return as many ** END OF WHO as there | |
254 | were elements in the list, since now the command is supposed to be | |
255 | _efficient_ for /who nick1,nick2,nick3 .. I return a _single_ end | |
256 | of query message. | |
257 | ||
258 | - /who did not work for a channel named in example #**StarWars** | |
259 | now it does handle it properly (the mask was passed through | |
260 | collapse() and then.. did not find that channel, fixed). | |
261 | ||
262 | - "/who #John" did not report an user having '#John' as "Real name", | |
263 | now it does (and does NOT report him twice if he is ALSO on a | |
264 | channel named #John, strange but true: this can happen). | |
265 | ||
266 | - "/who a,b,c,d" where a b c and d are channelnames/nicks now uses an hash | |
267 | lookup and therefore is extremely efficient, if _only_ one field is | |
268 | specified it is looked in all the fields; who really wants _only_ users on | |
269 | a specific channel or a single nick (without looking for a match in the | |
270 | other fields) can force the server to consider the parameter as a list | |
271 | adding a comma somewhere, like: | |
272 | ||
273 | "/who #Italia," or "/who ,Nemesi" | |
274 | ||
275 | Or even better to avoid misbehaviour with other servers: | |
276 | "/who #Italia %... #Italia," or "/who Nemesi %... Nemesi," | |
277 | ||
278 | This will make old servers act properly and new ones and should be the | |
279 | recomended way for GUI based clients to get a channel's userlist and all | |
280 | the infos they want about users on the channel. | |
281 | ||
282 | - If you use the new numeric, flags will contain all the information about | |
283 | a user on a channel. @ for op'd, + for voiced, and ! for zombie. eg: | |
284 | Isomer #coder-com H@+, where the old behavor of just displaying one of | |
285 | them has been preserved for the old numeric. [2.10.11+] | |
286 | ||
287 | Regards, Andrea aka Nemesi | |
288 |