Tcl-commands

From Base de connaissances eggdrops & TCL
Jump to: navigation, search
This page contains changes which are not marked for translation.

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.

This list is accurate for Eggdrop v1.6.18. Scripts written for v1.3/v1.4 series of Eggdrop should probably work with a few minor modifications depending on the script. Scripts which were written for v0.9, v1.0, v1.1 or v1.2 will probably not work without modification. Commands which have been changed in this version of Eggdrop (or are just new commands) are marked with vertical bars (|) on the left.

Eggdrop Tcl Commands

OUTPUT COMMANDS

putserv

  • Description: sends text to the server, like '.dump' (intended for direct server commands); output is queued so that the bot won't flood itself off the server.
  • Syntax : putserv <text> [options]
  • Options:
    • -next: push messages to the front of the queue
    • -normal: no effect
  • Returns: nothing
  • Module: server

puthelp

  • Description: sends text to the server, like 'putserv', but it uses a different queue intended for sending messages to channels or people.
  • Syntax : puthelp <text> [options]
  • Options:
    • -next: push messages to the front of the queue
    • -normal: no effect
  • Returns: nothing
  • Module: server

putquick

putquick <text> [options]

   Description: sends text to the server, like 'putserv', but it uses a
     different (and faster) queue.
   Options:
     -next:   push messages to the front of the queue
     -normal: no effect
   Returns: nothing
   Module: server


putkick <channel> <nick,nick,...> [reason]

   Description: sends kicks to the server and tries to put as many nicks
     into one kick command as possible.
   Returns: nothing
   Module: irc


putlog <text>

   Description: sends text to the bot's logfile, marked as 'misc' (o)
   Returns: nothing
   Module: core


putcmdlog <text>

   Description: sends text to the bot's logfile, marked as 'command' (c)
   Returns: nothing
   Module: core


putxferlog <text>

   Description: sends text to the bot's logfile, marked as 'file-area' (x)
   Returns: nothing
   Module: core


putloglev <level(s)> <channel> <text>

   Description: sends text to the bot's logfile, tagged with all of the
     valid levels given. Use "*" to indicate all log levels.
   Returns: nothing
   Module: core


dumpfile <nick> <filename>

   Description: dumps file from the help/text directory to a user on IRC via
     msg (one line per msg). The user has no flags, so the flag bindings
     won't work within the file.
   Returns: nothing
   Module: core


queuesize [queue]

   Returns: the number of messages in all queues. If a queue is specified,
     only the size of this queue is returned. Valid queues are: mode,
     server, help.
   Module: server


clearqueue <queue>

   Description: removes all messages from a queue. Valid arguments are:
     mode, server, help, or all.
   Returns: the number of deleted lines from the specified queue.
   Module: server

USER RECORD MANIPULATION COMMANDS

countusers

   Returns: number of users in the bot's database
   Module: core


validuser <handle>

   Returns: 1 if a user by that name exists; 0 otherwise
   Module: core


finduser <nick!user@host>

   Description: finds the user record which most closely matches the given
     nick!user@host
   Returns: the handle found, or "*" if none
   Module: core


userlist [flags]

   Returns: a list of users on the bot. You can use the flag matching
     system here ([global]{&/|}[chan]{&/|}[bot]). '&' specifies "and";
     '|' specifies "or".
   Module: core


passwdok <handle> <pass>

   Description: checks the password given against the user's password.
     Check against the password "" (a blank string) or "-" to find out
     if a user has no password set.
   Returns: 1 if the password matches for that user; 0 otherwise
   Module: core


getuser <handle> <entry-type> [extra info]

   Description: an interface to the new generic userfile support. Valid
     entry types are:
       BOTFL   - returns the current bot-specific flags for the user
                 (bot-only)
       BOTADDR - returns a list containing the bot's address, telnet port,
                 and relay port (bot-only)
       HOSTS   - returns a list of hosts for the user
       LASTON  - returns a list containing the unixtime last seen and the
                 last seen place. LASTON #channel returns the time last
                 seen time for the channel or 0 if no info exists.
       INFO    - returns the user's global info line
       XTRA    - returns the user's XTRA info
       COMMENT - returns the master-visible only comment for the user
       EMAIL   - returns the user's e-mail address
       URL     - returns the user's url
       HANDLE  - returns the user's handle as it is saved in the userfile
       PASS    - returns the user's encrypted password
   Returns: info specific to each entry-type
   Module: core


setuser <handle> <entry-type> [extra info]

   Description: this is the counterpart of getuser. It lets you set the
     various values. Other then the ones listed below, the entry-types are
     the same as getuser's.
       PASS    - sets a users password (no third arg will clear it)
       HOSTS   - if used with no third arg, all hosts for the user will be
                 be cleared. Otherwise, *1* hostmask is added :P
       LASTON  - This setting has 3 forms. "setuser <handle> LASTON
                 <unixtime> <place>" sets global LASTON time, "setuser
                 <handle> LASTON <unixtime>" sets global LASTON time
                 (leaving the place field empty), and "setuser <handle>
                 LASTON <unixtime> <channel>" sets a users LASTON time for
                 a channel (if it is a  valid channel).
   Returns: nothing
   Module: core


chhandle <old-handle> <new-handle>

   Description: changes a user's handle
   Returns: 1 on success; 0 if the new handle is invalid or already used,
     or if the user can't be found
   Module: core


chattr <handle> [changes [channel]]

   Description: changes the attributes for a user record, if you include any.
     Changes are of the form '+f', '-o', '+dk', '-o+d', etc. If changes are
     specified in the format of |<changes> <channel>, the channel-specific
     flags for that channel are altered. You can now use the +o|-o #channel
     format here too.
   Returns: new flags for the user (if you made no changes, the current
     flags are returned). If a channel was specified, the global AND the
     channel-specific flags for that channel are returned in the format of
     globalflags|channelflags. "*" is returned if the specified user does
     not exist.
   Module: core


