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 - linux, macos, freebsd, hpux, sunos.

Windows NT - windows.

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 (windows 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 forces wrap(2m) mode off minimising line 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 way in which the process is terminated, if a 0 argument is given an interrupt signal (kill request or nice-kill) is sent, writing a Ctrl-C to the <stdin> pipe on UNIX or sending Ctrl-C key events on Windows. This is likely to fail, particularly on Windows which does not have a robust signal interrupt system, however it is still typically bound to C-c C-c as Windows does not offer an alternative. On UNIX based systems C-c C-c is typically bound to ipipe-kill with a numeric argument of 2 which sends a SIGINT, see signal(7).

On UNIX platforms, if a +ve argument is given then only the top level process is sent a kill signal of the given value, e.g. the process would be terminated with a core dump if a value of 3 was given. If a -ve argument is given the process and all its children, in the same process group, will be sent a 0-n kill signal. When no argument is given the default used is either -9, -SIGKILL, or -15, -SIGTERM, depending on the setting of bit 0x2000000 of $system(5).

On Windows, if no argument or a -ve argument is given ipipe-kill terminates the process and all non-detached sub-processes, whereas a +ve only terminates the top level process.

ipipe-kill with no argument is typically bound to C-c C-k.

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. When wrap mode is enabled text output is automatically wrapped at the width of the current window, when disabled (see arg n bits 0x40 and 0x200) lines will only wrap at (maximum length of a MicroEmacs variable - 2), currently 2046, so that the ipipe command can safely process the output. This length can be controlled by the %ipipe-width user variable.

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 2025
Last Modified: 2025/03/16
Generated On: 2025/09/29