# HG changeset patch # User Chong Yidong # Date 1225256397 0 # Node ID 2d047ab6bc3e84f57c909845c42ae7d61b346543 # Parent a29f27ad97a5bb625856a451704ab8890ff5a5d8 (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. diff -r a29f27ad97a5 -r 2d047ab6bc3e doc/emacs/misc.texi --- a/doc/emacs/misc.texi Wed Oct 29 04:57:56 2008 +0000 +++ b/doc/emacs/misc.texi Wed Oct 29 04:59:57 2008 +0000 @@ -1270,68 +1270,44 @@ @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: + +@findex server-start + 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. @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. - -@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. + 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 @@ @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}. - - 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: - -@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. - -@item -Using virtual terminals, run @code{mail} in one virtual terminal -and run Emacs in another. - -@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 - - 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. +name, using the @samp{-s} option (@pxref{emacsclient Options}). @menu -* Invoking emacsclient:: Emacs client startup options. +* Invoking emacsclient:: Connecting to the Emacs server. +* emacsclient Options:: Emacs client startup options. @end menu -@node Invoking emacsclient,, Emacs Server, Emacs Server +@node Invoking emacsclient @subsection Invoking @code{emacsclient} -@cindex @code{emacsclient} invocation and options - - To run the @code{emacsclient} program, specify file names as arguments, -and optionally line numbers as well, like this: +@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}. + +@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). + +@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. + + 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. + +@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 emacsclient Options +@subsection @code{emacsclient} Options +@cindex @code{emacsclient} options + + 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 @@ @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