botattr <handle> [changes [channel]]

   Description: similar to chattr except this modifies bot flags rather
     than normal user attributes.
   Returns: new flags for the bot (if you made no changes, the current
     flags are returned). If a channel was specified, the global AND the
     channel-specific flags for that channel are returned in the format of
     globalflags|channelflags. "*" is returned if the specified bot does
     not exist.
   Module: core


matchattr <handle> <flags> [channel]

   Returns: 1 if the specified user has the specified flags; 0 otherwise
   Module: core


adduser <handle> [hostmask]

   Description: creates a new user entry with the handle and hostmask given
     (with no password and the default flags)
   Returns: 1 if successful; 0 if the handle already exists
   Module: core


addbot <handle> <address>

   Description: adds a new bot to the userlist with the handle and bot
     address given (with no password and no flags)
   Returns: 1 if successful; 0 if the bot already exists
   Module: core


deluser <handle>

   Description: attempts to erase the user record for a handle
   Returns: 1 if successful, 0 if no such user exists
   Module: core


delhost <handle> <hostmask>

   Description: deletes a hostmask from a user's host list
   Returns: 1 on success; 0 if the hostmask (or user) doesn't exist
   Module: core


addchanrec <handle> <channel>

   Description: adds a channel record for a user
   Returns: 1 on success; 0 if the user or channel does not exist
   Module: channels


delchanrec <handle> <channel>

   Description: removes a channel record for a user. This includes all
     associated channel flags.
   Returns: 1 on success; 0 if the user or channel does not exist
   Module: channels


haschanrec <handle> <channel>

   Returns: 1 if the given handle has a chanrec for the specified channel;
     0 otherwise
   Module: channels


getchaninfo <handle> <channel>

   Returns: info line for a specific channel (behaves just like 'getinfo')
   Module: channels


setchaninfo <handle> <channel> <info>

  Description: sets the info line on a specific channel for a user. If
    info is "none", it will be removed.
  Returns: nothing
  Module: channels


newchanban <channel> <ban> <creator> <comment> [lifetime] [options]

   Description: adds a ban to the 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.
   Options:
     sticky: forces the ban to be always active on a channel, even
             with dynamicbans on
     none:   no effect
   Returns: nothing
   Module: channels


newban <ban> <creator> <comment> [lifetime] [options]

   Description: adds a ban to the global ban list (which takes effect on
     all channels); creator is given credit for the ban in the ban list.
     lifetime is specified in minutes. If lifetime is not specified,
     global-ban-time (usually 60) is used. Setting the lifetime to 0 makes
     it a permanent ban.
   Options:
     sticky: forces the ban to be always active on a channel, even
             with dynamicbans on
     none:   no effect
   Returns: nothing
   Module: channels


newchanexempt <channel> <exempt> <creator> <comment> [lifetime] [options]

   Description: adds a exempt to the exempt list of a channel; creator is
     given credit for the exempt in the exempt list. lifetime is specified
     in minutes. If lifetime is not specified, exempt-time (usually 60) is
     used. Setting the lifetime to 0 makes it a permanent exempt. The exempt
     will not be removed until the corresponding ban has been removed. For
     timed bans, once the time period has expired, the exempt will not be
     removed until the corresponding ban has either expired or been removed.
   Options:
     sticky: forces the exempt to be always active on a channel, even
             with dynamicexempts on
     none:   no effect
   Returns: nothing
   Module: channels


newexempt <exempt> <creator> <comment> [lifetime] [options]

   Description: adds a exempt to the global exempt list (which takes effect
     on all channels); creator is given credit for the exempt in the exempt
     list. lifetime is specified in minutes. If lifetime is not specified,
     exempt-time (usually 60) is used. Setting the lifetime to 0 makes it a
     permanent exempt. The exempt will not be removed until the
     corresponding ban has been removed.
   Options:
     sticky: forces the exempt to be always active on a channel, even
             with dynamicexempts on
     none:   no effect
   Returns: nothing
   Module: channels


newchaninvite <channel> <invite> <creator> <comment> [lifetime] [options]

   Description: adds a invite to the invite list of a channel; creator is
     given credit for the invite in the invite list. lifetime is specified
     in minutes. If lifetime is not specified, invite-time (usually 60) is
     used. Setting the lifetime to 0 makes it a permanent invite. The invite
     will not be removed until the channel has gone -i.
   Options:
     sticky: forces the invite to be always active on a channel, even
             with dynamicinvites on
     none:   no effect
   Returns: nothing
   Module: channels


newinvite <invite> <creator> <comment> [lifetime] [options]

   Description: adds a invite to the global invite list (which takes effect
     on all channels); creator is given credit for the invite in the invite
     list. lifetime is specified in minutes. If lifetime is not specified,
     invite-time (usually 60) is used. Setting the lifetime to 0 makes it
     a permanent invite. The invite will not be removed until the channel
     has gone -i.
   Options:
     sticky: forces the invite to be always active on a channel, even
             with dynamicinvites on
     none:   no effect
   Returns: nothing
   Module: channels


stick <banmask> [channel]

   Description: makes a ban sticky, or, if a channel is specified, then it
     is set sticky on that channel only.
   Returns: 1 on success; 0 otherwise
   Module: channels


unstick <banmask> [channel]

   Description: makes a ban no longer sticky, or, if a channel is
     specified, then it is unstuck on that channel only.
   Returns: 1 on success; 0 otherwise
   Module: channels


stickexempt <exemptmask> [channel]

   Description: makes an exempt sticky, or, if a channel is specified,
     then it is set sticky on that channel only.
   Returns: 1 on success; 0 otherwise
   Module: channels


