200 lines
6.5 KiB
Groff
200 lines
6.5 KiB
Groff
.\" See section COPYING for conditions for redistribution.
|
|
.TH EMACSCLIENT 1 "2024-08-20" "GNU Emacs" "GNU"
|
|
.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
|
|
.\" other params are allowed: see man(7), man(1)
|
|
.SH NAME
|
|
emacsclient \- tells a running Emacs to visit a file
|
|
.SH SYNOPSIS
|
|
.B emacsclient
|
|
.I "[options] files ..."
|
|
.SH "DESCRIPTION"
|
|
This manual page documents briefly the
|
|
.BR emacsclient
|
|
command. Full documentation is available in the GNU Info format; see
|
|
below.
|
|
.PP
|
|
.B emacsclient
|
|
works in conjunction with the built-in Emacs server.
|
|
.PP
|
|
You can either call
|
|
.B emacsclient
|
|
directly or let other programs run it for you when necessary. On
|
|
GNU and Unix systems many programs consult the environment
|
|
variable EDITOR (sometimes also VISUAL) to obtain the command used for
|
|
editing. Thus, setting this environment variable to 'emacsclient'
|
|
will allow these programs to use an already running Emacs for editing.
|
|
Other operating systems might have their own methods for defining the
|
|
default editor.
|
|
|
|
For
|
|
.B emacsclient
|
|
to work, you need an already running Emacs with a server. Within Emacs,
|
|
call the functions "server-start" or "server-mode". (Your ".emacs" file
|
|
can do this automatically if you add either "(server-start)" or
|
|
"(server-mode 1)" to it.)
|
|
|
|
When you've finished editing the buffer, type "C-x #"
|
|
("server-edit"). This saves the file and sends a message back to the
|
|
.B emacsclient
|
|
program telling it to exit. The programs that use
|
|
EDITOR wait for the "editor" (actually,
|
|
.BR emacsclient )
|
|
to exit. "C-x #" also checks for other pending external requests to
|
|
edit various
|
|
files, and selects the next such file.
|
|
|
|
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.
|
|
|
|
.SH OPTIONS
|
|
Most options follow the usual GNU command line syntax, with long
|
|
options starting with two dashes ("\-").
|
|
.TP
|
|
.BI + line\fR[\fP\fB:\fPcolumn\fR]\fP
|
|
Go to the specified
|
|
.I line
|
|
and
|
|
.IR column .
|
|
A missing
|
|
.I column
|
|
is treated as column 1.
|
|
This option applies only to the next file specified.
|
|
.TP
|
|
.B \-a, \-\-alternate-editor=COMMAND
|
|
If the Emacs server is not running, run the specified shell command instead.
|
|
If the empty string is specified, run "emacs \-\-daemon" to
|
|
start Emacs in daemon mode, and try to connect to it.
|
|
|
|
See also the ALTERNATE_EDITOR environment variable, over which this
|
|
option takes precedence.
|
|
.TP
|
|
.B -c, \-\-create-frame
|
|
Create a new frame instead of trying to use the current Emacs frame.
|
|
.TP
|
|
.B -r \-\-reuse-frame
|
|
Reuse an existing frame if one exists, otherwise create a new frame.
|
|
.TP
|
|
.B \-F, \-\-frame-parameters=ALIST
|
|
Set the parameters of a newly-created frame.
|
|
.TP
|
|
.B \-d, \-\-display=DISPLAY
|
|
Tell the server to display the files on the given display.
|
|
.TP
|
|
.B \-e, \-\-eval
|
|
Do not visit files but instead evaluate the arguments as Emacs
|
|
Lisp expressions.
|
|
.TP
|
|
.B \-f, \-\-server-file=FILENAME
|
|
Use TCP configuration file FILENAME for communication.
|
|
Relative filenames are relative to "~/.emacs.d/server/" or
|
|
"$XDG_CONFIG_HOME/emacs/server/", and the default is "server".
|
|
|
|
See also the EMACS_SERVER_FILE environment variable, over which this
|
|
option takes precedence.
|
|
.TP
|
|
.B \-n, \-\-no-wait
|
|
Return immediately without waiting for you to "finish" the buffer in
|
|
Emacs. If combined with --eval, this option is ignored.
|
|
.TP
|
|
.B \-w, \-\-timeout=N
|
|
How long to wait, in seconds, for Emacs to respond before giving up.
|
|
The default is 0, which means to wait forever.
|
|
.TP
|
|
.B \-\-parent-id=ID
|
|
Open an
|
|
.B emacsclient
|
|
frame as a client frame in the parent X window with id ID.
|
|
.TP
|
|
.B \-q, \-\-quiet
|
|
Do not let
|
|
.B emacsclient
|
|
display messages about waiting for Emacs or connecting to remote
|
|
server sockets.
|
|
.TP
|
|
.B \-u, \-\-suppress-output
|
|
Do not let
|
|
.B emacsclient
|
|
display results returned from the server. Mostly useful in
|
|
combination with --eval when the evaluation performed is for
|
|
side-effect rather than result.
|
|
.TP
|
|
.B \-s, \-\-socket-name=FILENAME
|
|
Use socket named FILENAME for communication.
|
|
Relative filenames are relative to "$XDG_RUNTIME_DIR/emacs/" or "$TMPDIR/".
|
|
|
|
See also the EMACS_SOCKET_NAME environment variable, over which this
|
|
option takes precedence.
|
|
.TP
|
|
.B \-nw, \-t, \-\-tty, \-\-no-window-system
|
|
Open a new Emacs frame on the current terminal.
|
|
.TP
|
|
.B \-T, \-\-tramp=PREFIX
|
|
Set PREFIX to add to filenames for Emacs to locate files on remote
|
|
machines using TRAMP. This is mostly useful in combination with using
|
|
the Emacs server on a remote host (either using TCP with
|
|
--server-file, or a socket forwarded over SSH).
|
|
|
|
See also the EMACSCLIENT_TRAMP environment variable, over which this
|
|
option takes precedence.
|
|
.TP
|
|
.B \-V, \-\-version
|
|
Print version information and exit.
|
|
.TP
|
|
.B \-H, \-\-help
|
|
Print this usage information message and exit.
|
|
.SH "EXIT STATUS"
|
|
Normally, the exit status is 0. If emacsclient shuts down due to
|
|
Emacs signaling an error, the exit status is 1.
|
|
.SH ENVIRONMENT
|
|
.TP
|
|
.B ALTERNATE_EDITOR
|
|
If the Emacs server is not running, run the shell command in this
|
|
environment variable instead. If set to the empty string, run
|
|
"emacs \-\-daemon" to start Emacs in daemon mode, and try to connect
|
|
to it. Will be overridden by the
|
|
.B \-\-alternate-editor
|
|
option, if present.
|
|
.TP
|
|
.B EMACSCLIENT_TRAMP
|
|
A prefix to add to filenames, intended to allow Emacs to locate files
|
|
on remote machines using TRAMP. Will be overridden by the
|
|
.B \-\-tramp
|
|
option, if present.
|
|
.TP
|
|
.B EMACS_SERVER_FILE
|
|
Look in this file to discover where to find a TCP Emacs server.
|
|
Relative filenames are relative to "~/.emacs.d/server/" or
|
|
"$XDG_CONFIG_HOME/emacs/server/", and the
|
|
default is "server". Will be overridden by the
|
|
.B \-\-server-file
|
|
option, if present.
|
|
.TP
|
|
.B EMACS_SOCKET_NAME
|
|
The filename of the socket to use for communication with the Emacs server.
|
|
Relative filenames are relative to "$XDG_RUNTIME_DIR/emacs/" or "$TMPDIR/".
|
|
Will be overridden by the
|
|
.B \-\-socket-name
|
|
option, if present.
|
|
.SH "SEE ALSO"
|
|
The program is documented fully in
|
|
.IR "Using Emacs as a Server"
|
|
available via the Info system.
|
|
|
|
The XDG_ environment variables are described in detail in the
|
|
.UR https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
|
|
XDG Base Directory Specification
|
|
.UE .
|
|
|
|
.SH AUTHOR
|
|
This manual page was originally written by Stephane Bortzmeyer
|
|
<bortzmeyer@debian.org>, for the Debian GNU/Linux system, but is not
|
|
specific to that system.
|
|
.SH COPYING
|
|
This manual page is in the public domain.
|
|
|
|
.\" Local Variables:
|
|
.\" eval: (add-hook 'before-save-hook 'time-stamp nil t)
|
|
.\" time-stamp-pattern: "3/.TH EMACSCLIENT 1 \"%Y-%02m-%02d\" \"GNU Emacs\" \"GNU\"$"
|
|
.\" time-stamp-time-zone: "UTC0"
|
|
.\" End:
|