Various programs can invoke your choice of editor to edit a
particular piece of text. For instance, version control programs
invoke an editor to enter version control logs (see Version Control), and the Unix mail utility invokes an editor to
enter a message to send. By convention, your choice of editor is
specified by the environment variable EDITOR. If you set
EDITOR to ‘emacs’, Emacs would be invoked, but in an
inconvenient way—by starting a new Emacs process. This is
inconvenient because the new Emacs process doesn’t share buffers, a
command history, or other kinds of information with any existing Emacs
process.
You can solve this problem by setting up Emacs as an edit server, so that it “listens” for external edit requests and acts accordingly. There are various ways to start an Emacs server:
server-start in an existing Emacs process:
either type M-x server-start, or put the expression
(server-start) in your init file (see The Emacs Initialization File). The
existing Emacs process is the server; when you exit Emacs, the server
dies with the Emacs process.
server-start after initialization and does not open an
initial frame. It then waits for edit requests from clients.
emacsclient with the ‘--alternate-editor=""’
command-line option. This starts an Emacs daemon only if no Emacs daemon
is already running.
systemd to manage startup,
you can automatically start Emacs in daemon mode when you login
using the supplied systemd unit file. To activate this:
systemctl --user enable emacs
(If your Emacs was installed into a non-standard location, you may need to copy the emacs.service file to a standard directory such as ~/.config/systemd/user/.)
systemd: the systemd service creates a socket and
listens for connections on it; when emacsclient connects to
it for the first time, systemd can launch the Emacs server
and hand over the socket to it for servicing emacsclient
connections. A setup to use this functionality could be:
~/.config/systemd/user/emacs.socket:
[Socket] ListenStream=/path/to/.emacs.socket DirectoryMode=0700 [Install] WantedBy=sockets.target
(The emacs.service file described above must also be installed.)
The ListenStream path will be the path that Emacs listens for
connections from emacsclient; this is a file of your choice.
Once an Emacs server is started, you can use a shell
command called emacsclient to connect to the Emacs process
and tell it to visit a file. You can then set the EDITOR
environment variable to ‘emacsclient’, so that external programs
will use the existing Emacs process for editing.32
You can run multiple Emacs servers on the same machine by giving
each one a unique server name, using the variable
server-name. For example, M-x set-variable RET
server-name RET "foo" RET sets the server name to
‘foo’. The emacsclient program can specify a server by
name, using the ‘-s’ or the ‘-f’ option (see emacsclient Options), depending on whether or not the server uses a TCP socket
(see TCP Emacs server).
If you want to run multiple Emacs daemons (see Initial Options), you can give each daemon its own server name like this:
emacs --daemon=foo
The Emacs server can optionally be stopped automatically when
certain conditions are met. To do this, set the option
server-stop-automatically to one of the following values:
emptyThis value causes the server to be stopped when it has no clients, no unsaved file-visiting buffers and no running processes anymore.
delete-frameThis value means that when the last client frame is being closed, you are asked whether each unsaved file-visiting buffer must be saved and each unfinished process can be stopped, and if so, the server is stopped.
kill-terminalThis value means that when the last client frame is being closed with
C-x C-c (save-buffers-kill-terminal), you are asked
whether each unsaved file-visiting buffer must be saved and each
unfinished process can be stopped, and if so, the server is stopped.
If you have defined a server by a unique server name, it is possible
to connect to the server from another Emacs instance and evaluate Lisp
expressions on the server, using the server-eval-at function.
For instance, (server-eval-at "foo" '(+ 1 2)) evaluates the
expression (+ 1 2) on the ‘foo’ server, and returns
3. (If there is no server with that name, an error is
signaled.) Currently, this feature is mainly useful for developers.
If your operating system’s desktop environment is
freedesktop.org-compatible
(which is true of most GNU/Linux and other recent Unix-like GUIs), you
may use the ‘Emacs (Client)’ menu entry to connect to an Emacs
server with emacsclient. The daemon starts if not
already running.
An Emacs server usually listens to connections on a local Unix
domain socket. Some operating systems, such as MS-Windows, do not
support local sockets; in that case, the server uses TCP sockets
instead. In some cases it is useful to have the server listen on a
TCP socket even if local sockets are supported, e.g., if you need to
contact the Emacs server from a remote machine. You can set
server-use-tcp to non-nil to have Emacs listen on a TCP
socket instead of a local socket. This is the default if your OS does
not support local sockets.
If the Emacs server is set to use TCP, it will by default listen on
a random port on the localhost interface. This can be changed to
another interface and/or a fixed port using the variables
server-host and server-port.
A TCP socket is not subject to file system permissions. To retain
some control over which users can talk to an Emacs server over TCP
sockets, the emacsclient program must send an authorization
key to the server. This key is normally randomly generated by the
Emacs server. This is the recommended mode of operation.
If needed, you can set the authorization key to a static value by
setting the server-auth-key variable. The key must consist of
64 ASCII printable characters except for space (this means characters
from ‘!’ to ‘~’, or from decimal code 33 to 126). You can
use M-x server-generate-key to get a random key.
When you start a TCP Emacs server, Emacs creates a server file
containing the TCP information to be used by emacsclient to
connect to the server. The variable server-auth-dir specifies
the default directory containing the server file; by default, this is
~/.emacs.d/server/. In the absence of a local socket with file
permissions, the permissions of this directory determine which users
can have their emacsclient processes talk to the Emacs
server. If server-name is an absolute file name, the server
file is created where specified by that file name.
To tell emacsclient to connect to the server over TCP with
a specific server file, use the ‘-f’ or ‘--server-file’
option, or set the EMACS_SERVER_FILE environment variable
(see emacsclient Options). If server-auth-dir is set to a
non-standard value, or if server-name is set to an absolute
file name, emacsclient needs an absolute file name to the
server file, as the default server-auth-dir is hard-coded in
emacsclient to be used as the directory for resolving
relative filenames.
emacsclient ¶The 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 use
‘-c’ to open multiple frames using X forwarding you may wish to
disable single-keyboard mode. See Multiple Displays.
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.
emacsclient Options ¶You can pass some optional arguments to the emacsclient
program, such as:
emacsclient -c +12 file1 +4:3 file2
The ‘+line’ or ‘+line:column’ arguments specify line numbers, or line and column numbers, for the next file argument. These behave like the command line arguments for Emacs itself. See Action Arguments.
The other optional arguments recognized by emacsclient are
listed below:
Specify a shell command to run if emacsclient fails to
contact Emacs. This is useful when running emacsclient in a
script. The command may include arguments, which may be quoted "like
this". Currently, escaping of quotes is not supported.
As a special exception, if command is the empty string, then
emacsclient starts Emacs in daemon mode (as ‘emacs
--daemon’) and then tries connecting again.
The environment variable ALTERNATE_EDITOR has the same effect as
the ‘-a’ option. If both are present, the latter takes
precedence.
Create a new graphical client frame, instead of using an existing Emacs frame. See below for the special behavior of C-x C-c in a client frame. If Emacs cannot create a new graphical frame (e.g., if it cannot connect to the X server), it tries to create a text terminal client frame, as though you had supplied the ‘-t’ option instead.
On MS-Windows, a single Emacs session cannot display frames on both graphical and text terminals, nor on multiple text terminals. Thus, if the Emacs server is running on a text terminal, the ‘-c’ option, like the ‘-t’ option, creates a new frame in the server’s current text terminal. See How to Start Emacs on MS-Windows.
If you omit a filename argument while supplying the ‘-c’ option,
the new frame displays the *scratch* buffer by default. You
can customize this behavior with the variable initial-buffer-choice
(see Entering Emacs).
Create a new graphical client frame if none exists, otherwise use an existing Emacs frame.
Set the parameters for a newly-created graphical frame (see Frame Parameters).
Tell Emacs to open the given files on the X display display (assuming there is more than one X display available).
Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some
files. When this option is given, the arguments to
emacsclient are interpreted as a list of expressions to
evaluate, not as a list of files to visit.
Passing complex Lisp expression via the --eval command-line
option sometimes requires elaborate escaping of characters special to
the shell. To avoid this, you can pass arguments to Lisp functions in
your expression as additional separate arguments to
emacsclient, and use server-eval-args-left in the
expression to access those arguments. If empty string arguments are
passed to emacsclient, those are included as well. Be careful
to have your expression remove the processed arguments from
server-eval-args-left regardless of whether your code succeeds,
for example by using pop, otherwise Emacs will attempt to
evaluate those arguments as separate Lisp expressions.
Specify a server file (see TCP Emacs server) for connecting to an
Emacs server via TCP. Alternatively, you can set the
EMACS_SERVER_FILE environment variable to point to the server
file. (The command-line option overrides the environment variable.)
An Emacs server usually uses a local socket to listen for connections,
but also supports connections over TCP. To connect to a TCP Emacs
server, emacsclient needs to read a server file
containing the connection details of the Emacs server. The name of
this file is specified with this option, either as a file name
relative to ~/.emacs.d/server or as an absolute file name.
See TCP Emacs server.
Let emacsclient exit immediately, instead of waiting until
all server buffers are finished. You can take as long as you like to
edit the server buffers within Emacs, and they are not killed
when you type C-x # in them.
Wait for a response from Emacs for N seconds before giving up.
If there is no response within that time, emacsclient will
display a warning and exit. The default is ‘0’, which means to
wait forever.
Open an emacsclient frame as a client frame in the parent X
window with id id, via the XEmbed protocol. Currently, this
option is mainly useful for developers.
Do not let emacsclient display messages about waiting for
Emacs or connecting to remote server sockets.
Do not let emacsclient display results returned from the
server. Mostly useful in combination with ‘-e’ when the
evaluation performed is for side-effect rather than result.
Connect to the Emacs server named server-name. (This option is
not supported on MS-Windows.) The server name is given by the
variable server-name on the Emacs server. If this option is
omitted, emacsclient connects to the default socket.
If you set server-name of the Emacs server to an absolute file
name, give the same absolute file name as server-name to this
option to instruct emacsclient to connect to that server.
You need to use this option if you started Emacs as daemon
(see Initial Options) and specified the name for the server
started by the daemon.
Alternatively, you can set the EMACS_SOCKET_NAME environment
variable to point to the server socket. (The command-line option
overrides the environment variable.)
Create a new client frame on the current text terminal, instead of using an existing Emacs frame. This behaves just like the ‘-c’ option, described above, except that it creates a text terminal frame (see Text Terminals).
On MS-Windows, ‘-t’ behaves just like ‘-c’ if the Emacs server is using the graphical display, but if the Emacs server is running on a text terminal, it creates a new frame in the current text terminal.
Set the prefix to add to filenames for Emacs to locate files on remote
machines (see Remote Files) using TRAMP (see The Tramp
Manual in The Tramp Manual). This is mostly useful in
combination with using the Emacs server from a remote host. By
ssh-forwarding the listening socket, or ssh-forwarding the listening
port see TCP Emacs server and making the
server-file available on a remote machine, programs on the
remote machine can use emacsclient as the value for the
EDITOR and similar environment variables, but instead of talking
to an Emacs server on the remote machine, the files will be visited in
the local Emacs session using TRAMP.
Setting the environment variable EMACSCLIENT_TRAMP has the same
effect as using the ‘-T’ option. If both are specified, the
command-line option takes precedence.
For example, assume two hosts, ‘local’ and ‘remote’.
local$ ssh -R "/home/%r/.emacs.socket":"${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}/emacs%i}${XDG_RUNTIME_DIR:+/emacs}/server" remote
remote$ export EMACS_SOCKET_NAME=$HOME/.emacs.socket
remote$ export EMACSCLIENT_TRAMP=/ssh:remote:
remote$ export EDITOR=emacsclient
remote$ $EDITOR /tmp/foo.txt #Should open in local emacs.
If you are using a platform where emacsclient does not use
Unix domain sockets (i.e., MS-Windows), or your SSH implementation is
not able to forward them (e.g., OpenSSH before version 6.7), you can
forward a TCP port instead. In this example, assume that the local
Emacs listens on tcp port 12345. Assume further that
/home is on a shared file system, so that the server file
~/.emacs.d/server/server is readable on both hosts.
local$ ssh -R12345:localhost:12345 remote remote$ export EMACS_SERVER_FILE=server remote$ export EMACSCLIENT_TRAMP=/ssh:remote: remote$ export EDITOR=emacsclient remote$ $EDITOR /tmp/foo.txt #Should open in local emacs.
Print version information and exit.
Print usage information message and exit.
The new graphical or text terminal frames created by the ‘-c’
or ‘-t’ options are considered client frames. Any new
frame that you create from a client frame is also considered a client
frame. If you type C-x C-c (save-buffers-kill-terminal)
in a client frame, that command does not kill the Emacs session as it
normally does (see Exiting Emacs). Instead, Emacs deletes the client
frame; furthermore, if the client frame has an emacsclient
waiting to regain control (i.e., if you did not supply the ‘-n’
option), Emacs deletes all other frames of the same client, and marks
the client’s server buffers as finished, as though you had typed
C-x # in all of them. If it so happens that there are no
remaining frames after the client frame(s) are deleted, the Emacs
session exits.
As an exception, when Emacs is started as a daemon, all frames are considered client frames, and C-x C-c never kills Emacs. To kill a daemon session, type M-x kill-emacs.
Note that the ‘-t’ and ‘-n’ options are contradictory: ‘-t’ says to take control of the current text terminal to create a new client frame, while ‘-n’ says not to take control of the text terminal. If you supply both options, Emacs visits the specified files(s) in an existing frame rather than a new client frame, negating the effect of ‘-t’.
Some
programs use a different environment variable; for example, to make
TeX use ‘emacsclient’, set the TEXEDIT environment
variable to ‘emacsclient +%d %s’.