unstickexempt <exemptmask> [channel]

   Description: makes an exempt no longer sticky, or, if a channel is
     specified, then it is unstuck on that channel only.
   Returns: 1 on success; 0 otherwise
   Module: channels


stickinvite <invitemask> [channel]

   Description: makes an invite sticky, or, if a channel is specified,
     then it is set sticky on that channel only.
   Returns: 1 on success; 0 otherwise
   Module: channels


unstickinvite <invitemask> [channel]

   Description: makes an invite no longer sticky, or, if a channel is
     specified, then it is unstuck on that channel only.
   Returns: 1 on success; 0 otherwise
   Module: channels


killchanban <channel> <ban>

   Description: removes a ban from the ban list for a channel
   Returns: 1 on success; 0 otherwise
   Module: channels


killban <ban>

   Description: removes a ban from the global ban list
   Returns: 1 on success; 0 otherwise
   Module: channels


killchanexempt <channel> <exempt>

   Description: removes an exempt from the exempt list for a channel
   Returns: 1 on success; 0 otherwise
   Module: channels


killexempt <exempt>

   Description: removes an exempt from the global exempt list
   Returns: 1 on success; 0 otherwise
   Module: channels


killchaninvite <channel> <invite>

   Description: removes an invite from the invite list for a channel
   Returns: 1 on success; 0 otherwise
   Module: channels


killinvite <invite>

   Description: removes an invite from the global invite list
   Returns: 1 on success; 0 otherwise
   Module: channels


ischanjuped <channel>

   Returns: 1 if the channel is juped, and the bot is unable to join; 0
     otherwise
   Module: channels


isban <ban> [channel]

   Returns: 1 if the specified ban is in the global ban list; 0 otherwise.
     If a channel is specified, that channel's ban list is checked as well.
   Module: channels


ispermban <ban> [channel]

   Returns: 1 if the specified 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 as well.
   Module: channels


isexempt <exempt> [channel]

   Returns: 1 if the specified exempt is in the global exempt list; 0
     otherwise. If a channel is specified, that channel's exempt list is
     checked as well.
   Module: channels


ispermexempt <exempt> [channel]

   Returns: 1 if the specified exempt is in the global exempt list AND is
     marked as permanent; 0 otherwise. If a channel is specified, that
     channel's exempt list is checked as well.
   Module: channels


isinvite <invite> [channel]

   Returns: 1 if the specified invite is in the global invite list; 0
     otherwise. If a channel is specified, that channel's invite list is
     checked as well.
   Module: channels


isperminvite <invite> [channel]

   Returns: 1 if the specified invite is in the global invite list AND is
     marked as permanent; 0 otherwise. If a channel is specified, that
     channel's invite list is checked as well.
   Module: channels


isbansticky <ban> [channel]

   Returns: 1 if the specified ban is marked as sticky in the global ban
     list; 0 otherwise. If a channel is specified, that channel's ban list
     is checked as well.
   Module: channels


isexemptsticky <exempt> [channel]

   Returns: 1 if the specified exempt is marked as sticky in the global
     exempt list; 0 otherwise. If a channel is specified, that channel's
     exempt list is checked as well.
   Module: channels


isinvitesticky <invite> [channel]

   Returns: 1 if the specified invite is marked as sticky in the global
     invite list; 0 otherwise. If a channel is specified, that channel's
     invite list is checked as well.
   Module: channels


matchban <nick!user@host> [channel]

   Returns: 1 if the specified nick!user@host matches a ban in the global
     ban list; 0 otherwise. If a channel is specified, that channel's ban
     list is checked as well.
   Module: channels


matchexempt <nick!user@host> [channel]

   Returns: 1 if the specified nick!user@host matches an exempt in the
     global exempt list; 0 otherwise. If a channel is specified, that
     channel's exempt list is checked as well.
   Module: channels


matchinvite <nick!user@host> [channel]

   Returns: 1 if the specified nick!user@host matches an invite in the
     global invite list; 0 otherwise. If a channel is specified, that
     channel's invite list is checked as well.
   Module: channels


banlist [channel]

   Returns: a list of global bans, or, if a channel is specified, a
     list of channel-specific bans. Each entry is a sublist containing:
     hostmask, comment, expiration timestamp, time added, last time
     active, and creator. The three timestamps are in unixtime format.
   Module: channels


exemptlist [channel]

   Returns: a list of global exempts, or, if a channel is specified, a
     list of channel-specific exempts. Each entry is a sublist containing:
     hostmask, comment, expiration timestamp, time added, last time
     active, and creator. The three timestamps are in unixtime format.
   Module: channels


invitelist [channel]

   Returns: a list of global invites, or, if a channel is specified, a
     list of channel-specific invites. Each entry is a sublist containing:
     hostmask, comment, expiration timestamp, time added, last time
     active, and creator. The three timestamps are in unixtime format.
   Module: channels


newignore <hostmask> <creator> <comment> [lifetime]

   Description: 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
   Module: core


killignore <hostmask>

   Description: removes an entry from the ignore list
   Returns: 1 if successful; 0 otherwise
   Module: core


ignorelist

   Returns: a list of ignores. Each entry is a sublist containing:
     hostmask, comment, expiration timestamp, time added, and creator.
     The timestamps are in unixtime format.
   Module: core


isignore <hostmask>

   Returns: 1 if the ignore is in the list; 0 otherwise
   Module: core


save

   Description: writes the user and channel files to disk
   Returns: nothing
   Module: core


reload

   Description: loads the userfile from disk, replacing whatever is in
     memory
   Returns: nothing
   Module: core


backup

   Description: makes a simple backup of the userfile that's on disk.
     If the channels module is loaded, this also makes a simple backup
     of the channel file.
   Returns: nothing
   Module: core


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
   Module: core

CHANNEL COMMANDS

