1*remote.txt* For Vim version 8.2. Last change: 2019 May 05 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Vim client-server communication *client-server* 8 91. Common functionality |clientserver| 102. X11 specific items |x11-clientserver| 113. MS-Windows specific items |w32-clientserver| 12 13============================================================================== 141. Common functionality *clientserver* 15 16When compiled with the |+clientserver| option, Vim can act as a command 17server. It accepts messages from a client and executes them. At the same 18time, Vim can function as a client and send commands to a Vim server. 19 20The following command line arguments are available: 21 22 argument meaning ~ 23 24 --remote [+{cmd}] {file} ... *--remote* 25 Open the file list in a remote Vim. When 26 there is no Vim server, execute locally. 27 There is one optional init command: +{cmd}. 28 This must be an Ex command that can be 29 followed by "|". 30 The rest of the command line is taken as the 31 file list. Thus any non-file arguments must 32 come before this. 33 You cannot edit stdin this way |--|. 34 The remote Vim is raised. If you don't want 35 this use > 36 vim --remote-send "<C-\><C-N>:n filename<CR>" 37< 38 --remote-silent [+{cmd}] {file} ... *--remote-silent* 39 As above, but don't complain if there is no 40 server and the file is edited locally. 41 --remote-wait [+{cmd}] {file} ... *--remote-wait* 42 As --remote, but wait for files to complete 43 (unload) in remote Vim. 44 --remote-wait-silent [+{cmd}] {file} ... *--remote-wait-silent* 45 As --remote-wait, but don't complain if there 46 is no server. 47 *--remote-tab* 48 --remote-tab Like --remote but open each file in a new 49 tabpage. 50 *--remote-tab-silent* 51 --remote-tab-silent Like --remote-silent but open each file in a 52 new tabpage. 53 *--remote-tab-wait* 54 --remote-tab-wait Like --remote-wait but open each file in a new 55 tabpage. 56 57 *--remote-tab-wait-silent* 58 --remote-tab-wait-silent Like --remote-wait-silent but open each file 59 in a new tabpage. 60 *--servername* 61 --servername {name} Become the server {name}. When used together 62 with one of the --remote commands: connect to 63 server {name} instead of the default (see 64 below). The name used will be uppercase. 65 *--remote-send* 66 --remote-send {keys} Send {keys} to server and exit. The {keys} 67 are not mapped. Special key names are 68 recognized, e.g., "<CR>" results in a CR 69 character. 70 *--remote-expr* 71 --remote-expr {expr} Evaluate {expr} in server and print the result 72 on stdout. 73 *--serverlist* 74 --serverlist Output a list of server names. 75 76 77Examples ~ 78 79Edit "file.txt" in an already running GVIM server: > 80 gvim --remote file.txt 81 82Edit "file.txt" in an already running server called FOOBAR: > 83 gvim --servername FOOBAR --remote file.txt 84 85Edit "file.txt" in server "FILES" if it exists, become server "FILES" 86otherwise: > 87 gvim --servername FILES --remote-silent file.txt 88 89This doesn't work, all arguments after --remote will be used as file names: > 90 gvim --remote --servername FOOBAR file.txt 91 92Edit file "+foo" in a remote server (note the use of "./" to avoid the special 93meaning of the leading plus): > 94 vim --remote ./+foo 95 96Tell the remote server "BLA" to write all files and exit: > 97 vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>' 98 99 100SERVER NAME *client-server-name* 101 102By default Vim will try to register the name under which it was invoked (gvim, 103egvim ...). This can be overridden with the --servername argument. If the 104specified name is not available, a postfix is applied until a free name is 105encountered, i.e. "gvim1" for the second invocation of gvim on a particular 106X-server. The resulting name is available in the servername builtin variable 107|v:servername|. The case of the server name is ignored, thus "gvim" and 108"GVIM" are considered equal. 109 110When Vim is invoked with --remote, --remote-wait or --remote-send it will try 111to locate the server name determined by the invocation name and --servername 112argument as described above. If an exact match is not available, the first 113server with the number postfix will be used. If a name with the number 114postfix is specified with the --servername argument, it must match exactly. 115 116If no server can be located and --remote or --remote-wait was used, Vim will 117start up according to the rest of the command line and do the editing by 118itself. This way it is not necessary to know whether gvim is already started 119when sending command to it. 120 121The --serverlist argument will cause Vim to print a list of registered command 122servers on the standard output (stdout) and exit. 123 124Win32 Note: Making the Vim server go to the foreground doesn't always work, 125because MS-Windows doesn't allow it. The client will move the server to the 126foreground when using the --remote or --remote-wait argument and the server 127name starts with "g". 128 129 130REMOTE EDITING 131 132The --remote argument will cause a |:drop| command to be constructed from the 133rest of the command line and sent as described above. 134The --remote-wait argument does the same thing and additionally sets up to 135wait for each of the files to have been edited. This uses the BufUnload 136event, thus as soon as a file has been unloaded, Vim assumes you are done 137editing it. 138Note that the --remote and --remote-wait arguments will consume the rest of 139the command line. I.e. all remaining arguments will be regarded as filenames. 140You can not put options there! 141 142 143FUNCTIONS 144 *E240* *E573* 145There are a number of Vim functions for scripting the command server. See 146the description in |eval.txt| or use CTRL-] on the function name to jump to 147the full explanation. 148 149 synopsis explanation ~ 150 remote_startserver( name) run a server 151 remote_expr( server, string, idvar) send expression 152 remote_send( server, string, idvar) send key sequence 153 serverlist() get a list of available servers 154 remote_peek( serverid, retvar) check for reply string 155 remote_read( serverid) read reply string 156 server2client( serverid, string) send reply string 157 remote_foreground( server) bring server to the front 158 159See also the explanation of |CTRL-\_CTRL-N|. Very useful as a leading key 160sequence. 161The {serverid} for server2client() can be obtained with expand("<client>") 162 163============================================================================== 1642. X11 specific items *x11-clientserver* 165 *E247* *E248* *E251* *E258* *E277* 166 167The communication between client and server goes through the X server. The 168display of the Vim server must be specified. The usual protection of the X 169server is used, you must be able to open a window on the X server for the 170communication to work. It is possible to communicate between different 171systems. 172 173By default, a GUI Vim will register a name on the X-server by which it can be 174addressed for subsequent execution of injected strings. Vim can also act as 175a client and send strings to other instances of Vim on the same X11 display. 176 177When an X11 GUI Vim (gvim) is started, it will try to register a send-server 178name on the 'VimRegistry' property on the root window. 179 180A non GUI Vim with access to the X11 display (|xterm-clipboard| enabled), can 181also act as a command server if a server name is explicitly given with the 182--servername argument, or when Vim was built with the |+autoservername| 183feature. 184 185An empty --servername argument will cause the command server to be disabled. 186 187To send commands to a Vim server from another application, read the source 188file src/if_xcmdsrv.c, it contains some hints about the protocol used. 189 190============================================================================== 1913. Win32 specific items *w32-clientserver* 192 193Every Win32 Vim can work as a server, also in the console. You do not need a 194version compiled with OLE. Windows messages are used, this works on any 195version of MS-Windows. But only communication within one system is possible. 196 197Since MS-Windows messages are used, any other application should be able to 198communicate with a Vim server. An alternative is using the OLE functionality 199|ole-interface|. 200 201When using gvim, the --remote-wait only works properly this way: > 202 203 start /w gvim --remote-wait file.txt 204< 205 vim:tw=78:sw=4:ts=8:noet:ft=help:norl: 206