Merge branch 'vendor/OPENRESOLV' with the following changes:
[dragonfly.git] / share / termcap / termcap.5
1.\" Copyright (c) 1985, 1991, 1993, 1994
2.\" The Regents of the University of California. All rights reserved.
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
dc71b7ab 12.\" 3. Neither the name of the University nor the names of its contributors
13.\" may be used to endorse or promote products derived from this software
14.\" without specific prior written permission.
28.\" @(#)termcap.5 8.3 (Berkeley) 4/16/94
30.\" /***************************************************************************
32.\" ****************************************************************************
33.\" * ncurses is copyright (C) 1992-1995 *
34.\" * Zeyd M. Ben-Halim *
35.\" * *
36.\" * Eric S. Raymond *
37.\" * *
38.\" * *
39.\" * Permission is hereby granted to reproduce and distribute ncurses *
40.\" * by any means and for any fee, whether alone or as part of a *
41.\" * larger distribution, in source or in binary form, PROVIDED *
42.\" * this notice is included with any such distribution, and is not *
43.\" * removed from any of its header files. Mention of ncurses in any *
44.\" * applications linked with it is highly appreciated. *
45.\" * *
46.\" * ncurses comes AS IS with no warranty, implied or expressed. *
47.\" * *
48.\" ***************************************************************************/
7f49811b 50.\" $FreeBSD: src/share/termcap/termcap.5,v 1.30 2012/03/25 09:23:10 joel Exp $
984263bc 51.\"
186f72aa 52.Dd May 12, 2012
55.Sh NAME
56.Nm termcap
57.Nd terminal capability data base
64is a data base describing terminals,
66for example,
68.Xr \&vi 1
70.Xr ncurses 3 .
71Terminals are described in
73by giving a set of capabilities that they have and by describing
74how operations are performed.
75Padding requirements and initialization sequences
76are included in
77.Nm .
79Entries in
81consist of a number of `:'-separated fields.
82The first entry for each terminal gives the names that are known for the
83terminal, separated by `|' characters.
84The first name given is the most common abbreviation for the terminal.
85The last name given should be a long name fully identifying the terminal,
86and all others are understood as synonyms for the terminal name.
87All names but the last should be in lower case and contain no blanks;
88the last name may well contain upper case characters and blanks for
91Terminal names (except for the last, verbose entry)
92should be chosen using the following conventions.
93The particular piece of hardware making up the terminal
94should have a root name chosen, thus
95.Dq hp2621
96This name should not contain hyphens.
97Modes that the hardware can be in
98or user preferences
99should be indicated by appending a hyphen and an indicator of the mode.
100Therefore, a
101.Dq vt100
102in 132-column mode would be
103.Dq vt100-w .
104The following suffixes should be used where possible:
105.Bl -column indent "With automatic margins (usually default)xx" -offset indent
106.Sy "Suffix Meaning Example"
107-w Wide mode (more than 80 columns) vt100-w
108-am With automatic margins (usually default) vt100-am
109-nam Without automatic margins vt100-nam
110.Pf \- Ar n Ta No "Number of lines on screen aaa-60"
111-na No arrow keys (leave them in local) concept100-na
112.Pf \- Ar \&np Ta No "Number of pages of memory concept100-4p"
113-rv Reverse video concept100-rv
116The description field attempts to convey the semantics of the
118You may find some codes in the description field:
119.Bl -tag -width #[1-9]
120.It (P)
121indicates that padding may be specified.
122.It #[1-9]
123in the description field indicates that the string is passed through
3867d280 124.Xr tparm 3
984263bc 125or
3867d280 126.Xr tgoto 3
127with parms as given (#\fIi\fP).
128.It (P*)
129indicates that padding may vary in proportion to the number of
130lines affected.
131.It (#\d\fIi\fP\u)
132indicates the \fIi\fP\uth\d parameter.
135These are the boolean capabilities:
136.Bd -literal
137\fBBoolean TCap Description\fR
138\fBVariables Code\fR
139auto_left_margin bw cursor_left wraps from column 0 to last
140 column
141auto_right_margin am terminal has automatic margins
142no_esc_ctlc xb beehive (f1=escape, f2=ctrl C)
143ceol_standout_glitch xs standout not erased by overwriting (hp)
144eat_newline_glitch xn newline ignored after 80 cols (concept)
145erase_overstrike eo can erase overstrikes with a blank
146generic_type gn generic line type
147hard_copy hc hardcopy terminal
148has_meta_key km Has a meta key, sets msb high
149has_status_line hs has extra status line
150insert_null_glitch in insert mode distinguishes nulls
151memory_above da display may be retained above the screen
152memory_below db display may be retained below the screen
153move_insert_mode mi safe to move while in insert mode
154move_standout_mode ms safe to move while in standout mode
155over_strike os terminal can overstrike
156status_line_esc_ok es escape can be used on the status line
157dest_tabs_magic_smso xt tabs destructive, magic so char (t1061)
186f72aa 158tilde_glitch hz cannot print ~'s (hazeltine)
159transparent_underline ul underline character overstrikes
160xon_xoff xo terminal uses xon/xoff handshaking
161needs_xon_xoff nx padding will not work, xon/xoff required
162prtr_silent 5i printer will not echo on screen
163hard_cursor HC cursor is hard to see
164non_rev_rmcup NR enter_ca_mode does not reverse exit_ca_mode
165no_pad_char NP pad character does not exist
166non_dest_scroll_region ND scrolling region is non-destructive
167can_change cc terminal can re-define existing colors
168back_color_erase ut screen erased with background color
169hue_lightness_saturation hl terminal uses only HLS color
170 notation (tektronix)
171col_addr_glitch YA only positive motion for column address and
172 micro_column_address caps
173cr_cancels_micro_mode YB using cr turns off micro mode
174has_print_wheel YC printer needs operator to change character
175 set
176row_addr_glitch YD only positive motion for row_address and
177 micro_row_address caps
178semi_auto_right_margin YE printing in last column causes cr
179cpi_changes_res YF changing character pitch changes resolution
180lpi_changes_res YG changing line pitch changes resolution
183These are the numeric capabilities:
184.Bd -literal
185\fBNumeric TCap Description\fR
186\fBVariables Code\fR
187columns co number of columns in aline
188init_tabs it tabs initially every # spaces
189lines li number of lines on screen or page
190lines_of_memory lm lines of memory if > line. 0 => varies
191magic_cookie_glitch sg number of blank chars left by
192 enter_standout_mode or exit_standout_mode
193padding_baud_rate pb lowest baud rate where padding needed
194virtual_terminal vt virtual terminal number (CB/unix)
195width_status_line ws columns in status line
196num_labels Nl number of labels on screen
197label_height lh rows in each label
198label_width lw columns in each label
199max_attributes ma maximum combined attributes terminal can
200 handle
201maximum_windows MW maximum number of definable windows
202magic_cookie_glitch_ul ug number of blanks left by underline
204# These came in with SVr4's color support
206max_colors Co maximum numbers of colors on screen
207max_pairs pa maximum number of color-pairs on the screen
186f72aa 208no_color_video NC video attributes that cannot be used with
209 colors
211# The following numeric capabilities are present in the SVr4.0 term
212# structure, but are not yet documented in the man page.
213# They came in with SVr4's printer support.
215buffer_capacity Ya numbers of bytes buffered before printing
216dot_vert_spacing Yb spacing of pins vertically in pins per inch
217dot_horz_spacing Yc spacing of dots horizontally in dots per
218 inch
219max_micro_address Yd maximum value in micro_..._address
220max_micro_jump Ye maximum value in parm_..._micro
221micro_char_size Yf character size when in micro mode
222micro_line_size Yg line size when in micro mode
223number_of_pins Yh numbers of pins in print-head
224output_res_char Yi horizontal resolution in units per line
225output_res_line Yj vertical resolution in units per line
226output_res_horz_inch Yk horizontal resolution in units per inch
227output_res_vert_inch Yl vertical resolution in units per inch
228print_rate Ym print rate in chars per second
229wide_char_size Yn character step size when in double wide
230 mode
231buttons BT number of buttons on mouse
232bit_image_entwining Yo number of passed for each bit-image row
233bit_image_type Yp type of bit-image device
236These are the string capabilities:
237.Bd -literal
238\fBString TCap Description\fR
239\fBVariables Code\fR
240back_tab bt back tab (P)
241bell bl audible signal (bell) (P)
242carriage_return cr carriage return (P*)
243change_scroll_region cs change region to line #1 to line #2 (P)
244clear_all_tabs ct clear all tab stops (P)
245clear_screen cl clear screen and home cursor (P*)
246clr_eol ce clear to end of line (P)
247clr_eos cd clear to end of screen (P*)
248column_address ch horizontal position #1, absolute (P)
249command_character CC terminal settable cmd character in
250 prototype
251cursor_address cm move to row #1 columns #2
252cursor_down do down one line
253cursor_home ho home cursor
254cursor_invisible vi make cursor invisible
255cursor_left le move left one space
256cursor_mem_address CM memory relative cursor addressing
257cursor_normal ve make cursor appear normal (undo
258 cursor_invisible/cursor_visible)
259cursor_right nd move right one space
260cursor_to_ll ll last line, first column
261cursor_up up up one line
262cursor_visible vs make cursor very visible
263delete_character dc delete character (P*)
264delete_line dl delete line (P*)
265dis_status_line ds disable status line
266down_half_line hd half a line down
267enter_alt_charset_mode as start alternate character set (P)
268enter_blink_mode mb turn on blinking
269enter_bold_mode md turn on bold (extra bright) mode
270enter_ca_mode ti string to start programs using
271 cursor_address
272enter_delete_mode dm enter delete mode
273enter_dim_mode mh turn on half-bright mode
274enter_insert_mode im enter insert mode
275enter_secure_mode mk turn on blank mode (characters invisible)
276enter_protected_mode mp turn on protected mode
277enter_reverse_mode mr turn on reverse video mode
278enter_standout_mode so begin standout mode
279enter_underline_mode us begin underline mode
280erase_chars ec erase #1 characters (P)
281exit_alt_charset_mode ae end alternate character set (P)
282exit_attribute_mode me turn off all attributes
283exit_ca_mode te strings to end programs using cup
284exit_delete_mode ed end delete mode
285exit_insert_mode ei exit insert mode
286exit_standout_mode se exit standout mode
287exit_underline_mode ue exit underline mode
288flash_screen vb visible bell (may not move cursor)
289form_feed ff hardcopy terminal page eject (P*)
290from_status_line fs return from status line
291init_1string i1 initialization string
292init_2string is initialization string
293init_3string i3 initialization string
294init_file if name of initialization file
295insert_character ic insert character (P)
296insert_line al insert line (P*)
297insert_padding ip insert padding after inserted character
298key_backspace kb backspace key
299key_catab ka clear-all-tabs key
300key_clear kC clear-screen or erase key
301key_ctab kt clear-tab key
302key_dc kD delete-character key
303key_dl kL delete-line key
304key_down kd down-arrow key
305key_eic kM sent by rmir or smir in insert mode
306key_eol kE clear-to-end-of-line key
307key_eos kS clear-to-end-of-screen key
308key_f0 k0 F0 function key
309key_f1 k1 F1 function key
310key_f10 k; F10 function key
311key_f2 k2 F2 function key
312key_f3 k3 F3 function key
313key_f4 k4 F4 function key
314key_f5 k5 F5 function key
315key_f6 k6 F6 function key
316key_f7 k7 F7 function key
317key_f8 k8 F8 function key
318key_f9 k9 F9 function key
319key_home kh home key
320key_ic kI insert-character key
321key_il kA insert-line key
322key_left kl left-arrow key
323key_ll kH last-line key
324key_npage kN next-page key
325key_ppage kP prev-page key
326key_right kr right-arrow key
327key_sf kF scroll-forward key
328key_sr kR scroll-backward key
329key_stab kT set-tab key
330key_up ku up-arrow key
331keypad_local ke leave 'keyboard_transmit' mode
332keypad_xmit ks enter 'keyboard_transmit' mode
333lab_f0 l0 label on function key f0 if not f0
334lab_f1 l1 label on function key f1 if not f1
335lab_f10 la label on function key f10 if not f10
336lab_f2 l2 label on function key f2 if not f2
337lab_f3 l3 label on function key f3 if not f3
338lab_f4 l4 label on function key f4 if not f4
339lab_f5 l5 label on function key f5 if not f5
340lab_f6 l6 label on function key f6 if not f6
341lab_f7 l7 label on function key f7 if not f7
342lab_f8 l8 label on function key f8 if not f8
343lab_f9 l9 label on function key f9 if not f9
344meta_off mo turn off meta mode
345meta_on mm turn on meta mode (8th-bit on)
346newline nw newline (behave like cr followed by lf)
347pad_char pc padding char (instead of null)
348parm_dch DC delete #1 chars (P*)
349parm_delete_line DL delete #1 lines (P*)
350parm_down_cursor DO down #1 lines (P*)
351parm_ich IC insert #1 chars (P*)
352parm_index SF scroll forward #1 lines (P)
353parm_insert_line AL insert #1 lines (P*)
354parm_left_cursor LE move #1 chars to the left (P)
355parm_right_cursor RI move #1 chars to the right (P*)
356parm_rindex SR scroll back #1 lines (P)
357parm_up_cursor UP up #1 lines (P*)
358pkey_key pk program function key #1 to type string #2
359pkey_local pl program function key #1 to execute
360 string #2
361pkey_xmit px program function key #1 to transmit
362 string #2
363print_screen ps print contents of screen
364prtr_off pf turn off printer
365prtr_on po turn on printer
366repeat_char rp repeat char #1 #2 times (P*)
367reset_1string r1 reset string
368reset_2string r2 reset string
369reset_3string r3 reset string
370reset_file rf name of reset file
371restore_cursor rc restore cursor to last position of
372 save_cursor
373row_address cv vertical position #1 absolute (P)
374save_cursor sc save current cursor position (P)
375scroll_forward sf scroll text up (P)
376scroll_reverse sr scroll text down (P)
377set_attributes sa define video attributes #1-#9 (PG9)
378set_tab st set a tab in every row, current columns
379set_window wi current window is lines #1-#2 cols #3-#4
380tab ta tab to next 8-space hardware tab stop
381to_status_line ts move to status line
382underline_char uc underline char and move past it
383up_half_line hu half a line up
384init_prog iP path name of program for initialization
385key_a1 K1 upper left of keypad
386key_a3 K3 upper right of keypad
387key_b2 K2 center of keypad
388key_c1 K4 lower left of keypad
389key_c3 K5 lower right of keypad
390prtr_non pO turn on printer for #1 bytes
391termcap_init2 i2 secondary initialization string
392termcap_reset rs terminal reset string
394# SVr1 capabilities stop here. IBM's version of terminfo is the same as
395# SVr4 up to this point, but has a different set afterwards.
397char_padding rP like insert_padding but when in insert mode
398acs_chars ac graphics charset pairs - def=vt100
399plab_norm pn program label #1 to show string #2
400key_btab kB back-tab key
401enter_xon_mode SX turn on xon/xoff handshaking
402exit_xon_mode RX turn off xon/xoff handshaking
403enter_am_mode SA turn on automatic margins
404exit_am_mode RA turn off automatic margins
405xon_character XN XON character
406xoff_character XF XOFF character
407ena_acs eA enable alternate char set
408label_on LO turn on soft labels
409label_off LF turn off soft labels
410key_beg @1 begin key
411key_cancel @2 cancel key
412key_close @3 close key
413key_command @4 command key
414key_copy @5 copy key
415key_create @6 create key
416key_end @7 end key
417key_enter @8 enter/send key
418key_exit @9 exit key
419key_find @0 find key
420key_help %1 help key
421key_mark %2 mark key
422key_message %3 message key
423key_move %4 move key
424key_next %5 next key
425key_open %6 open key
426key_options %7 options key
427key_previous %8 previous key
428key_print %9 print key
429key_redo %0 redo key
430key_reference &1 reference key
431key_refresh &2 refresh key
432key_replace &3 replace key
433key_restart &4 restart key
434key_resume &5 resume key
435key_save &6 save key
436key_suspend &7 suspend key
437key_undo &8 undo key
438key_sbeg &9 shifted key
439key_scancel &0 shifted key
440key_scommand *1 shifted key
441key_scopy *2 shifted key
442key_screate *3 shifted key
443key_sdc *4 shifted key
444key_sdl *5 shifted key
445key_select *6 select key
446key_send *7 shifted key
447key_seol *8 shifted key
448key_sexit *9 shifted key
449key_sfind *0 shifted key
450key_shelp #1 shifted key
451key_shome #2 shifted key
452key_sic #3 shifted key
453key_sleft #4 shifted key
454key_smessage %a shifted key
455key_smove %b shifted key
456key_snext %c shifted key
457key_soptions %d shifted key
458key_sprevious %e shifted key
459key_sprint %f shifted key
460key_sredo %g shifted key
461key_sreplace %h shifted key
462key_sright %i shifted key
463key_srsume %j shifted key
464key_ssave !1 shifted key
465key_ssuspend !2 shifted key
466key_sundo !3 shifted key
467req_for_input RF send next input char (for ptys)
468key_f11 F1 F11 function key
469key_f12 F2 F12 function key
470key_f13 F3 F13 function key
471key_f14 F4 F14 function key
472key_f15 F5 F15 function key
473key_f16 F6 F16 function key
474key_f17 F7 F17 function key
475key_f18 F8 F18 function key
476key_f19 F9 F19 function key
477key_f20 FA F20 function key
478key_f21 FB F21 function key
479key_f22 FC F22 function key
480key_f23 FD F23 function key
481key_f24 FE F24 function key
482key_f25 FF F25 function key
483key_f26 FG F26 function key
484key_f27 FH F27 function key
485key_f28 FI F28 function key
486key_f29 FJ F29 function key
487key_f30 FK F30 function key
488key_f31 FL F31 function key
489key_f32 FM F32 function key
490key_f33 FN F33 function key
491key_f34 FO F34 function key
492key_f35 FP F35 function key
493key_f36 FQ F36 function key
494key_f37 FR F37 function key
495key_f38 FS F38 function key
496key_f39 FT F39 function key
497key_f40 FU F40 function key
498key_f41 FV F41 function key
499key_f42 FW F42 function key
500key_f43 FX F43 function key
501key_f44 FY F44 function key
502key_f45 FZ F45 function key
503key_f46 Fa F46 function key
504key_f47 Fb F47 function key
505key_f48 Fc F48 function key
506key_f49 Fd F49 function key
507key_f50 Fe F50 function key
508key_f51 Ff F51 function key
509key_f52 Fg F52 function key
510key_f53 Fh F53 function key
511key_f54 Fi F54 function key
512key_f55 Fj F55 function key
513key_f56 Fk F56 function key
514key_f57 Fl F57 function key
515key_f58 Fm F58 function key
516key_f59 Fn F59 function key
517key_f60 Fo F60 function key
518key_f61 Fp F61 function key
519key_f62 Fq F62 function key
520key_f63 Fr F63 function key
521clr_bol cb Clear to beginning of line
522clear_margins MC clear right and left soft margins
523set_left_margin ML set left soft margin
524set_right_margin MR set right soft margin
525label_format Lf label format
526set_clock SC set clock, #1 hrs #2 mins #3 secs
527display_clock DK display clock at (#1,#2)
528remove_clock RC remove clock
529create_window CW define a window #1 from #2, #3 to #4, #5
530goto_window WG go to window #1
531hangup HU hang-up phone
532dial_phone DI dial number #1
533quick_dial QD dial number #1 without checking
534tone TO select touch tone dialing
535pulse PU select pulse dialling
536flash_hook fh flash switch hook
537fixed_pause PA pause for 2-3 seconds
538wait_tone WA wait for dial-tone
539user0 u0 User string #0
540user1 u1 User string #1
541user2 u2 User string #2
542user3 u3 User string #3
543user4 u4 User string #4
544user5 u5 User string #5
545user6 u6 User string #6
546user7 u7 User string #7
547user8 u8 User string #8
548user9 u9 User string #9
550# SVr4 added these capabilities to support color
552orig_pair op Set default pair to its original value
553orig_colors oc Set all color pairs to the original ones
554initialize_color Ic initialize color #1 to (#2,#3,#4)
555initialize_pair Ip Initialize color pair #1 to fg=(#2,#3,#4),
556 bg=(#5,#6,#7)
557set_color_pair sp Set current color pair to #1
558set_foreground Sf Set foreground color #1
559set_background Sb Set background color #1
561# SVr4 added these capabilities to support printers
563change_char_pitch ZA Change number of characters per inch
564change_line_pitch ZB Change number of lines per inch
565change_res_horz ZC Change horizontal resolution
566change_res_vert ZD Change vertical resolution
567define_char ZE Define a character
568enter_doublewide_mode ZF Enter double-wide mode
569enter_draft_quality ZG Enter draft-quality mode
570enter_italics_mode ZH Enter italic mode
571enter_leftward_mode ZI Start leftward carriage motion
572enter_micro_mode ZJ Start micro-motion mode
573enter_near_letter_quality ZK Enter NLQ mode
574enter_normal_quality ZL Enter normal-quality mode
575enter_shadow_mode ZM Enter shadow-print mode
576enter_subscript_mode ZN Enter subscript mode
577enter_superscript_mode ZO Enter superscript mode
578enter_upward_mode ZP Start upward carriage motion
579exit_doublewide_mode ZQ End double-wide mode
580exit_italics_mode ZR End italic mode
581exit_leftward_mode ZS End left-motion mode
582exit_micro_mode ZT End micro-motion mode
583exit_shadow_mode ZU End shadow-print mode
584exit_subscript_mode ZV End subscript mode
585exit_superscript_mode ZW End superscript mode
586exit_upward_mode ZX End reverse character motion
587micro_column_address ZY Like column_address in micro mode
588micro_down ZZ Like cursor_down in micro mode
589micro_left Za Like cursor_left in micro mode
590micro_right Zb Like cursor_right in micro mode
591micro_row_address Zc Like row_address in micro mode
592micro_up Zd Like cursor_up in micro mode
593order_of_pins Ze Match software bits to print-head pins
594parm_down_micro Zf Like parm_down_cursor in micro mode
595parm_left_micro Zg Like parm_left_cursor in micro mode
596parm_right_micro Zh Like parm_right_cursor in micro mode
597parm_up_micro Zi Like parm_up_cursor in micro mode
598select_char_set Zj Select character set
599set_bottom_margin Zk Set bottom margin at current line
600set_bottom_margin_parm Zl Set bottom margin at line #1 or #2 lines
601 from bottom
602set_left_margin_parm Zm Set left (right) margin at column #1 (#2)
603set_right_margin_parm Zn Set right margin at column #1
604set_top_margin Zo Set top margin at current line
605set_top_margin_parm Zp Set top (bottom) margin at row #1 (#2)
606start_bit_image Zq Start printing bit image graphics
607start_char_set_def Zr Start character set definition
608stop_bit_image Zs Stop printing bit image graphics
609stop_char_set_def Zt End definition of character aet
610subscript_characters Zu List of subscriptible characters
611superscript_characters Zv List of superscriptible characters
612these_cause_cr Zw Printing any of these chars causes CR
613zero_motion Zx No motion for subsequent character
615# The following string capabilities are present in the SVr4.0 term
616# structure, but are not documented in the man page.
618char_set_names Zy List of character set names
619key_mouse Km Mouse event has occurred
620mouse_info Mi Mouse status information
621req_mouse_pos RQ Request mouse position
622get_mouse Gm Curses should get button events
623set_a_foreground AF Set ANSI foreground color
624set_a_background AB Set ANSI background color
625pkey_plab xl Program function key #1 to type string #2
626 and show string #3
627device_type dv Indicate language/codeset support
628code_set_init ci Init sequence for multiple codesets
629set0_des_seq s0 Shift to code set 0 (EUC set 0, ASCII)
630set1_des_seq s1 Shift to code set 1
631set2_des_seq s2 Shift to code set 2
632set3_des_seq s3 Shift to code set 3
633set_lr_margin ML Set both left and right margins to #1, #2
634set_tb_margin MT Sets both top and bottom margins to #1, #2
635bit_image_repeat Xy Repeat bit image cell #1 #2 times
636bit_image_newline Zz Move to next row of the bit image
637bit_image_carriage_return Yv Move to beginning of same row
638color_names Yw Give name for color #1
639define_bit_image_region Yx Define rectangular bit image region
640end_bit_image_region Yy End a bit-image region
641set_color_band Yz Change to ribbon color #1
642set_page_length YZ Set page length to #1 lines
644# SVr4 added these capabilities for direct PC-clone support
646display_pc_char S1 Display PC character
647enter_pc_charset_mode S2 Enter PC character display mode
648exit_pc_charset_mode S3 Exit PC character display mode
649enter_scancode_mode S4 Enter PC scancode mode
650exit_scancode_mode S5 Exit PC scancode mode
651pc_term_options S6 PC terminal options
652scancode_escape S7 Escape for scancode emulation
653alt_scancode_esc S8 Alternate escape for scancode emulation
655# The XSI Curses standard added these.
657enter_horizontal_hl_mode Xh Enter horizontal highlight mode
658enter_left_hl_mode Xl Enter left highlight mode
659enter_low_hl_mode Xo Enter low highlight mode
660enter_right_hl_mode Xr Enter right highlight mode
661enter_top_hl_mode Xt Enter top highlight mode
662enter_vertical_hl_mode Xv Enter vertical highlight mode
665Obsolete termcap capabilities.
666New software should not rely on them at all.
667.Bd -literal
668\fBBoolean TCap Description\fR
669\fBVariables Code\fR
670linefeed_is_newline NL move down with ^J
671even_parity EP terminal requires even parity
672odd_parity OP terminal requires odd parity
673half_duplex HD terminal is half-duplex
674lower_case_only LC terminal has only lower case
675upper_case_only UC terminal has only upper case
676has_hardware_tabs pt has 8-char tabs invoked with ^I
677return_does_clr_eol xr return clears the line
678tek_4025_insert_line xx Tektronix 4025 insert-line glitch
679backspaces_with_bs bs uses ^H to move left
680crt_no_scrolling ns crt cannot scroll
681no_correctly_working_cr nc no way to go to start of line
683.Bd -literal
684\fBNumber TCap Description\fR
685\fBVariables Code\fR
686backspace_delay dB padding required for ^H
687form_feed_delay dF padding required for ^L
688horizontal_tab_delay dT padding required for ^I
689vertical_tab_delay dV padding required for ^V
690number_of_function_keys kn count of function keys
691carriage_return_delay dC pad needed for CR
692new_line_delay dN pad needed for LF
694.Bd -literal
695\fBString TCap Description\fR
696\fBVariables Code\fR
697other_non_function_keys ko list of self-mapped keycaps
698arrow_key_map ma map arrow keys
699memory_lock_above ml lock visible screen memory above the
700 current line
701memory_unlock mu unlock visible screen memory above the
702 current line
703linefeed_if_not_lf nl use to move down
704backspace_if_not_bs bc move left, if not ^H
706.Ss A Sample Entry
707The following entry, which describes the Concept\-100, is among the more
708complex entries in the
710file as of this writing.
711.Bd -literal
712ca\||\|concept100\||\|c100\||\|concept\||\|c104\||\|concept100-4p\||\|HDS Concept\-100:\e
713 :al=3*\eE^R:am:bl=^G:cd=16*\eE^C:ce=16\eE^U:cl=2*^L:cm=\eEa%+ %+ :\e
715 :ip=16*:is=\eEU\eEf\eE7\eE5\eE8\eEl\eENH\eEK\eE\e200\eEo&\e200\eEo\e47\eE:k1=\eE5:\e
716 :k2=\eE6:k3=\eE7:kb=^h:kd=\eE<:ke=\eEx:kh=\eE?:kl=\eE>:kr=\eE=:ks=\eEX:\e
717 :ku=\eE;:le=^H:li#24:mb=\eEC:me=\eEN\e200:mh=\eEE:mi:mk=\eEH:mp=\eEI:\e
718 :mr=\eED:nd=\eE=:pb#9600:rp=0.2*\eEr%.%+ :se=\eEd\eEe:sf=^J:so=\eEE\eED:\e
719 :.ta=8\et:te=\eEv \e200\e200\e200\e200\e200\e200\eEp\er\en:\e
720 :ti=\eEU\eEv 8p\eEp\er:ue=\eEg:ul:up=\eE;:us=\eEG:\e
721 :vb=\eEk\e200\e200\e200\e200\e200\e200\e200\e200\e200\e200\e200\e200\e200\e200\eEK:\e
722 :ve=\eEw:vs=\eEW:vt#8:xn:\e
723 :bs:cr=^M:dC#9:dT#8:nl=^J:ta=^I:pt:
726Entries may continue onto multiple lines by giving a \e as the last
727character of a line, and empty fields
728may be included for readability (here between the last field on a line
729and the first field on the next).
730Comments may be included on lines beginning with
731.Dq # .
732.Ss Types of Capabilities
733Capabilities in
735are of three types: Boolean capabilities,
736which indicate particular features that the terminal has;
737numeric capabilities,
738giving the size of the display or the size of other attributes;
739and string capabilities,
740which give character sequences that can be used to perform particular
741terminal operations.
742All capabilities have two-letter codes.
743For instance, the fact that
744the Concept has
745.Em automatic margins
746(an automatic return and linefeed
747when the end of a line is reached) is indicated by the Boolean capability
748.Sy \&am .
749Hence the description of the Concept includes
750.Sy \&am .
752Numeric capabilities are followed by the character `#' then the value.
753In the example above
754.Sy \&co ,
755which indicates the number of columns the display has,
756gives the value `80' for the Concept.
758Finally, string-valued capabilities, such as
759.Sy \&ce
761sequence) are given by the two-letter code, an `=', then a string
762ending at the next following `:'.
763A delay in milliseconds may appear after
764the `=' in such a capability,
765which causes padding characters to be supplied by
3867d280 766.Xr tputs 3
767after the remainder of the string is sent to provide this delay.
768The delay can be either a number,
769such as `20', or a number followed by
770an `*',
771such as `3*'.
772An `*' indicates that the padding required is proportional
773to the number of lines affected by the operation, and the amount given is
774the per-affected-line padding required.
775(In the case of insert-character,
776the factor is still the number of
777.Em lines
779this is always 1 unless the terminal has
780.Sy \&in
781and the software uses it.)
782When an `*' is specified, it is sometimes useful to give a delay of the form
783`3.5' to specify a delay per line to tenths of milliseconds.
784(Only one decimal place is allowed.)
786A number of escape sequences are provided in the string-valued capabilities
787for easy encoding of control characters there.
788.Sy \&\eE
789maps to an
790.Dv ESC
792.Sy \&^X
793maps to a control-X for any appropriate X,
794and the sequences
795.Sy \&\en
796.Sy \&\er
797.Sy \&\et
798.Sy \&\eb
799.Sy \&\ef
800map to linefeed, return, tab, backspace, and formfeed, respectively.
801Finally, characters may be given as three octal digits after a
802.Sy \&\e ,
803and the characters
804.Sy \&^
806.Sy \&\e
807may be given as
808.Sy \&\e^
810.Sy \&\e\e .
811If it is necessary to place a
812.Sy \&:
813in a capability it must be escaped as
814.Sy \e:
815or be encoded as
816.Sy \&\e072 .
817If it is necessary to place a
818.Dv NUL
819character in a string capability it
820must be encoded as
821.Sy \&\e200 .
822(The routines that deal with
824use C strings and strip the high bits of the output very late, so that
826.Sy \&\e200
827comes out as a
828.Sy \&\e000
831Sometimes individual capabilities must be commented out.
832To do this, put a period before the capability name.
833For example, see the first
834.Sy \&cr
836.Sy \&ta
837in the example above.
838.Ss Preparing Descriptions
839The most effective way to prepare a terminal description is by imitating
840the description of a similar terminal in
842and to build up a description gradually, using partial descriptions
3867d280 844.Xr \&vi 1
845to check that they are correct.
846Be aware that a very unusual terminal may expose deficiencies in
847the ability of the
849file to describe it
850or bugs in
3867d280 851.Xr \&vi 1 .
852To easily test a new terminal description you are working on
853you can put it in your home directory in a file called
854.Pa .termcap
855and programs will look there before looking in
856.Pa /usr/share/misc/termcap .
857You can also set the environment variable
859to a list of absolute file pathnames (separated by spaces or colons),
860one of which contains the description you are working on,
861and programs will search them in the order listed, and nowhere else.
863.Xr termcap 3 .
866environment variable is usually set to the
868entry itself
869to avoid reading files when starting up a program.
871To get the padding for insert-line right
872(if the terminal manufacturer did not document it),
873a severe test is to use
3867d280 874.Xr \&vi 1
875to edit
876.Pa /etc/passwd
877at 9600 baud, delete roughly 16 lines from the middle of the screen,
878then hit the `u' key several times quickly.
879If the display messes up, more padding is usually needed.
880A similar test can be used for insert-character.
881.Ss Basic Capabilities
882The number of columns on each line of the display is given by the
883.Sy \&co
884numeric capability.
885If the display is a
886.Tn CRT ,
887then the
888number of lines on the screen is given by the
889.Sy \&li
891If the display wraps around to the beginning of the next line when
892the cursor reaches the right margin, then it should have the
893.Sy \&am
895If the terminal can clear its screen,
896the code to do this is given by the
897.Sy \&cl
898string capability.
899If the terminal overstrikes
900(rather than clearing the position when a character is overwritten),
901it should have the
902.Sy \&os
904If the terminal is a printing terminal,
905with no soft copy unit,
906give it both
907.Sy \&hc
909.Sy \&os .
910.Pf ( Sy \&os
911applies to storage scope terminals,
912such as the Tektronix 4010 series,
913as well as to hard copy and
914.Tn APL
916If there is a code to move the cursor to the left edge of the current row,
917give this as
918.Sy \&cr .
919(Normally this will be carriage-return,
920.Sy \&^M . )
921If there is a code to produce an audible signal (bell, beep,
923give this as
924.Sy \&bl .
926If there is a code (such as backspace)
927to move the cursor one position to the left,
928that capability should be given as
929.Sy \&le .
931codes to move to the right, up, and down
932should be given as
933.Sy \&nd ,
934.Sy \&up ,
936.Sy \&do ,
939.Em local cursor motions
940should not alter the text they pass over;
941for example, you would not normally use
942.Dq nd=\ \&
943unless the terminal has the
944.Sy \&os
946because the space would erase the character moved over.
948A very important point here is that the local cursor motions encoded
951have undefined behavior at the left and top edges of a
952.Tn CRT
954Programs should never attempt to backspace around the left edge,
956.Sy \&bw
957is given, and never attempt to go up off the top
958using local cursor motions.
960In order to scroll text up,
961a program goes to the bottom left corner of the screen and sends the
962.Sy \&sf
963(index) string.
964To scroll text down,
965a program goes to the top left corner of the screen and sends the
966.Sy \&sr
967(reverse index) string.
968The strings
969.Sy \&sf
971.Sy \&sr
972have undefined behavior
973when not on their respective corners of the screen.
974Parameterized versions of the scrolling sequences are
975.Sy \&SF
977.Sy \&SR ,
978which have the same semantics as
979.Sy \&sf
981.Sy \&sr
982except that they take one parameter
983and scroll that many lines.
984They also have undefined behavior
985except at the appropriate corner of the screen.
988.Sy \&am
989capability tells whether the cursor sticks at the right
990edge of the screen when text is output there,
991but this does not necessarily apply to
992.Sy \&nd
993from the last column.
994Leftward local motion is defined from the left edge only when
995.Sy \&bw
996is given; then an
997.Sy \&le
998from the left edge will move to the right edge of the previous row.
999This is useful for drawing a box around the edge of the screen,
1000for example.
1001If the terminal has switch-selectable automatic margins,
1004description usually assumes that this feature is on,
1005.Em i.e . ,
1006.Sy \&am .
1007If the terminal has a command
1008that moves to the first column of the next line,
1009that command can be given as
1010.Sy \&nw
1012It is permissible for this to clear the remainder of the current line,
1013so if the terminal has no correctly-working
1014.Tn \&CR
1016.Tn \&LF
1017it may still be possible to craft a working
1018.Sy \&nw
1019out of one or both of them.
1021These capabilities suffice to describe hardcopy and
1022.Dq glass-tty
1024Thus the Teletype model 33 is described as
1025.Bd -literal -offset indent
1026T3\||\|tty33\||\|33\||\|tty\||\|Teletype model 33:\e
1027 :bl=^G:co#72:cr=^M:do=^J:hc:os:
1030and the Lear Siegler
1031.Tn ADM Ns \-3
1032is described as
1033.Bd -literal -offset indent
186f72aa 1034l3\||\|adm3\||\|3\||\|LSI ADM-3:\e
1037.Ss Parameterized Strings
1038Cursor addressing and other strings requiring parameters
1039are described by a
1040parameterized string capability, with
1041.Xr printf 3 Ns \-like
1043.Sy \&%x
1044in it,
1045while other characters are passed through unchanged.
1046For example, to address the cursor the
1047.Sy \&cm
1048capability is given, using two parameters: the row and column to move to.
1049(Rows and columns are numbered from zero and refer to the physical screen
1050visible to the user, not to any unseen memory.
1051If the terminal has memory-relative cursor addressing,
1052that can be indicated by an analogous
1053.Sy \&CM
1057.Sy \&%
1058encodings have the following meanings:
1059.Bl -column xxxxx
1060.It "%% output `%'"
1061.It "%d output value as in"
3867d280 1062.Xr printf 3
1064.It "%2 output value as in"
3867d280 1065.Xr printf 3
1067.It "%3 output value as in"
3867d280 1068.Xr printf 3
1070.It "%. output value as in"
3867d280 1071.Xr printf 3
1073.It "%+" Ns Em x Ta No add
1074.Em x
1075to value, then do %.
1076.It "%>" Ns Em \&xy Ta No if
1077value >
1078.Em x
1079then add
1080.Em y ,
1081no output
1082.It "%r reverse order of two parameters, no output"
1083.It "%i increment by one, no output"
1084.It "%n exclusive-or all parameters with 0140 (Datamedia 2500)"
1085.It "\&%B" Ta Tn BCD No "(16*(value/10)) + (value%10), no output"
1086.It "%D Reverse coding (value \- 2*(value%16)), no output (Delta Data)."
1089Consider the Hewlett-Packard 2645, which, to get to row 3 and column 12, needs
1090to be sent
1091.Dq \eE&a12c03Y
1092padded for 6 milliseconds.
1093Note that the order
1094of the row and column coordinates is reversed here
1095and that the row and column
1096are sent as two-digit integers.
1097Thus its
1098.Sy \&cm
1099capability is
1100.Dq Li cm=6\eE&%r%2c%2Y .
1102The Datamedia 2500 needs the current row and column sent
1103encoded in binary using
1104.Dq \&%. .
1105Terminals that use
1106.Dq %.\&
1107need to be able to
1108backspace the cursor
1109.Pq Sy \&le
1110and to move the cursor up one line on the screen
1111.Pq Sy \&up .
1112This is necessary because it is not always safe to transmit
1113.Sy \&\en ,
1114.Sy \&^D ,
1116.Sy \&\er ,
1117as the system may change or discard them.
1118(Programs using
1120must set terminal modes so that tabs are not expanded, so
1121.Sy \&\et
1122is safe to send.
1123This turns out to be essential for the Ann Arbor 4080.)
1125A final example is the Lear Siegler
1126.Tn ADM Ns \-3a ,
1127which offsets row and column
1128by a blank character, thus
1129.Dq Li cm=\eE=%+ %+\ \& .
1131Row or column absolute cursor addressing
1132can be given as single parameter capabilities
1133.Sy \&ch
1134(horizontal position absolute) and
1135.Sy \&cv
1136(vertical position absolute).
1137Sometimes these are shorter than the more general two-parameter sequence
1138(as with the Hewlett-Packard 2645) and can be used in preference to
1139.Sy \&cm .
1140If there are parameterized local motions
1141.Pf ( Em e.g . ,
1143.Ar n
1144positions to the right)
1145these can be given as
1146.Sy \&DO ,
1147.Sy \&LE ,
1148.Sy \&RI ,
1150.Sy \&UP
1151with a single parameter indicating how many positions to move.
1152These are primarily useful if the terminal does not have
1153.Sy \&cm ,
1154such as the Tektronix 4025.
1155.Ss Cursor Motions
1156If the terminal has a fast way to home the cursor
1157(to the very upper left corner of the screen), this can be given as
1158.Sy \&ho .
1159Similarly, a fast way of getting to the lower left-hand corner
1160can be given as
1161.Sy \&ll ;
1162this may involve going up with
1163.Sy \&up
1164from the home position,
1165but a program should never do this itself (unless
1166.Sy \&ll
1167does), because it can
1168make no assumption about the effect of moving up from the home position.
1169Note that the home position is the same as
1170cursor address (0,0): to the top left corner of the screen, not of memory.
1171(Therefore, the
1172.Dq \eEH
1173sequence on Hewlett-Packard terminals
1174cannot be used for
1175.Sy \&ho . )
1176.Ss Area Clears
1177If the terminal can clear from the current position to the end of the
1178line, leaving the cursor where it is, this should be given as
1179.Sy \&ce .
1180If the terminal can clear from the current position to the end of the
1181display, this should be given as
1182.Sy \&cd .
1183.Sy \&cd
1184must only be invoked from the first column of a line.
1186it can be simulated by a request to delete a large number of lines,
1187if a true
1188.Sy \&cd
1189is not available.)
1190.Ss Insert/Delete Line
1191If the terminal can open a new blank line
1192before the line containing the cursor,
1193this should be given as
1194.Sy \&al ;
1195this must be invoked only from the first
1196position of a line.
1197The cursor must then appear at the left of the newly blank line.
1198If the terminal can delete the line that the cursor is on, this
1199should be given as
1200.Sy \&dl ;
1201this must only be used from the first position on
1202the line to be deleted.
1203Versions of
1204.Sy \&al
1206.Sy \&dl
1207which take a single parameter
1208and insert or delete that many lines
1209can be given as
1210.Sy \&AL
1212.Sy \&DL .
1213If the terminal has a settable scrolling region
1214(like the VT100),
1215the command to set this can be described with the
1216.Sy \&cs
1218which takes two parameters: the top and bottom lines of the scrolling region.
1219The cursor position is, alas, undefined after using this command.
1220It is possible to get the effect of insert or delete line
1221using this command \(em the
1222.Sy \&sc
1224.Sy \&rc
1225(save and restore cursor) commands are also useful.
1226Inserting lines at the top or bottom of the screen can also be done using
1227.Sy \&sr
1229.Sy \&sf
1230on many terminals without a true insert/delete line,
1231and is often faster even on terminals with those features.
1233If the terminal has the ability to define a window as part of memory
1234which all commands affect, it should be given as the parameterized string
1235.Sy \&wi .
1236The four parameters are the starting and ending lines in memory
1237and the starting and ending columns in memory, in that order.
1239.Xr terminfo 5
1240capability is described for completeness.
1241It is unlikely that any
1242.Nm Ns \-using
1243program will support it.)
1245If the terminal can retain display memory above the screen, then the
1246.Sy \&da
1247capability should be given;
1248if display memory can be retained
1249below, then
1250.Sy \&db
1251should be given.
1252These indicate
1253that deleting a line or scrolling may bring non-blank lines up from below
1254or that scrolling back with
1255.Sy \&sr
1256may bring down non-blank lines.
1257.Ss Insert/Delete Character
1258There are two basic kinds of intelligent terminals with respect to
1259insert/delete character that can be described using
1260.Nm .
1261The most common insert/delete character operations affect only the characters
1262on the current line and shift characters off the end of the line rigidly.
1263Other terminals, such as the Concept\-100 and the Perkin Elmer Owl, make
1264a distinction between typed and untyped blanks on the screen, shifting
1265upon an insert or delete only to an untyped blank on the screen which is
1266either eliminated or expanded to two untyped blanks.
1267You can determine
1268the kind of terminal you have by clearing the screen then typing
1269text separated by cursor motions.
1271.Dq Li abc\ \ \ \ def
1272using local
1273cursor motions (not spaces) between the
1274.Dq abc
1275and the
1276.Dq def .
1277Then position the cursor before the
1278.Dq abc
1279and put the terminal in insert
1281If typing characters causes the rest of the line to shift
1282rigidly and characters to fall off the end, then your terminal does
1283not distinguish between blanks and untyped positions.
1284If the
1285.Dq abc
1286shifts over to the
1287.Dq def
1288which then move together around the end of the
1289current line and onto the next as you insert, then you have the second type of
1290terminal and should give the capability
1291.Sy \&in ,
1292which stands for
1293.Dq insert null .
1294While these are two logically separate attributes
1295(one line
1296.Em \&vs .
1297multi-line insert mode,
1298and special treatment of untyped spaces),
1299we have seen no terminals whose insert
1300mode cannot be described with the single attribute.
1304entries can describe both terminals that have an insert mode and terminals
1305that send a simple sequence to open a blank position on the current line.
1306Give as
1307.Sy \&im
1308the sequence to get into insert mode.
1309Give as
1310.Sy \&ei
1311the sequence to leave insert mode.
1312Now give as
1313.Sy \&ic
1314any sequence that needs to be sent just before
1315each character to be inserted.
1316Most terminals with a true insert mode
1317will not give
1318.Sy \&ic ;
1319terminals that use a sequence to open a screen
1320position should give it here.
1321(If your terminal has both,
1322insert mode is usually preferable to
1323.Sy \&ic .
1324Do not give both unless the terminal actually requires both to be used
1325in combination.)
1326If post-insert padding is needed, give this as a number of milliseconds
1328.Sy \&ip
1329(a string option).
1330Any other sequence that may need to be
1331sent after insertion of a single character can also be given in
1332.Sy \&ip .
1333If your terminal needs to be placed into an `insert mode'
1334and needs a special code preceding each inserted character,
1335then both
1336.Sy \&im Ns / Sy \&ei
1338.Sy \&ic
1339can be given, and both will be used.
1341.Sy \&IC
1342capability, with one parameter
1343.Em n ,
1344will repeat the effects of
1345.Sy \&ic
1346.Em n
1349It is occasionally necessary to move around while in insert mode
1350to delete characters on the same line
1351.Pf ( Em e.g . ,
1352if there is a tab after
1353the insertion position).
1354If your terminal allows motion while in
1355insert mode, you can give the capability
1356.Sy \&mi
1357to speed up inserting
1358in this case.
1360.Sy \&mi
1361will affect only speed.
1362Some terminals
1363(notably Datamedia's) must not have
1364.Sy \&mi
1365because of the way their
1366insert mode works.
1368Finally, you can specify
1369.Sy \&dc
1370to delete a single character,
1371.Sy \&DC
1372with one parameter
1373.Em n
1374to delete
1375.Em n
1377and delete mode by giving
1378.Sy \&dm
1380.Sy \&ed
1381to enter and exit delete mode
1382(which is any mode the terminal needs to be placed in for
1383.Sy \&dc
1384to work).
186f72aa 1385.Ss Highlighting, Underlining, and Visible Bells
1386If your terminal has one or more kinds of display attributes,
1387these can be represented in a number of different ways.
1388You should choose one display form as
1389.Em standout mode ,
1390representing a good high-contrast, easy-on-the-eyes format
1391for highlighting error messages and other attention getters.
1392(If you have a choice, reverse video plus half-bright is good,
1393or reverse video alone.)
1394The sequences to enter and exit standout mode
1395are given as
1396.Sy \&so
1398.Sy \&se ,
1400If the code to change into or out of standout
1401mode leaves one or even two blank spaces or garbage characters on the screen,
1402as the
1403.Tn TVI
1404912 and Teleray 1061 do,
1406.Sy \&sg
1407should be given to tell how many characters are left.
1409Codes to begin underlining and end underlining can be given as
1410.Sy \&us
1412.Sy \&ue ,
1414Underline mode change garbage is specified by
1415.Sy \&ug ,
1416similar to
1417.Sy \&sg .
1418If the terminal has a code to underline the current character and move
1419the cursor one position to the right,
1420such as the Microterm Mime,
1421this can be given as
1422.Sy \&uc .
1424Other capabilities to enter various highlighting modes include
1425.Sy \&mb
1427.Sy \&md
1428(bold or extra bright),
1429.Sy \&mh
1430(dim or half-bright),
1431.Sy \&mk
1432(blanking or invisible text),
1433.Sy \&mp
1435.Sy \&mr
1436(reverse video),
1437.Sy \&me
1438(turn off
1439.Em all
1440attribute modes),
1441.Sy \&as
1442(enter alternate character set mode), and
1443.Sy \&ae
1444(exit alternate character set mode).
1445Turning on any of these modes singly may or may not turn off other modes.
1447If there is a sequence to set arbitrary combinations of mode,
1448this should be given as
1449.Sy \&sa
1450(set attributes), taking 9 parameters.
1451Each parameter is either 0 or 1,
1452as the corresponding attributes is on or off.
1453The 9 parameters are, in order: standout, underline, reverse, blink,
1454dim, bold, blank, protect, and alternate character set.
1455Not all modes need be supported by
1456.Sy \&sa ,
1457only those for which corresponding attribute commands exist.
1458(It is unlikely that a
1459.Nm Ns \-using
1460program will support this capability, which is defined for compatibility
1462.Xr terminfo 5 . )
1464Terminals with the
1465.Dq magic cookie
1467.Pf ( Sy \&sg
1469.Sy \&ug ) ,
1470rather than maintaining extra attribute bits for each character cell,
1471instead deposit special
1472.Dq cookies ,
1474.Dq garbage characters ,
1475when they receive mode-setting sequences,
1476which affect the display algorithm.
1478Some terminals,
1479such as the Hewlett-Packard 2621,
1480automatically leave standout
1481mode when they move to a new line or when the cursor is addressed.
1482Programs using standout mode
1483should exit standout mode on such terminals
1484before moving the cursor or sending a newline.
1485On terminals where this is not a problem,
1487.Sy \&ms
1488capability should be present
1489to say that this overhead is unnecessary.
1491If the terminal has
1492a way of flashing the screen to indicate an error quietly
1493(a bell replacement),
1494this can be given as
1495.Sy \&vb ;
1496it must not move the cursor.
1498If the cursor needs to be made more visible than normal
1499when it is not on the bottom line
1500(to change, for example, a non-blinking underline into an easier-to-find
1501block or blinking underline),
1502give this sequence as
1503.Sy \&vs .
1504If there is a way to make the cursor completely invisible, give that as
1505.Sy \&vi .
1506The capability
1507.Sy \&ve ,
1508which undoes the effects of both of these modes,
1509should also be given.
1511If your terminal correctly displays underlined characters
1512(with no special codes needed)
1513even though it does not overstrike,
1514then you should give the capability
1515.Sy \&ul .
1516If overstrikes are erasable with a blank,
1517this should be indicated by giving
1518.Sy \&eo .
1519.Ss Keypad
1520If the terminal has a keypad that transmits codes when the keys are pressed,
1521this information can be given.
1522Note that it is not possible to handle
1523terminals where the keypad only works in local mode
1524(this applies, for example, to the unshifted Hewlett-Packard 2621 keys).
1525If the keypad can be set to transmit or not transmit,
1526give these codes as
1527.Sy \&ks
1529.Sy \&ke .
1530Otherwise the keypad is assumed to always transmit.
1531The codes sent by the left-arrow, right-arrow, up-arrow, down-arrow,
1532and home keys can be given as
1533.Sy \&kl ,
1534.Sy \&kr ,
1535.Sy \&ku ,
1536.Sy \&kd ,
1538.Sy \&kh ,
1540If there are function keys such as f0, f1, ..., f9, the codes they send
1541can be given as
1542.Sy \&k0 ,
1543.Sy \&k1 ,
1545.Sy \&k9 .
1546If these keys have labels other than the default f0 through f9, the labels
1547can be given as
1548.Sy \&l0 ,
1549.Sy \&l1 ,
1551.Sy \&l9 .
1552The codes transmitted by certain other special keys can be given:
1553.Sy \&kH
1554(home down),
1555.Sy \&kb
1557.Sy \&ka
1558(clear all tabs),
1559.Sy \&kt
1560(clear the tab stop in this column),
1561.Sy \&kC
1562(clear screen or erase),
1563.Sy \&kD
1564(delete character),
1565.Sy \&kL
1566(delete line),
1567.Sy \&kM
1568(exit insert mode),
1569.Sy \&kE
1570(clear to end of line),
1571.Sy \&kS
1572(clear to end of screen),
1573.Sy \&kI
1574(insert character or enter insert mode),
1575.Sy \&kA
1576(insert line),
1577.Sy \&kN
1578(next page),
1579.Sy \&kP
1580(previous page),
1581.Sy \&kF
1582(scroll forward/down),
1583.Sy \&kR
1584(scroll backward/up), and
1585.Sy \&kT
1586(set a tab stop in this column).
1587In addition, if the keypad has a 3 by 3 array of keys
1588including the four arrow keys, then the other five keys can be given as
1589.Sy \&K1 ,
1590.Sy \&K2 ,
1591.Sy \&K3 ,
1592.Sy \&K4 ,
1594.Sy \&K5 .
1595These keys are useful when the effects of a 3 by 3 directional pad are needed.
1596The obsolete
1597.Sy \&ko
1598capability formerly used to describe
1599.Dq other
1600function keys has been
1601completely supplanted by the above capabilities.
1604.Sy \&ma
1605entry is also used to indicate arrow keys on terminals that have
1606single-character arrow keys.
1607It is obsolete but still in use in
1608version 2 of
1609.Sy \&vi
1610which must be run on some minicomputers due to
1611memory limitations.
1612This field is redundant with
1613.Sy \&kl ,
1614.Sy \&kr ,
1615.Sy \&ku ,
1616.Sy \&kd ,
1618.Sy \&kh .
1619It consists of groups of two characters.
1620In each group, the first character is what an arrow key sends, and the
1621second character is the corresponding
1622.Sy \&vi
1624These commands are
1625.Ar h
1627.Sy \&kl ,
1628.Ar j
1630.Sy \&kd ,
1631.Ar k
1633.Sy \&ku ,
1634.Ar l
1636.Sy \&kr ,
1638.Ar H
1640.Sy \&kh .
1641For example, the Mime would have
1642.Dq Li ma=^Hh^Kj^Zk^Xl
1643indicating arrow keys left (^H), down (^K), up (^Z), and right (^X).
1644(There is no home key on the Mime.)
1645.Ss Tabs and Initialization
1646If the terminal needs to be in a special mode when running
1647a program that uses these capabilities,
1648the codes to enter and exit this mode can be given as
1649.Sy \&ti
1651.Sy \&te .
1652This arises, for example, from terminals like the Concept with more than
1653one page of memory.
1654If the terminal has only memory-relative cursor addressing and not
1655screen-relative cursor addressing,
1656a screen-sized window must be fixed into
1657the display for cursor addressing to work properly.
1658This is also used for the Tektronix 4025, where
1659.Sy \&ti
1660sets the command character to be the one used by
1661.Nm .
1663Other capabilities
1665.Sy \&is ,
1666an initialization string for the terminal,
1668.Sy \&if ,
1669the name of a file containing long initialization strings.
1670These strings are expected to set the terminal into modes
1671consistent with the rest of the
1674They are normally sent to the terminal by the
3867d280 1675.Xr tset 1
1676program each time the user logs in.
1677They will be printed in the following order:
1678.Sy \&is ;
1679setting tabs using
1680.Sy \&ct
1682.Sy \&st ;
1683and finally
1684.Sy \&if .
68a1e415 1685.Pf ( Xr Terminfo 5
1687.Sy \&i\&1-i2
1688instead of
1689.Sy \&is
1690and runs the program
1691.Sy \&iP
1692and prints
1693.Sy "\&i\&3"
1694after the other initializations.)
1695A pair of sequences that does a harder reset from a totally unknown state
1696can be analogously given as
1697.Sy \&rs
1699.Sy \&if .
1700These strings are output by the
3867d280 1701.Xr reset 1
984263bc 1702program, which is used when the terminal gets into a wedged state.
68a1e415 1703.Pf ( Xr Terminfo 5
1705.Sy "\&r1-r3"
1706instead of
1707.Sy \&rs . )
1708Commands are normally placed in
1709.Sy \&rs
1711.Sy \&rf
1712only if they produce annoying effects on the screen and are not necessary
1713when logging in.
1714For example, the command to set the VT100 into 80-column mode
1715would normally be part of
1716.Sy \&is ,
1717but it causes an annoying glitch of the screen and is not normally needed
1718since the terminal is usually already in 80-column mode.
1720If the terminal has hardware tabs,
1721the command to advance to the next tab stop can be given as
1722.Sy \&ta
1724.Sy \&^I ) .
1726.Dq backtab
1727command which moves leftward to the previous tab stop
1728can be given as
1729.Sy \&bt .
1730By convention,
1731if the terminal driver modes indicate that tab stops are being expanded
1732by the computer rather than being sent to the terminal,
1733programs should not use
1734.Sy \&ta
1736.Sy \&bt
1737even if they are present,
1738since the user may not have the tab stops properly set.
1739If the terminal has hardware tabs that are initially set every
1740.Ar n
1741positions when the terminal is powered up, then the numeric parameter
1742.Sy \&it
1743is given, showing the number of positions between tab stops.
1744This is normally used by the
3867d280 1745.Xr tset 1
1746command to determine whether to set the driver mode for hardware tab
1747expansion, and whether to set the tab stops.
1748If the terminal has tab stops that can be saved in nonvolatile memory, the
1750description can assume that they are properly set.
1752If there are commands to set and clear tab stops, they can be given as
1753.Sy \&ct
1754(clear all tab stops) and
1755.Sy \&st
1756(set a tab stop in the current column of every row).
1757If a more complex sequence is needed to set the tabs than can be
1758described by this, the sequence can be placed in
1759.Sy \&is
1761.Sy \&if .
1762.Ss Delays
1763Certain capabilities control padding in the terminal driver.
1764These are primarily needed by hardcopy terminals and are used by the
3867d280 1765.Xr tset 1
1766program to set terminal driver modes appropriately.
1767Delays embedded in the capabilities
1768.Sy \&cr ,
1769.Sy \&sf ,
1770.Sy \&le ,
1771.Sy \&ff ,
1773.Sy \&ta
1774will cause the appropriate delay bits to be set in the terminal driver.
1776.Sy \&pb
1777(padding baud rate) is given, these values can be ignored at baud rates
1778below the value of
1779.Sy \&pb .
1781.Bx 4.2
3867d280 1782.Xr tset 1 ,
1783the delays are given as numeric capabilities
1784.Sy \&dC ,
1785.Sy \&dN ,
1786.Sy \&dB ,
1787.Sy \&dF ,
1789.Sy \&dT
1791.Ss Miscellaneous
1792If the terminal requires other than a
1793.Dv NUL
1794(zero) character as a pad,
1795this can be given as
1796.Sy \&pc .
1797Only the first character of the
1798.Sy \&pc
1799string is used.
1801If the terminal has commands to save and restore the position of the
1802cursor, give them as
1803.Sy \&sc
1805.Sy \&rc .
1807If the terminal has an extra
1808.Dq status line
1809that is not normally used by
1810software, this fact can be indicated.
1811If the status line is viewed as an extra line below the bottom line,
1812then the capability
1813.Sy \&hs
1814should be given.
1815Special strings to go to a position in the status line and to return
1816from the status line can be given as
1817.Sy \&ts
1819.Sy \&fs .
7f49811b 1820.Pf ( Sy \&fs
1821must leave the cursor position in the same place that it was before
1822.Sy \&ts .
1823If necessary, the
1824.Sy \&sc
1826.Sy \&rc
1827strings can be included in
1828.Sy \&ts
1830.Sy \&fs
1831to get this effect.)
1832The capability
1833.Sy \&ts
1834takes one parameter, which is the column number of the status line
1835to which the cursor is to be moved.
1836If escape sequences and other special commands such as tab work while in
1837the status line, the flag
1838.Sy \&es
1839can be given.
1840A string that turns off the status line (or otherwise erases its contents)
1841should be given as
1842.Sy \&ds .
1843The status line is normally assumed to be the same width as the
1844rest of the screen,
1845.Em i.e . ,
1846.Sy \&co .
1847If the status line is a different width (possibly because the terminal
1848does not allow an entire line to be loaded), then its width in columns
1849can be indicated with the numeric parameter
1850.Sy \&ws .
1852If the terminal can move up or down half a line, this can be
1853indicated with
1854.Sy \&hu
1855(half-line up) and
1856.Sy \&hd
1857(half-line down).
1858This is primarily useful for superscripts and subscripts on hardcopy
1860If a hardcopy terminal can eject to the next page (form feed),
1861give this as
1862.Sy \&ff
1864.Sy \&^L ) .
1866If there is a command to repeat a given character a given number of times
1867(to save time transmitting a large number of identical characters),
1868this can be indicated with the parameterized string
1869.Sy \&rp .
1870The first parameter is the character to be repeated and the second is
1871the number of times to repeat it.
1872(This is a
1873.Xr terminfo 5
1874feature that is unlikely to be supported by a program that uses
1875.Nm . )
1877If the terminal has a settable command character, such as the
1878Tektronix 4025, this can be indicated with
1879.Sy \&CC .
1880A prototype command character is chosen which is used in all capabilities.
1881This character is given in the
1882.Sy \&CC
1883capability to identify it.
1884The following convention is supported on some
1887The environment is to be searched for a
1888.Ev \&CC
1890and if found,
1891all occurrences of the prototype character are replaced by the character
1892in the environment variable.
1893This use of the
1894.Ev \&CC
1895environment variable
1896is a very bad idea, as it conflicts with
1897.Xr make 1 .
1899Terminal descriptions that do not represent a specific kind of known
1900terminal, such as
1901.Em switch ,
1902.Em dialup ,
1903.Em patch ,
3867d280 1905.Em network ,
1906should include the
1907.Sy \&gn
1908(generic) capability so that programs can complain that they do not know
1909how to talk to the terminal.
1910(This capability does not apply to
1911.Em virtual
1912terminal descriptions for which the escape sequences are known.)
1914If the terminal uses xoff/xon
1915.Pq Tn DC3 Ns / Ns Tn DC1
1916handshaking for flow control, give
1917.Sy \&xo .
1918Padding information should still be included so that routines can make
1919better decisions about costs, but actual pad characters will not be
1922If the terminal has a
1923.Dq meta key
1924which acts as a shift key, setting the
19258th bit of any character transmitted, then this fact can be indicated with
1926.Sy \&km .
1927Otherwise, software will assume that the 8th bit is parity and it will
1928usually be cleared.
1929If strings exist to turn this
1930.Dq meta mode
1931on and off, they can be given as
1932.Sy \&mm
1934.Sy \&mo .
1936If the terminal has more lines of memory than will fit on the screen at once,
1937the number of lines of memory can be indicated with
1938.Sy \&lm .
1939An explicit value of 0 indicates that the number of lines is not fixed,
1940but that there is still more memory than fits on the screen.
1942If the terminal is one of those supported by the
1944system virtual
1945terminal protocol, the terminal number can be given as
1946.Sy \&vt .
1948Media copy strings which control an auxiliary printer
1949connected to the terminal can be given as
1950.Sy \&ps :
1951print the contents of the screen;
1952.Sy \&pf :
1953turn off the printer; and
1954.Sy \&po :
1955turn on the printer.
1956When the printer is on, all text sent to the terminal will be sent to the
1958It is undefined whether the text is also displayed on the terminal screen
1959when the printer is on.
1960A variation
1961.Sy \&pO
1962takes one parameter and leaves the printer on for as many characters as the
1963value of the parameter, then turns the printer off.
1964The parameter should not exceed 255.
1965All text, including
1966.Sy \&pf ,
1967is transparently passed to the printer while
1968.Sy \&pO
1969is in effect.
1971Strings to program function keys can be given as
1972.Sy \&pk ,
1973.Sy \&pl ,
1975.Sy \&px .
1976Each of these strings takes two parameters: the function key number
1977to program (from 0 to 9) and the string to program it with.
1978Function key numbers out of this range may program undefined keys
1979in a terminal-dependent manner.
1980The differences among the capabilities are that
1981.Sy \&pk
1982causes pressing the given key to be the same as the user typing the given
1984.Sy \&pl
1985causes the string to be executed by the terminal in local mode;
1987.Sy \&px
1988causes the string to be transmitted to the computer.
1989Unfortunately, due to lack of a definition for string parameters in
1990.Nm ,
1992.Xr terminfo 5
1993supports these capabilities.
1995For the
1996.Xr xterm 1
1997terminal emulator the traditional behavior in
1999when exiting a pager such as
2000.Xr less 1
2002.Xr more 1 ,
2003or an editor such as
2004.Xr vi 1
2006.Em NOT
2007to clear the screen after the program exits.
2008If you prefer to clear the screen there are a number of
2009.Dq xterm-clear
2010entries that add this capability in the
2012file that you can use directly, or as examples.
2013.Ss Glitches and Braindamage
2014Hazeltine terminals, which do not allow `~' characters to be displayed,
2015should indicate
2016.Sy \&hz .
2019.Sy \&nc
2020capability, now obsolete, formerly indicated Datamedia terminals,
2021which echo
2022.Sy \&\er \en
2024carriage return then ignore a following linefeed.
2026Terminals that ignore a linefeed immediately after an
2027.Sy \&am
2028wrap, such as the Concept, should indicate
2029.Sy \&xn .
2032.Sy \&ce
2033is required to get rid of standout
2034(instead of merely writing normal text on top of it),
2035.Sy \&xs
2036should be given.
2038Teleray terminals, where tabs turn all characters moved over to blanks,
2039should indicate
2040.Sy \&xt
2041(destructive tabs).
2042This glitch is also taken to mean that it is not possible
2043to position the cursor on top of a
2044.Dq magic cookie ,
2045and that
2046to erase standout mode it is necessary to use delete and insert line.
2048The Beehive Superbee, which is unable to correctly transmit the
2049.Dv ESC
2051.Sy \&^C
2052characters, has
2053.Sy \&xb ,
2054indicating that the
2055.Dq \&f\&1
2056key is used for
2057.Dv ESC
2059.Dq \&f\&2
2060for ^C.
2061(Only certain Superbees have this problem, depending on the
2062.Tn ROM . )
2064Other specific terminal problems may be corrected by adding more
2065capabilities of the form
7f49811b 2066.Sy x Ns Em x .
2067.Ss Similar Terminals
2068If there are two very similar terminals,
2069one can be defined as being just like the other with certain exceptions.
2070The string capability
2071.Sy \&tc
2072can be given
2073with the name of the similar terminal.
2074This capability must be
2075.Em last ,
2076and the combined length of the entries
2077must not exceed 1024.
2078The capabilities given before
2079.Sy \&tc
2080override those in the terminal type invoked by
2081.Sy \&tc .
2082A capability can be canceled by placing
2083.Sy \&xx@
2084to the left of the
2085.Sy \&tc
2086invocation, where
2087.Sy \&xx
2088is the capability.
2089For example, the entry
2090.Bd -literal -offset indent
2094defines a
2095.Dq 2621\-nl
2096that does not have the
2097.Sy \&ks
2099.Sy \&ke
2101hence does not turn on the function key labels when in visual mode.
2102This is useful for different modes for a terminal, or for different
2103user preferences.
2104.Sh FILES
2105.Bl -tag -width /usr/share/misc/termcap.db -compact
2106.It Pa /usr/share/misc/termcap
2107File containing terminal descriptions.
2108.It Pa /usr/share/misc/termcap.db
2109Hash database file containing terminal descriptions (see
2110.Xr cap_mkdb 1 ) .
2112.Sh SEE ALSO
2113.Xr cap_mkdb 1 ,
2114.Xr ex 1 ,
2115.Xr more 1 ,
2116.Xr tset 1 ,
2117.Xr ul 1 ,
2118.Xr vi 1 ,
186f72aa 2119.Xr xterm 1 ,
2120.Xr ncurses 3 ,
2121.Xr printf 3 ,
2122.Xr termcap 3 ,
2123.Xr term 5
2126.Em Note :
2129were replaced by
2130.Xr terminfo 5
2132.At V
2133Release 2.0.
2134The transition will be relatively painless if capabilities flagged as
2135.Dq obsolete
2136are avoided.
2138Lines and columns are now stored by the kernel as well as in the termcap
2140Most programs now use the kernel information primarily; the information
2141in this file is used only if the kernel does not have any information.
2144.Xr \&vi 1
2145program allows only 256 characters for string capabilities, and the routines
2147.Xr termlib 3
2148do not check for overflow of this buffer.
2149The total length of a single entry (excluding only escaped newlines)
2150may not exceed 1024.
2152Not all programs support all entries.
2156file format appeared in
2157.Bx 3 .