428
+ − 1 \input texinfo @c -*-texinfo-*-
+ − 2 @setfilename ../info/termcap.info
+ − 3 @settitle The Termcap Library
+ − 4 @ifinfo
+ − 5 @direntry
+ − 6 * Termcap: (termcap). Termcap library of the GNU system.
+ − 7 @end direntry
+ − 8
+ − 9 This file documents the termcap library of the GNU system.
+ − 10
+ − 11 Copyright (C) 1988 Free Software Foundation, Inc.
+ − 12
+ − 13 Permission is granted to make and distribute verbatim copies of
+ − 14 this manual provided the copyright notice and this permission notice
+ − 15 are preserved on all copies.
+ − 16
+ − 17 @ignore
+ − 18 Permission is granted to process this file through TeX and print the
+ − 19 results, provided the printed document carries copying permission
+ − 20 notice identical to this one except for the removal of this paragraph
+ − 21 (this paragraph not being relevant to the printed manual).
+ − 22
+ − 23 @end ignore
+ − 24 Permission is granted to copy and distribute modified versions of this
+ − 25 manual under the conditions for verbatim copying, provided that the entire
+ − 26 resulting derived work is distributed under the terms of a permission
+ − 27 notice identical to this one.
+ − 28
+ − 29 Permission is granted to copy and distribute translations of this manual
+ − 30 into another language, under the above conditions for modified versions,
+ − 31 except that this permission notice may be stated in a translation approved
+ − 32 by the Foundation.
+ − 33 @end ifinfo
+ − 34
+ − 35 @setchapternewpage odd
+ − 36 @titlepage
+ − 37 @sp 6
+ − 38 @center @titlefont{Termcap}
+ − 39 @sp 1
+ − 40 @center The Termcap Library and Data Base
+ − 41 @sp 4
+ − 42 @center First Edition
+ − 43 @sp 1
+ − 44 @center April 1988
+ − 45 @sp 5
+ − 46 @center Richard M. Stallman
+ − 47 @sp 1
+ − 48 @center Free Software Foundation
+ − 49 @page
+ − 50 @vskip 0pt plus 1filll
+ − 51 Copyright @copyright{} 1988 Free Software Foundation, Inc.
+ − 52
+ − 53 Published by the Free Software Foundation
+ − 54 (675 Mass Ave, Cambridge MA 02139).
+ − 55 Printed copies are available for $10 each.
+ − 56
+ − 57 Permission is granted to make and distribute verbatim copies of
+ − 58 this manual provided the copyright notice and this permission notice
+ − 59 are preserved on all copies.
+ − 60
+ − 61 Permission is granted to copy and distribute modified versions of this
+ − 62 manual under the conditions for verbatim copying, provided that the entire
+ − 63 resulting derived work is distributed under the terms of a permission
+ − 64 notice identical to this one.
+ − 65
+ − 66 Permission is granted to copy and distribute translations of this manual
+ − 67 into another language, under the above conditions for modified versions,
+ − 68 except that this permission notice may be stated in a translation approved
+ − 69 by the Foundation.
+ − 70 @end titlepage
+ − 71 @page
+ − 72
+ − 73 @synindex vr fn
+ − 74
+ − 75 @node Top, Introduction, (DIR), (DIR)
+ − 76
+ − 77 @menu
+ − 78 * Introduction::What is termcap? Why this manual?
+ − 79 * Library:: The termcap library functions.
+ − 80 * Data Base:: What terminal descriptions in @file{/etc/termcap} look like.
+ − 81 * Capabilities::Definitions of the individual terminal capabilities:
+ − 82 how to write them in descriptions, and how to use
+ − 83 their values to do display updating.
+ − 84 * Summary:: Brief table of capability names and their meanings.
+ − 85 * Var Index:: Index of C functions and variables.
+ − 86 * Cap Index:: Index of termcap capabilities.
+ − 87 * Index:: Concept index.
+ − 88 @end menu
+ − 89
+ − 90 @node Introduction, Library, Top, Top
+ − 91 @unnumbered Introduction
+ − 92
+ − 93 @cindex termcap
+ − 94 @dfn{Termcap} is a library and data base that enables programs to use
+ − 95 display terminals in a terminal-independent manner. It originated in
+ − 96 Berkeley Unix.
+ − 97
+ − 98 The termcap data base describes the capabilities of hundreds of different
+ − 99 display terminals in great detail. Some examples of the information
+ − 100 recorded for a terminal could include how many columns wide it is, what
+ − 101 string to send to move the cursor to an arbitrary position (including how
+ − 102 to encode the row and column numbers), how to scroll the screen up one or
+ − 103 several lines, and how much padding is needed for such a scrolling
+ − 104 operation.
+ − 105
+ − 106 The termcap library is provided for easy access this data base in programs
+ − 107 that want to do terminal-independent character-based display output.
+ − 108
+ − 109 This manual describes the GNU version of the termcap library, which has
+ − 110 some extensions over the Unix version. All the extensions are identified
+ − 111 as such, so this manual also tells you how to use the Unix termcap.
+ − 112
+ − 113 The GNU version of the termcap library is available free as source code,
+ − 114 for use in free programs, and runs on Unix and VMS systems (at least). You
+ − 115 can find it in the GNU Emacs distribution in the files @file{termcap.c} and
+ − 116 @file{tparam.c}.
+ − 117
+ − 118 This manual was written for the GNU project, whose goal is to develop a
+ − 119 complete free operating system upward-compatible with Unix for user
+ − 120 programs. The project is approximately two thirds complete. For more
+ − 121 information on the GNU project, including the GNU Emacs editor and the
+ − 122 mostly-portable optimizing C compiler, send one dollar to
+ − 123
+ − 124 @display
+ − 125 Free Software Foundation
+ − 126 675 Mass Ave
+ − 127 Cambridge, MA 02139
+ − 128 @end display
+ − 129
+ − 130 @node Library, Data Base, Introduction, Top
+ − 131 @chapter The Termcap Library
+ − 132
+ − 133 The termcap library is the application programmer's interface to the
+ − 134 termcap data base. It contains functions for the following purposes:
+ − 135
+ − 136 @itemize @bullet
+ − 137 @item
+ − 138 Finding the description of the user's terminal type (@code{tgetent}).
+ − 139
+ − 140 @item
+ − 141 Interrogating the description for information on various topics
+ − 142 (@code{tgetnum}, @code{tgetflag}, @code{tgetstr}).
+ − 143
+ − 144 @item
+ − 145 Computing and performing padding (@code{tputs}).
+ − 146
+ − 147 @item
+ − 148 Encoding numeric parameters such as cursor positions into the
+ − 149 terminal-specific form required for display commands (@code{tparam},
+ − 150 @code{tgoto}).
+ − 151 @end itemize
+ − 152
+ − 153 @menu
+ − 154 * Preparation:: Preparing to use the termcap library.
+ − 155 * Find:: Finding the description of the terminal being used.
+ − 156 * Interrogate:: Interrogating the description for particular capabilities.
+ − 157 * Initialize:: Initialization for output using termcap.
+ − 158 * Padding:: Outputting padding.
+ − 159 * Parameters:: Encoding parameters such as cursor positions.
+ − 160 @end menu
+ − 161
+ − 162 @node Preparation, Find, Library, Library
+ − 163 @section Preparing to Use the Termcap Library
+ − 164
+ − 165 To use the termcap library in a program, you need two kinds of preparation:
+ − 166
+ − 167 @itemize @bullet
+ − 168 @item
+ − 169 The compiler needs declarations of the functions and variables in the
+ − 170 library.
+ − 171
+ − 172 On GNU systems, it suffices to include the header file
+ − 173 @file{termcap.h} in each source file that uses these functions and
+ − 174 variables.@refill
+ − 175
+ − 176 On Unix systems, there is often no such header file. Then you must
4312
+ − 177 explicitly declare the variables as external. You can do likewise for
428
+ − 178 the functions, or let them be implicitly declared and cast their
+ − 179 values from type @code{int} to the appropriate type.
+ − 180
+ − 181 We illustrate the declarations of the individual termcap library
+ − 182 functions with ANSI C prototypes because they show how to pass the
+ − 183 arguments. If you are not using the GNU C compiler, you probably
+ − 184 cannot use function prototypes, so omit the argument types and names
+ − 185 from your declarations.
+ − 186
+ − 187 @item
+ − 188 The linker needs to search the library. Usually either
+ − 189 @samp{-ltermcap} or @samp{-ltermlib} as an argument when linking will
+ − 190 do this.@refill
+ − 191 @end itemize
+ − 192
+ − 193 @node Find, Interrogate, Preparation, Library
+ − 194 @section Finding a Terminal Description: @code{tgetent}
+ − 195
+ − 196 @findex tgetent
+ − 197 An application program that is going to use termcap must first look up the
+ − 198 description of the terminal type in use. This is done by calling
+ − 199 @code{tgetent}, whose declaration in ANSI Standard C looks like:
+ − 200
+ − 201 @example
+ − 202 int tgetent (char *@var{buffer}, char *@var{termtype});
+ − 203 @end example
+ − 204
+ − 205 @noindent
+ − 206 This function finds the description and remembers it internally so that
+ − 207 you can interrogate it about specific terminal capabilities
+ − 208 (@pxref{Interrogate}).
+ − 209
+ − 210 The argument @var{termtype} is a string which is the name for the type of
+ − 211 terminal to look up. Usually you would obtain this from the environment
+ − 212 variable @code{TERM} using @code{getenv ("TERM")}.
+ − 213
+ − 214 If you are using the GNU version of termcap, you can alternatively ask
+ − 215 @code{tgetent} to allocate enough space. Pass a null pointer for
+ − 216 @var{buffer}, and @code{tgetent} itself allocates the storage using
+ − 217 @code{malloc}. In this case the returned value on success is the address
+ − 218 of the storage, cast to @code{int}. But normally there is no need for you
+ − 219 to look at the address. Do not free the storage yourself.@refill
+ − 220
+ − 221 With the Unix version of termcap, you must allocate space for the
+ − 222 description yourself and pass the address of the space as the argument
+ − 223 @var{buffer}. There is no way you can tell how much space is needed, so
+ − 224 the convention is to allocate a buffer 2048 characters long and assume that
+ − 225 is enough. (Formerly the convention was to allocate 1024 characters and
+ − 226 assume that was enough. But one day, for one kind of terminal, that was
+ − 227 not enough.)
+ − 228
+ − 229 No matter how the space to store the description has been obtained,
+ − 230 termcap records its address internally for use when you later interrogate
+ − 231 the description with @code{tgetnum}, @code{tgetstr} or @code{tgetflag}. If
+ − 232 the buffer was allocated by termcap, it will be freed by termcap too if you
+ − 233 call @code{tgetent} again. If the buffer was provided by you, you must
+ − 234 make sure that its contents remain unchanged for as long as you still plan
+ − 235 to interrogate the description.@refill
+ − 236
+ − 237 The return value of @code{tgetent} is @minus{}1 if there is some difficulty
+ − 238 accessing the data base of terminal types, 0 if the data base is accessible
+ − 239 but the specified type is not defined in it, and some other value
+ − 240 otherwise.
+ − 241
+ − 242 Here is how you might use the function @code{tgetent}:
+ − 243
+ − 244 @example
+ − 245 #ifdef unix
+ − 246 static char term_buffer[2048];
+ − 247 #else
+ − 248 #define term_buffer 0
+ − 249 #endif
+ − 250
+ − 251 init_terminal_data ()
+ − 252 @{
+ − 253 char *termtype = getenv ("TERM");
+ − 254 int success;
+ − 255
+ − 256 if (termtype == 0)
+ − 257 fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
+ − 258
+ − 259 success = tgetent (term_buffer, termtype);
+ − 260 if (success < 0)
+ − 261 fatal ("Could not access the termcap data base.\n");
+ − 262 if (success == 0)
+ − 263 fatal ("Terminal type `%s' is not defined.\n", termtype);
+ − 264 @}
+ − 265 @end example
+ − 266
+ − 267 @noindent
+ − 268 Here we assume the function @code{fatal} prints an error message and exits.
+ − 269
+ − 270 If the environment variable @code{TERMCAP} is defined, its value is used to
+ − 271 override the terminal type data base. The function @code{tgetent} checks
+ − 272 the value of @code{TERMCAP} automatically. If the value starts with
+ − 273 @samp{/} then it is taken as a file name to use as the data base file,
+ − 274 instead of @file{/etc/termcap} which is the standard data base. If the
+ − 275 value does not start with @samp{/} then it is itself used as the terminal
+ − 276 description, provided that the terminal type @var{termtype} is among the
+ − 277 types it claims to apply to. @xref{Data Base}, for information on the
+ − 278 format of a terminal description.@refill
+ − 279
+ − 280 @node Interrogate, Initialize, Find, Library
+ − 281 @section Interrogating the Terminal Description
+ − 282
+ − 283 Each piece of information recorded in a terminal description is called a
+ − 284 @dfn{capability}. Each defined terminal capability has a two-letter code
+ − 285 name and a specific meaning. For example, the number of columns is named
+ − 286 @samp{co}. @xref{Capabilities}, for definitions of all the standard
+ − 287 capability names.
+ − 288
+ − 289 Once you have found the proper terminal description with @code{tgetent}
+ − 290 (@pxref{Find}), your application program must @dfn{interrogate} it for
+ − 291 various terminal capabilities. You must specify the two-letter code of
+ − 292 the capability whose value you seek.
+ − 293
+ − 294 Capability values can be numeric, boolean (capability is either present or
+ − 295 absent) or strings. Any particular capability always has the same value
+ − 296 type; for example, @samp{co} always has a numeric value, while @samp{am}
+ − 297 (automatic wrap at margin) is always a flag, and @samp{cm} (cursor motion
+ − 298 command) always has a string value. The documentation of each capability
+ − 299 says which type of value it has.@refill
+ − 300
+ − 301 There are three functions to use to get the value of a capability,
+ − 302 depending on the type of value the capability has. Here are their
+ − 303 declarations in ANSI C:
+ − 304
+ − 305 @findex tgetnum
+ − 306 @findex tgetflag
+ − 307 @findex tgetstr
+ − 308 @example
+ − 309 int tgetnum (char *@var{name});
+ − 310 int tgetflag (char *@var{name});
+ − 311 char *tgetstr (char *@var{name}, char **@var{area});
+ − 312 @end example
+ − 313
+ − 314 @table @code
+ − 315 @item tgetnum
+ − 316 Use @code{tgetnum} to get a capability value that is numeric. The
+ − 317 argument @var{name} is the two-letter code name of the capability. If
+ − 318 the capability is present, @code{tgetnum} returns the numeric value
+ − 319 (which is nonnegative). If the capability is not mentioned in the
+ − 320 terminal description, @code{tgetnum} returns @minus{}1.
+ − 321
+ − 322 @item tgetflag
+ − 323 Use @code{tgetflag} to get a boolean value. If the capability
+ − 324 @var{name} is present in the terminal description, @code{tgetflag}
+ − 325 returns 1; otherwise, it returns 0.
+ − 326
+ − 327 @item tgetstr
+ − 328 Use @code{tgetstr} to get a string value. It returns a pointer to a
+ − 329 string which is the capability value, or a null pointer if the
+ − 330 capability is not present in the terminal description.
+ − 331
+ − 332 There are two ways @code{tgetstr} can find space to store the string value:
+ − 333
+ − 334 @itemize @bullet
+ − 335 @item
+ − 336 You can ask @code{tgetstr} to allocate the space. Pass a null
+ − 337 pointer for the argument @var{area}, and @code{tgetstr} will use
+ − 338 @code{malloc} to allocate storage big enough for the value.
+ − 339 Termcap will never free this storage or refer to it again; you
+ − 340 should free it when you are finished with it.
+ − 341
+ − 342 This method is more robust, since there is no need to guess how
+ − 343 much space is needed. But it is supported only by the GNU
+ − 344 termcap library.
+ − 345
+ − 346 @item
+ − 347 You can provide the space. Provide for the argument @var{area} the
+ − 348 address of a pointer variable of type @code{char *}. Before calling
+ − 349 @code{tgetstr}, initialize the variable to point at available space.
+ − 350 Then @code{tgetstr} will store the string value in that space and will
+ − 351 increment the pointer variable to point after the space that has been
+ − 352 used. You can use the same pointer variable for many calls to
+ − 353 @code{tgetstr}.
+ − 354
+ − 355 There is no way to determine how much space is needed for a single
+ − 356 string, and no way for you to prevent or handle overflow of the area
+ − 357 you have provided. However, you can be sure that the total size of
+ − 358 all the string values you will obtain from the terminal description is
+ − 359 no greater than the size of the description (unless you get the same
+ − 360 capability twice). You can determine that size with @code{strlen} on
+ − 361 the buffer you provided to @code{tgetent}. See below for an example.
+ − 362
+ − 363 Providing the space yourself is the only method supported by the Unix
+ − 364 version of termcap.
+ − 365 @end itemize
+ − 366 @end table
+ − 367
+ − 368 Note that you do not have to specify a terminal type or terminal
+ − 369 description for the interrogation functions. They automatically use the
+ − 370 description found by the most recent call to @code{tgetent}.
+ − 371
+ − 372 Here is an example of interrogating a terminal description for various
+ − 373 capabilities, with conditionals to select between the Unix and GNU methods
+ − 374 of providing buffer space.
+ − 375
+ − 376 @example
+ − 377 char *tgetstr ();
+ − 378
+ − 379 char *cl_string, *cm_string;
+ − 380 int height;
+ − 381 int width;
+ − 382 int auto_wrap;
+ − 383
+ − 384 char PC; /* For tputs. */
+ − 385 char *BC; /* For tgoto. */
+ − 386 char *UP;
+ − 387
+ − 388 interrogate_terminal ()
+ − 389 @{
+ − 390 #ifdef UNIX
+ − 391 /* Here we assume that an explicit term_buffer
+ − 392 was provided to tgetent. */
+ − 393 char *buffer
+ − 394 = (char *) malloc (strlen (term_buffer));
+ − 395 #define BUFFADDR &buffer
+ − 396 #else
+ − 397 #define BUFFADDR 0
+ − 398 #endif
+ − 399
+ − 400 char *temp;
+ − 401
+ − 402 /* Extract information we will use. */
+ − 403 cl_string = tgetstr ("cl", BUFFADDR);
+ − 404 cm_string = tgetstr ("cm", BUFFADDR);
+ − 405 auto_wrap = tgetflag ("am");
+ − 406 height = tgetnum ("li");
+ − 407 width = tgetnum ("co");
+ − 408
+ − 409 /* Extract information that termcap functions use. */
+ − 410 temp = tgetstr ("pc", BUFFADDR);
+ − 411 PC = temp ? *temp : 0;
+ − 412 BC = tgetstr ("le", BUFFADDR);
+ − 413 UP = tgetstr ("up", BUFFADDR);
+ − 414 @}
+ − 415 @end example
+ − 416
+ − 417 @noindent
+ − 418 @xref{Padding}, for information on the variable @code{PC}. @xref{Using
+ − 419 Parameters}, for information on @code{UP} and @code{BC}.
+ − 420
+ − 421 @node Initialize, Padding, Interrogate, Library
+ − 422 @section Initialization for Use of Termcap
+ − 423 @cindex terminal flags (kernel)
+ − 424
+ − 425 Before starting to output commands to a terminal using termcap,
+ − 426 an application program should do two things:
+ − 427
+ − 428 @itemize @bullet
+ − 429 @item
+ − 430 Initialize various global variables which termcap library output
+ − 431 functions refer to. These include @code{PC} and @code{ospeed} for
+ − 432 padding (@pxref{Output Padding}) and @code{UP} and @code{BC} for
+ − 433 cursor motion (@pxref{tgoto}).@refill
+ − 434
+ − 435 @item
+ − 436 Tell the kernel to turn off alteration and padding of horizontal-tab
+ − 437 characters sent to the terminal.
+ − 438 @end itemize
+ − 439
+ − 440 To turn off output processing in Berkeley Unix you would use @code{ioctl}
+ − 441 with code @code{TIOCLSET} to set the bit named @code{LLITOUT}, and clear
+ − 442 the bits @code{ANYDELAY} using @code{TIOCSETN}. In POSIX or System V, you
+ − 443 must clear the bit named @code{OPOST}. Refer to the system documentation
+ − 444 for details.@refill
+ − 445
+ − 446 If you do not set the terminal flags properly, some older terminals will
+ − 447 not work. This is because their commands may contain the characters that
+ − 448 normally signify newline, carriage return and horizontal tab---characters
+ − 449 which the kernel thinks it ought to modify before output.
+ − 450
+ − 451 When you change the kernel's terminal flags, you must arrange to restore
+ − 452 them to their normal state when your program exits. This implies that the
+ − 453 program must catch fatal signals such as @code{SIGQUIT} and @code{SIGINT}
+ − 454 and restore the old terminal flags before actually terminating.
+ − 455
+ − 456 Modern terminals' commands do not use these special characters, so if you
+ − 457 do not care about problems with old terminals, you can leave the kernel's
+ − 458 terminal flags unaltered.
+ − 459
+ − 460 @node Padding, Parameters, Initialize, Library
+ − 461 @section Padding
+ − 462 @cindex padding
+ − 463
+ − 464 @dfn{Padding} means outputting null characters following a terminal display
+ − 465 command that takes a long time to execute. The terminal description says
+ − 466 which commands require padding and how much; the function @code{tputs},
+ − 467 described below, outputs a terminal command while extracting from it the
+ − 468 padding information, and then outputs the padding that is necessary.
+ − 469
+ − 470 @menu
+ − 471 * Why Pad:: Explanation of padding.
+ − 472 * Describe Padding:: The data base says how much padding a terminal needs.
+ − 473 * Output Padding:: Using @code{tputs} to output the needed padding.
+ − 474 @end menu
+ − 475
+ − 476 @node Why Pad, Describe Padding, Padding, Padding
+ − 477 @subsection Why Pad, and How
+ − 478
+ − 479 Most types of terminal have commands that take longer to execute than they
+ − 480 do to send over a high-speed line. For example, clearing the screen may
+ − 481 take 20msec once the entire command is received. During that time, on a
+ − 482 9600 bps line, the terminal could receive about 20 additional output
+ − 483 characters while still busy clearing the screen. Every terminal has a
+ − 484 certain amount of buffering capacity to remember output characters that
+ − 485 cannot be processed yet, but too many slow commands in a row can cause the
+ − 486 buffer to fill up. Then any additional output that cannot be processed
+ − 487 immediately will be lost.
+ − 488
+ − 489 To avoid this problem, we normally follow each display command with enough
4312
+ − 490 useless characters (usually null characters) to fill up the time that the
428
+ − 491 display command needs to execute. This does the job if the terminal throws
+ − 492 away null characters without using up space in the buffer (which most
+ − 493 terminals do). If enough padding is used, no output can ever be lost. The
+ − 494 right amount of padding avoids loss of output without slowing down
+ − 495 operation, since the time used to transmit padding is time that nothing
+ − 496 else could be done.
+ − 497
+ − 498 The number of padding characters needed for an operation depends on the
+ − 499 line speed. In fact, it is proportional to the line speed. A 9600 baud
+ − 500 line transmits about one character per msec, so the clear screen command in
+ − 501 the example above would need about 20 characters of padding. At 1200 baud,
+ − 502 however, only about 3 characters of padding are needed to fill up 20msec.
+ − 503
+ − 504 @node Describe Padding, Output Padding, Why Pad, Padding
+ − 505 @subsection Specifying Padding in a Terminal Description
+ − 506
+ − 507 In the terminal description, the amount of padding required by each display
+ − 508 command is recorded as a sequence of digits at the front of the command.
+ − 509 These digits specify the padding time in msec. They can be followed
+ − 510 optionally by a decimal point and one more digit, which is a number of
+ − 511 tenths of msec.
+ − 512
+ − 513 Sometimes the padding needed by a command depends on the cursor position.
+ − 514 For example, the time taken by an ``insert line'' command is usually
+ − 515 proportional to the number of lines that need to be moved down or cleared.
+ − 516 An asterisk (@samp{*}) following the padding time says that the time
+ − 517 should be multiplied by the number of screen lines affected by the command.
+ − 518
+ − 519 @example
+ − 520 :al=1.3*\E[L:
+ − 521 @end example
+ − 522
+ − 523 @noindent
+ − 524 is used to describe the ``insert line'' command for a certain terminal.
+ − 525 The padding required is 1.3 msec per line affected. The command itself is
+ − 526 @samp{@key{ESC} [ L}.
+ − 527
+ − 528 The padding time specified in this way tells @code{tputs} how many pad
+ − 529 characters to output. @xref{Output Padding}.
+ − 530
+ − 531 Two special capability values affect padding for all commands. These are
+ − 532 the @samp{pc} and @samp{pb}. The variable @samp{pc} specifies the
+ − 533 character to pad with, and @samp{pb} the speed below which no padding is
+ − 534 needed. The defaults for these variables, a null character and 0,
+ − 535 are correct for most terminals. @xref{Pad Specs}.
+ − 536
+ − 537 @node Output Padding,, Describe Padding, Padding
+ − 538 @subsection Performing Padding with @code{tputs}
+ − 539 @cindex line speed
+ − 540
+ − 541 @findex tputs
+ − 542 Use the termcap function @code{tputs} to output a string containing an
+ − 543 optional padding spec of the form described above (@pxref{Describe
+ − 544 Padding}). The function @code{tputs} strips off and decodes the padding
+ − 545 spec, outputs the rest of the string, and then outputs the appropriate
+ − 546 padding. Here is its declaration in ANSI C:
+ − 547
+ − 548 @example
+ − 549 char PC;
+ − 550 short ospeed;
+ − 551
+ − 552 int tputs (char *@var{string}, int @var{nlines}, int (*@var{outfun}) ());
+ − 553 @end example
+ − 554
+ − 555 Here @var{string} is the string (including padding spec) to be output;
+ − 556 @var{nlines} is the number of lines affected by the operation, which is
+ − 557 used to multiply the amount of padding if the padding spec ends with a
+ − 558 @samp{*}. Finally, @var{outfun} is a function (such as @code{fputchar})
+ − 559 that is called to output each character. When actually called,
+ − 560 @var{outfun} should expect one argument, a character.
+ − 561
+ − 562 @vindex ospeed
+ − 563 @vindex PC
+ − 564 The operation of @code{tputs} is controlled by two global variables,
+ − 565 @code{ospeed} and @code{PC}. The value of @code{ospeed} is supposed to be
+ − 566 the terminal output speed, encoded as in the @code{ioctl} system call which
+ − 567 gets the speed information. This is needed to compute the number of
+ − 568 padding characters. The value of @code{PC} is the character used for
+ − 569 padding.
+ − 570
+ − 571 You are responsible for storing suitable values into these variables before
+ − 572 using @code{tputs}. The value stored into the @code{PC} variable should be
+ − 573 taken from the @samp{pc} capability in the terminal description (@pxref{Pad
+ − 574 Specs}). Store zero in @code{PC} if there is no @samp{pc}
+ − 575 capability.@refill
+ − 576
+ − 577 The argument @var{nlines} requires some thought. Normally, it should be
+ − 578 the number of lines whose contents will be cleared or moved by the command.
+ − 579 For cursor motion commands, or commands that do editing within one line,
+ − 580 use the value 1. For most commands that affect multiple lines, such as
+ − 581 @samp{al} (insert a line) and @samp{cd} (clear from the cursor to the end
+ − 582 of the screen), @var{nlines} should be the screen height minus the current
+ − 583 vertical position (origin 0). For multiple insert and scroll commands such
+ − 584 as @samp{AL} (insert multiple lines), that same value for @var{nlines} is
+ − 585 correct; the number of lines being inserted is @i{not} correct.@refill
+ − 586
+ − 587 If a ``scroll window'' feature is used to reduce the number of lines
+ − 588 affected by a command, the value of @var{nlines} should take this into
+ − 589 account. This is because the delay time required depends on how much work
+ − 590 the terminal has to do, and the scroll window feature reduces the work.
+ − 591 @xref{Scrolling}.
+ − 592
+ − 593 Commands such as @samp{ic} and @samp{dc} (insert or delete characters) are
+ − 594 problematical because the padding needed by these commands is proportional
+ − 595 to the number of characters affected, which is the number of columns from
+ − 596 the cursor to the end of the line. It would be nice to have a way to
+ − 597 specify such a dependence, and there is no need for dependence on vertical
+ − 598 position in these commands, so it is an obvious idea to say that for these
+ − 599 commands @var{nlines} should really be the number of columns affected.
+ − 600 However, the definition of termcap clearly says that @var{nlines} is always
+ − 601 the number of lines affected, even in this case, where it is always 1. It
+ − 602 is not easy to change this rule now, because too many programs and terminal
+ − 603 descriptions have been written to follow it.
+ − 604
+ − 605 Because @var{nlines} is always 1 for the @samp{ic} and @samp{dc} strings,
+ − 606 there is no reason for them to use @samp{*}, but some of them do. These
+ − 607 should be corrected by deleting the @samp{*}. If, some day, such entries
+ − 608 have disappeared, it may be possible to change to a more useful convention
+ − 609 for the @var{nlines} argument for these operations without breaking any
+ − 610 programs.
+ − 611
+ − 612 @node Parameters,, Padding, Library
+ − 613 @section Filling In Parameters
+ − 614 @cindex parameters
+ − 615
+ − 616 Some terminal control strings require numeric @dfn{parameters}. For
+ − 617 example, when you move the cursor, you need to say what horizontal and
+ − 618 vertical positions to move it to. The value of the terminal's @samp{cm}
+ − 619 capability, which says how to move the cursor, cannot simply be a string of
+ − 620 characters; it must say how to express the cursor position numbers and
+ − 621 where to put them within the command.
+ − 622
+ − 623 The specifications of termcap include conventions as to which string-valued
+ − 624 capabilities require parameters, how many parameters, and what the
+ − 625 parameters mean; for example, it defines the @samp{cm} string to take
+ − 626 two parameters, the vertical and horizontal positions, with 0,0 being the
+ − 627 upper left corner. These conventions are described where the individual
+ − 628 commands are documented.
+ − 629
+ − 630 Termcap also defines a language used within the capability definition for
+ − 631 specifying how and where to encode the parameters for output. This language
+ − 632 uses character sequences starting with @samp{%}. (This is the same idea as
+ − 633 @code{printf}, but the details are different.) The language for parameter
+ − 634 encoding is described in this section.
+ − 635
+ − 636 A program that is doing display output calls the functions @code{tparam} or
+ − 637 @code{tgoto} to encode parameters according to the specifications. These
+ − 638 functions produce a string containing the actual commands to be output (as
+ − 639 well a padding spec which must be processed with @code{tputs};
+ − 640 @pxref{Padding}).
+ − 641
+ − 642 @menu
+ − 643 * Encode Parameters:: The language for encoding parameters.
+ − 644 * Using Parameters:: Outputting a string command with parameters.
+ − 645 @end menu
+ − 646
+ − 647 @node Encode Parameters, Using Parameters, Parameters, Parameters
+ − 648 @subsection Describing the Encoding
+ − 649 @cindex %
+ − 650
+ − 651 A terminal command string that requires parameters contains special
+ − 652 character sequences starting with @samp{%} to say how to encode the
+ − 653 parameters. These sequences control the actions of @code{tparam} and
+ − 654 @code{tgoto}.
+ − 655
+ − 656 The parameters values passed to @code{tparam} or @code{tgoto} are
+ − 657 considered to form a vector. A pointer into this vector determines
+ − 658 the next parameter to be processed. Some of the @samp{%}-sequences
+ − 659 encode one parameter and advance the pointer to the next parameter.
+ − 660 Other @samp{%}-sequences alter the pointer or alter the parameter
+ − 661 values without generating output.
+ − 662
+ − 663 For example, the @samp{cm} string for a standard ANSI terminal is written
+ − 664 as @samp{\E[%i%d;%dH}. (@samp{\E} stands for @key{ESC}.) @samp{cm} by
+ − 665 convention always requires two parameters, the vertical and horizontal goal
+ − 666 positions, so this string specifies the encoding of two parameters. Here
+ − 667 @samp{%i} increments the two values supplied, and each @samp{%d} encodes
+ − 668 one of the values in decimal. If the cursor position values 20,58 are
+ − 669 encoded with this string, the result is @samp{\E[21;59H}.
+ − 670
+ − 671 First, here are the @samp{%}-sequences that generate output. Except for
+ − 672 @samp{%%}, each of them encodes one parameter and advances the pointer
+ − 673 to the following parameter.
+ − 674
+ − 675 @table @samp
+ − 676 @item %%
+ − 677 Output a single @samp{%}. This is the only way to represent a literal
+ − 678 @samp{%} in a terminal command with parameters. @samp{%%} does not
+ − 679 use up a parameter.
+ − 680
+ − 681 @item %d
+ − 682 As in @code{printf}, output the next parameter in decimal.
+ − 683
+ − 684 @item %2
+ − 685 Like @samp{%02d} in @code{printf}: output the next parameter in
+ − 686 decimal, and always use at least two digits.
+ − 687
+ − 688 @item %3
+ − 689 Like @samp{%03d} in @code{printf}: output the next parameter in
+ − 690 decimal, and always use at least three digits. Note that @samp{%4}
+ − 691 and so on are @emph{not} defined.
+ − 692
+ − 693 @item %.
+ − 694 Output the next parameter as a single character whose ASCII code is
+ − 695 the parameter value. Like @samp{%c} in @code{printf}.
+ − 696
+ − 697 @item %+@var{char}
+ − 698 Add the next parameter to the character @var{char}, and output the
+ − 699 resulting character. For example, @samp{%+ } represents 0 as a space,
+ − 700 1 as @samp{!}, etc.
+ − 701 @end table
+ − 702
+ − 703 The following @samp{%}-sequences specify alteration of the parameters
+ − 704 (their values, or their order) rather than encoding a parameter for output.
+ − 705 They generate no output; they are used only for their side effects
+ − 706 on the parameters. Also, they do not advance the ``next parameter'' pointer
+ − 707 except as explicitly stated. Only @samp{%i}, @samp{%r} and @samp{%>} are
+ − 708 defined in standard Unix termcap. The others are GNU extensions.@refill
+ − 709
+ − 710 @table @samp
+ − 711 @item %i
+ − 712 Increment the next two parameters. This is used for terminals that
+ − 713 expect cursor positions in origin 1. For example, @samp{%i%d,%d} would
+ − 714 output two parameters with @samp{1} for 0, @samp{2} for 1, etc.
+ − 715
+ − 716 @item %r
+ − 717 Interchange the next two parameters. This is used for terminals whose
+ − 718 cursor positioning command expects the horizontal position first.
+ − 719
+ − 720 @item %s
+ − 721 Skip the next parameter. Do not output anything.
+ − 722
+ − 723 @item %b
+ − 724 Back up one parameter. The last parameter used will become once again
+ − 725 the next parameter to be output, and the next output command will use
+ − 726 it. Using @samp{%b} more than once, you can back up any number of
+ − 727 parameters, and you can refer to each parameter any number of times.
+ − 728
+ − 729 @item %>@var{c1}@var{c2}
+ − 730 Conditionally increment the next parameter. Here @var{c1} and
+ − 731 @var{c2} are characters which stand for their ASCII codes as numbers.
+ − 732 If the next parameter is greater than the ASCII code of @var{c1}, the
+ − 733 ASCII code of @var{c2} is added to it.@refill
+ − 734
+ − 735 @item %a @var{op} @var{type} @var{pos}
+ − 736 Perform arithmetic on the next parameter, do not use it up, and do not
+ − 737 output anything. Here @var{op} specifies the arithmetic operation,
+ − 738 while @var{type} and @var{pos} together specify the other operand.
+ − 739
+ − 740 Spaces are used above to separate the operands for clarity; the spaces
+ − 741 don't appear in the data base, where this sequence is exactly five
+ − 742 characters long.
+ − 743
+ − 744 The character @var{op} says what kind of arithmetic operation to
+ − 745 perform. It can be any of these characters:
+ − 746
+ − 747 @table @samp
+ − 748 @item =
+ − 749 assign a value to the next parameter, ignoring its old value.
+ − 750 The new value comes from the other operand.
+ − 751
+ − 752 @item +
+ − 753 add the other operand to the next parameter.
+ − 754
+ − 755 @item -
+ − 756 subtract the other operand from the next parameter.
+ − 757
+ − 758 @item *
+ − 759 multiply the next parameter by the other operand.
+ − 760
+ − 761 @item /
+ − 762 divide the next parameter by the other operand.
+ − 763 @end table
+ − 764
+ − 765 The ``other operand'' may be another parameter's value or a constant;
+ − 766 the character @var{type} says which. It can be:
+ − 767
+ − 768 @table @samp
+ − 769 @item p
+ − 770 Use another parameter. The character @var{pos} says which
+ − 771 parameter to use. Subtract 64 from its ASCII code to get the
+ − 772 position of the desired parameter relative to this one. Thus,
+ − 773 the character @samp{A} as @var{pos} means the parameter after the
+ − 774 next one; the character @samp{?} means the parameter before the
+ − 775 next one.
+ − 776
+ − 777 @item c
+ − 778 Use a constant value. The character @var{pos} specifies the
+ − 779 value of the constant. The 0200 bit is cleared out, so that 0200
+ − 780 can be used to represent zero.
+ − 781 @end table
+ − 782 @end table
+ − 783
+ − 784 The following @samp{%}-sequences are special purpose hacks to compensate
+ − 785 for the weird designs of obscure terminals. They modify the next parameter
+ − 786 or the next two parameters but do not generate output and do not use up any
+ − 787 parameters. @samp{%m} is a GNU extension; the others are defined in
+ − 788 standard Unix termcap.
+ − 789
+ − 790 @table @samp
+ − 791 @item %n
+ − 792 Exclusive-or the next parameter with 0140, and likewise the parameter
+ − 793 after next.
+ − 794
+ − 795 @item %m
+ − 796 Complement all the bits of the next parameter and the parameter after next.
+ − 797
+ − 798 @item %B
+ − 799 Encode the next parameter in BCD. It alters the value of the
+ − 800 parameter by adding six times the quotient of the parameter by ten.
+ − 801 Here is a C statement that shows how the new value is computed:
+ − 802
+ − 803 @example
+ − 804 @var{parm} = (@var{parm} / 10) * 16 + @var{parm} % 10;
+ − 805 @end example
+ − 806
+ − 807 @item %D
+ − 808 Transform the next parameter as needed by Delta Data terminals.
+ − 809 This involves subtracting twice the remainder of the parameter by 16.
+ − 810
+ − 811 @example
+ − 812 @var{parm} -= 2 * (@var{parm} % 16);
+ − 813 @end example
+ − 814 @end table
+ − 815
+ − 816 @node Using Parameters,, Encode Parameters, Parameters
+ − 817 @subsection Sending Display Commands with Parameters
+ − 818
+ − 819 The termcap library functions @code{tparam} and @code{tgoto} serve as the
+ − 820 analog of @code{printf} for terminal string parameters. The newer function
+ − 821 @code{tparam} is a GNU extension, more general but missing from Unix
+ − 822 termcap. The original parameter-encoding function is @code{tgoto}, which
+ − 823 is preferable for cursor motion.
+ − 824
+ − 825 @menu
+ − 826 * tparam:: The general case, for GNU termcap only.
+ − 827 * tgoto:: The special case of cursor motion.
+ − 828 @end menu
+ − 829
+ − 830 @node tparam, tgoto, Using Parameters, Using Parameters
+ − 831 @subsubsection @code{tparam}
+ − 832
+ − 833 @findex tparam
+ − 834 The function @code{tparam} can encode display commands with any number of
+ − 835 parameters and allows you to specify the buffer space. It is the preferred
+ − 836 function for encoding parameters for all but the @samp{cm} capability. Its
+ − 837 ANSI C declaration is as follows:
+ − 838
+ − 839 @example
+ − 840 char *tparam (char *@var{ctlstring}, char *@var{buffer}, int @var{size}, int @var{parm1},...)
+ − 841 @end example
+ − 842
+ − 843 The arguments are a control string @var{ctlstring} (the value of a terminal
+ − 844 capability, presumably), an output buffer @var{buffer} and @var{size}, and
+ − 845 any number of integer parameters to be encoded. The effect of
+ − 846 @code{tparam} is to copy the control string into the buffer, encoding
+ − 847 parameters according to the @samp{%} sequences in the control string.
+ − 848
+ − 849 You describe the output buffer by its address, @var{buffer}, and its size
+ − 850 in bytes, @var{size}. If the buffer is not big enough for the data to be
+ − 851 stored in it, @code{tparam} calls @code{malloc} to get a larger buffer. In
+ − 852 either case, @code{tparam} returns the address of the buffer it ultimately
+ − 853 uses. If the value equals @var{buffer}, your original buffer was used.
+ − 854 Otherwise, a new buffer was allocated, and you must free it after you are
+ − 855 done with printing the results. If you pass zero for @var{size} and
+ − 856 @var{buffer}, @code{tparam} always allocates the space with @code{malloc}.
+ − 857
+ − 858 All capabilities that require parameters also have the ability to specify
+ − 859 padding, so you should use @code{tputs} to output the string produced by
+ − 860 @code{tparam}. @xref{Padding}. Here is an example.
+ − 861
+ − 862 @example
+ − 863 @{
+ − 864 char *buf;
+ − 865 char buffer[40];
+ − 866
+ − 867 buf = tparam (command, buffer, 40, parm);
+ − 868 tputs (buf, 1, fputchar);
+ − 869 if (buf != buffer)
+ − 870 free (buf);
+ − 871 @}
+ − 872 @end example
+ − 873
+ − 874 If a parameter whose value is zero is encoded with @samp{%.}-style
+ − 875 encoding, the result is a null character, which will confuse @code{tputs}.
+ − 876 This would be a serious problem, but luckily @samp{%.} encoding is used
+ − 877 only by a few old models of terminal, and only for the @samp{cm}
+ − 878 capability. To solve the problem, use @code{tgoto} rather than
+ − 879 @code{tparam} to encode the @samp{cm} capability.@refill
+ − 880
+ − 881 @node tgoto,, tparam, Using Parameters
+ − 882 @subsubsection @code{tgoto}
+ − 883
+ − 884 @findex tgoto
+ − 885 The special case of cursor motion is handled by @code{tgoto}. There
+ − 886 are two reasons why you might choose to use @code{tgoto}:
+ − 887
+ − 888 @itemize @bullet
+ − 889 @item
+ − 890 For Unix compatibility, because Unix termcap does not have @code{tparam}.
+ − 891
+ − 892 @item
+ − 893 For the @samp{cm} capability, since @code{tgoto} has a special feature
+ − 894 to avoid problems with null characters, tabs and newlines on certain old
+ − 895 terminal types that use @samp{%.} encoding for that capability.
+ − 896 @end itemize
+ − 897
+ − 898 Here is how @code{tgoto} might be declared in ANSI C:
+ − 899
+ − 900 @example
+ − 901 char *tgoto (char *@var{cstring}, int @var{hpos}, int @var{vpos})
+ − 902 @end example
+ − 903
+ − 904 There are three arguments, the terminal description's @samp{cm} string and
+ − 905 the two cursor position numbers; @code{tgoto} computes the parametrized
+ − 906 string in an internal static buffer and returns the address of that buffer.
+ − 907 The next time you use @code{tgoto} the same buffer will be reused.
+ − 908
+ − 909 @vindex UP
+ − 910 @vindex BC
+ − 911 Parameters encoded with @samp{%.} encoding can generate null characters,
+ − 912 tabs or newlines. These might cause trouble: the null character because
+ − 913 @code{tputs} would think that was the end of the string, the tab because
+ − 914 the kernel or other software might expand it into spaces, and the newline
4312
+ − 915 because the kernel might add a carriage-return, or padding characters
428
+ − 916 normally used for a newline. To prevent such problems, @code{tgoto} is
+ − 917 careful to avoid these characters. Here is how this works: if the target
+ − 918 cursor position value is such as to cause a problem (that is to say, zero,
+ − 919 nine or ten), @code{tgoto} increments it by one, then compensates by
+ − 920 appending a string to move the cursor back or up one position.
+ − 921
+ − 922 The compensation strings to use for moving back or up are found in global
+ − 923 variables named @code{BC} and @code{UP}. These are actual external C
+ − 924 variables with upper case names; they are declared @code{char *}. It is up
+ − 925 to you to store suitable values in them, normally obtained from the
+ − 926 @samp{le} and @samp{up} terminal capabilities in the terminal description
+ − 927 with @code{tgetstr}. Alternatively, if these two variables are both zero,
+ − 928 the feature of avoiding nulls, tabs and newlines is turned off.
+ − 929
+ − 930 It is safe to use @code{tgoto} for commands other than @samp{cm} only if
+ − 931 you have stored zero in @code{BC} and @code{UP}.
+ − 932
+ − 933 Note that @code{tgoto} reverses the order of its operands: the horizontal
+ − 934 position comes before the vertical position in the arguments to
+ − 935 @code{tgoto}, even though the vertical position comes before the horizontal
+ − 936 in the parameters of the @samp{cm} string. If you use @code{tgoto} with a
+ − 937 command such as @samp{AL} that takes one parameter, you must pass the
+ − 938 parameter to @code{tgoto} as the ``vertical position''.@refill
+ − 939
+ − 940 @node Data Base, Capabilities, Library, Top
+ − 941 @chapter The Format of the Data Base
+ − 942
+ − 943 The termcap data base of terminal descriptions is stored in the file
+ − 944 @file{/etc/termcap}. It contains terminal descriptions, blank lines, and
+ − 945 comments.
+ − 946
+ − 947 A terminal description starts with one or more names for the terminal type.
+ − 948 The information in the description is a series of @dfn{capability names}
+ − 949 and values. The capability names have standard meanings
+ − 950 (@pxref{Capabilities}) and their values describe the terminal.
+ − 951
+ − 952 @menu
+ − 953 * Format:: Overall format of a terminal description.
+ − 954 * Capability Format:: Format of capabilities within a description.
+ − 955 * Naming:: Naming conventions for terminal types.
+ − 956 * Inheriting:: Inheriting part of a description from
+ − 957 a related terminal type.
+ − 958 @end menu
+ − 959
+ − 960 @node Format, Capability Format, Data Base, Data Base
+ − 961 @section Terminal Description Format
+ − 962 @cindex description format
+ − 963
+ − 964 Aside from comments (lines starting with @samp{#}, which are ignored), each
+ − 965 nonblank line in the termcap data base is a terminal description.
+ − 966 A terminal description is nominally a single line, but it can be split
+ − 967 into multiple lines by inserting the two characters @samp{\ newline}.
+ − 968 This sequence is ignored wherever it appears in a description.
+ − 969
+ − 970 The preferred way to split the description is between capabilities: insert
+ − 971 the four characters @samp{: \ newline tab} immediately before any colon.
+ − 972 This allows each sub-line to start with some indentation. This works
+ − 973 because, after the @samp{\ newline} are ignored, the result is @samp{: tab
+ − 974 :}; the first colon ends the preceding capability and the second colon
+ − 975 starts the next capability. If you split with @samp{\ newline} alone, you
+ − 976 may not add any indentation after them.
+ − 977
+ − 978 Here is a real example of a terminal description:
+ − 979
+ − 980 @example
+ − 981 dw|vt52|DEC vt52:\
+ − 982 :cr=^M:do=^J:nl=^J:bl=^G:\
+ − 983 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
+ − 984 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
+ − 985 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
+ − 986 @end example
+ − 987
+ − 988 Each terminal description begins with several names for the terminal type.
+ − 989 The names are separated by @samp{|} characters, and a colon ends the last
+ − 990 name. The first name should be two characters long; it exists only for the
+ − 991 sake of very old Unix systems and is never used in modern systems. The
+ − 992 last name should be a fully verbose name such as ``DEC vt52'' or ``Ann
+ − 993 Arbor Ambassador with 48 lines''. The other names should include whatever
+ − 994 the user ought to be able to specify to get this terminal type, such as
+ − 995 @samp{vt52} or @samp{aaa-48}. @xref{Naming}, for information on how to
+ − 996 choose terminal type names.
+ − 997
+ − 998 After the terminal type names come the terminal capabilities, separated by
+ − 999 colons and with a colon after the last one. Each capability has a
+ − 1000 two-letter name, such as @samp{cm} for ``cursor motion string'' or @samp{li}
+ − 1001 for ``number of display lines''.
+ − 1002
+ − 1003 @node Capability Format, Naming, Format, Data Base
+ − 1004 @section Writing the Capabilities
+ − 1005
+ − 1006 There are three kinds of capabilities: flags, numbers, and strings. Each
+ − 1007 kind has its own way of being written in the description. Each defined
+ − 1008 capability has by convention a particular kind of value; for example,
+ − 1009 @samp{li} always has a numeric value and @samp{cm} always a string value.
+ − 1010
+ − 1011 A flag capability is thought of as having a boolean value: the value is
+ − 1012 true if the capability is present, false if not. When the capability is
+ − 1013 present, just write its name between two colons.
+ − 1014
+ − 1015 A numeric capability has a value which is a nonnegative number. Write the
+ − 1016 capability name, a @samp{#}, and the number, between two colons. For
+ − 1017 example, @samp{@dots{}:li#48:@dots{}} is how you specify the @samp{li}
+ − 1018 capability for 48 lines.@refill
+ − 1019
+ − 1020 A string-valued capability has a value which is a sequence of characters.
+ − 1021 Usually these are the characters used to perform some display operation.
+ − 1022 Write the capability name, a @samp{=}, and the characters of the value,
+ − 1023 between two colons. For example, @samp{@dots{}:cm=\E[%i%d;%dH:@dots{}} is
+ − 1024 how the cursor motion command for a standard ANSI terminal would be
+ − 1025 specified.@refill
+ − 1026
+ − 1027 Special characters in the string value can be expressed using
+ − 1028 @samp{\}-escape sequences as in C; in addition, @samp{\E} stands for
+ − 1029 @key{ESC}. @samp{^} is also a kind of escape character; @samp{^} followed
+ − 1030 by @var{char} stands for the control-equivalent of @var{char}. Thus,
+ − 1031 @samp{^a} stands for the character control-a, just like @samp{\001}.
+ − 1032 @samp{\} and @samp{^} themselves can be represented as @samp{\\} and
+ − 1033 @samp{\^}.@refill
+ − 1034
+ − 1035 To include a colon in the string, you must write @samp{\072}. You might
+ − 1036 ask, ``Why can't @samp{\:} be used to represent a colon?'' The reason is
+ − 1037 that the interrogation functions do not count slashes while looking for a
+ − 1038 capability. Even if @samp{:ce=ab\:cd:} were interpreted as giving the
+ − 1039 @samp{ce} capability the value @samp{ab:cd}, it would also appear to define
+ − 1040 @samp{cd} as a flag.
+ − 1041
+ − 1042 The string value will often contain digits at the front to specify padding
+ − 1043 (@pxref{Padding}) and/or @samp{%}-sequences within to specify how to encode
+ − 1044 parameters (@pxref{Parameters}). Although these things are not to be
+ − 1045 output literally to the terminal, they are considered part of the value of
+ − 1046 the capability. They are special only when the string value is processed
+ − 1047 by @code{tputs}, @code{tparam} or @code{tgoto}. By contrast, @samp{\} and
+ − 1048 @samp{^} are considered part of the syntax for specifying the characters
+ − 1049 in the string.
+ − 1050
+ − 1051 Let's look at the VT52 example again:
+ − 1052
+ − 1053 @example
+ − 1054 dw|vt52|DEC vt52:\
+ − 1055 :cr=^M:do=^J:nl=^J:bl=^G:\
+ − 1056 :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
+ − 1057 :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
+ − 1058 :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
+ − 1059 @end example
+ − 1060
+ − 1061 Here we see the numeric-valued capabilities @samp{co} and @samp{li}, the
+ − 1062 flags @samp{bs} and @samp{pt}, and many string-valued capabilities. Most
+ − 1063 of the strings start with @key{ESC} represented as @samp{\E}. The rest
+ − 1064 contain control characters represented using @samp{^}. The meanings of the
+ − 1065 individual capabilities are defined elsewhere (@pxref{Capabilities}).
+ − 1066
+ − 1067 @node Naming, Inheriting, Capability Format, Data Base
+ − 1068 @section Terminal Type Name Conventions
+ − 1069 @cindex names of terminal types
+ − 1070
+ − 1071 There are conventions for choosing names of terminal types. For one thing,
+ − 1072 all letters should be in lower case. The terminal type for a terminal in
+ − 1073 its most usual or most fundamental mode of operation should not have a
+ − 1074 hyphen in it.
+ − 1075
+ − 1076 If the same terminal has other modes of operation which require
+ − 1077 different terminal descriptions, these variant descriptions are given
+ − 1078 names made by adding suffixes with hyphens. Such alternate descriptions
+ − 1079 are used for two reasons:
+ − 1080
+ − 1081 @itemize @bullet
+ − 1082 @item
+ − 1083 When the terminal has a switch that changes its behavior. Since the
+ − 1084 computer cannot tell how the switch is set, the user must tell the
+ − 1085 computer by choosing the appropriate terminal type name.
+ − 1086
+ − 1087 @cindex wrapping
+ − 1088 For example, the VT-100 has a setup flag that controls whether the
+ − 1089 cursor wraps at the right margin. If this flag is set to ``wrap'',
+ − 1090 you must use the terminal type @samp{vt100-am}. Otherwise you must
+ − 1091 use @samp{vt100-nam}. Plain @samp{vt100} is defined as a synonym for
+ − 1092 either @samp{vt100-am} or @samp{vt100-nam} depending on the
+ − 1093 preferences of the local site.@refill
+ − 1094
+ − 1095 The standard suffix @samp{-am} stands for ``automatic margins''.
+ − 1096
+ − 1097 @item
+ − 1098 To give the user a choice in how to use the terminal. This is done
+ − 1099 when the terminal has a switch that the computer normally controls.
+ − 1100
+ − 1101 @cindex screen size
+ − 1102 For example, the Ann Arbor Ambassador can be configured with many
+ − 1103 screen sizes ranging from 20 to 60 lines. Fewer lines make bigger
+ − 1104 characters but more lines let you see more of what you are editing.
+ − 1105 As a result, users have different preferences. Therefore, termcap
+ − 1106 provides terminal types for many screen sizes. If you choose type
+ − 1107 @samp{aaa-30}, the terminal will be configured to use 30 lines; if you
+ − 1108 choose @samp{aaa-48}, 48 lines will be used, and so on.
+ − 1109 @end itemize
+ − 1110
+ − 1111 Here is a list of standard suffixes and their conventional meanings:
+ − 1112
+ − 1113 @table @samp
+ − 1114 @item -w
+ − 1115 Short for ``wide''. This is a mode that gives the terminal more
+ − 1116 columns than usual. This is normally a user option.
+ − 1117
+ − 1118 @item -am
+ − 1119 ``Automatic margins''. This is an alternate description for use when
+ − 1120 the terminal's margin-wrap switch is on; it contains the @samp{am}
+ − 1121 flag. The implication is that normally the switch is off and the
+ − 1122 usual description for the terminal says that the switch is off.
+ − 1123
+ − 1124 @item -nam
+ − 1125 ``No automatic margins''. The opposite of @samp{-am}, this names an
+ − 1126 alternative description which lacks the @samp{am} flag. This implies
+ − 1127 that the terminal is normally operated with the margin-wrap switch
+ − 1128 turned on, and the normal description of the terminal says so.
+ − 1129
+ − 1130 @item -na
+ − 1131 ``No arrows''. This terminal description initializes the terminal to
+ − 1132 keep its arrow keys in local mode. This is a user option.
+ − 1133
+ − 1134 @item -rv
+ − 1135 ``Reverse video''. This terminal description causes text output for
+ − 1136 normal video to appear as reverse, and text output for reverse video
+ − 1137 to come out as normal. Often this description differs from the usual
+ − 1138 one by interchanging the two strings which turn reverse video on and
+ − 1139 off.@refill
+ − 1140
+ − 1141 This is a user option; you can choose either the ``reverse video''
+ − 1142 variant terminal type or the normal terminal type, and termcap will
+ − 1143 obey.
+ − 1144
+ − 1145 @item -s
+ − 1146 ``Status''. Says to enable use of a status line which ordinary output
+ − 1147 does not touch (@pxref{Status Line}).
+ − 1148
+ − 1149 Some terminals have a special line that is used only as a status line.
901
+ − 1150 For these terminals, there is no need for a @samp{-s} variant; the
428
+ − 1151 status line commands should be defined by default. On other
+ − 1152 terminals, enabling a status line means removing one screen line from
+ − 1153 ordinary use and reducing the effective screen height. For these
+ − 1154 terminals, the user can choose the @samp{-s} variant type to request
+ − 1155 use of a status line.
+ − 1156
+ − 1157 @item -@var{nlines}
+ − 1158 Says to operate with @var{nlines} lines on the screen, for terminals
+ − 1159 such as the Ambassador which provide this as an option. Normally this
+ − 1160 is a user option; by choosing the terminal type, you control how many
+ − 1161 lines termcap will use.
+ − 1162
+ − 1163 @item -@var{npages}p
+ − 1164 Says that the terminal has @var{npages} pages worth of screen memory,
+ − 1165 for terminals where this is a hardware option.
+ − 1166
+ − 1167 @item -unk
+ − 1168 Says that description is not for direct use, but only for reference in
+ − 1169 @samp{tc} capabilities. Such a description is a kind of subroutine,
+ − 1170 because it describes the common characteristics of several variant
+ − 1171 descriptions that would use other suffixes in place of @samp{-unk}.
+ − 1172 @end table
+ − 1173
+ − 1174 @node Inheriting,, Naming, Data Base
+ − 1175 @section Inheriting from Related Descriptions
+ − 1176
+ − 1177 @cindex inheritance
+ − 1178 When two terminal descriptions are similar, their identical parts do not
+ − 1179 need to be given twice. Instead, one of the two can be defined in terms of
+ − 1180 the other, using the @samp{tc} capability. We say that one description
+ − 1181 @dfn{refers to} the other, or @dfn{inherits from} the other.
+ − 1182
+ − 1183 The @samp{tc} capability must be the last one in the terminal description,
+ − 1184 and its value is a string which is the name of another terminal type which
+ − 1185 is referred to. For example,
+ − 1186
+ − 1187 @example
+ − 1188 N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
+ − 1189 :ti=\E[2J\E[30;0;0;30p:\
+ − 1190 :te=\E[60;0;0;30p\E[30;1H\E[J:\
+ − 1191 :li#30:tc=aaa-unk:
+ − 1192 @end example
+ − 1193
+ − 1194 @noindent
+ − 1195 defines the terminal type @samp{aaa-30} (also known as plain @samp{aaa}) in
+ − 1196 terms of @samp{aaa-unk}, which defines everything about the Ambassador that
+ − 1197 is independent of screen height. The types @samp{aaa-36}, @samp{aaa-48}
+ − 1198 and so on for other screen heights are likewise defined to inherit from
+ − 1199 @samp{aaa-unk}.
+ − 1200
+ − 1201 The capabilities overridden by @samp{aaa-30} include @samp{li}, which says
+ − 1202 how many lines there are, and @samp{ti} and @samp{te}, which configure the
+ − 1203 terminal to use that many lines.
+ − 1204
+ − 1205 The effective terminal description for type @samp{aaa} consists of the text
+ − 1206 shown above followed by the text of the description of @samp{aaa-unk}. The
+ − 1207 @samp{tc} capability is handled automatically by @code{tgetent}, which
+ − 1208 finds the description thus referenced and combines the two descriptions
+ − 1209 (@pxref{Find}). Therefore, only the implementor of the terminal
+ − 1210 descriptions needs to think about using @samp{tc}. Users and application
+ − 1211 programmers do not need to be concerned with it.
+ − 1212
+ − 1213 Since the reference terminal description is used last, capabilities
+ − 1214 specified in the referring description override any specifications of the
+ − 1215 same capabilities in the reference description.
+ − 1216
+ − 1217 The referring description can cancel out a capability without specifying
+ − 1218 any new value for it by means of a special trick. Write the capability in
+ − 1219 the referring description, with the character @samp{@@} after the capability
+ − 1220 name, as follows:
+ − 1221
+ − 1222 @example
+ − 1223 NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
+ − 1224 :am@@:tc=aaa-30:
+ − 1225 @end example
+ − 1226
+ − 1227 @node Capabilities, Summary, Data Base, Top
+ − 1228 @chapter Definitions of the Terminal Capabilities
+ − 1229
+ − 1230 This section is divided into many subsections, each for one aspect of
+ − 1231 use of display terminals. For writing a display program, you usually need
+ − 1232 only check the subsections for the operations you want to use. For writing
+ − 1233 a terminal description, you must read each subsection and fill in the
+ − 1234 capabilities described there.
+ − 1235
+ − 1236 String capabilities that are display commands may require numeric
+ − 1237 parameters (@pxref{Parameters}). Most such capabilities do not use
+ − 1238 parameters. When a capability requires parameters, this is explicitly
+ − 1239 stated at the beginning of its definition. In simple cases, the first or
+ − 1240 second sentence of the definition mentions all the parameters, in the order
+ − 1241 they should be given, using a name
+ − 1242 @iftex
+ − 1243 in italics
+ − 1244 @end iftex
+ − 1245 @ifinfo
+ − 1246 in upper case
+ − 1247 @end ifinfo
+ − 1248 for each one. For example, the @samp{rp} capability is a command that
+ − 1249 requires two parameters; its definition begins as follows:
+ − 1250
+ − 1251 @quotation
+ − 1252 String of commands to output a graphic character @var{c}, repeated @var{n}
+ − 1253 times.
+ − 1254 @end quotation
+ − 1255
+ − 1256 In complex cases or when there are many parameters, they are described
+ − 1257 explicitly.
+ − 1258
+ − 1259 When a capability is described as obsolete, this means that programs should
+ − 1260 not be written to look for it, but terminal descriptions should still be
+ − 1261 written to provide it.
+ − 1262
+ − 1263 When a capability is described as very obsolete, this means that it should
+ − 1264 be omitted from terminal descriptions as well.
+ − 1265
+ − 1266 @menu
+ − 1267 * Basic:: Basic characteristics.
+ − 1268 * Screen Size:: Screen size, and what happens when it changes.
+ − 1269 * Cursor Motion:: Various ways to move the cursor.
+ − 1270 * Scrolling:: Pushing text up and down on the screen.
+ − 1271 * Wrapping:: What happens if you write a character in the last column.
+ − 1272 * Windows:: Limiting the part of the window that output affects.
+ − 1273 * Clearing:: Erasing one or many lines.
+ − 1274 * Insdel Line:: Making new blank lines in mid-screen; deleting lines.
+ − 1275 * Insdel Char:: Inserting and deleting characters within a line.
+ − 1276 * Standout:: Highlighting some of the text.
+ − 1277 * Underlining:: Underlining some of the text.
+ − 1278 * Cursor Visibility:: Making the cursor more or less easy to spot.
+ − 1279 * Bell:: Attracts user's attention; not localized on the screen.
+ − 1280 * Keypad:: Recognizing when function keys or arrows are typed.
+ − 1281 * Meta Key:: @key{META} acts like an extra shift key.
+ − 1282 * Initialization:: Commands used to initialize or reset the terminal.
+ − 1283 * Pad Specs:: Info for the kernel on how much padding is needed.
+ − 1284 * Status Line:: A status line displays ``background'' information.
+ − 1285 * Half-Line:: Moving by half-lines, for superscripts and subscripts.
+ − 1286 * Printer:: Controlling auxiliary printers of display terminals.
+ − 1287 @end menu
+ − 1288
+ − 1289 @node Basic, Screen Size, Capabilities, Capabilities
+ − 1290 @section Basic Characteristics
+ − 1291
+ − 1292 This section documents the capabilities that describe the basic and
+ − 1293 nature of the terminal, and also those that are relevant to the output
+ − 1294 of graphic characters.
+ − 1295
+ − 1296 @table @samp
+ − 1297 @item os
+ − 1298 @kindex os
+ − 1299 @cindex overstrike
+ − 1300 Flag whose presence means that the terminal can overstrike. This
+ − 1301 means that outputting a graphic character does not erase whatever was
+ − 1302 present in the same character position before. The terminals that can
+ − 1303 overstrike include printing terminals, storage tubes (all obsolete
+ − 1304 nowadays), and many bit-map displays.
+ − 1305
+ − 1306 @item eo
+ − 1307 @kindex eo
+ − 1308 Flag whose presence means that outputting a space can erase an
+ − 1309 overstrike. If this is not present and overstriking is supported,
+ − 1310 output of a space has no effect except to move the cursor.
+ − 1311
+ − 1312 @item gn
+ − 1313 @kindex gn
+ − 1314 @cindex generic terminal type
+ − 1315 Flag whose presence means that this terminal type is a generic type
+ − 1316 which does not really describe any particular terminal. Generic types
+ − 1317 are intended for use as the default type assigned when the user
+ − 1318 connects to the system, with the intention that the user should
+ − 1319 specify what type he really has. One example of a generic type
+ − 1320 is the type @samp{network}.
+ − 1321
+ − 1322 Since the generic type cannot say how to do anything interesting with
+ − 1323 the terminal, termcap-using programs will always find that the
+ − 1324 terminal is too weak to be supported if the user has failed to specify
+ − 1325 a real terminal type in place of the generic one. The @samp{gn} flag
+ − 1326 directs these programs to use a different error message: ``You have
+ − 1327 not specified your real terminal type'', rather than ``Your terminal
+ − 1328 is not powerful enough to be used''.
+ − 1329
+ − 1330 @item hc
+ − 1331 @kindex hc
+ − 1332 Flag whose presence means this is a hardcopy terminal.
+ − 1333
+ − 1334 @item rp
+ − 1335 @kindex rp
+ − 1336 @cindex repeat output
+ − 1337 String of commands to output a graphic character @var{c}, repeated @var{n}
+ − 1338 times. The first parameter value is the ASCII code for the desired
+ − 1339 character, and the second parameter is the number of times to repeat the
+ − 1340 character. Often this command requires padding proportional to the
+ − 1341 number of times the character is repeated. This effect can be had by
+ − 1342 using parameter arithmetic with @samp{%}-sequences to compute the
+ − 1343 amount of padding, then generating the result as a number at the front
+ − 1344 of the string so that @code{tputs} will treat it as padding.
+ − 1345
+ − 1346 @item hz
+ − 1347 @kindex hz
+ − 1348 Flag whose presence means that the ASCII character @samp{~} cannot be
+ − 1349 output on this terminal because it is used for display commands.
+ − 1350
+ − 1351 Programs handle this flag by checking all text to be output and
+ − 1352 replacing each @samp{~} with some other character(s). If this is not
+ − 1353 done, the screen will be thoroughly garbled.
+ − 1354
+ − 1355 The old Hazeltine terminals that required such treatment are probably
+ − 1356 very rare today, so you might as well not bother to support this flag.
+ − 1357
+ − 1358 @item CC
+ − 1359 @kindex CC
+ − 1360 @cindex command character
+ − 1361 String whose presence means the terminal has a settable command
+ − 1362 character. The value of the string is the default command character
+ − 1363 (which is usually @key{ESC}).
+ − 1364
+ − 1365 All the strings of commands in the terminal description should be
+ − 1366 written to use the default command character. If you are writing an
+ − 1367 application program that changes the command character, use the
+ − 1368 @samp{CC} capability to figure out how to translate all the display
+ − 1369 commands to work with the new command character.
+ − 1370
+ − 1371 Most programs have no reason to look at the @samp{CC} capability.
+ − 1372
+ − 1373 @item xb
+ − 1374 @kindex xb
+ − 1375 @cindex Superbee
+ − 1376 Flag whose presence identifies Superbee terminals which are unable to
+ − 1377 transmit the characters @key{ESC} and @kbd{Control-C}. Programs which
+ − 1378 support this flag are supposed to check the input for the code sequences
+ − 1379 sent by the @key{F1} and @key{F2} keys, and pretend that @key{ESC}
+ − 1380 or @kbd{Control-C} (respectively) had been read. But this flag is
+ − 1381 obsolete, and not worth supporting.
+ − 1382 @end table
+ − 1383
+ − 1384 @node Screen Size, Cursor Motion, Basic, Capabilities
+ − 1385 @section Screen Size
+ − 1386 @cindex screen size
+ − 1387
+ − 1388 A terminal description has two capabilities, @samp{co} and @samp{li},
+ − 1389 that describe the screen size in columns and lines. But there is more
+ − 1390 to the question of screen size than this.
+ − 1391
+ − 1392 On some operating systems the ``screen'' is really a window and the
+ − 1393 effective width can vary. On some of these systems, @code{tgetnum}
+ − 1394 uses the actual width of the window to decide what value to return for
+ − 1395 the @samp{co} capability, overriding what is actually written in the
+ − 1396 terminal description. On other systems, it is up to the application
+ − 1397 program to check the actual window width using a system call. For
+ − 1398 example, on BSD 4.3 systems, the system call @code{ioctl} with code
+ − 1399 @code{TIOCGWINSZ} will tell you the current screen size.
+ − 1400
+ − 1401 On all window systems, termcap is powerless to advise the application
+ − 1402 program if the user resizes the window. Application programs must
+ − 1403 deal with this possibility in a system-dependent fashion. On some
+ − 1404 systems the C shell handles part of the problem by detecting changes
+ − 1405 in window size and setting the @code{TERMCAP} environment variable
+ − 1406 appropriately. This takes care of application programs that are
+ − 1407 started subsequently. It does not help application programs already
+ − 1408 running.
+ − 1409
+ − 1410 On some systems, including BSD 4.3, all programs using a terminal get
+ − 1411 a signal named @code{SIGWINCH} whenever the screen size changes.
+ − 1412 Programs that use termcap should handle this signal by using
+ − 1413 @code{ioctl TIOCGWINSZ} to learn the new screen size.
+ − 1414
+ − 1415 @table @samp
+ − 1416 @item co
+ − 1417 @kindex co
+ − 1418 @cindex screen size
+ − 1419 Numeric value, the width of the screen in character positions. Even
+ − 1420 hardcopy terminals normally have a @samp{co} capability.
+ − 1421
+ − 1422 @item li
+ − 1423 @kindex li
+ − 1424 Numeric value, the height of the screen in lines.
+ − 1425 @end table
+ − 1426
+ − 1427 @node Cursor Motion, Wrapping, Screen Size, Capabilities
+ − 1428 @section Cursor Motion
+ − 1429 @cindex cursor motion
+ − 1430
+ − 1431 Termcap assumes that the terminal has a @dfn{cursor}, a spot on the screen
+ − 1432 where a visible mark is displayed, and that most display commands take
+ − 1433 effect at the position of the cursor. It follows that moving the cursor
+ − 1434 to a specified location is very important.
+ − 1435
+ − 1436 There are many terminal capabilities for different cursor motion
+ − 1437 operations. A terminal description should define as many as possible, but
+ − 1438 most programs do not need to use most of them. One capability, @samp{cm},
+ − 1439 moves the cursor to an arbitrary place on the screen; this by itself is
+ − 1440 sufficient for any application as long as there is no need to support
+ − 1441 hardcopy terminals or certain old, weak displays that have only relative
+ − 1442 motion commands. Use of other cursor motion capabilities is an
+ − 1443 optimization, enabling the program to output fewer characters in some
+ − 1444 common cases.
+ − 1445
+ − 1446 If you plan to use the relative cursor motion commands in an application
+ − 1447 program, you must know what the starting cursor position is. To do this,
+ − 1448 you must keep track of the cursor position and update the records each
+ − 1449 time anything is output to the terminal, including graphic characters.
+ − 1450 In addition, it is necessary to know whether the terminal wraps after
+ − 1451 writing in the rightmost column. @xref{Wrapping}.
+ − 1452
+ − 1453 One other motion capability needs special mention: @samp{nw} moves the
+ − 1454 cursor to the beginning of the following line, perhaps clearing all the
+ − 1455 starting line after the cursor, or perhaps not clearing at all. This
+ − 1456 capability is a least common denominator that is probably supported even by
+ − 1457 terminals that cannot do most other things such as @samp{cm} or @samp{do}.
+ − 1458 Even hardcopy terminals can support @samp{nw}.
+ − 1459
+ − 1460 @table @asis
+ − 1461 @item @samp{cm}
+ − 1462 @kindex cm
+ − 1463 String of commands to position the cursor at line @var{l}, column @var{c}.
+ − 1464 Both parameters are origin-zero, and are defined relative to the
+ − 1465 screen, not relative to display memory.
+ − 1466
+ − 1467 All display terminals except a few very obsolete ones support @samp{cm},
+ − 1468 so it is acceptable for an application program to refuse to operate on
+ − 1469 terminals lacking @samp{cm}.
+ − 1470
+ − 1471 @item @samp{ho}
+ − 1472 @kindex ho
+ − 1473 @cindex home position
+ − 1474 String of commands to move the cursor to the upper left corner of the
+ − 1475 screen (this position is called the @dfn{home position}). In
+ − 1476 terminals where the upper left corner of the screen is not the same as
+ − 1477 the beginning of display memory, this command must go to the upper
+ − 1478 left corner of the screen, not the beginning of display memory.
+ − 1479
+ − 1480 Every display terminal supports this capability, and many application
+ − 1481 programs refuse to operate if the @samp{ho} capability is missing.
+ − 1482
+ − 1483 @item @samp{ll}
+ − 1484 @kindex ll
+ − 1485 String of commands to move the cursor to the lower left corner of the
+ − 1486 screen. On some terminals, moving up from home position does this,
+ − 1487 but programs should never assume that will work. Just output the
+ − 1488 @samp{ll} string (if it is provided); if moving to home position and
+ − 1489 then moving up is the best way to get there, the @samp{ll} command
+ − 1490 will do that.
+ − 1491
+ − 1492 @item @samp{cr}
+ − 1493 @kindex cr
+ − 1494 String of commands to move the cursor to the beginning of the line it
+ − 1495 is on. If this capability is not specified, many programs assume
+ − 1496 they can use the ASCII carriage return character for this.
+ − 1497
+ − 1498 @item @samp{le}
+ − 1499 @kindex le
+ − 1500 String of commands to move the cursor left one column. Unless the
+ − 1501 @samp{bw} flag capability is specified, the effect is undefined if the
+ − 1502 cursor is at the left margin; do not use this command there. If
+ − 1503 @samp{bw} is present, this command may be used at the left margin, and
+ − 1504 it wraps the cursor to the last column of the preceding line.
+ − 1505
+ − 1506 @item @samp{nd}
+ − 1507 @kindex nd
+ − 1508 String of commands to move the cursor right one column. The effect is
+ − 1509 undefined if the cursor is at the right margin; do not use this
+ − 1510 command there, not even if @samp{am} is present.
+ − 1511
+ − 1512 @item @samp{up}
+ − 1513 @kindex up
+ − 1514 String of commands to move the cursor vertically up one line. The
+ − 1515 effect of sending this string when on the top line is undefined;
+ − 1516 programs should never use it that way.
+ − 1517
+ − 1518 @item @samp{do}
+ − 1519 @kindex do
+ − 1520 String of commands to move the cursor vertically down one line. The
+ − 1521 effect of sending this string when on the bottom line is undefined;
+ − 1522 programs should never use it that way.
+ − 1523
+ − 1524 The original idea was that this string would not contain a newline
+ − 1525 character and therefore could be used without disabling the kernel's usual
+ − 1526 habit of converting of newline into a carriage-return newline sequence.
+ − 1527 But many terminal descriptions do use newline in the @samp{do} string, so
+ − 1528 this is not possible; a program which sends the @samp{do} string must
+ − 1529 disable output conversion in the kernel (@pxref{Initialize}).
+ − 1530
+ − 1531 @item @samp{bw}
+ − 1532 @kindex bw
+ − 1533 Flag whose presence says that @samp{le} may be used in column zero
+ − 1534 to move to the last column of the preceding line. If this flag
+ − 1535 is not present, @samp{le} should not be used in column zero.
+ − 1536
+ − 1537 @item @samp{nw}
+ − 1538 @kindex nw
+ − 1539 String of commands to move the cursor to start of next line, possibly
+ − 1540 clearing rest of line (following the cursor) before moving.
+ − 1541
+ − 1542 @item @samp{DO}, @samp{UP}, @samp{LE}, @samp{RI}
+ − 1543 @kindex DO
+ − 1544 @kindex LE
+ − 1545 @kindex RI
+ − 1546 @kindex UP
+ − 1547 Strings of commands to move the cursor @var{n} lines down vertically,
+ − 1548 up vertically, or @var{n} columns left or right. Do not attempt to
+ − 1549 move past any edge of the screen with these commands; the effect of
+ − 1550 trying that is undefined. Only a few terminal descriptions provide
+ − 1551 these commands, and most programs do not use them.
+ − 1552
+ − 1553 @item @samp{CM}
+ − 1554 @kindex CM
+ − 1555 String of commands to position the cursor at line @var{l}, column
+ − 1556 @var{c}, relative to display memory. Both parameters are origin-zero.
+ − 1557 This capability is present only in terminals where there is a
+ − 1558 difference between screen-relative and memory-relative addressing, and
+ − 1559 not even in all such terminals.
+ − 1560
+ − 1561 @item @samp{ch}
+ − 1562 @kindex ch
+ − 1563 String of commands to position the cursor at column @var{c} in the
+ − 1564 same line it is on. This is a special case of @samp{cm} in which the
+ − 1565 vertical position is not changed. The @samp{ch} capability is
+ − 1566 provided only when it is faster to output than @samp{cm} would be in
+ − 1567 this special case. Programs should not assume most display terminals
+ − 1568 have @samp{ch}.
+ − 1569
+ − 1570 @item @samp{cv}
+ − 1571 @kindex cv
+ − 1572 String of commands to position the cursor at line @var{l} in the same
+ − 1573 column. This is a special case of @samp{cm} in which the horizontal
+ − 1574 position is not changed. The @samp{cv} capability is provided only
+ − 1575 when it is faster to output than @samp{cm} would be in this special
+ − 1576 case. Programs should not assume most display terminals have
+ − 1577 @samp{cv}.
+ − 1578
+ − 1579 @item @samp{sc}
+ − 1580 @kindex sc
+ − 1581 String of commands to make the terminal save the current cursor
+ − 1582 position. Only the last saved position can be used. If this
+ − 1583 capability is present, @samp{rc} should be provided also. Most
+ − 1584 terminals have neither.
+ − 1585
+ − 1586 @item @samp{rc}
+ − 1587 @kindex rc
+ − 1588 String of commands to make the terminal restore the last saved cursor
+ − 1589 position. If this capability is present, @samp{sc} should be provided
+ − 1590 also. Most terminals have neither.
+ − 1591
+ − 1592 @item @samp{ff}
+ − 1593 @kindex ff
+ − 1594 String of commands to advance to the next page, for a hardcopy
+ − 1595 terminal.
+ − 1596
+ − 1597 @item @samp{ta}
+ − 1598 @kindex ta
+ − 1599 String of commands to move the cursor right to the next hardware tab
+ − 1600 stop column. Missing if the terminal does not have any kind of
+ − 1601 hardware tabs. Do not send this command if the kernel's terminal
+ − 1602 modes say that the kernel is expanding tabs into spaces.
+ − 1603
+ − 1604 @item @samp{bt}
+ − 1605 @kindex bt
+ − 1606 String of commands to move the cursor left to the previous hardware
+ − 1607 tab stop column. Missing if the terminal has no such ability; many
+ − 1608 terminals do not. Do not send this command if the kernel's terminal
+ − 1609 modes say that the kernel is expanding tabs into spaces.
+ − 1610 @end table
+ − 1611
+ − 1612 The following obsolete capabilities should be included in terminal
+ − 1613 descriptions when appropriate, but should not be looked at by new programs.
+ − 1614
+ − 1615 @table @samp
+ − 1616 @item nc
+ − 1617 @kindex nc
+ − 1618 Flag whose presence means the terminal does not support the ASCII
+ − 1619 carriage return character as @samp{cr}. This flag is needed because
+ − 1620 old programs assume, when the @samp{cr} capability is missing, that
+ − 1621 ASCII carriage return can be used for the purpose. We use @samp{nc}
+ − 1622 to tell the old programs that carriage return may not be used.
+ − 1623
+ − 1624 New programs should not assume any default for @samp{cr}, so they need
+ − 1625 not look at @samp{nc}. However, descriptions should contain @samp{nc}
+ − 1626 whenever they do not contain @samp{cr}.
+ − 1627
+ − 1628 @item xt
+ − 1629 @kindex xt
+ − 1630 Flag whose presence means that the ASCII tab character may not be used
+ − 1631 for cursor motion. This flag exists because old programs assume, when
+ − 1632 the @samp{ta} capability is missing, that ASCII tab can be used for
+ − 1633 the purpose. We use @samp{xt} to tell the old programs not to use tab.
+ − 1634
+ − 1635 New programs should not assume any default for @samp{ta}, so they need
+ − 1636 not look at @samp{xt} in connection with cursor motion. Note that
+ − 1637 @samp{xt} also has implications for standout mode (@pxref{Standout}).
+ − 1638 It is obsolete in regard to cursor motion but not in regard to
+ − 1639 standout.
+ − 1640
+ − 1641 In fact, @samp{xt} means that the terminal is a Teleray 1061.
+ − 1642
+ − 1643 @item bc
+ − 1644 @kindex bc
+ − 1645 Very obsolete alternative name for the @samp{le} capability.
+ − 1646
+ − 1647 @item bs
+ − 1648 @kindex bs
+ − 1649 Flag whose presence means that the ASCII character backspace may be
+ − 1650 used to move the cursor left. Obsolete; look at @samp{le} instead.
+ − 1651
+ − 1652 @item nl
+ − 1653 @kindex nl
+ − 1654 Obsolete capability which is a string that can either be used to move
+ − 1655 the cursor down or to scroll. The same string must scroll when used
+ − 1656 on the bottom line and move the cursor when used on any other line.
+ − 1657 New programs should use @samp{do} or @samp{sf}, and ignore @samp{nl}.
+ − 1658
+ − 1659 If there is no @samp{nl} capability, some old programs assume they can
+ − 1660 use the newline character for this purpose. These programs follow a
+ − 1661 bad practice, but because they exist, it is still desirable to define
+ − 1662 the @samp{nl} capability in a terminal description if the best way to
+ − 1663 move down is @emph{not} a newline.
+ − 1664 @end table
+ − 1665
+ − 1666 @node Wrapping, Scrolling, Cursor Motion, Capabilities
+ − 1667 @section Wrapping
+ − 1668 @cindex wrapping
+ − 1669
+ − 1670 @dfn{Wrapping} means moving the cursor from the right margin to the left
+ − 1671 margin of the following line. Some terminals wrap automatically when a
+ − 1672 graphic character is output in the last column, while others do not. Most
+ − 1673 application programs that use termcap need to know whether the terminal
+ − 1674 wraps. There are two special flag capabilities to describe what the
+ − 1675 terminal does when a graphic character is output in the last column.
+ − 1676
+ − 1677 @table @samp
+ − 1678 @item am
+ − 1679 @kindex am
+ − 1680 Flag whose presence means that writing a character in the last column
+ − 1681 causes the cursor to wrap to the beginning of the next line.
+ − 1682
+ − 1683 If @samp{am} is not present, writing in the last column leaves the
+ − 1684 cursor at the place where the character was written.
+ − 1685
+ − 1686 Writing in the last column of the last line should be avoided on
+ − 1687 terminals with @samp{am}, as it may or may not cause scrolling to
+ − 1688 occur (@pxref{Scrolling}). Scrolling is surely not what you would
+ − 1689 intend.
+ − 1690
+ − 1691 If your program needs to check the @samp{am} flag, then it also needs
+ − 1692 to check the @samp{xn} flag which indicates that wrapping happens in a
+ − 1693 strange way. Many common terminals have the @samp{xn} flag.
+ − 1694
+ − 1695 @item xn
+ − 1696 @kindex xn
+ − 1697 Flag whose presence means that the cursor wraps in a strange way. At
+ − 1698 least two distinct kinds of strange behavior are known; the termcap
+ − 1699 data base does not contain anything to distinguish the two.
+ − 1700
+ − 1701 On Concept-100 terminals, output in the last column wraps the cursor
+ − 1702 almost like an ordinary @samp{am} terminal. But if the next thing
+ − 1703 output is a newline, it is ignored.
+ − 1704
+ − 1705 DEC VT-100 terminals (when the wrap switch is on) do a different
+ − 1706 strange thing: the cursor wraps only if the next thing output is
+ − 1707 another graphic character. In fact, the wrap occurs when the
+ − 1708 following graphic character is received by the terminal, before the
+ − 1709 character is placed on the screen.
+ − 1710
+ − 1711 On both of these terminals, after writing in the last column a
+ − 1712 following graphic character will be displayed in the first column of
+ − 1713 the following line. But the effect of relative cursor motion
+ − 1714 characters such as newline or backspace at such a time depends on the
+ − 1715 terminal. The effect of erase or scrolling commands also depends on
+ − 1716 the terminal. You can't assume anything about what they will do on a
+ − 1717 terminal that has @samp{xn}. So, to be safe, you should never do
+ − 1718 these things at such a time on such a terminal.
+ − 1719
+ − 1720 To be sure of reliable results on a terminal which has the @samp{xn}
+ − 1721 flag, output a @samp{cm} absolute positioning command after writing in
+ − 1722 the last column. Another safe thing to do is to output carriage-return
+ − 1723 newline, which will leave the cursor at the beginning of the following
+ − 1724 line.
+ − 1725 @end table
+ − 1726
+ − 1727 @node Scrolling, Windows, Wrapping, Capabilities
+ − 1728 @section Scrolling
+ − 1729 @cindex scrolling
+ − 1730
+ − 1731 @dfn{Scrolling} means moving the contents of the screen up or down one or
+ − 1732 more lines. Moving the contents up is @dfn{forward scrolling}; moving them
+ − 1733 down is @dfn{reverse scrolling}.
+ − 1734
+ − 1735 Scrolling happens after each line of output during ordinary output on most
+ − 1736 display terminals. But in an application program that uses termcap for
+ − 1737 random-access output, scrolling happens only when explicitly requested with
+ − 1738 the commands in this section.
+ − 1739
+ − 1740 Some terminals have a @dfn{scroll region} feature. This lets you limit
+ − 1741 the effect of scrolling to a specified range of lines. Lines outside the
+ − 1742 range are unaffected when scrolling happens. The scroll region feature
+ − 1743 is available if either @samp{cs} or @samp{cS} is present.
+ − 1744
+ − 1745 @table @samp
+ − 1746 @item sf
+ − 1747 @kindex sf
+ − 1748 String of commands to scroll the screen one line up, assuming it is
+ − 1749 output with the cursor at the beginning of the bottom line.
+ − 1750
+ − 1751 @item sr
+ − 1752 @kindex sr
+ − 1753 String of commands to scroll the screen one line down, assuming it is
+ − 1754 output with the cursor at the beginning of the top line.
+ − 1755
+ − 1756 @item SF
+ − 1757 @kindex SF
+ − 1758 String of commands to scroll the screen @var{n} lines up, assuming it
+ − 1759 is output with the cursor at the beginning of the bottom line.
+ − 1760
+ − 1761 @item SR
+ − 1762 @kindex SR
+ − 1763 String of commands to scroll the screen @var{n} line down, assuming it
+ − 1764 is output with the cursor at the beginning of the top line.
+ − 1765
+ − 1766 @item cs
+ − 1767 @kindex cs
+ − 1768 String of commands to set the scroll region. This command takes two
+ − 1769 parameters, @var{start} and @var{end}, which are the line numbers
+ − 1770 (origin-zero) of the first line to include in the scroll region and of
+ − 1771 the last line to include in it. When a scroll region is set,
+ − 1772 scrolling is limited to the specified range of lines; lines outside
+ − 1773 the range are not affected by scroll commands.
+ − 1774
+ − 1775 Do not try to move the cursor outside the scroll region. The region
+ − 1776 remains set until explicitly removed. To remove the scroll region,
+ − 1777 use another @samp{cs} command specifying the full height of the
+ − 1778 screen.
+ − 1779
+ − 1780 The cursor position is undefined after the @samp{cs} command is set,
+ − 1781 so position the cursor with @samp{cm} immediately afterward.
+ − 1782
+ − 1783 @item cS
+ − 1784 @kindex cS
+ − 1785 String of commands to set the scroll region using parameters in
+ − 1786 different form. The effect is the same as if @samp{cs} were used.
+ − 1787 Four parameters are required:
+ − 1788
+ − 1789 @enumerate
+ − 1790 @item
+ − 1791 Total number of lines on the screen.
+ − 1792 @item
+ − 1793 Number of lines above desired scroll region.
+ − 1794 @item
+ − 1795 Number of lines below (outside of) desired scroll region.
+ − 1796 @item
+ − 1797 Total number of lines on the screen, the same as the first parameter.
+ − 1798 @end enumerate
+ − 1799
+ − 1800 This capability is a GNU extension that was invented to allow the Ann
+ − 1801 Arbor Ambassador's scroll-region command to be described; it could
+ − 1802 also be done by putting non-Unix @samp{%}-sequences into a @samp{cs}
+ − 1803 string, but that would have confused Unix programs that used the
+ − 1804 @samp{cs} capability with the Unix termcap. Currently only GNU Emacs
+ − 1805 uses the @samp{cS} capability.
+ − 1806
+ − 1807 @item ns
+ − 1808 @kindex ns
+ − 1809 Flag which means that the terminal does not normally scroll for
+ − 1810 ordinary sequential output. For modern terminals, this means that
+ − 1811 outputting a newline in ordinary sequential output with the cursor on
+ − 1812 the bottom line wraps to the top line. For some obsolete terminals,
+ − 1813 other things may happen.
+ − 1814
+ − 1815 The terminal may be able to scroll even if it does not normally do so.
+ − 1816 If the @samp{sf} capability is provided, it can be used for scrolling
+ − 1817 regardless of @samp{ns}.
+ − 1818
+ − 1819 @item da
+ − 1820 @kindex da
+ − 1821 Flag whose presence means that lines scrolled up off the top of the
+ − 1822 screen may come back if scrolling down is done subsequently.
+ − 1823
+ − 1824 The @samp{da} and @samp{db} flags do not, strictly speaking, affect
+ − 1825 how to scroll. But programs that scroll usually need to clear the
+ − 1826 lines scrolled onto the screen, if these flags are present.
+ − 1827
+ − 1828 @item db
+ − 1829 @kindex db
+ − 1830 Flag whose presence means that lines scrolled down off the bottom of
+ − 1831 the screen may come back if scrolling up is done subsequently.
+ − 1832
+ − 1833 @item lm
+ − 1834 @kindex lm
+ − 1835 Numeric value, the number of lines of display memory that the terminal
+ − 1836 has. A value of zero means that the terminal has more display memory
+ − 1837 than can fit on the screen, but no fixed number of lines. (The number
+ − 1838 of lines may depend on the amount of text in each line.)
+ − 1839 @end table
+ − 1840
+ − 1841 Any terminal description that defines @samp{SF} should also define @samp{sf};
+ − 1842 likewise for @samp{SR} and @samp{sr}. However, many terminals can only
+ − 1843 scroll by one line at a time, so it is common to find @samp{sf} and not
+ − 1844 @samp{SF}, or @samp{sr} without @samp{SR}.@refill
+ − 1845
+ − 1846 Therefore, all programs that use the scrolling facilities should be
+ − 1847 prepared to work with @samp{sf} in the case that @samp{SF} is absent, and
+ − 1848 likewise with @samp{sr}. On the other hand, an application program that
+ − 1849 uses only @samp{sf} and not @samp{SF} is acceptable, though slow on some
+ − 1850 terminals.@refill
+ − 1851
+ − 1852 When outputting a scroll command with @code{tputs}, the @var{nlines}
+ − 1853 argument should be the total number of lines in the portion of the screen
+ − 1854 being scrolled. Very often these commands require padding proportional to
+ − 1855 this number of lines. @xref{Padding}.
+ − 1856
+ − 1857 @node Windows, Clearing, Scrolling, Capabilities
+ − 1858 @section Windows
+ − 1859 @cindex window
+ − 1860
+ − 1861 A @dfn{window}, in termcap, is a rectangular portion of the screen to which
+ − 1862 all display operations are restricted. Wrapping, clearing, scrolling,
+ − 1863 insertion and deletion all operate as if the specified window were all the
+ − 1864 screen there was.
+ − 1865
+ − 1866 @table @samp
+ − 1867 @item wi
+ − 1868 @kindex wi
+ − 1869 String of commands to set the terminal output screen window.
+ − 1870 This string requires four parameters, all origin-zero:
+ − 1871 @enumerate
+ − 1872 @item
+ − 1873 The first line to include in the window.
+ − 1874 @item
+ − 1875 The last line to include in the window.
+ − 1876 @item
+ − 1877 The first column to include in the window.
+ − 1878 @item
+ − 1879 The last column to include in the window.
+ − 1880 @end enumerate
+ − 1881 @end table
+ − 1882
+ − 1883 Most terminals do not support windows.
+ − 1884
+ − 1885 @node Clearing, Insdel Line, Windows, Capabilities
+ − 1886 @section Clearing Parts of the Screen
+ − 1887 @cindex erasing
+ − 1888 @cindex clearing the screen
+ − 1889
+ − 1890 There are several terminal capabilities for clearing parts of the screen
+ − 1891 to blank. All display terminals support the @samp{cl} string, and most
+ − 1892 display terminals support all of these capabilities.
+ − 1893
+ − 1894 @table @samp
+ − 1895 @item cl
+ − 1896 @kindex cl
+ − 1897 String of commands to clear the entire screen and position the cursor
+ − 1898 at the upper left corner.
+ − 1899
+ − 1900 @item cd
+ − 1901 @kindex cd
+ − 1902 String of commands to clear the line the cursor is on, and all the
+ − 1903 lines below it, down to the bottom of the screen. This command string
+ − 1904 should be used only with the cursor in column zero; their effect is
+ − 1905 undefined if the cursor is elsewhere.
+ − 1906
+ − 1907 @item ce
+ − 1908 @kindex ce
+ − 1909 String of commands to clear from the cursor to the end of the current
+ − 1910 line.
+ − 1911
+ − 1912 @item ec
+ − 1913 @kindex ec
+ − 1914 String of commands to clear @var{n} characters, starting with the
+ − 1915 character that the cursor is on. This command string is expected to
+ − 1916 leave the cursor position unchanged. The parameter @var{n} should never
+ − 1917 be large enough to reach past the right margin; the effect of such a
+ − 1918 large parameter would be undefined.
+ − 1919 @end table
+ − 1920
+ − 1921 Clear to end of line (@samp{ce}) is extremely important in programs that
+ − 1922 maintain an updating display. Nearly all display terminals support this
904
+ − 1923 operation, so it is acceptable for an application program to refuse to
428
+ − 1924 work if @samp{ce} is not present. However, if you do not want this
+ − 1925 limitation, you can accomplish clearing to end of line by outputting spaces
+ − 1926 until you reach the right margin. In order to do this, you must know the
+ − 1927 current horizontal position. Also, this technique assumes that writing a
+ − 1928 space will erase. But this happens to be true on all the display terminals
+ − 1929 that fail to support @samp{ce}.
+ − 1930
+ − 1931 @node Insdel Line, Insdel Char, Clearing, Capabilities
+ − 1932 @section Insert/Delete Line
+ − 1933
+ − 1934 @cindex insert line
+ − 1935 @cindex delete line
+ − 1936 @dfn{Inserting a line} means creating a blank line in the middle
+ − 1937 of the screen, and pushing the existing lines of text apart. In fact,
+ − 1938 the lines above the insertion point do not change, while the lines below
+ − 1939 move down, and one is normally lost at the bottom of the screen.
+ − 1940
+ − 1941 @dfn{Deleting a line} means causing the line to disappear from the screen,
+ − 1942 closing up the gap by moving the lines below it upward. A new line
+ − 1943 appears at the bottom of the screen. Usually this line is blank, but
+ − 1944 on terminals with the @samp{db} flag it may be a line previously moved
+ − 1945 off the screen bottom by scrolling or line insertion.
+ − 1946
+ − 1947 Insertion and deletion of lines is useful in programs that maintain an
+ − 1948 updating display some parts of which may get longer or shorter. They are
+ − 1949 also useful in editors for scrolling parts of the screen, and for
+ − 1950 redisplaying after lines of text are killed or inserted.
+ − 1951
+ − 1952 Many terminals provide commands to insert or delete a single line at the
+ − 1953 cursor position. Some provide the ability to insert or delete several
+ − 1954 lines with one command, using the number of lines to insert or delete as a
+ − 1955 parameter. Always move the cursor to column zero before using any of
+ − 1956 these commands.
+ − 1957
+ − 1958 @table @samp
+ − 1959 @item al
+ − 1960 @kindex al
+ − 1961 String of commands to insert a blank line before the line the cursor
+ − 1962 is on. The existing line, and all lines below it, are moved down.
+ − 1963 The last line in the screen (or in the scroll region, if one is set)
+ − 1964 disappears and in most circumstances is discarded. It may not be
+ − 1965 discarded if the @samp{db} is present (@pxref{Scrolling}).
+ − 1966
+ − 1967 The cursor must be at the left margin before this command is used.
+ − 1968 This command does not move the cursor.
+ − 1969
+ − 1970 @item dl
+ − 1971 @kindex dl
+ − 1972 String of commands to delete the line the cursor is on. The following
+ − 1973 lines move up, and a blank line appears at the bottom of the screen
+ − 1974 (or bottom of the scroll region). If the terminal has the @samp{db}
+ − 1975 flag, a nonblank line previously pushed off the screen bottom may
+ − 1976 reappear at the bottom.
+ − 1977
+ − 1978 The cursor must be at the left margin before this command is used.
+ − 1979 This command does not move the cursor.
+ − 1980
+ − 1981 @item AL
+ − 1982 @kindex AL
+ − 1983 String of commands to insert @var{n} blank lines before the line that
+ − 1984 the cursor is on. It is like @samp{al} repeated @var{n} times, except
+ − 1985 that it is as fast as one @samp{al}.
+ − 1986
+ − 1987 @item DL
+ − 1988 @kindex DL
+ − 1989 String of commands to delete @var{n} lines starting with the line that
+ − 1990 the cursor is on. It is like @samp{dl} repeated @var{n} times, except
+ − 1991 that it is as fast as one @samp{dl}.
+ − 1992 @end table
+ − 1993
+ − 1994 Any terminal description that defines @samp{AL} should also define
+ − 1995 @samp{al}; likewise for @samp{DL} and @samp{dl}. However, many terminals
+ − 1996 can only insert or delete one line at a time, so it is common to find
+ − 1997 @samp{al} and not @samp{AL}, or @samp{dl} without @samp{DL}.@refill
+ − 1998
+ − 1999 Therefore, all programs that use the insert and delete facilities should be
+ − 2000 prepared to work with @samp{al} in the case that @samp{AL} is absent, and
+ − 2001 likewise with @samp{dl}. On the other hand, it is acceptable to write
+ − 2002 an application that uses only @samp{al} and @samp{dl} and does not look
+ − 2003 for @samp{AL} or @samp{DL} at all.@refill
+ − 2004
+ − 2005 If a terminal does not support line insertion and deletion directly,
+ − 2006 but does support a scroll region, the effect of insertion and deletion
+ − 2007 can be obtained with scrolling. However, it is up to the individual
+ − 2008 user program to check for this possibility and use the scrolling
+ − 2009 commands to get the desired result. It is fairly important to implement
+ − 2010 this alternate strategy, since it is the only way to get the effect of
+ − 2011 line insertion and deletion on the popular VT100 terminal.
+ − 2012
+ − 2013 Insertion and deletion of lines is affected by the scroll region on
+ − 2014 terminals that have a settable scroll region. This is useful when it is
+ − 2015 desirable to move any few consecutive lines up or down by a few lines.
+ − 2016 @xref{Scrolling}.
+ − 2017
+ − 2018 The line pushed off the bottom of the screen is not lost if the terminal
+ − 2019 has the @samp{db} flag capability; instead, it is pushed into display
+ − 2020 memory that does not appear on the screen. This is the same thing that
+ − 2021 happens when scrolling pushes a line off the bottom of the screen.
+ − 2022 Either reverse scrolling or deletion of a line can bring the apparently
+ − 2023 lost line back onto the bottom of the screen. If the terminal has the
+ − 2024 scroll region feature as well as @samp{db}, the pushed-out line really
+ − 2025 is lost if a scroll region is in effect.
+ − 2026
+ − 2027 When outputting an insert or delete command with @code{tputs}, the
+ − 2028 @var{nlines} argument should be the total number of lines from the cursor
+ − 2029 to the bottom of the screen (or scroll region). Very often these commands
+ − 2030 require padding proportional to this number of lines. @xref{Padding}.
+ − 2031
+ − 2032 For @samp{AL} and @samp{DL} the @var{nlines} argument should @emph{not}
+ − 2033 depend on the number of lines inserted or deleted; only the total number of
+ − 2034 lines affected. This is because it is just as fast to insert two or
+ − 2035 @var{n} lines with @samp{AL} as to insert one line with @samp{al}.
+ − 2036
+ − 2037 @node Insdel Char, Standout, Insdel Line, Capabilities
+ − 2038 @section Insert/Delete Character
+ − 2039 @cindex insert character
+ − 2040 @cindex delete character
+ − 2041
+ − 2042 @dfn{Inserting a character} means creating a blank space in the middle of a
+ − 2043 line, and pushing the rest of the line rightward. The character in the
+ − 2044 rightmost column is lost.
+ − 2045
+ − 2046 @dfn{Deleting a character} means causing the character to disappear from
+ − 2047 the screen, closing up the gap by moving the rest of the line leftward. A
+ − 2048 blank space appears in the rightmost column.
+ − 2049
+ − 2050 Insertion and deletion of characters is useful in programs that maintain an
+ − 2051 updating display some parts of which may get longer or shorter. It is also
+ − 2052 useful in editors for redisplaying the results of editing within a line.
+ − 2053
+ − 2054 Many terminals provide commands to insert or delete a single character at
+ − 2055 the cursor position. Some provide the ability to insert or delete several
+ − 2056 characters with one command, using the number of characters to insert or
+ − 2057 delete as a parameter.
+ − 2058
+ − 2059 @cindex insert mode
+ − 2060 Many terminals provide an insert mode in which outputting a graphic
+ − 2061 character has the added effect of inserting a position for that character.
+ − 2062 A special command string is used to enter insert mode and another is used
+ − 2063 to exit it. The reason for designing a terminal with an insert mode rather
+ − 2064 than an insert command is that inserting character positions is usually
+ − 2065 followed by writing characters into them. With insert mode, this is as
+ − 2066 fast as simply writing the characters, except for the fixed overhead of
+ − 2067 entering and leaving insert mode. However, when the line speed is great
+ − 2068 enough, padding may be required for the graphic characters output in insert
+ − 2069 mode.
+ − 2070
+ − 2071 Some terminals require you to enter insert mode and then output a special
+ − 2072 command for each position to be inserted. Or they may require special
+ − 2073 commands to be output before or after each graphic character to be
+ − 2074 inserted.
+ − 2075
+ − 2076 @cindex delete mode
+ − 2077 Deletion of characters is usually accomplished by a straightforward command
+ − 2078 to delete one or several positions; but on some terminals, it is necessary
+ − 2079 to enter a special delete mode before using the delete command, and leave
+ − 2080 delete mode afterward. Sometimes delete mode and insert mode are the same
+ − 2081 mode.
+ − 2082
+ − 2083 Some terminals make a distinction between character positions in which a
+ − 2084 space character has been output and positions which have been cleared. On
+ − 2085 these terminals, the effect of insert or delete character runs to the first
+ − 2086 cleared position rather than to the end of the line. In fact, the effect
+ − 2087 may run to more than one line if there is no cleared position to stop the
+ − 2088 shift on the first line. These terminals are identified by the @samp{in}
+ − 2089 flag capability.
+ − 2090
+ − 2091 On terminals with the @samp{in} flag, the technique of skipping over
+ − 2092 characters that you know were cleared, and then outputting text later on in
+ − 2093 the same line, causes later insert and delete character operations on that
+ − 2094 line to do nonstandard things. A program that has any chance of doing this
+ − 2095 must check for the @samp{in} flag and must be careful to write explicit
+ − 2096 space characters into the intermediate columns when @samp{in} is present.
+ − 2097
+ − 2098 A plethora of terminal capabilities are needed to describe all of this
+ − 2099 complexity. Here is a list of them all. Following the list, we present
+ − 2100 an algorithm for programs to use to take proper account of all of these
+ − 2101 capabilities.
+ − 2102
+ − 2103 @table @samp
+ − 2104 @item im
+ − 2105 @kindex im
+ − 2106 String of commands to enter insert mode.
+ − 2107
+ − 2108 If the terminal has no special insert mode, but it can insert
+ − 2109 characters with a special command, @samp{im} should be defined with a
+ − 2110 null value, because the @samp{vi} editor assumes that insertion of a
+ − 2111 character is impossible if @samp{im} is not provided.
+ − 2112
+ − 2113 New programs should not act like @samp{vi}. They should pay attention
+ − 2114 to @samp{im} only if it is defined.
+ − 2115
+ − 2116 @item ei
+ − 2117 @kindex ei
+ − 2118 String of commands to leave insert mode. This capability must be
+ − 2119 present if @samp{im} is.
+ − 2120
+ − 2121 On a few old terminals the same string is used to enter and exit
+ − 2122 insert mode. This string turns insert mode on if it was off, and off
+ − 2123 if it was on. You can tell these terminals because the @samp{ei}
+ − 2124 string equals the @samp{im} string. If you want to support these
+ − 2125 terminals, you must always remember accurately whether insert mode is
+ − 2126 in effect. However, these terminals are obsolete, and it is
+ − 2127 reasonable to refuse to support them. On all modern terminals, you
+ − 2128 can safely output @samp{ei} at any time to ensure that insert mode is
+ − 2129 turned off.
+ − 2130
+ − 2131 @item ic
+ − 2132 @kindex ic
+ − 2133 String of commands to insert one character position at the cursor.
+ − 2134 The cursor does not move.
+ − 2135
+ − 2136 If outputting a graphic character while in insert mode is sufficient
+ − 2137 to insert the character, then the @samp{ic} capability should be
+ − 2138 defined with a null value.
+ − 2139
+ − 2140 If your terminal offers a choice of ways to insert---either use insert
+ − 2141 mode or use a special command---then define @samp{im} and do not define
+ − 2142 @samp{ic}, since this gives the most efficient operation when several
+ − 2143 characters are to be inserted. @emph{Do not} define both strings, for
+ − 2144 that means that @emph{both} must be used each time insertion is done.
+ − 2145
+ − 2146 @item ip
+ − 2147 @kindex ip
+ − 2148 String of commands to output following an inserted graphic character
+ − 2149 in insert mode. Often it is used just for a padding spec, when padding
+ − 2150 is needed after an inserted character (@pxref{Padding}).
+ − 2151
+ − 2152 @item IC
+ − 2153 @kindex IC
+ − 2154 String of commands to insert @var{n} character positions at and after
+ − 2155 the cursor. It has the same effect as repeating the @samp{ic} string
+ − 2156 and a space, @var{n} times.
+ − 2157
+ − 2158 If @samp{IC} is provided, application programs may use it without first
+ − 2159 entering insert mode.
+ − 2160
+ − 2161 @item mi
+ − 2162 @kindex mi
+ − 2163 Flag whose presence means it is safe to move the cursor while in insert
+ − 2164 mode and assume the terminal remains in insert mode.
+ − 2165
+ − 2166 @item in
+ − 2167 @kindex in
+ − 2168 Flag whose presence means that the terminal distinguishes between
+ − 2169 character positions in which space characters have been output and
+ − 2170 positions which have been cleared.
+ − 2171 @end table
+ − 2172
+ − 2173 An application program can assume that the terminal can do character
+ − 2174 insertion if @emph{any one of} the capabilities @samp{IC}, @samp{im},
+ − 2175 @samp{ic} or @samp{ip} is provided.
+ − 2176
+ − 2177 To insert @var{n} blank character positions, move the cursor to the place
+ − 2178 to insert them and follow this algorithm:
+ − 2179
+ − 2180 @enumerate
+ − 2181 @item
+ − 2182 If an @samp{IC} string is provided, output it with parameter @var{n}
+ − 2183 and you are finished. Otherwise (or if you don't want to bother to
+ − 2184 look for an @samp{IC} string) follow the remaining steps.
+ − 2185
+ − 2186 @item
+ − 2187 Output the @samp{im} string, if there is one, unless the terminal is
+ − 2188 already in insert mode.
+ − 2189
+ − 2190 @item
+ − 2191 Repeat steps 4 through 6, @var{n} times.
+ − 2192
+ − 2193 @item
+ − 2194 Output the @samp{ic} string if any.
+ − 2195
+ − 2196 @item
+ − 2197 Output a space.
+ − 2198
+ − 2199 @item
+ − 2200 Output the @samp{ip} string if any.
+ − 2201
+ − 2202 @item
+ − 2203 Output the @samp{ei} string, eventually, to exit insert mode. There
+ − 2204 is no need to do this right away. If the @samp{mi} flag is present,
+ − 2205 you can move the cursor and the cursor will remain in insert mode;
+ − 2206 then you can do more insertion elsewhere without reentering insert
+ − 2207 mode.
+ − 2208 @end enumerate
+ − 2209
+ − 2210 To insert @var{n} graphic characters, position the cursor and follow this
+ − 2211 algorithm:
+ − 2212
+ − 2213 @enumerate
+ − 2214 @item
+ − 2215 If an @samp{IC} string is provided, output it with parameter @var{n},
+ − 2216 then output the graphic characters, and you are finished. Otherwise
+ − 2217 (or if you don't want to bother to look for an @samp{IC} string)
+ − 2218 follow the remaining steps.
+ − 2219
+ − 2220 @item
+ − 2221 Output the @samp{im} string, if there is one, unless the terminal is
+ − 2222 already in insert mode.
+ − 2223
+ − 2224 @item
+ − 2225 For each character to be output, repeat steps 4 through 6.
+ − 2226
+ − 2227 @item
+ − 2228 Output the @samp{ic} string if any.
+ − 2229
+ − 2230 @item
+ − 2231 Output the next graphic character.
+ − 2232
+ − 2233 @item
+ − 2234 Output the @samp{ip} string if any.
+ − 2235
+ − 2236 @item
+ − 2237 Output the @samp{ei} string, eventually, to exit insert mode. There
+ − 2238 is no need to do this right away. If the @samp{mi} flag is present,
+ − 2239 you can move the cursor and the cursor will remain in insert mode;
+ − 2240 then you can do more insertion elsewhere without reentering insert
+ − 2241 mode.
+ − 2242 @end enumerate
+ − 2243
+ − 2244 Note that this is not the same as the original Unix termcap specifications
+ − 2245 in one respect: it assumes that the @samp{IC} string can be used without
+ − 2246 entering insert mode. This is true as far as I know, and it allows you be
+ − 2247 able to avoid entering and leaving insert mode, and also to be able to
+ − 2248 avoid the inserted-character padding after the characters that go into the
+ − 2249 inserted positions.
+ − 2250
+ − 2251 Deletion of characters is less complicated; deleting one column is done by
+ − 2252 outputting the @samp{dc} string. However, there may be a delete mode that
+ − 2253 must be entered with @samp{dm} in order to make @samp{dc} work.
+ − 2254
+ − 2255 @table @samp
+ − 2256 @item dc
+ − 2257 @kindex dc
+ − 2258 String of commands to delete one character position at the cursor. If
+ − 2259 @samp{dc} is not present, the terminal cannot delete characters.
+ − 2260
+ − 2261 @item DC
+ − 2262 @kindex DC
+ − 2263 String of commands to delete @var{n} characters starting at the cursor.
+ − 2264 It has the same effect as repeating the @samp{dc} string @var{n} times.
+ − 2265 Any terminal description that has @samp{DC} also has @samp{dc}.
+ − 2266
+ − 2267 @item dm
+ − 2268 @kindex dm
+ − 2269 String of commands to enter delete mode. If not present, there is no
+ − 2270 delete mode, and @samp{dc} can be used at any time (assuming there is
+ − 2271 a @samp{dc}).
+ − 2272
+ − 2273 @item ed
+ − 2274 @kindex ed
+ − 2275 String of commands to exit delete mode. This must be present if
+ − 2276 @samp{dm} is.
+ − 2277 @end table
+ − 2278
+ − 2279 To delete @var{n} character positions, position the cursor and follow these
+ − 2280 steps:
+ − 2281
+ − 2282 @enumerate
+ − 2283 @item
+ − 2284 If the @samp{DC} string is present, output it with parameter @var{n}
+ − 2285 and you are finished. Otherwise, follow the remaining steps.
+ − 2286
+ − 2287 @item
+ − 2288 Output the @samp{dm} string, unless you know the terminal is already
+ − 2289 in delete mode.
+ − 2290
+ − 2291 @item
+ − 2292 Output the @samp{dc} string @var{n} times.
+ − 2293
+ − 2294 @item
+ − 2295 Output the @samp{ed} string eventually. If the flag capability
+ − 2296 @samp{mi} is present, you can move the cursor and do more deletion
+ − 2297 without leaving and reentering delete mode.
+ − 2298 @end enumerate
+ − 2299
+ − 2300 As with the @samp{IC} string, we have departed from the original termcap
+ − 2301 specifications by assuming that @samp{DC} works without entering delete
+ − 2302 mode even though @samp{dc} would not.
+ − 2303
+ − 2304 If the @samp{dm} and @samp{im} capabilities are both present and have the
+ − 2305 same value, it means that the terminal has one mode for both insertion and
+ − 2306 deletion. It is useful for a program to know this, because then it can do
+ − 2307 insertions after deletions, or vice versa, without leaving insert/delete
+ − 2308 mode and reentering it.
+ − 2309
+ − 2310 @node Standout, Underlining, Insdel Char, Capabilities
+ − 2311 @section Standout and Appearance Modes
+ − 2312 @cindex appearance modes
+ − 2313 @cindex standout
+ − 2314 @cindex magic cookie
+ − 2315
+ − 2316 @dfn{Appearance modes} are modifications to the ways characters are
+ − 2317 displayed. Typical appearance modes include reverse video, dim, bright,
+ − 2318 blinking, underlined, invisible, and alternate character set. Each kind of
+ − 2319 terminal supports various among these, or perhaps none.
+ − 2320
+ − 2321 For each type of terminal, one appearance mode or combination of them that
+ − 2322 looks good for highlighted text is chosen as the @dfn{standout mode}. The
+ − 2323 capabilities @samp{so} and @samp{se} say how to enter and leave standout
+ − 2324 mode. Programs that use appearance modes only to highlight some text
+ − 2325 generally use the standout mode so that they can work on as many terminals
+ − 2326 as possible. Use of specific appearance modes other than ``underlined''
+ − 2327 and ``alternate character set'' is rare.
+ − 2328
+ − 2329 Terminals that implement appearance modes fall into two general classes as
+ − 2330 to how they do it.
+ − 2331
+ − 2332 In some terminals, the presence or absence of any appearance mode is
+ − 2333 recorded separately for each character position. In these terminals, each
+ − 2334 graphic character written is given the appearance modes current at the time
+ − 2335 it is written, and keeps those modes until it is erased or overwritten.
+ − 2336 There are special commands to turn the appearance modes on or off for
+ − 2337 characters to be written in the future.
+ − 2338
+ − 2339 In other terminals, the change of appearance modes is represented by a
+ − 2340 marker that belongs to a certain screen position but affects all following
+ − 2341 screen positions until the next marker. These markers are traditionally
+ − 2342 called @dfn{magic cookies}.
+ − 2343
+ − 2344 The same capabilities (@samp{so}, @samp{se}, @samp{mb} and so on) for
+ − 2345 turning appearance modes on and off are used for both magic-cookie
+ − 2346 terminals and per-character terminals. On magic cookie terminals, these
+ − 2347 give the commands to write the magic cookies. On per-character terminals,
+ − 2348 they change the current modes that affect future output and erasure. Some
+ − 2349 simple applications can use these commands without knowing whether or not
+ − 2350 they work by means of cookies.
+ − 2351
+ − 2352 However, a program that maintains and updates a display needs to know
+ − 2353 whether the terminal uses magic cookies, and exactly what their effect is.
+ − 2354 This information comes from the @samp{sg} capability.
+ − 2355
+ − 2356 The @samp{sg} capability is a numeric capability whose presence indicates
+ − 2357 that the terminal uses magic cookies for appearance modes. Its value is
+ − 2358 the number of character positions that a magic cookie occupies. Usually
+ − 2359 the cookie occupies one or more character positions on the screen, and these
+ − 2360 character positions are displayed as blank, but in some terminals the
+ − 2361 cookie has zero width.
+ − 2362
+ − 2363 The @samp{sg} capability describes both the magic cookie to turn standout
+ − 2364 on and the cookie to turn it off. This makes the assumption that both
+ − 2365 kinds of cookie have the same width on the screen. If that is not true,
+ − 2366 the narrower cookie must be ``widened'' with spaces until it has the same
+ − 2367 width as the other.
+ − 2368
+ − 2369 On some magic cookie terminals, each line always starts with normal
+ − 2370 display; in other words, the scope of a magic cookie never extends over
+ − 2371 more than one line. But on other terminals, one magic cookie affects all
+ − 2372 the lines below it unless explicitly canceled. Termcap does not define any
+ − 2373 way to distinguish these two ways magic cookies can work. To be safe, it
+ − 2374 is best to put a cookie at the beginning of each line.
+ − 2375
+ − 2376 On some per-character terminals, standout mode or other appearance modes
+ − 2377 may be canceled by moving the cursor. On others, moving the cursor has no
+ − 2378 effect on the state of the appearance modes. The latter class of terminals
+ − 2379 are given the flag capability @samp{ms} (``can move in standout''). All
+ − 2380 programs that might have occasion to move the cursor while appearance modes
+ − 2381 are turned on must check for this flag; if it is not present, they should
+ − 2382 reset appearance modes to normal before doing cursor motion.
+ − 2383
+ − 2384 A program that has turned on only standout mode should use @samp{se} to
+ − 2385 reset the standout mode to normal. A program that has turned on only
+ − 2386 alternate character set mode should use @samp{ae} to return it to normal.
+ − 2387 If it is possible that any other appearance modes are turned on, use the
+ − 2388 @samp{me} capability to return them to normal.
+ − 2389
+ − 2390 Note that the commands to turn on one appearance mode, including @samp{so}
+ − 2391 and @samp{mb} @dots{} @samp{mr}, if used while some other appearance modes
+ − 2392 are turned on, may combine the two modes on some terminals but may turn off
+ − 2393 the mode previously enabled on other terminals. This is because some
+ − 2394 terminals do not have a command to set or clear one appearance mode without
+ − 2395 changing the others. Programs should not attempt to use appearance modes
+ − 2396 in combination except with @samp{sa}, and when switching from one single
+ − 2397 mode to another should always turn off the previously enabled mode and then
+ − 2398 turn on the new desired mode.
+ − 2399
+ − 2400 On some old terminals, the @samp{so} and @samp{se} commands may be the same
+ − 2401 command, which has the effect of turning standout on if it is off, or off
+ − 2402 it is on. It is therefore risky for a program to output extra @samp{se}
+ − 2403 commands for good measure. Fortunately, all these terminals are obsolete.
+ − 2404
+ − 2405 Programs that update displays in which standout-text may be replaced with
+ − 2406 non-standout text must check for the @samp{xs} flag. In a per-character
+ − 2407 terminal, this flag says that the only way to remove standout once written is
+ − 2408 to clear that portion of the line with the @samp{ce} string or something
+ − 2409 even more powerful (@pxref{Clearing}); just writing new characters at those
+ − 2410 screen positions will not change the modes in effect there. In a magic
+ − 2411 cookie terminal, @samp{xs} says that the only way to remove a cookie is to
+ − 2412 clear a portion of the line that includes the cookie; writing a different
+ − 2413 cookie at the same position does not work.
+ − 2414
+ − 2415 Such programs must also check for the @samp{xt} flag, which means that the
+ − 2416 terminal is a Teleray 1061. On this terminal it is impossible to position
+ − 2417 the cursor at the front of a magic cookie, so the only two ways to remove a
+ − 2418 cookie are (1) to delete the line it is on or (2) to position the cursor at
+ − 2419 least one character before it (possibly on a previous line) and output the
+ − 2420 @samp{se} string, which on these terminals finds and removes the next
+ − 2421 @samp{so} magic cookie on the screen. (It may also be possible to remove a
+ − 2422 cookie which is not at the beginning of a line by clearing that line.) The
+ − 2423 @samp{xt} capability also has implications for the use of tab characters,
+ − 2424 but in that regard it is obsolete (@pxref{Cursor Motion}).
+ − 2425
+ − 2426 @table @samp
+ − 2427 @item so
+ − 2428 @kindex so
+ − 2429 String of commands to enter standout mode.
+ − 2430
+ − 2431 @item se
+ − 2432 @kindex se
+ − 2433 String of commands to leave standout mode.
+ − 2434
+ − 2435 @item sg
+ − 2436 @kindex sg
+ − 2437 Numeric capability, the width on the screen of the magic cookie. This
+ − 2438 capability is absent in terminals that record appearance modes
+ − 2439 character by character.
+ − 2440
+ − 2441 @item ms
+ − 2442 @kindex ms
+ − 2443 Flag whose presence means that it is safe to move the cursor while the
+ − 2444 appearance modes are not in the normal state. If this flag is absent,
+ − 2445 programs should always reset the appearance modes to normal before
+ − 2446 moving the cursor.
+ − 2447
+ − 2448 @item xs
+ − 2449 @kindex xs
+ − 2450 Flag whose presence means that the only way to reset appearance modes
+ − 2451 already on the screen is to clear to end of line. On a per-character
+ − 2452 terminal, you must clear the area where the modes are set. On a magic
+ − 2453 cookie terminal, you must clear an area containing the cookie.
+ − 2454 See the discussion above.
+ − 2455
+ − 2456 @item xt
+ − 2457 @kindex xt
+ − 2458 Flag whose presence means that the cursor cannot be positioned right
+ − 2459 in front of a magic cookie, and that @samp{se} is a command to delete
+ − 2460 the next magic cookie following the cursor. See discussion above.
+ − 2461
+ − 2462 @item mb
+ − 2463 @kindex mb
+ − 2464 String of commands to enter blinking mode.
+ − 2465
+ − 2466 @item md
+ − 2467 @kindex md
+ − 2468 String of commands to enter double-bright mode.
+ − 2469
+ − 2470 @item mh
+ − 2471 @kindex mh
+ − 2472 String of commands to enter half-bright mode.
+ − 2473
+ − 2474 @item mk
+ − 2475 @kindex mk
+ − 2476 String of commands to enter invisible mode.
+ − 2477
+ − 2478 @item mp
+ − 2479 @kindex mp
+ − 2480 String of commands to enter protected mode.
+ − 2481
+ − 2482 @item mr
+ − 2483 @kindex mr
+ − 2484 String of commands to enter reverse-video mode.
+ − 2485
+ − 2486 @item me
+ − 2487 @kindex me
+ − 2488 String of commands to turn off all appearance modes, including
+ − 2489 standout mode and underline mode. On some terminals it also turns off
+ − 2490 alternate character set mode; on others, it may not. This capability
+ − 2491 must be present if any of @samp{mb} @dots{} @samp{mr} is present.
+ − 2492
+ − 2493 @item as
+ − 2494 @kindex as
+ − 2495 String of commands to turn on alternate character set mode. This mode
+ − 2496 assigns some or all graphic characters an alternate picture on the
+ − 2497 screen. There is no standard as to what the alternate pictures look
+ − 2498 like.
+ − 2499
+ − 2500 @item ae
+ − 2501 @kindex ae
+ − 2502 String of commands to turn off alternate character set mode.
+ − 2503
+ − 2504 @item sa
+ − 2505 @kindex sa
+ − 2506 String of commands to turn on an arbitrary combination of appearance
+ − 2507 modes. It accepts 9 parameters, each of which controls a particular
+ − 2508 kind of appearance mode. A parameter should be 1 to turn its appearance
+ − 2509 mode on, or zero to turn that mode off. Most terminals do not support
+ − 2510 the @samp{sa} capability, even among those that do have various
+ − 2511 appearance modes.
+ − 2512
+ − 2513 The nine parameters are, in order, @var{standout}, @var{underline},
+ − 2514 @var{reverse}, @var{blink}, @var{half-bright}, @var{double-bright},
+ − 2515 @var{blank}, @var{protect}, @var{alt char set}.
+ − 2516 @end table
+ − 2517
+ − 2518 @node Underlining, Cursor Visibility, Standout, Capabilities
+ − 2519 @section Underlining
+ − 2520 @cindex underlining
+ − 2521
+ − 2522 Underlining on most terminals is a kind of appearance mode, much like
+ − 2523 standout mode. Therefore, it may be implemented using magic cookies or as
+ − 2524 a flag in the terminal whose current state affects each character that is
+ − 2525 output. @xref{Standout}, for a full explanation.
+ − 2526
+ − 2527 The @samp{ug} capability is a numeric capability whose presence indicates
+ − 2528 that the terminal uses magic cookies for underlining. Its value is the
+ − 2529 number of character positions that a magic cookie for underlining occupies;
+ − 2530 it is used for underlining just as @samp{sg} is used for standout. Aside
+ − 2531 from the simplest applications, it is impossible to use underlining
+ − 2532 correctly without paying attention to the value of @samp{ug}.
+ − 2533
+ − 2534 @table @samp
+ − 2535 @item us
+ − 2536 @kindex us
+ − 2537 String of commands to turn on underline mode or to output a magic cookie
+ − 2538 to start underlining.
+ − 2539
+ − 2540 @item ue
+ − 2541 @kindex ue
+ − 2542 String of commands to turn off underline mode or to output a magic
+ − 2543 cookie to stop underlining.
+ − 2544
+ − 2545 @item ug
+ − 2546 @kindex ug
+ − 2547 Width of magic cookie that represents a change of underline mode;
+ − 2548 or missing, if the terminal does not use a magic cookie for this.
+ − 2549
+ − 2550 @item ms
+ − 2551 @kindex ms
+ − 2552 Flag whose presence means that it is safe to move the cursor while the
+ − 2553 appearance modes are not in the normal state. Underlining is an
+ − 2554 appearance mode. If this flag is absent, programs should always turn
+ − 2555 off underlining before moving the cursor.
+ − 2556 @end table
+ − 2557
+ − 2558 There are two other, older ways of doing underlining: there can be a
+ − 2559 command to underline a single character, or the output of @samp{_}, the
+ − 2560 ASCII underscore character, as an overstrike could cause a character to be
+ − 2561 underlined. New programs need not bother to handle these capabilities
+ − 2562 unless the author cares strongly about the obscure terminals which support
+ − 2563 them. However, terminal descriptions should provide these capabilities
+ − 2564 when appropriate.
+ − 2565
+ − 2566 @table @samp
+ − 2567 @item uc
+ − 2568 @kindex uc
+ − 2569 String of commands to underline the character under the cursor, and
+ − 2570 move the cursor right.
+ − 2571
+ − 2572 @item ul
+ − 2573 @kindex ul
+ − 2574 Flag whose presence means that the terminal can underline by
+ − 2575 overstriking an underscore character (@samp{_}); some terminals can do
+ − 2576 this even though they do not support overstriking in general. An
+ − 2577 implication of this flag is that when outputting new text to overwrite
+ − 2578 old text, underscore characters must be treated specially lest they
+ − 2579 underline the old text instead.
+ − 2580 @end table
+ − 2581
+ − 2582 @node Cursor Visibility, Bell, Underlining, Capabilities
+ − 2583 @section Cursor Visibility
+ − 2584 @cindex visibility
+ − 2585
+ − 2586 Some terminals have the ability to make the cursor invisible, or to enhance
+ − 2587 it. Enhancing the cursor is often done by programs that plan to use the
+ − 2588 cursor to indicate to the user a position of interest that may be anywhere
+ − 2589 on the screen---for example, the Emacs editor enhances the cursor on entry.
+ − 2590 Such programs should always restore the cursor to normal on exit.
+ − 2591
+ − 2592 @table @samp
+ − 2593 @item vs
+ − 2594 @kindex vs
+ − 2595 String of commands to enhance the cursor.
+ − 2596
+ − 2597 @item vi
+ − 2598 @kindex vi
+ − 2599 String of commands to make the cursor invisible.
+ − 2600
+ − 2601 @item ve
+ − 2602 @kindex ve
+ − 2603 String of commands to return the cursor to normal.
+ − 2604 @end table
+ − 2605
+ − 2606 If you define either @samp{vs} or @samp{vi}, you must also define @samp{ve}.
+ − 2607
+ − 2608 @node Bell, Keypad, Cursor Visibility, Capabilities
+ − 2609 @section Bell
+ − 2610 @cindex bell
+ − 2611 @cindex visible bell
+ − 2612
+ − 2613 Here we describe commands to make the terminal ask for the user to pay
+ − 2614 attention to it.
+ − 2615
+ − 2616 @table @samp
+ − 2617 @item bl
+ − 2618 @kindex bl
+ − 2619 String of commands to cause the terminal to make an audible sound. If
+ − 2620 this capability is absent, the terminal has no way to make a suitable
+ − 2621 sound.
+ − 2622
+ − 2623 @item vb
+ − 2624 @kindex vb
+ − 2625 String of commands to cause the screen to flash to attract attention
+ − 2626 (``visible bell''). If this capability is absent, the terminal has no
+ − 2627 way to do such a thing.
+ − 2628 @end table
+ − 2629
+ − 2630 @node Keypad, Meta Key, Bell, Capabilities
+ − 2631 @section Keypad and Function Keys
+ − 2632
+ − 2633 Many terminals have arrow and function keys that transmit specific
+ − 2634 character sequences to the computer. Since the precise sequences used
+ − 2635 depend on the terminal, termcap defines capabilities used to say what the
+ − 2636 sequences are. Unlike most termcap string-valued capabilities, these are
+ − 2637 not strings of commands to be sent to the terminal, rather strings that
+ − 2638 are received from the terminal.
+ − 2639
+ − 2640 Programs that expect to use keypad keys should check, initially, for a
+ − 2641 @samp{ks} capability and send it, to make the keypad actually transmit.
+ − 2642 Such programs should also send the @samp{ke} string when exiting.
+ − 2643
+ − 2644 @table @asis
+ − 2645 @item @samp{ks}
+ − 2646 @kindex ka@dots{}ku
+ − 2647 String of commands to make the function keys transmit. If this
+ − 2648 capability is not provided, but the others in this section are,
+ − 2649 programs may assume that the function keys always transmit.
+ − 2650
+ − 2651 @item @samp{ke}
+ − 2652 String of commands to make the function keys work locally. This
+ − 2653 capability is provided only if @samp{ks} is.
+ − 2654
+ − 2655 @item @samp{kl}
+ − 2656 String of input characters sent by typing the left-arrow key. If this
+ − 2657 capability is missing, you cannot expect the terminal to have a
+ − 2658 left-arrow key that transmits anything to the computer.
+ − 2659
+ − 2660 @item @samp{kr}
+ − 2661 String of input characters sent by typing the right-arrow key.
+ − 2662
+ − 2663 @item @samp{ku}
+ − 2664 String of input characters sent by typing the up-arrow key.
+ − 2665
+ − 2666 @item @samp{kd}
+ − 2667 String of input characters sent by typing the down-arrow key.
+ − 2668
+ − 2669 @item @samp{kh}
+ − 2670 String of input characters sent by typing the ``home-position'' key.
+ − 2671
+ − 2672 @item @samp{K1} @dots{} @samp{K5}
+ − 2673 @kindex K1@dots{}K5
+ − 2674 Strings of input characters sent by the five other keys in a 3-by-3
+ − 2675 array that includes the arrow keys, if the keyboard has such a 3-by-3
+ − 2676 array. Note that one of these keys may be the ``home-position'' key,
+ − 2677 in which case one of these capabilities will have the same value as
+ − 2678 the @samp{kh} key.
+ − 2679
+ − 2680 @item @samp{k0}
+ − 2681 String of input characters sent by function key 10 (or 0, if the terminal
+ − 2682 has one labeled 0).
+ − 2683
+ − 2684 @item @samp{k1} @dots{} @samp{k9}
+ − 2685 @kindex k1@dots{}k9
+ − 2686 Strings of input characters sent by function keys 1 through 9,
+ − 2687 provided for those function keys that exist.
+ − 2688
+ − 2689 @item @samp{kn}
+ − 2690 Number: the number of numbered function keys, if there are more than
+ − 2691 10.
+ − 2692
+ − 2693 @item @samp{l0} @dots{} @samp{l9}
+ − 2694 @kindex l0@dots{}l9
+ − 2695 Strings which are the labels appearing on the keyboard on the keys
+ − 2696 described by the capabilities @samp{k0} @dots{} @samp{l9}. These
+ − 2697 capabilities should be left undefined if the labels are @samp{f0} or
+ − 2698 @samp{f10} and @samp{f1} @dots{} @samp{f9}.@refill
+ − 2699
+ − 2700 @item @samp{kH}
+ − 2701 @kindex kA@dots{}kT
+ − 2702 String of input characters sent by the ``home down'' key, if there is
+ − 2703 one.
+ − 2704
+ − 2705 @item @samp{kb}
+ − 2706 String of input characters sent by the ``backspace'' key, if there is
+ − 2707 one.
+ − 2708
+ − 2709 @item @samp{ka}
+ − 2710 String of input characters sent by the ``clear all tabs'' key, if there
+ − 2711 is one.
+ − 2712
+ − 2713 @item @samp{kt}
+ − 2714 String of input characters sent by the ``clear tab stop this column''
+ − 2715 key, if there is one.
+ − 2716
+ − 2717 @item @samp{kC}
+ − 2718 String of input characters sent by the ``clear screen'' key, if there is
+ − 2719 one.
+ − 2720
+ − 2721 @item @samp{kD}
+ − 2722 String of input characters sent by the ``delete character'' key, if
+ − 2723 there is one.
+ − 2724
+ − 2725 @item @samp{kL}
+ − 2726 String of input characters sent by the ``delete line'' key, if there is
+ − 2727 one.
+ − 2728
+ − 2729 @item @samp{kM}
+ − 2730 String of input characters sent by the ``exit insert mode'' key, if
+ − 2731 there is one.
+ − 2732
+ − 2733 @item @samp{kE}
+ − 2734 String of input characters sent by the ``clear to end of line'' key, if
+ − 2735 there is one.
+ − 2736
+ − 2737 @item @samp{kS}
+ − 2738 String of input characters sent by the ``clear to end of screen'' key,
+ − 2739 if there is one.
+ − 2740
+ − 2741 @item @samp{kI}
+ − 2742 String of input characters sent by the ``insert character'' or ``enter
+ − 2743 insert mode'' key, if there is one.
+ − 2744
+ − 2745 @item @samp{kA}
+ − 2746 String of input characters sent by the ``insert line'' key, if there is
+ − 2747 one.
+ − 2748
+ − 2749 @item @samp{kN}
+ − 2750 String of input characters sent by the ``next page'' key, if there is
+ − 2751 one.
+ − 2752
+ − 2753 @item @samp{kP}
+ − 2754 String of input characters sent by the ``previous page'' key, if there is
+ − 2755 one.
+ − 2756
+ − 2757 @item @samp{kF}
+ − 2758 String of input characters sent by the ``scroll forward'' key, if there
+ − 2759 is one.
+ − 2760
+ − 2761 @item @samp{kR}
+ − 2762 String of input characters sent by the ``scroll reverse'' key, if there
+ − 2763 is one.
+ − 2764
+ − 2765 @item @samp{kT}
+ − 2766 String of input characters sent by the ``set tab stop in this column''
+ − 2767 key, if there is one.
+ − 2768
+ − 2769 @item @samp{ko}
+ − 2770 String listing the other function keys the terminal has. This is a
+ − 2771 very obsolete way of describing the same information found in the
+ − 2772 @samp{kH} @dots{} @samp{kT} keys. The string contains a list of
+ − 2773 two-character termcap capability names, separated by commas. The
+ − 2774 meaning is that for each capability name listed, the terminal has a
+ − 2775 key which sends the string which is the value of that capability. For
+ − 2776 example, the value @samp{:ko=cl,ll,sf,sr:} says that the terminal has
+ − 2777 four function keys which mean ``clear screen'', ``home down'',
+ − 2778 ``scroll forward'' and ``scroll reverse''.@refill
+ − 2779 @end table
+ − 2780
+ − 2781 @node Meta Key, Initialization, Keypad, Capabilities
+ − 2782 @section Meta Key
+ − 2783
+ − 2784 @cindex meta key
+ − 2785 A Meta key is a key on the keyboard that modifies each character you type
+ − 2786 by controlling the 0200 bit. This bit is on if and only if the Meta key is
+ − 2787 held down when the character is typed. Characters typed using the Meta key
+ − 2788 are called Meta characters. Emacs uses Meta characters as editing
+ − 2789 commands.
+ − 2790
+ − 2791 @table @samp
+ − 2792 @item km
+ − 2793 @kindex km
+ − 2794 Flag whose presence means that the terminal has a Meta key.
+ − 2795
+ − 2796 @item mm
+ − 2797 @kindex mm
+ − 2798 String of commands to enable the functioning of the Meta key.
+ − 2799
+ − 2800 @item mo
+ − 2801 @kindex mo
+ − 2802 String of commands to disable the functioning of the Meta key.
+ − 2803 @end table
+ − 2804
+ − 2805 If the terminal has @samp{km} but does not have @samp{mm} and @samp{mo}, it
+ − 2806 means that the Meta key always functions. If it has @samp{mm} and
+ − 2807 @samp{mo}, it means that the Meta key can be turned on or off. Send the
+ − 2808 @samp{mm} string to turn it on, and the @samp{mo} string to turn it off.
+ − 2809 I do not know why one would ever not want it to be on.
+ − 2810
+ − 2811 @node Initialization, Pad Specs, Meta Key, Capabilities
+ − 2812 @section Initialization
+ − 2813 @cindex reset
+ − 2814 @cindex initialization
+ − 2815 @cindex tab stops
+ − 2816
+ − 2817 @table @samp
+ − 2818 @item ti
+ − 2819 @kindex ti
+ − 2820 String of commands to put the terminal into whatever special modes are
+ − 2821 needed or appropriate for programs that move the cursor
+ − 2822 nonsequentially around the screen. Programs that use termcap to do
+ − 2823 full-screen display should output this string when they start up.
+ − 2824
+ − 2825 @item te
+ − 2826 @kindex te
+ − 2827 String of commands to undo what is done by the @samp{ti} string.
+ − 2828 Programs that output the @samp{ti} string on entry should output this
+ − 2829 string when they exit.
+ − 2830
+ − 2831 @item is
+ − 2832 @kindex is
+ − 2833 String of commands to initialize the terminal for each login session.
+ − 2834
+ − 2835 @item if
+ − 2836 @kindex if
+ − 2837 String which is the name of a file containing the string of commands
+ − 2838 to initialize the terminal for each session of use. Normally @samp{is}
+ − 2839 and @samp{if} are not both used.
+ − 2840
+ − 2841 @item i1
+ − 2842 @itemx i3
+ − 2843 @kindex i1
+ − 2844 @kindex i3
+ − 2845 Two more strings of commands to initialize the terminal for each login
+ − 2846 session. The @samp{i1} string (if defined) is output before @samp{is}
+ − 2847 or @samp{if}, and the @samp{i3} string (if defined) is output after.
+ − 2848
+ − 2849 The reason for having three separate initialization strings is to make
+ − 2850 it easier to define a group of related terminal types with slightly
+ − 2851 different initializations. Define two or three of the strings in the
+ − 2852 basic type; then the other types can override one or two of the
+ − 2853 strings.
+ − 2854
+ − 2855 @item rs
+ − 2856 @kindex rs
+ − 2857 String of commands to reset the terminal from any strange mode it may
+ − 2858 be in. Normally this includes the @samp{is} string (or other commands
+ − 2859 with the same effects) and more. What would go in the @samp{rs}
+ − 2860 string but not in the @samp{is} string are annoying or slow commands
+ − 2861 to bring the terminal back from strange modes that nobody would
+ − 2862 normally use.
+ − 2863
+ − 2864 @item it
+ − 2865 @kindex it
+ − 2866 Numeric value, the initial spacing between hardware tab stop columns
+ − 2867 when the terminal is powered up. Programs to initialize the terminal
+ − 2868 can use this to decide whether there is a need to set the tab stops.
+ − 2869 If the initial width is 8, well and good; if it is not 8, then the
+ − 2870 tab stops should be set; if they cannot be set, the kernel is told
+ − 2871 to convert tabs to spaces, and other programs will observe this and do
+ − 2872 likewise.
+ − 2873
+ − 2874 @item ct
+ − 2875 @kindex ct
+ − 2876 String of commands to clear all tab stops.
+ − 2877
+ − 2878 @item st
+ − 2879 @kindex st
+ − 2880 String of commands to set tab stop at current cursor column on all
+ − 2881 lines.
+ − 2882 @end table
+ − 2883
+ − 2884 @node Pad Specs, Status Line, Initialization, Capabilities
+ − 2885 @section Padding Capabilities
+ − 2886 @cindex padding
+ − 2887
+ − 2888 There are two terminal capabilities that exist just to explain the proper
+ − 2889 way to obey the padding specifications in all the command string
+ − 2890 capabilities. One, @samp{pc}, must be obeyed by all termcap-using
+ − 2891 programs.
+ − 2892
+ − 2893 @table @samp
+ − 2894 @item pb
+ − 2895 @kindex pb
+ − 2896 Numeric value, the lowest baud rate at which padding is actually
+ − 2897 needed. Programs may check this and refrain from doing any padding at
+ − 2898 lower speeds.
+ − 2899
+ − 2900 @item pc
+ − 2901 @kindex pc
+ − 2902 String of commands for padding. The first character of this string is
+ − 2903 to be used as the pad character, instead of using null characters for
+ − 2904 padding. If @samp{pc} is not provided, use null characters. Every
+ − 2905 program that uses termcap must look up this capability and use it to
+ − 2906 set the variable @code{PC} that is used by @code{tputs}.
+ − 2907 @xref{Padding}.
+ − 2908 @end table
+ − 2909
+ − 2910 Some termcap capabilities exist just to specify the amount of padding that
+ − 2911 the kernel should give to cursor motion commands used in ordinary
+ − 2912 sequential output.
+ − 2913
+ − 2914 @table @samp
+ − 2915 @item dC
+ − 2916 @kindex dC
+ − 2917 Numeric value, the number of msec of padding needed for the
+ − 2918 carriage-return character.
+ − 2919
+ − 2920 @item dN
+ − 2921 @kindex dN
+ − 2922 Numeric value, the number of msec of padding needed for the newline
+ − 2923 (linefeed) character.
+ − 2924
+ − 2925 @item dB
+ − 2926 @kindex dB
+ − 2927 Numeric value, the number of msec of padding needed for the backspace
+ − 2928 character.
+ − 2929
+ − 2930 @item dF
+ − 2931 @kindex dF
+ − 2932 Numeric value, the number of msec of padding needed for the formfeed
+ − 2933 character.
+ − 2934
+ − 2935 @item dT
+ − 2936 @kindex dT
+ − 2937 Numeric value, the number of msec of padding needed for the tab
+ − 2938 character.
+ − 2939 @end table
+ − 2940
+ − 2941 In some systems, the kernel uses the above capabilities; in other systems,
+ − 2942 the kernel uses the paddings specified in the string capabilities
+ − 2943 @samp{cr}, @samp{sf}, @samp{le}, @samp{ff} and @samp{ta}. Descriptions of
+ − 2944 terminals which require such padding should contain the @samp{dC} @dots{}
+ − 2945 @samp{dT} capabilities and also specify the appropriate padding in the
+ − 2946 corresponding string capabilities. Since no modern terminals require
+ − 2947 padding for ordinary sequential output, you probably won't need to do
+ − 2948 either of these things.
+ − 2949
+ − 2950 @node Status Line, Half-Line, Pad Specs, Capabilities
+ − 2951 @section Status Line
+ − 2952
+ − 2953 @cindex status line
+ − 2954 A @dfn{status line} is a line on the terminal that is not used for ordinary
+ − 2955 display output but instead used for a special message. The intended use is
+ − 2956 for a continuously updated description of what the user's program is doing,
+ − 2957 and that is where the name ``status line'' comes from, but in fact it could
+ − 2958 be used for anything. The distinguishing characteristic of a status line
+ − 2959 is that ordinary output to the terminal does not affect it; it changes only
+ − 2960 if the special status line commands of this section are used.
+ − 2961
+ − 2962 @table @samp
+ − 2963 @item hs
+ − 2964 @kindex hs
+ − 2965 Flag whose presence means that the terminal has a status line. If a
+ − 2966 terminal description specifies that there is a status line, it must
+ − 2967 provide the @samp{ts} and @samp{fs} capabilities.
+ − 2968
+ − 2969 @item ts
+ − 2970 @kindex ts
+ − 2971 String of commands to move the terminal cursor into the status line.
+ − 2972 Usually these commands must specifically record the old cursor
+ − 2973 position for the sake of the @samp{fs} string.
+ − 2974
+ − 2975 @item fs
+ − 2976 @kindex fs
+ − 2977 String of commands to move the cursor back from the status line to its
+ − 2978 previous position (outside the status line).
+ − 2979
+ − 2980 @item es
+ − 2981 @kindex es
+ − 2982 Flag whose presence means that other display commands work while
+ − 2983 writing the status line. In other words, one can clear parts of it,
+ − 2984 insert or delete characters, move the cursor within it using @samp{ch}
+ − 2985 if there is a @samp{ch} capability, enter and leave standout mode, and
+ − 2986 so on.
+ − 2987
+ − 2988 @item ds
+ − 2989 @kindex ds
+ − 2990 String of commands to disable the display of the status line. This
+ − 2991 may be absent, if there is no way to disable the status line display.
+ − 2992
+ − 2993 @item ws
+ − 2994 @kindex ws
+ − 2995 Numeric value, the width of the status line. If this capability is
+ − 2996 absent in a terminal that has a status line, it means the status line
+ − 2997 is the same width as the other lines.
+ − 2998
+ − 2999 Note that the value of @samp{ws} is sometimes as small as 8.
+ − 3000 @end table
+ − 3001
+ − 3002 @node Half-Line, Printer, Status Line, Capabilities
+ − 3003 @section Half-Line Motion
+ − 3004
+ − 3005 Some terminals have commands for moving the cursor vertically by half-lines,
+ − 3006 useful for outputting subscripts and superscripts. Mostly it is hardcopy
+ − 3007 terminals that have such features.
+ − 3008
+ − 3009 @table @samp
+ − 3010 @item hu
+ − 3011 @kindex hu
+ − 3012 String of commands to move the cursor up half a line. If the terminal
+ − 3013 is a display, it is your responsibility to avoid moving up past the
+ − 3014 top line; however, most likely the terminal that supports this is a
+ − 3015 hardcopy terminal and there is nothing to be concerned about.
+ − 3016
+ − 3017 @item hd
+ − 3018 @kindex hd
+ − 3019 String of commands to move the cursor down half a line. If the
+ − 3020 terminal is a display, it is your responsibility to avoid moving down
+ − 3021 past the bottom line, etc.
+ − 3022 @end table
+ − 3023
+ − 3024 @node Printer,, Half-Line, Capabilities
+ − 3025 @section Controlling Printers Attached to Terminals
+ − 3026 @cindex printer
+ − 3027
+ − 3028 Some terminals have attached hardcopy printer ports. They may be able to
+ − 3029 copy the screen contents to the printer; they may also be able to redirect
+ − 3030 output to the printer. Termcap does not have anything to tell the program
+ − 3031 whether the redirected output appears also on the screen; it does on some
+ − 3032 terminals but not all.
+ − 3033
+ − 3034 @table @samp
+ − 3035 @item ps
+ − 3036 @kindex ps
+ − 3037 String of commands to cause the contents of the screen to be printed.
+ − 3038 If it is absent, the screen contents cannot be printed.
+ − 3039
+ − 3040 @item po
+ − 3041 @kindex po
+ − 3042 String of commands to redirect further output to the printer.
+ − 3043
+ − 3044 @item pf
+ − 3045 @kindex pf
+ − 3046 String of commands to terminate redirection of output to the printer.
+ − 3047 This capability must be present in the description if @samp{po} is.
+ − 3048
+ − 3049 @item pO
+ − 3050 @kindex pO
+ − 3051 String of commands to redirect output to the printer for next @var{n}
+ − 3052 characters of output, regardless of what they are. Redirection will
+ − 3053 end automatically after @var{n} characters of further output. Until
+ − 3054 then, nothing that is output can end redirection, not even the
+ − 3055 @samp{pf} string if there is one. The number @var{n} should not be
+ − 3056 more than 255.
+ − 3057
+ − 3058 One use of this capability is to send non-text byte sequences (such as
+ − 3059 bit-maps) to the printer.
+ − 3060 @end table
+ − 3061
+ − 3062 Most terminals with printers do not support all of @samp{ps}, @samp{po} and
+ − 3063 @samp{pO}; any one or two of them may be supported. To make a program that
+ − 3064 can send output to all kinds of printers, it is necessary to check for all
+ − 3065 three of these capabilities, choose the most convenient of the ones that
+ − 3066 are provided, and use it in its own appropriate fashion.
+ − 3067
+ − 3068 @node Summary, Var Index, Capabilities, Top
+ − 3069 @chapter Summary of Capability Names
+ − 3070
+ − 3071 Here are all the terminal capability names in alphabetical order
+ − 3072 with a brief description of each. For cross references to their definitions,
+ − 3073 see the index of capability names (@pxref{Cap Index}).
+ − 3074
+ − 3075 @table @samp
+ − 3076 @item ae
+ − 3077 String to turn off alternate character set mode.
+ − 3078 @item al
+ − 3079 String to insert a blank line before the cursor.
+ − 3080 @item AL
+ − 3081 String to insert @var{n} blank lines before the cursor.
+ − 3082 @item am
+ − 3083 Flag: output to last column wraps cursor to next line.
+ − 3084 @item as
+ − 3085 String to turn on alternate character set mode.like.
+ − 3086 @item bc
+ − 3087 Very obsolete alternative name for the @samp{le} capability.
+ − 3088 @item bl
+ − 3089 String to sound the bell.
+ − 3090 @item bs
+ − 3091 Obsolete flag: ASCII backspace may be used for leftward motion.
+ − 3092 @item bt
+ − 3093 String to move the cursor left to the previous hardware tab stop column.
+ − 3094 @item bw
+ − 3095 Flag: @samp{le} at left margin wraps to end of previous line.
+ − 3096 @item CC
+ − 3097 String to change terminal's command character.
+ − 3098 @item cd
+ − 3099 String to clear the line the cursor is on, and following lines.
+ − 3100 @item ce
+ − 3101 String to clear from the cursor to the end of the line.
+ − 3102 @item ch
+ − 3103 String to position the cursor at column @var{c} in the same line.
+ − 3104 @item cl
+ − 3105 String to clear the entire screen and put cursor at upper left corner.
+ − 3106 @item cm
+ − 3107 String to position the cursor at line @var{l}, column @var{c}.
+ − 3108 @item CM
+ − 3109 String to position the cursor at line @var{l}, column
+ − 3110 @var{c}, relative to display memory.
+ − 3111 @item co
+ − 3112 Number: width of the screen.
+ − 3113 @item cr
+ − 3114 String to move cursor sideways to left margin.
+ − 3115 @item cs
+ − 3116 String to set the scroll region.
+ − 3117 @item cS
+ − 3118 Alternate form of string to set the scroll region.
+ − 3119 @item ct
+ − 3120 String to clear all tab stops.
+ − 3121 @item cv
+ − 3122 String to position the cursor at line @var{l} in the same column.
+ − 3123 @item da
+ − 3124 Flag: data scrolled off top of screen may be scrolled back.
+ − 3125 @item db
+ − 3126 Flag: data scrolled off bottom of screen may be scrolled back.
+ − 3127 @item dB
+ − 3128 Obsolete number: msec of padding needed for the backspace character.
+ − 3129 @item dc
+ − 3130 String to delete one character position at the cursor.
+ − 3131 @item dC
+ − 3132 Obsolete number: msec of padding needed for the carriage-return character.
+ − 3133 @item DC
+ − 3134 String to delete @var{n} characters starting at the cursor.
+ − 3135 @item dF
+ − 3136 Obsolete number: msec of padding needed for the formfeed character.
+ − 3137 @item dl
+ − 3138 String to delete the line the cursor is on.
+ − 3139 @item DL
+ − 3140 String to delete @var{n} lines starting with the cursor's line.
+ − 3141 @item dm
+ − 3142 String to enter delete mode.
+ − 3143 @item dN
+ − 3144 Obsolete number: msec of padding needed for the newline character.
+ − 3145 @item do
+ − 3146 String to move the cursor vertically down one line.
+ − 3147 @item DO
+ − 3148 String to move cursor vertically down @var{n} lines.
+ − 3149 @item ds
+ − 3150 String to disable the display of the status line.
+ − 3151 @item dT
+ − 3152 Obsolete number: msec of padding needed for the tab character.
+ − 3153 @item ec
+ − 3154 String of commands to clear @var{n} characters at cursor.
+ − 3155 @item ed
+ − 3156 String to exit delete mode.
+ − 3157 @item ei
+ − 3158 String to leave insert mode.
+ − 3159 @item eo
+ − 3160 Flag: output of a space can erase an overstrike.
+ − 3161 @item es
+ − 3162 Flag: other display commands work while writing the status line.
+ − 3163 @item ff
+ − 3164 String to advance to the next page, for a hardcopy terminal.
+ − 3165 @item fs
+ − 3166 String to move the cursor back from the status line to its
+ − 3167 previous position (outside the status line).
+ − 3168 @item gn
+ − 3169 Flag: this terminal type is generic, not real.
+ − 3170 @item hc
+ − 3171 Flag: hardcopy terminal.
+ − 3172 @item hd
+ − 3173 String to move the cursor down half a line.
+ − 3174 @item ho
+ − 3175 String to position cursor at upper left corner.
+ − 3176 @item hs
+ − 3177 Flag: the terminal has a status line.
+ − 3178 @item hu
+ − 3179 String to move the cursor up half a line.
+ − 3180 @item hz
+ − 3181 Flag: terminal cannot accept @samp{~} as output.
+ − 3182 @item i1
+ − 3183 String to initialize the terminal for each login session.
+ − 3184 @item i3
+ − 3185 String to initialize the terminal for each login session.
+ − 3186 @item ic
+ − 3187 String to insert one character position at the cursor.
+ − 3188 @item IC
+ − 3189 String to insert @var{n} character positions at the cursor.
+ − 3190 @item if
+ − 3191 String naming a file of commands to initialize the terminal.
+ − 3192 @item im
+ − 3193 String to enter insert mode.
+ − 3194 @item in
+ − 3195 Flag: outputting a space is different from moving over empty positions.
+ − 3196 @item ip
+ − 3197 String to output following an inserted character in insert mode.
+ − 3198 @item is
+ − 3199 String to initialize the terminal for each login session.
+ − 3200 @item it
+ − 3201 Number: initial spacing between hardware tab stop columns.
+ − 3202 @item k0
+ − 3203 String of input sent by function key 0 or 10.
+ − 3204 @item k1 @dots{} k9
+ − 3205 Strings of input sent by function keys 1 through 9.
+ − 3206 @item K1 @dots{} K5
+ − 3207 Strings sent by the five other keys in 3-by-3 array with arrows.
+ − 3208 @item ka
+ − 3209 String of input sent by the ``clear all tabs'' key.
+ − 3210 @item kA
+ − 3211 String of input sent by the ``insert line'' key.
+ − 3212 @item kb
+ − 3213 String of input sent by the ``backspace'' key.
+ − 3214 @item kC
+ − 3215 String of input sent by the ``clear screen'' key.
+ − 3216 @item kd
+ − 3217 String of input sent by typing the down-arrow key.
+ − 3218 @item kD
+ − 3219 String of input sent by the ``delete character'' key.
+ − 3220 @item ke
+ − 3221 String to make the function keys work locally.
+ − 3222 @item kE
+ − 3223 String of input sent by the ``clear to end of line'' key.
+ − 3224 @item kF
+ − 3225 String of input sent by the ``scroll forward'' key.
+ − 3226 @item kh
+ − 3227 String of input sent by typing the ``home-position'' key.
+ − 3228 @item kH
+ − 3229 String of input sent by the ``home down'' key.
+ − 3230 @item kI
+ − 3231 String of input sent by the ``insert character'' or ``enter
+ − 3232 insert mode'' key.
+ − 3233 @item kl
+ − 3234 String of input sent by typing the left-arrow key.
+ − 3235 @item kL
+ − 3236 String of input sent by the ``delete line'' key.
+ − 3237 @item km
+ − 3238 Flag: the terminal has a Meta key.
+ − 3239 @item kM
+ − 3240 String of input sent by the ``exit insert mode'' key.
+ − 3241 @item kn
+ − 3242 Numeric value, the number of numbered function keys.
+ − 3243 @item kN
+ − 3244 String of input sent by the ``next page'' key.
+ − 3245 @item ko
+ − 3246 Very obsolete string listing the terminal's named function keys.
+ − 3247 @item kP
+ − 3248 String of input sent by the ``previous page'' key.
+ − 3249 @item kr
+ − 3250 String of input sent by typing the right-arrow key.
+ − 3251 @item kR
+ − 3252 String of input sent by the ``scroll reverse'' key.
+ − 3253 @item ks
+ − 3254 String to make the function keys transmit.
+ − 3255 @item kS
+ − 3256 String of input sent by the ``clear to end of screen'' key.
+ − 3257 @item kt
+ − 3258 String of input sent by the ``clear tab stop this column'' key.
+ − 3259 @item kT
+ − 3260 String of input sent by the ``set tab stop in this column'' key.
+ − 3261 @item ku
+ − 3262 String of input sent by typing the up-arrow key.
+ − 3263 @item l0
+ − 3264 String on keyboard labelling function key 0 or 10.
+ − 3265 @item l1 @dots{} l9
+ − 3266 Strings on keyboard labelling function keys 1 through 9.
+ − 3267 @item le
+ − 3268 String to move the cursor left one column.
+ − 3269 @item LE
+ − 3270 String to move cursor left @var{n} columns.
+ − 3271 @item li
+ − 3272 Number: height of the screen.
+ − 3273 @item ll
+ − 3274 String to position cursor at lower left corner.
+ − 3275 @item lm
+ − 3276 Number: lines of display memory.
+ − 3277 @item mb
+ − 3278 String to enter blinking mode.
+ − 3279 @item md
+ − 3280 String to enter double-bright mode.
+ − 3281 @item me
+ − 3282 String to turn off all appearance modes
+ − 3283 @item mh
+ − 3284 String to enter half-bright mode.
+ − 3285 @item mi
+ − 3286 Flag: cursor motion in insert mode is safe.
+ − 3287 @item mk
+ − 3288 String to enter invisible mode.
+ − 3289 @item mm
+ − 3290 String to enable the functioning of the Meta key.
+ − 3291 @item mo
+ − 3292 String to disable the functioning of the Meta key.
+ − 3293 @item mp
+ − 3294 String to enter protected mode.
+ − 3295 @item mr
+ − 3296 String to enter reverse-video mode.
+ − 3297 @item ms
+ − 3298 Flag: cursor motion in standout mode is safe.
+ − 3299 @item nc
+ − 3300 Obsolete flag: do not use ASCII carriage-return on this terminal.
+ − 3301 @item nd
+ − 3302 String to move the cursor right one column.
+ − 3303 @item nl
+ − 3304 Obsolete alternative name for the @samp{do} and @samp{sf} capabilities.
+ − 3305 @item ns
+ − 3306 Flag: the terminal does not normally scroll for sequential output.
+ − 3307 @item nw
+ − 3308 String to move to start of next line, possibly clearing rest of old line.
+ − 3309 @item os
+ − 3310 Flag: terminal can overstrike.
+ − 3311 @item pb
+ − 3312 Number: the lowest baud rate at which padding is actually needed.
+ − 3313 @item pc
+ − 3314 String containing character for padding.
+ − 3315 @item pf
+ − 3316 String to terminate redirection of output to the printer.
+ − 3317 @item po
+ − 3318 String to redirect further output to the printer.
+ − 3319 @item pO
4312
+ − 3320 String to redirect @var{n} characters of output to the printer.
428
+ − 3321 @item ps
+ − 3322 String to print the screen on the attached printer.
+ − 3323 @item rc
+ − 3324 String to move to last saved cursor position.
+ − 3325 @item RI
+ − 3326 String to move cursor right @var{n} columns.
+ − 3327 @item rp
+ − 3328 String to output character @var{c} repeated @var{n} times.
+ − 3329 @item rs
+ − 3330 String to reset the terminal from any strange modes.
+ − 3331 @item sa
+ − 3332 String to turn on an arbitrary combination of appearance modes.
+ − 3333 @item sc
+ − 3334 String to save the current cursor position.
+ − 3335 @item se
+ − 3336 String to leave standout mode.
+ − 3337 @item sf
+ − 3338 String to scroll the screen one line up.
+ − 3339 @item SF
+ − 3340 String to scroll the screen @var{n} lines up.
+ − 3341 @item sg
+ − 3342 Number: width of magic standout cookie. Absent if magic cookies are
+ − 3343 not used.
+ − 3344 @item so
+ − 3345 String to enter standout mode.
+ − 3346 @item sr
+ − 3347 String to scroll the screen one line down.
+ − 3348 @item SR
+ − 3349 String to scroll the screen @var{n} line down.
+ − 3350 @item st
+ − 3351 String to set tab stop at current cursor column on all lines.
+ − 3352 programs.
+ − 3353 @item ta
+ − 3354 String to move the cursor right to the next hardware tab stop column.
+ − 3355 @item te
+ − 3356 String to return terminal to settings for sequential output.
+ − 3357 @item ti
+ − 3358 String to initialize terminal for random cursor motion.
+ − 3359 @item ts
+ − 3360 String to move the terminal cursor into the status line.
+ − 3361 @item uc
+ − 3362 String to underline one character and move cursor right.
+ − 3363 @item ue
+ − 3364 String to turn off underline mode
+ − 3365 @item ug
+ − 3366 Number: width of underlining magic cookie. Absent if underlining
+ − 3367 doesn't use magic cookies.
+ − 3368 @item ul
+ − 3369 Flag: underline by overstriking with an underscore.
+ − 3370 @item up
+ − 3371 String to move the cursor vertically up one line.
+ − 3372 @item UP
+ − 3373 String to move cursor vertically up @var{n} lines.
+ − 3374 @item us
+ − 3375 String to turn on underline mode
+ − 3376 @item vb
+ − 3377 String to make the screen flash.
+ − 3378 @item ve
+ − 3379 String to return the cursor to normal.
+ − 3380 @item vi
+ − 3381 String to make the cursor invisible.
+ − 3382 @item vs
+ − 3383 String to enhance the cursor.
+ − 3384 @item wi
+ − 3385 String to set the terminal output screen window.
+ − 3386 @item ws
+ − 3387 Number: the width of the status line.
+ − 3388 @item xb
+ − 3389 Flag: superbee terminal.
+ − 3390 @item xn
+ − 3391 Flag: cursor wraps in a strange way.
+ − 3392 @item xs
+ − 3393 Flag: clearing a line is the only way to clear the appearance modes of
+ − 3394 positions in that line (or, only way to remove magic cookies on that
+ − 3395 line).
+ − 3396 @item xt
+ − 3397 Flag: Teleray 1061; several strange characteristics.
+ − 3398 @end table
+ − 3399
+ − 3400 @node Var Index, Cap Index, Summary, Top
+ − 3401 @unnumbered Variable and Function Index
+ − 3402
+ − 3403 @printindex fn
+ − 3404
+ − 3405 @node Cap Index, Index, Var Index, Top
+ − 3406 @unnumbered Capability Index
+ − 3407
+ − 3408 @printindex ky
+ − 3409
+ − 3410 @node Index,, Cap Index, Top
+ − 3411 @unnumbered Concept Index
+ − 3412
+ − 3413 @printindex cp
+ − 3414
+ − 3415 @contents
+ − 3416 @bye