Commit 8cec98c0 authored by Chong Yidong's avatar Chong Yidong
Browse files

(Emacs Server): Rewrite. Document daemon-mode. Don't

mention obsolete emacs.bash script.
(Invoking emacsclient): Rewrite, moving optional arguments to
emacsclient Options.
(emacsclient Options): New node.
parent c409d2f3
......@@ -1270,68 +1270,44 @@ window.
@cindex server, using Emacs as
@cindex @env{EDITOR} environment variable
Various programs such as @code{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 @env{EDITOR} to specify which editor to run. If you set
@env{EDITOR} to @samp{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 @code{mail} by using the Emacs client program and the
server that is part of Emacs. Here is how.
Various programs such as @command{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 @env{EDITOR} to specify which editor to run. If
you set @env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
inconvenient way, by starting a new Emacs process. This is
inconvenient because the new Emacs process doesn't share buffers, a
command history, or other kinds of information with any existing Emacs
process.
You can solve this problem by setting up Emacs as an @dfn{edit
server}, so that it ``listens'' for external edit requests and acts
accordingly. There are two ways to start an Emacs server:
@cindex @env{TEXEDIT} environment variable
@findex server-start
First, the preparations. Within Emacs, call the function
@code{server-start}. (Your @file{.emacs} init file can do this
automatically if you add the expression @code{(server-start)} to it,
see @ref{Init File}.) Then, outside Emacs, set the @env{EDITOR}
environment variable to @samp{emacsclient}. (Note that some programs
use a different environment variable; for example, to make @TeX{} use
@samp{emacsclient}, you should set the @env{TEXEDIT} environment
variable to @samp{emacsclient +%d %s}.)
@pindex emacs.bash
@cindex Bash command to use Emacs server
As an alternative to using @code{emacsclient}, the file
@file{etc/emacs.bash} defines a Bash command @code{edit} which will
communicate with a running Emacs session, or start one if none exist.
@kindex C-x #
@findex server-edit
Now, whenever any program invokes your specified @env{EDITOR}
program, the effect is to send a message to your principal Emacs telling
it to visit a file. (That's what the program @code{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 @kbd{C-x #}
(@code{server-edit}). This saves the file and sends a message back to
the @code{emacsclient} program telling it to exit. The programs that
use @env{EDITOR} wait for the ``editor'' (actually, @code{emacsclient})
to exit. @kbd{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 @kbd{C-x #}. But @kbd{C-x #} is the way to
say that you are finished with one.
@vindex server-kill-new-buffers
@vindex server-temp-file-regexp
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 @code{server-kill-new-buffers} to @code{nil},
then a different criterion is used: finishing with a server buffer
kills it if the file name matches the regular expression
@code{server-temp-file-regexp}. This is set up to distinguish certain
``temporary'' files.
The first is to run the command @code{server-start} in an existing
Emacs process: either type @kbd{M-x server-start}, or put the
expression @code{(server-start)} in your initialization file
(@pxref{Init File}). The existing Emacs process is the server; when
you exit Emacs, the server dies with the Emacs process.
@cindex daemon, Emacs
The second way to start an Emacs server is to run Emacs as a
@dfn{daemon}, using the @samp{--daemon} command-line option.
@xref{Initial Options}. When Emacs is started this way, it calls
@code{server-start} after initialization, and returns control to the
calling terminal instead of opening an initial frame; it then waits in
the background, listening for edit requests.
@vindex server-window
If you set the variable @code{server-window} to a window or a frame,
@kbd{C-x #} displays the server buffer in that window or in that frame.
@cindex @env{TEXEDIT} environment variable
Once an Emacs server is set up, you can use a shell command called
@command{emacsclient} to connect to the existing Emacs process and
tell it to visit a file. If you set the @env{EDITOR} environment
variable to @samp{emacsclient}, programs such as @command{mail} will
use the existing Emacs process for editing.@footnote{Some programs use
a different environment variable; for example, to make @TeX{} use
@samp{emacsclient}, set the @env{TEXEDIT} environment variable to
@samp{emacsclient +%d %s}.}
@vindex server-name
You can run multiple Emacs servers on the same machine by giving
......@@ -1339,78 +1315,99 @@ each one a unique ``server name'', using the variable
@code{server-name}. For example, @kbd{M-x set-variable @key{RET}
server-name @key{RET} foo @key{RET}} sets the server name to
@samp{foo}. The @code{emacsclient} program can specify a server by
name using the @samp{-s} option. @xref{Invoking emacsclient}.
name, using the @samp{-s} option (@pxref{emacsclient Options}).
While @code{mail} or another application is waiting for
@code{emacsclient} to finish, @code{emacsclient} does not read terminal
input. So the terminal that @code{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:
@menu
* Invoking emacsclient:: Connecting to the Emacs server.
* emacsclient Options:: Emacs client startup options.
@end menu
@itemize @bullet
@item
Using a window system, run @code{mail} and the principal Emacs in two
separate windows. While @code{mail} is waiting for @code{emacsclient},
the window where it was running is blocked, but you can use Emacs by
switching windows.
@node Invoking emacsclient
@subsection Invoking @code{emacsclient}
@cindex @code{emacsclient} invocation
The simplest way to use the @command{emacsclient} program is to run
the shell command @samp{emacsclient @var{file}}, where @var{file} is a
file name. This connects to an Emacs server, and tells that Emacs
process to visit @var{file} in one of its existing frames---either a
graphical frame, or one in a text-only terminal (@pxref{Frames}). You
can then select that frame to begin editing.@footnote{Or, if you are
running the Emacs server's process on a separate virtual text-only
terminal, switch to that virtual terminal.}
If there is no Emacs server, the @command{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 (@pxref{Emacs
Server})---the above usage does not work; you need to use the
@samp{-c} or @samp{-t} option to tell Emacs to create a new frame.
@xref{emacsclient Options}.
@item
Using virtual terminals, run @code{mail} in one virtual terminal
and run Emacs in another.
@kindex C-x #
@findex server-edit
When you finish editing @var{file}, type @kbd{C-x #}
(@code{server-edit}) in its buffer. This saves the file and sends a
message back to the @command{emacsclient} program, telling it to exit.
Programs that use @env{EDITOR} usually wait for the ``editor''---in
the case @command{emacsclient}---to exit before doing something else.
You can also call @command{emacsclient} with multiple file name
arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the
Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs
selects the buffer visiting @var{file1}, and buries the other buffers
at the bottom of the buffer list (@pxref{Buffers}). The
@command{emacsclient} program exits once all the specified files are
finished (i.e., once you have typed @kbd{C-x #} in each server
buffer).
@item
Use Shell mode or Term mode in Emacs to run the other program such as
@code{mail}; then, @code{emacsclient} blocks only the subshell under
Emacs, and you can still use Emacs to edit the file.
@end itemize
@vindex server-kill-new-buffers
@vindex server-temp-file-regexp
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 @code{server-kill-new-buffers} to
@code{nil}, then a different criterion is used: finishing with a
server buffer kills it if the file name matches the regular expression
@code{server-temp-file-regexp}. This is set up to distinguish certain
``temporary'' files.
If you run @code{emacsclient} with the option @samp{--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.
Each @kbd{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 @kbd{C-x #}. But @kbd{C-x #} is the way to tell
@command{emacsclient} that you are finished.
@menu
* Invoking emacsclient:: Emacs client startup options.
@end menu
@vindex server-window
If you set the variable @code{server-window} to a window or a frame,
@kbd{C-x #} always displays the next server buffer in that window or
in that frame.
@node Invoking emacsclient,, Emacs Server, Emacs Server
@subsection Invoking @code{emacsclient}
@cindex @code{emacsclient} invocation and options
@node emacsclient Options
@subsection @code{emacsclient} Options
@cindex @code{emacsclient} options
To run the @code{emacsclient} program, specify file names as arguments,
and optionally line numbers as well, like this:
You can pass some optional arguments to the @command{emacsclient}
program, such as:
@example
emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@}}@dots{}
emacsclient -c +12 @var{file1} +4:3 @var{file2}
@end example
@noindent
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, @code{emacsclient} does not return until you use the
@kbd{C-x #} command on each of these buffers. When that happens,
Emacs sends a message to the @code{emacsclient} program telling it to
return.
If you invoke @code{emacsclient} for more than one file, the
additional client buffers are buried at the bottom of the buffer list
(@pxref{Buffers}). If you call @kbd{C-x #} after you are done editing
a client buffer, the next client buffer is automatically selected.
But if you use the option @samp{-n} or @samp{--no-wait} when running
@code{emacsclient}, then it returns immediately. (You can take as
long as you like to edit the files in Emacs.)
The option @samp{-a @var{command}} or
@samp{--alternate-editor=@var{command}} specifies a command to run if
@code{emacsclient} fails to contact Emacs. This is useful when
running @code{emacsclient} in a script. For example, the following
setting for the @env{EDITOR} environment variable will always give you
an editor, even if no Emacs server is running:
The @samp{+@var{linenum}} or @samp{+@var{linenum}:@var{columnnum}}
arguments specify line numbers, or line and column numbers, for the
next file argument. These behave like the command line arguments for
Emacs itself. @xref{Action Arguments}.
The other optional arguments recognized by @command{emacsclient} are
listed below:
@table @samp
@item -a @var{command}
@itemx --alternate-editor=@var{command}
Specify a command to run if @code{emacsclient} fails to contact Emacs.
This is useful when running @code{emacsclient} in a script. For
example, the following setting for the @env{EDITOR} environment
variable will always give you an editor, even if no Emacs server is
running:
@example
EDITOR="emacsclient --alternate-editor emacs +%d %s"
......@@ -1418,40 +1415,89 @@ EDITOR="emacsclient --alternate-editor emacs +%d %s"
@noindent
@cindex @env{ALTERNATE_EDITOR} environment variable
The environment variable @env{ALTERNATE_EDITOR} has the same effect, with
the value of the @samp{--alternate-editor} option taking precedence.
If you use several displays, you can tell Emacs on which display to
open the given files with the @samp{-d @var{display}} or
@samp{--display=@var{display}} option to @code{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 @samp{-s @var{name}} or
@samp{--socket-name=@var{name}} option to @code{emacsclient}. (This
option is not supported on MS-Windows.)
You can also use @code{emacsclient} to execute any piece of Emacs Lisp
code, using the @samp{-e} or @samp{--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.
The environment variable @env{ALTERNATE_EDITOR} has the same effect,
with the value of the @samp{--alternate-editor} option taking
precedence.
@item -c
Create a new graphical frame, instead of using an existing Emacs
frame. Note that 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 (@pxref{Frames}). If you omit
a filename argument while supplying the @samp{-c} option, the new
frame displays the @samp{*scratch*} buffer (@pxref{Buffers}).
@item -d @var{display}
@itemx --display=@var{display}
Tell Emacs to open the given files on the X display @var{display}
(assuming there is more than one X display available).
@item -e
@itemx --eval
Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some
files. When this option is given, the arguments to
@command{emacsclient} are interpreted as a list of expressions to
evaluate, @emph{not} as a list of files to visit.
@item -f @var{server-file}
@itemx --server-file=@var{server-file}
@cindex @env{EMACS_SERVER_FILE} environment variable
When you start the Emacs server (by calling @code{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. @code{emacsclient} uses this
information if it needs to connect to the server via TCP. By default,
the file goes in the @file{~/.emacs.d/server/} directory@footnote{On
MS-Windows, if @env{HOME} is not set or the TCP configuration file
cannot be found there, Emacs also looks for the file in the
@file{.emacs.d/server/} subdirectory of the directory pointed to by
the @env{APPDATA} environment variable.}. You can specify the file
name to use with the @samp{-f @var{file}} or
@samp{--server-file=@var{file}} options, or by setting
@cindex server file
Specify a @dfn{server file} for connecting to an Emacs server via TCP.
Usually, an Emacs server 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 (by calling
@code{server-start}), Emacs creates a server file that contains some
TCP connection information. @command{emacsclient} needs this
information to make the connection. By default, the file goes in the
@file{~/.emacs.d/server/}; on Microsoft Windows, if @env{HOME} is not
set or the TCP configuration file cannot be found there, Emacs also
looks for the file in the @file{.emacs.d/server/} subdirectory of the
directory pointed to by the @env{APPDATA} environment variable. You
can specify a server file to use with the @samp{-f @var{server-file}}
or @samp{--server-file=@var{server-file}} option, or by setting
@env{EMACS_SERVER_FILE} environment variable to the file name.
@item -n
@itemx --no-wait
Let @command{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 @emph{not} killed
when you type @kbd{C-x #} in them.
@item -s @var{server-name}
@itemx --socket-name=@var{server-name}
Connect to the Emacs server named @var{server-name}. The server name
is given by the variable @code{server-name} on the Emacs server. If
this option is omitted, @command{emacsclient} connects to the first
server it finds. (This option is not supported on MS-Windows.)
@item -t
@itemx --tty
@itemx -nw
Create a new Emacs frame on the current text-only terminal, instead of
using an existing Emacs frame. Note that 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
@samp{*scratch*} buffer. @xref{Buffers}.
@end table
If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) in an
Emacs frame created with @command{emacsclient}, via the @samp{-c} or
@samp{-t} options, Emacs deletes the frame instead of killing the
Emacs process itself. On a text-only terminal frame created with the
@samp{-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 @kbd{C-x #} in all of them.
When Emacs is started as a daemon, all frames are considered client
frames, so @kbd{C-x C-c} will never kill Emacs. To kill the Emacs
process, type @kbd{M-x kill-emacs}.
@node Printing, Sorting, Emacs Server, Top
@section Printing Hard Copies
@cindex hardcopy
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment