Tcl Commands for Eggdrop Bots v1.3

TCL Commands for Eggdrops v1.3

Core Eggdrop Commands
Output Commands
dumpfile	putcmdlog	puthelp	putlog	putloglev	putserv	putxferlog
User Record Manipulation Commands
addbot	addchanrec	adduser	backup	botattr	chattr	chnick	countusers
delchanrec	delhost	deluser	finduser	getchaninfo	getting-users	getuser	ignorelist
isignore	killignore	matchattr	matchchanattr	newignore	passwdok	reload	save
setchaninfo	setuser	userlist	validuser
User Record Ban Commands
banlist	isban	ispermban	killchanban	killban	matchban	newban	newchanban
Channel Commands
botisop	chanbans	chanlist	channel add	channel info	channel remove	channel set	channels
flushmode	getchanhost	getchanidle	getchanjoin	getchanmode	hand2nick	handonchan	ischanban
isdynamic	isop	isvoice	jump	loadchannels	nick2hand	onchan	onchansplit
pushmode	resetbans	resetchan	savechannels	topic	validchan	©1999 Thicks _-_ 09/99
DCC Commands
boot	bots	connect	console	dccbroadcast	dccdumpfile	dcclist	dccputchan
dccsimul	dccused	echo	getchan	getdccaway	getdccidle	hand2idx	idx2hand
killdcc	listen	putallbots	putbot	putdcc	rehash	restart	setdccaway
setchan	valididx	whom
Miscellaneous Commands
bind	control	ctime	date	decrypt	die	encrpyt	killtimer
killutimer	link	logfile	maskhost	myip	rand	sendnote	strftime
time	timer	timers	unlink	unames	unbind	unixtime	utimer
utimers
Global Variables
All config-file variables are global, too. But these variables are set by the bot.
botnick	botname	lastbind	numbersion	server	uptime	version

Notes Module Controls
notes	erasenotes	listnotes	storenote

Assoc Module Controls
assoc	killassoc

File System Module Controls
setpwd	getpwd	getfiles	getdirs	dccsend	filesend	setdesc	getdesc
setowner	getowner	setlink	getlink	getfileq	setuploads	getuploads	setdnloads
getdnloads	mkdir	rmdir	mv	cp	getflags	setflags

Control
Procedures

TCP
Connections

Match
Characters

Command Extensions
act	away	bcst	bot	chat	chjn	chof	chon	chpt	ctcp	ctcr
dcc	disc	fil	filt	flud	join	kick	link	load	mode	msg
msgm	nick	nkch	notc	note	part	pub	pubm	raw	rcvd	rejn
sent	sign	splt	time	topc	unld	wall
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. 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. To remove a binding, use unbind. For example, to remove that binding for the msg-command "stop", use *unbind msg - stop msg_stop*

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 ONLY the v1.3 series of eggdrop!

bind act <flags> <mask> <proc> proc-name <nick> <channel#> <action>

Stackable

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

See Also: bind, unbind, or Command Extensions
Return to Index

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.

addchanrec <handle> <channel>

Add a channel record for the user.
Returns: "1" on success, "0" if the user does not exist or if there isn't such a channel.

adduser <handle> <hostmask>

Creates a new user entry with the handle and hostmask given (with no password, and the default flags)
Returns: "1" if successful, "0" if it already existed

assoc <chan> [name]

Sets the name associated with a botnet channel, if you specify one.
Returns: Current name for that channel, if any.

See Also: Assoc Module
Return to Index

bind away - <mask> <proc> proc-name <bot> <idx> <msg>

Stackable

Triggers when a user goes away or comes back on the botnet (msg == "" when returning)

See Also: bind, unbind, or Command Extensions
Return to Index

backup

Makes a simple backup of the userfile that's on disk.
Returns: Nothing

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)

bind bcst <flags> <mask> <proc> proc-name <bot> <channel#> <text>

Stackable

When a bot says something on the botnet, it invokes this binding. Flags is ignored. The mask is checked against the text.

See Also: bind, unbind, or Command Extensions
Return to Index

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

Yes, you can use the new flag binding method here too, and this is where it becomes truely phearfull since you may never need to check attr's inside functions again...imagine: bind pub -o&+o command command_proc to only allow channel-spec ops to use it! No problem! Works fine!
Returns: Name of the command that was added, or (if proc-name was omitted), a list of the current bindings for this command.

