42. Using Emacs as a Server

Various programs such as mail can invoke your choice of editor to edit a particular piece of text, such as a message that you are sending. By convention, most of these programs use the environment variable EDITOR to specify which editor to run. If you set EDITOR to `emacs', they invoke Emacs--but in an inconvenient fashion, by starting a new, separate Emacs process. This is inconvenient because it takes time and because the new Emacs process doesn't share the buffers with any existing Emacs process.

You can arrange to use your existing Emacs process as the editor for programs like mail by using the Emacs client program and the server that is part of Emacs. Here is how.

First, the preparations. Within Emacs, call the function server-start. (Your `.emacs' init file can do this automatically if you add the expression (server-start) to it, see The Init File, `~/.emacs'.) Then, outside Emacs, set the EDITOR environment variable to `emacsclient'. (Note that some programs use a different environment variable; for example, to make TeX use `emacsclient', you should set the TEXEDIT environment variable to `emacsclient +%d %s'.)

As an alternative to using emacsclient, the file `etc/emacs.bash' defines a Bash command edit which will communicate with a running Emacs session, or start one if none exist.

Now, whenever any program invokes your specified EDITOR program, the effect is to send a message to your principal Emacs telling it to visit a file. (That's what the program emacsclient does.) Emacs displays the buffer immediately and you can immediately begin editing it in the already running Emacs session.

When you've finished editing that buffer, type C-x # (server-edit). This saves the file and sends a message back to the emacsclient program telling it to exit. The programs that use EDITOR wait for the "editor" (actually, emacsclient) to exit. C-x # also 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 say that you are finished with one.

Finishing with a server buffer also kills the buffer, unless it already existed in the Emacs session before the server 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.

If you set the variable server-window to a window or a frame, C-x # displays the server buffer in that window or in that frame.

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' option. See section Invoking emacsclient.

While mail or another application is waiting for emacsclient to finish, emacsclient does not read terminal input. So the terminal that mail was using is effectively blocked for the duration. In order to edit with your principal Emacs, you need to be able to use it without using that terminal. There are three ways to do this:

Using a window system, run mail and the principal Emacs in two separate windows. While mail is waiting for emacsclient, the window where it was running is blocked, but you can use Emacs by switching windows.
Using virtual terminals, run mail in one virtual terminal and run Emacs in another.
Use Shell mode or Term mode in Emacs to run the other program such as mail; then, emacsclient blocks only the subshell under Emacs, and you can still use Emacs to edit the file.

If you run emacsclient with the option `--no-wait', it returns immediately without waiting for you to "finish" the buffer in Emacs. Note that server buffers created in this way are not killed automatically when you finish with them.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

42.1 Invoking `emacsclient`

To run the emacsclient program, specify file names as arguments, and optionally line numbers as well, like this:

emacsclient {[+line[column]] filename}…

This tells Emacs to visit each of the specified files; if you specify a line number for a certain file, Emacs moves to that line in the file. If you specify a column number as well, Emacs puts point on that column in the line.

Ordinarily, emacsclient does not return until you use the C-x # command on each of these buffers. When that happens, Emacs sends a message to the emacsclient program telling it to return.

If you invoke emacsclient for more than one file, the additional client buffers are buried at the bottom of the buffer list (see section Using Multiple Buffers). If you call C-x # after you are done editing a client buffer, the next client buffer is automatically selected.

But if you use the option `-n' or `--no-wait' when running emacsclient, then it returns immediately. (You can take as long as you like to edit the files in Emacs.)

The option `-a command' or `--alternate-editor=command' specifies 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"

The environment variable ALTERNATE_EDITOR has the same effect, with the value of the `--alternate-editor' option taking precedence.

If you use several displays, you can tell Emacs on which display to open the given files with the `-d display' or `--display=display' option to emacsclient. This is handy when connecting from home to an Emacs session running on your machine at your workplace.

If there is more than one Emacs server running, you can specify a server name with the `-s name' or `--socket-name=name' option to emacsclient. (This option is not supported on MS-Windows.)

You can also use emacsclient to execute any piece of Emacs Lisp code, using the `-e' or `--eval' option. When this option is given, the rest of the arguments is interpreted as a list of expressions to evaluate, not a list of files to visit.

When you start the Emacs server (by calling server-start), Emacs creates a file with information about TCP connection to the server: the host where Emacs is running, the port where it is listening, and an authentication string. emacsclient uses this information if it needs to connect to the server via TCP. By default, the file goes in the `~/.emacs.d/server/' directory(19). You can specify the file name to use with the `-f file' or `--server-file=file' options, or by setting EMACS_SERVER_FILE environment variable to the file name.