ishell(3)

NAME

ishell - Open a interactive shell window
%ishell - User defined ishell shell

PLATFORM

Windows '95/'98/NT/2K/XP/Vista/7/10/11 - windows
Cygwin - cygwin
Unix - All variants.

SYNOPSIS

n ishell

%ishell = <shell>

DESCRIPTION

ishell creates an interactive shell window within the a MicroEmacs buffer window, providing access to the native operating systems command shell. Within the window commands may be entered and executed, the results are shown in the window.

On running ishell a new buffer is created called *shell* which contains the shell. Executing the command again while that shell is still running simply pops up the existing *shell* window, a new shell is started in the same buffer once the current shell has been exited.

Numeric Argument

The numeric argument n is a bit based flag where:

0x0f


Selects the shell to be executed from the shell list, see "Selecting the Shell" below. When no argument is given a value of 1 is used, selecting the first shell in the list.

0x10


Disables the interpretation of ANSI color escape sequences, see bit 0x1000 of ipipe-shell-command(2). Color is enabled by default, so 17 ishell runs the first shell in the list without color.

If a -ve argument is given then an existing *shell* window is popped up as usual, but no new shell is created if one is not already running.

Selecting the Shell

The shell that is executed is selected from a platform dependent list of shells using the numeric argument, the list being as follows

Unix


$SHELL

Windows


$COMSPEC (typically cmd.exe), powershell

Cygwin


$COMSPEC (converted to a cygwin path), powershell, $SHELL

When the list contains only one shell that shell is always used and the numeric argument is ignored. Otherwise, if the argument does not select a valid entry in the list (e.g. 0 ishell) then the user is prompted to "Select shell" from the list, a shell which is not in the list may also be entered.

An alternative shell may be added to the list by setting the user variable %ishell to the command used to launch it. The shell is inserted at the head of the list and therefore becomes the default, the standard platform shells remain available via the numeric argument. %ishell is typically set in the user or company setup macro file, see user-setup(3), for example:

set-variable %ishell "C:/Program Files/Git/bin/bash.exe" 

Additional controls are available within the shell window to control the editors interaction with the window. The operating mode is shown as a digit on the buffer mode line (2/3/4) which is defined in the following sections. The operational mode is changed with the F3 function key.

Mode 2 - Browse Mode


Locks the window and allows local editing to be performed. All commands entered into the window are interpreted by the editor. Mode 2 is typically entered to cut and paste from the window, search for text strings etc. In mode 2, a 2 is shown on the mode line.

Mode 3 - Semi-immersion


The normal operating mode, text typed into the window is presented to the shell window. Translation of MicroEmacs commands (i.e. beginning-of-word) are translated and passed to the shell. For interactive use this is the default mode. In mode 3, a 3 is shown on the mode line.

Mode 4 - Full Immersion


All input is passed to the shell, no MicroEmacs commands are interpreted and keys are passed straight to the shell window. This mode is used where none of the keys to be entered are to be interpreted by MicroEmacs. Note that you have to un-toggle mode 4 before you can swap buffers as this effectively locks the editor into the window.

To exit the shell then end the shell session using the normal exit command i.e. "exit" or "C-d" as normal and then close the buffer. A short cut "C-c C-k" is available to kill off the pipe. However, it is not recommended that this method is used as it effectively performs a hard kill of the buffer and attached process.

UNIX

The UNIX environment uses the native pty support of the operating system. The shell that is opened is determined by the conventional $SHELL environment variable, see "Selecting the Shell" above.

The shell window assumes that the user is running some sort of Emacs emulation on the command line (i.e. VISUAL=emacs for ksh(1), zsh(1), bash(1), tsch(1)) and passes Emacs controls for command line editing.

The shell window understands re-size operations and provides a limited decoding of the termio characters for a VT100 screen. From within the shell window it is possible to run the likes of top(1) correctly. It is even possible to run another MicroEmacs terminal session !!

WINDOWS

The Windows environment provides a very poor command shell facility, this is more of a fundamental problem with the operating system than anything else. Unfortunately NT/2K/XP/7/10/11 are no better than Windows '95/'98, stemming from the fact that Microsoft Windows is actually a huge Window Manager (hindered by legacy issues of MS-DOS).

For those familiar with the UNIX command shell then it is strongly recommended that the cygwin(3) BASH shell is used as an alternative. This is a far more responsive shell window and provides the familiar Emacs editing of the command line.

The command shell under Microsoft Windows is slow and very unresponsive, this would appear to be a problem with the command.com as the same problems are not apparent with the cygwin environment. However, the shell window is good for kicking off command line utilities (such as make) or any command line processes that generates output on stdout as all of the output is captured in the buffer window which can be scrolled backwards for post analysis. For this very reason it is more preferable to a standard MS-DOS box.

Where a ConPTY pseudo terminal can be created, see bit 0x08 of ipipe-shell-command(2), utilities which use embedded screen control characters may be run as the editor interprets them. If a pseudo terminal cannot be created a warning is issued as such utilities will not then work.

Changing the Shell

The shells offered are the command processor defined by the environment variable $COMSPEC (typically cmd.exe) and powershell, selected by the numeric argument as described in "Selecting the Shell" above. Where the user is using a different command shell (i.e. 4-DOS), then problems may arise if this is an old 16-bit executable, an alternative shell may be made the default by setting %ishell.

Note that %ishell replaces the $ME_ISHELL environment variable used by earlier versions of MicroEmacs, a $ME_ISHELL setting is no longer used and must be converted to %ishell.

Bugs

WinOldAp


Winoldap is created by the Microsoft environment whenever a shell is created. On occasions where processes have terminated badly the user may be prompted to kill these off; this is the normal behaviour of Windows. It is strongly advised that the shell is always exited correctly (i.e. exit) before leaving the editor. The Windows operating system for '95/'98 is not particularly resilient to erroneous processes and can bring the whole system down. NT/2K/XP do not appear to suffer from these problems (so much).

Locked Input


There are occasions after killing a process the editor appears to lock up. This is typically a case that the old application has not shut down correctly. Kill off the erroneous task (Alt-Ctrl-Del - End Task) then bring the editor under control using a few C-g abort-command(2) sequences.

NOTES

The ishell command uses the ipipe-shell-command(2) to manage the pipe between the editor and the shell. The window is controlled by the macro file hkipipe.emf which controls the interaction with the shell.

SEE ALSO

ipipe-shell-command(2), cygwin(3), user-setup(3).

Ref: ishell(3) File: m3mac034.3 Date: 2026/08/18

(c) Copyright JASSPA 2026