boot <user@bot> [reason]

Boot's a user from the partyline.
Returns: Nothing.

See Also: DCC Commands
Return to Index

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.

See Also: bind, unbind, or Command Extensions
Return to Index

botattr <handle> [changes [channel]]

Similar to chattr except for bot attributes rather than normal user attributes, this includes the channel-specific +s share flag.

botisop <channel>

Returns: "1" if the bot is an op on that channel; "0" otherwise.

botname

Returns: Current nick!user@host that the servers sees. ie: Valis!valis@crappy.com

botnick

Returns: Current nickname the bot is using, ie 'Valis' or 'Valis0', etc.

bots

Returns: List of the bots currently connected to the botnet.

See Also: DCC Commands
Return to Index

chanbans <channel>

Returns: a list of the current bans on the channel, each element is of the form ban bywho age. Age is seconds from the bots POV

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

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.

bind chat <flags> <mask> <proc> proc-name <nick> <channel#> <text>

Stackable

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.

See Also: bind, unbind, or Command Extensions
Return to Index

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 you can now use the +o|-o #channel format here too.
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.

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)

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.

channels

Returns: List of the channels the bot is monitoring (or trying to).

bind chjn <flags> <mask> <proc> proc-name <bot> <nick> <channel#> <flag><sock> <from>

Stackable

When someone joins a botnet channel, it invokes this binding. Flags is ignored. The mask is checked against the text.

See Also: bind, unbind, or Command Extensions
Return to Index

chnick <old-handle> <new-handle>

Changes a user's handle
Returns: "1" on success; "0" if the handle is already used, or is invalid, or the user can't be found.

bind chof <flags> <mask> <proc> proc-name <handle> <idx>

Stackable

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.

See Also: bind, unbind, or Command Extensions
Return to Index

bind chon <flags> <mask> <proc> proc-name <handle> <idx>

Stackable

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.

See Also: bind, unbind, or Command Extensions
Return to Index

bind chpt <flags> <mask> <proc> proc-name <bot> <nick> <sock> <chan>

Stackable

When someone parts a botnet channel, it invokes this binding. Flags is ignored. The mask is checked against the channel.

See Also: bind, unbind, or Command Extensions
Return to Index

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.

See Also: DCC Commands
Return to Index

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.

Return to Index

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.

See Also: DCC Commands
Return to Index

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.

countusers

Returns: Number of users in the bot's database.

cp <file> <destination>

Exactly the same as mv except it leaves the original file there aswell.
Returns: Same as mv.

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.

Return Value: 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).

See Also: bind, unbind, or Command Extensions
Return to Index

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

See Also: bind, unbind, or Command Extensions
Return to Index

ctime <unixtime>

Returns: A string of the date/time represented by the unix time given (ie "Fri Aug 3 11:34:55 1973").

date

Returns: The current date in standard format (ie "21 Dec 1994").

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

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

See Also: bind, unbind, or Command Extensions
Return to Index

dccbroadcast <message>

Sends your message to everyone on the party line on the bot net, in the form "*** " for local users, and "*** [Bot] " for users on other bots.

See Also: DCC Commands
Return to Index

dccdumpfile <idx> <filename>

Dumps out a file from the text directory to a dcc chat user. The flag matching that's used everywhere else works here too.

See Also: DCC Commands
Return to Index

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) or any new dcc type that gets added.

See Also: DCC Commands
Return to Index

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.

See Also: DCC Commands
Return to Index

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 connections), "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)!

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.

See Also: DCC Commands
Return to Index

dccused

Returns: Number of dcc connections currently in use.

See Also: DCC Commands
Return to Index

decrypt <key> <encrypted-base64-string>

Returns: Decrypted string (using blowfish).

delchanrec <handle> <channel>

Removes a channel record for the user. This includes all associated channel flags.
Returns: "1" on success, "0" if the user does not exist or if there isn't such a channel.

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.

deluser <handle>

Attempts to erase a user record with that handle.
Returns: "1" if successful, "0" if no such user exists.

die [reason]

Causes the bot to log a fatal error and exit completely. If no reason is given, "EXIT" is used.

bind disc <flags> <mask> <proc> proc-name <botname>

Stackable

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.

