emacsclientThe simplest way to use the emacsclient program is to run
the shell command ‘emacsclient file’, where file is a
file name. This connects to an Emacs server, and tells that Emacs
process to visit file in one of its existing frames—either a
graphical frame, or one in a text terminal (see Frames and Graphical Displays). You
can then select that frame to begin editing.
If there is no Emacs server, the emacsclient program halts
with an error message (you can prevent this from happening by using
the ‘--alternate-editor=""’ option to emacsclient,
see emacsclient Options). If the Emacs process has no existing
frame—which can happen if it was started as a daemon (see Using Emacs as a Server)—then Emacs opens a frame on the terminal in which you
called emacsclient.
You can also force emacsclient to open a new frame on a
graphical display using the ‘-c’ option, or on a text terminal
using the ‘-t’ option. See emacsclient Options.
If you are running on a single text terminal, you can switch between
emacsclient’s shell and the Emacs server using one of two
methods: (i) run the Emacs server and emacsclient on
different virtual terminals, and switch to the Emacs server’s virtual
terminal after calling emacsclient; or (ii) call
emacsclient from within the Emacs server itself, using Shell
mode (see Interactive Subshell) or Term mode (see Term Mode);
emacsclient blocks only the subshell under Emacs, and you can
still use Emacs to edit the file.
When you finish editing file in the Emacs server, type
C-x # (server-edit) in its buffer. This saves the file
and sends a message back to the emacsclient program, telling
it to exit. Programs that use EDITOR usually wait for the
editor—in this case emacsclient—to exit before doing
something else.
If you want to abandon the edit instead, use the M-x server-edit-abort command. This sends a message back to the
emacsclient program, telling it to exit with abnormal exit
status, and doesn’t save any buffers.
You can also call emacsclient with multiple file name
arguments: ‘emacsclient file1 file2 ...’ tells the
Emacs server to visit file1, file2, and so forth. Emacs
selects the buffer visiting file1, and buries the other buffers
at the bottom of the buffer list (see Using Multiple Buffers). The
emacsclient program exits once all the specified files are
finished (i.e., once you have typed C-x # in each server
buffer).
Finishing with a server buffer also kills the buffer, unless it
already existed in the Emacs session before the server was asked to
create it. However, if you set server-kill-new-buffers to
nil, then a different criterion is used: finishing with a
server buffer kills it if the file name matches the regular expression
server-temp-file-regexp. This is set up to distinguish certain
temporary files.
Each C-x # checks for other pending external requests to edit
various files, and selects the next such file. You can switch to a
server buffer manually if you wish; you don’t have to arrive at it
with C-x #. But C-x # is the way to tell
emacsclient that you are finished.
If you set the value of the variable server-window to a
window or a frame, C-x # always displays the next server buffer
in that window or in that frame.
When emacsclient connects, the server will normally output
a message that says how to exit the client frame. If
server-client-instructions is set to nil, this message
is inhibited.