Next: emacsclient Options, Up: Emacs Server [Contents][Index]

### 41.1 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). You can then select that frame to begin editing.

If there is no Emacs server, the `emacsclient` program halts with an error message. If the Emacs process has no existing frame—which can happen if it was started as a daemon (see Emacs 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, or on a text terminal, using the ‘`-c`’ and ‘`-t`’ options. 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 Shell) 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.

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

Next: emacsclient Options, Up: Emacs Server [Contents][Index]