blob: a8e5857728ca3800584449567846124947d39567 [file] [log] [blame]
Bram Moolenaared997ad2019-07-21 16:42:00 +02001*channel.txt* For Vim version 8.1. Last change: 2019 Jul 21
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7 Inter-process communication *channel*
8
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01009Vim uses channels to communicate with other processes.
Bram Moolenaar269f5952016-07-15 22:54:41 +020010A channel uses a socket or pipes. *socket-interface*
Bram Moolenaar38a55632016-02-15 22:07:32 +010011Jobs can be used to start processes and communicate with them.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010012The Netbeans interface also uses a channel. |netbeans|
13
Bram Moolenaar38a55632016-02-15 22:07:32 +0100141. Overview |job-channel-overview|
152. Channel demo |channel-demo|
163. Opening a channel |channel-open|
174. Using a JSON or JS channel |channel-use|
185. Channel commands |channel-commands|
196. Using a RAW or NL channel |channel-raw|
207. More channel functions |channel-more|
Bram Moolenaared997ad2019-07-21 16:42:00 +0200218. channel functions details |channel-functions-details|
229. Starting a job with a channel |job-start|
2310. Starting a job without a channel |job-start-nochannel|
2411. Job functions |job-functions-details|
2512. Job options |job-options|
2613. Controlling a job |job-control|
2714. Using a prompt buffer |prompt-buffer|
Bram Moolenaar3b5f9292016-01-28 22:37:01 +010028
Bram Moolenaar38a55632016-02-15 22:07:32 +010029{only when compiled with the |+channel| feature for channel stuff}
Bram Moolenaarf37506f2016-08-31 22:22:10 +020030 You can check this with: `has('channel')`
Bram Moolenaar38a55632016-02-15 22:07:32 +010031{only when compiled with the |+job| feature for job stuff}
Bram Moolenaarf37506f2016-08-31 22:22:10 +020032 You can check this with: `has('job')`
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:
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200381. A daemon, serving several Vim instances.
Bram Moolenaar38a55632016-02-15 22:07:32 +010039 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
Bram Moolenaar77cdfd12016-03-12 12:57:59 +010047For when using sockets See |job-start|, |job-start-nochannel| and
48|channel-open|. For 2 and 3, one or more jobs using pipes, see |job-start|.
Bram Moolenaar38a55632016-02-15 22:07:32 +010049For 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.
Bram Moolenaar7dda86f2018-04-20 22:36:41 +020060- Using a daemon, connecting over a socket in JSON mode. E.g. to lookup
Bram Moolenaar09521312016-08-12 22:54:35 +020061 cross-references in a database.
Bram Moolenaar38a55632016-02-15 22:07:32 +010062
63==============================================================================
Bram Moolenaar26852122016-05-24 20:02:38 +0200642. Channel demo *channel-demo* *demoserver.py*
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 Moolenaar8b1862a2016-02-27 19:21:24 +010077 echo ch_evalexpr(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 Moolenaar02e83b42016-02-21 20:10:26 +010096 call ch_sendexpr(channel, 'hello!', {'callback': "MyHandler"})
Bram Moolenaar38a55632016-02-15 22:07:32 +010097Vim 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"})
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100104 call ch_sendexpr(channel, 'hello!')
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100105
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100106When trying out channels it's useful to see what is going on. You can tell
107Vim to write lines in log file: >
108 call ch_logfile('channellog', 'w')
109See |ch_logfile()|.
110
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100111==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01001123. Opening a channel *channel-open*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100113
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100114To open a channel: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100115 let channel = ch_open({address} [, {options}])
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100116 if ch_status(channel) == "open"
117 " use the channel
Bram Moolenaar38a55632016-02-15 22:07:32 +0100118
119Use |ch_status()| to see if the channel could be opened.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100120
121{address} has the form "hostname:port". E.g., "localhost:8765".
122
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100123{options} is a dictionary with optional entries: *channel-open-options*
Bram Moolenaar4d919d72016-02-05 22:36:41 +0100124
125"mode" can be: *channel-mode*
126 "json" - Use JSON, see below; most convenient way. Default.
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100127 "js" - Use JS (JavaScript) encoding, more efficient than JSON.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100128 "nl" - Use messages that end in a NL character
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100129 "raw" - Use raw messages
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100130 *channel-callback* *E921*
Bram Moolenaar38a55632016-02-15 22:07:32 +0100131"callback" A function that is called when a message is received that is
132 not handled otherwise. It gets two arguments: the channel
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100133 and the received message. Example: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100134 func Handle(channel, msg)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100135 echo 'Received: ' . a:msg
136 endfunc
Bram Moolenaar38a55632016-02-15 22:07:32 +0100137 let channel = ch_open("localhost:8765", {"callback": "Handle"})
138<
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100139 When "mode" is "json" or "js" the "msg" argument is the body
140 of the received message, converted to Vim types.
141 When "mode" is "nl" the "msg" argument is one message,
142 excluding the NL.
143 When "mode" is "raw" the "msg" argument is the whole message
144 as a string.
Bram Moolenaare18c0b32016-03-20 21:08:34 +0100145
146 For all callbacks: Use |function()| to bind it to arguments
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100147 and/or a Dictionary. Or use the form "dict.function" to bind
148 the Dictionary.
Bram Moolenaar06d2d382016-05-20 17:24:11 +0200149
150 Callbacks are only called at a "safe" moment, usually when Vim
151 is waiting for the user to type a character. Vim does not use
152 multi-threading.
153
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100154 *close_cb*
155"close_cb" A function that is called when the channel gets closed, other
Bram Moolenaar38a55632016-02-15 22:07:32 +0100156 than by calling ch_close(). It should be defined like this: >
157 func MyCloseHandler(channel)
Bram Moolenaar06d2d382016-05-20 17:24:11 +0200158< Vim will invoke callbacks that handle data before invoking
159 close_cb, thus when this function is called no more data will
Bram Moolenaar68e65602019-05-26 21:33:31 +0200160 be passed to the callbacks. However, if a callback causes Vim
161 to check for messages, the close_cb may be invoked while still
162 in the callback. The plugin must handle this somehow, it can
163 be useful to know that no more data is coming.
Bram Moolenaar958dc692016-12-01 15:34:12 +0100164 *channel-drop*
165"drop" Specifies when to drop messages:
166 "auto" When there is no callback to handle a message.
167 The "close_cb" is also considered for this.
168 "never" All messages will be kept.
169
Bram Moolenaar0b146882018-09-06 16:27:24 +0200170 *channel-noblock*
171"noblock" Same effect as |job-noblock|. Only matters for writing.
172
Bram Moolenaar06d2d382016-05-20 17:24:11 +0200173 *waittime*
Bram Moolenaar38a55632016-02-15 22:07:32 +0100174"waittime" The time to wait for the connection to be made in
Bram Moolenaarf3913272016-02-25 00:00:01 +0100175 milliseconds. A negative number waits forever.
176
177 The default is zero, don't wait, which is useful if a local
178 server is supposed to be running already. On Unix Vim
179 actually uses a 1 msec timeout, that is required on many
180 systems. Use a larger value for a remote server, e.g. 10
181 msec at least.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100182 *channel-timeout*
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100183"timeout" The time to wait for a request when blocking, E.g. when using
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100184 ch_evalexpr(). In milliseconds. The default is 2000 (2
Bram Moolenaar38a55632016-02-15 22:07:32 +0100185 seconds).
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100186
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100187When "mode" is "json" or "js" the "callback" is optional. When omitted it is
188only possible to receive a message after sending one.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100189
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100190To change the channel options after opening it use |ch_setoptions()|. The
191arguments are similar to what is passed to |ch_open()|, but "waittime" cannot
192be given, since that only applies to opening the channel.
Bram Moolenaar4d919d72016-02-05 22:36:41 +0100193
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100194For example, the handler can be added or changed: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100195 call ch_setoptions(channel, {'callback': callback})
196When "callback" is empty (zero or an empty string) the handler is removed.
197
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100198After a callback has been invoked Vim will update the screen and put the
199cursor back where it belongs. Thus the callback should not need to do
200`:redraw`.
201
Bram Moolenaar38a55632016-02-15 22:07:32 +0100202The timeout can be changed: >
203 call ch_setoptions(channel, {'timeout': msec})
204<
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100205 *channel-close* *E906*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100206Once done with the channel, disconnect it like this: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100207 call ch_close(channel)
208When a socket is used this will close the socket for both directions. When
209pipes are used (stdin/stdout/stderr) they are all closed. This might not be
210what you want! Stopping the job with job_stop() might be better.
Bram Moolenaar187db502016-02-27 14:44:26 +0100211All readahead is discarded, callbacks will no longer be invoked.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100212
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100213Note that a channel is closed in three stages:
214 - The I/O ends, log message: "Closing channel". There can still be queued
215 messages to read or callbacks to invoke.
216 - The readahead is cleared, log message: "Clearing channel". Some variables
217 may still reference the channel.
218 - The channel is freed, log message: "Freeing channel".
219
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100220When the channel can't be opened you will get an error message. There is a
221difference between MS-Windows and Unix: On Unix when the port doesn't exist
222ch_open() fails quickly. On MS-Windows "waittime" applies.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200223*E898* *E901* *E902*
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100224
225If there is an error reading or writing a channel it will be closed.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200226*E630* *E631*
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100227
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100228==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01002294. Using a JSON or JS channel *channel-use*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100230
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100231If mode is JSON then a message can be sent synchronously like this: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100232 let response = ch_evalexpr(channel, {expr})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100233This awaits a response from the other side.
234
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100235When mode is JS this works the same, except that the messages use
Bram Moolenaar38a55632016-02-15 22:07:32 +0100236JavaScript encoding. See |js_encode()| for the difference.
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100237
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100238To send a message, without handling a response or letting the channel callback
239handle the response: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100240 call ch_sendexpr(channel, {expr})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100241
242To send a message and letting the response handled by a specific function,
243asynchronously: >
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100244 call ch_sendexpr(channel, {expr}, {'callback': Handler})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100245
246Vim will match the response with the request using the message ID. Once the
247response is received the callback will be invoked. Further responses with the
248same ID will be ignored. If your server sends back multiple responses you
249need to send them with ID zero, they will be passed to the channel callback.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100250
251The {expr} is converted to JSON and wrapped in an array. An example of the
252message that the receiver will get when {expr} is the string "hello":
253 [12,"hello"] ~
254
255The format of the JSON sent is:
256 [{number},{expr}]
257
258In which {number} is different every time. It must be used in the response
259(if any):
260
261 [{number},{response}]
262
263This way Vim knows which sent message matches with which received message and
264can call the right handler. Also when the messages arrive out of order.
265
Bram Moolenaarf1f07922016-08-26 17:58:53 +0200266A newline character is terminating the JSON text. This can be used to
267separate the read text. For example, in Python:
268 splitidx = read_text.find('\n')
269 message = read_text[:splitidx]
270 rest = read_text[splitidx + 1:]
271
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100272The sender must always send valid JSON to Vim. Vim can check for the end of
273the message by parsing the JSON. It will only accept the message if the end
Bram Moolenaarf1f07922016-08-26 17:58:53 +0200274was received. A newline after the message is optional.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100275
276When the process wants to send a message to Vim without first receiving a
277message, it must use the number zero:
278 [0,{response}]
279
280Then channel handler will then get {response} converted to Vim types. If the
281channel does not have a handler the message is dropped.
282
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100283It is also possible to use ch_sendraw() and ch_evalraw() on a JSON or JS
284channel. The caller is then completely responsible for correct encoding and
285decoding.
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100286
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100287==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01002885. Channel commands *channel-commands*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100289
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100290With a JSON channel the process can send commands to Vim that will be
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100291handled by Vim internally, it does not require a handler for the channel.
292
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100293Possible commands are: *E903* *E904* *E905*
Bram Moolenaar220adb12016-09-12 12:17:26 +0200294 ["redraw", {forced}]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100295 ["ex", {Ex command}]
296 ["normal", {Normal mode command}]
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100297 ["expr", {expression}, {number}]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100298 ["expr", {expression}]
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100299 ["call", {func name}, {argument list}, {number}]
300 ["call", {func name}, {argument list}]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100301
302With all of these: Be careful what these commands do! You can easily
303interfere with what the user is doing. To avoid trouble use |mode()| to check
304that the editor is in the expected state. E.g., to send keys that must be
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100305inserted as text, not executed as a command:
306 ["ex","if mode() == 'i' | call feedkeys('ClassName') | endif"] ~
307
308Errors in these commands are normally not reported to avoid them messing up
309the display. If you do want to see them, set the 'verbose' option to 3 or
310higher.
311
312
313Command "redraw" ~
314
Bram Moolenaar63b74a82019-03-24 15:09:13 +0100315The other commands do not explicitly update the screen, so that you can send a
316sequence of commands without the cursor moving around. A redraw can happen as
317a side effect of some commands. You must end with the "redraw" command to
318show any changed text and show the cursor where it belongs.
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100319
320The argument is normally an empty string:
321 ["redraw", ""] ~
322To first clear the screen pass "force":
323 ["redraw", "force"] ~
324
325
326Command "ex" ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100327
328The "ex" command is executed as any Ex command. There is no response for
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100329completion or error. You could use functions in an |autoload| script:
330 ["ex","call myscript#MyFunc(arg)"]
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100331
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100332You can also use "call |feedkeys()|" to insert any key sequence.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100333
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100334When there is an error a message is written to the channel log, if it exists,
335and v:errmsg is set to the error.
336
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100337
338Command "normal" ~
339
Bram Moolenaar681baaf2016-02-04 20:57:07 +0100340The "normal" command is executed like with ":normal!", commands are not
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100341mapped. Example to open the folds under the cursor:
342 ["normal" "zO"]
343
344
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100345Command "expr" with response ~
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100346
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100347The "expr" command can be used to get the result of an expression. For
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100348example, to get the number of lines in the current buffer:
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100349 ["expr","line('$')", -2] ~
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100350
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100351It will send back the result of the expression:
Bram Moolenaare0fa3742016-02-20 15:47:01 +0100352 [-2, "last line"] ~
353The format is:
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100354 [{number}, {result}]
Bram Moolenaar187db502016-02-27 14:44:26 +0100355
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100356Here {number} is the same as what was in the request. Use a negative number
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100357to avoid confusion with message that Vim sends. Use a different number on
358every request to be able to match the request with the response.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100359
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100360{result} is the result of the evaluation and is JSON encoded. If the
Bram Moolenaar595e64e2016-02-07 19:19:53 +0100361evaluation fails or the result can't be encoded in JSON it is the string
362"ERROR".
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100363
364
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100365Command "expr" without a response ~
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100366
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100367This command is similar to "expr" above, but does not send back any response.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100368Example:
Bram Moolenaarfb1f6262016-01-31 20:24:32 +0100369 ["expr","setline('$', ['one', 'two', 'three'])"] ~
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100370There is no third argument in the request.
371
372
373Command "call" ~
374
375This is similar to "expr", but instead of passing the whole expression as a
376string this passes the name of a function and a list of arguments. This
377avoids the conversion of the arguments to a string and escaping and
378concatenating them. Example:
379 ["call", "line", ["$"], -2] ~
380
381Leave out the fourth argument if no response is to be sent:
382 ["call", "setline", ["$", ["one", "two", "three"]]] ~
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100383
384==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01003856. Using a RAW or NL channel *channel-raw*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100386
Bram Moolenaarc0514bf2016-11-17 14:50:09 +0100387If mode is RAW or NL then a message can be sent like this: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100388 let response = ch_evalraw(channel, {string})
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100389
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100390The {string} is sent as-is. The response will be what can be read from the
391channel right away. Since Vim doesn't know how to recognize the end of the
Bram Moolenaar38a55632016-02-15 22:07:32 +0100392message you need to take care of it yourself. The timeout applies for reading
393the first byte, after that it will not wait for anything more.
394
Bram Moolenaar910b8aa2016-02-16 21:03:07 +0100395If mode is "nl" you can send a message in a similar way. You are expected
Bram Moolenaar38a55632016-02-15 22:07:32 +0100396to put in the NL after each message. Thus you can also send several messages
397ending in a NL at once. The response will be the text up to and including the
398first NL. This can also be just the NL for an empty response.
399If no NL was read before the channel timeout an empty string is returned.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100400
401To send a message, without expecting a response: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100402 call ch_sendraw(channel, {string})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100403The process can send back a response, the channel handler will be called with
404it.
405
406To send a message and letting the response handled by a specific function,
407asynchronously: >
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100408 call ch_sendraw(channel, {string}, {'callback': 'MyHandler'})
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100409
Bram Moolenaar38a55632016-02-15 22:07:32 +0100410This {string} can also be JSON, use |json_encode()| to create it and
411|json_decode()| to handle a received JSON message.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100412
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100413It is not possible to use |ch_evalexpr()| or |ch_sendexpr()| on a raw channel.
Bram Moolenaarcbebd482016-02-07 23:02:56 +0100414
Bram Moolenaar818078d2016-08-27 21:58:42 +0200415A String in Vim cannot contain NUL bytes. To send or receive NUL bytes read
416or write from a buffer. See |in_io-buffer| and |out_io-buffer|.
417
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100418==============================================================================
Bram Moolenaar38a55632016-02-15 22:07:32 +01004197. More channel functions *channel-more*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100420
Bram Moolenaar38a55632016-02-15 22:07:32 +0100421To obtain the status of a channel: ch_status(channel). The possible results
422are:
423 "fail" Failed to open the channel.
424 "open" The channel can be used.
Bram Moolenaar06481422016-04-30 15:13:38 +0200425 "buffered" The channel was closed but there is data to read.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100426 "closed" The channel was closed.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100427
Bram Moolenaar187db502016-02-27 14:44:26 +0100428To obtain the job associated with a channel: ch_getjob(channel)
Bram Moolenaar3b5f9292016-01-28 22:37:01 +0100429
Bram Moolenaar38a55632016-02-15 22:07:32 +0100430To read one message from a channel: >
431 let output = ch_read(channel)
432This uses the channel timeout. To read without a timeout, just get any
433message that is available: >
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100434 let output = ch_read(channel, {'timeout': 0})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100435When no message was available then the result is v:none for a JSON or JS mode
Bram Moolenaar4b785f62016-11-29 21:54:44 +0100436channels, an empty string for a RAW or NL channel. You can use |ch_canread()|
437to check if there is something to read.
438
Bram Moolenaar05aafed2017-08-11 19:12:11 +0200439Note that when there is no callback, messages are dropped. To avoid that add
440a close callback to the channel.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100441
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100442To read all output from a RAW channel that is available: >
443 let output = ch_readraw(channel)
Bram Moolenaar38a55632016-02-15 22:07:32 +0100444To read the error output: >
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100445 let output = ch_readraw(channel, {"part": "err"})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100446
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100447ch_read() and ch_readraw() use the channel timeout. When there is nothing to
448read within that time an empty string is returned. To specify a different
449timeout in msec use the "timeout" option:
450 {"timeout": 123} ~
451To read from the error output use the "part" option:
452 {"part": "err"} ~
453To read a message with a specific ID, on a JS or JSON channel:
454 {"id": 99} ~
455When no ID is specified or the ID is -1, the first message is returned. This
456overrules any callback waiting for this message.
457
458For a RAW channel this returns whatever is available, since Vim does not know
459where a message ends.
460For a NL channel this returns one message.
461For a JS or JSON channel this returns one decoded message.
462This includes any sequence number.
463
Bram Moolenaar38a55632016-02-15 22:07:32 +0100464==============================================================================
Bram Moolenaared997ad2019-07-21 16:42:00 +02004658. channel functions details *channel-functions-details*
466
467ch_canread({handle}) *ch_canread()*
468 Return non-zero when there is something to read from {handle}.
469 {handle} can be a Channel or a Job that has a Channel.
470
471 This is useful to read from a channel at a convenient time,
472 e.g. from a timer.
473
474 Note that messages are dropped when the channel does not have
475 a callback. Add a close callback to avoid that.
476
477
478ch_close({handle}) *ch_close()*
479 Close {handle}. See |channel-close|.
480 {handle} can be a Channel or a Job that has a Channel.
481 A close callback is not invoked.
482
483
484ch_close_in({handle}) *ch_close_in()*
485 Close the "in" part of {handle}. See |channel-close-in|.
486 {handle} can be a Channel or a Job that has a Channel.
487 A close callback is not invoked.
488
489
490ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
491 Send {expr} over {handle}. The {expr} is encoded
492 according to the type of channel. The function cannot be used
493 with a raw channel. See |channel-use|.
494 {handle} can be a Channel or a Job that has a Channel.
495 *E917*
496 {options} must be a Dictionary. It must not have a "callback"
497 entry. It can have a "timeout" entry to specify the timeout
498 for this specific request.
499
500 ch_evalexpr() waits for a response and returns the decoded
501 expression. When there is an error or timeout it returns an
502 empty string.
503
504
505ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
506 Send {string} over {handle}.
507 {handle} can be a Channel or a Job that has a Channel.
508
509 Works like |ch_evalexpr()|, but does not encode the request or
510 decode the response. The caller is responsible for the
511 correct contents. Also does not add a newline for a channel
512 in NL mode, the caller must do that. The NL in the response
513 is removed.
514 Note that Vim does not know when the text received on a raw
515 channel is complete, it may only return the first part and you
516 need to use |ch_readraw()| to fetch the rest.
517 See |channel-use|.
518
519
520ch_getbufnr({handle}, {what}) *ch_getbufnr()*
521 Get the buffer number that {handle} is using for {what}.
522 {handle} can be a Channel or a Job that has a Channel.
523 {what} can be "err" for stderr, "out" for stdout or empty for
524 socket output.
525 Returns -1 when there is no buffer.
526
527
528ch_getjob({channel}) *ch_getjob()*
529 Get the Job associated with {channel}.
530 If there is no job calling |job_status()| on the returned Job
531 will result in "fail".
532
533
534ch_info({handle}) *ch_info()*
535 Returns a Dictionary with information about {handle}. The
536 items are:
537 "id" number of the channel
538 "status" "open", "buffered" or "closed", like
539 ch_status()
540 When opened with ch_open():
541 "hostname" the hostname of the address
542 "port" the port of the address
543 "sock_status" "open" or "closed"
544 "sock_mode" "NL", "RAW", "JSON" or "JS"
545 "sock_io" "socket"
546 "sock_timeout" timeout in msec
547 When opened with job_start():
548 "out_status" "open", "buffered" or "closed"
549 "out_mode" "NL", "RAW", "JSON" or "JS"
550 "out_io" "null", "pipe", "file" or "buffer"
551 "out_timeout" timeout in msec
552 "err_status" "open", "buffered" or "closed"
553 "err_mode" "NL", "RAW", "JSON" or "JS"
554 "err_io" "out", "null", "pipe", "file" or "buffer"
555 "err_timeout" timeout in msec
556 "in_status" "open" or "closed"
557 "in_mode" "NL", "RAW", "JSON" or "JS"
558 "in_io" "null", "pipe", "file" or "buffer"
559 "in_timeout" timeout in msec
560
561
562ch_log({msg} [, {handle}]) *ch_log()*
563 Write {msg} in the channel log file, if it was opened with
564 |ch_logfile()|.
565 When {handle} is passed the channel number is used for the
566 message.
567 {handle} can be a Channel or a Job that has a Channel. The
568 Channel must be open for the channel number to be used.
569
570
571ch_logfile({fname} [, {mode}]) *ch_logfile()*
572 Start logging channel activity to {fname}.
573 When {fname} is an empty string: stop logging.
574
575 When {mode} is omitted or "a" append to the file.
576 When {mode} is "w" start with an empty file.
577
578 Use |ch_log()| to write log messages. The file is flushed
579 after every message, on Unix you can use "tail -f" to see what
580 is going on in real time.
581
582 This function is not available in the |sandbox|.
583 NOTE: the channel communication is stored in the file, be
584 aware that this may contain confidential and privacy sensitive
585 information, e.g. a password you type in a terminal window.
586
587
588ch_open({address} [, {options}]) *ch_open()*
589 Open a channel to {address}. See |channel|.
590 Returns a Channel. Use |ch_status()| to check for failure.
591
592 {address} has the form "hostname:port", e.g.,
593 "localhost:8765".
594
595 If {options} is given it must be a |Dictionary|.
596 See |channel-open-options|.
597
598
599ch_read({handle} [, {options}]) *ch_read()*
600 Read from {handle} and return the received message.
601 {handle} can be a Channel or a Job that has a Channel.
602 For a NL channel this waits for a NL to arrive, except when
603 there is nothing more to read (channel was closed).
604 See |channel-more|.
605
606
607ch_readblob({handle} [, {options}]) *ch_readblob()*
608 Like ch_read() but reads binary data and returns a |Blob|.
609 See |channel-more|.
610
611
612ch_readraw({handle} [, {options}]) *ch_readraw()*
613 Like ch_read() but for a JS and JSON channel does not decode
614 the message. For a NL channel it does not block waiting for
615 the NL to arrive, but otherwise works like ch_read().
616 See |channel-more|.
617
618
619ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
620 Send {expr} over {handle}. The {expr} is encoded
621 according to the type of channel. The function cannot be used
622 with a raw channel.
623 See |channel-use|. *E912*
624 {handle} can be a Channel or a Job that has a Channel.
625
626
627ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()*
628 Send |String| or |Blob| {expr} over {handle}.
629 Works like |ch_sendexpr()|, but does not encode the request or
630 decode the response. The caller is responsible for the
631 correct contents. Also does not add a newline for a channel
632 in NL mode, the caller must do that. The NL in the response
633 is removed.
634 See |channel-use|.
635
636
637ch_setoptions({handle}, {options}) *ch_setoptions()*
638 Set options on {handle}:
639 "callback" the channel callback
640 "timeout" default read timeout in msec
641 "mode" mode for the whole channel
642 See |ch_open()| for more explanation.
643 {handle} can be a Channel or a Job that has a Channel.
644
645 Note that changing the mode may cause queued messages to be
646 lost.
647
648 These options cannot be changed:
649 "waittime" only applies to |ch_open()|
650
651
652ch_status({handle} [, {options}]) *ch_status()*
653 Return the status of {handle}:
654 "fail" failed to open the channel
655 "open" channel can be used
656 "buffered" channel can be read, not written to
657 "closed" channel can not be used
658 {handle} can be a Channel or a Job that has a Channel.
659 "buffered" is used when the channel was closed but there is
660 still data that can be obtained with |ch_read()|.
661
662 If {options} is given it can contain a "part" entry to specify
663 the part of the channel to return the status for: "out" or
664 "err". For example, to get the error status: >
665 ch_status(job, {"part": "err"})
666<
667
668==============================================================================
6699. Starting a job with a channel *job-start* *job*
Bram Moolenaar38a55632016-02-15 22:07:32 +0100670
671To start a job and open a channel for stdin/stdout/stderr: >
672 let job = job_start(command, {options})
673
674You can get the channel with: >
675 let channel = job_getchannel(job)
676
677The channel will use NL mode. If you want another mode it's best to specify
678this in {options}. When changing the mode later some text may have already
679been received and not parsed correctly.
680
681If the command produces a line of output that you want to deal with, specify
682a handler for stdout: >
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100683 let job = job_start(command, {"out_cb": "MyHandler"})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100684The function will be called with the channel and a message. You would define
685it like this: >
686 func MyHandler(channel, msg)
687
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100688Without the handler you need to read the output with |ch_read()| or
Bram Moolenaar06481422016-04-30 15:13:38 +0200689|ch_readraw()|. You can do this in the close callback, see |read-in-close-cb|.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100690
Bram Moolenaar1ccd8ff2017-08-11 19:50:37 +0200691Note that if the job exits before you read the output, the output may be lost.
692This depends on the system (on Unix this happens because closing the write end
693of a pipe causes the read end to get EOF). To avoid this make the job sleep
694for a short while before it exits.
695
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100696The handler defined for "out_cb" will not receive stderr. If you want to
697handle that separately, add an "err_cb" handler: >
698 let job = job_start(command, {"out_cb": "MyHandler",
699 \ "err_cb": "ErrHandler"})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100700
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100701If you want to handle both stderr and stdout with one handler use the
702"callback" option: >
703 let job = job_start(command, {"callback": "MyHandler"})
704
Bram Moolenaar3ec574f2017-06-13 18:12:01 +0200705Depending on the system, starting a job can put Vim in the background, the
706started job gets the focus. To avoid that, use the `foreground()` function.
707This might not always work when called early, put in the callback handler or
708use a timer to call it after the job has started.
709
Bram Moolenaar8b1862a2016-02-27 19:21:24 +0100710You can send a message to the command with ch_evalraw(). If the channel is in
711JSON or JS mode you can use ch_evalexpr().
Bram Moolenaar38a55632016-02-15 22:07:32 +0100712
713There are several options you can use, see |job-options|.
Bram Moolenaar187db502016-02-27 14:44:26 +0100714For example, to start a job and write its output in buffer "dummy": >
715 let logjob = job_start("tail -f /tmp/log",
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100716 \ {'out_io': 'buffer', 'out_name': 'dummy'})
Bram Moolenaar187db502016-02-27 14:44:26 +0100717 sbuf dummy
Bram Moolenaar38a55632016-02-15 22:07:32 +0100718
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100719
720Job input from a buffer ~
Bram Moolenaar818078d2016-08-27 21:58:42 +0200721 *in_io-buffer*
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100722To run a job that reads from a buffer: >
723 let job = job_start({command},
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100724 \ {'in_io': 'buffer', 'in_name': 'mybuffer'})
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100725<
726 *E915* *E918*
727The buffer is found by name, similar to |bufnr()|. The buffer must exist and
728be loaded when job_start() is called.
729
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100730By default this reads the whole buffer. This can be changed with the "in_top"
731and "in_bot" options.
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100732
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100733A special mode is when "in_top" is set to zero and "in_bot" is not set: Every
Bram Moolenaar74675a62017-07-15 13:53:23 +0200734time a line is added to the buffer, the last-but-one line will be sent to the
Bram Moolenaar5f148ec2016-03-07 22:59:26 +0100735job stdin. This allows for editing the last line and sending it when pressing
736Enter.
Bram Moolenaar0874a832016-09-01 15:11:51 +0200737 *channel-close-in*
738When not using the special mode the pipe or socket will be closed after the
739last line has been written. This signals the reading end that the input
740finished. You can also use |ch_close_in()| to close it sooner.
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100741
Bram Moolenaar063b9d12016-07-09 20:21:48 +0200742NUL bytes in the text will be passed to the job (internally Vim stores these
743as NL bytes).
744
Bram Moolenaar06481422016-04-30 15:13:38 +0200745
746Reading job output in the close callback ~
747 *read-in-close-cb*
748If the job can take some time and you don't need intermediate results, you can
749add a close callback and read the output there: >
750
751 func! CloseHandler(channel)
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200752 while ch_status(a:channel, {'part': 'out'}) == 'buffered'
Bram Moolenaar06481422016-04-30 15:13:38 +0200753 echomsg ch_read(a:channel)
754 endwhile
755 endfunc
756 let job = job_start(command, {'close_cb': 'CloseHandler'})
757
758You will want to do something more useful than "echomsg".
759
Bram Moolenaar38a55632016-02-15 22:07:32 +0100760==============================================================================
Bram Moolenaared997ad2019-07-21 16:42:00 +020076110. Starting a job without a channel *job-start-nochannel*
Bram Moolenaar38a55632016-02-15 22:07:32 +0100762
763To start another process without creating a channel: >
Bram Moolenaar328da0d2016-03-04 22:22:32 +0100764 let job = job_start(command,
Bram Moolenaar51628222016-12-01 23:03:28 +0100765 \ {"in_io": "null", "out_io": "null", "err_io": "null"})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100766
767This starts {command} in the background, Vim does not wait for it to finish.
768
Bram Moolenaar38a55632016-02-15 22:07:32 +0100769When Vim sees that neither stdin, stdout or stderr are connected, no channel
770will be created. Often you will want to include redirection in the command to
771avoid it getting stuck.
772
773There are several options you can use, see |job-options|.
774
Bram Moolenaar77cdfd12016-03-12 12:57:59 +0100775 *job-start-if-needed*
776To start a job only when connecting to an address does not work, do something
777like this: >
Bram Moolenaar38a55632016-02-15 22:07:32 +0100778 let channel = ch_open(address, {"waittime": 0})
779 if ch_status(channel) == "fail"
780 let job = job_start(command)
781 let channel = ch_open(address, {"waittime": 1000})
Bram Moolenaar38a55632016-02-15 22:07:32 +0100782 endif
Bram Moolenaar77cdfd12016-03-12 12:57:59 +0100783
784Note that the waittime for ch_open() gives the job one second to make the port
785available.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100786
787==============================================================================
Bram Moolenaared997ad2019-07-21 16:42:00 +020078811. Job functions *job-functions-details*
789
790job_getchannel({job}) *job_getchannel()*
791 Get the channel handle that {job} is using.
792 To check if the job has no channel: >
793 if string(job_getchannel()) == 'channel fail'
794<
795
796job_info([{job}]) *job_info()*
797 Returns a Dictionary with information about {job}:
798 "status" what |job_status()| returns
799 "channel" what |job_getchannel()| returns
800 "cmd" List of command arguments used to start the job
801 "process" process ID
802 "tty_in" terminal input name, empty when none
803 "tty_out" terminal output name, empty when none
804 "exitval" only valid when "status" is "dead"
805 "exit_cb" function to be called on exit
806 "stoponexit" |job-stoponexit|
807
808 Only in Unix:
809 "termsig" the signal which terminated the process
810 (See |job_stop()| for the values)
811 only valid when "status" is "dead"
812
813 Only in MS-Windows:
814 "tty_type" Type of virtual console in use.
815 Values are "winpty" or "conpty".
816 See 'termwintype'.
817
818 Without any arguments, returns a List with all Job objects.
819
820
821job_setoptions({job}, {options}) *job_setoptions()*
822 Change options for {job}. Supported are:
823 "stoponexit" |job-stoponexit|
824 "exit_cb" |job-exit_cb|
825
826
827job_start({command} [, {options}]) *job_start()*
828 Start a job and return a Job object. Unlike |system()| and
829 |:!cmd| this does not wait for the job to finish.
830 To start a job in a terminal window see |term_start()|.
831
832 If the job fails to start then |job_status()| on the returned
833 Job object results in "fail" and none of the callbacks will be
834 invoked.
835
836 {command} can be a String. This works best on MS-Windows. On
837 Unix it is split up in white-separated parts to be passed to
838 execvp(). Arguments in double quotes can contain white space.
839
840 {command} can be a List, where the first item is the executable
841 and further items are the arguments. All items are converted
842 to String. This works best on Unix.
843
844 On MS-Windows, job_start() makes a GUI application hidden. If
845 want to show it, Use |:!start| instead.
846
847 The command is executed directly, not through a shell, the
848 'shell' option is not used. To use the shell: >
849 let job = job_start(["/bin/sh", "-c", "echo hello"])
850< Or: >
851 let job = job_start('/bin/sh -c "echo hello"')
852< Note that this will start two processes, the shell and the
853 command it executes. If you don't want this use the "exec"
854 shell command.
855
856 On Unix $PATH is used to search for the executable only when
857 the command does not contain a slash.
858
859 The job will use the same terminal as Vim. If it reads from
860 stdin the job and Vim will be fighting over input, that
861 doesn't work. Redirect stdin and stdout to avoid problems: >
862 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
863<
864 The returned Job object can be used to get the status with
865 |job_status()| and stop the job with |job_stop()|.
866
867 Note that the job object will be deleted if there are no
868 references to it. This closes the stdin and stderr, which may
869 cause the job to fail with an error. To avoid this keep a
870 reference to the job. Thus instead of: >
871 call job_start('my-command')
872< use: >
873 let myjob = job_start('my-command')
874< and unlet "myjob" once the job is not needed or is past the
875 point where it would fail (e.g. when it prints a message on
876 startup). Keep in mind that variables local to a function
877 will cease to exist if the function returns. Use a
878 script-local variable if needed: >
879 let s:myjob = job_start('my-command')
880<
881 {options} must be a Dictionary. It can contain many optional
882 items, see |job-options|.
883
884
885job_status({job}) *job_status()* *E916*
886 Returns a String with the status of {job}:
887 "run" job is running
888 "fail" job failed to start
889 "dead" job died or was stopped after running
890
891 On Unix a non-existing command results in "dead" instead of
892 "fail", because a fork happens before the failure can be
893 detected.
894
895 If an exit callback was set with the "exit_cb" option and the
896 job is now detected to be "dead" the callback will be invoked.
897
898 For more information see |job_info()|.
899
900
901job_stop({job} [, {how}]) *job_stop()*
902 Stop the {job}. This can also be used to signal the job.
903
904 When {how} is omitted or is "term" the job will be terminated.
905 For Unix SIGTERM is sent. On MS-Windows the job will be
906 terminated forcedly (there is no "gentle" way).
907 This goes to the process group, thus children may also be
908 affected.
909
910 Effect for Unix:
911 "term" SIGTERM (default)
912 "hup" SIGHUP
913 "quit" SIGQUIT
914 "int" SIGINT
915 "kill" SIGKILL (strongest way to stop)
916 number signal with that number
917
918 Effect for MS-Windows:
919 "term" terminate process forcedly (default)
920 "hup" CTRL_BREAK
921 "quit" CTRL_BREAK
922 "int" CTRL_C
923 "kill" terminate process forcedly
924 Others CTRL_BREAK
925
926 On Unix the signal is sent to the process group. This means
927 that when the job is "sh -c command" it affects both the shell
928 and the command.
929
930 The result is a Number: 1 if the operation could be executed,
931 0 if "how" is not supported on the system.
932 Note that even when the operation was executed, whether the
933 job was actually stopped needs to be checked with
934 |job_status()|.
935
936 If the status of the job is "dead", the signal will not be
937 sent. This is to avoid to stop the wrong job (esp. on Unix,
938 where process numbers are recycled).
939
940 When using "kill" Vim will assume the job will die and close
941 the channel.
942
943
944==============================================================================
94512. Job options *job-options*
Bram Moolenaar38a55632016-02-15 22:07:32 +0100946
947The {options} argument in job_start() is a dictionary. All entries are
Bram Moolenaar02e83b42016-02-21 20:10:26 +0100948optional. Some options can be used after the job has started, using
949job_setoptions(job, {options}). Many options can be used with the channel
950related to the job, using ch_setoptions(channel, {options}).
951See |job_setoptions()| and |ch_setoptions()|.
Bram Moolenaar38a55632016-02-15 22:07:32 +0100952
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100953 *in_mode* *out_mode* *err_mode*
954"in_mode" mode specifically for stdin, only when using pipes
955"out_mode" mode specifically for stdout, only when using pipes
956"err_mode" mode specifically for stderr, only when using pipes
957 See |channel-mode| for the values.
958
959 Note: when setting "mode" the part specific mode is
960 overwritten. Therefore set "mode" first and the part
961 specific mode later.
962
963 Note: when writing to a file or buffer and when
964 reading from a buffer NL mode is used by default.
965
Bram Moolenaar0b146882018-09-06 16:27:24 +0200966 *job-noblock*
967"noblock": 1 When writing use a non-blocking write call. This
968 avoids getting stuck if Vim should handle other
969 messages in between, e.g. when a job sends back data
970 to Vim. It implies that when `ch_sendraw()` returns
971 not all data may have been written yet.
972 This option was added in patch 8.1.0350, test with: >
973 if has("patch-8.1.350")
974 let options['noblock'] = 1
975 endif
976<
Bram Moolenaardecb14d2016-02-20 23:32:02 +0100977 *job-callback*
978"callback": handler Callback for something to read on any part of the
979 channel.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100980 *job-out_cb* *out_cb*
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100981"out_cb": handler Callback for when there is something to read on
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100982 stdout. Only for when the channel uses pipes. When
983 "out_cb" wasn't set the channel callback is used.
Bram Moolenaar269f5952016-07-15 22:54:41 +0200984 The two arguments are the channel and the message.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100985
986 *job-err_cb* *err_cb*
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100987"err_cb": handler Callback for when there is something to read on
Bram Moolenaar4f3f6682016-03-26 23:01:59 +0100988 stderr. Only for when the channel uses pipes. When
989 "err_cb" wasn't set the channel callback is used.
Bram Moolenaar269f5952016-07-15 22:54:41 +0200990 The two arguments are the channel and the message.
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100991 *job-close_cb*
992"close_cb": handler Callback for when the channel is closed. Same as
Bram Moolenaar82af8712016-06-04 20:20:29 +0200993 "close_cb" on |ch_open()|, see |close_cb|.
Bram Moolenaarbc2eada2017-01-02 21:27:47 +0100994 *job-drop*
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +0200995"drop": when Specifies when to drop messages. Same as "drop" on
Bram Moolenaar51628222016-12-01 23:03:28 +0100996 |ch_open()|, see |channel-drop|. For "auto" the
997 exit_cb is not considered.
Bram Moolenaarbc2eada2017-01-02 21:27:47 +0100998 *job-exit_cb*
Bram Moolenaard6c2f052016-03-14 23:22:59 +0100999"exit_cb": handler Callback for when the job ends. The arguments are the
Bram Moolenaar38a55632016-02-15 22:07:32 +01001000 job and the exit status.
Bram Moolenaarb4ada792016-10-30 21:55:26 +01001001 Vim checks up to 10 times per second for jobs that
1002 ended. The check can also be triggered by calling
1003 |job_status()|, which may then invoke the exit_cb
1004 handler.
Bram Moolenaar06d2d382016-05-20 17:24:11 +02001005 Note that data can be buffered, callbacks may still be
1006 called after the process ends.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001007 *job-timeout*
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001008"timeout": time The time to wait for a request when blocking, E.g.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001009 when using ch_evalexpr(). In milliseconds. The
1010 default is 2000 (2 seconds).
1011 *out_timeout* *err_timeout*
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001012"out_timeout": time Timeout for stdout. Only when using pipes.
1013"err_timeout": time Timeout for stderr. Only when using pipes.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01001014 Note: when setting "timeout" the part specific mode is
1015 overwritten. Therefore set "timeout" first and the
1016 part specific mode later.
1017
Bram Moolenaar02e83b42016-02-21 20:10:26 +01001018 *job-stoponexit*
1019"stoponexit": {signal} Send {signal} to the job when Vim exits. See
1020 |job_stop()| for possible values.
1021"stoponexit": "" Do not stop the job when Vim exits.
1022 The default is "term".
1023
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001024 *job-term*
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001025"term": "open" Start a terminal in a new window and connect the job
1026 stdin/stdout/stderr to it. Similar to using
1027 `:terminal`.
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001028 NOTE: Not implemented yet!
Bram Moolenaar38a55632016-02-15 22:07:32 +01001029
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001030"channel": {channel} Use an existing channel instead of creating a new one.
1031 The parts of the channel that get used for the new job
1032 will be disconnected from what they were used before.
Bram Moolenaar51628222016-12-01 23:03:28 +01001033 If the channel was still used by another job this may
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001034 cause I/O errors.
1035 Existing callbacks and other settings remain.
1036
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02001037"pty": 1 Use a pty (pseudo-tty) instead of a pipe when
1038 possible. This is most useful in combination with a
1039 terminal window, see |terminal|.
1040 {only on Unix and Unix-like systems}
1041
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001042 *job-in_io* *in_top* *in_bot* *in_name* *in_buf*
1043"in_io": "null" disconnect stdin (read from /dev/null)
1044"in_io": "pipe" stdin is connected to the channel (default)
1045"in_io": "file" stdin reads from a file
1046"in_io": "buffer" stdin reads from a buffer
1047"in_top": number when using "buffer": first line to send (default: 1)
1048"in_bot": number when using "buffer": last line to send (default: last)
1049"in_name": "/path/file" the name of the file or buffer to read from
1050"in_buf": number the number of the buffer to read from
Bram Moolenaar38a55632016-02-15 22:07:32 +01001051
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001052 *job-out_io* *out_name* *out_buf*
1053"out_io": "null" disconnect stdout (goes to /dev/null)
1054"out_io": "pipe" stdout is connected to the channel (default)
1055"out_io": "file" stdout writes to a file
Bram Moolenaar51628222016-12-01 23:03:28 +01001056"out_io": "buffer" stdout appends to a buffer (see below)
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001057"out_name": "/path/file" the name of the file or buffer to write to
1058"out_buf": number the number of the buffer to write to
Bram Moolenaar9f5842e2016-05-29 16:17:08 +02001059"out_modifiable": 0 when writing to a buffer, 'modifiable' will be off
1060 (see below)
Bram Moolenaar169ebb02016-09-07 23:32:23 +02001061"out_msg": 0 when writing to a new buffer, the first line will be
1062 set to "Reading from channel output..."
Bram Moolenaar38a55632016-02-15 22:07:32 +01001063
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001064 *job-err_io* *err_name* *err_buf*
1065"err_io": "out" stderr messages to go to stdout
1066"err_io": "null" disconnect stderr (goes to /dev/null)
1067"err_io": "pipe" stderr is connected to the channel (default)
1068"err_io": "file" stderr writes to a file
Bram Moolenaar51628222016-12-01 23:03:28 +01001069"err_io": "buffer" stderr appends to a buffer (see below)
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001070"err_name": "/path/file" the name of the file or buffer to write to
1071"err_buf": number the number of the buffer to write to
Bram Moolenaar9f5842e2016-05-29 16:17:08 +02001072"err_modifiable": 0 when writing to a buffer, 'modifiable' will be off
1073 (see below)
Bram Moolenaar169ebb02016-09-07 23:32:23 +02001074"err_msg": 0 when writing to a new buffer, the first line will be
1075 set to "Reading from channel error..."
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001076
Bram Moolenaar7db8f6f2016-03-29 23:12:46 +02001077"block_write": number only for testing: pretend every other write to stdin
1078 will block
1079
Bram Moolenaar05aafed2017-08-11 19:12:11 +02001080"env": dict environment variables for the new process
1081"cwd": "/path/to/dir" current working directory for the new process;
1082 if the directory does not exist an error is given
1083
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001084
1085Writing to a buffer ~
Bram Moolenaar818078d2016-08-27 21:58:42 +02001086 *out_io-buffer*
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001087When the out_io or err_io mode is "buffer" and there is a callback, the text
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01001088is appended to the buffer before invoking the callback.
1089
1090When a buffer is used both for input and output, the output lines are put
1091above the last line, since the last line is what is written to the channel
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001092input. Otherwise lines are appended below the last line.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01001093
Bram Moolenaar328da0d2016-03-04 22:22:32 +01001094When using JS or JSON mode with "buffer", only messages with zero or negative
1095ID will be added to the buffer, after decoding + encoding. Messages with a
1096positive number will be handled by a callback, commands are handled as usual.
1097
Bram Moolenaar82af8712016-06-04 20:20:29 +02001098The name of the buffer from "out_name" or "err_name" is compared the full name
1099of existing buffers, also after expanding the name for the current directory.
1100E.g., when a buffer was created with ":edit somename" and the buffer name is
1101"somename" it will use that buffer.
1102
1103If there is no matching buffer a new buffer is created. Use an empty name to
1104always create a new buffer. |ch_getbufnr()| can then be used to get the
1105buffer number.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01001106
1107For a new buffer 'buftype' is set to "nofile" and 'bufhidden' to "hide". If
1108you prefer other settings, create the buffer first and pass the buffer number.
Bram Moolenaar169ebb02016-09-07 23:32:23 +02001109 *out_modifiable* *err_modifiable*
Bram Moolenaar9f5842e2016-05-29 16:17:08 +02001110The "out_modifiable" and "err_modifiable" options can be used to set the
1111'modifiable' option off, or write to a buffer that has 'modifiable' off. That
1112means that lines will be appended to the buffer, but the user can't easily
1113change the buffer.
Bram Moolenaar169ebb02016-09-07 23:32:23 +02001114 *out_msg* *err_msg*
1115The "out_msg" option can be used to specify whether a new buffer will have the
1116first line set to "Reading from channel output...". The default is to add the
1117message. "err_msg" does the same for channel error.
1118
Bram Moolenaar9f5842e2016-05-29 16:17:08 +02001119When an existing buffer is to be written where 'modifiable' is off and the
1120"out_modifiable" or "err_modifiable" options is not zero, an error is given
1121and the buffer will not be written to.
1122
Bram Moolenaar187db502016-02-27 14:44:26 +01001123When the buffer written to is displayed in a window and the cursor is in the
1124first column of the last line, the cursor will be moved to the newly added
1125line and the window is scrolled up to show the cursor if needed.
1126
Bram Moolenaar063b9d12016-07-09 20:21:48 +02001127Undo is synced for every added line. NUL bytes are accepted (internally Vim
1128stores these as NL bytes).
Bram Moolenaar38a55632016-02-15 22:07:32 +01001129
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001130
1131Writing to a file ~
Bram Moolenaard6c2f052016-03-14 23:22:59 +01001132 *E920*
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01001133The file is created with permissions 600 (read-write for the user, not
1134accessible for others). Use |setfperm()| to change this.
1135
1136If the file already exists it is truncated.
1137
Bram Moolenaar38a55632016-02-15 22:07:32 +01001138==============================================================================
Bram Moolenaared997ad2019-07-21 16:42:00 +0200113913. Controlling a job *job-control*
Bram Moolenaar38a55632016-02-15 22:07:32 +01001140
1141To get the status of a job: >
1142 echo job_status(job)
1143
1144To make a job stop running: >
1145 job_stop(job)
1146
1147This is the normal way to end a job. On Unix it sends a SIGTERM to the job.
1148It is possible to use other ways to stop the job, or even send arbitrary
1149signals. E.g. to force a job to stop, "kill it": >
1150 job_stop(job, "kill")
1151
1152For more options see |job_stop()|.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01001153
Bram Moolenaarf2732452018-06-03 14:47:35 +02001154==============================================================================
Bram Moolenaared997ad2019-07-21 16:42:00 +0200115514. Using a prompt buffer *prompt-buffer*
Bram Moolenaarf2732452018-06-03 14:47:35 +02001156
1157If you want to type input for the job in a Vim window you have a few options:
1158- Use a normal buffer and handle all possible commands yourself.
1159 This will be complicated, since there are so many possible commands.
1160- Use a terminal window. This works well if what you type goes directly to
1161 the job and the job output is directly displayed in the window.
1162 See |terminal-window|.
1163- Use a prompt window. This works well when entering a line for the job in Vim
1164 while displaying (possibly filtered) output from the job.
1165
1166A prompt buffer is created by setting 'buftype' to "prompt". You would
1167normally only do that in a newly created buffer.
1168
1169The user can edit and enter one line of text at the very last line of the
1170buffer. When pressing Enter in the prompt line the callback set with
1171|prompt_setcallback()| is invoked. It would normally send the line to a job.
1172Another callback would receive the output from the job and display it in the
1173buffer, below the prompt (and above the next prompt).
1174
1175Only the text in the last line, after the prompt, is editable. The rest of the
1176buffer is not modifiable with Normal mode commands. It can be modified by
1177calling functions, such as |append()|. Using other commands may mess up the
1178buffer.
1179
1180After setting 'buftype' to "prompt" Vim does not automatically start Insert
1181mode, use `:startinsert` if you want to enter Insert mode, so that the user
1182can start typing a line.
1183
1184The text of the prompt can be set with the |prompt_setprompt()| function.
1185
1186The user can go to Normal mode and navigate through the buffer. This can be
1187useful see older output or copy text.
1188
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02001189The CTRL-W key can be used to start a window command, such as CTRL-W w to
1190switch to the next window. This also works in Insert mode (use Shift-CTRL-W
1191to delete a word). When leaving the window Insert mode will be stopped. When
1192coming back to the prompt window Insert mode will be restored.
1193
Bram Moolenaarf2732452018-06-03 14:47:35 +02001194Any command that starts Insert mode, such as "a", "i", "A" and "I", will move
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02001195the cursor to the last line. "A" will move to the end of the line, "I" to the
1196start of the line.
Bram Moolenaarf2732452018-06-03 14:47:35 +02001197
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01001198
Bram Moolenaar91f84f62018-07-29 15:07:52 +02001199 vim:tw=78:ts=8:noet:ft=help:norl: