emacsclient, Up: Using Emacs as a Server [Contents][Index]
You can pass some optional arguments to the
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
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
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
(see Entering Emacs).
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.
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
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.
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.
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
server-name on the Emacs server. If this option is
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
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 Non-Window 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 over TCP (see TCP Emacs server). By ssh-forwarding the listening port 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’, and 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 EDITOR="emacsclient \ --server-file=server \ --tramp=/ssh:remote:" remote$ $EDITOR /tmp/foo.txt #Should open in local emacs.
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 (
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
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
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’.
emacsclient, Up: Using Emacs as a Server [Contents][Index]