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