See Also: bind, unbind, or Command Extensions
Return to Index

dumpfile <nick> <filename>

Dumps out a 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 wont work within the file.

See Also: Output Commands
Return to Index

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

See Also: DCC Commands
Return to Index

encrypt <key> <string>

Returns: Encrypted string (using blowfish), encoded into ascii using base-64 so it can be sent over the botnet.

erasenotes <user> <numberlist>

Erases some or all stored notes for a user.
Returns: -1 if no such user, -2 if notefile failure, 0 if no such note, or number of erased notes. erasenote mynick "-" will erase all notes for mynick.

See Also: Notes Module
Return to Index

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

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.
Note: This Is ONLY Avaliable When The filesys.so Module Is Loaded!

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

See Also: bind, unbind, or Command Extensions
Return to Index

bind filt <flags> <mask> <proc> procname <idx> <text>

Stackable

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.

Return Value: 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.

See Also: bind, unbind, or Command Extensions
Return to Index

finduser <nick!user@host>

Finds the user record which most closely matches the given user@host.
Returns: The handle found, or "*" if none.

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

bind flud <flags> <type> <proc> procname <nick> <user@host> <handle> <type> <channel>

Stackable

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.

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

See Also: bind, unbind, or Command Extensions
Return to Index

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.

See Also: DCC Commands
Return to Index

getchanhost <nickname> <channel>

Returns: user@host of that person if they are on the channel, "0" otherwise.

getchanidle <nickname> <channel>

Returns: number of minutes that person has been idle. "0" if the specified user isn't even on the channel.

getchaninfo <handle> <channel>

Returns: info line for a specific channel. Behaves just like getinfo.

getchanjoin <nickname> <channel>

Returns: Timestamp of when that person joined the channel.

getchanmode <channel>

Returns: String of the type "+ntik key" for the channel specified.

getdccaway <idx>

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

See Also: DCC Commands
Return to Index

getdccidle <idx>

Returns: Number of seconds the dcc chat/file system/script user has been idle.

See Also: DCC Commands
Return to Index

getdesc <dir> <file>

Returns: The description for a file in the file system, if one exists.

getdirs <dir>

Returns: List of subdirectories in the directory given. The directory is relative to dcc-path.

getdnloads <handle>

Returns: List containing download statistics, in the same format as getuploads.

getflags <dir>

Returns: The flags required to access this directory.

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.

getfiles <dir>

Returns: List of files in the directory given. The directory is relative to dcc-path.

getlink <dir> <file>

Returns: The link for a linked file, if it exists.

getpwd <idx>

Returns: The current directory of a file system user.

getowner <dir> <file>

Returns: The owner of a file in the file system.

gettingusers

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.

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.

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

