Function: terminal-emulator

terminal-emulator is an interactive and byte-compiled function defined in terminal.el.gz.

Signature

(terminal-emulator BUFFER PROGRAM ARGS &optional WIDTH HEIGHT)

Documentation

Under a display-terminal emulator in BUFFER, run PROGRAM on arguments ARGS.

ARGS is a list of argument-strings. Remaining arguments are WIDTH and HEIGHT. BUFFER's contents are made an image of the display generated by that program, and any input typed when BUFFER is the current Emacs buffer is sent to that program as keyboard input.

Interactively, BUFFER defaults to "*terminal*" and PROGRAM and ARGS are parsed from an input-string using your usual shell. WIDTH and HEIGHT are determined from the size of the current window
-- WIDTH will be one less than the window's width, HEIGHT will be its height.

To switch buffers and leave the emulator, or to give commands to the emulator itself (as opposed to the program running under it), type Control-^. The following character is an emulator command. Type Control-^ twice to send it to the subprogram. This escape character may be changed using the variable terminal-escape-char.

Meta characters may not currently be sent through the terminal emulator.

Here is a list of some of the variables which control the behavior of the emulator -- see their documentation for more information: terminal-escape-char, terminal-scrolling, terminal-more-processing, terminal-redisplay-interval.

This function calls the value of terminal-mode-hook if that exists and is non-nil after the terminal buffer has been set up and the subprocess started.

Probably introduced at or before Emacs version 18.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/obsolete/terminal.el.gz
;; This used to have `new' in it, but that loses outside BSD
;; and it's apparently not needed in BSD.

;;;###autoload
(defun terminal-emulator (buffer program args &optional width height)
  "Under a display-terminal emulator in BUFFER, run PROGRAM on arguments ARGS.
ARGS is a list of argument-strings.  Remaining arguments are WIDTH and HEIGHT.
BUFFER's contents are made an image of the display generated by that program,
and any input typed when BUFFER is the current Emacs buffer is sent to that
program as keyboard input.

Interactively, BUFFER defaults to \"*terminal*\" and PROGRAM and ARGS
are parsed from an input-string using your usual shell.
WIDTH and HEIGHT are determined from the size of the current window
-- WIDTH will be one less than the window's width, HEIGHT will be its height.

To switch buffers and leave the emulator, or to give commands
to the emulator itself (as opposed to the program running under it),
type Control-^.  The following character is an emulator command.
Type Control-^ twice to send it to the subprogram.
This escape character may be changed using the variable `terminal-escape-char'.

`Meta' characters may not currently be sent through the terminal emulator.

Here is a list of some of the variables which control the behavior
of the emulator -- see their documentation for more information:
terminal-escape-char, terminal-scrolling, terminal-more-processing,
terminal-redisplay-interval.

This function calls the value of terminal-mode-hook if that exists
and is non-nil after the terminal buffer has been set up and the
subprocess started."
  (interactive
   (cons (with-current-buffer (get-buffer-create "*terminal*")
           (buffer-name (if (or (not (boundp 'te-process))
                                (null te-process)
                                (not (eq (process-status te-process)
                                         'run)))
                            (current-buffer)
                          (generate-new-buffer "*terminal*"))))
         (append
          (let* ((default-s
                   ;; Default shell is same thing M-x shell uses.
                   (or explicit-shell-file-name
                       (getenv "ESHELL")
                       (getenv "SHELL")
                       (if (eq system-type 'android)
                           "/system/bin/sh"
                         "/bin/sh")))
                 (s (read-string
                     (format "Run program in emulator (default %s): "
                             default-s))))
            (if (equal s "")
                (list default-s '())
              (te-parse-program-and-args s))))))
  (switch-to-buffer buffer)
  (if (null width) (setq width (- (window-width (selected-window)) 1)))
  (if (null height) (setq height (- (window-height (selected-window)) 1)))
  (terminal-mode)
  (setq te-width width te-height height)
  (setq te-terminal-name (concat te-terminal-name-prefix
				 (number-to-string te-width)
				 (number-to-string te-height)))
  (setq mode-line-buffer-identification
	(list (format "Emacs terminal %dx%d: %%b  " te-width te-height)
	      'te-pending-output-info))
  (let ((buffer-read-only nil))
    (te-clear-screen))
  (let (process)
    (while (setq process (get-buffer-process (current-buffer)))
      (if (y-or-n-p (format "Kill process %s? " (process-name process)))
	  (delete-process process)
	(error "Process %s not killed" (process-name process)))))
  (condition-case err
      (let ((process-environment
	     (cons (concat "TERM=" te-terminal-name)
		   (cons (concat "TERMCAP=" (te-create-termcap))
			 (cons (concat "TERMINFO=" (te-create-terminfo))
			       process-environment)))))
	(setq te-process
	      (start-process "terminal-emulator" (current-buffer)
			     "/bin/sh" "-c"
			     ;; Yuck!!! Start a shell to set some terminal
			     ;; control characteristics.  Then start the
			     ;; "env" program to setup the terminal type
			     ;; Then finally start the program we wanted.
			     (format "%s; exec %s"
				     te-stty-string
				     (mapconcat #'te-quote-arg-for-sh
						(cons program args) " "))))
	(set-process-filter te-process #'te-filter)
	(set-process-sentinel te-process #'te-sentinel))
    (error (fundamental-mode)
	   (signal (car err) (cdr err))))
  (setq inhibit-quit t)			;sport death
  (use-local-map terminal-map)
  (run-hooks 'terminal-mode-hook)
  (message "Entering Emacs terminal-emulator...  Type %s %s for help"
	   (single-key-description terminal-escape-char)
	   (mapconcat #'single-key-description
		      (where-is-internal #'te-escape-help terminal-escape-map t)
		      " ")))