channel add <name> [option-list]

   Description: adds a channel record for the bot to monitor. The full
     list of possible options are given in doc/settings/mod.channels. Note
     that the channel options must be in a list (enclosed in {}).
   Returns: nothing
   Module: channels


channel set <name> <options...>

   Description: sets options for the channel specified. The full list of
     possible options are given in doc/settings/mod.channels.
   Returns: nothing
   Module: channels


channel info <name>

   Returns: a list of info about the specified channel's settings.
   Module: channels


channel get <name> <setting>

   Returns: The value of the setting you specify. For flags, a value of 0
     means it is disabled (-), and non-zero means enabled (+).
   Module: channels


channel remove <name>

   Description: removes a channel record from the bot and makes the bot no
     longer monitor the channel
   Returns: nothing
   Module: channels


savechannels

   Description: saves the channel settings to the channel-file if one is
     defined.
   Returns: nothing
   Module: channels


loadchannels

   Description: reloads the channel settings from the channel-file if one
     is defined.
   Returns: nothing
   Module: channels


channels

   Returns: a list of the channels the bot has a channel record for
   Module: channels


channame2dname <channel-name>

 chandname2name <channel-dname>
  Description: these two functions are important to correctly support
    !channels. The bot differentiates between channel description names
    (chan dnames) and real channel names (chan names). The chan dnames
    are what you would normally call the channel, such as "!channel". The
    chan names are what the IRC server uses to identify the channel. They
    consist of the chan dname prefixed with an ID; such as "!ABCDEchannel".
    
    For bot functions like isop, isvoice, etc. you need to know the chan
    dnames. If you communicate with the server, you usually get the chan
    name, though. That's what you need the channame2dname function for.
    
    If you only have the chan dname and want to directly send raw server
    commands, use the chandname2name command.
    
    NOTE: For non-!channels, chan dname and chan name are the same.
  Module: irc


isbotnick <nick>

   Returns: 1 if the nick matches the botnick; 0 otherwise
   Module: server


botisop [channel]

   Returns: 1 if the bot has ops on the specified channel (or any channel
     if no channel is specified); 0 otherwise
   Module: irc


botishalfop [channel]

   Returns: 1 if the bot has halfops on the specified channel (or any channel
     if no channel is specified); 0 otherwise
   Module: irc


botisvoice [channel]

   Returns: 1 if the bot has a voice on the specified channel (or any
     channel if no channel is specified); 0 otherwise
   Module: irc


botonchan [channel]

  Returns: 1 if the bot is on the specified channel (or any channel if
    no channel is specified); 0 otherwise
  Module: irc


isop <nickname> [channel]

   Returns: 1 if someone by the specified nickname is on the channel (or
     any channel if no channel name is specified) and has ops; 0 otherwise
   Module: irc


ishalfop <nickname> [channel]

   Returns: 1 if someone by the specified nickname is on the channel (or
     any channel if no channel name is specified) and has halfops; 0 otherwise
   Module: irc


wasop <nickname> <channel>

   Returns: 1 if someone that just got opped/deopped in the chan had op
     before the modechange; 0 otherwise
   Module: irc


washalfop <nickname> <channel>

   Returns: 1 if someone that just got halfopped/dehalfopped in the chan
     had halfop before the modechange; 0 otherwise
   Module: irc


isvoice <nickname> [channel]

   Returns: 1 if someone by that nickname is on the channel (or any
     channel if no channel is specified) and has voice (+v); 0 otherwise
   Module: irc


onchan <nickname> [channel]

   Returns: 1 if someone by that nickname is on the specified channel (or
     any channel if none is specified); 0 otherwise
   Module: irc


nick2hand <nickname> [channel]

   Returns: the handle of a nickname on a channel. If a channel is not
     specified, the bot will check all of its channels. If the nick is
     not found, "" is returned. If the nick is found but does not have
     a handle, "*" is returned.
   Module: irc


hand2nick <handle> [channel]

   Returns: nickname of the first person on the specified channel (if one
     is specified) whose nick!user@host matches the given handle; "" is
     returned if no match is found. If no channel is specified, all channels
     are checked.
   Module: irc


handonchan <handle> [channel]

   Returns: 1 if the the nick!user@host for someone on the channel (or any
     channel if no channel name is specified) matches for the handle given;
     0 otherwise
   Module: irc