This is a generic interface to the new generic userfile support. It returns info specific to each entry-type.
Valid entry types are:

    BOTFL    Returns the current bot-specific flags for the user (if it's a bot :)
    BOTADDR  (another bot-only thing :) returns a list containing the bots address,
             the bots telnet port, and it's relay port.
    HOSTS    Returns a list of the host for the user
    LASTON   Returns a list containing the unixtime last seen, and the last seen place.
             OR
             LASTON #channel  Returns the time last seen on the channel or 0 if no info
    INFO     Returns the user's global info line
    XTRA     Returns the old xtra info
    COMMENT  Returns the master-visible only comment for the user
    EMAIL    Returns the users email address
    URL      Returns the users url address

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.

See Also: DCC Commands
Return to Index

hand2nick <handle> <channel>

Returns: nickname of the first person on the channel whose user@host matches that handle, if there is one, "0" otherwise

handonchan <handle> <channel>

Returns: "1" if the the user@host for someone on the channel matches for the handle given, "0" otherwise.

idx2hand <idx>

Returns: Handle of the user with that idx.

See Also: DCC Commands
Return to Index

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

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.

ischanban <ban> <channel>

Returns: "1" if that is a ban on the bot's channel.

isdynamic <channel>

Returns: 1 if the channel is an existing dynamic channel, 0 if not.

isignore <hostmask>

Returns: "1" if the ignore is in the list, "0" otherwise.

isop <nickname> <channel>

Returns: "1" if someone by that nickname is on the channel and has chop. "0" otherwise.

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.

isvoice <nickname> <channel>

Returns: "1" if someone by that nickname is on the channel and has voice (+v), "0" otherwise.

bind join <flags> <mask> <proc> procname <nick> <user@host> <handle> <channel>

Stackable

Triggered by someone joining the channel. The <mask> in the bind is matched against #channel nick!user@host and can contain wildcards.

See Also: bind, unbind, or Command Extensions
Return to Index

jump [server [port [password]]]

Jumps to the server specified, or (if none is specified) the next server in the list.Returns: Nothing

bind kick <flags> <mask> <proc> procname <nick> <user@host> <handle> <channel> <kicked-nick> <reason>

Stackable

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.

See Also: bind, unbind, or Command Extensions
Return to Index

killban <ban>

Removes a ban from the global ban list.
Returns: "1" if successful, "0" otherwise.

killassoc <chan>

Removes the name associated with a botnet channel, if any exists.
Use: killassoc & to kill all assocs.
Returns: Nothing.

See Also: Assoc Module
Return to Index

killchanban <channel> <ban>

Removes a ban from the enforced ban list for a channel.
Returns: "1" if successful, "0" otherwise

killdcc <idx>

Kills a party-line or file area connection, rather abruptly.
Returns: Nothing.

See Also: DCC Commands
Return to Index

killignore <hostmask>

Removes an entry from the ignore list.
Returns: "1" if successful, "0" otherwise.

killtimer <timerID>

Removes a minutely timer from the list.
Returns: Nothing.

killutimer <timerID>

Removes a secondly timer from the list.
Returns: Nothing.

lastbind

The last command binding which triggered. This allows you to identify which command triggered a tcl routine.

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.

bind link <flags> <mask> <proc> proc-name <botname> <via>

Stackable

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.

See Also: bind, unbind, or Command Extensions
Return to Index

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.

See Also: DCC Commands
Return to Index

listnotes <user> <numberlist>

Lists existing notes according to the numberlist. Example: 2-4;8;16-
Returns: -1 if no such user, -2 if notefile failure, 0 if no such note, list of existing notes.

See Also: Notes Module
Return to Index

bind load - <mask> <proc> proc-name <module>

Stackable

Triggers when a module is loaded.

See Also: bind, unbind, or Command Extensions
Return to Index

loadchannels

Reloads the channel settings from the channel-file if one is defined.
Returns: Nothing.

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:&nbps; {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

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.

matchattr <handle> <flags> [channel]

Returns: "1" if the specified user has the matching flags.

matchchanattr <handle> <flags> <channel>

Returns: identical to matchattr command with a channel argument. Heck they're the same command now :) Don't rely on this command in new scripts, it will go eventually :)

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)

Return to Index

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, and 2 on directory exists but is not a directory.

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.

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

See Also: bind, unbind,, or Command Extensions
Return to Index

bind msgm <flags> <mask> <proc> procname <nick> <user@host> <handle> <text>

Stackable

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.

See Also: bind, unbind,, or Command Extensions
Return to Index

bind mode <flags> <mask> <proc> proc-name <nick> <user@host> <handle> <channel> <mode-change> <victim>

Stackable

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" and victim will show the value of the mode change (for o/v/b) otherwise "". 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").

See Also: bind, unbind, or Command Extensions
Return to Index

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 destonation, -3 = you're trying to copy onto itself (duh!) -4 = no matchs found.

myip

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

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

Adds a ban to the global ban list (which takes effect on all channels). Other arguments work exactly like newchanban.
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

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

Adds an entry to the ignore list. The 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

bind nick <flags> <mask> <proc> procname <nick> <user@host> <handle> <channel> <newnick>

Stackable

Triggered when someone changes nicknames. Wildcards are allowed. The mask is matched against #channel newnick.

See Also: bind, unbind, or Command Extensions
Return to Index

nick2hand <nickname> <channel>

Returns: handle of the person on the channel with that nickname, if someone by that nickname is on the channel, "0" otherwise.

bind nkch - <mask> <proc> proc-name <oldnick> <newnick>

Stackable

Triggered whenever a local users nick is changed (in the userfile).

See Also: bind, unbind, or Command Extensions
Return to Index

bind notc <flags> <mask> <proc> procname <nick> <user@host> <handle> <text>

Stackable

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.

See Also: bind, unbind, or Command Extensions
Return to Index

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 wildcards), but it is not case sensitive. Flags is ignored.

