This file is indexed.

/usr/share/doc/vim/html/terminal.html is in vim-doc 2:8.0.1453-1ubuntu1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-type" content="text/html; charset=ISO-8859-1">
<TITLE>Vim documentation: terminal</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<H1>Vim documentation: terminal</H1>
<A NAME="top"></A>
<A HREF="index.html">main help file</A>

<HR>
<PRE>

*<A NAME="terminal.txt"></A><B>terminal.txt</B>*	For Vim version 8.0.  Last change: 2018 Jan 28


		  VIM REFERENCE MANUAL	  by <A HREF="intro.html#Bram">Bram</A> <A HREF="intro.html#Moolenaar">Moolenaar</A>



Terminal <A HREF="windows.html#window">window</A> support					*<A NAME="terminal"></A><B>terminal</B>*


WARNING: THIS IS ONLY PARTLY IMPLEMENTED, ANYTHING CAN STILL CHANGE

The <A HREF="#terminal">terminal</A> feature is optional, use this to check if your Vim has <A HREF="motion.html#it">it</A>:
<B>	echo has('terminal')</B>
If the result is &quot;1&quot; you have <A HREF="motion.html#it">it</A>.


1. Basic use		|<A HREF="#terminal-use">terminal-use</A>|
      Typing			|<A HREF="#terminal-typing">terminal-typing</A>|
      Size and color		|<A HREF="#terminal-size-color">terminal-size-color</A>|
      <A HREF="autocmd.html#Syntax">Syntax</A>			|<A HREF="#:terminal">:terminal</A>|
      Resizing			|<A HREF="#terminal-resizing">terminal-resizing</A>|
      Terminal Modes		|<A HREF="#Terminal-mode">Terminal-mode</A>|
      Cursor style		|<A HREF="#terminal-cursor-style">terminal-cursor-style</A>|
      <A HREF="eval.html#Special">Special</A> keys		|<A HREF="#terminal-special-keys">terminal-special-keys</A>|
      <A HREF="os_unix.html#Unix">Unix</A>			|<A HREF="#terminal-unix">terminal-unix</A>|
      <A HREF="os_win32.html#MS-Windows">MS-Windows</A>		|<A HREF="#terminal-ms-windows">terminal-ms-windows</A>|
2. Remote testing	|<A HREF="#terminal-testing">terminal-testing</A>|
3. Debugging		|<A HREF="#terminal-debug">terminal-debug</A>|
      Starting			|<A HREF="#termdebug-starting">termdebug-starting</A>|
      Example session		|<A HREF="#termdebug-example">termdebug-example</A>|
      Stepping through code	|<A HREF="#termdebug-stepping">termdebug-stepping</A>|
      Inspecting variables	|<A HREF="#termdebug-variables">termdebug-variables</A>|
      Other commands		|<A HREF="#termdebug-commands">termdebug-commands</A>|
      Communication		|<A HREF="#termdebug-communication">termdebug-communication</A>|
      Customizing		|<A HREF="#termdebug-customizing">termdebug-customizing</A>|

{Vi does not have any of these commands}
{only available when compiled with the |<A HREF="various.html#+terminal">+terminal</A>| feature}

The <A HREF="#terminal">terminal</A> feature requires the |<A HREF="various.html#+multi_byte">+multi_byte</A>|, |<A HREF="various.html#+job">+job</A>| and |<A HREF="various.html#+channel">+channel</A>| features.

==============================================================================

1. Basic use						*<A NAME="terminal-use"></A><B>terminal-use</B>*

This feature is for running a <A HREF="#terminal">terminal</A> emulator in a Vim <A HREF="windows.html#window">window</A>.  A <A HREF="channel.html#job">job</A> can be
started connected to the <A HREF="#terminal">terminal</A> emulator. For example, to run a shell:
<B>     :term bash</B>

Or to run build command:
<B>     :term make myprogram</B>

The <A HREF="channel.html#job">job</A> runs asynchronously from Vim, the <A HREF="windows.html#window">window</A> will be updated to show
output from the <A HREF="channel.html#job">job</A>, also while editing in another <A HREF="windows.html#window">window</A>.


<B><FONT COLOR="PURPLE">Typing </FONT></B>

							*<A NAME="terminal-typing"></A><B>terminal-typing</B>*
When the keyboard focus is in the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>, typed keys will be sent to
the <A HREF="channel.html#job">job</A>.  This uses a pty when possible.  You can click outside of the
<A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> to move keyboard focus elsewhere.

<A HREF="index.html#CTRL-W">CTRL-W</A> can be used to navigate between <A HREF="windows.html#windows">windows</A> and other <A HREF="index.html#CTRL-W">CTRL-W</A> commands, e.g.:
	<A HREF="index.html#CTRL-W">CTRL-W</A> <A HREF="index.html#CTRL-W">CTRL-W</A>	move focus to the next <A HREF="windows.html#window">window</A>
	<A HREF="index.html#CTRL-W">CTRL-W</A> :	enter an <A HREF="intro.html#Ex">Ex</A> command
