1- *remote.txt* For Vim version 9.1. Last change: 2022 Feb 17
1+ *remote.txt* For Vim version 9.1. Last change: 2025 Aug 22
22
33
44 VIM REFERENCE MANUAL by Bram Moolenaar
@@ -9,6 +9,7 @@ Vim client-server communication *client-server*
991. Common functionality | clientserver |
10102. X11 specific items | x11-clientserver |
11113. MS-Windows specific items | w32-clientserver |
12+ 4. Socket server specific items | socketserver-clientserver |
1213
1314==============================================================================
14151. Common functionality *clientserver*
@@ -61,7 +62,10 @@ The following command line arguments are available:
6162 --servername {name} Become the server {name} . When used together
6263 with one of the --remote commands: connect to
6364 server {name} instead of the default (see
64- below). The name used will be uppercase.
65+ below). The name used will be uppercase. If
66+ using the socketserver, you can specify a
67+ path, see | socketserver-name | for more
68+ details.
6569 *--remote-send*
6670 --remote-send {keys} Send {keys} to server and exit. The {keys}
6771 are not mapped. Special key names are
@@ -72,6 +76,12 @@ The following command line arguments are available:
7276 on stdout.
7377 *--serverlist*
7478 --serverlist Output a list of server names.
79+ *--clientserver*
80+ --clientserver {method} Use the specified method {method} as the
81+ backend for clientserver functionality. Can
82+ either be "socket" or "x11".
83+ {only available when compiled with both | +X11 |
84+ and | +socketserver | features}
7585
7686
7787Examples ~
@@ -105,7 +115,8 @@ specified name is not available, a postfix is applied until a free name is
105115encountered, i.e. "gvim1" for the second invocation of gvim on a particular
106116X-server. The resulting name is available in the servername builtin variable
107117| v:servername | . The case of the server name is ignored, thus "gvim" and
108- "GVIM" are considered equal.
118+ "GVIM" are considered equal. Note if a socket server is being used, there are
119+ some differences, see | socketserver-differences | .
109120
110121When Vim is invoked with --remote, --remote-wait or --remote-send it will try
111122to locate the server name determined by the invocation name and --servername
@@ -119,7 +130,8 @@ itself. This way it is not necessary to know whether gvim is already started
119130when sending command to it.
120131
121132The --serverlist argument will cause Vim to print a list of registered command
122- servers on the standard output (stdout) and exit.
133+ servers on the standard output (stdout) and exit. If a socket server is being
134+ used, there are caveats, see | socketserver-differences | .
123135 *{server}*
124136The {server} argument is used by several functions. When this is an empty
125137string then on Unix the default server name is used, which is "GVIM". On
@@ -206,4 +218,64 @@ When using gvim, the --remote-wait only works properly this way: >
206218
207219 start /w gvim --remote-wait file.txt
208220<
221+ ==============================================================================
222+ 4. Socket server specific items *socketserver-clientserver*
223+ *E1563* *E1564* *E1565* *E1566* *E1567*
224+
225+ The communication between client and server is done using Unix domain sockets.
226+ These sockets are either placed in these directories in the following order of
227+ availability:
228+ 1. "$XDG_RUTIME_DIR/vim" if $XDG_RUNTIME_DIR is set in the environment.
229+ 2. "$TMPDIR/vim-[uid]", where "[uid]" is the uid of the user. This
230+ directory will have the access permissions set to 700 so only the user
231+ can read or write from/to it. If $TMPDIR is not set, "/tmp" is used.
232+
233+ *socketserver-name*
234+ When specifying the server id/name, it can be taken as a generic name or an
235+ absolute or relative path. If the server id starts with either a "/"
236+ (absolute) or "./" | "../" (relative), then it is taken as path to the socket.
237+ Otherwise the server id will be the filename of the socket which will be
238+ placed in the above common directories. Note that a server id/name can only
239+ contain slashes "/" if it is taken as a path, so names such as "abc/dir" will
240+ be invalid.
241+
242+ Socket server functionality is available in both GTK GUI and terminal versions
243+ of Vim. Unless Vim is compiled with | +autoservername | feature, the socket
244+ server will have to started explicitly, just like X11, even in the GUI.
245+
246+ If Vim crashes or does not exit cleanly, the socket server will not remove the
247+ socket file and it will be left around. This is generally not a problem,
248+ because if a socket name is taken, Vim checks if the socket in its place is
249+ dead (not attached to any process), and can replace it instead of finding a
250+ new name.
251+
252+ To send commands to a Vim socket server from another application, read the
253+ source file src/os_unix.c, there is detailed description of the protocol used.
254+
255+ *socketserver-differences*
256+ Most of the functionality is the same as X11, however unlike X11, where the
257+ client does not need to be a server in order to communicate with another
258+ server, the socket server requires the server to be running even as a client.
259+ The exception is | serverlist() | or the | --serverlist | argument, which does not
260+ require the server to be running.
261+
262+ Additionally, the server id or client id will not be a number like X11 or
263+ MS-Windows (shown in hex representation), instead it is the absolute path to
264+ the socket. This can be seen via the | v:servername | variable.
265+
266+ The | --serverlist | argument will act just like X11, however it only checks the
267+ given common directories above. If a custom path is used for a socket, it
268+ will not be detected, such as a path either not in $XDG_RUNTIME_DIR or
269+ <$TMPDIR or /tmp>/vim of the | --serverlist | Vim process.
270+
271+ If you have both | +socketserver | and | +X11 | compiled, you will need to add
272+ | --clientserver | set to "socket" in combination with | --serverlist | to list
273+ the available servers. You cannot list both types of backends in one command.
274+
275+ *socketserver-x11*
276+ If Vim is compiled with both | +X11 | and | +socketserver | , then deciding which
277+ backend to use is done at startup time, via the | --clientserver | argument. By
278+ default if it is not specified, then X11 will be used. A Vim instance using a
279+ socket server cannot communicate with one using X11.
280+
209281 vim:tw=78:sw=4:ts=8:noet:ft=help:norl:
0 commit comments