blob: a52c739ad7799a13d08904665e81b9deaff3f968 [file] [log] [blame]
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01001*channel.txt* For Vim version 7.4. Last change: 2016 Feb 16
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7 Inter-process communication *channel*
8
9DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT
10
11Vim uses channels to communicate with other processes.
Bram Moolenaar38a55632016-02-15 22:07:32 +010012A channel uses a socket or pipes *socket-interface*
13Jobs can be used to start processes and communicate with them.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010014
Bram Moolenaar681baaf2016-02-04 20:57:07 +010015Vim current supports up to 10 simultaneous channels.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010016The Netbeans interface also uses a channel. |netbeans|
17
Bram Moolenaar38a55632016-02-15 22:07:32 +0100181. Overview |job-channel-overview|
192. Channel demo |channel-demo|
203. Opening a channel |channel-open|
214. Using a JSON or JS channel |channel-use|
225. Channel commands |channel-commands|
236. Using a RAW or NL channel |channel-raw|
247. More channel functions |channel-more|
258. Starting a job with a channel |job-start|
269. Starting a job without a channel |job-start-nochannel|
2710. Job options |job-options|
2811. Controlling a job |job-control|
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010029
30{Vi does not have any of these features}
Bram Moolenaar38a55632016-02-15 22:07:32 +010031{only when compiled with the |+channel| feature for channel stuff}
32{only when compiled with the |+job| feature for job stuff}
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010033
34==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +0100351. Overview *job-channel-overview*
36
37There are four main types of jobs:
381. A deamon, serving several Vim instances.
39 Vim connects to it with a socket.
402. One job working with one Vim instance, asynchronously.
41 Uses a socket or pipes.
423. A job performing some work for a short time, asynchronously.
43 Uses a socket or pipes.
444. Running a filter, synchronously.
45 Uses pipes.
46
47For when using sockets See |job-start|, |job-may-start| and |channel-open|.
48For 2 and 3, one or more jobs using pipes, see |job-start|.
49For 4 use the ":{range}!cmd" command, see |filter|.
50
51Over the socket and pipes these protocols are available:
52RAW nothing known, Vim cannot tell where a message ends
53NL every message ends in a NL (newline) character
54JSON JSON encoding |json_encode()|
55JS JavaScript style JSON-like encoding |js_encode()|
56
57Common combination are:
58- Using a job connected through pipes in NL mode. E.g., to run a style
59 checker and receive errors and warnings.
60- Using a deamon, connecting over a socket in JSON mode. E.g. to lookup
61 crosss-refrences in a database.
62
63==============================================================================
642. Channel demo *channel-demo*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010065
66This requires Python. The demo program can be found in
67$VIMRUNTIME/tools/demoserver.py
68Run it in one terminal. We will call this T1.
69
70Run Vim in another terminal. Connect to the demo server with: >
Bram Moolenaar38a55632016-02-15 22:07:32 +010071 let channel = ch_open('localhost:8765')
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010072
73In T1 you should see:
74 === socket opened === ~
75
76You can now send a message to the server: >
Bram Moolenaar38a55632016-02-15 22:07:32 +010077 echo ch_sendexpr(channel, 'hello!')
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010078
79The message is received in T1 and a response is sent back to Vim.
80You can see the raw messages in T1. What Vim sends is:
81 [1,"hello!"] ~
82And the response is:
83 [1,"got it"] ~
84The number will increase every time you send a message.
85
86The server can send a command to Vim. Type this on T1 (literally, including
Bram Moolenaarfb1f6262016-01-31 20:24:32 +010087the quotes):
88 ["ex","echo 'hi there'"] ~
89And you should see the message in Vim. You can move the cursor a word forward:
90 ["normal","w"] ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010091
92To handle asynchronous communication a callback needs to be used: >
Bram Moolenaar38a55632016-02-15 22:07:32 +010093 func MyHandler(channel, msg)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010094 echo "from the handler: " . a:msg
95 endfunc
Bram Moolenaar38a55632016-02-15 22:07:32 +010096 call ch_sendexpr(channel, 'hello!', "MyHandler")
97Vim will not wait for a response. Now the server can send the response later
98and MyHandler will be invoked.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010099
100Instead of giving a callback with every send call, it can also be specified
101when opening the channel: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100102 call ch_close(channel)
103 let channel = ch_open('localhost:8765', {'callback': "MyHandler"})
104 call ch_sendexpr(channel, 'hello!', 0)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100105
106==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01001073. Opening a channel *channel-open*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100108
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100109To open a channel: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100110 let channel = ch_open({address} [, {options}])
111
112Use |ch_status()| to see if the channel could be opened.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100113
114{address} has the form "hostname:port". E.g., "localhost:8765".
115
Bram Moolenaar38a55632016-02-15 22:07:32 +0100116{options} is a dictionary with optional entries:
Bram Moolenaar4d919d72016-02-05 22:36:41 +0100117
118"mode" can be: *channel-mode*
119 "json" - Use JSON, see below; most convenient way. Default.
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100120 "js" - Use JS (JavaScript) encoding, more efficient than JSON.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100121 "nl" - Use messages that end in a NL character
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100122 "raw" - Use raw messages
123
124 *channel-callback*
Bram Moolenaar38a55632016-02-15 22:07:32 +0100125"callback" A function that is called when a message is received that is
126 not handled otherwise. It gets two arguments: the channel
127 handle and the received message. Example: >
128 func Handle(channel, msg)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100129 echo 'Received: ' . a:msg
130 endfunc
Bram Moolenaar38a55632016-02-15 22:07:32 +0100131 let channel = ch_open("localhost:8765", {"callback": "Handle"})
132<
133 TODO:
134"err-cb" A function like "callback" but used for stderr. Only for when
135 the channel uses pipes.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100136
Bram Moolenaar38a55632016-02-15 22:07:32 +0100137 TODO:
138"close-cb" A function that is called when the channel gets closed, other
139 than by calling ch_close(). It should be defined like this: >
140 func MyCloseHandler(channel)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100141
Bram Moolenaar38a55632016-02-15 22:07:32 +0100142"waittime" The time to wait for the connection to be made in
143 milliseconds. The default is zero, don't wait, which is
144 useful if the server is supposed to be running already. A
145 negative number waits forever.
146
147"timeout" The time to wait for a request when blocking, using
148 ch_sendexpr(). Again in milliseconds. The default is 2000 (2
149 seconds).
Bram Moolenaar4d919d72016-02-05 22:36:41 +0100150
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100151When "mode" is "json" or "js" the "msg" argument is the body of the received
152message, converted to Vim types.
Bram Moolenaar4d919d72016-02-05 22:36:41 +0100153When "mode" is "raw" the "msg" argument is the whole message as a string.
154
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100155When "mode" is "json" or "js" the "callback" is optional. When omitted it is
156only possible to receive a message after sending one.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100157
Bram Moolenaar38a55632016-02-15 22:07:32 +0100158TODO:
159To change the channel options after opening it use ch_setoptions(). The
160arguments are similar to what is passed to ch_open(), but "waittime" cannot be
161given, since that only applies to opening the channel.
Bram Moolenaar4d919d72016-02-05 22:36:41 +0100162
Bram Moolenaar38a55632016-02-15 22:07:32 +0100163The handler can be added or changed: >
164 call ch_setoptions(channel, {'callback': callback})
165When "callback" is empty (zero or an empty string) the handler is removed.
166
167The timeout can be changed: >
168 call ch_setoptions(channel, {'timeout': msec})
169<
Bram Moolenaar835dc632016-02-07 14:27:38 +0100170 *E906*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100171Once done with the channel, disconnect it like this: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100172 call ch_close(channel)
173When a socket is used this will close the socket for both directions. When
174pipes are used (stdin/stdout/stderr) they are all closed. This might not be
175what you want! Stopping the job with job_stop() might be better.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100176
Bram Moolenaar38a55632016-02-15 22:07:32 +0100177TODO:
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100178Currently up to 10 channels can be in use at the same time. *E897*
179
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100180When the channel can't be opened you will get an error message. There is a
181difference between MS-Windows and Unix: On Unix when the port doesn't exist
182ch_open() fails quickly. On MS-Windows "waittime" applies.
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100183*E898* *E899* *E900* *E901* *E902*
184
185If there is an error reading or writing a channel it will be closed.
186*E896* *E630* *E631*
187
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100188==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01001894. Using a JSON or JS channel *channel-use*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100190
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100191If mode is JSON then a message can be sent synchronously like this: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100192 let response = ch_sendexpr(channel, {expr})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100193This awaits a response from the other side.
194
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100195When mode is JS this works the same, except that the messages use
Bram Moolenaar38a55632016-02-15 22:07:32 +0100196JavaScript encoding. See |js_encode()| for the difference.
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100197
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100198To send a message, without handling a response: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100199 call ch_sendexpr(channel, {expr}, 0)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100200
201To send a message and letting the response handled by a specific function,
202asynchronously: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100203 call ch_sendexpr(channel, {expr}, {callback})
204
205Vim will match the response with the request using the message ID. Once the
206response is received the callback will be invoked. Further responses with the
207same ID will be ignored. If your server sends back multiple responses you
208need to send them with ID zero, they will be passed to the channel callback.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100209
210The {expr} is converted to JSON and wrapped in an array. An example of the
211message that the receiver will get when {expr} is the string "hello":
212 [12,"hello"] ~
213
214The format of the JSON sent is:
215 [{number},{expr}]
216
217In which {number} is different every time. It must be used in the response
218(if any):
219
220 [{number},{response}]
221
222This way Vim knows which sent message matches with which received message and
223can call the right handler. Also when the messages arrive out of order.
224
225The sender must always send valid JSON to Vim. Vim can check for the end of
226the message by parsing the JSON. It will only accept the message if the end
227was received.
228
229When the process wants to send a message to Vim without first receiving a
230message, it must use the number zero:
231 [0,{response}]
232
233Then channel handler will then get {response} converted to Vim types. If the
234channel does not have a handler the message is dropped.
235
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100236On read error or ch_close() the string "DETACH" is sent, if still possible.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100237The channel will then be inactive.
238
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100239It is also possible to use ch_sendraw() on a JSON or JS channel. The caller
240is then completely responsible for correct encoding and decoding.
241
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100242==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01002435. Channel commands *channel-commands*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100244
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100245With a JSON channel the process can send commands to Vim that will be
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100246handled by Vim internally, it does not require a handler for the channel.
247
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100248Possible commands are: *E903* *E904* *E905*
249 ["redraw" {forced}]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100250 ["ex", {Ex command}]
251 ["normal", {Normal mode command}]
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100252 ["eval", {expression}, {number}]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100253 ["expr", {expression}]
254
255With all of these: Be careful what these commands do! You can easily
256interfere with what the user is doing. To avoid trouble use |mode()| to check
257that the editor is in the expected state. E.g., to send keys that must be
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100258inserted as text, not executed as a command:
259 ["ex","if mode() == 'i' | call feedkeys('ClassName') | endif"] ~
260
261Errors in these commands are normally not reported to avoid them messing up
262the display. If you do want to see them, set the 'verbose' option to 3 or
263higher.
264
265
266Command "redraw" ~
267
268The other commands do not update the screen, so that you can send a sequence
269of commands without the cursor moving around. You must end with the "redraw"
270command to show any changed text and show the cursor where it belongs.
271
272The argument is normally an empty string:
273 ["redraw", ""] ~
274To first clear the screen pass "force":
275 ["redraw", "force"] ~
276
277
278Command "ex" ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100279
280The "ex" command is executed as any Ex command. There is no response for
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100281completion or error. You could use functions in an |autoload| script:
282 ["ex","call myscript#MyFunc(arg)"]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100283
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100284You can also use "call |feedkeys()|" to insert any key sequence.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100285
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100286
287Command "normal" ~
288
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100289The "normal" command is executed like with ":normal!", commands are not
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100290mapped. Example to open the folds under the cursor:
291 ["normal" "zO"]
292
293
294Command "eval" ~
295
296The "eval" command an be used to get the result of an expression. For
297example, to get the number of lines in the current buffer:
298 ["eval","line('$')"] ~
299
300it will send back the result of the expression:
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100301 [{number}, {result}]
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100302Here {number} is the same as what was in the request. Use a negative number
303to avoid confusion with message that Vim sends.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100304
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100305{result} is the result of the evaluation and is JSON encoded. If the
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100306evaluation fails or the result can't be encoded in JSON it is the string
307"ERROR".
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100308
309
310Command "expr" ~
311
312The "expr" command is similar to "eval", but does not send back any response.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100313Example:
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100314 ["expr","setline('$', ['one', 'two', 'three'])"] ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100315
316==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01003176. Using a RAW or NL channel *channel-raw*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100318
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100319If mode is RAW or NL then a message can be send like this: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100320 let response = ch_sendraw(channel, {string})
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100321
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100322The {string} is sent as-is. The response will be what can be read from the
323channel right away. Since Vim doesn't know how to recognize the end of the
Bram Moolenaar38a55632016-02-15 22:07:32 +0100324message you need to take care of it yourself. The timeout applies for reading
325the first byte, after that it will not wait for anything more.
326
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100327If mode is "nl" you can send a message in a similar way. You are expected
Bram Moolenaar38a55632016-02-15 22:07:32 +0100328to put in the NL after each message. Thus you can also send several messages
329ending in a NL at once. The response will be the text up to and including the
330first NL. This can also be just the NL for an empty response.
331If no NL was read before the channel timeout an empty string is returned.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100332
333To send a message, without expecting a response: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100334 call ch_sendraw(channel, {string}, 0)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100335The process can send back a response, the channel handler will be called with
336it.
337
338To send a message and letting the response handled by a specific function,
339asynchronously: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100340 call ch_sendraw(channel, {string}, {callback})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100341
Bram Moolenaar38a55632016-02-15 22:07:32 +0100342This {string} can also be JSON, use |json_encode()| to create it and
343|json_decode()| to handle a received JSON message.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100344
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100345It is not possible to use |ch_sendexpr()| on a raw channel.
346
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100347==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01003487. More channel functions *channel-more*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100349
Bram Moolenaar38a55632016-02-15 22:07:32 +0100350To obtain the status of a channel: ch_status(channel). The possible results
351are:
352 "fail" Failed to open the channel.
353 "open" The channel can be used.
354 "closed" The channel was closed.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100355
356TODO:
Bram Moolenaar38a55632016-02-15 22:07:32 +0100357To objain the job associated with a channel: ch_getjob(channel)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100358
Bram Moolenaar38a55632016-02-15 22:07:32 +0100359TODO:
360To read one message from a channel: >
361 let output = ch_read(channel)
362This uses the channel timeout. To read without a timeout, just get any
363message that is available: >
364 let output = ch_read(channel, 0)
365When no message was available then the result is v:none for a JSON or JS mode
366channels, an empty string for a RAW or NL channel.
367
368To read all output from a RAW or NL channel that is available: >
369 let output = ch_readall(channel)
370To read the error output: >
371 let output = ch_readall(channel, "err")
372TODO: use channel timeout, no timeout or specify timeout?
373
374==============================================================================
3758. Starting a job with a channel *job-start* *job*
376
377To start a job and open a channel for stdin/stdout/stderr: >
378 let job = job_start(command, {options})
379
380You can get the channel with: >
381 let channel = job_getchannel(job)
382
383The channel will use NL mode. If you want another mode it's best to specify
384this in {options}. When changing the mode later some text may have already
385been received and not parsed correctly.
386
387If the command produces a line of output that you want to deal with, specify
388a handler for stdout: >
389 let job = job_start(command, {"out-cb": "MyHandler"})
390The function will be called with the channel and a message. You would define
391it like this: >
392 func MyHandler(channel, msg)
393
394Without the handler you need to read the output with ch_read().
395
396The handler defined for "out-cb" will also receive stderr. If you want to
397handle that separately, add an "err-cb" handler: >
398 let job = job_start(command, {"out-cb": "MyHandler",
399 \ "err-cb": "ErrHandler"})
400
401You can send a message to the command with ch_sendraw(). If the channel is in
402JSON or JS mode you can use ch_sendexpr().
403
404There are several options you can use, see |job-options|.
405
406TODO:
407To run a job and read its output once it is done: >
408
409 let job = job_start({command}, {'exit-cb': 'MyHandler'})
410 func MyHandler(job, status)
411 let channel = job_getchannel()
412 let output = ch_readall(channel)
413 " parse output
414 endfunc
415
416==============================================================================
4179. Starting a job without a channel *job-start-nochannel*
418
419To start another process without creating a channel: >
420 let job = job_start(command, {"in-io": "null", "out-io": "null"})
421
422This starts {command} in the background, Vim does not wait for it to finish.
423
424TODO:
425When Vim sees that neither stdin, stdout or stderr are connected, no channel
426will be created. Often you will want to include redirection in the command to
427avoid it getting stuck.
428
429There are several options you can use, see |job-options|.
430
431TODO: *job-may-start*
432To start a job only when connecting to an address does not work use
433job_maystart('command', {address}, {options}), For Example: >
434 let job = job_maystart(command, address, {"waittime": 1000})
435 let channel = job_gethandle(job)
436
437This comes down to: >
438 let channel = ch_open(address, {"waittime": 0})
439 if ch_status(channel) == "fail"
440 let job = job_start(command)
441 let channel = ch_open(address, {"waittime": 1000})
442 call job_sethandle(channel)
443 endif
444Note that the specified waittime applies to when the job has been started.
445This gives the job some time to make the port available.
446
447==============================================================================
44810. Job options *job-options*
449
450The {options} argument in job_start() is a dictionary. All entries are
451optional. The same options can be used with job_setoptions(job, {options}).
452
453TODO: *job-out-cb*
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100454"callback": handler
Bram Moolenaar38a55632016-02-15 22:07:32 +0100455"out-cb": handler Callback for when there is something to read on
456 stdout.
457TODO: *job-err-cb*
458"err-cb": handler Callback for when there is something to read on
459 stderr. Defaults to the same callback as "out-cb".
460TODO: *job-close-cb*
461"close-cb": handler Callback for when the channel is closed. Same as
462 "close-cb" on ch_open().
463TODO: *job-exit-cb*
464"exit-cb": handler Callback for when the job ends. The arguments are the
465 job and the exit status.
466TODO: *job-killonexit*
467"killonexit": 1 Stop the job when Vim exits.
468"killonexit": 0 Do not stop the job when Vim exits.
469 The default is 1.
470TODO: *job-term*
471"term": "open" Start a terminal and connect the job
472 stdin/stdout/stderr to it.
473
474TODO: *job-in-io*
475"in-io": "null" disconnect stdin
476"in-io": "pipe" stdin is connected to the channel (default)
477"in-io": "file" stdin reads from a file
478"in-file": "/path/file" the file to read from
479
480TODO: *job-out-io*
481"out-io": "null" disconnect stdout
482"out-io": "pipe" stdout is connected to the channel (default)
483"out-io": "file" stdout writes to a file
484"out-file": "/path/file" the file to write to
485"out-io": "buffer" stdout appends to a buffer
486"out-buffer": "name" buffer to append to
487
488TODO: *job-err-io*
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100489"err-io": "out" same type as stdout (default)
Bram Moolenaar38a55632016-02-15 22:07:32 +0100490"err-io": "null" disconnect stderr
491"err-io": "pipe" stderr is connected to the channel
492"err-io": "file" stderr writes to a file
493"err-file": "/path/file" the file to write to
494"err-io": "buffer" stderr appends to a buffer
495"err-buffer": "name" buffer to append to
496
497TODO: more options
498
499
500==============================================================================
50111. Controlling a job *job-control*
502
503To get the status of a job: >
504 echo job_status(job)
505
506To make a job stop running: >
507 job_stop(job)
508
509This is the normal way to end a job. On Unix it sends a SIGTERM to the job.
510It is possible to use other ways to stop the job, or even send arbitrary
511signals. E.g. to force a job to stop, "kill it": >
512 job_stop(job, "kill")
513
514For more options see |job_stop()|.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100515
516
517 vim:tw=78:ts=8:ft=help:norl: