summaryrefslogtreecommitdiff
path: root/lib/termcap/grot/termcap.texi
blob: eab49e88a4e2af44f1f643853a43b37fe000d3bc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
\input texinfo  @c -*-texinfo-*-
@setfilename termcap.info
@settitle The Termcap Library
@smallbook

@ifinfo
This file documents the termcap library of the GNU system.

Copyright (C) 1988 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifinfo

@setchapternewpage odd

@c @shorttitlepage The Termcap Manual

@titlepage
@ignore
@sp 6
@center @titlefont{Termcap}
@sp 1
@center The Termcap Library and Data Base
@sp 4
@center Second Edition
@sp 1
@center December 1992
@sp 5
@center Richard M. Stallman
@sp 1
@center Free Software Foundation
@end ignore

@c Real title page
@title The Termcap Manual
@subtitle The Termcap Library and Data Base
@subtitle Second Edition
@subtitle December 1992
@author Richard M. Stallman
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1988 Free Software Foundation, Inc.

Published by the Free Software Foundation
(59 Temple Place, Suite 330, Boston, MA 02111 USA).
Printed copies are available for $10 each.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@sp 2
Cover art by Etienne Suvasa.
@end titlepage
@page

@synindex vr fn

@node Top, Introduction, (dir), (dir)

@menu
* Introduction::  What is termcap?  Why this manual?
* Library::     The termcap library functions.
* Data Base::   What terminal descriptions in @file{/etc/termcap} look like.
* Capabilities::  Definitions of the individual terminal capabilities:
                 how to write them in descriptions, and how to use
                 their values to do display updating.
* Summary::     Brief table of capability names and their meanings.
* Var Index::   Index of C functions and variables.
* Cap Index::   Index of termcap capabilities.
* Index::       Concept index.

 --- The Detailed Node Listing ---

The Termcap Library

* Preparation::  Preparing to use the termcap library.
* Find::        Finding the description of the terminal being used.
* Interrogate::  Interrogating the description for particular capabilities.
* Initialize::  Initialization for output using termcap.
* Padding::     Outputting padding.
* Parameters::  Encoding parameters such as cursor positions.

Padding

* Why Pad::     Explanation of padding.
* Not Enough::  When there is not enough padding.
* Describe Padding::  The data base says how much padding a terminal needs.
* Output Padding::    Using @code{tputs} to output the needed padding.

Filling In Parameters

* Encode Parameters::  The language for encoding parameters.
* Using Parameters::   Outputting a string command with parameters.

Sending Display Commands with Parameters

* tparam::      The general case, for GNU termcap only.
* tgoto::       The special case of cursor motion.

The Format of the Data Base

* Format::      Overall format of a terminal description.
* Capability Format::  Format of capabilities within a description.
* Naming::      Naming conventions for terminal types.
* Inheriting::  Inheriting part of a description from
a related terminal type.
* Changing::    When changes in the data base take effect.

Definitions of the Terminal Capabilities

* Basic::       Basic characteristics.
* Screen Size::  Screen size, and what happens when it changes.
* Cursor Motion::  Various ways to move the cursor.
* Wrapping::    What happens if you write a character in the last column.
* Scrolling::   Pushing text up and down on the screen.
* Windows::     Limiting the part of the window that output affects.
* Clearing::    Erasing one or many lines.
* Insdel Line::  Making new blank lines in mid-screen; deleting lines.
* Insdel Char::  Inserting and deleting characters within a line.
* Standout::    Highlighting some of the text.
* Underlining::  Underlining some of the text.
* Cursor Visibility::  Making the cursor more or less easy to spot.
* Bell::        Attracts user's attention; not localized on the screen.
* Keypad::      Recognizing when function keys or arrows are typed.
* Meta Key::    @key{META} acts like an extra shift key.
* Initialization::  Commands used to initialize or reset the terminal.
* Pad Specs::   Info for the kernel on how much padding is needed.
* Status Line::  A status line displays ``background'' information.
* Half-Line::   Moving by half-lines, for superscripts and subscripts.
* Printer::     Controlling auxiliary printers of display terminals.
@end menu

@node Introduction, Library, Top, Top
@unnumbered Introduction

@cindex termcap
@dfn{Termcap} is a library and data base that enables programs to use
display terminals in a terminal-independent manner.  It originated in
Berkeley Unix.

The termcap data base describes the capabilities of hundreds of different
display terminals in great detail.  Some examples of the information
recorded for a terminal could include how many columns wide it is, what
string to send to move the cursor to an arbitrary position (including how
to encode the row and column numbers), how to scroll the screen up one or
several lines, and how much padding is needed for such a scrolling
operation.

The termcap library is provided for easy access this data base in programs
that want to do terminal-independent character-based display output.

This manual describes the GNU version of the termcap library, which has
some extensions over the Unix version.  All the extensions are identified
as such, so this manual also tells you how to use the Unix termcap.

The GNU version of the termcap library is available free as source code,
for use in free programs, and runs on Unix and VMS systems (at least).  You
can find it in the GNU Emacs distribution in the files @file{termcap.c} and
@file{tparam.c}.

This manual was written for the GNU project, whose goal is to develop a
complete free operating system upward-compatible with Unix for user
programs.  The project is approximately two thirds complete.  For more
information on the GNU project, including the GNU Emacs editor and the
mostly-portable optimizing C compiler, send one dollar to

@display
Free Software Foundation
675 Mass Ave
Cambridge, MA 02139
@end display

@node Library, Data Base, Introduction, Top
@chapter The Termcap Library

The termcap library is the application programmer's interface to the
termcap data base.  It contains functions for the following purposes:

@itemize @bullet
@item
Finding the description of the user's terminal type (@code{tgetent}).

@item
Interrogating the description for information on various topics
(@code{tgetnum}, @code{tgetflag}, @code{tgetstr}).

@item
Computing and performing padding (@code{tputs}).

@item
Encoding numeric parameters such as cursor positions into the
terminal-specific form required for display commands (@code{tparam},
@code{tgoto}).
@end itemize

@menu
* Preparation::  Preparing to use the termcap library.
* Find::        Finding the description of the terminal being used.
* Interrogate::  Interrogating the description for particular capabilities.
* Initialize::  Initialization for output using termcap.
* Padding::     Outputting padding.
* Parameters::  Encoding parameters such as cursor positions.
@end menu

@node Preparation, Find,  , Library
@section Preparing to Use the Termcap Library

To use the termcap library in a program, you need two kinds of preparation:

@itemize @bullet
@item
The compiler needs declarations of the functions and variables in the
library.

On GNU systems, it suffices to include the header file
@file{termcap.h} in each source file that uses these functions and
variables.@refill

On Unix systems, there is often no such header file.  Then you must
explictly declare the variables as external.  You can do likewise for
the functions, or let them be implicitly declared and cast their
values from type @code{int} to the appropriate type.

We illustrate the declarations of the individual termcap library
functions with ANSI C prototypes because they show how to pass the
arguments.  If you are not using the GNU C compiler, you probably
cannot use function prototypes, so omit the argument types and names
from your declarations.

@item
The linker needs to search the library.  Usually either
@samp{-ltermcap} or @samp{-ltermlib} as an argument when linking will
do this.@refill
@end itemize

@node Find, Interrogate, Preparation, Library
@section Finding a Terminal Description: @code{tgetent}

@findex tgetent
An application program that is going to use termcap must first look up the
description of the terminal type in use.  This is done by calling
@code{tgetent}, whose declaration in ANSI Standard C looks like:

@example
int tgetent (char *@var{buffer}, char *@var{termtype});
@end example

@noindent
This function finds the description and remembers it internally so that
you can interrogate it about specific terminal capabilities
(@pxref{Interrogate}).

The argument @var{termtype} is a string which is the name for the type of
terminal to look up.  Usually you would obtain this from the environment
variable @code{TERM} using @code{getenv ("TERM")}.

If you are using the GNU version of termcap, you can alternatively ask
@code{tgetent} to allocate enough space.  Pass a null pointer for
@var{buffer}, and @code{tgetent} itself allocates the storage using
@code{malloc}.  There is no way to get the address that was allocated,
and you shouldn't try to free the storage.@refill

With the Unix version of termcap, you must allocate space for the
description yourself and pass the address of the space as the argument
@var{buffer}.  There is no way you can tell how much space is needed, so
the convention is to allocate a buffer 2048 characters long and assume that
is enough.  (Formerly the convention was to allocate 1024 characters and
assume that was enough.  But one day, for one kind of terminal, that was
not enough.)

No matter how the space to store the description has been obtained,
termcap records its address internally for use when you later interrogate
the description with @code{tgetnum}, @code{tgetstr} or @code{tgetflag}.  If
the buffer was allocated by termcap, it will be freed by termcap too if you
call @code{tgetent} again.  If the buffer was provided by you, you must
make sure that its contents remain unchanged for as long as you still plan
to interrogate the description.@refill

The return value of @code{tgetent} is @minus{}1 if there is some difficulty
accessing the data base of terminal types, 0 if the data base is accessible
but the specified type is not defined in it, and some other value
otherwise.

Here is how you might use the function @code{tgetent}:

@smallexample
#ifdef unix
static char term_buffer[2048];
#else
#define term_buffer 0
#endif

init_terminal_data ()
@{
  char *termtype = getenv ("TERM");
  int success;

  if (termtype == 0)
    fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");

  success = tgetent (term_buffer, termtype);
  if (success < 0)
    fatal ("Could not access the termcap data base.\n");
  if (success == 0)
    fatal ("Terminal type `%s' is not defined.\n", termtype);
@}
@end smallexample

@noindent
Here we assume the function @code{fatal} prints an error message and exits.

If the environment variable @code{TERMCAP} is defined, its value is used to
override the terminal type data base.  The function @code{tgetent} checks
the value of @code{TERMCAP} automatically.  If the value starts with
@samp{/} then it is taken as a file name to use as the data base file,
instead of @file{/etc/termcap} which is the standard data base.  If the
value does not start with @samp{/} then it is itself used as the terminal
description, provided that the terminal type @var{termtype} is among the
types it claims to apply to.  @xref{Data Base}, for information on the
format of a terminal description.@refill

@node Interrogate, Initialize, Find, Library
@section Interrogating the Terminal Description

Each piece of information recorded in a terminal description is called a
@dfn{capability}.  Each defined terminal capability has a two-letter code
name and a specific meaning.  For example, the number of columns is named
@samp{co}.  @xref{Capabilities}, for definitions of all the standard
capability names.

Once you have found the proper terminal description with @code{tgetent}
(@pxref{Find}), your application program must @dfn{interrogate} it for
various terminal capabilities.  You must specify the two-letter code of
the capability whose value you seek.

Capability values can be numeric, boolean (capability is either present or
absent) or strings.  Any particular capability always has the same value
type; for example, @samp{co} always has a numeric value, while @samp{am}
(automatic wrap at margin) is always a flag, and @samp{cm} (cursor motion
command) always has a string value.  The documentation of each capability
says which type of value it has.@refill

There are three functions to use to get the value of a capability,
depending on the type of value the capability has.  Here are their
declarations in ANSI C:

@findex tgetnum
@findex tgetflag
@findex tgetstr
@example
int tgetnum (char *@var{name});
int tgetflag (char *@var{name});
char *tgetstr (char *@var{name}, char **@var{area});
@end example

@table @code
@item tgetnum
Use @code{tgetnum} to get a capability value that is numeric.  The
argument @var{name} is the two-letter code name of the capability.  If
the capability is present, @code{tgetnum} returns the numeric value
(which is nonnegative).  If the capability is not mentioned in the
terminal description, @code{tgetnum} returns @minus{}1.

@item tgetflag
Use @code{tgetflag} to get a boolean value.  If the capability
@var{name} is present in the terminal description, @code{tgetflag}
returns 1; otherwise, it returns 0.

@item tgetstr
Use @code{tgetstr} to get a string value.  It returns a pointer to a
string which is the capability value, or a null pointer if the
capability is not present in the terminal description.

There are two ways @code{tgetstr} can find space to store the string value:

@itemize @bullet
@item
You can ask @code{tgetstr} to allocate the space.  Pass a null
pointer for the argument @var{area}, and @code{tgetstr} will use
@code{malloc} to allocate storage big enough for the value.
Termcap will never free this storage or refer to it again; you
should free it when you are finished with it.

This method is more robust, since there is no need to guess how
much space is needed.  But it is supported only by the GNU
termcap library.

@item
You can provide the space.  Provide for the argument @var{area} the
address of a pointer variable of type @code{char *}.  Before calling
@code{tgetstr}, initialize the variable to point at available space.
Then @code{tgetstr} will store the string value in that space and will
increment the pointer variable to point after the space that has been
used.  You can use the same pointer variable for many calls to
@code{tgetstr}.

There is no way to determine how much space is needed for a single
string, and no way for you to prevent or handle overflow of the area
you have provided.  However, you can be sure that the total size of
all the string values you will obtain from the terminal description is
no greater than the size of the description (unless you get the same
capability twice).  You can determine that size with @code{strlen} on
the buffer you provided to @code{tgetent}.  See below for an example.

Providing the space yourself is the only method supported by the Unix
version of termcap.
@end itemize
@end table

Note that you do not have to specify a terminal type or terminal
description for the interrogation functions.  They automatically use the
description found by the most recent call to @code{tgetent}.

Here is an example of interrogating a terminal description for various
capabilities, with conditionals to select between the Unix and GNU methods
of providing buffer space.

@example
char *tgetstr ();

char *cl_string, *cm_string;
int height;
int width;
int auto_wrap;

char PC;   /* For tputs.  */
char *BC;  /* For tgoto.  */
char *UP;

interrogate_terminal ()
@{
#ifdef UNIX
  /* Here we assume that an explicit term_buffer
     was provided to tgetent.  */
  char *buffer
    = (char *) malloc (strlen (term_buffer));
#define BUFFADDR &buffer
#else
#define BUFFADDR 0
#endif

  char *temp;

  /* Extract information we will use.  */
  cl_string = tgetstr ("cl", BUFFADDR);
  cm_string = tgetstr ("cm", BUFFADDR);
  auto_wrap = tgetflag ("am");
  height = tgetnum ("li");
  width = tgetnum ("co");

  /* Extract information that termcap functions use.  */
  temp = tgetstr ("pc", BUFFADDR);
  PC = temp ? *temp : 0;
  BC = tgetstr ("le", BUFFADDR);
  UP = tgetstr ("up", BUFFADDR);
@}
@end example

@noindent
@xref{Padding}, for information on the variable @code{PC}.  @xref{Using
Parameters}, for information on @code{UP} and @code{BC}.

@node Initialize, Padding, Interrogate, Library
@section Initialization for Use of Termcap
@cindex terminal flags (kernel)

Before starting to output commands to a terminal using termcap,
an application program should do two things:

@itemize @bullet
@item
Initialize various global variables which termcap library output
functions refer to.  These include @code{PC} and @code{ospeed} for
padding (@pxref{Output Padding}) and @code{UP} and @code{BC} for
cursor motion (@pxref{tgoto}).@refill

@item
Tell the kernel to turn off alteration and padding of horizontal-tab
characters sent to the terminal.
@end itemize

To turn off output processing in Berkeley Unix you would use @code{ioctl}
with code @code{TIOCLSET} to set the bit named @code{LLITOUT}, and clear
the bits @code{ANYDELAY} using @code{TIOCSETN}.  In POSIX or System V, you
must clear the bit named @code{OPOST}.  Refer to the system documentation
for details.@refill

If you do not set the terminal flags properly, some older terminals will
not work.  This is because their commands may contain the characters that
normally signify newline, carriage return and horizontal tab---characters
which the kernel thinks it ought to modify before output.

When you change the kernel's terminal flags, you must arrange to restore
them to their normal state when your program exits.  This implies that the
program must catch fatal signals such as @code{SIGQUIT} and @code{SIGINT}
and restore the old terminal flags before actually terminating.

Modern terminals' commands do not use these special characters, so if you
do not care about problems with old terminals, you can leave the kernel's
terminal flags unaltered.

@node Padding, Parameters, Initialize, Library
@section Padding
@cindex padding

@dfn{Padding} means outputting null characters following a terminal display
command that takes a long time to execute.  The terminal description says
which commands require padding and how much; the function @code{tputs},
described below, outputs a terminal command while extracting from it the
padding information, and then outputs the padding that is necessary.

@menu
* Why Pad::     Explanation of padding.
* Not Enough::  When there is not enough padding.
* Describe Padding::  The data base says how much padding a terminal needs.
* Output Padding::  Using @code{tputs} to output the needed padding.
@end menu

@node Why Pad, Not Enough,  , Padding
@subsection Why Pad, and How

Most types of terminal have commands that take longer to execute than they
do to send over a high-speed line.  For example, clearing the screen may
take 20msec once the entire command is received.  During that time, on a
9600 bps line, the terminal could receive about 20 additional output
characters while still busy clearing the screen.  Every terminal has a
certain amount of buffering capacity to remember output characters that
cannot be processed yet, but too many slow commands in a row can cause the
buffer to fill up.  Then any additional output that cannot be processed
immediately will be lost.

To avoid this problem, we normally follow each display command with enough
useless charaters (usually null characters) to fill up the time that the
display command needs to execute.  This does the job if the terminal throws
away null characters without using up space in the buffer (which most
terminals do).  If enough padding is used, no output can ever be lost.  The
right amount of padding avoids loss of output without slowing down
operation, since the time used to transmit padding is time that nothing
else could be done.

The number of padding characters needed for an operation depends on the
line speed.  In fact, it is proportional to the line speed.  A 9600 baud
line transmits about one character per msec, so the clear screen command in
the example above would need about 20 characters of padding.  At 1200 baud,
however, only about 3 characters of padding are needed to fill up 20msec.

@node Not Enough, Describe Padding, Why Pad, Padding
@subsection When There Is Not Enough Padding

There are several common manifestations of insufficient padding.

@itemize @bullet
@item
Emacs displays @samp{I-search: ^Q-} at the bottom of the screen.

This means that the terminal thought its buffer was getting full of
display commands, so it tried to tell the computer to stop sending
any.

@item
The screen is garbled intermittently, or the details of garbling vary
when you repeat the action.  (A garbled screen could be due to a
command which is simply incorrect, or to user option in the terminal
which doesn't match the assumptions of the terminal description, but
this usually leads to reproducible failure.)

This means that the buffer did get full, and some commands were lost.
Many changeable factors can change which ones are lost.

@item
Screen is garbled at high output speeds but not at low speeds.
Padding problems nearly always go away at low speeds, usually even at
1200 baud.

This means that a high enough speed permits commands to arrive faster
than they can be executed.
@end itemize

Although any obscure command on an obscure terminal might lack padding,
in practice problems arise most often from the clearing commands
@samp{cl} and @samp{cd} (@pxref{Clearing}), the scrolling commands
@samp{sf} and @samp{sr} (@pxref{Scrolling}), and the line insert/delete
commands @samp{al} and @samp{dl} (@pxref{Insdel Line}).

Occasionally the terminal description fails to define @samp{sf} and some
programs will use @samp{do} instead, so you may get a problem with
@samp{do}.  If so, first define @samp{sf} just like @samp{do}, then
add some padding to @samp{sf}.

The best strategy is to add a lot of padding at first, perhaps 200 msec.
This is much more than enough; in fact, it should cause a visible slowdown.
(If you don't see a slowdown, the change has not taken effect;
@pxref{Changing}.)  If this makes the problem go away, you have found the
right place to add padding; now reduce the amount until the problem comes
back, then increase it again.  If the problem remains, either it is in some
other capability or it is not a matter of padding at all.

Keep in mind that on many terminals the correct padding for insert/delete
line or for scrolling is cursor-position dependent.  If you get problems
from scrolling a large region of the screen but not from scrolling a small
part (just a few lines moving), it may mean that fixed padding should be
replaced with position-dependent padding.

@node Describe Padding, Output Padding, Not Enough, Padding
@subsection Specifying Padding in a Terminal Description

In the terminal description, the amount of padding required by each display
command is recorded as a sequence of digits at the front of the command.
These digits specify the padding time in milliseconds (msec).  They can be
followed optionally by a decimal point and one more digit, which is a
number of tenths of msec.

Sometimes the padding needed by a command depends on the cursor position.
For example, the time taken by an ``insert line'' command is usually
proportional to the number of lines that need to be moved down or cleared.
An asterisk (@samp{*}) following the padding time says that the time
should be multiplied by the number of screen lines affected by the command.