See |<A HREF="index.html#CTRL-W">CTRL-W</A>| for more commands.


<A HREF="eval.html#Special">Special</A> in the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>:			*<A NAME="CTRL-W_."></A><B>CTRL-W_.</B>*  *<A NAME="CTRL-W_N"></A><B>CTRL-W_N</B>* 
	<A HREF="index.html#CTRL-W">CTRL-W</A> .	send a <A HREF="index.html#CTRL-W">CTRL-W</A> to the <A HREF="channel.html#job">job</A> in the <A HREF="#terminal">terminal</A>
	<A HREF="index.html#CTRL-W">CTRL-W</A> N	go to Terminal-Normal mode, see |<A HREF="#Terminal-mode">Terminal-mode</A>|
	CTRL-\ <A HREF="motion.html#CTRL-N">CTRL-N</A>   go to Terminal-Normal mode, see |<A HREF="#Terminal-mode">Terminal-mode</A>|

	<A HREF="index.html#CTRL-W">CTRL-W</A> &quot; {reg}  paste <A HREF="sponsor.html#register">register</A> {reg}		*<A NAME="CTRL-W_quote"></A><B>CTRL-W_quote</B>*
			Also works with the = <A HREF="sponsor.html#register">register</A> to insert the result of
			evaluating an <A HREF="eval.html#expression">expression</A>.
	CTRL-W CTRL-C	ends the <A HREF="channel.html#job">job</A>, see below |<A HREF="#t_CTRL-W_CTRL-C">t_CTRL-W_CTRL-C</A>|

See option <A HREF="options.html#'termkey'">'termkey'</A> for specifying another key instead of <A HREF="index.html#CTRL-W">CTRL-W</A> that
will work like <A HREF="index.html#CTRL-W">CTRL-W</A>.  However, typing <A HREF="options.html#'termkey'">'termkey'</A> <A HREF="if_cscop.html#twice">twice</A> sends <A HREF="options.html#'termkey'">'termkey'</A> to
the <A HREF="channel.html#job">job</A>.  For example:
	<A HREF="options.html#'termkey'">'termkey'</A> <A HREF="index.html#CTRL-W">CTRL-W</A>    move focus to the next <A HREF="windows.html#window">window</A>
	<A HREF="options.html#'termkey'">'termkey'</A> :	    enter an <A HREF="intro.html#Ex">Ex</A> command
	<A HREF="options.html#'termkey'">'termkey'</A> <A HREF="options.html#'termkey'">'termkey'</A> send <A HREF="options.html#'termkey'">'termkey'</A> to the <A HREF="channel.html#job">job</A> in the <A HREF="#terminal">terminal</A>
	<A HREF="options.html#'termkey'">'termkey'</A> .	    send a <A HREF="index.html#CTRL-W">CTRL-W</A> to the <A HREF="channel.html#job">job</A> in the <A HREF="#terminal">terminal</A>
	<A HREF="options.html#'termkey'">'termkey'</A> N	    go to <A HREF="#terminal">terminal</A> <A HREF="intro.html#Normal">Normal</A> mode, see below
	<A HREF="options.html#'termkey'">'termkey'</A> <A HREF="motion.html#CTRL-N">CTRL-N</A>    same <A HREF="motion.html#as">as</A> <A HREF="index.html#CTRL-W">CTRL-W</A> N
	<A HREF="options.html#'termkey'">'termkey'</A> CTRL-C    same <A HREF="motion.html#as">as</A> |<A HREF="#t_CTRL-W_CTRL-C">t_CTRL-W_CTRL-C</A>|

							*<A NAME="t_CTRL-\_CTRL-N"></A><B>t_CTRL-\_CTRL-N</B>*
The special key combination CTRL-\ <A HREF="motion.html#CTRL-N">CTRL-N</A> can be used to switch to <A HREF="intro.html#Normal">Normal</A>
mode, just like this works in any other mode.

							*<A NAME="t_CTRL-W_CTRL-C"></A><B>t_CTRL-W_CTRL-C</B>*
<A HREF="index.html#CTRL-W">CTRL-W</A> <A HREF="pattern.html#CTRL-C">CTRL-C</A> can be typed to forcefully end the <A HREF="channel.html#job">job</A>.  On <A HREF="os_win32.html#MS-Windows">MS-Windows</A> a
CTRL-BREAK will also kill the <A HREF="channel.html#job">job</A>.

If you type <A HREF="pattern.html#CTRL-C">CTRL-C</A> the effect depends on what the pty has been configured to
<A HREF="diff.html#do">do</A>.  For simple commands this causes a SIGINT to be sent to the <A HREF="channel.html#job">job</A>, which
would end <A HREF="motion.html#it">it</A>.  Other commands may ignore the SIGINT or handle the <A HREF="pattern.html#CTRL-C">CTRL-C</A>
themselves (like Vim does).

