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 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
  44 The "options" part can be as follows:
  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
  70    d   Join-delayed channel members
  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
 103    o : Include oplevel (shows 999 to users without ops in the channel)
 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