runtime/doc/remote.txt

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