Site Tools


exec_command

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

exec_command [2006/09/01 18:32]
exec_command [2018/11/28 21:15] (current)
Line 1: Line 1:
 +# $EPIC: exec_command.txt,​v 1.3 2006/08/30 21:02:47 sthalik Exp $
 +======Synopsis:​======
 +__exec__ [<​options>​] [<shell commands>​] \\
 +__exec__ -direct <​commands>​ \\
 +__exec__ -name <​name>​ <process id|shell commands>​ \\
 +__exec__ -out <process id|shell commands>​ \\
 +__exec__ -msg <​nickname|channel>​ <process id|shell commands>​ \\
 +__exec__ -notice <​nickname|channel>​ <process id|shell commands>​ \\
 +__exec__ -in <process id> <text to send to process> \\
 +__exec__ -window <process id|shell commands>​ \\
 +__exec__ -wintarget <​windesc>​ \\
 +__exec__ -<​signal>​ <process id> \\
 +__exec__ -close <process id> \\
 +__exec__ -closein <process id> \\
 +__exec__ -line {epic commands} <process id|shell commands>​ \\
 +__exec__ -linepart {epic commands} <process id|shell commands>​ \\
 +__exec__ -error {epic commands} <process id|shell commands>​ \\
 +__exec__ -errorpart {epic commands} <process id|shell commands>​ \\
 +__exec__ -end {epic commands} <process id|shell commands>​
 +
 +======Options:​======
 +|-direct ​   |executes commands without spawning a shell             |
 +|-name ​     |give the subprocess a (new) logical name             |
 +|-out       |send subprocess output to your current channel or query            |
 +|-msg       |send subprocess output to a nick or channel with [[MSG]] ​           |
 +|-notice ​   |send subprocess output to a nick or channel with [[NOTICE]] ​            |
 +|-in        |send a text string to the specified subprocess ​            |
 +|-window ​   |redirect subprocess output to the current window ​            |
 +|-wintarget |redirect subprocess output to the specified window ​            |
 +|-<​signal> ​ |send SIG<​signal>​ to the subprocess. \\ Numeric signals are also permitted. ​            |
 +|-close ​    ​|forcibly kill the subprocess and its children ​            |
 +|-closein ​  ​|close the input of the process but let it continue. ​            |
 +|-line ​     |run this command for each line of output. ​            |
 +|-linepart ​ |run this command for each partial line of output. ​            |
 +|-error ​    |run this command for each line of STDERR output. ​            |
 +|-errorpart |run this command for each partial line of STDERR output. ​            |
 +|-end       |run this command when the process terminates. \\ See comments on -END below. ​            |
 +
 +======Description:​======
 +__EXEC__ allows you to spawn other processes from within your client,
 +which are naturally treated as child processes. ​ For example, if you
 +wished to check your email without suspending your client (or
 +quitting irc), you could simply __EXEC__ your favorite mail program.
 +
 +Processes can be given unique names, allowing them to be referred to
 +more intuitively than trying to figure out its process id number.
 +Processes can also accept any signal normally available through use
 +of the Unix "​kill"​ command (letting you kill, suspend, etc. any
 +process that accepts such a signal). ​ Process identifiers begin with
 +a "​%"​. ​ Thus, a process named "​mail"​ with pid 0 could be referred to
 +as either "​%mail"​ or "​%0"​.
 +
 +__EXEC__ can take several different flags, each of which allow you to
 +manipulate the subprocess in different ways.  At the most basic
 +level, the only argument you really need to give is the external
 +program to run.  If no arguments are given at all, a list of any
 +currently running processes is returned.
 +
 +When using the -OUT, -MSG, or -NOTICE flags, output can be sent to
 +the target upon startup of the subprocess, or redirected to it after
 +it's already running by using its process id.
 +
 +Another flag of note, -CLOSE, can be used to shut down renegade
 +subprocesses that simply won't go away (i.e. with their own quit
 +command, with the KILL signal, etc.). ​ This actually just severs the
 +link between the subprocess and the client, so it will die on its
 +own the next time it tries to send data to the client.
 +
 +Something to remember when worried about a shell processing arguments
 +is the -DIRECT flag, which executes the commands without spawning a
 +shell. This can cut down on security risks, and save some memory.
 +
 +The options -LINE, -ERROR, -LINEPART, -ERRORPART and -END all take
 +arguments which must be enclosed in braces "​{}"​ and which are executed
 +for particular kinds of output that the process might give. The $*
 +variable will contain that output when those commands are executed.
 +
 +Note that the -END flag is different from the other flags. When you
 +specify a %process instead of shell commands, the flags you specify
 +become the new options for the currently running process of that name
 +(if possible), replacing the current settings for those options.
 +Specifying a -END flag in this mode is will add to, rather than
 +replace other -END options.
 +
 +======Examples:​======
 +(Assume that the process used with these examples is the Unix mail
 +program.)
 +
 +To start a process:
 +      /exec mail
 +
 +To start a process without a shell interfering:​
 +      /exec -direct mail
 +
 +To start a process and give it a human-readable name:
 +      /exec -name mail mail
 +
 +To send the output of a new subprocess to your current channel or query:
 +      /exec -out mail
 +
 +To send the output of a running subprocess to JoeBob with a [[MSG]]:
 +      /exec -msg joebob %mail
 +
 +To send the output of a new subprocess to #blah with a [[NOTICE]]:
 +      /exec -notice #blah mail
 +
 +To send a text string (command) to a running subprocess:
 +      /exec -in %mail ?
 +
 +To send a running subprocess the KILL signal:
 +      /exec -kill %mail
 +
 +To forcibly close down a stubborn subprocess that just won't die:
 +      /exec -close %mail
 +
 +To rename a process:
 +      /exec -name MyMail %mail
 +
 +To make all mail output bold:
 +      /exec -line {echo $chr(2)$*} %mail
 +
 +To add more -end commands after the process has started:
 +      /exec -end {commands} %mail
 +Which is equivalent to:
 +      /wait %process -cmd {commands}
 +
 +======Aliases:​======
 +When using __EXEC__ with the -IN flag, the functionality is identical to
 +using [[MSG]] to send a message to a process. ​ See [[MSG]] for more
 +information.
 +
 +When using the -END flag, the functionality is identical to using 
 +"​[[WAIT]] %process -cmd {command}"​.
 +
 +======Restrictions:​======
 +Use of external programs from within irc can sometimes be dangerous
 +if you don't know what you're doing. ​ The danger doesn'​t necessarily
 +lie in the external programs themselves, but rather in any lack of
 +knowledge about them you may have.  When all else fails, don't use a
 +command if you don't know what it does.
 +
 +You can explicitly limit your ability to use __EXEC__ in several ways.
 +If [[set SECURITY]] has the 1 bit set, the client will only permit __EXEC__
 +to be used interactively;​ using it from within aliases is not allowed.
 +For real security, you can #define RESTRICTED at compile time, which
 +will completely disable __EXEC__.
 +
 +======Other Notes:​======
 +The available signals that may be sent to a process will vary from system
 +to system.
 +