To change the keys you type use <A HREF="#terminal">terminal</A> mode mappings, see |<A HREF="map.html#:tmap">:tmap</A>|.
These are defined like any <A HREF="map.html#mapping">mapping</A>, but apply only when typing keys that are
sent to the <A HREF="channel.html#job">job</A> running in the <A HREF="#terminal">terminal</A>.  For example, to make Escape switch
to Terminal-Normal mode:
<B>   tnoremap &lt;Esc&gt; &lt;C-W&gt;N</B>

 							*<A NAME="options-in-terminal"></A><B>options-in-terminal</B>*
After opening the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> and setting <A HREF="options.html#'buftype'">'buftype'</A> to &quot;<A HREF="#terminal">terminal</A>&quot; the
<A HREF="autocmd.html#BufWinEnter">BufWinEnter</A> <A HREF="autocmd.html#autocommand">autocommand</A> event is triggered.  This makes <A HREF="motion.html#it">it</A> possible to set
<A HREF="options.html#options">options</A> specifically for the <A HREF="windows.html#window">window</A> and buffer.  Example:
<B>   au BufWinEnter * if &amp;buftype == 'terminal' | setlocal bufhidden=hide | endif</B>

Mouse events (click and drag) are passed to the <A HREF="#terminal">terminal</A>.  Mouse move events
are only passed when Vim itself is receiving them.  For a <A HREF="#terminal">terminal</A> that is
when <A HREF="options.html#'balloonevalterm'">'balloonevalterm'</A> is enabled.


<B><FONT COLOR="PURPLE">Size and color </FONT></B>

							*<A NAME="terminal-size-color"></A><B>terminal-size-color</B>*
See option <A HREF="options.html#'termsize'">'termsize'</A> for controlling the size of the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>.
(TODO: <A HREF="scroll.html#scrolling">scrolling</A> when the <A HREF="#terminal">terminal</A> is larger than the <A HREF="windows.html#window">window</A>)

The <A HREF="channel.html#job">job</A> running in the <A HREF="#terminal">terminal</A> can change the colors.  The default foreground
and background colors are taken from Vim, the <A HREF="intro.html#Normal">Normal</A> highlight group.

For a color <A HREF="#terminal">terminal</A> the <A HREF="options.html#'background'">'background'</A> option is used to decide whether the
<A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> will start with a white or black background.

To use a different color the Terminal highlight group can be used, for
example:
<B>    hi Terminal ctermbg=lightgrey ctermfg=blue guibg=lightgrey guifg=blue</B>


<B><FONT COLOR="PURPLE">Syntax </FONT></B>


:[range]ter[minal] [options] [command]			*<A NAME=":ter"></A><B>:ter</B>* *<A NAME=":terminal"></A><B>:terminal</B>*
			Open a new <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>.

			If [command] is provided run <A HREF="motion.html#it">it</A> <A HREF="motion.html#as">as</A> a <A HREF="channel.html#job">job</A> and connect
			the input and output to the <A HREF="#terminal">terminal</A>.
			If [command] is not given the <A HREF="options.html#'shell'">'shell'</A> option is used.
			if [command] is NONE no <A HREF="channel.html#job">job</A> is started, the pty of the
			<A HREF="#terminal">terminal</A> can be used by a command like <A HREF="debug.html#gdb">gdb</A>.

			A new buffer will be created, using [command] or
			<A HREF="options.html#'shell'">'shell'</A> <A HREF="motion.html#as">as</A> the name, prefixed with a &quot;<A HREF="change.html#!">!</A>&quot;.  If a buffer
			by this name already exists a number is added in
			parentheses.  E.g. if &quot;<A HREF="debug.html#gdb">gdb</A>&quot; exists the second <A HREF="#terminal">terminal</A>
			buffer will use &quot;!gdb (1)&quot;.

			If <A HREF="cmdline.html#[range]">[range]</A> is given the specified lines are used <A HREF="motion.html#as">as</A>
			input for the <A HREF="channel.html#job">job</A>.  It will not be possible to type
			keys in the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>.  For <A HREF="os_win32.html#MS-Windows">MS-Windows</A> see the
			++eof argument below.


						*<A NAME="term++close"></A><B>term++close</B>* *<A NAME="term++open"></A><B>term++open</B>*
			Supported [options] are:
			++close		The <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> will close
					automatically when the <A HREF="channel.html#job">job</A> terminates.
			++open		When the <A HREF="channel.html#job">job</A> terminates and no <A HREF="windows.html#window">window</A>
					shows <A HREF="motion.html#it">it</A>, a <A HREF="windows.html#window">window</A> will be opened.
					Note that this can be interruptive.
			++curwin	Open the <A HREF="#terminal">terminal</A> in the current
					<A HREF="windows.html#window">window</A>, <A HREF="diff.html#do">do</A> not split the current
					<A HREF="windows.html#window">window</A>.  Fails if the current buffer
					cannot be YXXYabandon|ed.
			++hidden	Open the <A HREF="#terminal">terminal</A> in a hidden buffer,
					no <A HREF="windows.html#window">window</A> will be used.
			++rows={height} Use {height} for the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>
					height.  If the <A HREF="#terminal">terminal</A> uses the full
					Vim height (no <A HREF="windows.html#window">window</A> above or below
					th <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>) the command line
					height will be reduced <A HREF="motion.html#as">as</A> needed.
			++cols={width}  Use {width} for the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>
					width. If the <A HREF="#terminal">terminal</A> uses the full
					Vim width (no <A HREF="windows.html#window">window</A> left or right of
					the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>) this value is
					ignored.
			++eof={text}	when using <A HREF="cmdline.html#[range]">[range]</A>: text to send after
					the last line was written. Cannot
					contain white space.  A CR is
					appended.  For <A HREF="os_win32.html#MS-Windows">MS-Windows</A> the default
					is to send <A HREF="scroll.html#CTRL-D">CTRL-D</A>.
					E.g. for a shell use &quot;++eof=exit&quot; and
					for <A HREF="if_pyth.html#Python">Python</A> &quot;++eof=exit()&quot;.  <A HREF="eval.html#Special">Special</A>
					codes can be used like with `:map`,
					e.g. &quot;&lt;C-Z&gt;&quot; for <A HREF="starting.html#CTRL-Z">CTRL-Z</A>.

			If you want to use more <A HREF="options.html#options">options</A> use the |<A HREF="eval.html#term_start()">term_start()</A>|
			function.

