GNU Info

(emacs)Emacs Server

---

Next: Hardcopy Prev: Shell Up: Top

---

Enter node , (file) or (file)node

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 in 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 and Emacs server
programs.  Here is how.

   First, the preparation.  Within Emacs, call the function
`server-start'.  (Your `.emacs' file can do this automatically if you
add the expression `(server-start)' to it.)  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'.)

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

   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.

   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.

Invoking emacsclient