
==============================================================================

           BGExec Version 1.3 -- Background Execution for Eggdrop
                            Written by Fosters@G0

                    (c) Copyright 1998 Eden Developments
                             All Rights Reserved

==============================================================================

BGExec consists of a module, a TCL and a small binary that provides you with
background command execution in Eggdrop v1.3.x

Why three files ? Well, TCL's existing exec command still freezes when the
bgexec binary is executed, even tho it forks. The module provides the low
level interface to the bgexec binary which does the actual grunt work. The
reason for the seperate binary is because when you fork() from eggdrop, it
leaves a zombie process each time, but bgexec's zombie will die after the
command has finished. The TCL provides the execbg proc, which is a higher
level interface to bgexec and will watch for command completion. 

bgexec also properly handles programs that are badly written and put
non-error information on stderr, thus fucking up eggdrop procedures. A good
example of this is traceroute. The only time stderr is used is when the
bgexec binary is used incorrectly, which should never happen from TCL as the
errors that cause it are stopped before it happens.

==============================[ INSTALLATION ]===============================

First, copy the directory bgexec.mod to your eggdrop1.3.x/src/mod directory
and type make. This will make the module which you can then copy to your
eggdrop/modules/ directory. Copy the bgexec.tcl to eggdrop/scripts, and add
the following to your eggdrop.conf:

# Load BGExec
loadmodule bgexec
source scripts/bgexec.tcl

You now must compile bgexec.c as follows:

gcc bgexec.c -o bgexec

Now copy the resulting binary (bgexec) to anywhere you like, ~/bin/ is the
best choice, or your eggdrop directory.

You now need to edit the bgexec.tcl as follows.

At the top of the file, you will find the following:

# Path to bgexec executable
set bgexec_path "/home/fosters/bin/bgexec"

# Interval in seconds for checking for completion
set bgcheck 3

Change the path to the bgexec binary to wherever you put it (you need to put
the bgexec in too). I suggest you either leave the bgcheck as it is, or
change it to something smaller if you find output too slow. Increasing the
value means it will take longer to find output.

=================================[ USEAGE ]=================================

A small example of using bgexec is in test.tcl, a larger (and much more
usefull) one is in traceroute.tcl This will allow you to perform traceroutes
from the bot. 

To run a command in the background you use the execbg command. It has the
following arguments:

execbg commandtorun proctocall info

commandto run is the path and filename of the command to run
proctocall is the proc to be called when the command has completed. It will
be called with the following arguments:

tmpfile: path and filename of file containing output from the command
info: whatever you gave as the last argument to execbg, usually an IDX or
nick/channel on IRC.

For how to load files into a variable, and displaying in a DCC, please look
at the test.tcl example. 

==============================[ SECURITY NOTE ]=============================

WARNING!!! *NO* PERMISSION CHECKS ARE DONE. IF YOU ARE NOT CAREFULL PEOPLE
MAY BE ABLE TO ACCESS YOUR SHELL FROM THE BOT. 

==============================================================================

If you have any comments, patches or ideas for bgexec please email them to
fosters@dvalley.demon.co.uk