See Also: bind, unbind, or Command Extensions
Return to Index

notes <user> [numberlist]

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 numberlist specified) a list of notes, -1 if no such user, -2 if notefile failure, 0 if no such note. Each note of the list is also a list: first element from, 2nd element timestamp, 3rd element the note itself. Example: notes mynick "2-4;8;16-"

See Also: Notes Module
Return to Index

numversion

Current numeric bot version (ie: "1010201").

Numerical version is "MMNNRRPP" where:	MM is the Major release number
	NN is the Minor release number
	RR is the sub-release number
	PP is the patch level for that sub-release

onchan <nickname> <channel>

Returns: "1" if someone by that nickname is on the bot's channel, "0" otherwise.

onchansplit <nick> <channel>

Returns: "1" if that nick is split from the channel, "0" otherwise.

bind part <flags> <mask> <proc> procname <nick> <user@host> <handle> <channel>

Stackable

Triggered by someone leaving the channel. As in JOIN, the <mask> is matched against #channel nick!user@host and can contain wildcards.

See Also: bind, unbind, or Command Extensions
Return to Index

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

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.

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

See Also: bind, unbind, or Command Extensions
Return to Index

bind pubm <flags> <mask> <proc> procname <nick> <user@host> <handle> <channel> <text>

Stackable

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.

See Also: bind, unbind, or Command Extensions
Return to Index

pushmode <channel> <mode> [arug]

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.

putallbots <message>

Broadcasts a message across the bot-net to all currently connected bots.
Returns: Nothing.

See Also: DCC Commands
Return to Index

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.

See Also: DCC Commands
Return to Index

putcmdlog <text>

Sends text to the log for any channel, marked as 'command' (c)
Returns: Nothing

See Also: Output Commands
Return to Index

putdcc <idx> <text>

Sends text to the dcc user indicated.
Returns: Nothing.

See Also: DCC Commands
Return to Index

puthelp <text>

Sends text to the server like 'putserv', but uses a different queue(intended for sending messages to channels or people)
Returns: Nothing

See Also: Output Commands
Return to Index

putlog <text>

Sends text to the log for any channel, marked as 'misc' (o)
Returns: Nothing

See Also: Output Commands
Return to Index

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

See Also: Output Commands
Return to Index

putserv <text>

Sends text to the server, like 'dump' (intended for direct server commands). Out put is queued so that you won't flood yourself off the server.
Returns: Nothing.

See Also: Output Commands
Return to Index

putxferlog <text>

Sends text to the log for any channel, marked as 'file-area' (x)
Returns: Nothing

See Also: Output Commands
Return to Index

rand <limit>

Returns: A random integer between 0 and limit-1.

bind raw <flags> <keyword-mask> <proc> procname <from> <keyword> <args...>

Stackable

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

Return Value: 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.

See Also: bind, unbind, or Command Extensions
Return to Index

bind rcvd <flags> <mask> <proc> proc-name <handle> <nick> <path/to/file>

Stackable

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)
(THIS IS ONLY AVALIABLE WHEN THE transfer.so MODULE IS LOADED)

See Also: bind, unbind, or Command Extensions
Return to Index

rehast

Rehash's the bot.
Returns: Nothing.

See Also: DCC Commands
Return to Index

bind rejn <flags> <nick!user@host> <proc> procname <nick> <user@host> <handle> <channel>

Stackable

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

See Also: bind, unbind, or Command Extensions
Return to Index

reload

Loads the userfile from disk (replacing whatever's in memory).
Returns: Nothing

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

restart

Rehash's the bot and kills all timers.
Returns: Nothing.

See Also: DCC Commands
Return to Index

rmdir <directory>

Removes a directory from the file system.
returns: 0 on success, 1 on failure.

save

Writes the userfile to disk.
Returns: Nothing.

savechannels

Saves the channel settings to the channel-file if one is defined.
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.

bind sent <flags> <mask> <proc> proc-name <handle> <nick> <path/to/file>

Stackable

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). (This IS ONLY Avaliable When The transfer.so Module Is Loaded).

See Also: bind, unbind, or Command Extensions
Return to Index

server

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

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.

See Also: DCC Commands
Return to Index

setchaninfo <handle> <channel> <info>

