This is an exhaustive list of all the Tcl commands added to eggdrop.  All
of the normal Tcl built-in commands are still there, of course.  But you
can also use these to manipulate features of the bot.  They are listed
according to category.

NOTICE:  This list is accurate for the v1.1 series of eggdrop!
SCRIPTS WHICH WERE WRITTEN FOR v0.9 OR v1.0 WILL PROBABLY NOT WORK WITHOUT
MODIFICATION.  Commands which have been changed in the v1.1 series (or are
just new commands) are marked with vertical bars on the left.



*** OUTPUT COMMANDS ***

  putserv <text>
    sends text to the server, like 'dump' (intended for direct server
      commands); output is queued so that you won't flood yourself off
      the server
    returns: nothing

  puthelp <text>
    sends text to the server like 'putserv', but uses a different queue
      (intended for sending messages to channels or people)
    returns: nothing

  putlog <text>
    sends text to the log for any channel, marked as 'misc' (o)
    returns: nothing

  putcmdlog <text>
    sends text to the log for any channel, marked as 'command' (c)
    returns: nothing

  putxferlog <text>
    sends text to the log for any channel, marked as 'file-area' (x)
    returns: nothing

  putloglev <level(s)> <channel> <text>
|   sends text to the log, tagged with all of the valid levels given (use
|     "*" to indicate all log levels)
    returns: nothing

  dumpfile <nick> <filename>
    dumps out a file from the text directory to a user on IRC via
      msg (one line per msg); %( and %[ won't work because it will
      assume the user is not an op or master


*** USER RECORD MANIPULATION COMMANDS ***

  countusers
    returns: number of users in the bot's database

  validuser <handle>
    returns: "1" if a user by that name exists; '0' otherwise

  finduser <nick!user@host>
    finds the user record which most closely matches the given user@host
    returns: the handle found, or "*" if none

  userlist [flags]
    returns: a list of the handles of users on the bot -- if you specify
      flags, only users who have ALL of those flags will be in the list

  passwdok <handle> <pass>
    checks the password given against the user's password -- if the user has
      not set a password, will always return "1"; check against the password
      "" (a blank string) to find out if a user has no password set
    returns: "1" if password matches for that user; "0" if not

  chpass <handle> [pass]
|   attempts to set a new password for a user, if that user exists; if you
|     leave off the password, it's reset (the user no longer has a password)

| chnick <old-handle> <new-handle>
|   changes a user's handle
|   returns: "1" on success; "0" if the handle is already used, the handle
|     is invalid, or the user can't be found

| chattr <handle> [changes [channel]]
|   changes the attributes for a user record, if you include any -- changes
|     are of the form "+f", "-o", "+dk", "-o+d", etc; if a channel is
|     specified, the channel-specific flags for that channel are altered
|   returns: new flags for the user (if you made no changes, returns current
|     flags); if a channel was specified, the channel-specific flags for that
|     channel are returned -- returns "*" if that user does not exist

  matchattr <handle> <flags>
    returns: "1" if the specified user has ALL the flags requested

| matchchanattr <handle> <flags> <channel>
|   returns: "1" if the specified user has ALL the channel-specific flags
|     requested for that channel

  adduser <handle> <hostmask>
    creates a new user entry with the handle and hostmask given (with no pass-
      word, and the default flags)
    returns: "1" if successful, "0" if it already existed

  addbot <handle> <address>
    creates a new bot entry with the handle and bot linking address given
      (with no password and no flags)
    returns: "1" if successful, "0" if it already existed

  deluser <handle>
    attempts to erase a user record with that handle
    returns: "1" if successful, "0" if no such user exists

  addhost <handle> <hostmask>
    adds a hostmask to the hostmask list for a user
    returns: nothing

  delhost <handle> <hostmask>
    deletes a hostmask from a user's hostmask list
    returns: "1" on success, "0" if that hostmask wasn't in the list or the
      user does not exist

  gethosts <handle>
    returns: the hostmask list for that user if there are any, "none" if
      the user exists but there are no hostmasks, "" if the user doesn't
      exist

  getinfo <handle>
    returns: info line for that user ("" if none exists); always returns
      an empty string for bots; if the user's info line is locked (ie, that
      user can't change their info line), the first character of the info
      line will be '@'

| getchaninfo <handle> <channel>
|   returns: info line for a specific channel (behaves just like 'getinfo')

  getaddr <handle>
    returns: link address for that bot ("" if none exists); always returns
      an empty string for non-bots

  getdccdir <handle>
    returns: dcc directory for that user ("" if none exists)

  getcomment <handle>
    returns: comment for that user ("" if none exists)

  getemail <handle>
    returns: email address for that user ("" if none exists)

  getxtra <handle>
    returns: xtra info for a user ("" if none exists)

| getlaston <handle> <channel>
|   returns: last time that user was on that channel (in unixtime format);
|     may return 0 if the user has never been on that channel or if there
|     is no such user

  setinfo <handle> <info>
    sets the info line for a user
    returns: nothing

|  setchaninfo <handle> <channel> <info>
|   sets the info line on a specific channel for a user
|   returns: nothing

  setdccdir <handle> <dccdir>
    sets the dcc directory for a user
    returns: nothing

  setcomment <handle> <comment>
    sets the comment for a user
    returns: nothing

  setemail <handle> <email>
    sets the email address for a user
    returns: nothing

  setxtra <handle> <xtrastuff>
    sets the xtra info for a user (this field exists specifically to be used
      by Tcl scripts)
    returns: nothing

| setlaston <handle> <channel> [timestamp]
|   sets the last time the user was on the channel to the current time (or
|     the time you specify, in unixtime)
|   returns: nothing

| newchanban <channel> <ban> <creator> <comment> [lifetime] [options]
|   adds a ban to the enforced ban list of a channel; creator is given
|     credit for the ban in the ban list; lifetime is specified in
|     minutes; if lifetime is not specified, ban-time (usually 60) is
|     used; setting the lifetime to 0 makes it a permanent ban; valid
|     options are:
|       sticky     forces the ban to be always active on a channel, even
|                    with dynamic bans on
|       none       (no effect)
|   returns: nothing

| newban <ban> <creator> <comment> [lifetime] [options]
|   adds a ban to the global ban list (which takes effect on all channels);
|     other arguments work exactly like newchanban
|   returns: nothing

  killchanban <channel> <ban>
    removes a ban from the enforced ban list for a channel
    returns: "1" if successful, "0" otherwise

  killban <ban>
    removes a ban from the global ban list
    returns: "1" if successful, "0" otherwise

  isban <ban> [channel]
    returns: "1" if that ban is in the global ban list, "0" otherwise; if
      a channel is specified, that channel's ban list is checked too
 
  ispermban <ban> [channel]
    returns: "1" if that ban is in the global ban list AND is marked as
      permanent, "0" otherwise; if a channel is specified, that channel's
      ban list is checked too

  matchban <nick!user@host> [channel]
    returns: "1" if that user address matches a ban in the global ban list,
      "0" otherwise; if a channel is specified, that channel's ban list is
      checked too

  banlist [channel]
    returns: list of global bans, or (if a channel is specified) list of
      channel-specific bans; each entry is itself a list, containing:
      hostmask, comment, expiration timestamp, time added, last time
      active, and creator (the three timestamps are in unixtime format)

  newignore <hostmask> <creator> <comment> [lifetime]
    adds an entry to the ignore list; creator is given credit for the
      ignore; lifetime is how many minutes until the ignore expires and
      is removed; if lifetime is not specified, ignore-time (usually 60)
      is used; setting the lifetime to 0 makes it a permanent ignore
    returns: nothing

  killignore <hostmask>
    removes an entry from the ignore list
    returns: "1" if successful, "0" otherwise

  ignorelist
    returns: list of ignores; each entry is itself a list, containing:
      hostmask, comment, expiration timestamp, time added, and creator
      (the three timestamps are in unixtime format)

  isignore <hostmask>
    returns: "1" if the ignore is in the list, "0" otherwise

  save
    writes the userfile to disk
    returns: nothing

  reload
    loads the userfile from disk (replacing whatever's in memory)
    returns: nothing

| backup
|   makes a simple backup of the userfile that's on disk
|   returns: nothing

  getting-users
    returns: "1" if the bot is currently downloading a userfile from
      a sharebot (and hence, user records are about to drastically
      change), "0" if not

| notes <user> [number]
|   gets info on notes stored for a user
|   returns: (if no numbers specified) number of notes for user,
|            -1 if no such user, -2 if notefile failure
|            (if a note number specified) the number'th note for the
|            user, -1 if no such user, -2 if notefile failure, 0 if
|            no such note. the note is a list, first element from,
|            2nd element timestamp, 3rd element the note itself

*** CHANNEL COMMANDS ***

  channel add <name> <option-list>
    adds a channel record for the bot to monitor; the full list of possible
      options is given in the "eggdrop.conf" sample config file; note that the
      channel options must be in a list (enclosed in {})
    returns: nothing

  channel set <name> <options...>
    sets options for the channel specified; the full list of possible
      options is given in the "eggdrop.conf" sample config file
    returns: nothing

  channel info <name>
    returns: list of info about that channel record: enforced mode, idle
      kick limit, need-op script, need-invite script, and then various
      +/- options as seen in the config file

  channel remove <name>
    destroys a channel record for the bot and makes the bot no longer
      monitor that channel
    returns: nothing

| savechannels
|   saves the channel settings to the channel-file if one is defined.
|   returns: nothing
   
| loadchannels
|   reloads the channel settings from the channel-file if one is defined.
|   returns: nothing
   
  channels
    returns: list of the channels the bot is monitoring (or trying to)

  botisop <channel>
    returns: "1" if the bot is an op on that channel; "0" otherwise

  isop <nickname> <channel>
    returns: "1" if someone by that nickname is on the channel and has chop;
      "0" otherwise

  isvoice <nickname> <channel>
    returns: "1" if someone by that nickname is on the channel and has voice
      (+v); "0" otherwise

  onchan <nickname> <channel>
    returns: "1" if someone by that nickname is on the bot's channel; "0"
      otherwise

  nick2hand <nickname> <channel>
    returns: handle of the person on the channel with that nickname, if
      someone by that nickname is on the channel; "" otherwise

  handonchan <handle> <channel>
    returns: "1" if the the user@host for someone on the channel matches
      for the handle given; "0" otherwise

  hand2nick <handle> <channel>
    returns: nickname of the first person on the channel whose user@host
      matches that handle, if there is one; "" otherwise

  ischanban <ban> <channel>
    returns: "1" if that is a ban on the bot's channel

  chanbans <channel>
    returns: a list of the current bans on the channel

| resetbans <channel>
|   removes all bans on the channel that aren't in the bot's ban list, and
|     refreshes any bans that should be on the channel but aren't
|   returns: nothing

| resetchan <channel>
|   rereads in the channel info from the server
|   returns: nothing

  getchanhost <nickname> <channel>
    returns: user@host of that person if they are on the channel; {} otherwise

| getchanjoin <nickname> <channel>
|   returns: timestamp of when that person joined the channel   

  onchansplit <nick> <channel>
    returns: "1" if that nick is split from the channel; "0" otherwise

| chanlist <channel> [flags[&chanflags]]
|   flags are any flags that are global flags, the '&' denotes to look for
|   channel specific flags.  Examples:
|      n         (Botowner)
|      &n        (Channel owner)
|      o&m       (Global op, Channel master)
    returns: list of nicknames currently on the bot's channel that have all
       of the flags specified; if no flags are given, all of the nicknames
       are returned

  getchanidle <nickname> <channel>
    returns: number of minutes that person has been idle; "0" if the speci-
      fied user isn't even on the channel

  getchanmode <channel>
    returns: string of the type "+ntik key" for the channel specified

  jump [server [port [password]]]
    jumps to the server specified, or (if none is specified) the next server
      in the list
    returns: nothing

  pushmode <channel> <mode> [arg]
    sends out a channel mode change (ex: pushmode #lame +o goober) through
      the bot's queueing system; all the mode changes will be sent out at
      once (combined into one line as much as possible) after the script
      finishes, or when 'flushmode' is called

  flushmode <channel>
    forces all previously pushed channel mode changes to go out right now,
      instead of when the script is done (just for the channel specified)

 
topic <channel>
    returns: string of the current topic on the specified channel

| validchan <channel>
|   checks if the bot is monitoring that channel
|   returns: 1 if the channel exists, 0 if not
|
| isdynamic <channel>
|   returns: 1 if the channel is an existing dynamic channel, 0 if not

*** DCC COMMANDS ***

  putdcc <idx> <text>
    sends text to the dcc user indicated
    returns: nothing

| putidx <idx> <text>
|   useful to  use in script connections, same as putdcc, but a little faster
|   sends text to the idx indicated
|   returns: nothing

  dccbroadcast <message>
    sends your message to everyone on the party line on the bot net, in the
      form "*** <message>" for local users, and "*** [Bot] <message>" for
      users on other bots
 
  dccputchan <channel> <message>
    sends your message to everyone on a certain channel on the bot net, in
      a form exactly like dccbroadcast does -- valid channels are 0 thru 99999
    returns: nothing

| boot <user@bot> [reason]
|    boot's a user from the partyline
|    returns: nothing

| restart
|   rehash's the bot and kills all timers
|   returns: nothing

| rehash
|   rehash's the bot
|   returns: nothing

  dccsimul <idx> <text...>
    simulates text typed in by the dcc user specified -- note that in v0.9,
      this only simulated commands; now a command must be preceded by a '.'
      to be simulated
    returns: nothing

  hand2idx <handle>
    returns: the idx (a number greater than or equal to zero) for the user
      given, if she is on the party line in chat mode (even if she is currently
      on a channel or in chat off), the file area, or in the control of a
      script; "-1" otherwise -- if the user is on multiple times, the oldest
      idx is returned

  idx2hand <idx>
    returns: handle of the user with that idx

| valididx <idx>
|   returns: "1" if the idx currently exists; "0" if not

  getchan <idx>
    returns: the current party line channel for a user on the party line --
      "0" indicates he's on the group party line, "-1" means he has chat off,
      and a value from 1 to 99999 is a private channel

  setchan <idx> <channel>
    sets a party line user's channel rather suddenly (the party line user
      is not notified that she is now on a new channel); a channel name
      can be used (provided it exists)
    returns: nothing

  console <idx> [channel] [console-modes]
    changes a dcc user's console mode, either to an absolute mode (like "mpj")
      or just adding/removing flags (like "+pj" or "-moc" or "+mp-c"); the
      user's console channel view can be changed also (as long as the new
      channel is defined in the bot)
    returns: a list containing the user's (new) channel view, and (new)
      console mode, or nothing if that user isn't currently in dcc chat

  echo <idx> [status]
    turns a user's echo on or off; the status has to be a 1 or 0
    returns: new value of echo for that user (or the current value, if
      status was omitted)

  putbot <bot-nick> <message>
    sends a message across the bot-net to another bot; if no script intercepts
      the message on the other end, the message just vanishes
    returns: nothing

  putallbots <message>
    broadcasts a message across the bot-net to all currently connected bots
    returns: nothing

  killdcc <idx>
    kills a party-line or file area connection, rather abruptly
    returns: nothing

  bots
    returns: list of the bots currently connected to the botnet

  dccused
    returns: number of dcc connections currently in use

  dcclist
    returns: list of active dcc connections that are in the chat area, the
      file area, or a script; each item in the list will be a sublist with
      four elements: idx, nickname, hostname, and type; type will be "chat",
      "files", "bot", "file_receiving", "file_sending", "file_send_pending",
      or "script" (or "socket" for connections that haven't been put under
      'control' yet)

  whom <chan>
    returns: list of people on the botnet who are on that channel (0 is
      the default party line); each item in the list will be a sublist
      with six elements: nickname, bot, hostname, access flag ('-', '@',
      '+', or '*'), minutes idle, and away message (blank if the user is
      not away)
|     if you specify a channel of * every user on the botnet is returned
|     with an extra argument indicating the channel the user is on

  getdccidle <idx>
    returns: number of seconds the dcc chat/file system/script user has
      been idle

  getdccaway <idx>
    returns: away message for a dcc chat user (or "" if the user is not
      set away)

  setdccaway <idx> <message>
    sets a party line user's away message and marks them away; if set to
      "", the user is marked un-away
    returns: nothing

  assoc <chan> [name]
    sets the name associated with a botnet channel, if you specify one
    returns: current name for that channel, if any

  killassoc <chan>
    removes the name associated with a botnet channel, if any exists
    returns: nothing

  connect <host> <port>
    makes an outgoing connection attempt and creates a dcc entry for it;
      a 'control' command should be used immediately after a successful
      'connect' so no input is lost
    returns: idx of the new connection

| listen <port> <type> [options]
|   opens a listening port to accept incoming telnets; type must be one of
|     "bots", "all", "users", "script", or "off":
| listen <port> bots [mask]
|   accepts connections from bots only; the optional mask is used to identify
|     permitted bot names; if the mask begins with '@' it is interpreted to
|     be a mask of permitted hosts to accept connections from
|   returns: port #
| listen <port> users [mask]
|   accepts connections from users only (no bots); the optional mask is used
|     to identify permitted nicknames; if the mask begins with '@' it is
|     interpreted to be a mask of permitted hosts to accept connections from
|   returns: port #
| listen <port> all [mask]
|   accepts connections from anyone; the optional mask is used to identify
|     permitted nicknames/botnames; if the mask begins with '@' it is
|     interpreted to be a mask of permitted hosts to accept connections from
|   returns: port #
| listen <port> script <proc>
|   accepts connections which are immediately routed to a proc; the proc
|     is called with one parameter: the idx of the new connection
|   returns: port #
| listen <port> off
|   stop listening at a port
|   returns: nothing

  dccdumpfile <idx> <filename>
    dumps out a file from the text directory to a dcc chat user; %( and
      %[ will work (unlike 'dumpfile')


*** FILE SYSTEM COMMANDS ***

  setpwd <idx> <dir>
    changes the directory of a file system user, in exactly the same way
      as a 'cd' command would (ie, the directory can be specified relative
      or absolute)
    returns: nothing

  getpwd <idx>
    returns: the current directory of a file system user

  getfiles <dir>
    returns: list of files in the directory given; the directory is relative
      to dcc-path

  getdirs <dir>
    returns: list of subdirectories in the directory given; the directory
      is relative to dcc-path

  dccsend <filename> <ircnick>
    attempts to start a dcc file transfer to the given nick; the filename must
      be specified either by full pathname or in relation to the bot's startup
      directory
    returns: "0" on success, "1" if the dcc table is full (too many con-
      nections), "2" if it can't open a socket for the transfer, "3" if the
      file doesn't exist, and "4" if the file was queued for later transfer
      (which means that person has too many file transfers going right now)

  filesend <idx> <filename> [ircnick]
    like dccsend, except it operates for a current filesystem user, and
      the filename is assumed to be a relative path from that user's
      current directory
    returns: "0" on failure; "1" on success (either an immediate send
      or a queued send)

  setdesc <dir> <file> <desc>
    sets the description for a file in a file system directory; the
      directory is relative to the dcc-path
    returns: nothing

  getdesc <dir> <file>
    returns: the description for a file in the file system, if one
      exists

  setowner <dir> <file> <handle>
    changes the owner for a file in the file system; the directory is
      relative to the dcc-path
    returns: nothing

  getowner <dir> <file>
    returns: the owner of a file in the file system

  setlink <dir> <file> <link>
    creates or changes a linked file (a file that actually exists on
      another bot); the directory is relative to dcc-path
    returns: nothing

  getlink <dir> <file>
    returns: the link for a linked file, if it exists

  getfileq <handle>
    returns: list of files queued by someone; each item in the list will be
      a sublist with two elements: nickname the file is being sent to, and
      the filename

  setuploads <handle> <#uploads> <size-in-k>
    sets a user's statistics on the number of files uploaded and the total
      kilobytes uploaded
    returns: nothing

  getuploads <handle>
    returns: list containing upload statistics for a user: the first
      element is the number of files uploaded; the second element is the
      total kilobytes uploaded

  setdnloads <handle> <#dnloads> <size-in-k>
    like setuploads, but sets the download statistics
    returns: nothing

  getdnloads <handle>
    returns: list containing download statistics, in the same format
      as getuploads

| mkdir <directory> [required-flags]
|   creates a directory in the files system, only users with the
|   required flags may access
|   returns:
|     0 on success
|     1 on can't create directory
|     2 on directory exists but is not a directory
|
| rmdir <directory>
|   removes a directory from the file system.
|   return: 0 on success, 1 on failure
|
| mv <file> <destination>
|   moves the file from it's source to the given destination, file
|   can also be a mask, eg /incoming/* provided the destination is
|   a directory
|   returns: number of files copied on success or negative numbers
|     to indicat errors: -1 = invalid source file, -2 = invalid desto
|     -3 = you're trying to copy onto itself (duh!) -4 = no matchs found
|
| cp <file> <destination>
|   exactly the same as mv except it leaves the original file there
|   aswell
|   returns: same as mv
|
| getflags <dir>
|   returns: the flags required to access this directory
|
| setflags <dir> [flags]
|   sets the flags required to access the directory
|   returns: 0 on success, -1 on failure

*** MISCELLANEOUS COMMANDS ***

  bind <type> <attr(s)> <command-name> [proc-name]
    adds a new keyword command to the bot; valid types are listed below; the
      <attr(s)> are the flags that a user must have to trigger this command;
      the <command-name> for each type is listed below; <proc-name> is the
      name of the Tcl procedure to call for this command (see below for the
|     format of the procedure call); if the proc-name is omitted, no binding
|     is added -- instead, the current binding is returned (if it's stackable,
|     a list of the current bindings is returned)
|   returns: name of the command that was added, or (if proc-name was omitted),
|     a list of the current bindings for this command

  unbind <type> <attr(s)> <command-name> <proc-name>
    removes a previously-made binding
    returns: name of the command that was removed

  logfile [<modes> <channel> <filename>]
    creates a new logfile, which will log the modes given for the channel
      listed -- or, if no logfile is specified, just returns a list of
      logfiles; "*" can be used to mean all channels; you can also change
      the modes and channel of an existing logfile with this command --
      entering a blank mode and channel makes the bot stop logging there
    returns: filename of logfile created, or (if no logfile is specified) a
      list of logfiles like: "{mco * eggdrop.log} {jp #lame lame.log}"

  maskhost <nick!user@host>
    returns: hostmask for the string given ("n!u@1.2.3.4" -> "*!u@1.2.3.*",
      "n!u@lame.com" -> "*!u@lame.com", "n!u@a.b.edu" -> "*!u@*.b.edu")

  timer <minutes> <tcl-command>
    executes the tcl command after a certain number of minutes have passed
    returns: a timerID

  utimer <seconds> <tcl-command>
    executes the tcl command after a certain number of seconds have passed
    returns: a timerID

  timers
    returns: list of active minutely timers; each entry in the list contains
      the number of minutes left till activation, the command that will be
      executed, and the timerID

  utimers
    returns: list of active secondly timers, identical in format to the
     
output from 'timers'

  killtimer <timerID>
    removes a minutely timer from the list
    returns: nothing

  killutimer <timerID>
    removes a secondly timer from the list
    returns: nothing

  unixtime
    returns: a long integer which is the current time according to unix

  time
    returns: the current time in 24-hour format (ie "14:15")

| strftime <formatstring> [time]
|   returns: a formatted string of time using standard strftime
|     fromat, uses the value of time, or now if no time specified

  date
    returns: the current date in standard format (ie "21 Dec 1994")

  ctime <unixtime>
    returns: a string of the date/time represented by the unix time given
      (ie "Fri Aug  3 11:34:55 1973")

  myip
    returns: a long number representing the bot's IP address, as it might
      appear in (for example) a DCC request

  rand <limit>
    returns: a random integer between 0 and limit-1 

  control <idx> <command>
    removes a user from the party line and sends all future input from them
      to the Tcl command given; the command will be called with two parameters:
      the idx of the user, and the input text; the command should return "0"
      to indicate success and "1" to indicate that it relinquishes control of
      the user back to the bot; the idx must be for a user in the party line
      area or the file area; if the input text is blank (""), it indicates
      that the dcc user has dropped connection
    returns: nothing

  sendnote <from> <to> <message>
    simulates what happens when one user sends a note to another (this can
      also do cross-bot notes)
    returns: "1" if the note was delivered locally or sent to another bot,
      "2" if the note was stored locally, "3" if the user's notebox is too
      full to store a note, "4" if a Tcl binding caught the note, "5" if
      the note was stored because the user is away, or "0" if the send failed

  link [via-bot] <bot>
    attempts to link to another bot directly (or, if you give a via-bot,
      it tells the via-bot to try
    returns: "1" if it looks okay and it will try; "0" if not

  unlink <bot>
    attempts to remove a bot from the botnet
    returns: "1" if it will try or has passed the request on; "0" if not

  encrypt <key> <string>
    returns: encrypted string (using blowfish), encoded into ascii using
      base-64 so it can be sent over the botnet

  decrypt <key> <encrypted-base64-string>
    returns: decrypted string (using blowfish)

  die [reason]
    causes the bot to log a fatal error and exit completely; if no reason
    is given, "EXIT" is used


GLOBAL VARIABLES:
  (All config-file variables are global, too.  But these three variables
  are set by the bot.)

  botnick
    current nickname the bot is using, ie 'Valis' or 'Valis0', etc

  botname
    current nick!user@host that the server sees, ie 'Valis!valis@crappy.com'

  server
    current server the bot is using, ie 'irc.math.ufl.edu:6667'

  version
    current bot version (ie: "1.1.2+pl1 1010201 pl1");
      first item is the text version, second item is a numerical version,
      and any following items are the names of patches that have been added

  uptime
    unixtime value for when the bot was started

 
COMMAND EXTENSION:

You can use the 'bind' command to attach Tcl procedures to certain events.
For example, you can write a Tcl procedure that gets called every time a
user says "danger" on the channel.  The following is a list of the types of
bindings, and how they work.  Under each binding type is the format of the
bind command, the list of arguments sent to the Tcl proc, and an explanation.

Some bindings are marked as "stackable".  That means that you can bind
multiple commands to the same trigger.  Normally, for example, a binding
of "bind msg - stop msg_stop" (which makes a msg-command "stop" call the
Tcl proc "msg_stop") will overwrite any previous binding you had for the
msg-command "stop".  With stackable bindings, like 'msgm' for example,
you can bind to the same command or mask again and again.  When the
binding is triggered, ALL the Tcl procs that are bound to it will be
called, one after another.

To remove a binding, use "unbind".  For example, to remove that binding
for the msg-command "stop", use "unbind msg - stop msg_stop".


  (1)  MSG
       bind msg <flags> <command> <proc>
       procname <nick> <user@host> <handle> <args>

       used for /msg commands; the first word of the user's msg is the
       command, and everything else becomes the argument string

  (2)  DCC
       bind dcc <flags> <command> <proc>
       procname <handle> <idx> <args>

       used for commands from a dcc chat on the party line; as in MSG, the
       command is the first word and everything else is the argument string;
       the idx is valid until the user disconnects; after that it may be
       reused, to be careful about storing an idx for long periods of time

  (3)  FIL
       bind fil <flags> <command> <proc>
       procname <handle> <idx> <args>

       the same as DCC, except this is triggered if the user is in the file
       area instead of the party line

  (4)  PUB
       bind pub <flags> <command> <proc>
       procname <nick> <user@host> <handle> <channel> <args>

       used for commands given on a channel; just like MSG, the first word
       becomes the command and everything else is the argument string

 
(5)  MSGM   (stackable)
       bind msgm <flags> <mask> <proc>
       procname <nick> <user@host> <handle> <text>

       matches the entire line of text from a /msg with the mask; this is
       more useful for binding Tcl procs to words or phrases spoken anywhere
       within a line of text

 
(6)  PUBM   (stackable)
       bind pubm <flags> <mask> <proc>
       procname <nick> <user@host> <handle> <channel> <text>
 
       just like MSGM, except it's triggered by things said on a channel
       instead of things /msg'd to the bot; the mask is matched against
       the channel name followed by the text, ie, "#nowhere hello there!",
       and can contain wildcards

  (7)  NOTC   (stackable)
      
bind notc <flags> <mask> <proc>
       procname <nick> <user@host> <handle> <text>

       matches the entire line of text from a /notice with the mask; it
       is considered a breach of protocol to respond to a /notice on IRC,
       so this is intended for internal use (ie, logging, etc) only

  (8)  JOIN   (stackable)
       bind join <flags> <mask> <proc>
       procname <nick> <user@host> <handle> <channel>
 
       triggered by someone joining the channel; the <mask> in the bind
       is matched against "#channel nick!user@host" and can contain
       wildcards

  (9)  PART   (stackable)
       bind part <flags> <mask> <proc>
       procname <nick> <user@host> <handle> <channel>

       triggered by someone leaving the channel; as in JOIN, the <mask>
       is matched against "#channel nick!user@host" and can contain
       wildcards

  (10) SIGN   (stackable)
       bind sign <flags> <mask> <proc>
       procname <nick> <user@host> <handle> <channel> <reason>
 
       triggered by a signoff, or possibly by someone who got netsplit and
       never returned; the signoff message is the last argument to the proc;
       wildcards can be used in <mask>, which contains the channel name

 
(11) TOPC   (stackable)
       bind topc <flags> <mask> <proc>
       procname <nick> <user@host> <handle> <channel> <topic>

       triggered by a topic change; can use wildcards in <mask>, which is
       matched against the channel name and new topic

  (12) KICK   (stackable)
       bind kick <flags> <mask> <proc>
       procname <nick> <user@host> <handle> <channel> <kicked-nick> <reason>
 
       triggered when someone is kicked off the channel; the <mask> is
       matched against "#channel nick" where the nickname is of the person
       who got kicked off (can use wildcards); the proc is called with
       the nick, user@host, and handle of the kicker, plus the channel,
       the nickname of the person who was kicked, and the reason; <flags>
       is unused here

  (13) NICK   (stackable)
      
bind nick <flags> <mask> <proc>
       procname <nick> <user@host> <handle> <channel> <newnick>
 
       triggered when someone changes nicknames; wildcards are allowed;
       the mask is matched against "#channel newnick"

 
(14) MODE   (stackable)
       bind mode <flags> <mask> <proc>
       proc-name <nick> <user@host> <handle> <channel> <mode-change>
 
       mode changes are broken down into their component parts before being
       sent here, so the <mode-change> will always be a single mode, like
       "+m" or "-o snowbot"; flags are ignored; the bot's automatic response
       to a mode change will happen AFTER all matching Tcl procs are called;
       the <mask> will have the channel prefixed (ie, "#turtle +m")

  (15) CTCP
       bind ctcp <flags> <keyword-mask> <proc>
       proc-name <nick> <user@host> <handle> <dest> <keyword> <args...>
   
       destination will be a nickname (the bot's nickname, obviously) or
       a channel name; keyword is the ctcp command and args may be empty;
       if the proc returns 0, the bot will attempt its own processing of
       the ctcp command

  (16) CTCR
       bind ctcr <flags> <keyword-mask> <proc>
       proc-name <nick> <user@host> <handle> <dest> <keyword> <args...>
 
       just like ctcp, but this is triggered for a ctcp-reply (ie, ctcp
       embedded in a notice instead of a privmsg)

| (17) RAW   (stackable)
|      bind raw <flags> <keyword-mask> <proc>
|      procname <from> <keyword> <args...>
|
|      previous versions of eggdrop required a special compile option to
|      enable this binding, but it's now standard; the mask is checked
|      against the keyword (either a numeric like "368" or a keyword like
|      "PRIVMSG"); from will be the server name or the source user (depending
|      on the keyword); flags are ignored; the order of the arguments is
|      identical to the order that the IRC server sends to the bot -- the
|      pre-processing only splits it apart enough to determine the keyword;
|      if the proc returns 1, eggdrop will not process the line any further
|      (THIS COULD CAUSE YOUR BOT TO BEHAVE ODDLY IN SOME CASES)

  (18) BOT
       bind bot <flags> <command> <proc>
       proc-name <from-bot> <command> <args>

       triggered by a message coming from another bot in the botnet; works
       similar to a DCC binding; the first word is the command and the rest
       becomes the argument string; flags are ignored

  (19) CHON   (stackable)
       bind chon <flags> <mask> <proc>
       proc-name <handle> <idx>

       when someone first enters the "party-line" area of the bot via dcc
       chat or telnet, this is triggered before they are connected to a
       chat channel (so yes, you can change the channel in a 'chon' proc);
       mask matches against handle; this is NOT triggered when someone
       returns from the file area, etc

  (20) CHOF   (stackable)
       bind chof <flags> <mask> <proc>
       proc-name <handle> <idx>

       triggered when someone leaves the party line to disconnect from the
       bot; mask matches against the handle; note that the connection may
       have already been dropped by the user, so don't send output to that
       idx

  (21) SENT   (stackable)
       bind sent <flags> <mask> <proc>
       proc-name <handle> <nick> <path/to/file>

       after a user has successfully downloaded a file from the bot, this
       binding is triggered; mask is matched against the handle of the user
       that initiated the transfer; nick is the actual recipient (on IRC) of
       the file; the path is relative to the dcc directory (unless the file
       transfer was started by a script call to 'dccsend', in which case the
       path is the exact path given in the call to 'dccsend')

  (22) RCVD   (stackable)
       bind rcvd <flags> <mask> <proc>
       proc-name <handle> <nick> <path/to/file>
 
       triggered after a user uploads a file successfully; mask is matched
       against the user's handle; nick is the nickname on IRC that the file
       transfer originated from; the path is where the file ended up,
       relative to the dcc directory (usually this is your incoming dir)

  (23) CHAT   (stackable)
       bind chat <flags> <mask> <proc>
       proc-name <nick> <channel#> <text>

       when someone says something on the botnet, it invokes this binding;
       flags is ignored; nick could be a user on this bot (ie "DronePup")
       or on another bot (ie "Eden@Wilde"); the mask is checked against the
       text

  (24) LINK   (stackable)
       bind link <flags> <mask> <proc>
       proc-name <botname> <via>

       triggered when a bot links into the botnet; botname is the name of
       the bot that just linked in; via is the bot it linked through; the
       mask is checked against the bot that linked; flags is ignored

  (25) DISC   (stackable)
       bind disc <flags> <mask> <proc>
       proc-name <botname>

       triggered when a bot disconnects from the botnet for whatever reason;
       just like the link bind, flags are ignored; mask is checked against the
       nickname of the bot that left

  (26) SPLT   (stackable)
       bind splt <flags> <mask> <proc>
       procname <nick> <user@host> <handle> <channel>
 
       triggered when someone gets netsplit on the channel; be aware that
       this may be a false alarm (it's easy to fake a netsplit signoff
       message); <mask> may contain wildcards, and is matched against the
       channel and nick!user@host just like join; anyone who is SPLT will
       trigger a REJN or SIGN within the next 15 minutes

  (27) REJN   (stackable)
       bind rejn <flags> <nick!user@host> <proc>
       procname <nick> <user@host> <handle> <channel>

       someone who was split has rejoined; <mask> can contain wildcards,
       and contains channel and nick!user@host just like join

| (28) FILT   (stackable)
|      bind filt <flags> <mask> <proc>
|      procname <idx> <text>
|
|      DCC party line and file system users have their text sent through
|      filt before being processed; if the proc a blank string, the text
|      is considered parsed; otherwise the bot will use the text returned
|      from the proc and continue parsing that

  (29) FLUD   (stackable)
       bind flud <flags> <type> <proc>
       procname <nick> <user@host> <handle> <type> <channel>

       any floods detected through the flood control settings (like
       'flood-ctcp') are sent here before processing; if the proc
       returns 1, no further action is taken on the flood; if the proc
       returns 0, the bot will do its normal "punishment" for the flood;
       the flood type is "pub", "msg", "join", or "ctcp" (and can be
       masked to "*" for the bind); flags is ignored

  (30) NOTE
       bind note <flags> <nickname> <proc>
       procname <from> <to> <text>

       incoming notes (either from the party line, someone on IRC, or
       someone on another bot on the botnet) are checked against these
       binds before being process; if a bind exists, the bot will not
       deliver the note; the nickname must be an exact match (no wild-
       cards), but it is not case sensitive; flags is ignored

  (31) ACT   (stackable)
       bind act <flags> <mask> <proc>
       proc-name <nick> <channel#> <action>

       when someone does an action on the botnet, it invokes this binding;
       flags is ignored; the mask is checked against the text of the
       action (this is very similar to the CHAT binding)

  (32) WALL   (stackable)
       bind wall <flags> <mask> <proc>
       proc-name <nick> <msg>

       when the bot receives a wallops, it invokes this binding; flags is
       ignored; the mask is checked against the text of the wallops msg

  (33) BCST   (stackable)
       bind chat <flags> <mask> <proc>
       proc-name <bot> <channel#> <text>

       when a bot says something on the botnet, it invokes this binding;
       flags is ignored; the mask is checked against the text

  (34) CHJN   (stackable)
       bind chat <flags> <mask> <proc>
       proc-name <bot> <nick> <channel#> <flag><sock> <from>

       when someone joins a botnet channel, it invokes this binding;
       flags is ignored; the mask is checked against the text

  (35) CHPT   (stackable)
       bind chat <flags> <mask> <proc>
       proc-name <bot> <nick> <sock>

       when someone parts a botnet channel, it invokes this binding;
       flags is ignored; the mask is checked against the text

| (36) TIME   (stackable)
|      bind time - <mask> <proc>
|      proc-name <bot> <min> <hour> <day> <month> <year>
|     
|      allows you to schedule procedure calls at certain times,
|      mask matches 5 space seperated integers of the form:
|      "min hour day month year"
      
(A) RETURN VALUES

    Several bindings pay attention to the value you return from the proc
    (using "return $value").  Usually they expect a 0 or 1, and failing
    to return any value is interpreted as a 0.

    Here's a list of the bindings that use the return value from procs
    they trigger:

    MSG   Return 1 to make the command get logged like so:
          (nick!user@host) !handle! command

    DCC   Return 1 to make the command get logged like so:
          #handle# command

    FIL   Return 1 to make the command get logged like so:
          #handle# files: command

    PUB   Return 1 to make the command get logged like so:
          <<nick>> !handle! command

    CTCP  Return 1 to ask the bot not to process the CTCP command on its
          own.  Otherwise it would send its own response to the CTCP
          (possibly an error message if it doesn't know how to deal with
          it).

    FILT  Return 1 to indicate the text has been processed, and the bot
          should just ignore it.  Otherwise it will treat the text like
          any other.

    FLUD  Return 1 to ask the bot not to take action on the flood.
          Otherwise it will do its normal punishment.

    RAW   Return 1 to ask the bot not to process the server text.  This
          can affect the bot's performance (by causing it to miss things
          that it would normally act on) -- you have been warned.

    WALL  Return 1 to make the command get logged liked so:
          !nick! msg

(B) CONTROL PROCEDURES

    Using the 'control' command you can put a DCC connection (or outgoing
    TCP connection) in control of a script.  All text that comes in on
    the connection is sent to the proc you specify.  All outgoing text
    should be sent with 'putdcc'.

    The control procedure is called with these parameters:
       procname <idx> <input-text>
    This allows you to use the same proc for several connections.  The
    idx will stay the same until the connection is dropped -- after that,
    it will probably get reused for a later connection.

    To indicate that the connection has closed, your control procedure
    will be called with blank text (the input-text will be "").  This
    is the only time it will ever be called with "" as the text, and it
    is the last time your proc will be called for that connection.

    If you want to hand control of your connection back to eggdrop, your
    proc should return 1.  Otherwise, return 0 to retain control.


(C) TCP CONNECTIONS

    Eggdrop allows you to make two types of TCP ("telnet") connections:
    outgoing and incoming.  For an outgoing connection, you specify the
    remote host and port to connect to.  For an incoming connection,
    you specify a port to listen at.

    All of the connections are *event driven*.  This means that the bot
    will trigger your procs when something happens on the connection,
    and your proc is expected to return as soon as possible.  Waiting
    in a proc for more input is a no-no.

    To initiate an outgoing connection, use:
       set idx [connect "hostname.goes.here" 3333]
    (as an example).  $idx now contains a new DCC entry for the outgoing
    connection.

    All connections use non-blocking (commonly called "asynchronous",
    which is a misnomer) I/O.  Without going into a big song and dance
    about asynchronous I/O, what this means to you is:

    * assume the connection succeeded immediately
    * if the connection failed, an EOF will arrive for that idx

    The only time a 'connect' call will return an error is if you gave
    a hostname and it couldn't find the IP for that hostname (this is
    considered a "DNS error").  Otherwise it will appear to have succeeded,
    and if the connection failed, you will immediately get an EOF.

    Right after doing a 'connect' call, you should set up a 'control' for
    the new idx (see the section above).  From then on, the connection
    will act just like a normal DCC connection that has been put under
    the control of a script.  If you ever return "1" from the control
    proc (indicating that you want control to return to eggdrop), the bot
    will just close the connection and dispose of it.  Other commands
    that work on normal DCC connections, like 'killdcc' and 'putdcc',
    will work on this idx too.

    To create a listening port, use:
       listen 6667 script grabproc
    which will create a new listening port at 6667, and assign it to the
    script 'grabproc'.

    When a new connection arrives, eggdrop will connect it up and create
    a new idx for the connection.  That idx is sent to 'grabproc'.  The
    proc will generally want to immediately put this idx under control:
       proc grabproc {newidx} {
         control $newidx my_control
       }
    Once your grabproc has been called, the idx behaves exactly like an
    outgoing connection would.

    The best way to learn how to use these commands is to find a script
    that uses them and follow it carefully.  Hopefully this has given you
    a good start though.


(D) MATCH CHARACTERS

    Many of the bindings allow match characters in the arguments.  Here
    are the four special characters:

    ?  matches any single character
    *  matches 0 or more characters of any type
    %  matches 0 or more non-space characters (can be used to match a
          single word)
    ~  matches 1 or more space characters (can be used for whitespace
          between words)
 
 

© 1996 - 2005 {Trond}   
Email