runtime/doc/remote.txt

   1 *remote.txt*    For Vim version 7.2b.  Last change: 2008 May 24
   2
   3
   4                   VIM REFERENCE MANUAL    by Bram Moolenaar
   5
   6
   7 Vim client-server communication                         *client-server*
   8
   9 1. Common functionality         |clientserver|
  10 2. X11 specific items           |x11-clientserver|
  11 3. MS-Windows specific items    |w32-clientserver|
  12
  13 {Vi does not have any of these commands}
  14
  15 ==============================================================================
  16 1. Common functionality                                 *clientserver*
  17
  18 When compiled with the |+clientserver| option, Vim can act as a command
  19 server.  It accepts messages from a client and executes them.  At the same
  20 time, Vim can function as a client and send commands to a Vim server.
  21
  22 The 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
  78 Examples ~
  79
  80 Edit "file.txt" in an already running GVIM server: >
  81     gvim --remote file.txt
  82
  83 Edit "file.txt" in an already running server called FOOBAR: >
  84     gvim --servername FOOBAR --remote file.txt
  85
  86 Edit "file.txt" in server "FILES" if it exists, become server "FILES"
  87 otherwise: >
  88     gvim --servername FILES --remote-silent file.txt
  89
  90 This doesn't work, all arguments after --remote will be used as file names: >
  91     gvim --remote --servername FOOBAR file.txt
  92
  93 Edit file "+foo" in a remote server (note the use of "./" to avoid the special
  94 meaning of the leading plus): >
  95     vim --remote ./+foo
  96
  97 Tell the remote server "BLA" to write all files and exit: >
  98     vim --servername BLA --remote-send '<C-\><C-N>:wqa<CR>'
  99
 100
 101 SERVER NAME
 102
 103 By default Vim will try to register the name under which it was invoked (gvim,
 104 egvim ...).  This can be overridden with the --servername argument.  If the
 105 specified name is not available, a postfix is applied until a free name is
 106 encountered, i.e. "gvim1" for the second invocation of gvim on a particular
 107 X-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
 111 When Vim is invoked with --remote, --remote-wait or --remote-send it will try
 112 to locate the server name determined by the invocation name and --servername
 113 argument as described above.  If an exact match is not available, the first
 114 server with the number postfix will be used.  If a name with the number
 115 postfix is specified with the --servername argument, it must match exactly.
 116
 117 If no server can be located and --remote or --remote-wait was used, Vim will
 118 start up according to the rest of the command line and do the editing by
 119 itself.  This way it is not necessary to know whether gvim is already started
 120 when sending command to it.
 121
 122 The --serverlist argument will cause Vim to print a list of registered command
 123 servers on the standard output (stdout) and exit.
 124
 125 Win32 Note: Making the Vim server go to the foreground doesn't always work,
 126 because MS-Windows doesn't allow it.  The client will move the server to the
 127 foreground when using the --remote or --remote-wait argument and the server
 128 name starts with "g".
 129
 130
 131 REMOTE EDITING
 132
 133 The --remote argument will cause a |:drop| command to be constructed from the
 134 rest of the command line and sent as described above.
 135 The --remote-wait argument does the same thing and additionally sets up to
 136 wait for each of the files to have been edited.  This uses the BufUnload
 137 event, thus as soon as a file has been unloaded, Vim assumes you are done
 138 editing it.
 139 Note that the --remote and --remote-wait arguments will consume the rest of
 140 the command line.  I.e. all remaining arguments will be regarded as filenames.
 141 You can not put options there!
 142
 143
 144 FUNCTIONS
 145                                                                 *E240* *E573*
 146 There are a number of Vim functions for scripting the command server.  See
 147 the description in |eval.txt| or use CTRL-] on the function name to jump to
 148 the 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
 159 See also the explanation of |CTRL-\_CTRL-N|.  Very useful as a leading key
 160 sequence.
 161 The {serverid} for server2client() can be obtained with expand("<client>")
 162
 163 ==============================================================================
 164 2. X11 specific items                                   *x11-clientserver*
 165                                     *E247* *E248* *E251* *E258* *E277*
 166
 167 The communication between client and server goes through the X server.  The
 168 display of the Vim server must be specified.  The usual protection of the X
 169 server is used, you must be able to open a window on the X server for the
 170 communication to work.  It is possible to communicate between different
 171 systems.
 172
 173 By default, a GUI Vim will register a name on the X-server by which it can be
 174 addressed for subsequent execution of injected strings.  Vim can also act as
 175 a client and send strings to other instances of Vim on the same X11 display.
 176
 177 When an X11 GUI Vim (gvim) is started, it will try to register a send-server
 178 name on the 'VimRegistry' property on the root window.
 179
 180 A non GUI Vim with access to the X11 display (|xterm-clipboard| enabled), can
 181 also act as a command server if a server name is explicitly given with the
 182 --servername argument.
 183
 184 An empty --servername argument will cause the command server to be disabled.
 185
 186 To send commands to a Vim server from another application, read the source
 187 file src/if_xcmdsrv.c, it contains some hints about the protocol used.
 188
 189 ==============================================================================
 190 3. Win32 specific items                                 *w32-clientserver*
 191
 192 Every Win32 Vim can work as a server, also in the console.  You do not need a
 193 version compiled with OLE.  Windows messages are used, this works on any
 194 version of MS-Windows.  But only communication within one system is possible.
 195
 196 Since MS-Windows messages are used, any other application should be able to
 197 communicate with a Vim server.  An alternative is using the OLE functionality
 198 |ole-interface|.
 199
 200 When 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: