home | help 
EMACSCLIENT(1)			       GNU			  EMACSCLIENT(1)

NAME
     emacsclient - tells a running Emacs to visit a file

SYNOPSIS
     emacsclient [options] files ...

DESCRIPTION
     This  manual page documents briefly the emacsclient command.  Full documen-
     tation is available in the GNU Info format; see below.

     emacsclient works in conjunction with the built-in Emacs server.

     You can either call emacsclient directly or let other programs run  it  for
     you  when necessary.  On GNU and Unix systems many programs consult the en-
     vironment 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  de-
     fault editor.

     For  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 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 ex-
     ternal 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.

OPTIONS
     Most options follow the usual GNU command line syntax,  with  long  options
     starting with two dashes ("-").

     +line[:column]
	    Go to the specified line and column.  A missing column is treated as
	    column 1.  This option applies only to the next file specified.

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

     -c, --create-frame
	    Create a new frame instead of trying to use the current Emacs frame.

     -r --reuse-frame
	    Reuse an existing frame if one exists, otherwise create a new frame.

     -F, --frame-parameters=ALIST
	    Set the parameters of a newly-created frame.

     -d, --display=DISPLAY
	    Tell the server to display the files on the given display.

     -e, --eval
	    Do not visit files but instead evaluate the arguments as Emacs  Lisp
	    expressions.

     -f, --server-file=FILENAME
	    Use  TCP  configuration  file  FILENAME for communication.	Relative
	    filenames  are  relative  to  "~/.emacs.d/server/"	 or   "$XDG_CON-
	    FIG_HOME/emacs/server/", and the default is "server".

	    See also the EMACS_SERVER_FILE environment variable, over which this
	    option takes precedence.

     -n, --no-wait
	    Return immediately without waiting for you to "finish" the buffer in
	    Emacs.  If combined with --eval, this option is ignored.

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

     --parent-id=ID
	    Open  an  emacsclient frame as a client frame in the parent X window
	    with id ID.

     -q, --quiet
	    Do not let emacsclient display messages about waiting for  Emacs  or
	    connecting to remote server sockets.

     -u, --suppress-output
	    Do	not  let  emacsclient  display results returned from the server.
	    Mostly useful in combination with --eval when  the	evaluation  per-
	    formed is for side-effect rather than result.

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

     -nw, -t, --tty, --no-window-system
	    Open a new Emacs frame on the current terminal.

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

     -V, --version
	    Print version information and exit.

     -H, --help
	    Print this usage information message and exit.

EXIT STATUS
     Normally,	the  exit  status  is 0.  If emacsclient shuts down due to Emacs
     signaling an error, the exit status is 1.

ENVIRONMENT
     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 --alternate-editor option, if
	    present.

     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
	    --tramp option, if present.

     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 --server-file option, if present.

     EMACS_SOCKET_NAME
	    The filename of the socket to use for communication with  the  Emacs
	    server.	Relative    filenames	are   relative	 to   "$XDG_RUN-
	    TIME_DIR/emacs/" or "$TMPDIR/".  Will be overridden by the --socket-
	    name option, if present.

SEE ALSO
     The program is documented fully in Using Emacs as a  Server  available  via
     the Info system.

     The  XDG_ environment variables are described in detail in the XDG Base Di-
     rectory Specification.

AUTHOR
     This  manual  page  was   originally   written   by   Stephane   Bortzmeyer
     <bortzmeyer@debian.org>,  for  the Debian GNU/Linux system, but is not spe-
     cific to that system.

COPYING
     This manual page is in the public domain.

GNU Emacs			   2024-08-20			  EMACSCLIENT(1)
home | help