When the buffer associated with the <A HREF="#terminal">terminal</A> is unloaded or wiped out the <A HREF="channel.html#job">job</A>
is killed, similar to calling `job_stop(job, &quot;kill&quot;)`

So long <A HREF="motion.html#as">as</A> the <A HREF="channel.html#job">job</A> is running the <A HREF="windows.html#window">window</A> behaves like <A HREF="motion.html#it">it</A> contains a modified
buffer.  Trying to close the <A HREF="windows.html#window">window</A> with `CTRL-W :quit` fails.  When using
`CTRL-W :quit!` the <A HREF="channel.html#job">job</A> is ended.  The text in the <A HREF="windows.html#window">window</A> is lost.  The buffer
still exists, but getting <A HREF="motion.html#it">it</A> in a <A HREF="windows.html#window">window</A> with `:buffer` will show an empty
buffer.

Trying to close the <A HREF="windows.html#window">window</A> with `CTRL-W :close` also fails.   Using
`CTRL-W :close!` will close the <A HREF="windows.html#window">window</A> and make the buffer hidden.

You can use `CTRL-W :hide` to close the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> and make the buffer
hidden, the <A HREF="channel.html#job">job</A> keeps running.  The `:buffer` command can be used to turn the
current <A HREF="windows.html#window">window</A> into a <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>.  If there are unsaved changes this
fails, use !  to force, <A HREF="motion.html#as">as</A> usual.

To have a background <A HREF="channel.html#job">job</A> run without a <A HREF="windows.html#window">window</A>, and open the <A HREF="windows.html#window">window</A> when it's
done, use <A HREF="options.html#options">options</A> like this:
<B>	:term ++hidden ++open make</B>
Note that the <A HREF="windows.html#window">window</A> will open at an unexpected moment, this will interrupt
what you are doing.


							*<A NAME="E947"></A><B>E947</B>* *<A NAME="E948"></A><B>E948</B>*
So long <A HREF="motion.html#as">as</A> the <A HREF="channel.html#job">job</A> is running, the buffer is considered modified and Vim
cannot be quit easily, see |<A HREF="editing.html#abandon">abandon</A>|.

When the <A HREF="channel.html#job">job</A> has finished and no changes were made to the buffer: closing the
<A HREF="windows.html#window">window</A> will wipe out the buffer.

Before changes can be made to a <A HREF="#terminal">terminal</A> buffer, the <A HREF="options.html#'modifiable'">'modifiable'</A> option must
be set.  This is only possible when the <A HREF="channel.html#job">job</A> has finished.  At the first change
the buffer will become a normal buffer and the highlighting is removed.
You may want to change the buffer name with |<A HREF="editing.html#:file">:file</A>| to be able to write, since
the buffer name will still be set to the command.


<B><FONT COLOR="PURPLE">Resizing </FONT></B>

							*<A NAME="terminal-resizing"></A><B>terminal-resizing</B>*
The size of the <A HREF="#terminal">terminal</A> can be in one of three modes:

1. The <A HREF="options.html#'termsize'">'termsize'</A> option is empty: The <A HREF="#terminal">terminal</A> size follows the <A HREF="windows.html#window">window</A> size.
   The minimal size is 2 screen lines with 10 cells.

2. The <A HREF="options.html#'termsize'">'termsize'</A> option is &quot;rows*cols&quot;, where &quot;rows&quot; is the minimal number of
   screen rows and &quot;cols&quot; is the minimal number of cells.

3. The <A HREF="options.html#'termsize'">'termsize'</A> option is &quot;rowsXcols&quot; (where the <A HREF="change.html#x">x</A> is upper or lower <A HREF="change.html#case">case</A>).
   The <A HREF="#terminal">terminal</A> size is fixed to the specified number of screen lines and
   cells.  If the <A HREF="windows.html#window">window</A> is bigger there will be unused empty space.

