.EL File Format – Processes

Synchronous subprocesses

These functions start a program, wait for it to end, and return. Emacs does not handle other events meanwhile, except that C-g can interrupt.

(with-temp-buffer
  (call-process "git" nil t nil "rev-parse" "HEAD")
  (string-trim (buffer-string)))

Asynchronous processes

make-process starts a program and returns a process object at once. The program runs alongside Emacs, whose output arrives while Emacs waits for input or is in accept-process-output. It takes keyword arguments:

start-process NAME BUFFER PROGRAM &rest ARGS is the older, shorter form, and start-file-process is the one that honours file name handlers. A pseudo-terminal (pty) makes the program think it talks to a terminal and merges the two output streams; a pipe keeps them separate and is more reliable for data. A process is a Lisp object, so a sentinel or a filter can use it to control the process.

(make-process
 :name "ping"
 :command '("ping" "-c" "3" "localhost")
 :buffer "*ping*"
 :noquery t
 :filter (lambda (proc string)
           (with-current-buffer (process-buffer proc)
             (goto-char (point-max))
             (insert string)))
 :sentinel (lambda (proc event)
             (message "%s: %s" (process-name proc) (string-trim event))))

When :stderr is a buffer, Emacs makes a hidden pseudo-process that reads the error output into that buffer. A filter is called with output in chunks that may stop in the middle of a line. A sentinel runs after a status change, with a string such as "finished\n" or "exited abnormally with code 1\n".

Environment

A program is looked up in the list exec-path, and its environment is process-environment, a list of "NAME=value" strings. The macro with-environment-variables (Emacs 28) binds some of them for its body: (with-environment-variables (("LANG" "C")) (shell-command-to-string "date")). getenv and setenv read and change them in Emacs itself.

Network connections

Threads

A thread runs Lisp code beside the main thread, but only one thread runs at a time. Threads are cooperative: control passes when the running thread waits (for a process, a mutex or a condition variable), calls thread-yield, or finishes. They share variables and buffers; a let binding of a variable is local to its thread.

From Emacs 31 make-thread has an argument to choose what happens when the current buffer of a thread is killed (“buffer disposition”), with thread-buffer-disposition and thread-set-buffer-disposition to read and set it. Timers are on Commands and modes.

JSON

Emacs has JSON functions built in (Emacs 27). From Emacs 30 they no longer depend on an external library, and json-available-p always returns true.

Emacs 30 changed some details: repeated object keys are kept in alist and plist results, bad UTF-8 signals json-utf8-decode-error, and integers of any size are accepted.

(json-parse-string "{\"a\": [1, 2, null]}" :object-type 'alist :array-type 'list)
;; => ((a 1 2 :null))
(json-serialize '((a . 1) (b . "x")))

System interaction and batch mode

Batch mode runs Emacs with no display. emacs --batch -l file.el loads a file and exits when done; --eval and -f run a form and a function. Messages go to standard error and princ to standard output. The option --script FILE loads a file as a script, and so does -x; from Emacs 31 the files loaded with -x and --script use lexical binding. A script starts with a line such as #!/usr/bin/env -S emacs --script (File structure). A script that needs its own arguments reads them from command-line-args-left and removes them:

#!/usr/bin/env -S emacs --script
;;; -*- lexical-binding: t -*-
(while command-line-args-left
  (princ (format "arg: %s\n" (pop command-line-args-left))))

Not described

Known, not yet covered

• Reference: dynamic modules are named only: a shared library that includes emacs-module.h is loaded with module-load, or by load; the C API is not described. D-Bus (dbus-call-method and friends) is named only.
• Reference: the SQLite functions (sqlite-open, sqlite-execute, sqlite-select), built in when Emacs is built with SQLite (Emacs 29), are named only.
• Reference: the rest of the options of make-network-process (for example :tls-parameters and the options set by set-network-process-option), the process filter details (process-filter-multibyte-p), signals and the pty settings are summarised.

Unknown

• The Emacs version that added threads and the -x option: the reference sources used here do not state it.

See also

• Files – file name handlers and remote files
• Commands and modes – timers and hooks
• Packages and autoloads – load of dynamic modules
• Processes – the manual chapter
• Threads – the manual section on threads
• Parsing and generating JSON values – the manual section