runtime/doc/remote.txt

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