Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

OPTIONS
       Most options follow the usual GNU command line syntax,  with  long  op-
       tions 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 com-
	      mand  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  ig-
	      nored.

       -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 win-
	      dow 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
	      performed	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  re-
	      mote 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.

       -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 op-
	      tion, 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
       Directory						 Specification
       <https://specifications.freedesktop.org/basedir-spec/basedir-spec-
       latest.html>.

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.

COPYING
       This manual page	is in the public domain.

GNU Emacs			  2024-08-20			EMACSCLIENT(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=emacsclient&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help