ischanban <ban> <channel>

   Returns: 1 if the specified ban is on the given channel's ban list
     (not the bot's banlist for the channel)
   Module: irc


ischanexempt <exempt> <channel>

   Returns: 1 if the specified exempt is on the given channel's exempt
     list (not the bot's exemptlist for the channel)
   Module: irc


ischaninvite <invite> <channel>

   Returns: 1 if the specified invite is on the given channel's invite
     list (not the bot's invitelist for the channel)
   Module: irc


chanbans <channel>

   Returns: a list of the current bans on the channel. Each element is
     a sublist of the form {<ban> <bywho> <age>}. age is seconds from the
     bot's point of view
   Module: irc


chanexempts <channel>

   Returns: a list of the current exempts on the channel. Each element is
     a sublist of the form {<exempts> <bywho> <age>}. age is seconds from the
     bot's point of view
   Module: irc


chaninvites <channel>

   Returns: a list of the current invites on the channel. Each element is
     a sublist of the form {<invites> <bywho> <age>}. age is seconds from the
     bot's point of view
   Module: irc


resetbans <channel>

   Description: 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
   Module: irc


resetexempts <channel>

   Description: removes all exempt on the channel that aren't in the bot's
     exempt list and refreshes any exempts that should be on the channel
     but aren't
   Returns: nothing
   Module: irc


resetinvites <channel>

   Description: removes all invites on the channel that aren't in the bot's
     invite list and refreshes any invites that should be on the channel
     but aren't
   Returns: nothing
   Module: irc


resetchan <channel>

   Description: rereads in the channel info from the server
   Returns: nothing
   Module: irc


getchanhost <nickname> [channel]

   Returns: user@host of the specified nickname (the nickname is not included
     in the returned host). If a channel is not specified, bot will check
     all of its channels. If the nickname is not on the channel(s), "" is
     returned.
   Module: irc


getchanjoin <nickname> <channel>

   Returns: timestamp (unixtime format) of when the specified nickname
     joined the channel
   Module: irc


onchansplit <nick> [channel]

   Returns: 1 if that nick is split from the channel (or any channel if no
     channel is specified); 0 otherwise
   Module: irc


chanlist <channel> [flags[&chanflags]]

   Description: flags are any global flags; the '&' denotes to look for
     channel specific flags. Examples:
       n         (Global Owner)
       &n        (Channel Owner)
       o&m       (Global Op, Channel Master)
     Now you can use even more complex matching of flags, including +&- flags
     and & or | (and or or) matching.
   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. Please note that if you're executing chanlist after a
     part or sign bind, the gone user will still be listed, so you can
     check for wasop, isop, etc.
   Module: irc


getchanidle <nickname> <channel>

   Returns: number of minutes that person has been idle; 0 if the
     specified user isn't on the channel
   Module: irc


getchanmode <channel>

   Returns: string of the type "+ntik key" for the channel specified
   Module: irc


jump [server [port [password]]]

   Description: jumps to the server specified, or (if none is specified)
     the next server in the bot's serverlist
   Returns: nothing
   Module: server


pushmode <channel> <mode> [arg]

   Description: sends out a channel mode change (ex: pushmode #lame +o
     goober) through the bot's queuing 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.
   Returns: nothing
   Module: irc


flushmode <channel>

   Description: forces all previously pushed channel mode changes to be
     sent to the server, instead of when the script is finished (just for
     the channel specified)
   Returns: nothing
   Module: irc


topic <channel>

   Returns: string containing the current topic of the specified channel
   Module: irc


validchan <channel>

   Description: checks if the bot has a channel record for the specified
     channel. Note that this does not necessarily mean that the bot is ON
     the channel.
   Returns: 1 if the channel exists, 0 if not
   Module: channels


isdynamic <channel>

   Returns: 1 if the channel is a dynamic channel; 0 otherwise
   Module: channels


setudef <flag/int/str> <name>

   Description: initializes a user defined channel flag, string or integer
     setting. You can use it like any other flag/setting. IMPORTANT: Don't
     forget to reinitialize your flags/settings after a restart, or it'll be
     lost.
   Returns: nothing
   Module: channels


renudef <flag/int/str> <oldname> <newname>

   Description: renames a user defined channel flag, string, or integer
     setting.
   Returns: nothing
   Module: channels


deludef <flag/int/str> <name>

   Description: deletes a user defined channel flag, string, or integer
     setting.
   Returns: nothing
   Module: channels

DCC COMMANDS

putdcc <idx> <text>

   Description: sends text to the idx specified
   Returns: nothing
   Module: core


dccbroadcast <message>

   Description: sends a message to everyone on the party line across the
     botnet, in the form of "*** <message>" for local users and
     "*** (Bot) <message>" for users on other bots
   Returns: nothing
   Module: core


dccputchan <channel> <message>

   Description: sends your message to everyone on a certain channel on the
     botnet, in a form exactly like dccbroadcast does. Valid channels are 0
     through 99999.
   Returns: nothing
   Module: core


boot <user@bot> [reason]

    Description: boots a user from the partyline
    Returns: nothing
    Module: core


dccsimul <idx> <text>

   Description: 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
   Module: core


hand2idx <handle>

   Returns: the idx (a number greater than or equal to zero) for the user
     given if the user 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 is returned if no idx is found. If the user is on
     multiple times, the oldest idx is returned.
   Module: core


idx2hand <idx>

   Returns: handle of the user with the given idx
   Module: core


valididx <idx>

   Returns: 1 if the idx currently exists; 0 otherwise
   Module: core


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
   Module: core


setchan <idx> <channel>

   Description: sets a party line user's channel. 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
   Module: core


console <idx> [channel] [console-modes]

   Description: 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 a valid channel).
   Returns: a list containing the user's (new) channel view and (new)
     console modes, or nothing if that user isn't currently on the partyline
   Module: core


echo <idx> [status]

   Description: 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)
   Module: core


strip <idx> [+/-strip-flags]

   Description: modifies the strip-flags for a user. The supported
     strip-flags are:
       b - remove all boldface codes
       c - remove all color codes
       r - remove all reverse video codes
       u - remove all underline codes
       a - remove all ANSI codes
       g - remove all ctrl-g (bell) codes
   Returns: new strip-flags for the specified user (or the current
     flags, if strip-flags was omitted)
   Module: core


putbot <bot-nick> <message>

   Description: sends a message across the botnet to another bot. If no
     script intercepts the message on the other end, the message is
     ignored.
   Returns: nothing
   Module: core


putallbots <message>

   Description: sends a message across the botnet to all bots. If no
     script intercepts the message on the other end, the message is
     ignored.
   Returns: nothing
   Module: core


killdcc <idx>

   Description: kills a partyline or file area connection
   Returns: nothing
   Module: core


bots

   Returns: list of the bots currently connected to the botnet
   Module: core


botlist

   Returns: a list of bots currently on the botnet. Each item in the list
     is a sublist with four elements: bot, uplink, version, sharing status:
       bot:     the bot's botnetnick
       uplink:  the bot the bot is connected to
       version: its current numeric version
       sharing: a "+" if the bot is a sharebot; "-" otherwise
   Module: core


islinked <bot>

   Returns: 1 if the bot is currently linked; 0 otherwise
   Module: core


dccused

   Returns: number of dcc connections currently in use
   Module: core


dcclist [type]

   Returns: a list of active connections, each item in the list is a
     sublist containing six elements:
       {<idx> <handle> <hostname> <type> {<other>} <timestamp>}.


The types are: chat, bot, files, file_receiving, file_sending,

     file_send_pending, script, socket (these are connections that have
     not yet been put under 'control'), telnet, and server. The timestamp
     is in unixtime format.
   Module: core


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 is 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 * for channel, every user on the botnet is returned
     with an extra argument indicating the channel the user is on.
   Module: core


getdccidle <idx>

   Returns: number of seconds the dcc chat/file system/script user has
     been idle
   Module: core


getdccaway <idx>

   Returns: away message for a dcc chat user (or "" if the user is not
     set away)
   Module: core


setdccaway <idx> <message>

   Description: sets a party line user's away message and marks them away.
    If set to "", the user is marked as no longer away.
   Returns: nothing
   Module: core


connect <host> <port>

   Description: 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
   Module: core


listen <port> <type> [options] [flag]

   Description: opens a listening port to accept incoming telnets; type
     must be one of "bots", "all", "users", "script", or "off":


listen <port> bots [mask]

         Description: 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 number


listen <port> users [mask]

         Description: 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 number


listen <port> all [mask]

         Description: 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 number


listen <port> script <proc> [flag]

         Description: accepts connections which are immediately routed to
           a proc. The proc is called with one parameter: the idx of the
           new connection. Flag may currently only be 'pub', which makes
           the bot allow anyone to connect.
         Returns: port number


listen <port> off

         Description: stop listening on a port
         Returns: nothing
   Module: core


dccdumpfile <idx> <filename>

   Description: dumps out a file from the text directory to a dcc chat
     user. The flag matching that's used everywhere else works here, too.
   Returns: nothing
   Module: core

NOTES MODULE

notes <user> [numberlist]

   Returns: -1 if no such user, -2 if notefile failure. If a numberlist
     is not specified, the number of notes stored for the user is returned.
     Otherwise, a list of sublists containing information about notes
     stored for the user is returned. Each sublist is in the format of:
       {<from> <timestamp> <note text>}.
   Module: notes


erasenotes <user> <numberlist>

   Description: erases some or all stored notes for a user. Use '-'
     to erase all notes.
   Returns: -1 if no such user, -2 if notefile failure, 0 if
     no such note, or number of erased notes.
   Module: notes


listnotes <user> <numberlist>

   Description: lists existing notes according to the numberlist (ex:
     "2-4;8;16-")
   Returns: -1 if no such user, -2 if notefile failure, 0 if no
     such note, list of existing notes.
   Module: notes


storenote <from> <to> <msg> <idx>

   Description: stores a note for later reading, notifies idx of any results
     (use idx -1 for no notify).
   Returns: 0 on success; non-0 on failure
   Module: notes

ASSOC MODULE

assoc <chan> [name]

   Description: sets the name associated with a botnet channel, if you
     specify one
   Returns: current name for that channel, if any
   Module: assoc


killassoc <chan>

   Description: removes the name associated with a botnet channel, if any
     exists. Use 'killassoc &' to kill all assocs.
   Returns: nothing
   Module: assoc

COMPRESS MODULE

compressfile [-level <level>] <src-file> [target-file]

 uncompressfile <src-file> [target-file]
   Description: compresses or un-compresses files. The level option specifies
     the compression mode to use when compressing. Available modes are from
     0 (minimum CPU usage, minimum compression) all the way up to 9 (maximum
     CPU usage, maximum compression). If you don't specify the target-file,
     the src-file will be overwritten.
   Returns: nothing
   Module: compress


iscompressed <filename>

   Description: determines whether <filename> is gzip compressed. Returns 1
     if it is, 0 if it isn't, and 2 if some kind of error prevented the
     checks from succeeding.
   Returns: nothing
   Module: compress

FILESYS MODULE

setpwd <idx> <dir>

   Description: changes the directory of a file system user, in exactly
     the same way as a 'cd' command would. The directory can be specified
     relative or absolute.
   Returns: nothing
   Module: filesys


getpwd <idx>

   Returns: the current directory of a file system user
   Module: filesys


getfiles <dir>

   Returns: a list of files in the directory given; the directory is
     relative to dcc-path
   Module: filesys


getdirs <dir>

   Returns: a list of subdirectories in the directory given; the directory
     is relative to dcc-path
   Module: filesys


dccsend <filename> <ircnick>

   Description: 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 success
     1 the dcc table is full (too many connections)
     2 can't open a socket for the transfer
     3 the file doesn't exist
     4 the file was queued for later transfer, which means that person has
       too many file transfers going right now
     5 copy-to-tmp is enabled and the file already exists in the temp
       directory
   Module: transfer


filesend <idx> <filename> [ircnick]

   Description: 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)
   Module: filesys


