/usr/share/doc/glibc-doc/html/libc_17.html is in glibc-doc 2.15-0ubuntu10.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 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 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- This file documents the GNU C library.
This is Edition 0.13, last updated 2011-07-19,
of The GNU C Library Reference Manual, for version
2.14 (Ubuntu EGLIBC 2.15-0ubuntu10) .
Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010, 2011 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation"
and "GNU Lesser General Public License", the Front-Cover texts being
"A GNU Manual", and with the Back-Cover Texts as in (a) below. A
copy of the license is included in the section entitled "GNU Free
Documentation License".
(a) The FSF's Back-Cover Text is: "You have the freedom to
copy and modify this GNU manual. Buying copies from the FSF
supports it in developing GNU and promoting software freedom."
-->
<!-- Created on April 20, 2012 by texi2html 1.82
texi2html was written by:
Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>The GNU C Library: 17. Low-Level Terminal Interface</title>
<meta name="description" content="The GNU C Library: 17. Low-Level Terminal Interface">
<meta name="keywords" content="The GNU C Library: 17. Low-Level Terminal Interface">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Low_002dLevel-Terminal-Interface"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="libc_16.html#Networks-Database" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Is-It-a-Terminal" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc_16.html#Sockets" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Low_002dLevel-Terminal-Interface-1"></a>
<h1 class="chapter">17. Low-Level Terminal Interface</h1>
<p>This chapter describes functions that are specific to terminal devices.
You can use these functions to do things like turn off input echoing;
set serial line characteristics such as line speed and flow control; and
change which characters are used for end-of-file, command-line editing,
sending signals, and similar control functions.
</p>
<p>Most of the functions in this chapter operate on file descriptors.
See section <a href="libc_13.html#Low_002dLevel-I_002fO">Low-Level Input/Output</a>, for more information about what a file
descriptor is and how to open a file descriptor for a terminal device.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Is-It-a-Terminal">17.1 Identifying Terminals</a></td><td> </td><td align="left" valign="top"> How to determine if a file is a terminal
device, and what its name is.
</td></tr>
<tr><td align="left" valign="top"><a href="#I_002fO-Queues">17.2 I/O Queues</a></td><td> </td><td align="left" valign="top"> About flow control and typeahead.
</td></tr>
<tr><td align="left" valign="top"><a href="#Canonical-or-Not">17.3 Two Styles of Input: Canonical or Not</a></td><td> </td><td align="left" valign="top"> Two basic styles of input processing.
</td></tr>
<tr><td align="left" valign="top"><a href="#Terminal-Modes">17.4 Terminal Modes</a></td><td> </td><td align="left" valign="top"> How to examine and modify flags controlling
details of terminal I/O: echoing,
signals, editing. Posix.
</td></tr>
<tr><td align="left" valign="top"><a href="#BSD-Terminal-Modes">17.5 BSD Terminal Modes</a></td><td> </td><td align="left" valign="top"> BSD compatible terminal mode setting
</td></tr>
<tr><td align="left" valign="top"><a href="#Line-Control">17.6 Line Control Functions</a></td><td> </td><td align="left" valign="top"> Sending break sequences, clearing
terminal buffers …
</td></tr>
<tr><td align="left" valign="top"><a href="#Noncanon-Example">17.7 Noncanonical Mode Example</a></td><td> </td><td align="left" valign="top"> How to read single characters without echo.
</td></tr>
<tr><td align="left" valign="top"><a href="#Pseudo_002dTerminals">17.8 Pseudo-Terminals</a></td><td> </td><td align="left" valign="top"> How to open a pseudo-terminal.
</td></tr>
</table>
<hr size="6">
<a name="Is-It-a-Terminal"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-Queues" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Identifying-Terminals"></a>
<h2 class="section">17.1 Identifying Terminals</h2>
<a name="index-terminal-identification"></a>
<a name="index-identifying-terminals"></a>
<p>The functions described in this chapter only work on files that
correspond to terminal devices. You can find out whether a file
descriptor is associated with a terminal by using the <code>isatty</code>
function.
</p>
<a name="index-unistd_002eh-13"></a>
<p>Prototypes for the functions in this section are declared in the header
file ‘<tt>unistd.h</tt>’.
</p>
<dl>
<dt><a name="index-isatty"></a><u>Function:</u> int <b>isatty</b><i> (int <var>filedes</var>)</i></dt>
<dd><p>This function returns <code>1</code> if <var>filedes</var> is a file descriptor
associated with an open terminal device, and <em>0</em> otherwise.
</p></dd></dl>
<p>If a file descriptor is associated with a terminal, you can get its
associated file name using the <code>ttyname</code> function. See also the
<code>ctermid</code> function, described in <a href="libc_27.html#Identifying-the-Terminal">Identifying the Controlling Terminal</a>.
</p>
<dl>
<dt><a name="index-ttyname"></a><u>Function:</u> char * <b>ttyname</b><i> (int <var>filedes</var>)</i></dt>
<dd><p>If the file descriptor <var>filedes</var> is associated with a terminal
device, the <code>ttyname</code> function returns a pointer to a
statically-allocated, null-terminated string containing the file name of
the terminal file. The value is a null pointer if the file descriptor
isn’t associated with a terminal, or the file name cannot be determined.
</p></dd></dl>
<dl>
<dt><a name="index-ttyname_005fr"></a><u>Function:</u> int <b>ttyname_r</b><i> (int <var>filedes</var>, char *<var>buf</var>, size_t <var>len</var>)</i></dt>
<dd><p>The <code>ttyname_r</code> function is similar to the <code>ttyname</code> function
except that it places its result into the user-specified buffer starting
at <var>buf</var> with length <var>len</var>.
</p>
<p>The normal return value from <code>ttyname_r</code> is <em>0</em>. Otherwise an
error number is returned to indicate the error. The following
<code>errno</code> error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> argument is not a valid file descriptor.
</p>
</dd>
<dt> <code>ENOTTY</code></dt>
<dd><p>The <var>filedes</var> is not associated with a terminal.
</p>
</dd>
<dt> <code>ERANGE</code></dt>
<dd><p>The buffer length <var>len</var> is too small to store the string to be
returned.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="I_002fO-Queues"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Is-It-a-Terminal" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Canonical-or-Not" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="I_002fO-Queues-1"></a>
<h2 class="section">17.2 I/O Queues</h2>
<p>Many of the remaining functions in this section refer to the input and
output queues of a terminal device. These queues implement a form of
buffering <em>within the kernel</em> independent of the buffering
implemented by I/O streams (see section <a href="libc_12.html#I_002fO-on-Streams">Input/Output on Streams</a>).
</p>
<a name="index-terminal-input-queue"></a>
<a name="index-typeahead-buffer"></a>
<p>The <em>terminal input queue</em> is also sometimes referred to as its
<em>typeahead buffer</em>. It holds the characters that have been received
from the terminal but not yet read by any process.
</p>
<p>The size of the input queue is described by the <code>MAX_INPUT</code> and
<code>_POSIX_MAX_INPUT</code> parameters; see <a href="libc_31.html#Limits-for-Files">Limits on File System Capacity</a>. You
are guaranteed a queue size of at least <code>MAX_INPUT</code>, but the queue
might be larger, and might even dynamically change size. If input flow
control is enabled by setting the <code>IXOFF</code> input mode bit
(see section <a href="#Input-Modes">Input Modes</a>), the terminal driver transmits STOP and START
characters to the terminal when necessary to prevent the queue from
overflowing. Otherwise, input may be lost if it comes in too fast from
the terminal. In canonical mode, all input stays in the queue until a
newline character is received, so the terminal input queue can fill up
when you type a very long line. See section <a href="#Canonical-or-Not">Two Styles of Input: Canonical or Not</a>.
</p>
<a name="index-terminal-output-queue"></a>
<p>The <em>terminal output queue</em> is like the input queue, but for output;
it contains characters that have been written by processes, but not yet
transmitted to the terminal. If output flow control is enabled by
setting the <code>IXON</code> input mode bit (see section <a href="#Input-Modes">Input Modes</a>), the
terminal driver obeys START and STOP characters sent by the terminal to
stop and restart transmission of output.
</p>
<p><em>Clearing</em> the terminal input queue means discarding any characters
that have been received but not yet read. Similarly, clearing the
terminal output queue means discarding any characters that have been
written but not yet transmitted.
</p>
<hr size="6">
<a name="Canonical-or-Not"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#I_002fO-Queues" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Two-Styles-of-Input_003a-Canonical-or-Not"></a>
<h2 class="section">17.3 Two Styles of Input: Canonical or Not</h2>
<p>POSIX systems support two basic modes of input: canonical and
noncanonical.
</p>
<a name="index-canonical-input-processing"></a>
<p>In <em>canonical input processing</em> mode, terminal input is processed in
lines terminated by newline (<code>'\n'</code>), EOF, or EOL characters. No
input can be read until an entire line has been typed by the user, and
the <code>read</code> function (see section <a href="libc_13.html#I_002fO-Primitives">Input and Output Primitives</a>) returns at most a
single line of input, no matter how many bytes are requested.
</p>
<p>In canonical input mode, the operating system provides input editing
facilities: some characters are interpreted specially to perform editing
operations within the current line of text, such as ERASE and KILL.
See section <a href="#Editing-Characters">Characters for Input Editing</a>.
</p>
<p>The constants <code>_POSIX_MAX_CANON</code> and <code>MAX_CANON</code> parameterize
the maximum number of bytes which may appear in a single line of
canonical input. See section <a href="libc_31.html#Limits-for-Files">Limits on File System Capacity</a>. You are guaranteed a maximum
line length of at least <code>MAX_CANON</code> bytes, but the maximum might be
larger, and might even dynamically change size.
</p>
<a name="index-noncanonical-input-processing"></a>
<p>In <em>noncanonical input processing</em> mode, characters are not grouped
into lines, and ERASE and KILL processing is not performed. The
granularity with which bytes are read in noncanonical input mode is
controlled by the MIN and TIME settings. See section <a href="#Noncanonical-Input">Noncanonical Input</a>.
</p>
<p>Most programs use canonical input mode, because this gives the user a
way to edit input line by line. The usual reason to use noncanonical
mode is when the program accepts single-character commands or provides
its own editing facilities.
</p>
<p>The choice of canonical or noncanonical input is controlled by the
<code>ICANON</code> flag in the <code>c_lflag</code> member of <code>struct termios</code>.
See section <a href="#Local-Modes">Local Modes</a>.
</p>
<hr size="6">
<a name="Terminal-Modes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Canonical-or-Not" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Mode-Data-Types" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Terminal-Modes-1"></a>
<h2 class="section">17.4 Terminal Modes</h2>
<a name="index-termios_002eh-1"></a>
<p>This section describes the various terminal attributes that control how
input and output are done. The functions, data structures, and symbolic
constants are all declared in the header file ‘<tt>termios.h</tt>’.
</p>
<p>Don’t confuse terminal attributes with file attributes. A device special
file which is associated with a terminal has file attributes as described
in <a href="libc_14.html#File-Attributes">File Attributes</a>. These are unrelated to the attributes of the
terminal device itself, which are discussed in this section.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Mode-Data-Types">17.4.1 Terminal Mode Data Types</a></td><td> </td><td align="left" valign="top"> The data type <code>struct termios</code> and
related types.
</td></tr>
<tr><td align="left" valign="top"><a href="#Mode-Functions">17.4.2 Terminal Mode Functions</a></td><td> </td><td align="left" valign="top"> Functions to read and set the terminal
attributes.
</td></tr>
<tr><td align="left" valign="top"><a href="#Setting-Modes">17.4.3 Setting Terminal Modes Properly</a></td><td> </td><td align="left" valign="top"> The right way to set terminal attributes
reliably.
</td></tr>
<tr><td align="left" valign="top"><a href="#Input-Modes">17.4.4 Input Modes</a></td><td> </td><td align="left" valign="top"> Flags controlling low-level input handling.
</td></tr>
<tr><td align="left" valign="top"><a href="#Output-Modes">17.4.5 Output Modes</a></td><td> </td><td align="left" valign="top"> Flags controlling low-level output handling.
</td></tr>
<tr><td align="left" valign="top"><a href="#Control-Modes">17.4.6 Control Modes</a></td><td> </td><td align="left" valign="top"> Flags controlling serial port behavior.
</td></tr>
<tr><td align="left" valign="top"><a href="#Local-Modes">17.4.7 Local Modes</a></td><td> </td><td align="left" valign="top"> Flags controlling high-level input handling.
</td></tr>
<tr><td align="left" valign="top"><a href="#Line-Speed">17.4.8 Line Speed</a></td><td> </td><td align="left" valign="top"> How to read and set the terminal line speed.
</td></tr>
<tr><td align="left" valign="top"><a href="#Special-Characters">17.4.9 Special Characters</a></td><td> </td><td align="left" valign="top"> Characters that have special effects,
and how to change them.
</td></tr>
<tr><td align="left" valign="top"><a href="#Noncanonical-Input">17.4.10 Noncanonical Input</a></td><td> </td><td align="left" valign="top"> Controlling how long to wait for input.
</td></tr>
</table>
<hr size="6">
<a name="Mode-Data-Types"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Terminal-Modes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Mode-Functions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Terminal-Mode-Data-Types"></a>
<h3 class="subsection">17.4.1 Terminal Mode Data Types</h3>
<a name="index-terminal-mode-data-types"></a>
<p>The entire collection of attributes of a terminal is stored in a
structure of type <code>struct termios</code>. This structure is used
with the functions <code>tcgetattr</code> and <code>tcsetattr</code> to read
and set the attributes.
</p>
<dl>
<dt><a name="index-struct-termios"></a><u>Data Type:</u> <b>struct termios</b></dt>
<dd><p>Structure that records all the I/O attributes of a terminal. The
structure includes at least the following members:
</p>
<dl compact="compact">
<dt> <code>tcflag_t c_iflag</code></dt>
<dd><p>A bit mask specifying flags for input modes; see <a href="#Input-Modes">Input Modes</a>.
</p>
</dd>
<dt> <code>tcflag_t c_oflag</code></dt>
<dd><p>A bit mask specifying flags for output modes; see <a href="#Output-Modes">Output Modes</a>.
</p>
</dd>
<dt> <code>tcflag_t c_cflag</code></dt>
<dd><p>A bit mask specifying flags for control modes; see <a href="#Control-Modes">Control Modes</a>.
</p>
</dd>
<dt> <code>tcflag_t c_lflag</code></dt>
<dd><p>A bit mask specifying flags for local modes; see <a href="#Local-Modes">Local Modes</a>.
</p>
</dd>
<dt> <code>cc_t c_cc[NCCS]</code></dt>
<dd><p>An array specifying which characters are associated with various
control functions; see <a href="#Special-Characters">Special Characters</a>.
</p></dd>
</dl>
<p>The <code>struct termios</code> structure also contains members which
encode input and output transmission speeds, but the representation is
not specified. See section <a href="#Line-Speed">Line Speed</a>, for how to examine and store the
speed values.
</p></dd></dl>
<p>The following sections describe the details of the members of the
<code>struct termios</code> structure.
</p>
<dl>
<dt><a name="index-tcflag_005ft"></a><u>Data Type:</u> <b>tcflag_t</b></dt>
<dd><p>This is an unsigned integer type used to represent the various
bit masks for terminal flags.
</p></dd></dl>
<dl>
<dt><a name="index-cc_005ft"></a><u>Data Type:</u> <b>cc_t</b></dt>
<dd><p>This is an unsigned integer type used to represent characters associated
with various terminal control functions.
</p></dd></dl>
<dl>
<dt><a name="index-NCCS"></a><u>Macro:</u> int <b>NCCS</b></dt>
<dd><p>The value of this macro is the number of elements in the <code>c_cc</code>
array.
</p></dd></dl>
<hr size="6">
<a name="Mode-Functions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Mode-Data-Types" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Setting-Modes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Terminal-Mode-Functions"></a>
<h3 class="subsection">17.4.2 Terminal Mode Functions</h3>
<a name="index-terminal-mode-functions"></a>
<dl>
<dt><a name="index-tcgetattr"></a><u>Function:</u> int <b>tcgetattr</b><i> (int <var>filedes</var>, struct termios *<var>termios-p</var>)</i></dt>
<dd><p>This function is used to examine the attributes of the terminal
device with file descriptor <var>filedes</var>. The attributes are returned
in the structure that <var>termios-p</var> points to.
</p>
<p>If successful, <code>tcgetattr</code> returns <em>0</em>. A return value of <em>-1</em>
indicates an error. The following <code>errno</code> error conditions are
defined for this function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> argument is not a valid file descriptor.
</p>
</dd>
<dt> <code>ENOTTY</code></dt>
<dd><p>The <var>filedes</var> is not associated with a terminal.
</p></dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-tcsetattr"></a><u>Function:</u> int <b>tcsetattr</b><i> (int <var>filedes</var>, int <var>when</var>, const struct termios *<var>termios-p</var>)</i></dt>
<dd><p>This function sets the attributes of the terminal device with file
descriptor <var>filedes</var>. The new attributes are taken from the
structure that <var>termios-p</var> points to.
</p>
<p>The <var>when</var> argument specifies how to deal with input and output
already queued. It can be one of the following values:
</p>
<dl compact="compact">
<dt> <code>TCSANOW</code></dt>
<dd><a name="index-TCSANOW"></a>
<p>Make the change immediately.
</p>
</dd>
<dt> <code>TCSADRAIN</code></dt>
<dd><a name="index-TCSADRAIN"></a>
<p>Make the change after waiting until all queued output has been written.
You should usually use this option when changing parameters that affect
output.
</p>
</dd>
<dt> <code>TCSAFLUSH</code></dt>
<dd><a name="index-TCSAFLUSH"></a>
<p>This is like <code>TCSADRAIN</code>, but also discards any queued input.
</p>
</dd>
<dt> <code>TCSASOFT</code></dt>
<dd><a name="index-TCSASOFT"></a>
<p>This is a flag bit that you can add to any of the above alternatives.
Its meaning is to inhibit alteration of the state of the terminal
hardware. It is a BSD extension; it is only supported on BSD systems
and the GNU system.
</p>
<p>Using <code>TCSASOFT</code> is exactly the same as setting the <code>CIGNORE</code>
bit in the <code>c_cflag</code> member of the structure <var>termios-p</var> points
to. See section <a href="#Control-Modes">Control Modes</a>, for a description of <code>CIGNORE</code>.
</p></dd>
</dl>
<p>If this function is called from a background process on its controlling
terminal, normally all processes in the process group are sent a
<code>SIGTTOU</code> signal, in the same way as if the process were trying to
write to the terminal. The exception is if the calling process itself
is ignoring or blocking <code>SIGTTOU</code> signals, in which case the
operation is performed and no signal is sent. See section <a href="libc_27.html#Job-Control">Job Control</a>.
</p>
<p>If successful, <code>tcsetattr</code> returns <em>0</em>. A return value of
<em>-1</em> indicates an error. The following <code>errno</code> error
conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> argument is not a valid file descriptor.
</p>
</dd>
<dt> <code>ENOTTY</code></dt>
<dd><p>The <var>filedes</var> is not associated with a terminal.
</p>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p>Either the value of the <code>when</code> argument is not valid, or there is
something wrong with the data in the <var>termios-p</var> argument.
</p></dd>
</dl>
</dd></dl>
<p>Although <code>tcgetattr</code> and <code>tcsetattr</code> specify the terminal
device with a file descriptor, the attributes are those of the terminal
device itself and not of the file descriptor. This means that the
effects of changing terminal attributes are persistent; if another
process opens the terminal file later on, it will see the changed
attributes even though it doesn’t have anything to do with the open file
descriptor you originally specified in changing the attributes.
</p>
<p>Similarly, if a single process has multiple or duplicated file
descriptors for the same terminal device, changing the terminal
attributes affects input and output to all of these file
descriptors. This means, for example, that you can’t open one file
descriptor or stream to read from a terminal in the normal
line-buffered, echoed mode; and simultaneously have another file
descriptor for the same terminal that you use to read from it in
single-character, non-echoed mode. Instead, you have to explicitly
switch the terminal back and forth between the two modes.
</p>
<hr size="6">
<a name="Setting-Modes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Mode-Functions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Input-Modes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Setting-Terminal-Modes-Properly"></a>
<h3 class="subsection">17.4.3 Setting Terminal Modes Properly</h3>
<p>When you set terminal modes, you should call <code>tcgetattr</code> first to
get the current modes of the particular terminal device, modify only
those modes that you are really interested in, and store the result with
<code>tcsetattr</code>.
</p>
<p>It’s a bad idea to simply initialize a <code>struct termios</code> structure
to a chosen set of attributes and pass it directly to <code>tcsetattr</code>.
Your program may be run years from now, on systems that support members
not documented in this manual. The way to avoid setting these members
to unreasonable values is to avoid changing them.
</p>
<p>What’s more, different terminal devices may require different mode
settings in order to function properly. So you should avoid blindly
copying attributes from one terminal device to another.
</p>
<p>When a member contains a collection of independent flags, as the
<code>c_iflag</code>, <code>c_oflag</code> and <code>c_cflag</code> members do, even
setting the entire member is a bad idea, because particular operating
systems have their own flags. Instead, you should start with the
current value of the member and alter only the flags whose values matter
in your program, leaving any other flags unchanged.
</p>
<p>Here is an example of how to set one flag (<code>ISTRIP</code>) in the
<code>struct termios</code> structure while properly preserving all the other
data in the structure:
</p>
<table><tr><td> </td><td><pre class="smallexample">int
set_istrip (int desc, int value)
{
struct termios settings;
int result;
</pre><pre class="smallexample">
</pre><pre class="smallexample"> result = tcgetattr (desc, &settings);
if (result < 0)
{
perror ("error in tcgetattr");
return 0;
}
</pre><pre class="smallexample"> settings.c_iflag &= ~ISTRIP;
if (value)
settings.c_iflag |= ISTRIP;
</pre><pre class="smallexample"> result = tcsetattr (desc, TCSANOW, &settings);
if (result < 0)
{
perror ("error in tcsetattr");
return 0;
}
return 1;
}
</pre></td></tr></table>
<hr size="6">
<a name="Input-Modes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Setting-Modes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Output-Modes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Input-Modes-1"></a>
<h3 class="subsection">17.4.4 Input Modes</h3>
<p>This section describes the terminal attribute flags that control
fairly low-level aspects of input processing: handling of parity errors,
break signals, flow control, and <RET> and <LFD> characters.
</p>
<p>All of these flags are bits in the <code>c_iflag</code> member of the
<code>struct termios</code> structure. The member is an integer, and you
change flags using the operators <code>&</code>, <code>|</code> and <code>^</code>. Don’t
try to specify the entire value for <code>c_iflag</code>—instead, change
only specific flags and leave the rest untouched (see section <a href="#Setting-Modes">Setting Terminal Modes Properly</a>).
</p>
<dl>
<dt><a name="index-INPCK"></a><u>Macro:</u> tcflag_t <b>INPCK</b></dt>
<dd><a name="index-parity-checking"></a>
<p>If this bit is set, input parity checking is enabled. If it is not set,
no checking at all is done for parity errors on input; the
characters are simply passed through to the application.
</p>
<p>Parity checking on input processing is independent of whether parity
detection and generation on the underlying terminal hardware is enabled;
see <a href="#Control-Modes">Control Modes</a>. For example, you could clear the <code>INPCK</code>
input mode flag and set the <code>PARENB</code> control mode flag to ignore
parity errors on input, but still generate parity on output.
</p>
<p>If this bit is set, what happens when a parity error is detected depends
on whether the <code>IGNPAR</code> or <code>PARMRK</code> bits are set. If neither
of these bits are set, a byte with a parity error is passed to the
application as a <code>'\0'</code> character.
</p></dd></dl>
<dl>
<dt><a name="index-IGNPAR"></a><u>Macro:</u> tcflag_t <b>IGNPAR</b></dt>
<dd><p>If this bit is set, any byte with a framing or parity error is ignored.
This is only useful if <code>INPCK</code> is also set.
</p></dd></dl>
<dl>
<dt><a name="index-PARMRK"></a><u>Macro:</u> tcflag_t <b>PARMRK</b></dt>
<dd><p>If this bit is set, input bytes with parity or framing errors are marked
when passed to the program. This bit is meaningful only when
<code>INPCK</code> is set and <code>IGNPAR</code> is not set.
</p>
<p>The way erroneous bytes are marked is with two preceding bytes,
<code>377</code> and <code>0</code>. Thus, the program actually reads three bytes
for one erroneous byte received from the terminal.
</p>
<p>If a valid byte has the value <code>0377</code>, and <code>ISTRIP</code> (see below)
is not set, the program might confuse it with the prefix that marks a
parity error. So a valid byte <code>0377</code> is passed to the program as
two bytes, <code>0377</code> <code>0377</code>, in this case.
</p></dd></dl>
<dl>
<dt><a name="index-ISTRIP"></a><u>Macro:</u> tcflag_t <b>ISTRIP</b></dt>
<dd><p>If this bit is set, valid input bytes are stripped to seven bits;
otherwise, all eight bits are available for programs to read.
</p></dd></dl>
<dl>
<dt><a name="index-IGNBRK"></a><u>Macro:</u> tcflag_t <b>IGNBRK</b></dt>
<dd><p>If this bit is set, break conditions are ignored.
</p>
<a name="index-break-condition_002c-detecting"></a>
<p>A <em>break condition</em> is defined in the context of asynchronous
serial data transmission as a series of zero-value bits longer than a
single byte.
</p></dd></dl>
<dl>
<dt><a name="index-BRKINT"></a><u>Macro:</u> tcflag_t <b>BRKINT</b></dt>
<dd><p>If this bit is set and <code>IGNBRK</code> is not set, a break condition
clears the terminal input and output queues and raises a <code>SIGINT</code>
signal for the foreground process group associated with the terminal.
</p>
<p>If neither <code>BRKINT</code> nor <code>IGNBRK</code> are set, a break condition is
passed to the application as a single <code>'\0'</code> character if
<code>PARMRK</code> is not set, or otherwise as a three-character sequence
<code>'\377'</code>, <code>'\0'</code>, <code>'\0'</code>.
</p></dd></dl>
<dl>
<dt><a name="index-IGNCR"></a><u>Macro:</u> tcflag_t <b>IGNCR</b></dt>
<dd><p>If this bit is set, carriage return characters (<code>'\r'</code>) are
discarded on input. Discarding carriage return may be useful on
terminals that send both carriage return and linefeed when you type the
<RET> key.
</p></dd></dl>
<dl>
<dt><a name="index-ICRNL"></a><u>Macro:</u> tcflag_t <b>ICRNL</b></dt>
<dd><p>If this bit is set and <code>IGNCR</code> is not set, carriage return characters
(<code>'\r'</code>) received as input are passed to the application as newline
characters (<code>'\n'</code>).
</p></dd></dl>
<dl>
<dt><a name="index-INLCR"></a><u>Macro:</u> tcflag_t <b>INLCR</b></dt>
<dd><p>If this bit is set, newline characters (<code>'\n'</code>) received as input
are passed to the application as carriage return characters (<code>'\r'</code>).
</p></dd></dl>
<dl>
<dt><a name="index-IXOFF"></a><u>Macro:</u> tcflag_t <b>IXOFF</b></dt>
<dd><p>If this bit is set, start/stop control on input is enabled. In other
words, the computer sends STOP and START characters as necessary to
prevent input from coming in faster than programs are reading it. The
idea is that the actual terminal hardware that is generating the input
data responds to a STOP character by suspending transmission, and to a
START character by resuming transmission. See section <a href="#Start_002fStop-Characters">Special Characters for Flow Control</a>.
</p></dd></dl>
<dl>
<dt><a name="index-IXON"></a><u>Macro:</u> tcflag_t <b>IXON</b></dt>
<dd><p>If this bit is set, start/stop control on output is enabled. In other
words, if the computer receives a STOP character, it suspends output
until a START character is received. In this case, the STOP and START
characters are never passed to the application program. If this bit is
not set, then START and STOP can be read as ordinary characters.
See section <a href="#Start_002fStop-Characters">Special Characters for Flow Control</a>.
</p></dd></dl>
<dl>
<dt><a name="index-IXANY"></a><u>Macro:</u> tcflag_t <b>IXANY</b></dt>
<dd><p>If this bit is set, any input character restarts output when output has
been suspended with the STOP character. Otherwise, only the START
character restarts output.
</p>
<p>This is a BSD extension; it exists only on BSD systems and the GNU system.
</p></dd></dl>
<dl>
<dt><a name="index-IMAXBEL"></a><u>Macro:</u> tcflag_t <b>IMAXBEL</b></dt>
<dd><p>If this bit is set, then filling up the terminal input buffer sends a
BEL character (code <code>007</code>) to the terminal to ring the bell.
</p>
<p>This is a BSD extension.
</p></dd></dl>
<hr size="6">
<a name="Output-Modes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Input-Modes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Control-Modes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Output-Modes-1"></a>
<h3 class="subsection">17.4.5 Output Modes</h3>
<p>This section describes the terminal flags and fields that control how
output characters are translated and padded for display. All of these
are contained in the <code>c_oflag</code> member of the <code>struct termios</code>
structure.
</p>
<p>The <code>c_oflag</code> member itself is an integer, and you change the flags
and fields using the operators <code>&</code>, <code>|</code>, and <code>^</code>. Don’t
try to specify the entire value for <code>c_oflag</code>—instead, change
only specific flags and leave the rest untouched (see section <a href="#Setting-Modes">Setting Terminal Modes Properly</a>).
</p>
<dl>
<dt><a name="index-OPOST"></a><u>Macro:</u> tcflag_t <b>OPOST</b></dt>
<dd><p>If this bit is set, output data is processed in some unspecified way so
that it is displayed appropriately on the terminal device. This
typically includes mapping newline characters (<code>'\n'</code>) onto
carriage return and linefeed pairs.
</p>
<p>If this bit isn’t set, the characters are transmitted as-is.
</p></dd></dl>
<p>The following three bits are BSD features, and they exist only BSD
systems and the GNU system. They are effective only if <code>OPOST</code> is
set.
</p>
<dl>
<dt><a name="index-ONLCR"></a><u>Macro:</u> tcflag_t <b>ONLCR</b></dt>
<dd><p>If this bit is set, convert the newline character on output into a pair
of characters, carriage return followed by linefeed.
</p></dd></dl>
<dl>
<dt><a name="index-OXTABS"></a><u>Macro:</u> tcflag_t <b>OXTABS</b></dt>
<dd><p>If this bit is set, convert tab characters on output into the appropriate
number of spaces to emulate a tab stop every eight columns.
</p></dd></dl>
<dl>
<dt><a name="index-ONOEOT"></a><u>Macro:</u> tcflag_t <b>ONOEOT</b></dt>
<dd><p>If this bit is set, discard <kbd>C-d</kbd> characters (code <code>004</code>) on
output. These characters cause many dial-up terminals to disconnect.
</p></dd></dl>
<hr size="6">
<a name="Control-Modes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Output-Modes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Local-Modes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Control-Modes-1"></a>
<h3 class="subsection">17.4.6 Control Modes</h3>
<p>This section describes the terminal flags and fields that control
parameters usually associated with asynchronous serial data
transmission. These flags may not make sense for other kinds of
terminal ports (such as a network connection pseudo-terminal). All of
these are contained in the <code>c_cflag</code> member of the <code>struct
termios</code> structure.
</p>
<p>The <code>c_cflag</code> member itself is an integer, and you change the flags
and fields using the operators <code>&</code>, <code>|</code>, and <code>^</code>. Don’t
try to specify the entire value for <code>c_cflag</code>—instead, change
only specific flags and leave the rest untouched (see section <a href="#Setting-Modes">Setting Terminal Modes Properly</a>).
</p>
<dl>
<dt><a name="index-CLOCAL"></a><u>Macro:</u> tcflag_t <b>CLOCAL</b></dt>
<dd><p>If this bit is set, it indicates that the terminal is connected
“locally” and that the modem status lines (such as carrier detect)
should be ignored.
<a name="index-modem-status-lines"></a>
<a name="index-carrier-detect"></a>
</p>
<p>On many systems if this bit is not set and you call <code>open</code> without
the <code>O_NONBLOCK</code> flag set, <code>open</code> blocks until a modem
connection is established.
</p>
<p>If this bit is not set and a modem disconnect is detected, a
<code>SIGHUP</code> signal is sent to the controlling process group for the
terminal (if it has one). Normally, this causes the process to exit;
see <a href="libc_24.html#Signal-Handling">Signal Handling</a>. Reading from the terminal after a disconnect
causes an end-of-file condition, and writing causes an <code>EIO</code> error
to be returned. The terminal device must be closed and reopened to
clear the condition.
<a name="index-modem-disconnect"></a>
</p></dd></dl>
<dl>
<dt><a name="index-HUPCL"></a><u>Macro:</u> tcflag_t <b>HUPCL</b></dt>
<dd><p>If this bit is set, a modem disconnect is generated when all processes
that have the terminal device open have either closed the file or exited.
</p></dd></dl>
<dl>
<dt><a name="index-CREAD"></a><u>Macro:</u> tcflag_t <b>CREAD</b></dt>
<dd><p>If this bit is set, input can be read from the terminal. Otherwise,
input is discarded when it arrives.
</p></dd></dl>
<dl>
<dt><a name="index-CSTOPB"></a><u>Macro:</u> tcflag_t <b>CSTOPB</b></dt>
<dd><p>If this bit is set, two stop bits are used. Otherwise, only one stop bit
is used.
</p></dd></dl>
<dl>
<dt><a name="index-PARENB"></a><u>Macro:</u> tcflag_t <b>PARENB</b></dt>
<dd><p>If this bit is set, generation and detection of a parity bit are enabled.
See section <a href="#Input-Modes">Input Modes</a>, for information on how input parity errors are handled.
</p>
<p>If this bit is not set, no parity bit is added to output characters, and
input characters are not checked for correct parity.
</p></dd></dl>
<dl>
<dt><a name="index-PARODD"></a><u>Macro:</u> tcflag_t <b>PARODD</b></dt>
<dd><p>This bit is only useful if <code>PARENB</code> is set. If <code>PARODD</code> is set,
odd parity is used, otherwise even parity is used.
</p></dd></dl>
<p>The control mode flags also includes a field for the number of bits per
character. You can use the <code>CSIZE</code> macro as a mask to extract the
value, like this: <code>settings.c_cflag & CSIZE</code>.
</p>
<dl>
<dt><a name="index-CSIZE"></a><u>Macro:</u> tcflag_t <b>CSIZE</b></dt>
<dd><p>This is a mask for the number of bits per character.
</p></dd></dl>
<dl>
<dt><a name="index-CS5"></a><u>Macro:</u> tcflag_t <b>CS5</b></dt>
<dd><p>This specifies five bits per byte.
</p></dd></dl>
<dl>
<dt><a name="index-CS6"></a><u>Macro:</u> tcflag_t <b>CS6</b></dt>
<dd><p>This specifies six bits per byte.
</p></dd></dl>
<dl>
<dt><a name="index-CS7"></a><u>Macro:</u> tcflag_t <b>CS7</b></dt>
<dd><p>This specifies seven bits per byte.
</p></dd></dl>
<dl>
<dt><a name="index-CS8"></a><u>Macro:</u> tcflag_t <b>CS8</b></dt>
<dd><p>This specifies eight bits per byte.
</p></dd></dl>
<p>The following four bits are BSD extensions; this exist only on BSD
systems and the GNU system.
</p>
<dl>
<dt><a name="index-CCTS_005fOFLOW"></a><u>Macro:</u> tcflag_t <b>CCTS_OFLOW</b></dt>
<dd><p>If this bit is set, enable flow control of output based on the CTS wire
(RS232 protocol).
</p></dd></dl>
<dl>
<dt><a name="index-CRTS_005fIFLOW"></a><u>Macro:</u> tcflag_t <b>CRTS_IFLOW</b></dt>
<dd><p>If this bit is set, enable flow control of input based on the RTS wire
(RS232 protocol).
</p></dd></dl>
<dl>
<dt><a name="index-MDMBUF"></a><u>Macro:</u> tcflag_t <b>MDMBUF</b></dt>
<dd><p>If this bit is set, enable carrier-based flow control of output.
</p></dd></dl>
<dl>
<dt><a name="index-CIGNORE"></a><u>Macro:</u> tcflag_t <b>CIGNORE</b></dt>
<dd><p>If this bit is set, it says to ignore the control modes and line speed
values entirely. This is only meaningful in a call to <code>tcsetattr</code>.
</p>
<p>The <code>c_cflag</code> member and the line speed values returned by
<code>cfgetispeed</code> and <code>cfgetospeed</code> will be unaffected by the
call. <code>CIGNORE</code> is useful if you want to set all the software
modes in the other members, but leave the hardware details in
<code>c_cflag</code> unchanged. (This is how the <code>TCSASOFT</code> flag to
<code>tcsettattr</code> works.)
</p>
<p>This bit is never set in the structure filled in by <code>tcgetattr</code>.
</p></dd></dl>
<hr size="6">
<a name="Local-Modes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Control-Modes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Line-Speed" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Local-Modes-1"></a>
<h3 class="subsection">17.4.7 Local Modes</h3>
<p>This section describes the flags for the <code>c_lflag</code> member of the
<code>struct termios</code> structure. These flags generally control
higher-level aspects of input processing than the input modes flags
described in <a href="#Input-Modes">Input Modes</a>, such as echoing, signals, and the choice
of canonical or noncanonical input.
</p>
<p>The <code>c_lflag</code> member itself is an integer, and you change the flags
and fields using the operators <code>&</code>, <code>|</code>, and <code>^</code>. Don’t
try to specify the entire value for <code>c_lflag</code>—instead, change
only specific flags and leave the rest untouched (see section <a href="#Setting-Modes">Setting Terminal Modes Properly</a>).
</p>
<dl>
<dt><a name="index-ICANON"></a><u>Macro:</u> tcflag_t <b>ICANON</b></dt>
<dd><p>This bit, if set, enables canonical input processing mode. Otherwise,
input is processed in noncanonical mode. See section <a href="#Canonical-or-Not">Two Styles of Input: Canonical or Not</a>.
</p></dd></dl>
<dl>
<dt><a name="index-ECHO"></a><u>Macro:</u> tcflag_t <b>ECHO</b></dt>
<dd><p>If this bit is set, echoing of input characters back to the terminal
is enabled.
<a name="index-echo-of-terminal-input"></a>
</p></dd></dl>
<dl>
<dt><a name="index-ECHOE"></a><u>Macro:</u> tcflag_t <b>ECHOE</b></dt>
<dd><p>If this bit is set, echoing indicates erasure of input with the ERASE
character by erasing the last character in the current line from the
screen. Otherwise, the character erased is re-echoed to show what has
happened (suitable for a printing terminal).
</p>
<p>This bit only controls the display behavior; the <code>ICANON</code> bit by
itself controls actual recognition of the ERASE character and erasure of
input, without which <code>ECHOE</code> is simply irrelevant.
</p></dd></dl>
<dl>
<dt><a name="index-ECHOPRT"></a><u>Macro:</u> tcflag_t <b>ECHOPRT</b></dt>
<dd><p>This bit is like <code>ECHOE</code>, enables display of the ERASE character in
a way that is geared to a hardcopy terminal. When you type the ERASE
character, a ‘<samp>\</samp>’ character is printed followed by the first
character erased. Typing the ERASE character again just prints the next
character erased. Then, the next time you type a normal character, a
‘<samp>/</samp>’ character is printed before the character echoes.
</p>
<p>This is a BSD extension, and exists only in BSD systems and the
GNU system.
</p></dd></dl>
<dl>
<dt><a name="index-ECHOK"></a><u>Macro:</u> tcflag_t <b>ECHOK</b></dt>
<dd><p>This bit enables special display of the KILL character by moving to a
new line after echoing the KILL character normally. The behavior of
<code>ECHOKE</code> (below) is nicer to look at.
</p>
<p>If this bit is not set, the KILL character echoes just as it would if it
were not the KILL character. Then it is up to the user to remember that
the KILL character has erased the preceding input; there is no
indication of this on the screen.
</p>
<p>This bit only controls the display behavior; the <code>ICANON</code> bit by
itself controls actual recognition of the KILL character and erasure of
input, without which <code>ECHOK</code> is simply irrelevant.
</p></dd></dl>
<dl>
<dt><a name="index-ECHOKE"></a><u>Macro:</u> tcflag_t <b>ECHOKE</b></dt>
<dd><p>This bit is similar to <code>ECHOK</code>. It enables special display of the
KILL character by erasing on the screen the entire line that has been
killed. This is a BSD extension, and exists only in BSD systems and the
GNU system.
</p></dd></dl>
<dl>
<dt><a name="index-ECHONL"></a><u>Macro:</u> tcflag_t <b>ECHONL</b></dt>
<dd><p>If this bit is set and the <code>ICANON</code> bit is also set, then the
newline (<code>'\n'</code>) character is echoed even if the <code>ECHO</code> bit
is not set.
</p></dd></dl>
<dl>
<dt><a name="index-ECHOCTL"></a><u>Macro:</u> tcflag_t <b>ECHOCTL</b></dt>
<dd><p>If this bit is set and the <code>ECHO</code> bit is also set, echo control
characters with ‘<samp>^</samp>’ followed by the corresponding text character.
Thus, control-A echoes as ‘<samp>^A</samp>’. This is usually the preferred mode
for interactive input, because echoing a control character back to the
terminal could have some undesired effect on the terminal.
</p>
<p>This is a BSD extension, and exists only in BSD systems and the
GNU system.
</p></dd></dl>
<dl>
<dt><a name="index-ISIG"></a><u>Macro:</u> tcflag_t <b>ISIG</b></dt>
<dd><p>This bit controls whether the INTR, QUIT, and SUSP characters are
recognized. The functions associated with these characters are performed
if and only if this bit is set. Being in canonical or noncanonical
input mode has no affect on the interpretation of these characters.
</p>
<p>You should use caution when disabling recognition of these characters.
Programs that cannot be interrupted interactively are very
user-unfriendly. If you clear this bit, your program should provide
some alternate interface that allows the user to interactively send the
signals associated with these characters, or to escape from the program.
<a name="index-interactive-signals_002c-from-terminal"></a>
</p>
<p>See section <a href="#Signal-Characters">Characters that Cause Signals</a>.
</p></dd></dl>
<dl>
<dt><a name="index-IEXTEN"></a><u>Macro:</u> tcflag_t <b>IEXTEN</b></dt>
<dd><p>POSIX.1 gives <code>IEXTEN</code> implementation-defined meaning,
so you cannot rely on this interpretation on all systems.
</p>
<p>On BSD systems and the GNU system, it enables the LNEXT and DISCARD characters.
See section <a href="#Other-Special">Other Special Characters</a>.
</p></dd></dl>
<dl>
<dt><a name="index-NOFLSH"></a><u>Macro:</u> tcflag_t <b>NOFLSH</b></dt>
<dd><p>Normally, the INTR, QUIT, and SUSP characters cause input and output
queues for the terminal to be cleared. If this bit is set, the queues
are not cleared.
</p></dd></dl>
<dl>
<dt><a name="index-TOSTOP"></a><u>Macro:</u> tcflag_t <b>TOSTOP</b></dt>
<dd><p>If this bit is set and the system supports job control, then
<code>SIGTTOU</code> signals are generated by background processes that
attempt to write to the terminal. See section <a href="libc_27.html#Access-to-the-Terminal">Access to the Controlling Terminal</a>.
</p></dd></dl>
<p>The following bits are BSD extensions; they exist only in BSD systems
and the GNU system.
</p>
<dl>
<dt><a name="index-ALTWERASE"></a><u>Macro:</u> tcflag_t <b>ALTWERASE</b></dt>
<dd><p>This bit determines how far the WERASE character should erase. The
WERASE character erases back to the beginning of a word; the question
is, where do words begin?
</p>
<p>If this bit is clear, then the beginning of a word is a nonwhitespace
character following a whitespace character. If the bit is set, then the
beginning of a word is an alphanumeric character or underscore following
a character which is none of those.
</p>
<p>See section <a href="#Editing-Characters">Characters for Input Editing</a>, for more information about the WERASE character.
</p></dd></dl>
<dl>
<dt><a name="index-FLUSHO"></a><u>Macro:</u> tcflag_t <b>FLUSHO</b></dt>
<dd><p>This is the bit that toggles when the user types the DISCARD character.
While this bit is set, all output is discarded. See section <a href="#Other-Special">Other Special Characters</a>.
</p></dd></dl>
<dl>
<dt><a name="index-NOKERNINFO"></a><u>Macro:</u> tcflag_t <b>NOKERNINFO</b></dt>
<dd><p>Setting this bit disables handling of the STATUS character.
See section <a href="#Other-Special">Other Special Characters</a>.
</p></dd></dl>
<dl>
<dt><a name="index-PENDIN"></a><u>Macro:</u> tcflag_t <b>PENDIN</b></dt>
<dd><p>If this bit is set, it indicates that there is a line of input that
needs to be reprinted. Typing the REPRINT character sets this bit; the
bit remains set until reprinting is finished. See section <a href="#Editing-Characters">Characters for Input Editing</a>.
</p></dd></dl>
<hr size="6">
<a name="Line-Speed"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Local-Modes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Special-Characters" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Line-Speed-1"></a>
<h3 class="subsection">17.4.8 Line Speed</h3>
<a name="index-line-speed"></a>
<a name="index-baud-rate"></a>
<a name="index-terminal-line-speed"></a>
<a name="index-terminal-line-speed-1"></a>
<p>The terminal line speed tells the computer how fast to read and write
data on the terminal.
</p>
<p>If the terminal is connected to a real serial line, the terminal speed
you specify actually controls the line—if it doesn’t match the
terminal’s own idea of the speed, communication does not work. Real
serial ports accept only certain standard speeds. Also, particular
hardware may not support even all the standard speeds. Specifying a
speed of zero hangs up a dialup connection and turns off modem control
signals.
</p>
<p>If the terminal is not a real serial line (for example, if it is a
network connection), then the line speed won’t really affect data
transmission speed, but some programs will use it to determine the
amount of padding needed. It’s best to specify a line speed value that
matches the actual speed of the actual terminal, but you can safely
experiment with different values to vary the amount of padding.
</p>
<p>There are actually two line speeds for each terminal, one for input and
one for output. You can set them independently, but most often
terminals use the same speed for both directions.
</p>
<p>The speed values are stored in the <code>struct termios</code> structure, but
don’t try to access them in the <code>struct termios</code> structure
directly. Instead, you should use the following functions to read and
store them:
</p>
<dl>
<dt><a name="index-cfgetospeed"></a><u>Function:</u> speed_t <b>cfgetospeed</b><i> (const struct termios *<var>termios-p</var>)</i></dt>
<dd><p>This function returns the output line speed stored in the structure
<code>*<var>termios-p</var></code>.
</p></dd></dl>
<dl>
<dt><a name="index-cfgetispeed"></a><u>Function:</u> speed_t <b>cfgetispeed</b><i> (const struct termios *<var>termios-p</var>)</i></dt>
<dd><p>This function returns the input line speed stored in the structure
<code>*<var>termios-p</var></code>.
</p></dd></dl>
<dl>
<dt><a name="index-cfsetospeed"></a><u>Function:</u> int <b>cfsetospeed</b><i> (struct termios *<var>termios-p</var>, speed_t <var>speed</var>)</i></dt>
<dd><p>This function stores <var>speed</var> in <code>*<var>termios-p</var></code> as the output
speed. The normal return value is <em>0</em>; a value of <em>-1</em>
indicates an error. If <var>speed</var> is not a speed, <code>cfsetospeed</code>
returns <em>-1</em>.
</p></dd></dl>
<dl>
<dt><a name="index-cfsetispeed"></a><u>Function:</u> int <b>cfsetispeed</b><i> (struct termios *<var>termios-p</var>, speed_t <var>speed</var>)</i></dt>
<dd><p>This function stores <var>speed</var> in <code>*<var>termios-p</var></code> as the input
speed. The normal return value is <em>0</em>; a value of <em>-1</em>
indicates an error. If <var>speed</var> is not a speed, <code>cfsetospeed</code>
returns <em>-1</em>.
</p></dd></dl>
<dl>
<dt><a name="index-cfsetspeed"></a><u>Function:</u> int <b>cfsetspeed</b><i> (struct termios *<var>termios-p</var>, speed_t <var>speed</var>)</i></dt>
<dd><p>This function stores <var>speed</var> in <code>*<var>termios-p</var></code> as both the
input and output speeds. The normal return value is <em>0</em>; a value
of <em>-1</em> indicates an error. If <var>speed</var> is not a speed,
<code>cfsetspeed</code> returns <em>-1</em>. This function is an extension in
4.4 BSD.
</p></dd></dl>
<dl>
<dt><a name="index-speed_005ft"></a><u>Data Type:</u> <b>speed_t</b></dt>
<dd><p>The <code>speed_t</code> type is an unsigned integer data type used to
represent line speeds.
</p></dd></dl>
<p>The functions <code>cfsetospeed</code> and <code>cfsetispeed</code> report errors
only for speed values that the system simply cannot handle. If you
specify a speed value that is basically acceptable, then those functions
will succeed. But they do not check that a particular hardware device
can actually support the specified speeds—in fact, they don’t know
which device you plan to set the speed for. If you use <code>tcsetattr</code>
to set the speed of a particular device to a value that it cannot
handle, <code>tcsetattr</code> returns <em>-1</em>.
</p>
<p><strong>Portability note:</strong> In the GNU library, the functions above
accept speeds measured in bits per second as input, and return speed
values measured in bits per second. Other libraries require speeds to
be indicated by special codes. For POSIX.1 portability, you must use
one of the following symbols to represent the speed; their precise
numeric values are system-dependent, but each name has a fixed meaning:
<code>B110</code> stands for 110 bps, <code>B300</code> for 300 bps, and so on.
There is no portable way to represent any speed but these, but these are
the only speeds that typical serial lines can support.
</p>
<a name="index-B0"></a>
<a name="index-B50"></a>
<a name="index-B75"></a>
<a name="index-B110"></a>
<a name="index-B134"></a>
<a name="index-B150"></a>
<a name="index-B200"></a>
<a name="index-B300"></a>
<a name="index-B600"></a>
<a name="index-B1200"></a>
<a name="index-B1800"></a>
<a name="index-B2400"></a>
<a name="index-B4800"></a>
<a name="index-B9600"></a>
<a name="index-B19200"></a>
<a name="index-B38400"></a>
<a name="index-B57600"></a>
<a name="index-B115200"></a>
<a name="index-B230400"></a>
<a name="index-B460800"></a>
<table><tr><td> </td><td><pre class="smallexample">B0 B50 B75 B110 B134 B150 B200
B300 B600 B1200 B1800 B2400 B4800
B9600 B19200 B38400 B57600 B115200
B230400 B460800
</pre></td></tr></table>
<a name="index-EXTA"></a>
<a name="index-EXTB"></a>
<p>BSD defines two additional speed symbols as aliases: <code>EXTA</code> is an
alias for <code>B19200</code> and <code>EXTB</code> is an alias for <code>B38400</code>.
These aliases are obsolete.
</p>
<hr size="6">
<a name="Special-Characters"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Line-Speed" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Editing-Characters" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Special-Characters-1"></a>
<h3 class="subsection">17.4.9 Special Characters</h3>
<p>In canonical input, the terminal driver recognizes a number of special
characters which perform various control functions. These include the
ERASE character (usually <DEL>) for editing input, and other editing
characters. The INTR character (normally <kbd>C-c</kbd>) for sending a
<code>SIGINT</code> signal, and other signal-raising characters, may be
available in either canonical or noncanonical input mode. All these
characters are described in this section.
</p>
<p>The particular characters used are specified in the <code>c_cc</code> member
of the <code>struct termios</code> structure. This member is an array; each
element specifies the character for a particular role. Each element has
a symbolic constant that stands for the index of that element—for
example, <code>VINTR</code> is the index of the element that specifies the INTR
character, so storing <code>'='</code> in <code><var>termios</var>.c_cc[VINTR]</code>
specifies ‘<samp>=</samp>’ as the INTR character.
</p>
<a name="index-_005fPOSIX_005fVDISABLE"></a>
<p>On some systems, you can disable a particular special character function
by specifying the value <code>_POSIX_VDISABLE</code> for that role. This
value is unequal to any possible character code. See section <a href="libc_31.html#Options-for-Files">Optional Features in File Support</a>, for more information about how to tell whether the operating
system you are using supports <code>_POSIX_VDISABLE</code>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Editing-Characters">17.4.9.1 Characters for Input Editing</a></td><td> </td><td align="left" valign="top"> Special characters that terminate lines and
delete text, and other editing functions.
</td></tr>
<tr><td align="left" valign="top"><a href="#Signal-Characters">17.4.9.2 Characters that Cause Signals</a></td><td> </td><td align="left" valign="top"> Special characters that send or raise signals
to or for certain classes of processes.
</td></tr>
<tr><td align="left" valign="top"><a href="#Start_002fStop-Characters">17.4.9.3 Special Characters for Flow Control</a></td><td> </td><td align="left" valign="top"> Special characters that suspend or resume
suspended output.
</td></tr>
<tr><td align="left" valign="top"><a href="#Other-Special">17.4.9.4 Other Special Characters</a></td><td> </td><td align="left" valign="top"> Other special characters for BSD systems:
they can discard output, and print status.
</td></tr>
</table>
<hr size="6">
<a name="Editing-Characters"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Special-Characters" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Signal-Characters" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Special-Characters" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Characters-for-Input-Editing"></a>
<h4 class="subsubsection">17.4.9.1 Characters for Input Editing</h4>
<p>These special characters are active only in canonical input mode.
See section <a href="#Canonical-or-Not">Two Styles of Input: Canonical or Not</a>.
</p>
<dl>
<dt><a name="index-VEOF"></a><u>Macro:</u> int <b>VEOF</b></dt>
<dd><a name="index-EOF-character"></a>
<p>This is the subscript for the EOF character in the special control
character array. <code><var>termios</var>.c_cc[VEOF]</code> holds the character
itself.
</p>
<p>The EOF character is recognized only in canonical input mode. It acts
as a line terminator in the same way as a newline character, but if the
EOF character is typed at the beginning of a line it causes <code>read</code>
to return a byte count of zero, indicating end-of-file. The EOF
character itself is discarded.
</p>
<p>Usually, the EOF character is <kbd>C-d</kbd>.
</p></dd></dl>
<dl>
<dt><a name="index-VEOL"></a><u>Macro:</u> int <b>VEOL</b></dt>
<dd><a name="index-EOL-character"></a>
<p>This is the subscript for the EOL character in the special control
character array. <code><var>termios</var>.c_cc[VEOL]</code> holds the character
itself.
</p>
<p>The EOL character is recognized only in canonical input mode. It acts
as a line terminator, just like a newline character. The EOL character
is not discarded; it is read as the last character in the input line.
</p>
<p>You don’t need to use the EOL character to make <RET> end a line.
Just set the ICRNL flag. In fact, this is the default state of
affairs.
</p></dd></dl>
<dl>
<dt><a name="index-VEOL2"></a><u>Macro:</u> int <b>VEOL2</b></dt>
<dd><a name="index-EOL2-character"></a>
<p>This is the subscript for the EOL2 character in the special control
character array. <code><var>termios</var>.c_cc[VEOL2]</code> holds the character
itself.
</p>
<p>The EOL2 character works just like the EOL character (see above), but it
can be a different character. Thus, you can specify two characters to
terminate an input line, by setting EOL to one of them and EOL2 to the
other.
</p>
<p>The EOL2 character is a BSD extension; it exists only on BSD systems
and the GNU system.
</p></dd></dl>
<dl>
<dt><a name="index-VERASE"></a><u>Macro:</u> int <b>VERASE</b></dt>
<dd><a name="index-ERASE-character"></a>
<p>This is the subscript for the ERASE character in the special control
character array. <code><var>termios</var>.c_cc[VERASE]</code> holds the
character itself.
</p>
<p>The ERASE character is recognized only in canonical input mode. When
the user types the erase character, the previous character typed is
discarded. (If the terminal generates multibyte character sequences,
this may cause more than one byte of input to be discarded.) This
cannot be used to erase past the beginning of the current line of text.
The ERASE character itself is discarded.
</p>
<p>Usually, the ERASE character is <DEL>.
</p></dd></dl>
<dl>
<dt><a name="index-VWERASE"></a><u>Macro:</u> int <b>VWERASE</b></dt>
<dd><a name="index-WERASE-character"></a>
<p>This is the subscript for the WERASE character in the special control
character array. <code><var>termios</var>.c_cc[VWERASE]</code> holds the character
itself.
</p>
<p>The WERASE character is recognized only in canonical mode. It erases an
entire word of prior input, and any whitespace after it; whitespace
characters before the word are not erased.
</p>
<p>The definition of a “word” depends on the setting of the
<code>ALTWERASE</code> mode; see section <a href="#Local-Modes">Local Modes</a>.
</p>
<p>If the <code>ALTWERASE</code> mode is not set, a word is defined as a sequence
of any characters except space or tab.
</p>
<p>If the <code>ALTWERASE</code> mode is set, a word is defined as a sequence of
characters containing only letters, numbers, and underscores, optionally
followed by one character that is not a letter, number, or underscore.
</p>
<p>The WERASE character is usually <kbd>C-w</kbd>.
</p>
<p>This is a BSD extension.
</p></dd></dl>
<dl>
<dt><a name="index-VKILL"></a><u>Macro:</u> int <b>VKILL</b></dt>
<dd><a name="index-KILL-character"></a>
<p>This is the subscript for the KILL character in the special control
character array. <code><var>termios</var>.c_cc[VKILL]</code> holds the character
itself.
</p>
<p>The KILL character is recognized only in canonical input mode. When the
user types the kill character, the entire contents of the current line
of input are discarded. The kill character itself is discarded too.
</p>
<p>The KILL character is usually <kbd>C-u</kbd>.
</p></dd></dl>
<dl>
<dt><a name="index-VREPRINT"></a><u>Macro:</u> int <b>VREPRINT</b></dt>
<dd><a name="index-REPRINT-character"></a>
<p>This is the subscript for the REPRINT character in the special control
character array. <code><var>termios</var>.c_cc[VREPRINT]</code> holds the character
itself.
</p>
<p>The REPRINT character is recognized only in canonical mode. It reprints
the current input line. If some asynchronous output has come while you
are typing, this lets you see the line you are typing clearly again.
</p>
<p>The REPRINT character is usually <kbd>C-r</kbd>.
</p>
<p>This is a BSD extension.
</p></dd></dl>
<hr size="6">
<a name="Signal-Characters"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Editing-Characters" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Start_002fStop-Characters" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Special-Characters" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Characters-that-Cause-Signals"></a>
<h4 class="subsubsection">17.4.9.2 Characters that Cause Signals</h4>
<p>These special characters may be active in either canonical or noncanonical
input mode, but only when the <code>ISIG</code> flag is set (see section <a href="#Local-Modes">Local Modes</a>).
</p>
<dl>
<dt><a name="index-VINTR"></a><u>Macro:</u> int <b>VINTR</b></dt>
<dd><a name="index-INTR-character"></a>
<a name="index-interrupt-character"></a>
<p>This is the subscript for the INTR character in the special control
character array. <code><var>termios</var>.c_cc[VINTR]</code> holds the character
itself.
</p>
<p>The INTR (interrupt) character raises a <code>SIGINT</code> signal for all
processes in the foreground job associated with the terminal. The INTR
character itself is then discarded. See section <a href="libc_24.html#Signal-Handling">Signal Handling</a>, for more
information about signals.
</p>
<p>Typically, the INTR character is <kbd>C-c</kbd>.
</p></dd></dl>
<dl>
<dt><a name="index-VQUIT"></a><u>Macro:</u> int <b>VQUIT</b></dt>
<dd><a name="index-QUIT-character"></a>
<p>This is the subscript for the QUIT character in the special control
character array. <code><var>termios</var>.c_cc[VQUIT]</code> holds the character
itself.
</p>
<p>The QUIT character raises a <code>SIGQUIT</code> signal for all processes in
the foreground job associated with the terminal. The QUIT character
itself is then discarded. See section <a href="libc_24.html#Signal-Handling">Signal Handling</a>, for more information
about signals.
</p>
<p>Typically, the QUIT character is <kbd>C-\</kbd>.
</p></dd></dl>
<dl>
<dt><a name="index-VSUSP"></a><u>Macro:</u> int <b>VSUSP</b></dt>
<dd><a name="index-SUSP-character"></a>
<a name="index-suspend-character"></a>
<p>This is the subscript for the SUSP character in the special control
character array. <code><var>termios</var>.c_cc[VSUSP]</code> holds the character
itself.
</p>
<p>The SUSP (suspend) character is recognized only if the implementation
supports job control (see section <a href="libc_27.html#Job-Control">Job Control</a>). It causes a <code>SIGTSTP</code>
signal to be sent to all processes in the foreground job associated with
the terminal. The SUSP character itself is then discarded.
See section <a href="libc_24.html#Signal-Handling">Signal Handling</a>, for more information about signals.
</p>
<p>Typically, the SUSP character is <kbd>C-z</kbd>.
</p></dd></dl>
<p>Few applications disable the normal interpretation of the SUSP
character. If your program does this, it should provide some other
mechanism for the user to stop the job. When the user invokes this
mechanism, the program should send a <code>SIGTSTP</code> signal to the
process group of the process, not just to the process itself.
See section <a href="libc_24.html#Signaling-Another-Process">Signaling Another Process</a>.
</p>
<dl>
<dt><a name="index-VDSUSP"></a><u>Macro:</u> int <b>VDSUSP</b></dt>
<dd><a name="index-DSUSP-character"></a>
<a name="index-delayed-suspend-character"></a>
<p>This is the subscript for the DSUSP character in the special control
character array. <code><var>termios</var>.c_cc[VDSUSP]</code> holds the character
itself.
</p>
<p>The DSUSP (suspend) character is recognized only if the implementation
supports job control (see section <a href="libc_27.html#Job-Control">Job Control</a>). It sends a <code>SIGTSTP</code>
signal, like the SUSP character, but not right away—only when the
program tries to read it as input. Not all systems with job control
support DSUSP; only BSD-compatible systems (including the GNU system).
</p>
<p>See section <a href="libc_24.html#Signal-Handling">Signal Handling</a>, for more information about signals.
</p>
<p>Typically, the DSUSP character is <kbd>C-y</kbd>.
</p></dd></dl>
<hr size="6">
<a name="Start_002fStop-Characters"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Signal-Characters" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Other-Special" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Special-Characters" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Special-Characters-for-Flow-Control"></a>
<h4 class="subsubsection">17.4.9.3 Special Characters for Flow Control</h4>
<p>These special characters may be active in either canonical or noncanonical
input mode, but their use is controlled by the flags <code>IXON</code> and
<code>IXOFF</code> (see section <a href="#Input-Modes">Input Modes</a>).
</p>
<dl>
<dt><a name="index-VSTART"></a><u>Macro:</u> int <b>VSTART</b></dt>
<dd><a name="index-START-character"></a>
<p>This is the subscript for the START character in the special control
character array. <code><var>termios</var>.c_cc[VSTART]</code> holds the
character itself.
</p>
<p>The START character is used to support the <code>IXON</code> and <code>IXOFF</code>
input modes. If <code>IXON</code> is set, receiving a START character resumes
suspended output; the START character itself is discarded. If
<code>IXANY</code> is set, receiving any character at all resumes suspended
output; the resuming character is not discarded unless it is the START
character. <code>IXOFF</code> is set, the system may also transmit START
characters to the terminal.
</p>
<p>The usual value for the START character is <kbd>C-q</kbd>. You may not be
able to change this value—the hardware may insist on using <kbd>C-q</kbd>
regardless of what you specify.
</p></dd></dl>
<dl>
<dt><a name="index-VSTOP"></a><u>Macro:</u> int <b>VSTOP</b></dt>
<dd><a name="index-STOP-character"></a>
<p>This is the subscript for the STOP character in the special control
character array. <code><var>termios</var>.c_cc[VSTOP]</code> holds the character
itself.
</p>
<p>The STOP character is used to support the <code>IXON</code> and <code>IXOFF</code>
input modes. If <code>IXON</code> is set, receiving a STOP character causes
output to be suspended; the STOP character itself is discarded. If
<code>IXOFF</code> is set, the system may also transmit STOP characters to the
terminal, to prevent the input queue from overflowing.
</p>
<p>The usual value for the STOP character is <kbd>C-s</kbd>. You may not be
able to change this value—the hardware may insist on using <kbd>C-s</kbd>
regardless of what you specify.
</p></dd></dl>
<hr size="6">
<a name="Other-Special"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Start_002fStop-Characters" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Noncanonical-Input" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Special-Characters" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Other-Special-Characters"></a>
<h4 class="subsubsection">17.4.9.4 Other Special Characters</h4>
<p>These special characters exist only in BSD systems and the GNU system.
</p>
<dl>
<dt><a name="index-VLNEXT"></a><u>Macro:</u> int <b>VLNEXT</b></dt>
<dd><a name="index-LNEXT-character"></a>
<p>This is the subscript for the LNEXT character in the special control
character array. <code><var>termios</var>.c_cc[VLNEXT]</code> holds the character
itself.
</p>
<p>The LNEXT character is recognized only when <code>IEXTEN</code> is set, but in
both canonical and noncanonical mode. It disables any special
significance of the next character the user types. Even if the
character would normally perform some editing function or generate a
signal, it is read as a plain character. This is the analogue of the
<kbd>C-q</kbd> command in Emacs. “LNEXT” stands for “literal next.”
</p>
<p>The LNEXT character is usually <kbd>C-v</kbd>.
</p></dd></dl>
<dl>
<dt><a name="index-VDISCARD"></a><u>Macro:</u> int <b>VDISCARD</b></dt>
<dd><a name="index-DISCARD-character"></a>
<p>This is the subscript for the DISCARD character in the special control
character array. <code><var>termios</var>.c_cc[VDISCARD]</code> holds the character
itself.
</p>
<p>The DISCARD character is recognized only when <code>IEXTEN</code> is set, but
in both canonical and noncanonical mode. Its effect is to toggle the
discard-output flag. When this flag is set, all program output is
discarded. Setting the flag also discards all output currently in the
output buffer. Typing any other character resets the flag.
</p></dd></dl>
<dl>
<dt><a name="index-VSTATUS"></a><u>Macro:</u> int <b>VSTATUS</b></dt>
<dd><a name="index-STATUS-character"></a>
<p>This is the subscript for the STATUS character in the special control
character array. <code><var>termios</var>.c_cc[VSTATUS]</code> holds the character
itself.
</p>
<p>The STATUS character’s effect is to print out a status message about how
the current process is running.
</p>
<p>The STATUS character is recognized only in canonical mode, and only if
<code>NOKERNINFO</code> is not set.
</p></dd></dl>
<hr size="6">
<a name="Noncanonical-Input"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Other-Special" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#BSD-Terminal-Modes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Terminal-Modes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Noncanonical-Input-1"></a>
<h3 class="subsection">17.4.10 Noncanonical Input</h3>
<p>In noncanonical input mode, the special editing characters such as
ERASE and KILL are ignored. The system facilities for the user to edit
input are disabled in noncanonical mode, so that all input characters
(unless they are special for signal or flow-control purposes) are passed
to the application program exactly as typed. It is up to the
application program to give the user ways to edit the input, if
appropriate.
</p>
<p>Noncanonical mode offers special parameters called MIN and TIME for
controlling whether and how long to wait for input to be available. You
can even use them to avoid ever waiting—to return immediately with
whatever input is available, or with no input.
</p>
<p>The MIN and TIME are stored in elements of the <code>c_cc</code> array, which
is a member of the <code>struct termios</code> structure. Each element of
this array has a particular role, and each element has a symbolic
constant that stands for the index of that element. <code>VMIN</code> and
<code>VMAX</code> are the names for the indices in the array of the MIN and
TIME slots.
</p>
<dl>
<dt><a name="index-VMIN"></a><u>Macro:</u> int <b>VMIN</b></dt>
<dd><a name="index-MIN-termios-slot"></a>
<p>This is the subscript for the MIN slot in the <code>c_cc</code> array. Thus,
<code><var>termios</var>.c_cc[VMIN]</code> is the value itself.
</p>
<p>The MIN slot is only meaningful in noncanonical input mode; it
specifies the minimum number of bytes that must be available in the
input queue in order for <code>read</code> to return.
</p></dd></dl>
<dl>
<dt><a name="index-VTIME"></a><u>Macro:</u> int <b>VTIME</b></dt>
<dd><a name="index-TIME-termios-slot"></a>
<p>This is the subscript for the TIME slot in the <code>c_cc</code> array. Thus,
<code><var>termios</var>.c_cc[VTIME]</code> is the value itself.
</p>
<p>The TIME slot is only meaningful in noncanonical input mode; it
specifies how long to wait for input before returning, in units of 0.1
seconds.
</p></dd></dl>
<p>The MIN and TIME values interact to determine the criterion for when
<code>read</code> should return; their precise meanings depend on which of
them are nonzero. There are four possible cases:
</p>
<ul>
<li>
Both TIME and MIN are nonzero.
<p>In this case, TIME specifies how long to wait after each input character
to see if more input arrives. After the first character received,
<code>read</code> keeps waiting until either MIN bytes have arrived in all, or
TIME elapses with no further input.
</p>
<p><code>read</code> always blocks until the first character arrives, even if
TIME elapses first. <code>read</code> can return more than MIN characters if
more than MIN happen to be in the queue.
</p>
</li><li>
Both MIN and TIME are zero.
<p>In this case, <code>read</code> always returns immediately with as many
characters as are available in the queue, up to the number requested.
If no input is immediately available, <code>read</code> returns a value of
zero.
</p>
</li><li>
MIN is zero but TIME has a nonzero value.
<p>In this case, <code>read</code> waits for time TIME for input to become
available; the availability of a single byte is enough to satisfy the
read request and cause <code>read</code> to return. When it returns, it
returns as many characters as are available, up to the number requested.
If no input is available before the timer expires, <code>read</code> returns a
value of zero.
</p>
</li><li>
TIME is zero but MIN has a nonzero value.
<p>In this case, <code>read</code> waits until at least MIN bytes are available
in the queue. At that time, <code>read</code> returns as many characters as
are available, up to the number requested. <code>read</code> can return more
than MIN characters if more than MIN happen to be in the queue.
</p></li></ul>
<p>What happens if MIN is 50 and you ask to read just 10 bytes?
Normally, <code>read</code> waits until there are 50 bytes in the buffer (or,
more generally, the wait condition described above is satisfied), and
then reads 10 of them, leaving the other 40 buffered in the operating
system for a subsequent call to <code>read</code>.
</p>
<p><strong>Portability note:</strong> On some systems, the MIN and TIME slots are
actually the same as the EOF and EOL slots. This causes no serious
problem because the MIN and TIME slots are used only in noncanonical
input and the EOF and EOL slots are used only in canonical input, but it
isn’t very clean. The GNU library allocates separate slots for these
uses.
</p>
<dl>
<dt><a name="index-cfmakeraw"></a><u>Function:</u> void <b>cfmakeraw</b><i> (struct termios *<var>termios-p</var>)</i></dt>
<dd><p>This function provides an easy way to set up <code>*<var>termios-p</var></code> for
what has traditionally been called “raw mode” in BSD. This uses
noncanonical input, and turns off most processing to give an unmodified
channel to the terminal.
</p>
<p>It does exactly this:
</p><table><tr><td> </td><td><pre class="smallexample"> <var>termios-p</var>->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
|INLCR|IGNCR|ICRNL|IXON);
<var>termios-p</var>->c_oflag &= ~OPOST;
<var>termios-p</var>->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
<var>termios-p</var>->c_cflag &= ~(CSIZE|PARENB);
<var>termios-p</var>->c_cflag |= CS8;
</pre></td></tr></table>
</dd></dl>
<hr size="6">
<a name="BSD-Terminal-Modes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Noncanonical-Input" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Line-Control" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="BSD-Terminal-Modes-1"></a>
<h2 class="section">17.5 BSD Terminal Modes</h2>
<a name="index-terminal-modes_002c-BSD"></a>
<p>The usual way to get and set terminal modes is with the functions described
in <a href="#Terminal-Modes">Terminal Modes</a>. However, on some systems you can use the
BSD-derived functions in this section to do some of the same thing. On
many systems, these functions do not exist. Even with the GNU C library,
the functions simply fail with <code>errno</code> = <code>ENOSYS</code> with many
kernels, including Linux.
</p>
<p>The symbols used in this section are declared in ‘<tt>sgtty.h</tt>’.
</p>
<dl>
<dt><a name="index-struct-sgttyb"></a><u>Data Type:</u> <b>struct sgttyb</b></dt>
<dd><p>This structure is an input or output parameter list for <code>gtty</code> and
<code>stty</code>.
</p>
<dl compact="compact">
<dt> <code>char sg_ispeed</code></dt>
<dd><p>Line speed for input
</p></dd>
<dt> <code>char sg_ospeed</code></dt>
<dd><p>Line speed for output
</p></dd>
<dt> <code>char sg_erase</code></dt>
<dd><p>Erase character
</p></dd>
<dt> <code>char sg_kill</code></dt>
<dd><p>Kill character
</p></dd>
<dt> <code>int sg_flags</code></dt>
<dd><p>Various flags
</p></dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-gtty"></a><u>Function:</u> int <b>gtty</b><i> (int <var>filedes</var>, struct sgttyb *<var>attributes</var>)</i></dt>
<dd><p>This function gets the attributes of a terminal.
</p>
<p><code>gtty</code> sets *<var>attributes</var> to describe the terminal attributes
of the terminal which is open with file descriptor <var>filedes</var>.
</p></dd></dl>
<dl>
<dt><a name="index-stty"></a><u>Function:</u> int <b>stty</b><i> (int <var>filedes</var>, struct sgttyb * attributes)</i></dt>
<dd>
<p>This function sets the attributes of a terminal.
</p>
<p><code>stty</code> sets the terminal attributes of the terminal which is open with
file descriptor <var>filedes</var> to those described by *<var>filedes</var>.
</p></dd></dl>
<hr size="6">
<a name="Line-Control"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#BSD-Terminal-Modes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Noncanon-Example" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Line-Control-Functions"></a>
<h2 class="section">17.6 Line Control Functions</h2>
<a name="index-terminal-line-control-functions"></a>
<p>These functions perform miscellaneous control actions on terminal
devices. As regards terminal access, they are treated like doing
output: if any of these functions is used by a background process on its
controlling terminal, normally all processes in the process group are
sent a <code>SIGTTOU</code> signal. The exception is if the calling process
itself is ignoring or blocking <code>SIGTTOU</code> signals, in which case the
operation is performed and no signal is sent. See section <a href="libc_27.html#Job-Control">Job Control</a>.
</p>
<a name="index-break-condition_002c-generating"></a>
<dl>
<dt><a name="index-tcsendbreak"></a><u>Function:</u> int <b>tcsendbreak</b><i> (int <var>filedes</var>, int <var>duration</var>)</i></dt>
<dd><p>This function generates a break condition by transmitting a stream of
zero bits on the terminal associated with the file descriptor
<var>filedes</var>. The duration of the break is controlled by the
<var>duration</var> argument. If zero, the duration is between 0.25 and 0.5
seconds. The meaning of a nonzero value depends on the operating system.
</p>
<p>This function does nothing if the terminal is not an asynchronous serial
data port.
</p>
<p>The return value is normally zero. In the event of an error, a value
of <em>-1</em> is returned. The following <code>errno</code> error conditions
are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> is not a valid file descriptor.
</p>
</dd>
<dt> <code>ENOTTY</code></dt>
<dd><p>The <var>filedes</var> is not associated with a terminal device.
</p></dd>
</dl>
</dd></dl>
<a name="index-flushing-terminal-output-queue"></a>
<a name="index-terminal-output-queue_002c-flushing"></a>
<dl>
<dt><a name="index-tcdrain"></a><u>Function:</u> int <b>tcdrain</b><i> (int <var>filedes</var>)</i></dt>
<dd><p>The <code>tcdrain</code> function waits until all queued
output to the terminal <var>filedes</var> has been transmitted.
</p>
<p>This function is a cancellation point in multi-threaded programs. This
is a problem if the thread allocates some resources (like memory, file
descriptors, semaphores or whatever) at the time <code>tcdrain</code> is
called. If the thread gets canceled these resources stay allocated
until the program ends. To avoid this calls to <code>tcdrain</code> should be
protected using cancellation handlers.
</p>
<p>The return value is normally zero. In the event of an error, a value
of <em>-1</em> is returned. The following <code>errno</code> error conditions
are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> is not a valid file descriptor.
</p>
</dd>
<dt> <code>ENOTTY</code></dt>
<dd><p>The <var>filedes</var> is not associated with a terminal device.
</p>
</dd>
<dt> <code>EINTR</code></dt>
<dd><p>The operation was interrupted by delivery of a signal.
See section <a href="libc_24.html#Interrupted-Primitives">Primitives Interrupted by Signals</a>.
</p></dd>
</dl>
</dd></dl>
<a name="index-clearing-terminal-input-queue"></a>
<a name="index-terminal-input-queue_002c-clearing"></a>
<dl>
<dt><a name="index-tcflush"></a><u>Function:</u> int <b>tcflush</b><i> (int <var>filedes</var>, int <var>queue</var>)</i></dt>
<dd><p>The <code>tcflush</code> function is used to clear the input and/or output
queues associated with the terminal file <var>filedes</var>. The <var>queue</var>
argument specifies which queue(s) to clear, and can be one of the
following values:
</p>
<dl compact="compact">
<dd><a name="index-TCIFLUSH"></a>
</dd>
<dt> <code>TCIFLUSH</code></dt>
<dd>
<p>Clear any input data received, but not yet read.
</p>
<a name="index-TCOFLUSH"></a>
</dd>
<dt> <code>TCOFLUSH</code></dt>
<dd>
<p>Clear any output data written, but not yet transmitted.
</p>
<a name="index-TCIOFLUSH"></a>
</dd>
<dt> <code>TCIOFLUSH</code></dt>
<dd>
<p>Clear both queued input and output.
</p></dd>
</dl>
<p>The return value is normally zero. In the event of an error, a value
of <em>-1</em> is returned. The following <code>errno</code> error conditions
are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> is not a valid file descriptor.
</p>
</dd>
<dt> <code>ENOTTY</code></dt>
<dd><p>The <var>filedes</var> is not associated with a terminal device.
</p>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p>A bad value was supplied as the <var>queue</var> argument.
</p></dd>
</dl>
<p>It is unfortunate that this function is named <code>tcflush</code>, because
the term “flush” is normally used for quite another operation—waiting
until all output is transmitted—and using it for discarding input or
output would be confusing. Unfortunately, the name <code>tcflush</code> comes
from POSIX and we cannot change it.
</p></dd></dl>
<a name="index-flow-control_002c-terminal"></a>
<a name="index-terminal-flow-control"></a>
<dl>
<dt><a name="index-tcflow"></a><u>Function:</u> int <b>tcflow</b><i> (int <var>filedes</var>, int <var>action</var>)</i></dt>
<dd><p>The <code>tcflow</code> function is used to perform operations relating to
XON/XOFF flow control on the terminal file specified by <var>filedes</var>.
</p>
<p>The <var>action</var> argument specifies what operation to perform, and can
be one of the following values:
</p>
<dl compact="compact">
<dd><a name="index-TCOOFF"></a>
</dd>
<dt> <code>TCOOFF</code></dt>
<dd><p>Suspend transmission of output.
</p>
<a name="index-TCOON"></a>
</dd>
<dt> <code>TCOON</code></dt>
<dd><p>Restart transmission of output.
</p>
<a name="index-TCIOFF"></a>
</dd>
<dt> <code>TCIOFF</code></dt>
<dd><p>Transmit a STOP character.
</p>
<a name="index-TCION"></a>
</dd>
<dt> <code>TCION</code></dt>
<dd><p>Transmit a START character.
</p></dd>
</dl>
<p>For more information about the STOP and START characters, see <a href="#Special-Characters">Special Characters</a>.
</p>
<p>The return value is normally zero. In the event of an error, a value
of <em>-1</em> is returned. The following <code>errno</code> error conditions
are defined for this function:
</p>
<dl compact="compact">
<dd><a name="index-EBADF-1"></a>
</dd>
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> is not a valid file descriptor.
</p>
<a name="index-ENOTTY-1"></a>
</dd>
<dt> <code>ENOTTY</code></dt>
<dd><p>The <var>filedes</var> is not associated with a terminal device.
</p>
<a name="index-EINVAL-1"></a>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p>A bad value was supplied as the <var>action</var> argument.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="Noncanon-Example"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Line-Control" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Pseudo_002dTerminals" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Noncanonical-Mode-Example"></a>
<h2 class="section">17.7 Noncanonical Mode Example</h2>
<p>Here is an example program that shows how you can set up a terminal
device to read single characters in noncanonical input mode, without
echo.
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <termios.h>
/* <span class="roman">Use this variable to remember original terminal attributes.</span> */
struct termios saved_attributes;
void
reset_input_mode (void)
{
tcsetattr (STDIN_FILENO, TCSANOW, &saved_attributes);
}
void
set_input_mode (void)
{
struct termios tattr;
char *name;
/* <span class="roman">Make sure stdin is a terminal.</span> */
if (!isatty (STDIN_FILENO))
{
fprintf (stderr, "Not a terminal.\n");
exit (EXIT_FAILURE);
}
/* <span class="roman">Save the terminal attributes so we can restore them later.</span> */
tcgetattr (STDIN_FILENO, &saved_attributes);
atexit (reset_input_mode);
</pre><pre class="smallexample"> /* <span class="roman">Set the funny terminal modes.</span> */
tcgetattr (STDIN_FILENO, &tattr);
tattr.c_lflag &= ~(ICANON|ECHO); /* <span class="roman">Clear ICANON and ECHO.</span> */
tattr.c_cc[VMIN] = 1;
tattr.c_cc[VTIME] = 0;
tcsetattr (STDIN_FILENO, TCSAFLUSH, &tattr);
}
</pre><pre class="smallexample">
int
main (void)
{
char c;
set_input_mode ();
while (1)
{
read (STDIN_FILENO, &c, 1);
if (c == '\004') /* <span class="roman"><kbd>C-d</kbd></span> */
break;
else
putchar (c);
}
return EXIT_SUCCESS;
}
</pre></td></tr></table>
<p>This program is careful to restore the original terminal modes before
exiting or terminating with a signal. It uses the <code>atexit</code>
function (see section <a href="libc_25.html#Cleanups-on-Exit">Cleanups on Exit</a>) to make sure this is done
by <code>exit</code>.
</p>
<p>The shell is supposed to take care of resetting the terminal modes when
a process is stopped or continued; see <a href="libc_27.html#Job-Control">Job Control</a>. But some
existing shells do not actually do this, so you may wish to establish
handlers for job control signals that reset terminal modes. The above
example does so.
</p>
<hr size="6">
<a name="Pseudo_002dTerminals"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Noncanon-Example" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Allocation" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Pseudo_002dTerminals-1"></a>
<h2 class="section">17.8 Pseudo-Terminals</h2>
<a name="index-pseudo_002dterminals"></a>
<p>A <em>pseudo-terminal</em> is a special interprocess communication channel
that acts like a terminal. One end of the channel is called the
<em>master</em> side or <em>master pseudo-terminal device</em>, the other side
is called the <em>slave</em> side. Data written to the master side is
received by the slave side as if it was the result of a user typing at
an ordinary terminal, and data written to the slave side is sent to the
master side as if it was written on an ordinary terminal.
</p>
<p>Pseudo terminals are the way programs like <code>xterm</code> and <code>emacs</code>
implement their terminal emulation functionality.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Allocation">17.8.1 Allocating Pseudo-Terminals</a></td><td> </td><td align="left" valign="top"> Allocating a pseudo terminal.
</td></tr>
<tr><td align="left" valign="top"><a href="#Pseudo_002dTerminal-Pairs">17.8.2 Opening a Pseudo-Terminal Pair</a></td><td> </td><td align="left" valign="top"> How to open both sides of a
pseudo-terminal in a single operation.
</td></tr>
</table>
<hr size="6">
<a name="Allocation"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Pseudo_002dTerminals" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Pseudo_002dTerminal-Pairs" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Pseudo_002dTerminals" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Allocating-Pseudo_002dTerminals"></a>
<h3 class="subsection">17.8.1 Allocating Pseudo-Terminals</h3>
<a name="index-allocating-pseudo_002dterminals"></a>
<a name="index-stdlib_002eh-11"></a>
<p>This subsection describes functions for allocating a pseudo-terminal,
and for making this pseudo-terminal available for actual use. These
functions are declared in the header file ‘<tt>stdlib.h</tt>’.
</p>
<dl>
<dt><a name="index-getpt"></a><u>Function:</u> int <b>getpt</b><i> (void)</i></dt>
<dd><p>The <code>getpt</code> function returns a new file descriptor for the next
available master pseudo-terminal. The normal return value from
<code>getpt</code> is a non-negative integer file descriptor. In the case of
an error, a value of <em>-1</em> is returned instead. The following
<code>errno</code> conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>ENOENT</code></dt>
<dd><p>There are no free master pseudo-terminals available.
</p></dd>
</dl>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-grantpt"></a><u>Function:</u> int <b>grantpt</b><i> (int <var>filedes</var>)</i></dt>
<dd><p>The <code>grantpt</code> function changes the ownership and access permission
of the slave pseudo-terminal device corresponding to the master
pseudo-terminal device associated with the file descriptor
<var>filedes</var>. The owner is set from the real user ID of the calling
process (see section <a href="libc_29.html#Process-Persona">The Persona of a Process</a>), and the group is set to a special
group (typically <em>tty</em>) or from the real group ID of the calling
process. The access permission is set such that the file is both
readable and writable by the owner and only writable by the group.
</p>
<p>On some systems this function is implemented by invoking a special
<code>setuid</code> root program (see section <a href="libc_29.html#How-Change-Persona">How an Application Can Change Persona</a>). As a
consequence, installing a signal handler for the <code>SIGCHLD</code> signal
(see section <a href="libc_24.html#Job-Control-Signals">Job Control Signals</a>) may interfere with a call to
<code>grantpt</code>.
</p>
<p>The normal return value from <code>grantpt</code> is <em>0</em>; a value of
<em>-1</em> is returned in case of failure. The following <code>errno</code>
error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> argument is not a valid file descriptor.
</p>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p>The <var>filedes</var> argument is not associated with a master pseudo-terminal
device.
</p>
</dd>
<dt> <code>EACCES</code></dt>
<dd><p>The slave pseudo-terminal device corresponding to the master associated
with <var>filedes</var> could not be accessed.
</p></dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-unlockpt"></a><u>Function:</u> int <b>unlockpt</b><i> (int <var>filedes</var>)</i></dt>
<dd><p>The <code>unlockpt</code> function unlocks the slave pseudo-terminal device
corresponding to the master pseudo-terminal device associated with the
file descriptor <var>filedes</var>. On many systems, the slave can only be
opened after unlocking, so portable applications should always call
<code>unlockpt</code> before trying to open the slave.
</p>
<p>The normal return value from <code>unlockpt</code> is <em>0</em>; a value of
<em>-1</em> is returned in case of failure. The following <code>errno</code>
error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> argument is not a valid file descriptor.
</p>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p>The <var>filedes</var> argument is not associated with a master pseudo-terminal
device.
</p></dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-ptsname"></a><u>Function:</u> char * <b>ptsname</b><i> (int <var>filedes</var>)</i></dt>
<dd><p>If the file descriptor <var>filedes</var> is associated with a
master pseudo-terminal device, the <code>ptsname</code> function returns a
pointer to a statically-allocated, null-terminated string containing the
file name of the associated slave pseudo-terminal file. This string
might be overwritten by subsequent calls to <code>ptsname</code>.
</p></dd></dl>
<dl>
<dt><a name="index-ptsname_005fr"></a><u>Function:</u> int <b>ptsname_r</b><i> (int <var>filedes</var>, char *<var>buf</var>, size_t <var>len</var>)</i></dt>
<dd><p>The <code>ptsname_r</code> function is similar to the <code>ptsname</code> function
except that it places its result into the user-specified buffer starting
at <var>buf</var> with length <var>len</var>.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<p><strong>Portability Note:</strong> On System V derived systems, the file
returned by the <code>ptsname</code> and <code>ptsname_r</code> functions may be
STREAMS-based, and therefore require additional processing after opening
before it actually behaves as a pseudo terminal.
</p>
<p>Typical usage of these functions is illustrated by the following example:
</p><table><tr><td> </td><td><pre class="smallexample">int
open_pty_pair (int *amaster, int *aslave)
{
int master, slave;
char *name;
master = getpt ();
if (master < 0)
return 0;
if (grantpt (master) < 0 || unlockpt (master) < 0)
goto close_master;
name = ptsname (master);
if (name == NULL)
goto close_master;
slave = open (name, O_RDWR);
if (slave == -1)
goto close_master;
if (isastream (slave))
{
if (ioctl (slave, I_PUSH, "ptem") < 0
|| ioctl (slave, I_PUSH, "ldterm") < 0)
goto close_slave;
}
*amaster = master;
*aslave = slave;
return 1;
close_slave:
close (slave);
close_master:
close (master);
return 0;
}
</pre></td></tr></table>
<hr size="6">
<a name="Pseudo_002dTerminal-Pairs"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Allocation" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Pseudo_002dTerminals" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Opening-a-Pseudo_002dTerminal-Pair"></a>
<h3 class="subsection">17.8.2 Opening a Pseudo-Terminal Pair</h3>
<a name="index-opening-a-pseudo_002dterminal-pair"></a>
<p>These functions, derived from BSD, are available in the separate
‘<tt>libutil</tt>’ library, and declared in ‘<tt>pty.h</tt>’.
</p>
<dl>
<dt><a name="index-openpty"></a><u>Function:</u> int <b>openpty</b><i> (int *<var>amaster</var>, int *<var>aslave</var>, char *<var>name</var>, const struct termios *<var>termp</var>, const struct winsize *<var>winp</var>)</i></dt>
<dd><p>This function allocates and opens a pseudo-terminal pair, returning the
file descriptor for the master in <var>*amaster</var>, and the file
descriptor for the slave in <var>*aslave</var>. If the argument <var>name</var>
is not a null pointer, the file name of the slave pseudo-terminal
device is stored in <code>*name</code>. If <var>termp</var> is not a null pointer,
the terminal attributes of the slave are set to the ones specified in
the structure that <var>termp</var> points to (see section <a href="#Terminal-Modes">Terminal Modes</a>).
Likewise, if the <var>winp</var> is not a null pointer, the screen size of
the slave is set to the values specified in the structure that
<var>winp</var> points to.
</p>
<p>The normal return value from <code>openpty</code> is <em>0</em>; a value of
<em>-1</em> is returned in case of failure. The following <code>errno</code>
conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>ENOENT</code></dt>
<dd><p>There are no free pseudo-terminal pairs available.
</p></dd>
</dl>
<p><strong>Warning:</strong> Using the <code>openpty</code> function with <var>name</var> not
set to <code>NULL</code> is <strong>very dangerous</strong> because it provides no
protection against overflowing the string <var>name</var>. You should use
the <code>ttyname</code> function on the file descriptor returned in
<var>*slave</var> to find out the file name of the slave pseudo-terminal
device instead.
</p></dd></dl>
<dl>
<dt><a name="index-forkpty"></a><u>Function:</u> int <b>forkpty</b><i> (int *<var>amaster</var>, char *<var>name</var>, const struct termios *<var>termp</var>, const struct winsize *<var>winp</var>)</i></dt>
<dd><p>This function is similar to the <code>openpty</code> function, but in
addition, forks a new process (see section <a href="libc_26.html#Creating-a-Process">Creating a Process</a>) and makes the
newly opened slave pseudo-terminal device the controlling terminal
(see section <a href="libc_27.html#Controlling-Terminal">Controlling Terminal of a Process</a>) for the child process.
</p>
<p>If the operation is successful, there are then both parent and child
processes and both see <code>forkpty</code> return, but with different values:
it returns a value of <em>0</em> in the child process and returns the child’s
process ID in the parent process.
</p>
<p>If the allocation of a pseudo-terminal pair or the process creation
failed, <code>forkpty</code> returns a value of <em>-1</em> in the parent
process.
</p>
<p><strong>Warning:</strong> The <code>forkpty</code> function has the same problems with
respect to the <var>name</var> argument as <code>openpty</code>.
</p></dd></dl>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Low_002dLevel-Terminal-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="libc_18.html#Syslog" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated by <em>root</em> on <em>April 20, 2012</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html 1.82</em></a>.
</font>
<br>
</p>
</body>
</html>
|