1*remote.txt* For Vim version 7.3. Last change: 2008 May 24 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< --remote-silent [+{cmd}] {file} ... *--remote-silent* 40 As above, but don't complain if there is no 41 server and the file is edited locally. 42 --remote-wait [+{cmd}] {file} ... *--remote-wait* 43 As --remote, but wait for files to complete 44 (unload) in remote Vim. 45 --remote-wait-silent [+{cmd}] {file} ... *--remote-wait-silent* 46 As --remote-wait, but don't complain if there 47 is no server. 48 *--remote-tab* 49 --remote-tab Like --remote but open each file in a new 50 tabpage. 51 *--remote-tab-silent* 52 --remote-tab-silent Like --remote-silent but open each file in a 53 new tabpage. 54 *--remote-tab-wait* 55 --remote-tab-wait Like --remote-wait but open each file in a new 56 tabpage. 57 58 *--remote-tab-wait-silent* 59 --remote-tab-wait-silent Like --remote-wait-silent but open each file 60 in a new tabpage. 61 *--servername* 62 --servername {name} Become the server {name}. When used together 63 with one of the --remote commands: connect to 64 server {name} instead of the default (see 65 below). 66 *--remote-send* 67 --remote-send {keys} Send {keys} to server and exit. The {keys} 68 are not mapped. Special key names are 69 recognized, e.g., "<CR>" results in a CR 70 character. 71 *--remote-expr* 72 --remote-expr {expr} Evaluate {expr} in server and print the result 73 on stdout. 74 *--serverlist* 75 --serverlist Output a list of server names. 76 77 78Examples ~ 79 80Edit "file.txt" in an already running GVIM server: > 81 gvim --remote file.txt 82 83Edit "file.txt" in an already running server called FOOBAR: > 84 gvim --servername FOOBAR --remote file.txt 85 86Edit "file.txt" in server "FILES" if it exists, become server "FILES" 87otherwise: > 88 gvim --servername FILES --remote-silent file.txt 89 90This doesn't work, all arguments after --remote will be used as file names: > 91 gvim --remote --servername FOOBAR file.txt 92 93Edit file "+foo" in a remote server (note the use of "./" to avoid the special 94meaning of the leading plus): > 95 vim --remote ./+foo 96 97Tell the remote server "BLA" to write all files and exit: > 98 vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>' 99 100 101SERVER NAME 102 103By default Vim will try to register the name under which it was invoked (gvim, 104egvim ...). This can be overridden with the --servername argument. If the 105specified name is not available, a postfix is applied until a free name is 106encountered, i.e. "gvim1" for the second invocation of gvim on a particular 107X-server. The resulting name is available in the servername builtin variable 108|v:servername|. The case of the server name is ignored, thus "gvim" and 109"GVIM" are considered equal. 110 111When Vim is invoked with --remote, --remote-wait or --remote-send it will try 112to locate the server name determined by the invocation name and --servername 113argument as described above. If an exact match is not available, the first 114server with the number postfix will be used. If a name with the number 115postfix is specified with the --servername argument, it must match exactly. 116 117If no server can be located and --remote or --remote-wait was used, Vim will 118start up according to the rest of the command line and do the editing by 119itself. This way it is not necessary to know whether gvim is already started 120when sending command to it. 121 122The --serverlist argument will cause Vim to print a list of registered command 123servers on the standard output (stdout) and exit. 124 125Win32 Note: Making the Vim server go to the foreground doesn't always work, 126because MS-Windows doesn't allow it. The client will move the server to the 127foreground when using the --remote or --remote-wait argument and the server 128name starts with "g". 129 130 131REMOTE EDITING 132 133The --remote argument will cause a |:drop| command to be constructed from the 134rest of the command line and sent as described above. 135The --remote-wait argument does the same thing and additionally sets up to 136wait for each of the files to have been edited. This uses the BufUnload 137event, thus as soon as a file has been unloaded, Vim assumes you are done 138editing it. 139Note that the --remote and --remote-wait arguments will consume the rest of 140the command line. I.e. all remaining arguments will be regarded as filenames. 141You can not put options there! 142 143 144FUNCTIONS 145 *E240* *E573* 146There are a number of Vim functions for scripting the command server. See 147the description in |eval.txt| or use CTRL-] on the function name to jump to 148the full explanation. 149 150 synopsis explanation ~ 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. 183 184An empty --servername argument will cause the command server to be disabled. 185 186To send commands to a Vim server from another application, read the source 187file src/if_xcmdsrv.c, it contains some hints about the protocol used. 188 189============================================================================== 1903. Win32 specific items *w32-clientserver* 191 192Every Win32 Vim can work as a server, also in the console. You do not need a 193version compiled with OLE. Windows messages are used, this works on any 194version of MS-Windows. But only communication within one system is possible. 195 196Since MS-Windows messages are used, any other application should be able to 197communicate with a Vim server. An alternative is using the OLE functionality 198|ole-interface|. 199 200When using gvim, the --remote-wait only works properly this way: > 201 202 start /w gvim --remote-wait file.txt 203< 204 vim:tw=78:sw=4:ts=8:ft=help:norl: 205