39a67920fb
closes: #18086 Signed-off-by: Hirohito Higashi <h.east.727@gmail.com> Signed-off-by: Christian Brabandt <cb@256bit.org>
282 lines
12 KiB
Plaintext
282 lines
12 KiB
Plaintext
*remote.txt* For Vim version 9.1. Last change: 2025 Aug 22
|
|
|
|
|
|
VIM REFERENCE MANUAL by Bram Moolenaar
|
|
|
|
|
|
Vim client-server communication *client-server*
|
|
|
|
1. Common functionality |clientserver|
|
|
2. X11 specific items |x11-clientserver|
|
|
3. MS-Windows specific items |w32-clientserver|
|
|
4. Socket server specific items |socketserver-clientserver|
|
|
|
|
==============================================================================
|
|
1. Common functionality *clientserver*
|
|
|
|
When compiled with the |+clientserver| option, Vim can act as a command
|
|
server. It accepts messages from a client and executes them. At the same
|
|
time, Vim can function as a client and send commands to a Vim server.
|
|
|
|
The following command line arguments are available:
|
|
|
|
argument meaning ~
|
|
|
|
--remote [+{cmd}] {file} ... *--remote*
|
|
Open the file list in a remote Vim. When
|
|
there is no Vim server, execute locally.
|
|
There is one optional init command: +{cmd}.
|
|
This must be an Ex command that can be
|
|
followed by "|".
|
|
The rest of the command line is taken as the
|
|
file list. Thus any non-file arguments must
|
|
come before this.
|
|
You cannot edit stdin this way |--|.
|
|
The remote Vim is raised. If you don't want
|
|
this use >
|
|
vim --remote-send "<C-\><C-N>:n filename<CR>"
|
|
<
|
|
--remote-silent [+{cmd}] {file} ... *--remote-silent*
|
|
As above, but don't complain if there is no
|
|
server and the file is edited locally.
|
|
--remote-wait [+{cmd}] {file} ... *--remote-wait*
|
|
As --remote, but wait for files to complete
|
|
(unload) in remote Vim.
|
|
--remote-wait-silent [+{cmd}] {file} ... *--remote-wait-silent*
|
|
As --remote-wait, but don't complain if there
|
|
is no server.
|
|
*--remote-tab*
|
|
--remote-tab Like --remote but open each file in a new
|
|
tabpage.
|
|
*--remote-tab-silent*
|
|
--remote-tab-silent Like --remote-silent but open each file in a
|
|
new tabpage.
|
|
*--remote-tab-wait*
|
|
--remote-tab-wait Like --remote-wait but open each file in a new
|
|
tabpage.
|
|
|
|
*--remote-tab-wait-silent*
|
|
--remote-tab-wait-silent Like --remote-wait-silent but open each file
|
|
in a new tabpage.
|
|
*--servername*
|
|
--servername {name} Become the server {name}. When used together
|
|
with one of the --remote commands: connect to
|
|
server {name} instead of the default (see
|
|
below). The name used will be uppercase. If
|
|
using the socketserver, you can specify a
|
|
path, see |socketserver-name| for more
|
|
details.
|
|
*--remote-send*
|
|
--remote-send {keys} Send {keys} to server and exit. The {keys}
|
|
are not mapped. Special key names are
|
|
recognized, e.g., "<CR>" results in a CR
|
|
character.
|
|
*--remote-expr*
|
|
--remote-expr {expr} Evaluate {expr} in server and print the result
|
|
on stdout.
|
|
*--serverlist*
|
|
--serverlist Output a list of server names.
|
|
*--clientserver*
|
|
--clientserver {method} Use the specified method {method} as the
|
|
backend for clientserver functionality. Can
|
|
either be "socket" or "x11".
|
|
{only available when compiled with both |+X11|
|
|
and |+socketserver| features}
|
|
|
|
|
|
Examples ~
|
|
|
|
Edit "file.txt" in an already running GVIM server: >
|
|
gvim --remote file.txt
|
|
|
|
Edit "file.txt" in an already running server called FOOBAR: >
|
|
gvim --servername FOOBAR --remote file.txt
|
|
|
|
Edit "file.txt" in server "FILES" if it exists, become server "FILES"
|
|
otherwise: >
|
|
gvim --servername FILES --remote-silent file.txt
|
|
|
|
This doesn't work, all arguments after --remote will be used as file names: >
|
|
gvim --remote --servername FOOBAR file.txt
|
|
|
|
Edit file "+foo" in a remote server (note the use of "./" to avoid the special
|
|
meaning of the leading plus): >
|
|
vim --remote ./+foo
|
|
|
|
Tell the remote server "BLA" to write all files and exit: >
|
|
vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>'
|
|
|
|
|
|
SERVER NAME *client-server-name*
|
|
|
|
By default Vim will try to register the name under which it was invoked (gvim,
|
|
egvim ...). This can be overridden with the --servername argument. If the
|
|
specified name is not available, a postfix is applied until a free name is
|
|
encountered, i.e. "gvim1" for the second invocation of gvim on a particular
|
|
X-server. The resulting name is available in the servername builtin variable
|
|
|v:servername|. The case of the server name is ignored, thus "gvim" and
|
|
"GVIM" are considered equal. Note if a socket server is being used, there are
|
|
some differences, see |socketserver-differences|.
|
|
|
|
When Vim is invoked with --remote, --remote-wait or --remote-send it will try
|
|
to locate the server name determined by the invocation name and --servername
|
|
argument as described above. If an exact match is not available, the first
|
|
server with the number postfix will be used. If a name with the number
|
|
postfix is specified with the --servername argument, it must match exactly.
|
|
|
|
If no server can be located and --remote or --remote-wait was used, Vim will
|
|
start up according to the rest of the command line and do the editing by
|
|
itself. This way it is not necessary to know whether gvim is already started
|
|
when sending command to it.
|
|
|
|
The --serverlist argument will cause Vim to print a list of registered command
|
|
servers on the standard output (stdout) and exit. If a socket server is being
|
|
used, there are caveats, see |socketserver-differences|.
|
|
*{server}*
|
|
The {server} argument is used by several functions. When this is an empty
|
|
string then on Unix the default server name is used, which is "GVIM". On
|
|
MS-Windows an empty string does not work.
|
|
|
|
Win32 Note: Making the Vim server go to the foreground doesn't always work,
|
|
because MS-Windows doesn't allow it. The client will move the server to the
|
|
foreground when using the --remote or --remote-wait argument and the server
|
|
name starts with "g".
|
|
|
|
|
|
REMOTE EDITING
|
|
|
|
The --remote argument will cause a |:drop| command to be constructed from the
|
|
rest of the command line and sent as described above.
|
|
The --remote-wait argument does the same thing and additionally sets up to
|
|
wait for each of the files to have been edited. This uses the BufUnload
|
|
event, thus as soon as a file has been unloaded, Vim assumes you are done
|
|
editing it.
|
|
Note that the --remote and --remote-wait arguments will consume the rest of
|
|
the command line. I.e. all remaining arguments will be regarded as filenames.
|
|
You can not put options there!
|
|
|
|
|
|
FUNCTIONS
|
|
*E240* *E573*
|
|
There are a number of Vim functions for scripting the command server. See
|
|
the description in |builtin.txt| or use CTRL-] on the function name to jump to
|
|
the full explanation.
|
|
|
|
synopsis explanation ~
|
|
remote_startserver( name) run a server
|
|
remote_expr( server, string, idvar) send expression
|
|
remote_send( server, string, idvar) send key sequence
|
|
serverlist() get a list of available servers
|
|
remote_peek( serverid, retvar) check for reply string
|
|
remote_read( serverid) read reply string
|
|
server2client( serverid, string) send reply string
|
|
remote_foreground( server) bring server to the front
|
|
|
|
See also the explanation of |CTRL-\_CTRL-N|. Very useful as a leading key
|
|
sequence.
|
|
The {serverid} for server2client() can be obtained with expand("<client>")
|
|
|
|
==============================================================================
|
|
2. X11 specific items *x11-clientserver*
|
|
*E247* *E248* *E251* *E258* *E277*
|
|
|
|
The communication between client and server goes through the X server. The
|
|
display of the Vim server must be specified. The usual protection of the X
|
|
server is used, you must be able to open a window on the X server for the
|
|
communication to work. It is possible to communicate between different
|
|
systems.
|
|
|
|
By default, a GUI Vim will register a name on the X-server by which it can be
|
|
addressed for subsequent execution of injected strings. Vim can also act as
|
|
a client and send strings to other instances of Vim on the same X11 display.
|
|
|
|
When an X11 GUI Vim (gvim) is started, it will try to register a send-server
|
|
name on the 'VimRegistry' property on the root window.
|
|
|
|
A non GUI Vim with access to the X11 display (|xterm-clipboard| enabled), can
|
|
also act as a command server if a server name is explicitly given with the
|
|
--servername argument, or when Vim was built with the |+autoservername|
|
|
feature.
|
|
|
|
An empty --servername argument will cause the command server to be disabled.
|
|
|
|
To send commands to a Vim server from another application, read the source
|
|
file src/if_xcmdsrv.c, it contains some hints about the protocol used.
|
|
|
|
==============================================================================
|
|
3. Win32 specific items *w32-clientserver*
|
|
|
|
Every Win32 Vim can work as a server, also in the console. You do not need a
|
|
version compiled with OLE. Windows messages are used, this works on any
|
|
version of MS-Windows. But only communication within one system is possible.
|
|
|
|
Since MS-Windows messages are used, any other application should be able to
|
|
communicate with a Vim server. An alternative is using the OLE functionality
|
|
|ole-interface|.
|
|
|
|
When using gvim, the --remote-wait only works properly this way: >
|
|
|
|
start /w gvim --remote-wait file.txt
|
|
<
|
|
==============================================================================
|
|
4. Socket server specific items *socketserver-clientserver*
|
|
*E1563* *E1564* *E1565* *E1566* *E1567*
|
|
|
|
The communication between client and server is done using Unix domain sockets.
|
|
These sockets are either placed in these directories in the following order of
|
|
availability:
|
|
1. "$XDG_RUTIME_DIR/vim" if $XDG_RUNTIME_DIR is set in the environment.
|
|
2. "$TMPDIR/vim-[uid]", where "[uid]" is the uid of the user. This
|
|
directory will have the access permissions set to 700 so only the user
|
|
can read or write from/to it. If $TMPDIR is not set, "/tmp" is used.
|
|
|
|
*socketserver-name*
|
|
When specifying the server id/name, it can be taken as a generic name or an
|
|
absolute or relative path. If the server id starts with either a "/"
|
|
(absolute) or "./" | "../" (relative), then it is taken as path to the socket.
|
|
Otherwise the server id will be the filename of the socket which will be
|
|
placed in the above common directories. Note that a server id/name can only
|
|
contain slashes "/" if it is taken as a path, so names such as "abc/dir" will
|
|
be invalid.
|
|
|
|
Socket server functionality is available in both GTK GUI and terminal versions
|
|
of Vim. Unless Vim is compiled with |+autoservername| feature, the socket
|
|
server will have to started explicitly, just like X11, even in the GUI.
|
|
|
|
If Vim crashes or does not exit cleanly, the socket server will not remove the
|
|
socket file and it will be left around. This is generally not a problem,
|
|
because if a socket name is taken, Vim checks if the socket in its place is
|
|
dead (not attached to any process), and can replace it instead of finding a
|
|
new name.
|
|
|
|
To send commands to a Vim socket server from another application, read the
|
|
source file src/os_unix.c, there is detailed description of the protocol used.
|
|
|
|
*socketserver-differences*
|
|
Most of the functionality is the same as X11, however unlike X11, where the
|
|
client does not need to be a server in order to communicate with another
|
|
server, the socket server requires the server to be running even as a client.
|
|
The exception is |serverlist()| or the |--serverlist| argument, which does not
|
|
require the server to be running.
|
|
|
|
Additionally, the server id or client id will not be a number like X11 or
|
|
MS-Windows (shown in hex representation), instead it is the absolute path to
|
|
the socket. This can be seen via the |v:servername| variable.
|
|
|
|
The |--serverlist| argument will act just like X11, however it only checks the
|
|
given common directories above. If a custom path is used for a socket, it
|
|
will not be detected, such as a path either not in $XDG_RUNTIME_DIR or
|
|
<$TMPDIR or /tmp>/vim of the |--serverlist| Vim process.
|
|
|
|
If you have both |+socketserver| and |+X11| compiled, you will need to add
|
|
|--clientserver| set to "socket" in combination with |--serverlist| to list
|
|
the available servers. You cannot list both types of backends in one command.
|
|
|
|
*socketserver-x11*
|
|
If Vim is compiled with both |+X11| and |+socketserver|, then deciding which
|
|
backend to use is done at startup time, via the |--clientserver| argument. By
|
|
default if it is not specified, then X11 will be used. A Vim instance using a
|
|
socket server cannot communicate with one using X11.
|
|
|
|
vim:tw=78:sw=4:ts=8:noet:ft=help:norl:
|