If the <A HREF="windows.html#window">window</A> is smaller than the <A HREF="#terminal">terminal</A> size, only part of the <A HREF="#terminal">terminal</A> can
be seen (the lower-left part).

The |<A HREF="eval.html#term_getsize()">term_getsize()</A>| function can be used to get the current size of the
<A HREF="#terminal">terminal</A>.  |<A HREF="eval.html#term_setsize()">term_setsize()</A>| can be used only when in the first or second mode,
not when <A HREF="options.html#'termsize'">'termsize'</A> is &quot;rowsXcols&quot;.


<B><FONT COLOR="PURPLE">Terminal-Job and Terminal-Normal mode </FONT></B>

							*<A NAME="Terminal-mode"></A><B>Terminal-mode</B>*
When the <A HREF="channel.html#job">job</A> is running the contents of the <A HREF="#terminal">terminal</A> is under <A HREF="intro.html#control">control</A> of the
<A HREF="channel.html#job">job</A>.  That includes the cursor position.  Typed keys are sent to the <A HREF="channel.html#job">job</A>.
The <A HREF="#terminal">terminal</A> contents can change at any time.  This is called Terminal-Job
mode.

Use <A HREF="index.html#CTRL-W">CTRL-W</A> N (or <A HREF="options.html#'termkey'">'termkey'</A> N) to switch to Terminal-Normal mode.  Now the
contents of the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> is under <A HREF="intro.html#control">control</A> of Vim, the <A HREF="channel.html#job">job</A> output is
suspended.  CTRL-\ <A HREF="motion.html#CTRL-N">CTRL-N</A> does the same.

Terminal-Job mode is where |<A HREF="map.html#:tmap">:tmap</A>| mappings are applied. Keys sent by
|<A HREF="eval.html#term_sendkeys()">term_sendkeys()</A>| are not subject to tmap, but keys from |<A HREF="eval.html#feedkeys()">feedkeys()</A>| are.


							*<A NAME="E946"></A><B>E946</B>*
In Terminal-Normal mode you can move the cursor around with the usual Vim
commands, Visually <A HREF="motion.html#mark">mark</A> text, <A HREF="change.html#yank">yank</A> text, etc.  But you cannot change the
contents of the buffer.  The commands that would start insert mode, such <A HREF="motion.html#as">as</A>
'<A HREF="insert.html#i">i</A>' and '<A HREF="insert.html#a">a</A>', return to Terminal-Job mode.  The <A HREF="windows.html#window">window</A> will be updated to show
the contents of the <A HREF="#terminal">terminal</A>. |<A HREF="insert.html#:startinsert">:startinsert</A>| is ineffective.

In Terminal-Normal mode the statusline and <A HREF="windows.html#window">window</A> title show &quot;(Terminal)&quot;.  If
the <A HREF="channel.html#job">job</A> ends while in Terminal-Normal mode this changes to
&quot;(Terminal-finished)&quot;.

It is not possible to enter <A HREF="insert.html#Insert">Insert</A> mode from Terminal-Job mode.


<B><FONT COLOR="PURPLE">Cursor style </FONT></B>

							*<A NAME="terminal-cursor-style"></A><B>terminal-cursor-style</B>*
By default the cursor in the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> uses a not blinking block.  The
normal xterm <A HREF="intro.html#escape">escape</A> sequences can be used to change the blinking state and the
shape.  Once focus leaves the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> Vim will restore the original
cursor.

An exception is when xterm is started with the &quot;-bc&quot; argument, or another way
that causes the cursor to blink.  This actually means that the blinking flag
is inverted.  Since Vim cannot detect this, the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> cursor
blinking will also be inverted.


<B><FONT COLOR="PURPLE">Special keys </FONT></B>

							*<A NAME="terminal-special-keys"></A><B>terminal-special-keys</B>*
Since the <A HREF="#terminal">terminal</A> emulator simulates an xterm, only <A HREF="intro.html#escape">escape</A> sequences that
both Vim and xterm recognize will be available in the <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>.  If you
want to pass on other <A HREF="intro.html#escape">escape</A> sequences to the <A HREF="channel.html#job">job</A> running in the <A HREF="#terminal">terminal</A> you
need to set up forwarding.  Example:
<B>	tmap &lt;expr&gt; &lt;Esc&gt;]b SendToTerm("\&lt;Esc&gt;]b")</B>
<B>	func SendToTerm(what)</B>
<B>	  call term_sendkeys('', a:what)</B>
<B>	  return ''</B>
<B>	endfunc</B>


<B><FONT COLOR="PURPLE">Unix </FONT></B>

							*<A NAME="terminal-unix"></A><B>terminal-unix</B>*
On <A HREF="os_unix.html#Unix">Unix</A> a pty is used to make <A HREF="motion.html#it">it</A> possible to run all kinds of commands.  You
can even run Vim in the <A HREF="#terminal">terminal</A>!  That's used for debugging, see below.