Sets the info line on a specific channel for a user.
Returns: Nothing

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.

See Also: DCC Commands
Return to Index

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.

setdnloads <handle> <#dnloads> <size-in-k>

Like setuploads, but sets the download statistics
Returns: Nothing.

setflags <dir> [flags]

Sets the flags required to access the directory.
Returns: 0 on success, -1 on failure.

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.

setowner <dir> <file> <handle>

Changes the owner for a file in the file system. The directory is relative to the dcc-path.
Returns: Nothing.

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.

setuploads <handle> <#uploads> <size-in-k>

Sets a user's statistics on the number of files uploaded and the total kilobytes uploaded.
Returns: Nothing.

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

This is the counterpart of getuser. It lets you set the various values.
Extra ones not supported about:

     PASS - use this to set a users password (no 3rd arg will clear it)
     HOSTS - for setting hosts, no extra info = clear, otherwise
             *1* hostmask is added :P
     LASTON - 2 forms:
              setuser  laston   
                 sets global laston time
              setuser  laston   *
                 will set a users laston time in a channel record 
                 (if it already exists)

bind sign <flags> <mask> <proc> procname <nick> <user@host> <handle> <channel> <reason>

Stackable

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.

See Also: bind, unbind, or Command Extensions
Return to Index

bind splt <flags> <mask> <proc> procname <nick> <user@host> <handle> <channel>

Stackable

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.

See Also: bind, unbind, or Command Extensions
Return to Index

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

Stores a note for later reading, notify idx of any results (use idx == -1 for no notify).
Returns: 0 on success and non-0 on failure.

See Also: Notes Module
Return to Index

strftime <fomatstring> [time]

Returns: a formatted string of time using standard strftime format, uses the value of time, or now if no time specified.

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.

Return to Index

time

Returns: The current time in 24-hour format (ie "14:15").

bind time - <mask> <proc> proc-name <min> <hour> <day> <month> <year>

Stackable

Allows you to schedule procedure calls at certain times, mask matches 5 space seperated integers of the form: "min hour day month year".

See Also: bind, unbind, or Command Extensions
Return to Index

timer <minutes> <tcl-command>

Executes the tcl command after a certain number of minutes have passed.
Returns: A timerID.

timers

Returns: List of active minutely timers. Eeach entry in the list contains the number of minutes left till activation, the command that will be executed, and the timerID.

bind topc <flags> <mask> <proc> procname <nick> <user@host> <handle> <channel> <topic>

Stackable

Triggered by a topic change. Can use wildcards in <mask>, which is matched against the channel name and new topic.

See Also: bind, unbind, or Command Extensions
Return to Index

topic <channel>

Returns: String of the current topic on the specified channel.

unbind <type> <attrs(s)> <command-name> [proc-name]

Removes a previously-made binding.
Returns: Name of the command that was removed.

bind unld - <mask> <proc> proc-name <module>

Stackable

Triggers when a module is unloaded.

See Also: bind, unbind, or Command Extensions
Return to Index

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.

unames

Returns: The current operating system the bot is using.

unixtime

Returns: A long integer which is the current time according to unix.

uptime

Unixtime value for when the bot was started.

userlist [flags]

Returns: a list of the handles of users on the bot.
You can use the new flag matching system here.
Usage: [global]{&/|}[chan]{&/|}[bot]
Matches the flags relvantly, (chan matches vs anywhere), & specifies and when match, | specifies or, only the first of these is relevant. The default is or.

utimer <seconds> <tcl-command>

Executes the tcl command after a certain number of seconds have passed.
Returns: A timerID.

utimers

Returns: List of active secondly timers, identical in format to the output from timers.

validchan <channel>

Checks if the bot is monitoring that channel.
Returns: 1 if the channel exists, 0 if not.

valididx <idx>

Returns "1" if the idx currently exists; "0" if not.

See Also: DCC Commands
Return to Index

validuser <handle>

Returns: "1" if a user by that name exists; '0' otherwise

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.

bind wall <flags> <mask> <proc> proc-name <nick> <msg>

Stackable

When the bot receives a wallops, it invokes this binding. Flags is ignored. The mask is checked against the text of the wallops msg.

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

See Also: bind, unbind, or Command Extensions
Return to Index

whom <channel>

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.

See Also: DCC Commands
Return to Index

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

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

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

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

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