fileresend <idx> <filename> [ircnick]

   Description: functions like filesend, only that it sends a DCC RESEND
     instead of a DCC SEND, which allows people to resume aborted file
     transfers if their client supports that protocol. ircII/BitchX/etc.
     support it; mIRC does not.
   Returns: 0 on failure; 1 on success (either an immediate send or a queued
     send)
   Module: filesys


setdesc <dir> <file> <desc>

   Description: sets the description for a file in a file system directory;
     the directory is relative to dcc-path
   Returns: nothing
   Module: filesys


getdesc <dir> <file>

   Returns: the description for a file in the file system, if one
     exists
   Module: filesys


setowner <dir> <file> <handle>

   Description: changes the owner for a file in the file system; the
     directory is relative to dcc-path
   Returns: nothing
   Module: filesys


getowner <dir> <file>

   Returns: the owner of a file in the file system
   Module: filesys


setlink <dir> <file> <link>

   Description: creates or changes a linked file (a file that actually
     exists on another bot); the directory is relative to dcc-path
   Returns: nothing
   Module: filesys


getlink <dir> <file>

   Returns: the link for a linked file, if it exists
   Module: filesys


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
   Module: transfer


getfilesendtime <idx>

   Returns: the unixtime value from when a file transfer started, or a
     negative number:
       -1 no matching transfer with the specified idx was found
       -2 the idx matches an entry which is not a file transfer
   Module: transfer