Environment <A HREF="eval.html#variables">variables</A> are used to pass information to the running <A HREF="channel.html#job">job</A>:
    <A HREF="starting.html#TERM">TERM</A>		name of the <A HREF="#terminal">terminal</A>, <A HREF="options.html#'term'">'term'</A>
    ROWS		number of rows in the <A HREF="#terminal">terminal</A> initially
    LINES		same <A HREF="motion.html#as">as</A> ROWS
    COLUMNS		number of columns in the <A HREF="#terminal">terminal</A> initially
    COLORS		number of colors, <A HREF="term.html#'t_Co'">'t_Co'</A> (256*256*256 in the <A HREF="gui.html#GUI">GUI</A>)
    VIM_SERVERNAME	<A HREF="eval.html#v:servername">v:servername</A>

The |<A HREF="remote.html#client-server">client-server</A>| feature can be used to communicate with the Vim instance
where the <A HREF="channel.html#job">job</A> was started.  This only works when <A HREF="eval.html#v:servername">v:servername</A> is not empty.
If needed you can set <A HREF="motion.html#it">it</A> with:
<B>	call remote_startserver('vim-server')</B>

In the <A HREF="channel.html#job">job</A> you can then <A HREF="diff.html#do">do</A> something like:
<B>	vim --servername $VIM_SERVERNAME --remote +123 some_file.c</B>
This will open the file &quot;some_file.c&quot; and put the cursor on line 123.


<B><FONT COLOR="PURPLE">MS-Windows </FONT></B>

							*<A NAME="terminal-ms-windows"></A><B>terminal-ms-windows</B>*
On <A HREF="os_win32.html#MS-Windows">MS-Windows</A> winpty is used to make <A HREF="motion.html#it">it</A> possible to run all kind of commands.
Obviously, they must be commands that run in a <A HREF="#terminal">terminal</A>, not open their own
<A HREF="windows.html#window">window</A>.

You need the following two files from winpty:

    winpty.dll
    winpty-agent.exe

You can <A HREF="intro.html#download">download</A> them from the following page:

    https://github.com/rprichard/winpty

Just put the files somewhere in your PATH.  You can set the <A HREF="options.html#'winptydll'">'winptydll'</A> option
to point to the right file, if needed.  If you have both the 32-bit and 64-bit
version, rename to winpty32.dll and winpty64.dll to match the way Vim was
build.

Environment <A HREF="eval.html#variables">variables</A> are used to pass information to the running <A HREF="channel.html#job">job</A>:
    VIM_SERVERNAME	<A HREF="eval.html#v:servername">v:servername</A>

==============================================================================

2. Remote <A HREF="eval.html#testing">testing</A>					*<A NAME="terminal-testing"></A><B>terminal-testing</B>*

Most Vim tests execute a <A HREF="usr_41.html#script">script</A> inside Vim.  For some tests this does not
work, running the test interferes with the code being tested.  To avoid this
Vim is executed in a <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>.  The test sends keystrokes to <A HREF="motion.html#it">it</A> and
inspects the resulting screen state.

<B><FONT COLOR="PURPLE">Functions </FONT></B>

<A HREF="eval.html#term_sendkeys()">term_sendkeys()</A>		send keystrokes to a <A HREF="#terminal">terminal</A> (not subject to tmap)
<A HREF="eval.html#term_wait()">term_wait()</A>		wait for screen to be updated
<A HREF="eval.html#term_scrape()">term_scrape()</A>		inspect <A HREF="#terminal">terminal</A> screen


==============================================================================

3. Debugging					*<A NAME="terminal-debug"></A><B>terminal-debug</B>*

The Terminal debugging <A HREF="usr_05.html#plugin">plugin</A> can be used to debug a program with <A HREF="debug.html#gdb">gdb</A> and <A HREF="starting.html#view">view</A>
the source code in a Vim <A HREF="windows.html#window">window</A>.  Since this is completely contained inside
Vim this also works remotely over an ssh connection.


<B><FONT COLOR="PURPLE">Starting </FONT></B>

							*<A NAME="termdebug-starting"></A><B>termdebug-starting</B>*
Load the <A HREF="usr_05.html#plugin">plugin</A> with this command:
<B>	packadd termdebug</B>

 							*<A NAME=":Termdebug"></A><B>:Termdebug</B>*
To start debugging use `:Termdebug` followed by the command name, for example:
<B>	:Termdebug vim</B>

This opens two <A HREF="windows.html#windows">windows</A>:

<A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A>	A <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> in which &quot;<A HREF="debug.html#gdb">gdb</A> vim&quot; is executed.  Here you
		can directly interact with <A HREF="debug.html#gdb">gdb</A>.  The buffer name is &quot;!gdb&quot;.

program <A HREF="windows.html#window">window</A>	A <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A> for the executed program.  When &quot;run&quot; is
		used in <A HREF="debug.html#gdb">gdb</A> the program I/O will happen in this <A HREF="windows.html#window">window</A>, so
		that <A HREF="motion.html#it">it</A> does not interfere with controlling <A HREF="debug.html#gdb">gdb</A>.  The buffer
		name is &quot;<A HREF="debug.html#gdb">gdb</A> program&quot;.

