42.2 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:

‘-a command’

‘--alternate-editor=command’

Specify a command to run if emacsclient fails to contact Emacs. This is useful when running emacsclient in a script. For example, the following setting for the EDITOR environment variable will always give you an editor, even if no Emacs server is running:

          EDITOR="emacsclient --alternate-editor emacs +%d %s"

As a special exception, if command is the empty string, then emacsclient starts Emacs in daemon mode 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.

‘-c’

Create a new graphical frame, instead of using an existing Emacs frame. Emacs 23 can create a graphical frame even if it was started in a text-only terminal, provided it is able to connect to a graphical display. If no graphical display is available, Emacs creates a new text-only terminal frame (see Frames). If you omit a filename argument while supplying the ‘-c’ option, the new frame displays the ‘*scratch*’ buffer (see Buffers).

‘-d display’

‘--display=display’

Tell Emacs to open the given files on the X display display (assuming there is more than one X display available).

‘-e’

‘--eval’

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.

‘-f server-file’

‘--server-file=server-file’

Specify a server file for connecting to an Emacs server via TCP.

An Emacs server usually uses an operating system feature called a “local socket” to listen for connections. Some operating systems, such as Microsoft Windows, do not support local sockets; in that case, Emacs uses TCP instead. When you start the Emacs server, Emacs creates a server file containing some TCP information that emacsclient needs for making the connection. By default, the server file is in ~/.emacs.d/server/. On Microsoft Windows, if emacsclient does not find the server file there, it looks in the .emacs.d/server/ subdirectory of the directory pointed to by the APPDATA environment variable. You can tell emacsclient to use a specific server file with the ‘-f’ or ‘--server-file’ option, or by setting the EMACS_SERVER_FILE environment variable.

Even if local sockets are available, you can tell Emacs to use TCP by setting the variable server-use-tcp to t. One advantage of TCP is that the server can accept connections from remote machines. For this to work, you must (i) set the variable server-host to the hostname or IP address of the machine on which the Emacs server runs, and (ii) provide emacsclient with the server file. (One convenient way to do the latter is to put the server file on a networked file system such as NFS.)

‘-n’

‘--no-wait’

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.

‘-s server-name’

‘--socket-name=server-name’

Connect to the Emacs server named server-name. The server name is given by the variable server-name on the Emacs server. If this option is omitted, emacsclient connects to the first server it finds. (This option is not supported on MS-Windows.)

‘-t’

‘--tty’

‘-nw’

Create a new Emacs frame on the current text-only terminal, instead of using an existing Emacs frame. Emacs 23 can open a text-only terminal even if it was started in another text-only terminal, or on a graphical display. If you omit a filename argument while supplying this option, the new frame displays the ‘*scratch*’ buffer. See Buffers.

If you type C-x C-c (save-buffers-kill-terminal) in an Emacs frame created with emacsclient, via the ‘-c’ or ‘-t’ options, Emacs deletes the frame instead of killing the Emacs process itself. On a text-only terminal frame created with the ‘-t’ option, this returns control to the terminal. Emacs also marks all the server buffers for the client as finished, as though you had typed C-x # in all of them.

When Emacs is started as a daemon, all frames are considered client frames, so C-x C-c will never kill Emacs. To kill the Emacs process, type M-x kill-emacs.