mkdir <directory> [<required-flags> [channel]]

   Description: creates a directory in the file system. Only users with the
     required flags may access it.
   Returns:
     0 success
     1 can't create directory
     2 directory exists but is not a directory
    -3 could not open filedb
   Module: filesys


rmdir <directory>

   Description: removes a directory from the file system.
   Returns: 0 on success; 1 on failure
   Module: filesys


mv <file> <destination>

   Description: moves a file from its source to the given destination.
     The file can also be a mask, such as /incoming/*, provided the
     destination is a directory.
   Returns: If the command was successful, the number of files moved will
     be returned. Otherwise, a negative number will be returned:
       -1 invalid source file
       -2 invalid destination
       -3 destination file exists
       -4 no matches found
   Module: filesys


cp <file> <destination>

   Description: copies a file from its source to the given destination.
     The file can also be a mask, such as /incoming/*, provided the
     destination is a directory.
   Returns: If the command was successful, the number of files copied will
     be returned. Otherwise, a negative number will be returned:
       -1 invalid source file
       -2 invalid destination
       -3 destination file exists
       -4 no matches found
   Module: filesys


getflags <dir>

   Returns: the flags required to access a directory
   Module: filesys


setflags <dir> [<flags> [channel]]

   Description: sets the flags required to access a directory
   Returns: 0 on success; -1 or -3 on failure
   Module: filesys


MISCELLANEOUS COMMANDS

bind <type> <flags> <keyword/mask> [proc-name]

   Description: You can use the 'bind' command to attach Tcl procedures
     to certain events. flags are the flags the user must have to trigger
     the event (if applicable). 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
   Module: core


unbind <type> <flags> <keyword/mask> <proc-name>

   Description: removes a previously created bind
   Returns: name of the command that was removed
   Module: core


binds [type/mask]

   Returns: a list of Tcl binds, each item in the list is a sublist of
     five elements:
       {<type> <flags> <name> <hits> <proc>}
   Module: core


logfile [<modes> <channel> <filename>]

   Description: creates a new logfile, which will log the modes given for
     the channel listed. If no logfile is specified, a list of existing
     logfiles will be returned. "*" indicates 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.


Logfile flags:

       b - information about bot linking and userfile sharing
       c - commands
       d - misc debug information
       h - raw share traffic
       j - joins, parts, quits, and netsplits on the channel
       k - kicks, bans, and mode changes on the channel
       m - private msgs, notices and ctcps to the bot
       o - misc info, errors, etc (IMPORTANT STUFF)
       p - public text on the channel
       r - raw incoming server traffic
       s - server connects, disconnects, and notices
       t - raw botnet traffic
       v - raw outgoing server traffic
       w - wallops (make sure the bot sets +w in init-server)
       x - file transfers and file-area commands
   Returns: filename of logfile created, or, if no logfile is specified, a
     list of logfiles such as: {mco * eggdrop.log} {jp #lame lame.log}
   Module: core


maskhost <nick!user@host>

   Returns: masked 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")
   Module: core


timer <minutes> <tcl-command>

   Description: executes the given Tcl command after a certain number of
     minutes have passed
   Returns: a timerID
   Module: core


utimer <seconds> <tcl-command>

   Description: executes the given Tcl command after a certain number of
     seconds have passed
   Returns: a timerID
   Module: core


timers

   Returns: a 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.
   Module: core


utimers

   Returns: a list of active secondly timers. Each entry in the list contains
     the number of minutes left till activation, the command that will be
     executed, and the timerID.
   Module: core


killtimer <timerID>

   Description: removes a minutely timer from the list
   Returns: nothing
   Module: core


killutimer <timerID>

   Description: removes a secondly timer from the list
   Returns: nothing
   Module: core


unixtime

   Returns: a long integer which represents the number of seconds that have
     passed since 00:00 Jan 1, 1970 (GMT).
   Module: core


duration <seconds>

   Returns: the number of seconds converted into years, weeks, days, hours,
     minutes, and seconds. 804600 seconds is turned into 1 week 2 days
     7 hours 30 minutes.
   Module: core


strftime <formatstring> [time]

   Returns: a formatted string of time using standard strftime format.
     If time is specified, the value of the specified time is used.
     Otherwise, the current time is used.
   Module: core


ctime <unixtime>

   Returns: a formatted date/time string based on the current locale
     settings from the unixtime string given; for example "Fri Aug 3
     11:34:55 1973"
   Module: core


myip

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


rand <limit>

   Returns: a random integer between 0 and limit-1
   Module: core


control <idx> <command>

   Description: removes an idx from the party line and sends all future
     input to the Tcl command given. The command will be called with two
     parameters: the idx 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. If the input text is blank (""), it
     indicates that the connection has been dropped. Also, if the input
     text is blank, never call killdcc on it, as it will fail with "invalid
     idx".
   Returns: nothing
   Module: core


sendnote <from> <to[@bot]> <message>

   Description: simulates what happens when one user sends a note to another
   Returns:
     0 - the send failed
     1 - the note was delivered locally or sent to another bot
     2 - the note was stored locally
     3 - the user's notebox is too full to store a note
     4 - a Tcl binding caught the note
     5 - the note was stored because the user is away
   Module: core


link [via-bot] <bot>

   Description: attempts to link to another bot directly. If you specify
     a via-bot, it tells the via-bot to attempt the link.
   Returns: 1 if the link will be attempted; 0 otherwise
   Module: core


unlink <bot>

   Description: attempts to unlink a bot from the botnet
   Returns: 1 on success; 0 otherwise
   Module: core


encrypt <key> <string>

   Returns: encrypted string (using the currently loaded encryption module),
     encoded into ASCII using base-64
   Module: encryption


decrypt <key> <encrypted-base64-string>

   Returns: decrypted string (using the currently loaded encryption module)
   Module: encryption


encpass <password>

   Returns: encrypted string (using the currently loaded encryption module)
   Module: encryption


die [reason]

   Description: causes the bot to log a fatal error and exit completely.
     If no reason is given, "EXIT" is used.
   Returns: none
   Module: core


unames

  Returns: the current operating system the bot is using
  Module: core


dnslookup <ip-address/hostname> <proc> [[arg1] [arg2] ... [argN]]

   Description: This issues an asynchronous dns lookup request. The
     command will block if dns module is not loaded; otherwise it will
     either return immediately or immediately call the specified proc
     (e.g. if the lookup is already cached).


As soon as the request completes, the specified proc will be called

     as follows:


<proc> <ipaddress> <hostname> <status> [[arg1] [arg2] ... [argN]]


status is 1 if the lookup was successful and 0 if it wasn't. All

     additional parameters (called arg1, arg2 and argN above) get
     appended to the proc's other parameters.
   Returns: nothing
   Module: core


md5 <string>

   Returns: the 128 bit MD5 message-digest of the specified string
   Module: core


callevent <event>

   Description: triggers the evnt bind manually for a certain event.
     For example: callevent rehash.
   Returns: nothing
   Module: core


traffic

   Returns: a list of sublists containing information about the bot's
     traffic usage in bytes. Each sublist contains five elements: type,
     in-traffic today, in-traffic total, out-traffic today, out-traffic
     total (in that order).
   Module: core


modules

   Returns: a list of sublists containing information about the bot's
     currently loaded modules. Each sublist contains three elements: module,
     version, and dependencies. Each dependency is also a sublist containing
     the module name and version.
   Module: core


loadmodule <module>

   Description: attempts to load the specified module.
   Returns: "Already loaded." if the module is already loaded, "" if
     successful, or the reason the module couldn't be loaded.
   Module: core


unloadmodule <module>

   Description: attempts to unload the specified module.
   Returns: "No such module" if the module is not loaded, "" otherwise.
   Module: core


loadhelp <helpfile-name>

   Description: attempts to load the specified help file from the help/
     directory.
   Returns: nothing
   Module: core


unloadhelp <helpfile-name>

   Description: attempts to unload the specified help file.
   Returns: nothing
   Module: core


reloadhelp

   Description: reloads the bot's help files.
   Returns: nothing
   Module: core


restart

   Description: rehashes the bot, kills all timers, reloads all modules,
     and reconnects the bot to the next server in its list.
   Returns: nothing
   Module: core


rehash

   Description: rehashes the bot
   Returns: nothing
   Module: core


stripcodes <strip-flags> <string>

   Description: strips specified control characters from the string given.
     strip-flags can be any combination of the following:
       b - remove all boldface codes
       c - remove all color codes
       r - remove all reverse video codes
       u - remove all underline codes
       a - remove all ANSI codes
       g - remove all ctrl-g (bell) codes
   Returns: the stripped string.
   Module: core


GLOBAL VARIABLES

NOTE: All config file variables are also global.


botnick

   Value: the current nickname the bot is using (for example: "Valis",
     "Valis0", etc.)
   Module: server


botname

   Value: the current nick!user@host that the server sees (for example:
     "Valis!valis@crappy.com")
   Module: server


server

  Value: the current server's real name (what server calls itself)
    and port bot is connected to (for example: "irc.math.ufl.edu:6667")
    Note that this does not nececerilly match the servers internet address.
  Module: server


serveraddress

  Value: the current server's internet address (hostname or IP) and port bot
    is connected to. This will correspond to the entry in server list (for
    example: "eu.undernet.org:6667"). Note that this does not necessarily
    match the name server calls itself.
  Module: server


version

   Value: current bot version "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
   Module: core


numversion

   Value: the current numeric bot version (for example: "1010201").
     Numerical version is in the format of "MNNRRPP", where:
       M   major release number
       NN  minor release number
       RR  sub-release number
       PP  patch level for that sub-release
   Module: core


uptime

   Value: the unixtime value for when the bot was started
   Module: core


server-online

    Value: the unixtime value for when the bot connected to its current
      server
    Module: server


lastbind

   Value: the last command binding which was triggered. This allows you to
     identify which command triggered a Tcl proc.
   Module: core


isjuped

   Value: 1 if bot's nick is juped(437); 0 otherwise
   Module: server


handlen

   Value: the value of the HANDLEN define in src/eggdrop.h
   Module: core


config

   Value: the filename of the config file Eggdrop is currently using
   Module: core

CONTROL PROCEDURES

Using the 'control' command, you can put a DCC connection (or outgoing TCP connection) in control of a script. All text received from 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. Don't call killdcc on the idx when text is blank, it will always fail with "invalid idx".


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

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 on.


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> <port>]


$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' will return an error is if you give it a hostname that can't be resolved (this is considered a "DNS error"). Otherwise, it will appear to have succeeded. 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. The 'killdcc' command will fail with "invalid idx" if you attempt to use it on a closed socket.


To create a listen port, use:

listen <port> script <proc>


Procs should be declared as:

<procname> <newidx>


For example:

listen 6687 script listen:grab


proc listen:grab {newidx} {

  control $newidx listen:control
}


When a new connection arrives in port 6687, Eggdrop will create a new idx for the connection. That idx is sent to 'listen:grab'. The proc immediately puts this idx under control. Once 'listen:grab' 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. However, hopefully this has given you a good start.

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)