The current <A HREF="windows.html#window">window</A> is used to show the source code.  When <A HREF="debug.html#gdb">gdb</A> pauses the
source file location will be displayed, if possible.  A sign is used to
highlight the current position (using highlight group debugPC).	 

If the buffer in the current <A HREF="windows.html#window">window</A> is modified, another <A HREF="windows.html#window">window</A> will be opened
to display the current <A HREF="debug.html#gdb">gdb</A> position.

Focus the <A HREF="#terminal">terminal</A> of the executed program to interact with <A HREF="motion.html#it">it</A>.  This works
the same <A HREF="motion.html#as">as</A> any command running in a <A HREF="#terminal">terminal</A> <A HREF="windows.html#window">window</A>.

When the debugger ends, typically by typing &quot;quit&quot; in the <A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A>, the two
opened <A HREF="windows.html#windows">windows</A> are closed.


<B><FONT COLOR="PURPLE">Example session </FONT></B>

							*<A NAME="termdebug-example"></A><B>termdebug-example</B>*
Start in the Vim &quot;src&quot; directory and build Vim:
<B>	% make</B>
Start Vim:
<B>	% ./vim</B>
Load the termdebug <A HREF="usr_05.html#plugin">plugin</A> and start debugging Vim:
<B>	:packadd termdebug</B>
<B>	:Termdebug vim</B>
You should now have three <A HREF="windows.html#windows">windows</A>:
    source  - where you started, has a <A HREF="windows.html#window">window</A> toolbar with buttons
    <A HREF="debug.html#gdb">gdb</A>	    - you can type <A HREF="debug.html#gdb">gdb</A> commands here
    program - the executed program will use this <A HREF="windows.html#window">window</A>
You can use <A HREF="index.html#CTRL-W">CTRL-W</A> <A HREF="index.html#CTRL-W">CTRL-W</A> or the mouse to move focus between <A HREF="windows.html#windows">windows</A>.
Put focus on the <A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A> and type:
<B>	break ex_help</B>
<B>	run</B>
Vim will start running in the program <A HREF="windows.html#window">window</A>. Put focus there and type:
<B>	:help gui</B>
Gdb will run into the ex_help breakpoint.  The source <A HREF="windows.html#window">window</A> now shows the 
ex_cmds.c file.  A &quot;<A HREF="change.html#&gt;&gt;">&gt;&gt;</A>&quot; marker will appear where the breakpoint was set.  The
line where the debugger stopped is highlighted.  You can now step through the
program.  Let's use the mouse: click on the &quot;Next&quot; button in the <A HREF="windows.html#window">window</A>
toolbar.  You will see the highlighting move <A HREF="motion.html#as">as</A> the debugger executes a line
of source code.

Click &quot;Next&quot; a few times until the for loop is highlighted.  Put the cursor on
the end of &quot;eap-&gt;arg&quot;, then click &quot;Eval&quot; in the toolbar.  You will see this
displayed:
<B><FONT COLOR="PURPLE">	"eap-&gt;arg": 0x555555e68855 "gui" </FONT></B>
This way you can inspect the value of local <A HREF="eval.html#variables">variables</A>.  You can also focus the
<A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A> and use a &quot;print&quot; command, e.g.:
<B>	print *eap</B>

Now go back to the source <A HREF="windows.html#window">window</A> and put the cursor on the first line after
the for loop, then type:
<B>	:Break</B>
You will see a &quot;<A HREF="change.html#&gt;&gt;">&gt;&gt;</A>&quot; marker appear, this indicates the new breakpoint.  Now
click &quot;Cont&quot; in the toolbar and the code until the breakpoint will be
executed.

You can type more advanced commands in the <A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A>.  For example, type:
<B>	watch curbuf</B>
Now click &quot;Cont&quot; in the toolbar (or type &quot;cont&quot; in the <A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A>). Execution
will now continue until the value of &quot;curbuf&quot; changes, which is in do_ecmd().
To remove this watchpoint again type in the <A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A>:
<B>	delete 3</B>

You can see the stack by typing in the <A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A>:
<B>	where</B>
Move through the stack frames, e.g. with:
<B>	frame 3</B>
The source <A HREF="windows.html#window">window</A> will show the code, at the point where the call was made to
a deeper level.


<B><FONT COLOR="PURPLE">Stepping through code </FONT></B>

							*<A NAME="termdebug-stepping"></A><B>termdebug-stepping</B>*
Put focus on the <A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A> to type commands there.  Some common ones are:
- <A HREF="pattern.html#CTRL-C">CTRL-C</A>	interrupt the program
- next		execute the current line and stop at the next line
- step		execute the current line and stop at the next statement,
		entering <A HREF="eval.html#functions">functions</A>
- finish	execute until leaving the current function
- where		show the stack
- frame N	go to the Nth stack frame
- continue	continue execution

