Function: server-process-filter

server-process-filter is a byte-compiled function defined in server.el.gz.

Signature

(server-process-filter PROC STRING)

Documentation

Process a request from the server to edit some files.

PROC is the server process. STRING consists of a sequence of commands prefixed by a dash. Some commands have arguments; these are &-quoted and need to be decoded by server-unquote-arg. The filter parses and executes these commands.

To illustrate the protocol, here is an example command that emacsclient sends to create a new X frame (note that the whole sequence is sent on a single line):

-env HOME=/home/lorentey
-env DISPLAY=:0.0
... lots of other -env commands
-display :0.0
-window-system

The following commands are accepted by the server:

-auth AUTH-STRING
  Authenticate the client using the secret authentication string
  AUTH-STRING.

-env NAME=VALUE
  An environment variable on the client side.

-dir DIRNAME
  The current working directory of the client process.

-current-frame
  Forbid the creation of new frames.

-frame-parameters ALIST
  Set the parameters of the created frame.

-nowait
  Request that the next frame created should not be
  associated with this client.

-display DISPLAY
  Set the display name to open X frames on.

-position +LINE[:COLUMN]
  Go to the given line and column number
  in the next file opened.

-file FILENAME
  Load the given file in the current frame.

-eval EXPR
  Evaluate EXPR as a Lisp expression and return the
  result in -print commands.

-window-system
  Open a new X frame.

-tty DEVICENAME TYPE
  Open a new tty frame at the client.

-suspend
  Suspend this tty frame. The client sends this string in
  response to SIGTSTP and SIGTTOU. The server must cease all I/O
  on this tty until it gets a -resume command.

-resume
  Resume this tty frame. The client sends this string when it
  gets the SIGCONT signal and it is the foreground process on its
  controlling tty.

-ignore COMMENT
  Do nothing, but put the comment in the server log.
  Useful for debugging.

The following commands are accepted by the client:

-emacs-pid PID
  Describes the process id of the Emacs process;
  used to forward window change signals to it.

-window-system-unsupported
  Signals that the server does not support creating X frames;
  the client must try again with a tty frame.

-print STRING
  Print STRING on stdout. Used to send values
  returned by -eval.

-print-nonl STRING
  Print STRING on stdout. Used to continue a
  preceding -print command that would be too big to send
  in a single message.

-error DESCRIPTION
  Signal an error and delete process PROC.

-suspend
  Suspend this terminal, i.e., stop the client process.
  Sent when the user presses C-z (suspend-frame).

Source Code

;; Defined in /usr/src/emacs/lisp/server.el.gz
(defun server-process-filter (proc string)
  "Process a request from the server to edit some files.
PROC is the server process.  STRING consists of a sequence of
commands prefixed by a dash.  Some commands have arguments;
these are &-quoted and need to be decoded by `server-unquote-arg'.
The filter parses and executes these commands.

To illustrate the protocol, here is an example command that
emacsclient sends to create a new X frame (note that the whole
sequence is sent on a single line):

	-env HOME=/home/lorentey
	-env DISPLAY=:0.0
	... lots of other -env commands
	-display :0.0
	-window-system

The following commands are accepted by the server:

`-auth AUTH-STRING'
  Authenticate the client using the secret authentication string
  AUTH-STRING.

`-env NAME=VALUE'
  An environment variable on the client side.

`-dir DIRNAME'
  The current working directory of the client process.

`-current-frame'
  Forbid the creation of new frames.

`-frame-parameters ALIST'
  Set the parameters of the created frame.

`-nowait'
  Request that the next frame created should not be
  associated with this client.

`-display DISPLAY'
  Set the display name to open X frames on.

`-position +LINE[:COLUMN]'
  Go to the given line and column number
  in the next file opened.

`-file FILENAME'
  Load the given file in the current frame.

`-eval EXPR'
  Evaluate EXPR as a Lisp expression and return the
  result in -print commands.

`-window-system'
  Open a new X frame.

`-tty DEVICENAME TYPE'
  Open a new tty frame at the client.

`-suspend'
  Suspend this tty frame.  The client sends this string in
  response to SIGTSTP and SIGTTOU.  The server must cease all I/O
  on this tty until it gets a -resume command.

`-resume'
  Resume this tty frame.  The client sends this string when it
  gets the SIGCONT signal and it is the foreground process on its
  controlling tty.

`-ignore COMMENT'
  Do nothing, but put the comment in the server log.
  Useful for debugging.


The following commands are accepted by the client:

`-emacs-pid PID'
  Describes the process id of the Emacs process;
  used to forward window change signals to it.

`-window-system-unsupported'
  Signals that the server does not support creating X frames;
  the client must try again with a tty frame.

`-print STRING'
  Print STRING on stdout.  Used to send values
  returned by -eval.

`-print-nonl STRING'
  Print STRING on stdout.  Used to continue a
  preceding -print command that would be too big to send
  in a single message.

`-error DESCRIPTION'
  Signal an error and delete process PROC.

`-suspend'
  Suspend this terminal, i.e., stop the client process.
  Sent when the user presses \\[suspend-frame]."
  ;; Push this to the end of the list, so the list is in the order in which
  ;; we need to process it.
  ;; This implies an O(N²) worst-case, which is not good:
  ;; we should arguably use a "true" O(N) queue, but N is bounded by
  ;; the number of concurrent emacsclient requests, so we should hopefully
  ;; never see really large values of N.
  (setq server--process-filter-pending
        (nconc server--process-filter-pending (list (cons proc string))))
  ;; Since our process filter sometimes needs to wait with `sit-for',
  ;; we need to be careful to try and avoid nested process filters
  ;; eating up the stack, so we use `server--process-filter-active&pending'
  ;; to make sure our process filters are run in sequence rather than in
  ;; a nested way. (bug#71223)
  (unless server--process-filter-active
    (server--process-filter-all-pending)))