Previous: Invoking emacsclient, Up: Emacs Server
emacsclient
OptionsYou 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:
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.
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 Windows Startup.
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).
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.
server-name
on the Emacs server. If this option is
omitted, emacsclient connects to the first server it finds.
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.
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.
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 (save-buffers-kill-terminal
)
in a client frame, that command does not kill the Emacs session as it
normally does (see Exiting). 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’.