doc/readme.who

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