/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 "1" 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> " {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 <Esc> <C-W>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 "<A HREF="#terminal">terminal</A>" 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 &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 "<A HREF="change.html#!">!</A>". If a buffer
by this name already exists a number is added in
parentheses. E.g. if "<A HREF="debug.html#gdb">gdb</A>" exists the second <A HREF="#terminal">terminal</A>
buffer will use "!gdb (1)".
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 "++eof=exit" and
for <A HREF="if_pyth.html#Python">Python</A> "++eof=exit()". <A HREF="eval.html#Special">Special</A>
codes can be used like with `:map`,
e.g. "<C-Z>" 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, "kill")`
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 "rows*cols", where "rows" is the minimal number of
screen rows and "cols" is the minimal number of cells.
3. The <A HREF="options.html#'termsize'">'termsize'</A> option is "rowsXcols" (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 "rowsXcols".
<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 "(Terminal)". If
the <A HREF="channel.html#job">job</A> ends while in Terminal-Normal mode this changes to
"(Terminal-finished)".
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 "-bc" 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 <expr> <Esc>]b SendToTerm("\<Esc>]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 "some_file.c" 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 "<A HREF="debug.html#gdb">gdb</A> vim" is executed. Here you
can directly interact with <A HREF="debug.html#gdb">gdb</A>. The buffer name is "!gdb".
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 "run" 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 "<A HREF="debug.html#gdb">gdb</A> program".
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 "quit" 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 "src" 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 "<A HREF="change.html#>>">>></A>" 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 "Next" 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 "Next" a few times until the for loop is highlighted. Put the cursor on
the end of "eap->arg", then click "Eval" in the toolbar. You will see this
displayed:
<B><FONT COLOR="PURPLE"> "eap->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 "print" 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 "<A HREF="change.html#>>">>></A>" marker appear, this indicates the new breakpoint. Now
click "Cont" 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 "Cont" in the toolbar (or type "cont" in the <A HREF="debug.html#gdb">gdb</A> <A HREF="windows.html#window">window</A>). Execution
will now continue until the value of "curbuf" 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> "step" command
:Over execute the <A HREF="debug.html#gdb">gdb</A> "next" command (:Next is a Vim command)
:Finish execute the <A HREF="debug.html#gdb">gdb</A> "finish" command
:Continue execute the <A HREF="debug.html#gdb">gdb</A> "continue" 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}
:'<,'>Evaluate evaluate the Visually selected text
This is similar to using "print" 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 "<A HREF="debug.html#gdb">gdb</A> communication". 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 "termdebugger" 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 "light":
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 "dark":
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 &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 &Columns is already larger than
g:termdebug_wide then a vertical split will be used without <A HREF="change.html#changing">changing</A> &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> &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>
|