39.2 Invoking 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 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.