@example
:al=1.3*\E[L:
@end example

@noindent
is used to describe the ``insert line'' command for a certain terminal.
The padding required is 1.3 msec per line affected.  The command itself is
@samp{@key{ESC} [ L}.

The padding time specified in this way tells @code{tputs} how many pad
characters to output.  @xref{Output Padding}.

Two special capability values affect padding for all commands.  These are
the @samp{pc} and @samp{pb}.  The variable @samp{pc} specifies the
character to pad with, and @samp{pb} the speed below which no padding is
needed.  The defaults for these variables, a null character and 0,
are correct for most terminals.  @xref{Pad Specs}.

@node Output Padding,  , Describe Padding, Padding
@subsection Performing Padding with @code{tputs}
@cindex line speed

@findex tputs
Use the termcap function @code{tputs} to output a string containing an
optional padding spec of the form described above (@pxref{Describe
Padding}).  The function @code{tputs} strips off and decodes the padding
spec, outputs the rest of the string, and then outputs the appropriate
padding.  Here is its declaration in ANSI C:

@example
char PC;
short ospeed;

int tputs (char *@var{string}, int @var{nlines}, int (*@var{outfun}) ());
@end example

Here @var{string} is the string (including padding spec) to be output;
@var{nlines} is the number of lines affected by the operation, which is
used to multiply the amount of padding if the padding spec ends with a
@samp{*}.  Finally, @var{outfun} is a function (such as @code{fputchar})
that is called to output each character.  When actually called,
@var{outfun} should expect one argument, a character.

@vindex ospeed
@vindex PC
The operation of @code{tputs} is controlled by two global variables,
@code{ospeed} and @code{PC}.  The value of @code{ospeed} is supposed to be
the terminal output speed, encoded as in the @code{ioctl} system call which
gets the speed information.  This is needed to compute the number of
padding characters.  The value of @code{PC} is the character used for
padding.

You are responsible for storing suitable values into these variables before
using @code{tputs}.  The value stored into the @code{PC} variable should be
taken from the @samp{pc} capability in the terminal description (@pxref{Pad
Specs}).  Store zero in @code{PC} if there is no @samp{pc}
capability.@refill

The argument @var{nlines} requires some thought.  Normally, it should be
the number of lines whose contents will be cleared or moved by the command.
For cursor motion commands, or commands that do editing within one line,
use the value 1.  For most commands that affect multiple lines, such as
@samp{al} (insert a line) and @samp{cd} (clear from the cursor to the end
of the screen), @var{nlines} should be the screen height minus the current
vertical position (origin 0).  For multiple insert and scroll commands such
as @samp{AL} (insert multiple lines), that same value for @var{nlines} is
correct; the number of lines being inserted is @i{not} correct.@refill

If a ``scroll window'' feature is used to reduce the number of lines
affected by a command, the value of @var{nlines} should take this into
account.  This is because the delay time required depends on how much work
the terminal has to do, and the scroll window feature reduces the work.
@xref{Scrolling}.

Commands such as @samp{ic} and @samp{dc} (insert or delete characters) are
problematical because the padding needed by these commands is proportional
to the number of characters affected, which is the number of columns from
the cursor to the end of the line.  It would be nice to have a way to
specify such a dependence, and there is no need for dependence on vertical
position in these commands, so it is an obvious idea to say that for these
commands @var{nlines} should really be the number of columns affected.
However, the definition of termcap clearly says that @var{nlines} is always
the number of lines affected, even in this case, where it is always 1.  It
is not easy to change this rule now, because too many programs and terminal
descriptions have been written to follow it.

Because @var{nlines} is always 1 for the @samp{ic} and @samp{dc} strings,
there is no reason for them to use @samp{*}, but some of them do.  These
should be corrected by deleting the @samp{*}.  If, some day, such entries
have disappeared, it may be possible to change to a more useful convention
for the @var{nlines} argument for these operations without breaking any
programs.

@node Parameters,  , Padding, Library
@section Filling In Parameters
@cindex parameters

Some terminal control strings require numeric @dfn{parameters}.  For
example, when you move the cursor, you need to say what horizontal and
vertical positions to move it to.  The value of the terminal's @samp{cm}
capability, which says how to move the cursor, cannot simply be a string of
characters; it must say how to express the cursor position numbers and
where to put them within the command.

The specifications of termcap include conventions as to which string-valued
capabilities require parameters, how many parameters, and what the
parameters mean; for example, it defines the @samp{cm} string to take
two parameters, the vertical and horizontal positions, with 0,0 being the
upper left corner.  These conventions are described where the individual
commands are documented.

Termcap also defines a language used within the capability definition for
specifying how and where to encode the parameters for output.  This language
uses character sequences starting with @samp{%}.  (This is the same idea as
@code{printf}, but the details are different.)  The language for parameter
encoding is described in this section.

A program that is doing display output calls the functions @code{tparam} or
@code{tgoto} to encode parameters according to the specifications.  These
functions produce a string containing the actual commands to be output (as
well a padding spec which must be processed with @code{tputs};
@pxref{Padding}).

@menu
* Encode Parameters::  The language for encoding parameters.
* Using Parameters::  Outputting a string command with parameters.
@end menu

@node Encode Parameters, Using Parameters,  , Parameters
@subsection Describing the Encoding
@cindex %

A terminal command string that requires parameters contains special
character sequences starting with @samp{%} to say how to encode the
parameters.  These sequences control the actions of @code{tparam} and
@code{tgoto}.

The parameters values passed to @code{tparam} or @code{tgoto} are
considered to form a vector.  A pointer into this vector determines
the next parameter to be processed.  Some of the @samp{%}-sequences
encode one parameter and advance the pointer to the next parameter.
Other @samp{%}-sequences alter the pointer or alter the parameter
values without generating output.

For example, the @samp{cm} string for a standard ANSI terminal is written
as @samp{\E[%i%d;%dH}.  (@samp{\E} stands for @key{ESC}.)  @samp{cm} by
convention always requires two parameters, the vertical and horizontal goal
positions, so this string specifies the encoding of two parameters.  Here
@samp{%i} increments the two values supplied, and each @samp{%d} encodes
one of the values in decimal.  If the cursor position values 20,58 are
encoded with this string, the result is @samp{\E[21;59H}.

First, here are the @samp{%}-sequences that generate output.  Except for
@samp{%%}, each of them encodes one parameter and advances the pointer
to the following parameter.

@table @samp
@item %%
Output a single @samp{%}.  This is the only way to represent a literal
@samp{%} in a terminal command with parameters.  @samp{%%} does not
use up a parameter.

@item %d
As in @code{printf}, output the next parameter in decimal.

@item %2
Like @samp{%02d} in @code{printf}: output the next parameter in
decimal, and always use at least two digits.

@item %3
Like @samp{%03d} in @code{printf}: output the next parameter in
decimal, and always use at least three digits.  Note that @samp{%4}
and so on are @emph{not} defined.

@item %.
Output the next parameter as a single character whose ASCII code is
the parameter value.  Like @samp{%c} in @code{printf}.

@item %+@var{char}
Add the next parameter to the character @var{char}, and output the
resulting character.  For example, @samp{%+ } represents 0 as a space,
1 as @samp{!}, etc.
@end table

The following @samp{%}-sequences specify alteration of the parameters
(their values, or their order) rather than encoding a parameter for output.
They generate no output; they are used only for their side effects
on the parameters.  Also, they do not advance the ``next parameter'' pointer
except as explicitly stated.  Only @samp{%i}, @samp{%r} and @samp{%>} are
defined in standard Unix termcap.  The others are GNU extensions.@refill

@table @samp
@item %i
Increment the next two parameters.  This is used for terminals that
expect cursor positions in origin 1.  For example, @samp{%i%d,%d} would
output two parameters with @samp{1} for 0, @samp{2} for 1, etc.

@item %r
Interchange the next two parameters.  This is used for terminals whose
cursor positioning command expects the horizontal position first.

@item %s
Skip the next parameter.  Do not output anything.

@item %b
Back up one parameter.  The last parameter used will become once again
the next parameter to be output, and the next output command will use
it.  Using @samp{%b} more than once, you can back up any number of
parameters, and you can refer to each parameter any number of times.

@item %>@var{c1}@var{c2}
Conditionally increment the next parameter.  Here @var{c1} and
@var{c2} are characters which stand for their ASCII codes as numbers.
If the next parameter is greater than the ASCII code of @var{c1}, the
ASCII code of @var{c2} is added to it.@refill

@item %a @var{op} @var{type} @var{pos}
Perform arithmetic on the next parameter, do not use it up, and do not
output anything.  Here @var{op} specifies the arithmetic operation,
while @var{type} and @var{pos} together specify the other operand.

Spaces are used above to separate the operands for clarity; the spaces
don't appear in the data base, where this sequence is exactly five
characters long.

The character @var{op} says what kind of arithmetic operation to
perform.  It can be any of these characters:

@table @samp
@item =
assign a value to the next parameter, ignoring its old value.
The new value comes from the other operand.

@item +
add the other operand to the next parameter.

@item -
subtract the other operand from the next parameter.

@item *
multiply the next parameter by the other operand.

@item /
divide the next parameter by the other operand.
@end table

The ``other operand'' may be another parameter's value or a constant;
the character @var{type} says which.  It can be:

@table @samp
@item p
Use another parameter.  The character @var{pos} says which
parameter to use.  Subtract 64 from its ASCII code to get the
position of the desired parameter relative to this one.  Thus,
the character @samp{A} as @var{pos} means the parameter after the
next one; the character @samp{?} means the parameter before the
next one.

@item c
Use a constant value.  The character @var{pos} specifies the
value of the constant.  The 0200 bit is cleared out, so that 0200
can be used to represent zero.
@end table
@end table

The following @samp{%}-sequences are special purpose hacks to compensate
for the weird designs of obscure terminals.  They modify the next parameter
or the next two parameters but do not generate output and do not use up any
parameters.  @samp{%m} is a GNU extension; the others are defined in
standard Unix termcap.

@table @samp
@item %n
Exclusive-or the next parameter with 0140, and likewise the parameter
after next.

@item %m
Complement all the bits of the next parameter and the parameter after next.

@item %B
Encode the next parameter in BCD.  It alters the value of the
parameter by adding six times the quotient of the parameter by ten.
Here is a C statement that shows how the new value is computed:

@example
@var{parm} = (@var{parm} / 10) * 16 + @var{parm} % 10;
@end example

@item %D
Transform the next parameter as needed by Delta Data terminals.
This involves subtracting twice the remainder of the parameter by 16.

@example
@var{parm} -= 2 * (@var{parm} % 16);
@end example
@end table

@node Using Parameters,  , Encode Parameters, Parameters
@subsection Sending Display Commands with Parameters

The termcap library functions @code{tparam} and @code{tgoto} serve as the
analog of @code{printf} for terminal string parameters.  The newer function
@code{tparam} is a GNU extension, more general but missing from Unix
termcap.  The original parameter-encoding function is @code{tgoto}, which
is preferable for cursor motion.

@menu
* tparam::      The general case, for GNU termcap only.
* tgoto::       The special case of cursor motion.
@end menu

@node tparam, tgoto,  , Using Parameters
@subsubsection @code{tparam}

@findex tparam
The function @code{tparam} can encode display commands with any number of
parameters and allows you to specify the buffer space.  It is the preferred
function for encoding parameters for all but the @samp{cm} capability.  Its
ANSI C declaration is as follows:

@smallexample
char *tparam (char *@var{ctlstring}, char *@var{buffer}, int @var{size}, int @var{parm1},...)
@end smallexample

The arguments are a control string @var{ctlstring} (the value of a terminal
capability, presumably), an output buffer @var{buffer} and @var{size}, and
any number of integer parameters to be encoded.  The effect of
@code{tparam} is to copy the control string into the buffer, encoding
parameters according to the @samp{%} sequences in the control string.

You describe the output buffer by its address, @var{buffer}, and its size
in bytes, @var{size}.  If the buffer is not big enough for the data to be
stored in it, @code{tparam} calls @code{malloc} to get a larger buffer.  In
either case, @code{tparam} returns the address of the buffer it ultimately
uses.  If the value equals @var{buffer}, your original buffer was used.
Otherwise, a new buffer was allocated, and you must free it after you are
done with printing the results.  If you pass zero for @var{size} and
@var{buffer}, @code{tparam} always allocates the space with @code{malloc}.

All capabilities that require parameters also have the ability to specify
padding, so you should use @code{tputs} to output the string produced by
@code{tparam}.  @xref{Padding}.  Here is an example.

@example
@{
char *buf;
char buffer[40];

buf = tparam (command, buffer, 40, parm);
tputs (buf, 1, fputchar);
if (buf != buffer)
free (buf);
@}
@end example

If a parameter whose value is zero is encoded with @samp{%.}-style
encoding, the result is a null character, which will confuse @code{tputs}.
This would be a serious problem, but luckily @samp{%.} encoding is used
only by a few old models of terminal, and only for the @samp{cm}
capability.  To solve the problem, use @code{tgoto} rather than
@code{tparam} to encode the @samp{cm} capability.@refill

@node tgoto,  , tparam, Using Parameters
@subsubsection @code{tgoto}

@findex tgoto
The special case of cursor motion is handled by @code{tgoto}.  There
are two reasons why you might choose to use @code{tgoto}:

@itemize @bullet
@item
For Unix compatibility, because Unix termcap does not have @code{tparam}.

@item
For the @samp{cm} capability, since @code{tgoto} has a special feature
to avoid problems with null characters, tabs and newlines on certain old
terminal types that use @samp{%.} encoding for that capability.
@end itemize

Here is how @code{tgoto} might be declared in ANSI C:

@example
char *tgoto (char *@var{cstring}, int @var{hpos}, int @var{vpos})
@end example

There are three arguments, the terminal description's @samp{cm} string and
the two cursor position numbers; @code{tgoto} computes the parametrized
string in an internal static buffer and returns the address of that buffer.
The next time you use @code{tgoto} the same buffer will be reused.

@vindex UP
@vindex BC
Parameters encoded with @samp{%.} encoding can generate null characters,
tabs or newlines.  These might cause trouble: the null character because
@code{tputs} would think that was the end of the string, the tab because
the kernel or other software might expand it into spaces, and the newline
becaue the kernel might add a carriage-return, or padding characters
normally used for a newline.  To prevent such problems, @code{tgoto} is
careful to avoid these characters.  Here is how this works: if the target
cursor position value is such as to cause a problem (that is to say, zero,
nine or ten), @code{tgoto} increments it by one, then compensates by
appending a string to move the cursor back or up one position.

The compensation strings to use for moving back or up are found in global
variables named @code{BC} and @code{UP}.  These are actual external C
variables with upper case names; they are declared @code{char *}.  It is up
to you to store suitable values in them, normally obtained from the
@samp{le} and @samp{up} terminal capabilities in the terminal description
with @code{tgetstr}.  Alternatively, if these two variables are both zero,
the feature of avoiding nulls, tabs and newlines is turned off.

It is safe to use @code{tgoto} for commands other than @samp{cm} only if
you have stored zero in @code{BC} and @code{UP}.

Note that @code{tgoto} reverses the order of its operands: the horizontal
position comes before the vertical position in the arguments to
@code{tgoto}, even though the vertical position comes before the horizontal
in the parameters of the @samp{cm} string.  If you use @code{tgoto} with a
command such as @samp{AL} that takes one parameter, you must pass the
parameter to @code{tgoto} as the ``vertical position''.@refill

@node Data Base, Capabilities, Library, Top
@chapter The Format of the Data Base

The termcap data base of terminal descriptions is stored in the file
@file{/etc/termcap}.  It contains terminal descriptions, blank lines, and
comments.

A terminal description starts with one or more names for the terminal type.
The information in the description is a series of @dfn{capability names}
and values.  The capability names have standard meanings
(@pxref{Capabilities}) and their values describe the terminal.

@menu
* Format::      Overall format of a terminal description.
* Capability Format::  Format of capabilities within a description.
* Naming::      Naming conventions for terminal types.
* Inheriting::  Inheriting part of a description from
a related terminal type.
* Changing::    When changes in the data base take effect.
@end menu

@node Format, Capability Format,  , Data Base
@section Terminal Description Format
@cindex description format

Aside from comments (lines starting with @samp{#}, which are ignored), each
nonblank line in the termcap data base is a terminal description.
A terminal description is nominally a single line, but it can be split
into multiple lines by inserting the two characters @samp{\ newline}.
This sequence is ignored wherever it appears in a description.

The preferred way to split the description is between capabilities: insert
the four characters @samp{: \ newline tab} immediately before any colon.
This allows each sub-line to start with some indentation.  This works
because, after the @samp{\ newline} are ignored, the result is @samp{: tab
:}; the first colon ends the preceding capability and the second colon
starts the next capability.  If you split with @samp{\ newline} alone, you
may not add any indentation after them.

Here is a real example of a terminal description:

@example
dw|vt52|DEC vt52:\
        :cr=^M:do=^J:nl=^J:bl=^G:\
        :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\
        :cm=\EY%+ %+ :co#80:li#24:\
        :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
        :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
@end example

Each terminal description begins with several names for the terminal type.
The names are separated by @samp{|} characters, and a colon ends the last
name.  The first name should be two characters long; it exists only for the
sake of very old Unix systems and is never used in modern systems.  The
last name should be a fully verbose name such as ``DEC vt52'' or ``Ann
Arbor Ambassador with 48 lines''.  The other names should include whatever
the user ought to be able to specify to get this terminal type, such as
@samp{vt52} or @samp{aaa-48}.  @xref{Naming}, for information on how to
choose terminal type names.

After the terminal type names come the terminal capabilities, separated by
colons and with a colon after the last one.  Each capability has a
two-letter name, such as @samp{cm} for ``cursor motion string'' or @samp{li}
for ``number of display lines''.

@node Capability Format, Naming, Format, Data Base
@section Writing the Capabilities

There are three kinds of capabilities: flags, numbers, and strings.  Each
kind has its own way of being written in the description.  Each defined
capability has by convention a particular kind of value; for example,
@samp{li} always has a numeric value and @samp{cm} always a string value.

A flag capability is thought of as having a boolean value: the value is
true if the capability is present, false if not.  When the capability is
present, just write its name between two colons.

A numeric capability has a value which is a nonnegative number.  Write the
capability name, a @samp{#}, and the number, between two colons.  For
example, @samp{@dots{}:li#48:@dots{}} is how you specify the @samp{li}
capability for 48 lines.@refill

A string-valued capability has a value which is a sequence of characters.
Usually these are the characters used to perform some display operation.
Write the capability name, a @samp{=}, and the characters of the value,
between two colons.  For example, @samp{@dots{}:cm=\E[%i%d;%dH:@dots{}} is
how the cursor motion command for a standard ANSI terminal would be
specified.@refill

Special characters in the string value can be expressed using
@samp{\}-escape sequences as in C; in addition, @samp{\E} stands for
@key{ESC}.  @samp{^} is also a kind of escape character; @samp{^} followed
by @var{char} stands for the control-equivalent of @var{char}.  Thus,
@samp{^a} stands for the character control-a, just like @samp{\001}.
@samp{\} and @samp{^} themselves can be represented as @samp{\\} and
@samp{\^}.@refill

To include a colon in the string, you must write @samp{\072}.  You might
ask, ``Why can't @samp{\:} be used to represent a colon?''  The reason is
that the interrogation functions do not count slashes while looking for a
capability.  Even if @samp{:ce=ab\:cd:} were interpreted as giving the
@samp{ce} capability the value @samp{ab:cd}, it would also appear to define
@samp{cd} as a flag.

The string value will often contain digits at the front to specify padding
(@pxref{Padding}) and/or @samp{%}-sequences within to specify how to encode
parameters (@pxref{Parameters}).  Although these things are not to be
output literally to the terminal, they are considered part of the value of
the capability.  They are special only when the string value is processed
by @code{tputs}, @code{tparam} or @code{tgoto}.  By contrast, @samp{\} and
@samp{^} are considered part of the syntax for specifying the characters
in the string.

Let's look at the VT52 example again:

@example
dw|vt52|DEC vt52:\
        :cr=^M:do=^J:nl=^J:bl=^G:\
        :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:\
        :cm=\EY%+ %+ :co#80:li#24:\     
        :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
        :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
@end example

Here we see the numeric-valued capabilities @samp{co} and @samp{li}, the
flags @samp{bs} and @samp{pt}, and many string-valued capabilities.  Most
of the strings start with @key{ESC} represented as @samp{\E}.  The rest
contain control characters represented using @samp{^}.  The meanings of the
individual capabilities are defined elsewhere (@pxref{Capabilities}).

@node Naming, Inheriting, Capability Format, Data Base
@section Terminal Type Name Conventions
@cindex names of terminal types

There are conventions for choosing names of terminal types.  For one thing,
all letters should be in lower case.  The terminal type for a terminal in
its most usual or most fundamental mode of operation should not have a
hyphen in it.

If the same terminal has other modes of operation which require
different terminal descriptions, these variant descriptions are given
names made by adding suffixes with hyphens.  Such alternate descriptions
are used for two reasons:

@itemize @bullet
@item
When the terminal has a switch that changes its behavior.  Since the
computer cannot tell how the switch is set, the user must tell the
computer by choosing the appropriate terminal type name.

@cindex wrapping
For example, the VT-100 has a setup flag that controls whether the
cursor wraps at the right margin.  If this flag is set to ``wrap'',
you must use the terminal type @samp{vt100-am}.  Otherwise you must
use @samp{vt100-nam}.  Plain @samp{vt100} is defined as a synonym for
either @samp{vt100-am} or @samp{vt100-nam} depending on the
preferences of the local site.@refill

The standard suffix @samp{-am} stands for ``automatic margins''.

@item
To give the user a choice in how to use the terminal.  This is done
when the terminal has a switch that the computer normally controls.

@cindex screen size
For example, the Ann Arbor Ambassador can be configured with many
screen sizes ranging from 20 to 60 lines.  Fewer lines make bigger
characters but more lines let you see more of what you are editing.
As a result, users have different preferences.  Therefore, termcap
provides terminal types for many screen sizes.  If you choose type
@samp{aaa-30}, the terminal will be configured to use 30 lines; if you
choose @samp{aaa-48}, 48 lines will be used, and so on.
@end itemize

Here is a list of standard suffixes and their conventional meanings:

@table @samp
@item -w
Short for ``wide''.  This is a mode that gives the terminal more
columns than usual.  This is normally a user option.

@item -am
``Automatic margins''.  This is an alternate description for use when
the terminal's margin-wrap switch is on; it contains the @samp{am}
flag.  The implication is that normally the switch is off and the
usual description for the terminal says that the switch is off.

@item -nam
``No automatic margins''.  The opposite of @samp{-am}, this names an
alternative description which lacks the @samp{am} flag.  This implies
that the terminal is normally operated with the margin-wrap switch
turned on, and the normal description of the terminal says so.

@item -na
``No arrows''.  This terminal description initializes the terminal to
keep its arrow keys in local mode.  This is a user option.

@item -rv
``Reverse video''.  This terminal description causes text output for
normal video to appear as reverse, and text output for reverse video
to come out as normal.  Often this description differs from the usual
one by interchanging the two strings which turn reverse video on and
off.@refill

This is a user option; you can choose either the ``reverse video''
variant terminal type or the normal terminal type, and termcap will
obey.

@item -s
``Status''.  Says to enable use of a status line which ordinary output
does not touch (@pxref{Status Line}).

Some terminals have a special line that is used only as a status line.
For these terminals, there is no need for an @samp{-s} variant; the
status line commands should be defined by default.  On other
terminals, enabling a status line means removing one screen line from
ordinary use and reducing the effective screen height.  For these
terminals, the user can choose the @samp{-s} variant type to request
use of a status line.

@item -@var{nlines}
Says to operate with @var{nlines} lines on the screen, for terminals
such as the Ambassador which provide this as an option.  Normally this
is a user option; by choosing the terminal type, you control how many
lines termcap will use.

@item -@var{npages}p
Says that the terminal has @var{npages} pages worth of screen memory,
for terminals where this is a hardware option.

@item -unk
Says that description is not for direct use, but only for reference in
@samp{tc} capabilities.  Such a description is a kind of subroutine,
because it describes the common characteristics of several variant
descriptions that would use other suffixes in place of @samp{-unk}.
@end table

@node Inheriting, Changing, Naming, Data Base
@section Inheriting from Related Descriptions

@cindex inheritance
When two terminal descriptions are similar, their identical parts do not
need to be given twice.  Instead, one of the two can be defined in terms of
the other, using the @samp{tc} capability.  We say that one description
@dfn{refers to} the other, or @dfn{inherits from} the other.

The @samp{tc} capability must be the last one in the terminal description,
and its value is a string which is the name of another terminal type which
is referred to.  For example,

@example
N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
        :ti=\E[2J\E[30;0;0;30p:\
        :te=\E[60;0;0;30p\E[30;1H\E[J:\
        :li#30:tc=aaa-unk:
@end example

@noindent
defines the terminal type @samp{aaa-30} (also known as plain @samp{aaa}) in
terms of @samp{aaa-unk}, which defines everything about the Ambassador that
is independent of screen height.  The types @samp{aaa-36}, @samp{aaa-48}
and so on for other screen heights are likewise defined to inherit from
@samp{aaa-unk}.

The capabilities overridden by @samp{aaa-30} include @samp{li}, which says
how many lines there are, and @samp{ti} and @samp{te}, which configure the
terminal to use that many lines.

The effective terminal description for type @samp{aaa} consists of the text
shown above followed by the text of the description of @samp{aaa-unk}.  The
@samp{tc} capability is handled automatically by @code{tgetent}, which
finds the description thus referenced and combines the two descriptions
(@pxref{Find}).  Therefore, only the implementor of the terminal
descriptions needs to think about using @samp{tc}.  Users and application
programmers do not need to be concerned with it.

Since the reference terminal description is used last, capabilities
specified in the referring description override any specifications of the
same capabilities in the reference description.

The referring description can cancel out a capability without specifying
any new value for it by means of a special trick.  Write the capability in
the referring description, with the character @samp{@@} after the capability
name, as follows:

@smallexample
NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
        :am@@:tc=aaa-30:
@end smallexample

@node Changing,  , Inheriting, Data Base
@section When Changes in the Data Base Take Effect

Each application program must read the terminal description from the
data base, so a change in the data base is effective for all jobs started
after the change is made.

The change will usually have no effect on a job that have been in existence
since before the change. The program probably read the terminal description
once, when it was started, and is continuing to use what it read then.
If the program does not have a feature for reexamining the data base, then
you will need to run it again (probably killing the old job).

If the description in use is coming from the @code{TERMCAP} environment
variable, then the data base file is effectively overridden, and changes in
it will have no effect until you change the @code{TERMCAP} variable as
well.  For example, some users' @file{.login} files automatically copy the
terminal description into @code{TERMCAP} to speed startup of applications.
If you have done this, you will need to change the @code{TERMCAP} variable
to make the changed data base take effect.

@node Capabilities, Summary, Data Base, Top
@chapter Definitions of the Terminal Capabilities

This section is divided into many subsections, each for one aspect of
use of display terminals.  For writing a display program, you usually need
only check the subsections for the operations you want to use.  For writing
a terminal description, you must read each subsection and fill in the
capabilities described there.

String capabilities that are display commands may require numeric
parameters (@pxref{Parameters}).  Most such capabilities do not use
parameters.  When a capability requires parameters, this is explicitly
stated at the beginning of its definition.  In simple cases, the first or
second sentence of the definition mentions all the parameters, in the order
they should be given, using a name
@iftex
in italics
@end iftex
@ifinfo
in upper case
@end ifinfo
for each one.  For example, the @samp{rp} capability is a command that
requires two parameters; its definition begins as follows:

@quotation
String of commands to output a graphic character @var{c}, repeated @var{n}
times.
@end quotation

In complex cases or when there are many parameters, they are described
explicitly.

When a capability is described as obsolete, this means that programs should
not be written to look for it, but terminal descriptions should still be
written to provide it.

When a capability is described as very obsolete, this means that it should
be omitted from terminal descriptions as well.

@menu
* Basic::       Basic characteristics.
* Screen Size::  Screen size, and what happens when it changes.
* Cursor Motion::  Various ways to move the cursor.
* Wrapping::    What happens if you write a character in the last column.
* Scrolling::   Pushing text up and down on the screen.
* Windows::     Limiting the part of the window that output affects.
* Clearing::    Erasing one or many lines.
* Insdel Line::  Making new blank lines in mid-screen; deleting lines.
* Insdel Char::  Inserting and deleting characters within a line.
* Standout::    Highlighting some of the text.
* Underlining::  Underlining some of the text.
* Cursor Visibility::  Making the cursor more or less easy to spot.
* Bell::        Attracts user's attention; not localized on the screen.
* Keypad::      Recognizing when function keys or arrows are typed.
* Meta Key::    @key{META} acts like an extra shift key.
* Initialization::  Commands used to initialize or reset the terminal.
* Pad Specs::   Info for the kernel on how much padding is needed.
* Status Line::  A status line displays ``background'' information.
* Half-Line::   Moving by half-lines, for superscripts and subscripts.
* Printer::     Controlling auxiliary printers of display terminals.
@end menu

@node Basic, Screen Size,  , Capabilities
@section Basic Characteristics

This section documents the capabilities that describe the basic and
nature of the terminal, and also those that are relevant to the output
of graphic characters.

@table @samp
@item os
@kindex os
@cindex overstrike
Flag whose presence means that the terminal can overstrike.  This
means that outputting a graphic character does not erase whatever was
present in the same character position before.  The terminals that can
overstrike include printing terminals, storage tubes (all obsolete
nowadays), and many bit-map displays.

@item eo
@kindex eo
Flag whose presence means that outputting a space erases a character
position even if the terminal supports overstriking.  If this flag is
not present and overstriking is supported, output of a space has no
effect except to move the cursor.

(On terminals that do not support overstriking, you can always assume
that outputting a space at a position erases whatever character was
previously displayed there.)

@item gn
@kindex gn
@cindex generic terminal type
Flag whose presence means that this terminal type is a generic type
which does not really describe any particular terminal.  Generic types
are intended for use as the default type assigned when the user
connects to the system, with the intention that the user should
specify what type he really has.  One example of a generic type
is the type @samp{network}.

Since the generic type cannot say how to do anything interesting with
the terminal, termcap-using programs will always find that the
terminal is too weak to be supported if the user has failed to specify
a real terminal type in place of the generic one.  The @samp{gn} flag
directs these programs to use a different error message: ``You have
not specified your real terminal type'', rather than ``Your terminal
is not powerful enough to be used''.

@item hc
@kindex hc
Flag whose presence means this is a hardcopy terminal.

@item rp
@kindex rp
@cindex repeat output
String of commands to output a graphic character @var{c}, repeated @var{n}
times.  The first parameter value is the ASCII code for the desired
character, and the second parameter is the number of times to repeat the
character.  Often this command requires padding proportional to the 
number of times the character is repeated.  This effect can be had by
using parameter arithmetic with @samp{%}-sequences to compute the
amount of padding, then generating the result as a number at the front
of the string so that @code{tputs} will treat it as padding.

@item hz
@kindex hz
Flag whose presence means that the ASCII character @samp{~} cannot be
output on this terminal because it is used for display commands.

Programs handle this flag by checking all text to be output and
replacing each @samp{~} with some other character(s).  If this is not
done, the screen will be thoroughly garbled.

The old Hazeltine terminals that required such treatment are probably
very rare today, so you might as well not bother to support this flag.

@item CC
@kindex CC
@cindex command character
String whose presence means the terminal has a settable command
character.  The value of the string is the default command character
(which is usually @key{ESC}).

All the strings of commands in the terminal description should be
written to use the default command character.  If you are writing an
application program that changes the command character, use the
@samp{CC} capability to figure out how to translate all the display
commands to work with the new command character.

Most programs have no reason to look at the @samp{CC} capability.

@item xb
@kindex xb
@cindex Superbee
Flag whose presence identifies Superbee terminals which are unable to
transmit the characters @key{ESC} and @kbd{Control-C}.  Programs which
support this flag are supposed to check the input for the code sequences
sent by the @key{F1} and @key{F2} keys, and pretend that @key{ESC}
or @kbd{Control-C} (respectively) had been read.  But this flag is
obsolete, and not worth supporting.
@end table

@node Screen Size, Cursor Motion, Basic, Capabilities
@section Screen Size
@cindex screen size

A terminal description has two capabilities, @samp{co} and @samp{li},
that describe the screen size in columns and lines.  But there is more
to the question of screen size than this.

On some operating systems the ``screen'' is really a window and the
effective width can vary.  On some of these systems, @code{tgetnum}
uses the actual width of the window to decide what value to return for
the @samp{co} capability, overriding what is actually written in the
terminal description.  On other systems, it is up to the application
program to check the actual window width using a system call.  For
example, on BSD 4.3 systems, the system call @code{ioctl} with code
@code{TIOCGWINSZ} will tell you the current screen size.

On all window systems, termcap is powerless to advise the application
program if the user resizes the window.  Application programs must
deal with this possibility in a system-dependent fashion.  On some
systems the C shell handles part of the problem by detecting changes
in window size and setting the @code{TERMCAP} environment variable
appropriately.  This takes care of application programs that are
started subsequently.  It does not help application programs already
running.

On some systems, including BSD 4.3, all programs using a terminal get
a signal named @code{SIGWINCH} whenever the screen size changes.
Programs that use termcap should handle this signal by using
@code{ioctl TIOCGWINSZ} to learn the new screen size.

@table @samp
@item co
@kindex co
@cindex screen size
Numeric value, the width of the screen in character positions.  Even
hardcopy terminals normally have a @samp{co} capability.

@item li
@kindex li
Numeric value, the height of the screen in lines.
@end table

@node Cursor Motion, Wrapping, Screen Size, Capabilities
@section Cursor Motion
@cindex cursor motion

Termcap assumes that the terminal has a @dfn{cursor}, a spot on the screen
where a visible mark is displayed, and that most display commands take
effect at the position of the cursor.  It follows that moving the cursor
to a specified location is very important.

There are many terminal capabilities for different cursor motion
operations.  A terminal description should define as many as possible, but
most programs do not need to use most of them.  One capability, @samp{cm},
moves the cursor to an arbitrary place on the screen; this by itself is
sufficient for any application as long as there is no need to support
hardcopy terminals or certain old, weak displays that have only relative
motion commands.  Use of other cursor motion capabilities is an
optimization, enabling the program to output fewer characters in some
common cases.

If you plan to use the relative cursor motion commands in an application
program, you must know what the starting cursor position is.  To do this,
you must keep track of the cursor position and update the records each
time anything is output to the terminal, including graphic characters.
In addition, it is necessary to know whether the terminal wraps after
writing in the rightmost column.  @xref{Wrapping}.

One other motion capability needs special mention: @samp{nw} moves the
cursor to the beginning of the following line, perhaps clearing all the
starting line after the cursor, or perhaps not clearing at all.  This
capability is a least common denominator that is probably supported even by
terminals that cannot do most other things such as @samp{cm} or @samp{do}.
Even hardcopy terminals can support @samp{nw}.

@table @asis
@item @samp{cm}
@kindex cm
String of commands to position the cursor at line @var{l}, column @var{c}.
Both parameters are origin-zero, and are defined relative to the
screen, not relative to display memory.

All display terminals except a few very obsolete ones support @samp{cm},
so it is acceptable for an application program to refuse to operate on
terminals lacking @samp{cm}.

@item @samp{ho}
@kindex ho
@cindex home position
String of commands to move the cursor to the upper left corner of the
screen (this position is called the @dfn{home position}).  In
terminals where the upper left corner of the screen is not the same as
the beginning of display memory, this command must go to the upper
left corner of the screen, not the beginning of display memory.

Every display terminal supports this capability, and many application
programs refuse to operate if the @samp{ho} capability is missing.

@item @samp{ll}
@kindex ll
String of commands to move the cursor to the lower left corner of the
screen.  On some terminals, moving up from home position does this,
but programs should never assume that will work.  Just output the
@samp{ll} string (if it is provided); if moving to home position and
then moving up is the best way to get there, the @samp{ll} command
will do that.

@item @samp{cr}
@kindex cr
String of commands to move the cursor to the beginning of the line it
is on.  If this capability is not specified, many programs assume
they can use the ASCII carriage return character for this.

@item @samp{le}
@kindex le
String of commands to move the cursor left one column.  Unless the
@samp{bw} flag capability is specified, the effect is undefined if the
cursor is at the left margin; do not use this command there.  If
@samp{bw} is present, this command may be used at the left margin, and
it wraps the cursor to the last column of the preceding line.

@item @samp{nd}
@kindex nd
String of commands to move the cursor right one column.  The effect is
undefined if the cursor is at the right margin; do not use this
command there, not even if @samp{am} is present.

@item @samp{up}
@kindex up
String of commands to move the cursor vertically up one line.  The
effect of sending this string when on the top line is undefined;
programs should never use it that way.

@item @samp{do}
@kindex do
String of commands to move the cursor vertically down one line.  The
effect of sending this string when on the bottom line is undefined;
programs should never use it that way.

Some programs do use @samp{do} to scroll up one line if used at the
bottom line, if @samp{sf} is not defined but @samp{sr} is.  This is
only to compensate for certain old, incorrect terminal descriptions.
(In principle this might actually lead to incorrect behavior on other
terminals, but that seems to happen rarely if ever.)  But the proper
solution is that the terminal description should define @samp{sf} as
well as @samp{do} if the command is suitable for scrolling.

The original idea was that this string would not contain a newline
character and therefore could be used without disabling the kernel's
usual habit of converting of newline into a carriage-return newline
sequence.  But many terminal descriptions do use newline in the
@samp{do} string, so this is not possible; a program which sends the
@samp{do} string must disable output conversion in the kernel
(@pxref{Initialize}).

@item @samp{bw}
@kindex bw
Flag whose presence says that @samp{le} may be used in column zero
to move to the last column of the preceding line.  If this flag
is not present, @samp{le} should not be used in column zero.

@item @samp{nw}
@kindex nw
String of commands to move the cursor to start of next line, possibly
clearing rest of line (following the cursor) before moving.

@item @samp{DO}, @samp{UP}, @samp{LE}, @samp{RI}
@kindex DO
@kindex LE
@kindex RI
@kindex UP
Strings of commands to move the cursor @var{n} lines down vertically,
up vertically, or @var{n} columns left or right.  Do not attempt to
move past any edge of the screen with these commands; the effect of
trying that is undefined.  Only a few terminal descriptions provide
these commands, and most programs do not use them.

@item @samp{CM}
@kindex CM
String of commands to position the cursor at line @var{l}, column
@var{c}, relative to display memory.  Both parameters are origin-zero.
This capability is present only in terminals where there is a
difference between screen-relative and memory-relative addressing, and
not even in all such terminals.

@item @samp{ch}
@kindex ch
String of commands to position the cursor at column @var{c} in the
same line it is on.  This is a special case of @samp{cm} in which the
vertical position is not changed.  The @samp{ch} capability is
provided only when it is faster to output than @samp{cm} would be in
this special case.  Programs should not assume most display terminals
have @samp{ch}.

@item @samp{cv}
@kindex cv
String of commands to position the cursor at line @var{l} in the same
column.  This is a special case of @samp{cm} in which the horizontal
position is not changed.  The @samp{cv} capability is provided only
when it is faster to output than @samp{cm} would be in this special
case.  Programs should not assume most display terminals have
@samp{cv}.

@item @samp{sc}
@kindex sc
String of commands to make the terminal save the current cursor
position.  Only the last saved position can be used.  If this
capability is present, @samp{rc} should be provided also.  Most
terminals have neither.

@item @samp{rc}
@kindex rc
String of commands to make the terminal restore the last saved cursor
position.  If this capability is present, @samp{sc} should be provided
also.  Most terminals have neither.

@item @samp{ff}
@kindex ff
String of commands to advance to the next page, for a hardcopy
terminal.

@item @samp{ta}
@kindex ta
String of commands to move the cursor right to the next hardware tab
stop column.  Missing if the terminal does not have any kind of
hardware tabs.  Do not send this command if the kernel's terminal
modes say that the kernel is expanding tabs into spaces.

@item @samp{bt}
@kindex bt
String of commands to move the cursor left to the previous hardware
tab stop column.  Missing if the terminal has no such ability; many
terminals do not.  Do not send this command if the kernel's terminal
modes say that the kernel is expanding tabs into spaces.
@end table

The following obsolete capabilities should be included in terminal
descriptions when appropriate, but should not be looked at by new programs.

@table @samp
@item nc
@kindex nc
Flag whose presence means the terminal does not support the ASCII
carriage return character as @samp{cr}.  This flag is needed because
old programs assume, when the @samp{cr} capability is missing, that
ASCII carriage return can be used for the purpose.  We use @samp{nc}
to tell the old programs that carriage return may not be used.

New programs should not assume any default for @samp{cr}, so they need
not look at @samp{nc}.  However, descriptions should contain @samp{nc}
whenever they do not contain @samp{cr}.

@item xt
@kindex xt
Flag whose presence means that the ASCII tab character may not be used
for cursor motion.  This flag exists because old programs assume, when
the @samp{ta} capability is missing, that ASCII tab can be used for
the purpose.  We use @samp{xt} to tell the old programs not to use tab.

New programs should not assume any default for @samp{ta}, so they need
not look at @samp{xt} in connection with cursor motion.  Note that
@samp{xt} also has implications for standout mode (@pxref{Standout}).
It is obsolete in regard to cursor motion but not in regard to
standout.

In fact, @samp{xt} means that the terminal is a Teleray 1061.

@item bc
@kindex bc
Very obsolete alternative name for the @samp{le} capability.

@item bs
@kindex bs
Flag whose presence means that the ASCII character backspace may be
used to move the cursor left.  Obsolete; look at @samp{le} instead.

@item nl
@kindex nl
Obsolete capability which is a string that can either be used to move
the cursor down or to scroll.  The same string must scroll when used
on the bottom line and move the cursor when used on any other line.
New programs should use @samp{do} or @samp{sf}, and ignore @samp{nl}.

If there is no @samp{nl} capability, some old programs assume they can
use the newline character for this purpose.  These programs follow a
bad practice, but because they exist, it is still desirable to define
the @samp{nl} capability in a terminal description if the best way to
move down is @emph{not} a newline.
@end table

@node Wrapping, Scrolling, Cursor Motion, Capabilities
@section Wrapping
@cindex wrapping

@dfn{Wrapping} means moving the cursor from the right margin to the left
margin of the following line.  Some terminals wrap automatically when a
graphic character is output in the last column, while others do not.  Most
application programs that use termcap need to know whether the terminal
wraps.  There are two special flag capabilities to describe what the
terminal does when a graphic character is output in the last column.

@table @samp
@item am
@kindex am
Flag whose presence means that writing a character in the last column
causes the cursor to wrap to the beginning of the next line.

If @samp{am} is not present, writing in the last column leaves the
cursor at the place where the character was written.

Writing in the last column of the last line should be avoided on
terminals with @samp{am}, as it may or may not cause scrolling to
occur (@pxref{Scrolling}).  Scrolling is surely not what you would
intend.

If your program needs to check the @samp{am} flag, then it also needs
to check the @samp{xn} flag which indicates that wrapping happens in a
strange way.  Many common terminals have the @samp{xn} flag.

@item xn
@kindex xn
Flag whose presence means that the cursor wraps in a strange way.  At
least two distinct kinds of strange behavior are known; the termcap
data base does not contain anything to distinguish the two.

On Concept-100 terminals, output in the last column wraps the cursor
almost like an ordinary @samp{am} terminal.  But if the next thing
output is a newline, it is ignored.

DEC VT-100 terminals (when the wrap switch is on) do a different
strange thing: the cursor wraps only if the next thing output is
another graphic character.  In fact, the wrap occurs when the
following graphic character is received by the terminal, before the
character is placed on the screen.

On both of these terminals, after writing in the last column a
following graphic character will be displayed in the first column of
the following line.  But the effect of relative cursor motion
characters such as newline or backspace at such a time depends on the
terminal.  The effect of erase or scrolling commands also depends on
the terminal.  You can't assume anything about what they will do on a
terminal that has @samp{xn}.  So, to be safe, you should never do
these things at such a time on such a terminal.

To be sure of reliable results on a terminal which has the @samp{xn}
flag, output a @samp{cm} absolute positioning command after writing in
the last column.  Another safe thing to do is to output carriage-return
newline, which will leave the cursor at the beginning of the following
line.

@item LP
@kindex LP
Flag whose presence means that it is safe to write in the last column of
the last line without worrying about undesired scrolling.  @samp{LP}
indicates the DEC flavor of @samp{xn} strangeness.
@end table

@node Scrolling, Windows, Wrapping, Capabilities
@section Scrolling
@cindex scrolling

@dfn{Scrolling} means moving the contents of the screen up or down one or
more lines.  Moving the contents up is @dfn{forward scrolling}; moving them
down is @dfn{reverse scrolling}.

Scrolling happens after each line of output during ordinary output on most
display terminals.  But in an application program that uses termcap for
random-access output, scrolling happens only when explicitly requested with
the commands in this section.

Some terminals have a @dfn{scroll region} feature.  This lets you limit
the effect of scrolling to a specified range of lines.  Lines outside the
range are unaffected when scrolling happens.  The scroll region feature
is available if either @samp{cs} or @samp{cS} is present.

@table @samp
@item sf
@kindex sf
String of commands to scroll the screen one line up, assuming it is
output with the cursor at the beginning of the bottom line.

@item sr
@kindex sr
String of commands to scroll the screen one line down, assuming it is
output with the cursor at the beginning of the top line.

@item do
A few programs will try to use @samp{do} to do the work of @samp{sf}.
This is not really correct---it is an attempt to compensate for the
absence of a @samp{sf} command in some old terminal descriptions.

Since these terminal descriptions do define @samp{sr}, perhaps at one
time the definition of @samp{do} was different and it could be used
for scrolling as well.  But it isn't desirable to combine these two
functions in one capability, since scrolling often requires more
padding than simply moving the cursor down.  Defining @samp{sf} and
@samp{do} separately allows you to specify the padding properly.
Also, all sources agree that @samp{do} should not be relied on to do
scrolling.

So the best approach is to add @samp{sf} capabilities to the
descriptions of these terminals, copying the definition of @samp{do}
if that does scroll.

@item SF
@kindex SF
String of commands to scroll the screen @var{n} lines up, assuming it
is output with the cursor at the beginning of the bottom line.

@item SR
@kindex SR
String of commands to scroll the screen @var{n} lines down, assuming it
is output with the cursor at the beginning of the top line.

@item cs
@kindex cs
String of commands to set the scroll region.  This command takes two
parameters, @var{start} and @var{end}, which are the line numbers
(origin-zero) of the first line to include in the scroll region and of
the last line to include in it.  When a scroll region is set,
scrolling is limited to the specified range of lines; lines outside
the range are not affected by scroll commands.

Do not try to move the cursor outside the scroll region.  The region
remains set until explicitly removed.  To remove the scroll region,
use another @samp{cs} command specifying the full height of the
screen.

The cursor position is undefined after the @samp{cs} command is set,
so position the cursor with @samp{cm} immediately afterward.

@item cS
@kindex cS
String of commands to set the scroll region using parameters in
different form.  The effect is the same as if @samp{cs} were used.
Four parameters are required:

@enumerate
@item
Total number of lines on the screen.
@item
Number of lines above desired scroll region.
@item
Number of lines below (outside of) desired scroll region.
@item
Total number of lines on the screen, the same as the first parameter.
@end enumerate

This capability is a GNU extension that was invented to allow the Ann
Arbor Ambassador's scroll-region command to be described; it could
also be done by putting non-Unix @samp{%}-sequences into a @samp{cs}
string, but that would have confused Unix programs that used the
@samp{cs} capability with the Unix termcap.  Currently only GNU Emacs
uses the @samp{cS} capability.

@item ns
@kindex ns
Flag which means that the terminal does not normally scroll for
ordinary sequential output.  For modern terminals, this means that
outputting a newline in ordinary sequential output with the cursor on
the bottom line wraps to the top line.  For some obsolete terminals,
other things may happen.

The terminal may be able to scroll even if it does not normally do so.
If the @samp{sf} capability is provided, it can be used for scrolling
regardless of @samp{ns}.

@item da
@kindex da
Flag whose presence means that lines scrolled up off the top of the
screen may come back if scrolling down is done subsequently.

The @samp{da} and @samp{db} flags do not, strictly speaking, affect
how to scroll.  But programs that scroll usually need to clear the
lines scrolled onto the screen, if these flags are present.

@item db
@kindex db
Flag whose presence means that lines scrolled down off the bottom of
the screen may come back if scrolling up is done subsequently.

@item lm
@kindex lm
Numeric value, the number of lines of display memory that the terminal
has.  A value of zero means that the terminal has more display memory
than can fit on the screen, but no fixed number of lines.  (The number
of lines may depend on the amount of text in each line.)
@end table

Any terminal description that defines @samp{SF} should also define @samp{sf};
likewise for @samp{SR} and @samp{sr}.  However, many terminals can only
scroll by one line at a time, so it is common to find @samp{sf} and not
@samp{SF}, or @samp{sr} without @samp{SR}.@refill

Therefore, all programs that use the scrolling facilities should be
prepared to work with @samp{sf} in the case that @samp{SF} is absent, and
likewise with @samp{sr}.  On the other hand, an application program that
uses only @samp{sf} and not @samp{SF} is acceptable, though slow on some
terminals.@refill

When outputting a scroll command with @code{tputs}, the @var{nlines}
argument should be the total number of lines in the portion of the screen
being scrolled.  Very often these commands require padding proportional to
this number of lines.  @xref{Padding}.

@node Windows, Clearing, Scrolling, Capabilities
@section Windows
@cindex window

A @dfn{window}, in termcap, is a rectangular portion of the screen to which
all display operations are restricted.  Wrapping, clearing, scrolling,
insertion and deletion all operate as if the specified window were all the
screen there was.

@table @samp
@item wi
@kindex wi
String of commands to set the terminal output screen window.
This string requires four parameters, all origin-zero:
@enumerate
@item
The first line to include in the window.
@item
The last line to include in the window.
@item
The first column to include in the window.
@item
The last column to include in the window.
@end enumerate
@end table

Most terminals do not support windows.

@node Clearing, Insdel Line, Windows, Capabilities
@section Clearing Parts of the Screen
@cindex erasing
@cindex clearing the screen

There are several terminal capabilities for clearing parts of the screen
to blank.  All display terminals support the @samp{cl} string, and most
display terminals support all of these capabilities.

@table @samp
@item cl
@kindex cl
String of commands to clear the entire screen and position the cursor
at the upper left corner.

@item cd
@kindex cd
String of commands to clear the line the cursor is on, and all the
lines below it, down to the bottom of the screen.  This command string
should be used only with the cursor in column zero; their effect is
undefined if the cursor is elsewhere.

@item ce
@kindex ce
String of commands to clear from the cursor to the end of the current
line.

@item ec
@kindex ec
String of commands to clear @var{n} characters, starting with the
character that the cursor is on.  This command string is expected to
leave the cursor position unchanged.  The parameter @var{n} should never
be large enough to reach past the right margin; the effect of such a
large parameter would be undefined.
@end table

Clear to end of line (@samp{ce}) is extremely important in programs that
maintain an updating display.  Nearly all display terminals support this
operation, so it is acceptable for a an application program to refuse to
work if @samp{ce} is not present.  However, if you do not want this
limitation, you can accomplish clearing to end of line by outputting spaces
until you reach the right margin.  In order to do this, you must know the
current horizontal position.  Also, this technique assumes that writing a
space will erase.  But this happens to be true on all the display terminals
that fail to support @samp{ce}.

@node Insdel Line, Insdel Char, Clearing, Capabilities
@section Insert/Delete Line

@cindex insert line
@cindex delete line
@dfn{Inserting a line} means creating a blank line in the middle
of the screen, and pushing the existing lines of text apart.  In fact,
the lines above the insertion point do not change, while the lines below
move down, and one is normally lost at the bottom of the screen.

@dfn{Deleting a line} means causing the line to disappear from the screen,
closing up the gap by moving the lines below it upward.  A new line
appears at the bottom of the screen.  Usually this line is blank, but
on terminals with the @samp{db} flag it may be a line previously moved
off the screen bottom by scrolling or line insertion.

Insertion and deletion of lines is useful in programs that maintain an
updating display some parts of which may get longer or shorter.  They are
also useful in editors for scrolling parts of the screen, and for
redisplaying after lines of text are killed or inserted.

Many terminals provide commands to insert or delete a single line at the
cursor position.  Some provide the ability to insert or delete several
lines with one command, using the number of lines to insert or delete as a
parameter.  Always move the cursor to column zero before using any of
these commands.

@table @samp
@item al
@kindex al
String of commands to insert a blank line before the line the cursor
is on.  The existing line, and all lines below it, are moved down.
The last line in the screen (or in the scroll region, if one is set)
disappears and in most circumstances is discarded.  It may not be
discarded if the @samp{db} is present (@pxref{Scrolling}).

The cursor must be at the left margin before this command is used.
This command does not move the cursor.

@item dl
@kindex dl
String of commands to delete the line the cursor is on.  The following
lines move up, and a blank line appears at the bottom of the screen
(or bottom of the scroll region).  If the terminal has the @samp{db}
flag, a nonblank line previously pushed off the screen bottom may
reappear at the bottom.

The cursor must be at the left margin before this command is used.
This command does not move the cursor.

@item AL
@kindex AL
String of commands to insert @var{n} blank lines before the line that
the cursor is on.  It is like @samp{al} repeated @var{n} times, except
that it is as fast as one @samp{al}.

@item DL
@kindex DL
String of commands to delete @var{n} lines starting with the line that
the cursor is on.  It is like @samp{dl} repeated @var{n} times, except
that it is as fast as one @samp{dl}.
@end table

Any terminal description that defines @samp{AL} should also define
@samp{al}; likewise for @samp{DL} and @samp{dl}.  However, many terminals
can only insert or delete one line at a time, so it is common to find
@samp{al} and not @samp{AL}, or @samp{dl} without @samp{DL}.@refill

Therefore, all programs that use the insert and delete facilities should be
prepared to work with @samp{al} in the case that @samp{AL} is absent, and
likewise with @samp{dl}.  On the other hand, it is acceptable to write
an application that uses only @samp{al} and @samp{dl} and does not look
for @samp{AL} or @samp{DL} at all.@refill

If a terminal does not support line insertion and deletion directly,
but does support a scroll region, the effect of insertion and deletion
can be obtained with scrolling.  However, it is up to the individual
user program to check for this possibility and use the scrolling
commands to get the desired result.  It is fairly important to implement
this alternate strategy, since it is the only way to get the effect of
line insertion and deletion on the popular VT100 terminal.

Insertion and deletion of lines is affected by the scroll region on
terminals that have a settable scroll region.  This is useful when it is
desirable to move any few consecutive lines up or down by a few lines.
@xref{Scrolling}.

The line pushed off the bottom of the screen is not lost if the terminal
has the @samp{db} flag capability; instead, it is pushed into display
memory that does not appear on the screen.  This is the same thing that
happens when scrolling pushes a line off the bottom of the screen.
Either reverse scrolling or deletion of a line can bring the apparently
lost line back onto the bottom of the screen.  If the terminal has the
scroll region feature as well as @samp{db}, the pushed-out line really
is lost if a scroll region is in effect.

When outputting an insert or delete command with @code{tputs}, the
@var{nlines} argument should be the total number of lines from the cursor
to the bottom of the screen (or scroll region).  Very often these commands
require padding proportional to this number of lines.  @xref{Padding}.

For @samp{AL} and @samp{DL} the @var{nlines} argument should @emph{not}
depend on the number of lines inserted or deleted; only the total number of
lines affected.  This is because it is just as fast to insert two or
@var{n} lines with @samp{AL} as to insert one line with @samp{al}.

@node Insdel Char, Standout, Insdel Line, Capabilities
@section Insert/Delete Character
@cindex insert character
@cindex delete character

@dfn{Inserting a character} means creating a blank space in the middle of a
line, and pushing the rest of the line rightward.  The character in the
rightmost column is lost.

@dfn{Deleting a character} means causing the character to disappear from
the screen, closing up the gap by moving the rest of the line leftward.  A
blank space appears in the rightmost column.

Insertion and deletion of characters is useful in programs that maintain an
updating display some parts of which may get longer or shorter.  It is also
useful in editors for redisplaying the results of editing within a line.

Many terminals provide commands to insert or delete a single character at
the cursor position.  Some provide the ability to insert or delete several
characters with one command, using the number of characters to insert or
delete as a parameter.

@cindex insert mode
Many terminals provide an insert mode in which outputting a graphic
character has the added effect of inserting a position for that character.
A special command string is used to enter insert mode and another is used
to exit it.  The reason for designing a terminal with an insert mode rather
than an insert command is that inserting character positions is usually
followed by writing characters into them.  With insert mode, this is as
fast as simply writing the characters, except for the fixed overhead of
entering and leaving insert mode.  However, when the line speed is great
enough, padding may be required for the graphic characters output in insert
mode.

Some terminals require you to enter insert mode and then output a special
command for each position to be inserted.  Or they may require special
commands to be output before or after each graphic character to be
inserted.

@cindex delete mode
Deletion of characters is usually accomplished by a straightforward command
to delete one or several positions; but on some terminals, it is necessary
to enter a special delete mode before using the delete command, and leave
delete mode afterward.  Sometimes delete mode and insert mode are the same
mode.

Some terminals make a distinction between character positions in which a
space character has been output and positions which have been cleared.  On
these terminals, the effect of insert or delete character runs to the first
cleared position rather than to the end of the line.  In fact, the effect
may run to more than one line if there is no cleared position to stop the
shift on the first line.  These terminals are identified by the @samp{in}
flag capability.

On terminals with the @samp{in} flag, the technique of skipping over
characters that you know were cleared, and then outputting text later on in
the same line, causes later insert and delete character operations on that
line to do nonstandard things.  A program that has any chance of doing this
must check for the @samp{in} flag and must be careful to write explicit
space characters into the intermediate columns when @samp{in} is present.

A plethora of terminal capabilities are needed to describe all of this
complexity.  Here is a list of them all.  Following the list, we present
an algorithm for programs to use to take proper account of all of these
capabilities.

@table @samp
@item im
@kindex im
String of commands to enter insert mode.

If the terminal has no special insert mode, but it can insert
characters with a special command, @samp{im} should be defined with a
null value, because the @samp{vi} editor assumes that insertion of a
character is impossible if @samp{im} is not provided.

New programs should not act like @samp{vi}.  They should pay attention
to @samp{im} only if it is defined.

@item ei
@kindex ei
String of commands to leave insert mode.  This capability must be
present if @samp{im} is.

On a few old terminals the same string is used to enter and exit
insert mode.  This string turns insert mode on if it was off, and off
it it was on.  You can tell these terminals because the @samp{ei}
string equals the @samp{im} string.  If you want to support these
terminals, you must always remember accurately whether insert mode is
in effect.  However, these terminals are obsolete, and it is
reasonable to refuse to support them.  On all modern terminals, you
can safely output @samp{ei} at any time to ensure that insert mode is
turned off.

@item ic
@kindex ic
String of commands to insert one character position at the cursor.
The cursor does not move.

If outputting a graphic character while in insert mode is sufficient
to insert the character, then the @samp{ic} capability should be
defined with a null value.

If your terminal offers a choice of ways to insert---either use insert
mode or use a special command---then define @samp{im} and do not define
@samp{ic}, since this gives the most efficient operation when several
characters are to be inserted.  @emph{Do not} define both strings, for
that means that @emph{both} must be used each time insertion is done.

@item ip
@kindex ip
String of commands to output following an inserted graphic character
in insert mode.  Often it is used just for a padding spec, when padding
is needed after an inserted character (@pxref{Padding}).

@item IC
@kindex IC
String of commands to insert @var{n} character positions at and after
the cursor.  It has the same effect as repeating the @samp{ic} string
and a space, @var{n} times.

If @samp{IC} is provided, application programs may use it without first
entering insert mode.

@item mi
@kindex mi
Flag whose presence means it is safe to move the cursor while in insert
mode and assume the terminal remains in insert mode.

@item in
@kindex in
Flag whose presence means that the terminal distinguishes between
character positions in which space characters have been output and
positions which have been cleared.
@end table

An application program can assume that the terminal can do character
insertion if @emph{any one of} the capabilities @samp{IC}, @samp{im},
@samp{ic} or @samp{ip} is provided.

To insert @var{n} blank character positions, move the cursor to the place
to insert them and follow this algorithm:

@enumerate
@item
If an @samp{IC} string is provided, output it with parameter @var{n}
and you are finished.  Otherwise (or if you don't want to bother to
look for an @samp{IC} string) follow the remaining steps.

@item
Output the @samp{im} string, if there is one, unless the terminal is
already in insert mode.

@item
Repeat steps 4 through 6, @var{n} times.

@item
Output the @samp{ic} string if any.

@item
Output a space.

@item
Output the @samp{ip} string if any.

@item
Output the @samp{ei} string, eventually, to exit insert mode.  There
is no need to do this right away.  If the @samp{mi} flag is present,
you can move the cursor and the cursor will remain in insert mode;
then you can do more insertion elsewhere without reentering insert
mode.
@end enumerate

To insert @var{n} graphic characters, position the cursor and follow this
algorithm:

@enumerate
@item
If an @samp{IC} string is provided, output it with parameter @var{n},
then output the graphic characters, and you are finished.  Otherwise
(or if you don't want to bother to look for an @samp{IC} string)
follow the remaining steps.

@item
Output the @samp{im} string, if there is one, unless the terminal is
already in insert mode.

@item
For each character to be output, repeat steps 4 through 6.

@item
Output the @samp{ic} string if any.

@item
Output the next graphic character.

@item
Output the @samp{ip} string if any.

@item
Output the @samp{ei} string, eventually, to exit insert mode.  There
is no need to do this right away.  If the @samp{mi} flag is present,
you can move the cursor and the cursor will remain in insert mode;
then you can do more insertion elsewhere without reentering insert
mode.
@end enumerate

Note that this is not the same as the original Unix termcap specifications
in one respect: it assumes that the @samp{IC} string can be used without
entering insert mode.  This is true as far as I know, and it allows you be
able to avoid entering and leaving insert mode, and also to be able to
avoid the inserted-character padding after the characters that go into the
inserted positions.

Deletion of characters is less complicated; deleting one column is done by
outputting the @samp{dc} string.  However, there may be a delete mode that
must be entered with @samp{dm} in order to make @samp{dc} work.

@table @samp
@item dc
@kindex dc
String of commands to delete one character position at the cursor.  If
@samp{dc} is not present, the terminal cannot delete characters.

@item DC
@kindex DC
String of commands to delete @var{n} characters starting at the cursor.
It has the same effect as repeating the @samp{dc} string @var{n} times.
Any terminal description that has @samp{DC} also has @samp{dc}.

@item dm
@kindex dm
String of commands to enter delete mode.  If not present, there is no
delete mode, and @samp{dc} can be used at any time (assuming there is
a @samp{dc}).

@item ed
@kindex ed
String of commands to exit delete mode.  This must be present if
@samp{dm} is.
@end table

To delete @var{n} character positions, position the cursor and follow these
steps:

@enumerate
@item
If the @samp{DC} string is present, output it with parameter @var{n}
and you are finished.  Otherwise, follow the remaining steps.

@item
Output the @samp{dm} string, unless you know the terminal is already
in delete mode.

@item
Output the @samp{dc} string @var{n} times.

@item
Output the @samp{ed} string eventually.  If the flag capability
@samp{mi} is present, you can move the cursor and do more deletion
without leaving and reentering delete mode.
@end enumerate

As with the @samp{IC} string, we have departed from the original termcap
specifications by assuming that @samp{DC} works without entering delete
mode even though @samp{dc} would not.

If the @samp{dm} and @samp{im} capabilities are both present and have the
same value, it means that the terminal has one mode for both insertion and
deletion.  It is useful for a program to know this, because then it can do
insertions after deletions, or vice versa, without leaving insert/delete
mode and reentering it.

@node Standout, Underlining, Insdel Char, Capabilities
@section Standout and Appearance Modes
@cindex appearance modes
@cindex standout
@cindex magic cookie

@dfn{Appearance modes} are modifications to the ways characters are
displayed.  Typical appearance modes include reverse video, dim, bright,
blinking, underlined, invisible, and alternate character set.  Each kind of
terminal supports various among these, or perhaps none.

For each type of terminal, one appearance mode or combination of them that
looks good for highlighted text is chosen as the @dfn{standout mode}.  The
capabilities @samp{so} and @samp{se} say how to enter and leave standout
mode.  Programs that use appearance modes only to highlight some text
generally use the standout mode so that they can work on as many terminals
as possible.  Use of specific appearance modes other than ``underlined''
and ``alternate character set'' is rare.

Terminals that implement appearance modes fall into two general classes as
to how they do it.

In some terminals, the presence or absence of any appearance mode is
recorded separately for each character position.  In these terminals, each
graphic character written is given the appearance modes current at the time
it is written, and keeps those modes until it is erased or overwritten.
There are special commands to turn the appearance modes on or off for
characters to be written in the future.

In other terminals, the change of appearance modes is represented by a
marker that belongs to a certain screen position but affects all following
screen positions until the next marker.  These markers are traditionally
called @dfn{magic cookies}.

The same capabilities (@samp{so}, @samp{se}, @samp{mb} and so on) for
turning appearance modes on and off are used for both magic-cookie
terminals and per-character terminals.  On magic cookie terminals, these
give the commands to write the magic cookies.  On per-character terminals,
they change the current modes that affect future output and erasure.  Some
simple applications can use these commands without knowing whether or not
they work by means of cookies.

However, a program that maintains and updates a display needs to know
whether the terminal uses magic cookies, and exactly what their effect is.
This information comes from the @samp{sg} capability.

The @samp{sg} capability is a numeric capability whose presence indicates
that the terminal uses magic cookies for appearance modes.  Its value is
the number of character positions that a magic cookie occupies.  Usually
the cookie occupies one or more character positions on the screen, and these
character positions are displayed as blank, but in some terminals the
cookie has zero width.

The @samp{sg} capability describes both the magic cookie to turn standout
on and the cookie to turn it off.  This makes the assumption that both
kinds of cookie have the same width on the screen.  If that is not true,
the narrower cookie must be ``widened'' with spaces until it has the same
width as the other.

On some magic cookie terminals, each line always starts with normal
display; in other words, the scope of a magic cookie never extends over
more than one line.  But on other terminals, one magic cookie affects all
the lines below it unless explicitly canceled.  Termcap does not define any
way to distinguish these two ways magic cookies can work.  To be safe, it
is best to put a cookie at the beginning of each line.

On some per-character terminals, standout mode or other appearance modes
may be canceled by moving the cursor.  On others, moving the cursor has no
effect on the state of the appearance modes.  The latter class of terminals
are given the flag capability @samp{ms} (``can move in standout'').  All
programs that might have occasion to move the cursor while appearance modes
are turned on must check for this flag; if it is not present, they should
reset appearance modes to normal before doing cursor motion.

A program that has turned on only standout mode should use @samp{se} to
reset the standout mode to normal.  A program that has turned on only
alternate character set mode should use @samp{ae} to return it to normal.
If it is possible that any other appearance modes are turned on, use the
@samp{me} capability to return them to normal.

Note that the commands to turn on one appearance mode, including @samp{so}
and @samp{mb} @dots{} @samp{mr}, if used while some other appearance modes
are turned on, may combine the two modes on some terminals but may turn off
the mode previously enabled on other terminals.  This is because some
terminals do not have a command to set or clear one appearance mode without
changing the others.  Programs should not attempt to use appearance modes
in combination except with @samp{sa}, and when switching from one single
mode to another should always turn off the previously enabled mode and then
turn on the new desired mode.

On some old terminals, the @samp{so} and @samp{se} commands may be the same
command, which has the effect of turning standout on if it is off, or off
it is on.  It is therefore risky for a program to output extra @samp{se}
commands for good measure.  Fortunately, all these terminals are obsolete.

Programs that update displays in which standout-text may be replaced with
non-standout text must check for the @samp{xs} flag.  In a per-character
terminal, this flag says that the only way to remove standout once written is
to clear that portion of the line with the @samp{ce} string or something
even more powerful (@pxref{Clearing}); just writing new characters at those
screen positions will not change the modes in effect there.  In a magic
cookie terminal, @samp{xs} says that the only way to remove a cookie is to
clear a portion of the line that includes the cookie; writing a different
cookie at the same position does not work.

Such programs must also check for the @samp{xt} flag, which means that the
terminal is a Teleray 1061.  On this terminal it is impossible to position
the cursor at the front of a magic cookie, so the only two ways to remove a
cookie are (1) to delete the line it is on or (2) to position the cursor at
least one character before it (possibly on a previous line) and output the
@samp{se} string, which on these terminals finds and removes the next
@samp{so} magic cookie on the screen.  (It may also be possible to remove a
cookie which is not at the beginning of a line by clearing that line.)  The
@samp{xt} capability also has implications for the use of tab characters,
but in that regard it is obsolete (@xref{Cursor Motion}).

@table @samp
@item so
@kindex so
String of commands to enter standout mode.

@item se
@kindex se
String of commands to leave standout mode.

@item sg
@kindex sg
Numeric capability, the width on the screen of the magic cookie.  This
capability is absent in terminals that record appearance modes
character by character.

@item ms
@kindex ms
Flag whose presence means that it is safe to move the cursor while the
appearance modes are not in the normal state.  If this flag is absent,
programs should always reset the appearance modes to normal before
moving the cursor.

@item xs
@kindex xs
Flag whose presence means that the only way to reset appearance modes
already on the screen is to clear to end of line.  On a per-character
terminal, you must clear the area where the modes are set.  On a magic
cookie terminal, you must clear an area containing the cookie.
See the discussion above.

@item xt
@kindex xt
Flag whose presence means that the cursor cannot be positioned right
in front of a magic cookie, and that @samp{se} is a command to delete
the next magic cookie following the cursor.  See discussion above.

@item mb
@kindex mb
String of commands to enter blinking mode.

@item md
@kindex md
String of commands to enter double-bright mode.

@item mh
@kindex mh
String of commands to enter half-bright mode.

@item mk
@kindex mk
String of commands to enter invisible mode.

@item mp
@kindex mp
String of commands to enter protected mode.

@item mr
@kindex mr
String of commands to enter reverse-video mode.

@item me
@kindex me
String of commands to turn off all appearance modes, including
standout mode and underline mode.  On some terminals it also turns off
alternate character set mode; on others, it may not.  This capability
must be present if any of @samp{mb} @dots{} @samp{mr} is present.

@item as
@kindex as
String of commands to turn on alternate character set mode.  This mode
assigns some or all graphic characters an alternate picture on the
screen.  There is no standard as to what the alternate pictures look
like.

@item ae
@kindex ae
String of commands to turn off alternate character set mode.

@item sa
@kindex sa
String of commands to turn on an arbitrary combination of appearance
modes.  It accepts 9 parameters, each of which controls a particular
kind of appearance mode.  A parameter should be 1 to turn its appearance
mode on, or zero to turn that mode off.  Most terminals do not support
the @samp{sa} capability, even among those that do have various
appearance modes.

The nine parameters are, in order, @var{standout}, @var{underline},
@var{reverse}, @var{blink}, @var{half-bright}, @var{double-bright},
@var{blank}, @var{protect}, @var{alt char set}.
@end table

@node Underlining, Cursor Visibility, Standout, Capabilities
@section Underlining
@cindex underlining

Underlining on most terminals is a kind of appearance mode, much like
standout mode.  Therefore, it may be implemented using magic cookies or as
a flag in the terminal whose current state affects each character that is
output.  @xref{Standout}, for a full explanation.

The @samp{ug} capability is a numeric capability whose presence indicates
that the terminal uses magic cookies for underlining.  Its value is the
number of character positions that a magic cookie for underlining occupies;
it is used for underlining just as @samp{sg} is used for standout.  Aside
from the simplest applications, it is impossible to use underlining
correctly without paying attention to the value of @samp{ug}.

@table @samp
@item us
@kindex us
String of commands to turn on underline mode or to output a magic cookie
to start underlining.

@item ue
@kindex ue
String of commands to turn off underline mode or to output a magic
cookie to stop underlining.

@item ug
@kindex ug
Width of magic cookie that represents a change of underline mode;
or missing, if the terminal does not use a magic cookie for this.

@item ms
@kindex ms
Flag whose presence means that it is safe to move the cursor while the
appearance modes are not in the normal state.  Underlining is an
appearance mode.  If this flag is absent, programs should always turn
off underlining before moving the cursor.
@end table

There are two other, older ways of doing underlining: there can be a
command to underline a single character, or the output of @samp{_}, the
ASCII underscore character, as an overstrike could cause a character to be
underlined.  New programs need not bother to handle these capabilities
unless the author cares strongly about the obscure terminals which support
them.  However, terminal descriptions should provide these capabilities
when appropriate.

@table @samp
@item uc
@kindex uc
String of commands to underline the character under the cursor, and
move the cursor right.

@item ul
@kindex ul
Flag whose presence means that the terminal can underline by
overstriking an underscore character (@samp{_}); some terminals can do
this even though they do not support overstriking in general.  An
implication of this flag is that when outputting new text to overwrite
old text, underscore characters must be treated specially lest they
underline the old text instead.
@end table

@node Cursor Visibility, Bell, Underlining, Capabilities
@section Cursor Visibility
@cindex visibility

Some terminals have the ability to make the cursor invisible, or to enhance
it.  Enhancing the cursor is often done by programs that plan to use the
cursor to indicate to the user a position of interest that may be anywhere
on the screen---for example, the Emacs editor enhances the cursor on entry.
Such programs should always restore the cursor to normal on exit.

@table @samp
@item vs
@kindex vs
String of commands to enhance the cursor.

@item vi
@kindex vi
String of commands to make the cursor invisible.

@item ve
@kindex ve
String of commands to return the cursor to normal.
@end table

If you define either @samp{vs} or @samp{vi}, you must also define @samp{ve}.

@node Bell, Keypad, Cursor Visibility, Capabilities
@section Bell
@cindex bell
@cindex visible bell

Here we describe commands to make the terminal ask for the user to pay
attention to it.

@table @samp
@item bl
@kindex bl
String of commands to cause the terminal to make an audible sound.  If
this capability is absent, the terminal has no way to make a suitable
sound.

@item vb
@kindex vb
String of commands to cause the screen to flash to attract attention
(``visible bell'').  If this capability is absent, the terminal has no
way to do such a thing.
@end table

@node Keypad, Meta Key, Bell, Capabilities
@section Keypad and Function Keys

Many terminals have arrow and function keys that transmit specific
character sequences to the computer.  Since the precise sequences used
depend on the terminal, termcap defines capabilities used to say what the
sequences are.  Unlike most termcap string-valued capabilities, these are
not strings of commands to be sent to the terminal, rather strings that
are received from the terminal.

Programs that expect to use keypad keys should check, initially, for a
@samp{ks} capability and send it, to make the keypad actually transmit.
Such programs should also send the @samp{ke} string when exiting.

@table @asis
@item @samp{ks}
@kindex ka@dots{}ku
String of commands to make the keypad keys transmit.  If this
capability is not provided, but the others in this section are,
programs may assume that the keypad keys always transmit.

@item @samp{ke}
String of commands to make the keypad keys work locally.  This
capability is provided only if @samp{ks} is.

@item @samp{kl}
String of input characters sent by typing the left-arrow key.  If this
capability is missing, you cannot expect the terminal to have a
left-arrow key that transmits anything to the computer.

@item @samp{kr}
String of input characters sent by typing the right-arrow key.

@item @samp{ku}
String of input characters sent by typing the up-arrow key.

@item @samp{kd}
String of input characters sent by typing the down-arrow key.

@item @samp{kh}
String of input characters sent by typing the ``home-position'' key.

@item @samp{K1} @dots{} @samp{K5}
@kindex K1@dots{}K5
Strings of input characters sent by the five other keys in a 3-by-3
array that includes the arrow keys, if the keyboard has such a 3-by-3
array.  Note that one of these keys may be the ``home-position'' key,
in which case one of these capabilities will have the same value as
the @samp{kh} key.

@item @samp{k0}
String of input characters sent by function key 10 (or 0, if the terminal
has one labeled 0).

@item @samp{k1} @dots{} @samp{k9}
@kindex k1@dots{}k9
Strings of input characters sent by function keys 1 through 9,
provided for those function keys that exist.

@item @samp{kn}
Number: the number of numbered function keys, if there are more than
10.

@item @samp{l0} @dots{} @samp{l9}
@kindex l0@dots{}l9
Strings which are the labels appearing on the keyboard on the keys
described by the capabilities @samp{k0} @dots{} @samp{l9}.  These
capabilities should be left undefined if the labels are @samp{f0} or
@samp{f10} and @samp{f1} @dots{} @samp{f9}.@refill

@item @samp{kH}
@kindex kA@dots{}kT
String of input characters sent by the ``home down'' key, if there is
one.

@item @samp{kb}
String of input characters sent by the ``backspace'' key, if there is
one.

@item @samp{ka}
String of input characters sent by the ``clear all tabs'' key, if there
is one.

@item @samp{kt}
String of input characters sent by the ``clear tab stop this column''
key, if there is one.

@item @samp{kC}
String of input characters sent by the ``clear screen'' key, if there is
one.

@item @samp{kD}
String of input characters sent by the ``delete character'' key, if
there is one.

@item @samp{kL}
String of input characters sent by the ``delete line'' key, if there is
one.

@item @samp{kM}
String of input characters sent by the ``exit insert mode'' key, if
there is one.

@item @samp{kE}
String of input characters sent by the ``clear to end of line'' key, if
there is one.

@item @samp{kS}
String of input characters sent by the ``clear to end of screen'' key,
if there is one.

@item @samp{kI}
String of input characters sent by the ``insert character'' or ``enter
insert mode'' key, if there is one.

@item @samp{kA}
String of input characters sent by the ``insert line'' key, if there is
one.

@item @samp{kN}
String of input characters sent by the ``next page'' key, if there is
one.

@item @samp{kP}
String of input characters sent by the ``previous page'' key, if there is
one.

@item @samp{kF}
String of input characters sent by the ``scroll forward'' key, if there
is one.

@item @samp{kR}
String of input characters sent by the ``scroll reverse'' key, if there
is one.

@item @samp{kT}
String of input characters sent by the ``set tab stop in this column''
key, if there is one.

@item @samp{ko}
String listing the other function keys the terminal has.  This is a
very obsolete way of describing the same information found in the
@samp{kH} @dots{} @samp{kT} keys.  The string contains a list of
two-character termcap capability names, separated by commas.  The
meaning is that for each capability name listed, the terminal has a
key which sends the string which is the value of that capability.  For
example, the value @samp{:ko=cl,ll,sf,sr:} says that the terminal has
four function keys which mean ``clear screen'', ``home down'',
``scroll forward'' and ``scroll reverse''.@refill
@end table

@node Meta Key, Initialization, Keypad, Capabilities
@section Meta Key

@cindex meta key
A Meta key is a key on the keyboard that modifies each character you type
by controlling the 0200 bit.  This bit is on if and only if the Meta key is
held down when the character is typed.  Characters typed using the Meta key
are called Meta characters.  Emacs uses Meta characters as editing
commands.

@table @samp
@item km
@kindex km
Flag whose presence means that the terminal has a Meta key.

@item mm
@kindex mm
String of commands to enable the functioning of the Meta key.

@item mo
@kindex mo
String of commands to disable the functioning of the Meta key.
@end table

If the terminal has @samp{km} but does not have @samp{mm} and @samp{mo}, it
means that the Meta key always functions.  If it has @samp{mm} and
@samp{mo}, it means that the Meta key can be turned on or off.  Send the
@samp{mm} string to turn it on, and the @samp{mo} string to turn it off.
I do not know why one would ever not want it to be on.

@node Initialization, Pad Specs, Meta Key, Capabilities
@section Initialization
@cindex reset
@cindex initialization
@cindex tab stops

@table @samp
@item ti
@kindex ti
String of commands to put the terminal into whatever special modes are
needed or appropriate for programs that move the cursor
nonsequentially around the screen.  Programs that use termcap to do
full-screen display should output this string when they start up.

@item te
@kindex te
String of commands to undo what is done by the @samp{ti} string.
Programs that output the @samp{ti} string on entry should output this
string when they exit.

@item is
@kindex is
String of commands to initialize the terminal for each login session.

@item if
@kindex if
String which is the name of a file containing the string of commands
to initialize the terminal for each session of use.  Normally @samp{is}
and @samp{if} are not both used.

@item i1
@itemx i3
@kindex i1
@kindex i3
Two more strings of commands to initialize the terminal for each login
session.  The @samp{i1} string (if defined) is output before @samp{is}
or @samp{if}, and the @samp{i3} string (if defined) is output after.

The reason for having three separate initialization strings is to make
it easier to define a group of related terminal types with slightly
different initializations.  Define two or three of the strings in the
basic type; then the other types can override one or two of the
strings.

@item rs
@kindex rs
String of commands to reset the terminal from any strange mode it may
be in.  Normally this includes the @samp{is} string (or other commands
with the same effects) and more.  What would go in the @samp{rs}
string but not in the @samp{is} string are annoying or slow commands
to bring the terminal back from strange modes that nobody would
normally use.

@item it
@kindex it
Numeric value, the initial spacing between hardware tab stop columns
when the terminal is powered up.  Programs to initialize the terminal
can use this to decide whether there is a need to set the tab stops.
If the initial width is 8, well and good; if it is not 8, then the
tab stops should be set; if they cannot be set, the kernel is told
to convert tabs to spaces, and other programs will observe this and do
likewise.

@item ct
@kindex ct
String of commands to clear all tab stops.

@item st
@kindex st
String of commands to set tab stop at current cursor column on all
lines.

@item NF
@kindex NF
Flag whose presence means that the terminal does not support XON/XOFF
flow control.  Programs should not send XON (@kbd{C-q}) or XOFF
(@kbd{C-s}) characters to the terminal.
@end table

@node Pad Specs, Status Line, Initialization, Capabilities
@section Padding Capabilities
@cindex padding

There are two terminal capabilities that exist just to explain the proper
way to obey the padding specifications in all the command string
capabilities.  One, @samp{pc}, must be obeyed by all termcap-using
programs.

@table @samp
@item pb
@kindex pb
Numeric value, the lowest baud rate at which padding is actually
needed.  Programs may check this and refrain from doing any padding at
lower speeds.

@item pc
@kindex pc
String of commands for padding.  The first character of this string is
to be used as the pad character, instead of using null characters for
padding.  If @samp{pc} is not provided, use null characters.  Every
program that uses termcap must look up this capability and use it to
set the variable @code{PC} that is used by @code{tputs}.
@xref{Padding}.
@end table

Some termcap capabilities exist just to specify the amount of padding that
the kernel should give to cursor motion commands used in ordinary
sequential output.

@table @samp
@item dC
@kindex dC
Numeric value, the number of msec of padding needed for the
carriage-return character.

@item dN
@kindex dN
Numeric value, the number of msec of padding needed for the newline
(linefeed) character.

@item dB
@kindex dB
Numeric value, the number of msec of padding needed for the backspace
character.

@item dF
@kindex dF
Numeric value, the number of msec of padding needed for the formfeed
character.

@item dT
@kindex dT
Numeric value, the number of msec of padding needed for the tab
character.
@end table

In some systems, the kernel uses the above capabilities; in other systems,
the kernel uses the paddings specified in the string capabilities
@samp{cr}, @samp{sf}, @samp{le}, @samp{ff} and @samp{ta}.  Descriptions of
terminals which require such padding should contain the @samp{dC} @dots{}
@samp{dT} capabilities and also specify the appropriate padding in the
corresponding string capabilities.  Since no modern terminals require
padding for ordinary sequential output, you probably won't need to do
either of these things.

@node Status Line, Half-Line, Pad Specs, Capabilities
@section Status Line

@cindex status line
A @dfn{status line} is a line on the terminal that is not used for ordinary
display output but instead used for a special message.  The intended use is
for a continuously updated description of what the user's program is doing,
and that is where the name ``status line'' comes from, but in fact it could
be used for anything.  The distinguishing characteristic of a status line
is that ordinary output to the terminal does not affect it; it changes only
if the special status line commands of this section are used.

@table @samp
@item hs
@kindex hs
Flag whose presence means that the terminal has a status line.  If a
terminal description specifies that there is a status line, it must
provide the @samp{ts} and @samp{fs} capabilities.

@item ts
@kindex ts
String of commands to move the terminal cursor into the status line.
Usually these commands must specifically record the old cursor
position for the sake of the @samp{fs} string.

@item fs
@kindex fs
String of commands to move the cursor back from the status line to its
previous position (outside the status line).

@item es
@kindex es
Flag whose presence means that other display commands work while
writing the status line.  In other words, one can clear parts of it,
insert or delete characters, move the cursor within it using @samp{ch}
if there is a @samp{ch} capability, enter and leave standout mode, and
so on.

@item ds
@kindex ds
String of commands to disable the display of the status line.  This
may be absent, if there is no way to disable the status line display.

@item ws
@kindex ws
Numeric value, the width of the status line.  If this capability is
absent in a terminal that has a status line, it means the status line
is the same width as the other lines.

Note that the value of @samp{ws} is sometimes as small as 8.
@end table

@node Half-Line, Printer, Status Line, Capabilities
@section Half-Line Motion

Some terminals have commands for moving the cursor vertically by half-lines,
useful for outputting subscripts and superscripts.  Mostly it is hardcopy
terminals that have such features.

@table @samp
@item hu
@kindex hu
String of commands to move the cursor up half a line.  If the terminal
is a display, it is your responsibility to avoid moving up past the
top line; however, most likely the terminal that supports this is a
hardcopy terminal and there is nothing to be concerned about.

@item hd
@kindex hd
String of commands to move the cursor down half a line.  If the
terminal is a display, it is your responsibility to avoid moving down
past the bottom line, etc.
@end table

@node Printer,  , Half-Line, Capabilities
@section Controlling Printers Attached to Terminals
@cindex printer

Some terminals have attached hardcopy printer ports.  They may be able to
copy the screen contents to the printer; they may also be able to redirect
output to the printer.  Termcap does not have anything to tell the program
whether the redirected output appears also on the screen; it does on some
terminals but not all.

@table @samp
@item ps
@kindex ps
String of commands to cause the contents of the screen to be printed.
If it is absent, the screen contents cannot be printed.

@item po
@kindex po
String of commands to redirect further output to the printer.

@item pf
@kindex pf
String of commands to terminate redirection of output to the printer.
This capability must be present in the description if @samp{po} is.

@item pO
@kindex pO
String of commands to redirect output to the printer for next @var{n}
characters of output, regardless of what they are.  Redirection will
end automatically after @var{n} characters of further output.  Until
then, nothing that is output can end redirection, not even the
@samp{pf} string if there is one.  The number @var{n} should not be
more than 255.

One use of this capability is to send non-text byte sequences (such as
bit-maps) to the printer.
@end table

Most terminals with printers do not support all of @samp{ps}, @samp{po} and
@samp{pO}; any one or two of them may be supported.  To make a program that
can send output to all kinds of printers, it is necessary to check for all
three of these capabilities, choose the most convenient of the ones that
are provided, and use it in its own appropriate fashion.

@node Summary, Var Index, Capabilities, Top
@chapter Summary of Capability Names

Here are all the terminal capability names in alphabetical order
with a brief description of each.  For cross references to their definitions,
see the index of capability names (@pxref{Cap Index}).

@table @samp
@item ae
String to turn off alternate character set mode.
@item al
String to insert a blank line before the cursor.
@item AL
String to insert @var{n} blank lines before the cursor.
@item am
Flag: output to last column wraps cursor to next line.
@item as
String to turn on alternate character set mode.like.
@item bc
Very obsolete alternative name for the @samp{le} capability.
@item bl
String to sound the bell.
@item bs
Obsolete flag: ASCII backspace may be used for leftward motion.
@item bt
String to move the cursor left to the previous hardware tab stop column.
@item bw
Flag: @samp{le} at left margin wraps to end of previous line.
@item CC
String to change terminal's command character.
@item cd
String to clear the line the cursor is on, and following lines.
@item ce
String to clear from the cursor to the end of the line.
@item ch
String to position the cursor at column @var{c} in the same line.
@item cl
String to clear the entire screen and put cursor at upper left corner.
@item cm
String to position the cursor at line @var{l}, column @var{c}.
@item CM
String to position the cursor at line @var{l}, column
@var{c}, relative to display memory.
@item co
Number: width of the screen.
@item cr
String to move cursor sideways to left margin.
@item cs
String to set the scroll region.
@item cS
Alternate form of string to set the scroll region.
@item ct
String to clear all tab stops.
@item cv
String to position the cursor at line @var{l} in the same column.
@item da
Flag: data scrolled off top of screen may be scrolled back.
@item db
Flag: data scrolled off bottom of screen may be scrolled back.
@item dB
Obsolete number: msec of padding needed for the backspace character.
@item dc
String to delete one character position at the cursor.
@item dC
Obsolete number: msec of padding needed for the carriage-return character.
@item DC
String to delete @var{n} characters starting at the cursor.
@item dF
Obsolete number: msec of padding needed for the formfeed character.
@item dl
String to delete the line the cursor is on.
@item DL
String to delete @var{n} lines starting with the cursor's line.
@item dm
String to enter delete mode.
@item dN
Obsolete number: msec of padding needed for the newline character.
@item do
String to move the cursor vertically down one line.
@item DO
String to move cursor vertically down @var{n} lines.
@item ds
String to disable the display of the status line.
@item dT
Obsolete number: msec of padding needed for the tab character.
@item ec
String of commands to clear @var{n} characters at cursor.
@item ed
String to exit delete mode.
@item ei
String to leave insert mode.
@item eo
Flag: output of a space can erase an overstrike.
@item es
Flag: other display commands work while writing the status line.
@item ff
String to advance to the next page, for a hardcopy terminal.
@item fs
String to move the cursor back from the status line to its
previous position (outside the status line).
@item gn
Flag: this terminal type is generic, not real.
@item hc
Flag: hardcopy terminal.
@item hd
String to move the cursor down half a line.
@item ho
String to position cursor at upper left corner.
@item hs
Flag: the terminal has a status line.
@item hu
String to move the cursor up half a line.
@item hz
Flag: terminal cannot accept @samp{~} as output.
@item i1
String to initialize the terminal for each login session.
@item i3
String to initialize the terminal for each login session.
@item ic
String to insert one character position at the cursor.
@item IC
String to insert @var{n} character positions at the cursor.
@item if
String naming a file of commands to initialize the terminal.
@item im
String to enter insert mode.
@item in
Flag: outputting a space is different from moving over empty positions.
@item ip
String to output following an inserted character in insert mode.
@item is
String to initialize the terminal for each login session.
@item it
Number: initial spacing between hardware tab stop columns.
@item k0
String of input sent by function key 0 or 10.
@item k1 @dots{} k9
Strings of input sent by function keys 1 through 9.
@item K1 @dots{} K5
Strings sent by the five other keys in 3-by-3 array with arrows.
@item ka
String of input sent by the ``clear all tabs'' key.
@item kA
String of input sent by the ``insert line'' key.
@item kb
String of input sent by the ``backspace'' key.
@item kC
String of input sent by the ``clear screen'' key.
@item kd
String of input sent by typing the down-arrow key.
@item kD
String of input sent by the ``delete character'' key.
@item ke
String to make the function keys work locally.
@item kE
String of input sent by the ``clear to end of line'' key.
@item kF
String of input sent by the ``scroll forward'' key.
@item kh
String of input sent by typing the ``home-position'' key.
@item kH
String of input sent by the ``home down'' key.
@item kI
String of input sent by the ``insert character'' or ``enter
insert mode'' key.
@item kl
String of input sent by typing the left-arrow key.
@item kL
String of input sent by the ``delete line'' key.
@item km
Flag: the terminal has a Meta key.
@item kM
String of input sent by the ``exit insert mode'' key.
@item kn
Numeric value, the number of numbered function keys.
@item kN
String of input sent by the ``next page'' key.
@item ko
Very obsolete string listing the terminal's named function keys.
@item kP
String of input sent by the ``previous page'' key.
@item kr
String of input sent by typing the right-arrow key.
@item kR
String of input sent by the ``scroll reverse'' key.
@item ks
String to make the function keys transmit.
@item kS
String of input sent by the ``clear to end of screen'' key.
@item kt
String of input sent by the ``clear tab stop this column'' key.
@item kT
String of input sent by the ``set tab stop in this column'' key.
@item ku
String of input sent by typing the up-arrow key.
@item l0
String on keyboard labelling function key 0 or 10.
@item l1 @dots{} l9
Strings on keyboard labelling function keys 1 through 9.
@item le
String to move the cursor left one column.
@item LE
String to move cursor left @var{n} columns.
@item li
Number: height of the screen.
@item ll
String to position cursor at lower left corner.
@item lm
Number: lines of display memory.
@item LP
Flag: writing to last column of last line will not scroll.
@item mb
String to enter blinking mode.
@item md
String to enter double-bright mode.
@item me
String to turn off all appearance modes
@item mh
String to enter half-bright mode.
@item mi
Flag: cursor motion in insert mode is safe.
@item mk
String to enter invisible mode.
@item mm
String to enable the functioning of the Meta key.
@item mo
String to disable the functioning of the Meta key.
@item mp
String to enter protected mode.
@item mr
String to enter reverse-video mode.
@item ms
Flag: cursor motion in standout mode is safe.
@item nc
Obsolete flag: do not use ASCII carriage-return on this terminal.
@item nd
String to move the cursor right one column.
@item NF
Flag: do not use XON/XOFF flow control.
@item nl
Obsolete alternative name for the @samp{do} and @samp{sf} capabilities.
@item ns
Flag: the terminal does not normally scroll for sequential output.
@item nw
String to move to start of next line, possibly clearing rest of old line.
@item os
Flag: terminal can overstrike.
@item pb
Number: the lowest baud rate at which padding is actually needed.
@item pc
String containing character for padding.
@item pf
String to terminate redirection of output to the printer.
@item po
String to redirect further output to the printer.
@item pO
String to redirect @var{n} characters ofoutput to the printer.
@item ps
String to print the screen on the attached printer.
@item rc
String to move to last saved cursor position.
@item RI
String to move cursor right @var{n} columns.
@item rp
String to output character @var{c} repeated @var{n} times.
@item rs
String to reset the terminal from any strange modes.
@item sa
String to turn on an arbitrary combination of appearance modes.
@item sc
String to save the current cursor position.
@item se
String to leave standout mode.
@item sf
String to scroll the screen one line up.
@item SF
String to scroll the screen @var{n} lines up.
@item sg
Number: width of magic standout cookie.  Absent if magic cookies are
not used.
@item so
String to enter standout mode.
@item sr
String to scroll the screen one line down.
@item SR
String to scroll the screen @var{n} line down.
@item st
String to set tab stop at current cursor column on all lines.
programs.
@item ta
String to move the cursor right to the next hardware tab stop column.
@item te
String to return terminal to settings for sequential output.
@item ti
String to initialize terminal for random cursor motion.
@item ts
String to move the terminal cursor into the status line.
@item uc
String to underline one character and move cursor right.
@item ue
String to turn off underline mode
@item ug
Number: width of underlining magic cookie.  Absent if underlining
doesn't use magic cookies.
@item ul
Flag: underline by overstriking with an underscore.
@item up
String to move the cursor vertically up one line.
@item UP
String to move cursor vertically up @var{n} lines.
@item us
String to turn on underline mode
@item vb
String to make the screen flash.
@item ve
String to return the cursor to normal.
@item vi
String to make the cursor invisible.
@item vs
String to enhance the cursor.
@item wi
String to set the terminal output screen window.
@item ws
Number: the width of the status line.
@item xb
Flag: superbee terminal.
@item xn
Flag: cursor wraps in a strange way.
@item xs
Flag: clearing a line is the only way to clear the appearance modes of
positions in that line (or, only way to remove magic cookies on that
line).
@item xt
Flag: Teleray 1061; several strange characteristics.
@end table

@node Var Index, Cap Index, Summary, Top
@unnumbered Variable and Function Index

@printindex fn

@node Cap Index, Index, Var Index, Top
@unnumbered Capability Index

@printindex ky

@node Index,  , Cap Index, Top
@unnumbered Concept Index

@printindex cp

@contents
@bye