$buffer-ipipe(5)

NAME

$buffer-ipipe - Divert buffer incremental pipe input through macro.
$buffer-ipipe-flags - Incremental pipe creation flags.

SYNOPSIS

$buffer-ipipe commandName

$buffer-ipipe-flags flags ; read-only

DESCRIPTION

$buffer-ipipe allows the buffer incremental pipe input mechanism to be diverted through a command macro defined by commandName. On a buffer running an ipipe-shell-command(2) the command, set by this variable, will be called whenever new text has been inserted by the executing process. Two alpha-marks will be set in the buffer, 'i' denotes the start of the newly inserted text and 'I' denotes the end.

When the ipiped command exits the commandName is called with a numeric argument of 0 and the $result(5) variable is set to the exit code of the process, this will be the last call of the command. The following values of $result are also used by MicroEmacs:

-1000


The ipiped process did not exit normally, cause unknown.

-1009


The ipiped process was killed.

-1011


The ipiped process core dumped.

-1015


The ipiped process was terminated.

Not all platforms support all of these exit codes.

$buffer-ipipe-flags is a read-only variable which records how the incremental pipe running, or last run, in the current buffer was created by ipipe-shell-command(2). It allows macros to determine how the process was launched, and how its output was processed, without having to retain this information themselves. flags is a bit based flag where:

0x01


The buffer is, or was, running an ipiped process. This bit remains set after the process has exited, mode pipe(2m) may be used to determine whether the process is still running. If this bit is clear the buffer has never run an ipiped process and all other bits are 0.

0x02


The process was launched with a pseudo terminal, i.e. a UNIX PTY or a Windows ConPTY, as opposed to a plain anonymous pipe. A pseudo terminal may be requested but not granted, this bit reflects what was created and not what was asked for, see ipipe-shell-command bits 0x08 and 0x2000.

0x04


The pipe was created as a raw pipe, see ipipe-shell-command bit 0x40. As no text annotation is added in this mode, the buffer does not contain the leading "cd path" and command lines, so the command-line which was executed cannot be recovered from the buffer.

0x08


wrap(2m) mode was enabled when the pipe was created, i.e. neither bit 0x200 nor bit 0x40, raw mode which also forces wrap mode off, was given to ipipe-shell-command. The buffer's wrap mode may subsequently be changed, by the user or a macro, this bit always records the state at creation.

0x10


The pipe output is being decoded from UTF-8, see ipipe-shell-command bit 0x800. Note that this bit is clear when the output is not decoded for any reason, such as the terminal not operating in UTF-8 mode, and not simply when decoding was explicitly disabled.

0x20


ANSI color processing was enabled, see ipipe-shell-command bit 0x1000.

The remaining bits are reserved for future use and are currently always 0.

EXAMPLE

The following example, taken from the ipipe-rerun macro, uses $buffer-ipipe-flags to construct the numeric argument required to re-launch the command in the current buffer with the same settings:

; A raw pipe leaves no command-line in the buffer to re-run 
!iif &band 0x04 $buffer-ipipe-flags \ 
    -8 ml-write "[ipipe-rerun Error: command-line lost]" 
; Convert the flags back into an ipipe-shell-command argument 
set-variable #l0 &con &band 0x02 $buffer-ipipe-flags 0x08 0x2000 
set-variable #l0 &add #l0 &con &band 0x08 $buffer-ipipe-flags 0 0x200 
set-variable #l0 &add #l0 &con &band 0x20 $buffer-ipipe-flags 0x1000 0 

Note that bits 0x02 and 0x08 are inverted in the construction as ipipe-shell-command bits 0x2000 and 0x200 disable the features which $buffer-ipipe-flags reports as enabled.

SEE ALSO

ipipe-shell-command(2), goto-alpha-mark(2), $result(5), $buffer-input(5), pipe(2m), wrap(2m).

Ref: $buffer-ipipe(5) File: m5var006.5 Date: 2025/10/27

(c) Copyright JASSPA 2026