In the <A HREF="windows.html#window">window</A> showing the source code these commands can used to <A HREF="intro.html#control">control</A> <A HREF="debug.html#gdb">gdb</A>:
 :Run [args]	    run the program with [args] or the previous arguments
 :Arguments {args}  set arguments for the next :Run

 :Break		set a breakpoint at the current line; a sign will be displayed
 :Delete	delete a breakpoint at the current line

 :Step		execute the <A HREF="debug.html#gdb">gdb</A> &quot;step&quot; command
 :Over 		execute the <A HREF="debug.html#gdb">gdb</A> &quot;next&quot; command (:Next is a Vim command)
 :Finish	execute the <A HREF="debug.html#gdb">gdb</A> &quot;finish&quot; command
 :Continue	execute the <A HREF="debug.html#gdb">gdb</A> &quot;continue&quot; command
 :Stop		interrupt the program

If <A HREF="options.html#'mouse'">'mouse'</A> is set the <A HREF="usr_05.html#plugin">plugin</A> adds a <A HREF="windows.html#window">window</A> toolbar with these entries:
  Step		:Step
  Next		:Over
  Finish	:Finish
  Cont		:Continue
  Stop		:Stop
  Eval		:Evaluate
This way you can use the mouse to perform the most common commands.  You need
to have the <A HREF="options.html#'mouse'">'mouse'</A> option set to enable mouse clicks.


<B><FONT COLOR="PURPLE">Inspecting variables </FONT></B>

							*<A NAME="termdebug-variables"></A><B>termdebug-variables</B>*
 :Evaluate	    evaluate the <A HREF="eval.html#expression">expression</A> under the cursor
 <A HREF="various.html#K">K</A>		    same
 :Evaluate {expr}   evaluate {expr}
 :'&lt;,'&gt;Evaluate	    evaluate the Visually selected text

This is similar to using &quot;print&quot; in the <A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A>.


<B><FONT COLOR="PURPLE">Other commands </FONT></B>

							*<A NAME="termdebug-commands"></A><B>termdebug-commands</B>*
 :Gdb	       jump to the <A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A>
 :Program      jump to the <A HREF="windows.html#window">window</A> with the running program


<B><FONT COLOR="PURPLE">Communication </FONT></B>

						*<A NAME="termdebug-communication"></A><B>termdebug-communication</B>*
There is another, hidden, buffer, which is used for Vim to communicate with
<A HREF="debug.html#gdb">gdb</A>.  The buffer name is &quot;<A HREF="debug.html#gdb">gdb</A> communication&quot;.  Do not delete this buffer, <A HREF="motion.html#it">it</A>
will break the debugger.


<B><FONT COLOR="PURPLE">Customizing </FONT></B>

							*<A NAME="termdebug-customizing"></A><B>termdebug-customizing</B>*
To change the name of the <A HREF="debug.html#gdb">gdb</A> command, set the &quot;termdebugger&quot; variable before
invoking `:Termdebug`:
<B>	let termdebugger = "mygdb"</B>

 						*<A NAME="gdb-version"></A><B>gdb-version</B>*
Only debuggers fully compatible with <A HREF="debug.html#gdb">gdb</A> will work.  Vim uses the GDB/MI
interface.  This probably requires <A HREF="debug.html#gdb">gdb</A> version 7.12.  if you get this error:
<B><FONT COLOR="PURPLE">	Undefined command: "new-ui". Try "help".</FONT></B>
Then your <A HREF="debug.html#gdb">gdb</A> is too old.


					*<A NAME="hl-debugPC"></A><B>hl-debugPC</B>* *<A NAME="hl-debugBreakpoint"></A><B>hl-debugBreakpoint</B>*
The color of the <A HREF="sign.html#signs">signs</A> can be adjusted with these highlight groups:
- debugPC		the current position
- debugBreakpoint	a breakpoint

The defaults are, when <A HREF="options.html#'background'">'background'</A> is &quot;light&quot;:
  hi debugPC term=reverse ctermbg=lightblue guibg=lightblue
  hi debugBreakpoint term=reverse ctermbg=red guibg=red

When <A HREF="options.html#'background'">'background'</A> is &quot;dark&quot;:
  hi debugPC term=reverse ctermbg=darkblue guibg=darkblue
  hi debugBreakpoint term=reverse ctermbg=red guibg=red

To change the width of the Vim <A HREF="windows.html#window">window</A> when debugging starts, and use a
vertical split:
<B>  let g:termdebug_wide = 163</B>
This will set &amp;columns to 163 when <A HREF="#:Termdebug">:Termdebug</A> is used.  The value is restored
when quitting the debugger.
If g:termdebug_wide is set and &amp;Columns is already  larger than
g:termdebug_wide then a vertical split will be used without <A HREF="change.html#changing">changing</A> &amp;columns.
Set <A HREF="motion.html#it">it</A> to 1 to get a vertical split without every <A HREF="change.html#changing">changing</A> &amp;columns (useful
for when the <A HREF="#terminal">terminal</A> can't be resized by Vim).



<A HREF="#top">top</A> - <A HREF="index.html">main help file</A>
</PRE>
</BODY>


</HTML>