ipipe-shell-command(2)

NAME

ipipe-shell-command - Incremental pipe (non-suspending system call)
ipipe-kill - Kill a incremental pipe
ipipe-write - Write a string to an incremental pipe

SYNOPSIS

n ipipe-shell-command "command" ["buffer-name"] ["buffer-ipipe-command"] (esc backslash) 
n ipipe-write "string"
n ipipe-kill

PLATFORM

UNIX - irix, hpux, sunos, freebsd, linux.

Windows NT - win32.

DESCRIPTION

ipipe-shell-command executes the given system command command, opening up a *icommand* buffer into which the results of the command execution are displayed. Unlike the pipe-shell-command(2), the user may continue editing during command execution. The command may be terminated by deleting the buffer or issuing a ipipe-kill command.

The argument n can be used to change the default behavior of pipe-shell-command described above, n is a bit based flag where:-

0x01


Enables the use of the default buffer name *icommand* (default). If this bit is clear the user must supply a buffer name buffer-name. The buffer naming allows another command to be started without effecting any other existing command buffer.

0x02


Hides the output buffer, the default action pops up a window and displays the output buffer in a new window.

0x04


Disable the use of the command-line processor to launch the program (MS Win32 versions only). By default the "command" is launched by executing the command:

    %COMSPEC% /c command 

Where %COMSPEC% is typically command.com. If this bit is set "command" is launched directly.

0x08


Detach the launched process from MicroEmacs (MS Win32 versions only). By default the command is launched as a child process of MicroEmacs with a new console. With this bit set the process is completely detached from MicroEmacs instead.

0x10


Disable the command name mangling (MS Win32 versions only). By default any '/' characters found in the command name (the first argument only) are converted to '\' characters to make it Windows compliant.

0x20


Displays the new process window (win32 versions only), by default the window is hidden.

0x40


Raw ipipe, disable text annotation at the start and end of the pipe output and force wrap(2m) mode off.

0x80


Supply a function buffer-ipipe-command to be invoked when the pipe receives data and terminates. This is equivalent to setting the buffer variable $buffer-ipipe(5) but allows the pipe to be set when the ipipe is created. Setting the $buffer-ipipe on invocation allows the pipe exit status to be trapped properly.

0x100


When set the command-line to be run is the first line of buffer string, this feature can be used to overcome the default 1024 character command-line limit. When a multiple-line command-line is required, a negative argument can be given to insert-string(2).

0x200


When set prevents the lines from wrapping.

Many other macro commands (see compile(3), grep(3), etc.) use this command.

ipipe-write writes a string string to an open ipipe, n times.

ipipe-kill terminates an open ipipe and is automatically invoked when the ipipe buffer is deleted using delete-buffer(2) or when MicroEmacs is exited. The numeric argument n may be used to change the signal generated, where n takes the following values:

1


Sends a Terminate process signal, literally a SIGKILL signal on UNIX or a WM_CLOSE on Windows. This is the default signal and is typically bound to C-c C-k.

2


Sends an interrupt signal, writes a Ctrl-C to the <stdin> pipe on UNIX or sends Ctrl-C key events on Windows. This is typically bound to C-c C-c.

NOTES

On UNIX platforms the TERM environment variable of the new process may be set by setting the user variable %ipipe-term to the required value, e.g.:

    set-variable %ipipe-term "TERM=vt100-nam" 

Ipipe shells support a large sub-set of vt100 terminal commands, notable exceptions are color, font support and auto-margins. Using the terminal type "vt100-nam" disables the use of auto-margins, thereby providing better support.

On platforms which do not support ipipe-shell-command, such as MS-DOS, executing ipipe-shell-command automatically invokes pipe-shell-command. Therefore macros may safely use ipipes without explicitly checking the platform type. ipipe-shell-command does not run reliably on Windows 3.11 and Windows 95; Windows NT does support ipipes.

While the pipe command is running, mode pipe(2m) is enabled. Modes lock(2m) and wrap(2m) effect the output behavior of an ipipe-shell-command.

EXAMPLE

The following example is the xgrep(3) command macro which utilizes the ipipe-shell-command, diverting the output to a buffer called *grep*.

define-macro xgrep 
    !force set-variable #l0 @1 
    !if &not $status 
        set-variable #l0 @ml00 %xgrep-com 
    !endif 
    !if @? 
        1 pipe-shell-command &cat %xgrep-com #l0 "*grep*" @mna 
    !else 
        1 ipipe-shell-command &cat %xgrep-com #l0 "*grep*" @mna 
    !endif 
!emacro 

Note that if an argument is passed to grep then it uses pipe-shell-command instead. This is useful if another command is using grep which must finish before the calling command can continue, see replace-all-string(3) for an example.

BUGS

On MicroSoft Windows platforms, ipipe-shell-command spawns the shell (e.g. command.com) with the appropriate command line to make it execute the given command. If the command to be run detaches from the shell and creates its own window, for example me.exe, ipipe-kill will only kill the shell, it will not kill the actual process, i.e. the me.exe.

On MicroSoft Windows platforms ipipe-shell-command does not work on Novell's Intranet Client v2.2 networked drives, version 2.5 does appear to work.

SEE ALSO

$buffer-ipipe(5), $buffer-input(5), compile(3), grep(3), pipe-shell-command(2), replace-all-string(3), shell-command(2), pipe(2m), lock(2m), wrap(2m).

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12