/usr/share/doc/glibc-doc/html/libc_12.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 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 4865 4866 4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896 4897 4898 4899 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927 4928 4929 4930 4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 4945 4946 4947 4948 4949 4950 4951 4952 4953 4954 4955 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 5014 5015 5016 5017 5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 5033 5034 5035 5036 5037 5038 5039 5040 5041 5042 5043 5044 5045 5046 5047 5048 5049 5050 5051 5052 5053 5054 5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 5082 5083 5084 5085 5086 5087 5088 5089 5090 5091 5092 5093 5094 5095 5096 5097 5098 5099 5100 5101 5102 5103 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5190 5191 5192 5193 5194 5195 5196 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 5341 5342 5343 5344 5345 5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 5356 5357 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 5417 5418 5419 5420 5421 5422 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 5669 5670 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5681 5682 5683 5684 5685 5686 5687 5688 5689 5690 5691 5692 5693 5694 5695 5696 5697 5698 5699 5700 5701 5702 5703 5704 5705 5706 5707 5708 5709 5710 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 5731 5732 5733 5734 5735 5736 5737 5738 5739 5740 5741 5742 5743 5744 5745 5746 5747 5748 5749 5750 5751 5752 5753 5754 5755 5756 5757 5758 5759 5760 5761 5762 5763 5764 5765 5766 5767 5768 5769 5770 5771 5772 5773 5774 5775 5776 5777 5778 5779 5780 5781 5782 5783 5784 5785 5786 5787 5788 5789 5790 5791 5792 5793 5794 5795 5796 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 5809 5810 5811 5812 5813 5814 5815 5816 5817 5818 5819 5820 5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5832 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 5862 5863 5864 5865 5866 5867 5868 5869 5870 5871 5872 5873 5874 5875 5876 5877 5878 5879 5880 5881 5882 5883 5884 5885 5886 5887 5888 5889 5890 5891 5892 5893 5894 5895 5896 5897 5898 5899 5900 5901 5902 5903 5904 5905 5906 5907 5908 5909 5910 5911 5912 5913 5914 5915 5916 5917 5918 5919 5920 5921 5922 5923 5924 5925 5926 5927 5928 5929 5930 5931 5932 5933 5934 5935 5936 5937 5938 5939 5940 5941 5942 5943 5944 5945 5946 5947 5948 5949 5950 5951 5952 5953 5954 5955 5956 5957 5958 5959 5960 5961 5962 5963 5964 5965 5966 5967 5968 5969 5970 5971 5972 5973 5974 5975 5976 5977 5978 5979 5980 5981 5982 5983 5984 5985 5986 5987 5988 5989 5990 5991 5992 5993 5994 5995 5996 5997 5998 5999 6000 6001 6002 6003 6004 6005 6006 6007 6008 6009 6010 6011 6012 6013 6014 6015 6016 6017 6018 6019 6020 6021 6022 6023 6024 6025 6026 6027 6028 6029 6030 6031 6032 6033 6034 6035 6036 6037 6038 6039 6040 6041 6042 6043 6044 6045 6046 6047 6048 6049 6050 6051 6052 6053 6054 6055 6056 6057 6058 6059 6060 6061 6062 6063 6064 6065 6066 6067 6068 6069 6070 6071 6072 6073 6074 6075 6076 6077 6078 6079 6080 6081 6082 6083 6084 6085 6086 6087 6088 6089 6090 6091 6092 6093 6094 6095 6096 6097 6098 6099 6100 6101 6102 6103 6104 6105 6106 6107 6108 6109 6110 6111 6112 6113 6114 6115 6116 6117 6118 6119 6120 6121 6122 6123 6124 6125 6126 6127 6128 6129 6130 6131 6132 6133 6134 6135 6136 6137 6138 6139 6140 6141 6142 6143 6144 6145 6146 6147 6148 6149 6150 6151 6152 6153 6154 6155 6156 6157 6158 6159 6160 6161 6162 6163 6164 6165 6166 6167 6168 6169 6170 6171 6172 6173 6174 6175 6176 6177 6178 6179 6180 6181 6182 6183 6184 6185 6186 6187 6188 6189 6190 6191 6192 6193 6194 6195 6196 6197 6198 6199 6200 6201 6202 6203 6204 6205 6206 6207 6208 6209 6210 6211 6212 6213 6214 6215 6216 6217 6218 6219 6220 6221 6222 6223 6224 6225 6226 6227 6228 6229 6230 6231 6232 6233 6234 6235 6236 6237 6238 6239 6240 6241 6242 6243 6244 6245 6246 6247 6248 6249 6250 6251 6252 6253 6254 6255 6256 6257 6258 6259 6260 6261 6262 6263 6264 6265 6266 6267 6268 6269 6270 6271 6272 6273 6274 6275 6276 6277 6278 6279 6280 6281 6282 6283 6284 6285 6286 6287 6288 6289 6290 6291 6292 6293 6294 6295 6296 6297 6298 6299 6300 6301 6302 6303 6304 6305 6306 6307 6308 6309 6310 6311 6312 6313 6314 6315 6316 6317 6318 6319 6320 6321 6322 6323 6324 6325 6326 6327 6328 6329 6330 6331 6332 6333 6334 6335 6336 6337 6338 6339 6340 6341 6342 6343 6344 6345 6346 6347 6348 6349 6350 6351 6352 6353 6354 6355 6356 6357 6358 6359 6360 6361 6362 6363 6364 6365 6366 6367 6368 6369 6370 6371 6372 6373 6374 6375 6376 6377 6378 6379 6380 6381 6382 6383 6384 6385 6386 6387 6388 6389 6390 6391 6392 6393 6394 6395 6396 6397 6398 6399 6400 6401 6402 6403 6404 6405 6406 6407 6408 6409 6410 6411 6412 6413 6414 6415 6416 6417 6418 6419 6420 6421 6422 6423 6424 6425 6426 6427 6428 6429 6430 6431 6432 6433 6434 6435 6436 6437 6438 6439 6440 6441 6442 6443 6444 6445 6446 6447 6448 6449 6450 6451 6452 6453 6454 6455 6456 6457 6458 6459 6460 6461 6462 6463 6464 6465 6466 6467 6468 6469 6470 6471 6472 6473 6474 6475 6476 6477 6478 6479 6480 6481 6482 6483 6484 6485 6486 6487 6488 6489 6490 6491 6492 6493 6494 6495 6496 6497 6498 6499 6500 6501 6502 6503 6504 6505 6506 6507 6508 6509 6510 6511 6512 6513 6514 6515 6516 6517 6518 6519 6520 6521 6522 6523 6524 6525 6526 | <!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: 12. Input/Output on Streams</title>
<meta name="description" content="The GNU C Library: 12. Input/Output on Streams">
<meta name="keywords" content="The GNU C Library: 12. Input/Output on Streams">
<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="I_002fO-on-Streams"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="libc_11.html#File-Name-Portability" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Streams" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc_11.html#I_002fO-Overview" 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_13.html#Low_002dLevel-I_002fO" 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_002fOutput-on-Streams"></a>
<h1 class="chapter">12. Input/Output on Streams</h1>
<p>This chapter describes the functions for creating streams and performing
input and output operations on them. As discussed in <a href="libc_11.html#I_002fO-Overview">Input/Output Overview</a>, a stream is a fairly abstract, high-level concept
representing a communications channel to a file, device, or process.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Streams">12.1 Streams</a></td><td> </td><td align="left" valign="top"> About the data type representing a stream.
</td></tr>
<tr><td align="left" valign="top"><a href="#Standard-Streams">12.2 Standard Streams</a></td><td> </td><td align="left" valign="top"> Streams to the standard input and output
devices are created for you.
</td></tr>
<tr><td align="left" valign="top"><a href="#Opening-Streams">12.3 Opening Streams</a></td><td> </td><td align="left" valign="top"> How to create a stream to talk to a file.
</td></tr>
<tr><td align="left" valign="top"><a href="#Closing-Streams">12.4 Closing Streams</a></td><td> </td><td align="left" valign="top"> Close a stream when you are finished with it.
</td></tr>
<tr><td align="left" valign="top"><a href="#Streams-and-Threads">12.5 Streams and Threads</a></td><td> </td><td align="left" valign="top"> Issues with streams in threaded programs.
</td></tr>
<tr><td align="left" valign="top"><a href="#Streams-and-I18N">12.6 Streams in Internationalized Applications</a></td><td> </td><td align="left" valign="top"> Streams in internationalized applications.
</td></tr>
<tr><td align="left" valign="top"><a href="#Simple-Output">12.7 Simple Output by Characters or Lines</a></td><td> </td><td align="left" valign="top"> Unformatted output by characters and lines.
</td></tr>
<tr><td align="left" valign="top"><a href="#Character-Input">12.8 Character Input</a></td><td> </td><td align="left" valign="top"> Unformatted input by characters and words.
</td></tr>
<tr><td align="left" valign="top"><a href="#Line-Input">12.9 Line-Oriented Input</a></td><td> </td><td align="left" valign="top"> Reading a line or a record from a stream.
</td></tr>
<tr><td align="left" valign="top"><a href="#Unreading">12.10 Unreading</a></td><td> </td><td align="left" valign="top"> Peeking ahead/pushing back input just read.
</td></tr>
<tr><td align="left" valign="top"><a href="#Block-Input_002fOutput">12.11 Block Input/Output</a></td><td> </td><td align="left" valign="top"> Input and output operations on blocks of data.
</td></tr>
<tr><td align="left" valign="top"><a href="#Formatted-Output">12.12 Formatted Output</a></td><td> </td><td align="left" valign="top"> <code>printf</code> and related functions.
</td></tr>
<tr><td align="left" valign="top"><a href="#Customizing-Printf">12.13 Customizing <code>printf</code></a></td><td> </td><td align="left" valign="top"> You can define new conversion specifiers for
<code>printf</code> and friends.
</td></tr>
<tr><td align="left" valign="top"><a href="#Formatted-Input">12.14 Formatted Input</a></td><td> </td><td align="left" valign="top"> <code>scanf</code> and related functions.
</td></tr>
<tr><td align="left" valign="top"><a href="#EOF-and-Errors">12.15 End-Of-File and Errors</a></td><td> </td><td align="left" valign="top"> How you can tell if an I/O error happens.
</td></tr>
<tr><td align="left" valign="top"><a href="#Error-Recovery">12.16 Recovering from errors</a></td><td> </td><td align="left" valign="top"> What you can do about errors.
</td></tr>
<tr><td align="left" valign="top"><a href="#Binary-Streams">12.17 Text and Binary Streams</a></td><td> </td><td align="left" valign="top"> Some systems distinguish between text files
and binary files.
</td></tr>
<tr><td align="left" valign="top"><a href="#File-Positioning">12.18 File Positioning</a></td><td> </td><td align="left" valign="top"> About random-access streams.
</td></tr>
<tr><td align="left" valign="top"><a href="#Portable-Positioning">12.19 Portable File-Position Functions</a></td><td> </td><td align="left" valign="top"> Random access on peculiar ISO C systems.
</td></tr>
<tr><td align="left" valign="top"><a href="#Stream-Buffering">12.20 Stream Buffering</a></td><td> </td><td align="left" valign="top"> How to control buffering of streams.
</td></tr>
<tr><td align="left" valign="top"><a href="#Other-Kinds-of-Streams">12.21 Other Kinds of Streams</a></td><td> </td><td align="left" valign="top"> Streams that do not necessarily correspond
to an open file.
</td></tr>
<tr><td align="left" valign="top"><a href="#Formatted-Messages">12.22 Formatted Messages</a></td><td> </td><td align="left" valign="top"> Print strictly formatted messages.
</td></tr>
</table>
<hr size="6">
<a name="Streams"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Standard-Streams" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Streams-1"></a>
<h2 class="section">12.1 Streams</h2>
<p>For historical reasons, the type of the C data structure that represents
a stream is called <code>FILE</code> rather than “stream”. Since most of
the library functions deal with objects of type <code>FILE *</code>, sometimes
the term <em>file pointer</em> is also used to mean “stream”. This leads
to unfortunate confusion over terminology in many books on C. This
manual, however, is careful to use the terms “file” and “stream”
only in the technical sense.
<a name="index-file-pointer"></a>
</p>
<a name="index-stdio_002eh"></a>
<p>The <code>FILE</code> type is declared in the header file ‘<tt>stdio.h</tt>’.
</p>
<dl>
<dt><a name="index-FILE"></a><u>Data Type:</u> <b>FILE</b></dt>
<dd><p>This is the data type used to represent stream objects. A <code>FILE</code>
object holds all of the internal state information about the connection
to the associated file, including such things as the file position
indicator and buffering information. Each stream also has error and
end-of-file status indicators that can be tested with the <code>ferror</code>
and <code>feof</code> functions; see <a href="#EOF-and-Errors">End-Of-File and Errors</a>.
</p></dd></dl>
<p><code>FILE</code> objects are allocated and managed internally by the
input/output library functions. Don’t try to create your own objects of
type <code>FILE</code>; let the library do it. Your programs should
deal only with pointers to these objects (that is, <code>FILE *</code> values)
rather than the objects themselves.
</p>
<hr size="6">
<a name="Standard-Streams"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Streams" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Opening-Streams" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Standard-Streams-1"></a>
<h2 class="section">12.2 Standard Streams</h2>
<a name="index-standard-streams"></a>
<a name="index-streams_002c-standard"></a>
<p>When the <code>main</code> function of your program is invoked, it already has
three predefined streams open and available for use. These represent
the “standard” input and output channels that have been established
for the process.
</p>
<p>These streams are declared in the header file ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-1"></a>
</p>
<dl>
<dt><a name="index-stdin"></a><u>Variable:</u> FILE * <b>stdin</b></dt>
<dd><p>The <em>standard input</em> stream, which is the normal source of input for the
program.
</p></dd></dl>
<a name="index-standard-input-stream"></a>
<dl>
<dt><a name="index-stdout"></a><u>Variable:</u> FILE * <b>stdout</b></dt>
<dd><p>The <em>standard output</em> stream, which is used for normal output from
the program.
</p></dd></dl>
<a name="index-standard-output-stream"></a>
<dl>
<dt><a name="index-stderr"></a><u>Variable:</u> FILE * <b>stderr</b></dt>
<dd><p>The <em>standard error</em> stream, which is used for error messages and
diagnostics issued by the program.
</p></dd></dl>
<a name="index-standard-error-stream"></a>
<p>In the GNU system, you can specify what files or processes correspond to
these streams using the pipe and redirection facilities provided by the
shell. (The primitives shells use to implement these facilities are
described in <a href="libc_14.html#File-System-Interface">File System Interface</a>.) Most other operating systems
provide similar mechanisms, but the details of how to use them can vary.
</p>
<p>In the GNU C library, <code>stdin</code>, <code>stdout</code>, and <code>stderr</code> are
normal variables which you can set just like any others. For example,
to redirect the standard output to a file, you could do:
</p>
<table><tr><td> </td><td><pre class="smallexample">fclose (stdout);
stdout = fopen ("standard-output-file", "w");
</pre></td></tr></table>
<p>Note however, that in other systems <code>stdin</code>, <code>stdout</code>, and
<code>stderr</code> are macros that you cannot assign to in the normal way.
But you can use <code>freopen</code> to get the effect of closing one and
reopening it. See section <a href="#Opening-Streams">Opening Streams</a>.
</p>
<p>The three streams <code>stdin</code>, <code>stdout</code>, and <code>stderr</code> are not
unoriented at program start (see section <a href="#Streams-and-I18N">Streams in Internationalized Applications</a>).
</p>
<hr size="6">
<a name="Opening-Streams"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Standard-Streams" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Closing-Streams" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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-Streams-1"></a>
<h2 class="section">12.3 Opening Streams</h2>
<a name="index-opening-a-stream"></a>
<p>Opening a file with the <code>fopen</code> function creates a new stream and
establishes a connection between the stream and a file. This may
involve creating a new file.
</p>
<a name="index-stdio_002eh-2"></a>
<p>Everything described in this section is declared in the header file
‘<tt>stdio.h</tt>’.
</p>
<dl>
<dt><a name="index-fopen"></a><u>Function:</u> FILE * <b>fopen</b><i> (const char *<var>filename</var>, const char *<var>opentype</var>)</i></dt>
<dd><p>The <code>fopen</code> function opens a stream for I/O to the file
<var>filename</var>, and returns a pointer to the stream.
</p>
<p>The <var>opentype</var> argument is a string that controls how the file is
opened and specifies attributes of the resulting stream. It must begin
with one of the following sequences of characters:
</p>
<dl compact="compact">
<dt> ‘<samp>r</samp>’</dt>
<dd><p>Open an existing file for reading only.
</p>
</dd>
<dt> ‘<samp>w</samp>’</dt>
<dd><p>Open the file for writing only. If the file already exists, it is
truncated to zero length. Otherwise a new file is created.
</p>
</dd>
<dt> ‘<samp>a</samp>’</dt>
<dd><p>Open a file for append access; that is, writing at the end of file only.
If the file already exists, its initial contents are unchanged and
output to the stream is appended to the end of the file.
Otherwise, a new, empty file is created.
</p>
</dd>
<dt> ‘<samp>r+</samp>’</dt>
<dd><p>Open an existing file for both reading and writing. The initial contents
of the file are unchanged and the initial file position is at the
beginning of the file.
</p>
</dd>
<dt> ‘<samp>w+</samp>’</dt>
<dd><p>Open a file for both reading and writing. If the file already exists, it
is truncated to zero length. Otherwise, a new file is created.
</p>
</dd>
<dt> ‘<samp>a+</samp>’</dt>
<dd><p>Open or create file for both reading and appending. If the file exists,
its initial contents are unchanged. Otherwise, a new file is created.
The initial file position for reading is at the beginning of the file,
but output is always appended to the end of the file.
</p></dd>
</dl>
<p>As you can see, ‘<samp>+</samp>’ requests a stream that can do both input and
output. When using such a stream, you must call <code>fflush</code>
(see section <a href="#Stream-Buffering">Stream Buffering</a>) or a file positioning function such as
<code>fseek</code> (see section <a href="#File-Positioning">File Positioning</a>) when switching from reading
to writing or vice versa. Otherwise, internal buffers might not be
emptied properly.
</p>
<p>Additional characters may appear after these to specify flags for the
call. Always put the mode (‘<samp>r</samp>’, ‘<samp>w+</samp>’, etc.) first; that is
the only part you are guaranteed will be understood by all systems.
</p>
<p>The GNU C library defines one additional character for use in
<var>opentype</var>: the character ‘<samp>x</samp>’ insists on creating a new
file—if a file <var>filename</var> already exists, <code>fopen</code> fails
rather than opening it. If you use ‘<samp>x</samp>’ you are guaranteed that
you will not clobber an existing file. This is equivalent to the
<code>O_EXCL</code> option to the <code>open</code> function (see section <a href="libc_13.html#Opening-and-Closing-Files">Opening and Closing Files</a>).
</p>
<p>The character ‘<samp>b</samp>’ in <var>opentype</var> has a standard meaning; it
requests a binary stream rather than a text stream. But this makes no
difference in POSIX systems (including the GNU system). If both
‘<samp>+</samp>’ and ‘<samp>b</samp>’ are specified, they can appear in either order.
See section <a href="#Binary-Streams">Text and Binary Streams</a>.
</p>
<a name="index-stream-orientation"></a>
<a name="index-orientation_002c-stream"></a>
<p>If the <var>opentype</var> string contains the sequence
<code>,ccs=<var>STRING</var></code> then <var>STRING</var> is taken as the name of a
coded character set and <code>fopen</code> will mark the stream as
wide-oriented which appropriate conversion functions in place to convert
from and to the character set <var>STRING</var> is place. Any other stream
is opened initially unoriented and the orientation is decided with the
first file operation. If the first operation is a wide character
operation, the stream is not only marked as wide-oriented, also the
conversion functions to convert to the coded character set used for the
current locale are loaded. This will not change anymore from this point
on even if the locale selected for the <code>LC_CTYPE</code> category is
changed.
</p>
<p>Any other characters in <var>opentype</var> are simply ignored. They may be
meaningful in other systems.
</p>
<p>If the open fails, <code>fopen</code> returns a null pointer.
</p>
<p>When the sources are compiling with <code>_FILE_OFFSET_BITS == 64</code> on a
32 bit machine this function is in fact <code>fopen64</code> since the LFS
interface replaces transparently the old interface.
</p></dd></dl>
<p>You can have multiple streams (or file descriptors) pointing to the same
file open at the same time. If you do only input, this works
straightforwardly, but you must be careful if any output streams are
included. See section <a href="libc_13.html#Stream_002fDescriptor-Precautions">Dangers of Mixing Streams and Descriptors</a>. This is equally true
whether the streams are in one program (not usual) or in several
programs (which can easily happen). It may be advantageous to use the
file locking facilities to avoid simultaneous access. See section <a href="libc_13.html#File-Locks">File Locks</a>.
</p>
<dl>
<dt><a name="index-fopen64"></a><u>Function:</u> FILE * <b>fopen64</b><i> (const char *<var>filename</var>, const char *<var>opentype</var>)</i></dt>
<dd><p>This function is similar to <code>fopen</code> but the stream it returns a
pointer for is opened using <code>open64</code>. Therefore this stream can be
used even on files larger then <em>2^31</em> bytes on 32 bit machines.
</p>
<p>Please note that the return type is still <code>FILE *</code>. There is no
special <code>FILE</code> type for the LFS interface.
</p>
<p>If the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a 32
bits machine this function is available under the name <code>fopen</code>
and so transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-FOPEN_005fMAX"></a><u>Macro:</u> int <b>FOPEN_MAX</b></dt>
<dd><p>The value of this macro is an integer constant expression that
represents the minimum number of streams that the implementation
guarantees can be open simultaneously. You might be able to open more
than this many streams, but that is not guaranteed. The value of this
constant is at least eight, which includes the three standard streams
<code>stdin</code>, <code>stdout</code>, and <code>stderr</code>. In POSIX.1 systems this
value is determined by the <code>OPEN_MAX</code> parameter; see section <a href="libc_31.html#General-Limits">General Capacity Limits</a>. In BSD and GNU, it is controlled by the <code>RLIMIT_NOFILE</code>
resource limit; see section <a href="libc_22.html#Limits-on-Resources">Limiting Resource Usage</a>.
</p></dd></dl>
<dl>
<dt><a name="index-freopen"></a><u>Function:</u> FILE * <b>freopen</b><i> (const char *<var>filename</var>, const char *<var>opentype</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>This function is like a combination of <code>fclose</code> and <code>fopen</code>.
It first closes the stream referred to by <var>stream</var>, ignoring any
errors that are detected in the process. (Because errors are ignored,
you should not use <code>freopen</code> on an output stream if you have
actually done any output using the stream.) Then the file named by
<var>filename</var> is opened with mode <var>opentype</var> as for <code>fopen</code>,
and associated with the same stream object <var>stream</var>.
</p>
<p>If the operation fails, a null pointer is returned; otherwise,
<code>freopen</code> returns <var>stream</var>.
</p>
<p><code>freopen</code> has traditionally been used to connect a standard stream
such as <code>stdin</code> with a file of your own choice. This is useful in
programs in which use of a standard stream for certain purposes is
hard-coded. In the GNU C library, you can simply close the standard
streams and open new ones with <code>fopen</code>. But other systems lack
this ability, so using <code>freopen</code> is more portable.
</p>
<p>When the sources are compiling with <code>_FILE_OFFSET_BITS == 64</code> on a
32 bit machine this function is in fact <code>freopen64</code> since the LFS
interface replaces transparently the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-freopen64"></a><u>Function:</u> FILE * <b>freopen64</b><i> (const char *<var>filename</var>, const char *<var>opentype</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>This function is similar to <code>freopen</code>. The only difference is that
on 32 bit machine the stream returned is able to read beyond the
<em>2^31</em> bytes limits imposed by the normal interface. It should be
noted that the stream pointed to by <var>stream</var> need not be opened
using <code>fopen64</code> or <code>freopen64</code> since its mode is not important
for this function.
</p>
<p>If the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a 32
bits machine this function is available under the name <code>freopen</code>
and so transparently replaces the old interface.
</p></dd></dl>
<p>In some situations it is useful to know whether a given stream is
available for reading or writing. This information is normally not
available and would have to be remembered separately. Solaris
introduced a few functions to get this information from the stream
descriptor and these functions are also available in the GNU C library.
</p>
<dl>
<dt><a name="index-_005f_005ffreadable"></a><u>Function:</u> int <b>__freadable</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>__freadable</code> function determines whether the stream
<var>stream</var> was opened to allow reading. In this case the return value
is nonzero. For write-only streams the function returns zero.
</p>
<p>This function is declared in ‘<tt>stdio_ext.h</tt>’.
</p></dd></dl>
<dl>
<dt><a name="index-_005f_005ffwritable"></a><u>Function:</u> int <b>__fwritable</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>__fwritable</code> function determines whether the stream
<var>stream</var> was opened to allow writing. In this case the return value
is nonzero. For read-only streams the function returns zero.
</p>
<p>This function is declared in ‘<tt>stdio_ext.h</tt>’.
</p></dd></dl>
<p>For slightly different kind of problems there are two more functions.
They provide even finer-grained information.
</p>
<dl>
<dt><a name="index-_005f_005ffreading"></a><u>Function:</u> int <b>__freading</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>__freading</code> function determines whether the stream
<var>stream</var> was last read from or whether it is opened read-only. In
this case the return value is nonzero, otherwise it is zero.
Determining whether a stream opened for reading and writing was last
used for writing allows to draw conclusions about the content about the
buffer, among other things.
</p>
<p>This function is declared in ‘<tt>stdio_ext.h</tt>’.
</p></dd></dl>
<dl>
<dt><a name="index-_005f_005ffwriting"></a><u>Function:</u> int <b>__fwriting</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>__fwriting</code> function determines whether the stream
<var>stream</var> was last written to or whether it is opened write-only. In
this case the return value is nonzero, otherwise it is zero.
</p>
<p>This function is declared in ‘<tt>stdio_ext.h</tt>’.
</p></dd></dl>
<hr size="6">
<a name="Closing-Streams"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Opening-Streams" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Streams-and-Threads" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Closing-Streams-1"></a>
<h2 class="section">12.4 Closing Streams</h2>
<a name="index-closing-a-stream"></a>
<p>When a stream is closed with <code>fclose</code>, the connection between the
stream and the file is canceled. After you have closed a stream, you
cannot perform any additional operations on it.
</p>
<dl>
<dt><a name="index-fclose"></a><u>Function:</u> int <b>fclose</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This function causes <var>stream</var> to be closed and the connection to
the corresponding file to be broken. Any buffered output is written
and any buffered input is discarded. The <code>fclose</code> function returns
a value of <code>0</code> if the file was closed successfully, and <code>EOF</code>
if an error was detected.
</p>
<p>It is important to check for errors when you call <code>fclose</code> to close
an output stream, because real, everyday errors can be detected at this
time. For example, when <code>fclose</code> writes the remaining buffered
output, it might get an error because the disk is full. Even if you
know the buffer is empty, errors can still occur when closing a file if
you are using NFS.
</p>
<p>The function <code>fclose</code> is declared in ‘<tt>stdio.h</tt>’.
</p></dd></dl>
<p>To close all streams currently available the GNU C Library provides
another function.
</p>
<dl>
<dt><a name="index-fcloseall"></a><u>Function:</u> int <b>fcloseall</b><i> (void)</i></dt>
<dd><p>This function causes all open streams of the process to be closed and
the connection to corresponding files to be broken. All buffered data
is written and any buffered input is discarded. The <code>fcloseall</code>
function returns a value of <code>0</code> if all the files were closed
successfully, and <code>EOF</code> if an error was detected.
</p>
<p>This function should be used only in special situations, e.g., when an
error occurred and the program must be aborted. Normally each single
stream should be closed separately so that problems with individual
streams can be identified. It is also problematic since the standard
streams (see section <a href="#Standard-Streams">Standard Streams</a>) will also be closed.
</p>
<p>The function <code>fcloseall</code> is declared in ‘<tt>stdio.h</tt>’.
</p></dd></dl>
<p>If the <code>main</code> function to your program returns, or if you call the
<code>exit</code> function (see section <a href="libc_25.html#Normal-Termination">Normal Termination</a>), all open streams are
automatically closed properly. If your program terminates in any other
manner, such as by calling the <code>abort</code> function (see section <a href="libc_25.html#Aborting-a-Program">Aborting a Program</a>) or from a fatal signal (see section <a href="libc_24.html#Signal-Handling">Signal Handling</a>), open streams
might not be closed properly. Buffered output might not be flushed and
files may be incomplete. For more information on buffering of streams,
see <a href="#Stream-Buffering">Stream Buffering</a>.
</p>
<hr size="6">
<a name="Streams-and-Threads"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Closing-Streams" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Streams-and-I18N" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Streams-and-Threads-1"></a>
<h2 class="section">12.5 Streams and Threads</h2>
<a name="index-threads"></a>
<a name="index-multi_002dthreaded-application"></a>
<p>Streams can be used in multi-threaded applications in the same way they
are used in single-threaded applications. But the programmer must be
aware of the possible complications. It is important to know about
these also if the program one writes never use threads since the design
and implementation of many stream functions is heavily influenced by the
requirements added by multi-threaded programming.
</p>
<p>The POSIX standard requires that by default the stream operations are
atomic. I.e., issuing two stream operations for the same stream in two
threads at the same time will cause the operations to be executed as if
they were issued sequentially. The buffer operations performed while
reading or writing are protected from other uses of the same stream. To
do this each stream has an internal lock object which has to be
(implicitly) acquired before any work can be done.
</p>
<p>But there are situations where this is not enough and there are also
situations where this is not wanted. The implicit locking is not enough
if the program requires more than one stream function call to happen
atomically. One example would be if an output line a program wants to
generate is created by several function calls. The functions by
themselves would ensure only atomicity of their own operation, but not
atomicity over all the function calls. For this it is necessary to
perform the stream locking in the application code.
</p>
<dl>
<dt><a name="index-flockfile"></a><u>Function:</u> void <b>flockfile</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>flockfile</code> function acquires the internal locking object
associated with the stream <var>stream</var>. This ensures that no other
thread can explicitly through <code>flockfile</code>/<code>ftrylockfile</code> or
implicit through a call of a stream function lock the stream. The
thread will block until the lock is acquired. An explicit call to
<code>funlockfile</code> has to be used to release the lock.
</p></dd></dl>
<dl>
<dt><a name="index-ftrylockfile"></a><u>Function:</u> int <b>ftrylockfile</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>ftrylockfile</code> function tries to acquire the internal locking
object associated with the stream <var>stream</var> just like
<code>flockfile</code>. But unlike <code>flockfile</code> this function does not
block if the lock is not available. <code>ftrylockfile</code> returns zero if
the lock was successfully acquired. Otherwise the stream is locked by
another thread.
</p></dd></dl>
<dl>
<dt><a name="index-funlockfile"></a><u>Function:</u> void <b>funlockfile</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>funlockfile</code> function releases the internal locking object of
the stream <var>stream</var>. The stream must have been locked before by a
call to <code>flockfile</code> or a successful call of <code>ftrylockfile</code>.
The implicit locking performed by the stream operations do not count.
The <code>funlockfile</code> function does not return an error status and the
behavior of a call for a stream which is not locked by the current
thread is undefined.
</p></dd></dl>
<p>The following example shows how the functions above can be used to
generate an output line atomically even in multi-threaded applications
(yes, the same job could be done with one <code>fprintf</code> call but it is
sometimes not possible):
</p>
<table><tr><td> </td><td><pre class="smallexample">FILE *fp;
{
…
flockfile (fp);
fputs ("This is test number ", fp);
fprintf (fp, "%d\n", test);
funlockfile (fp)
}
</pre></td></tr></table>
<p>Without the explicit locking it would be possible for another thread to
use the stream <var>fp</var> after the <code>fputs</code> call return and before
<code>fprintf</code> was called with the result that the number does not
follow the word ‘<samp>number</samp>’.
</p>
<p>From this description it might already be clear that the locking objects
in streams are no simple mutexes. Since locking the same stream twice
in the same thread is allowed the locking objects must be equivalent to
recursive mutexes. These mutexes keep track of the owner and the number
of times the lock is acquired. The same number of <code>funlockfile</code>
calls by the same threads is necessary to unlock the stream completely.
For instance:
</p>
<table><tr><td> </td><td><pre class="smallexample">void
foo (FILE *fp)
{
ftrylockfile (fp);
fputs ("in foo\n", fp);
/* <span class="roman">This is very wrong!!!</span> */
funlockfile (fp);
}
</pre></td></tr></table>
<p>It is important here that the <code>funlockfile</code> function is only called
if the <code>ftrylockfile</code> function succeeded in locking the stream. It
is therefore always wrong to ignore the result of <code>ftrylockfile</code>.
And it makes no sense since otherwise one would use <code>flockfile</code>.
The result of code like that above is that either <code>funlockfile</code>
tries to free a stream that hasn’t been locked by the current thread or it
frees the stream prematurely. The code should look like this:
</p>
<table><tr><td> </td><td><pre class="smallexample">void
foo (FILE *fp)
{
if (ftrylockfile (fp) == 0)
{
fputs ("in foo\n", fp);
funlockfile (fp);
}
}
</pre></td></tr></table>
<p>Now that we covered why it is necessary to have these locking it is
necessary to talk about situations when locking is unwanted and what can
be done. The locking operations (explicit or implicit) don’t come for
free. Even if a lock is not taken the cost is not zero. The operations
which have to be performed require memory operations that are safe in
multi-processor environments. With the many local caches involved in
such systems this is quite costly. So it is best to avoid the locking
completely if it is not needed – because the code in question is never
used in a context where two or more threads may use a stream at a time.
This can be determined most of the time for application code; for
library code which can be used in many contexts one should default to be
conservative and use locking.
</p>
<p>There are two basic mechanisms to avoid locking. The first is to use
the <code>_unlocked</code> variants of the stream operations. The POSIX
standard defines quite a few of those and the GNU library adds a few
more. These variants of the functions behave just like the functions
with the name without the suffix except that they do not lock the
stream. Using these functions is very desirable since they are
potentially much faster. This is not only because the locking
operation itself is avoided. More importantly, functions like
<code>putc</code> and <code>getc</code> are very simple and traditionally (before the
introduction of threads) were implemented as macros which are very fast
if the buffer is not empty. With the addition of locking requirements
these functions are no longer implemented as macros since they would
expand to too much code.
But these macros are still available with the same functionality under the new
names <code>putc_unlocked</code> and <code>getc_unlocked</code>. This possibly huge
difference of speed also suggests the use of the <code>_unlocked</code>
functions even if locking is required. The difference is that the
locking then has to be performed in the program:
</p>
<table><tr><td> </td><td><pre class="smallexample">void
foo (FILE *fp, char *buf)
{
flockfile (fp);
while (*buf != '/')
putc_unlocked (*buf++, fp);
funlockfile (fp);
}
</pre></td></tr></table>
<p>If in this example the <code>putc</code> function would be used and the
explicit locking would be missing the <code>putc</code> function would have to
acquire the lock in every call, potentially many times depending on when
the loop terminates. Writing it the way illustrated above allows the
<code>putc_unlocked</code> macro to be used which means no locking and direct
manipulation of the buffer of the stream.
</p>
<p>A second way to avoid locking is by using a non-standard function which
was introduced in Solaris and is available in the GNU C library as well.
</p>
<dl>
<dt><a name="index-_005f_005ffsetlocking"></a><u>Function:</u> int <b>__fsetlocking</b><i> (FILE *<var>stream</var>, int <var>type</var>)</i></dt>
<dd>
<p>The <code>__fsetlocking</code> function can be used to select whether the
stream operations will implicitly acquire the locking object of the
stream <var>stream</var>. By default this is done but it can be disabled and
reinstated using this function. There are three values defined for the
<var>type</var> parameter.
</p>
<dl compact="compact">
<dt> <code>FSETLOCKING_INTERNAL</code>
<a name="index-FSETLOCKING_005fINTERNAL"></a>
</dt>
<dd><p>The stream <code>stream</code> will from now on use the default internal
locking. Every stream operation with exception of the <code>_unlocked</code>
variants will implicitly lock the stream.
</p>
</dd>
<dt> <code>FSETLOCKING_BYCALLER</code>
<a name="index-FSETLOCKING_005fBYCALLER"></a>
</dt>
<dd><p>After the <code>__fsetlocking</code> function returns the user is responsible
for locking the stream. None of the stream operations will implicitly
do this anymore until the state is set back to
<code>FSETLOCKING_INTERNAL</code>.
</p>
</dd>
<dt> <code>FSETLOCKING_QUERY</code>
<a name="index-FSETLOCKING_005fQUERY"></a>
</dt>
<dd><p><code>__fsetlocking</code> only queries the current locking state of the
stream. The return value will be <code>FSETLOCKING_INTERNAL</code> or
<code>FSETLOCKING_BYCALLER</code> depending on the state.
</p></dd>
</dl>
<p>The return value of <code>__fsetlocking</code> is either
<code>FSETLOCKING_INTERNAL</code> or <code>FSETLOCKING_BYCALLER</code> depending on
the state of the stream before the call.
</p>
<p>This function and the values for the <var>type</var> parameter are declared
in ‘<tt>stdio_ext.h</tt>’.
</p></dd></dl>
<p>This function is especially useful when program code has to be used
which is written without knowledge about the <code>_unlocked</code> functions
(or if the programmer was too lazy to use them).
</p>
<hr size="6">
<a name="Streams-and-I18N"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Streams-and-Threads" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Simple-Output" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Streams-in-Internationalized-Applications"></a>
<h2 class="section">12.6 Streams in Internationalized Applications</h2>
<p>ISO C90 introduced the new type <code>wchar_t</code> to allow handling
larger character sets. What was missing was a possibility to output
strings of <code>wchar_t</code> directly. One had to convert them into
multibyte strings using <code>mbstowcs</code> (there was no <code>mbsrtowcs</code>
yet) and then use the normal stream functions. While this is doable it
is very cumbersome since performing the conversions is not trivial and
greatly increases program complexity and size.
</p>
<p>The Unix standard early on (I think in XPG4.2) introduced two additional
format specifiers for the <code>printf</code> and <code>scanf</code> families of
functions. Printing and reading of single wide characters was made
possible using the <code>%C</code> specifier and wide character strings can be
handled with <code>%S</code>. These modifiers behave just like <code>%c</code> and
<code>%s</code> only that they expect the corresponding argument to have the
wide character type and that the wide character and string are
transformed into/from multibyte strings before being used.
</p>
<p>This was a beginning but it is still not good enough. Not always is it
desirable to use <code>printf</code> and <code>scanf</code>. The other, smaller and
faster functions cannot handle wide characters. Second, it is not
possible to have a format string for <code>printf</code> and <code>scanf</code>
consisting of wide characters. The result is that format strings would
have to be generated if they have to contain non-basic characters.
</p>
<a name="index-C_002b_002b-streams"></a>
<a name="index-streams_002c-C_002b_002b"></a>
<p>In the Amendment 1 to ISO C90 a whole new set of functions was
added to solve the problem. Most of the stream functions got a
counterpart which take a wide character or wide character string instead
of a character or string respectively. The new functions operate on the
same streams (like <code>stdout</code>). This is different from the model of
the C++ runtime library where separate streams for wide and normal I/O
are used.
</p>
<a name="index-orientation_002c-stream-1"></a>
<a name="index-stream-orientation-1"></a>
<p>Being able to use the same stream for wide and normal operations comes
with a restriction: a stream can be used either for wide operations or
for normal operations. Once it is decided there is no way back. Only a
call to <code>freopen</code> or <code>freopen64</code> can reset the
<em>orientation</em>. The orientation can be decided in three ways:
</p>
<ul>
<li>
If any of the normal character functions is used (this includes the
<code>fread</code> and <code>fwrite</code> functions) the stream is marked as not
wide oriented.
</li><li>
If any of the wide character functions is used the stream is marked as
wide oriented.
</li><li>
The <code>fwide</code> function can be used to set the orientation either way.
</li></ul>
<p>It is important to never mix the use of wide and not wide operations on
a stream. There are no diagnostics issued. The application behavior
will simply be strange or the application will simply crash. The
<code>fwide</code> function can help avoiding this.
</p>
<dl>
<dt><a name="index-fwide"></a><u>Function:</u> int <b>fwide</b><i> (FILE *<var>stream</var>, int <var>mode</var>)</i></dt>
<dd>
<p>The <code>fwide</code> function can be used to set and query the state of the
orientation of the stream <var>stream</var>. If the <var>mode</var> parameter has
a positive value the streams get wide oriented, for negative values
narrow oriented. It is not possible to overwrite previous orientations
with <code>fwide</code>. I.e., if the stream <var>stream</var> was already
oriented before the call nothing is done.
</p>
<p>If <var>mode</var> is zero the current orientation state is queried and
nothing is changed.
</p>
<p>The <code>fwide</code> function returns a negative value, zero, or a positive
value if the stream is narrow, not at all, or wide oriented
respectively.
</p>
<p>This function was introduced in Amendment 1 to ISO C90 and is
declared in ‘<tt>wchar.h</tt>’.
</p></dd></dl>
<p>It is generally a good idea to orient a stream as early as possible.
This can prevent surprise especially for the standard streams
<code>stdin</code>, <code>stdout</code>, and <code>stderr</code>. If some library
function in some situations uses one of these streams and this use
orients the stream in a different way the rest of the application
expects it one might end up with hard to reproduce errors. Remember
that no errors are signal if the streams are used incorrectly. Leaving
a stream unoriented after creation is normally only necessary for
library functions which create streams which can be used in different
contexts.
</p>
<p>When writing code which uses streams and which can be used in different
contexts it is important to query the orientation of the stream before
using it (unless the rules of the library interface demand a specific
orientation). The following little, silly function illustrates this.
</p>
<table><tr><td> </td><td><pre class="smallexample">void
print_f (FILE *fp)
{
if (fwide (fp, 0) > 0)
/* <span class="roman">Positive return value means wide orientation.</span> */
fputwc (L'f', fp);
else
fputc ('f', fp);
}
</pre></td></tr></table>
<p>Note that in this case the function <code>print_f</code> decides about the
orientation of the stream if it was unoriented before (will not happen
if the advise above is followed).
</p>
<p>The encoding used for the <code>wchar_t</code> values is unspecified and the
user must not make any assumptions about it. For I/O of <code>wchar_t</code>
values this means that it is impossible to write these values directly
to the stream. This is not what follows from the ISO C locale model
either. What happens instead is that the bytes read from or written to
the underlying media are first converted into the internal encoding
chosen by the implementation for <code>wchar_t</code>. The external encoding
is determined by the <code>LC_CTYPE</code> category of the current locale or
by the ‘<samp>ccs</samp>’ part of the mode specification given to <code>fopen</code>,
<code>fopen64</code>, <code>freopen</code>, or <code>freopen64</code>. How and when the
conversion happens is unspecified and it happens invisible to the user.
</p>
<p>Since a stream is created in the unoriented state it has at that point
no conversion associated with it. The conversion which will be used is
determined by the <code>LC_CTYPE</code> category selected at the time the
stream is oriented. If the locales are changed at the runtime this
might produce surprising results unless one pays attention. This is
just another good reason to orient the stream explicitly as soon as
possible, perhaps with a call to <code>fwide</code>.
</p>
<hr size="6">
<a name="Simple-Output"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Streams-and-I18N" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Character-Input" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Simple-Output-by-Characters-or-Lines"></a>
<h2 class="section">12.7 Simple Output by Characters or Lines</h2>
<a name="index-writing-to-a-stream_002c-by-characters"></a>
<p>This section describes functions for performing character- and
line-oriented output.
</p>
<p>These narrow streams functions are declared in the header file
‘<tt>stdio.h</tt>’ and the wide stream functions in ‘<tt>wchar.h</tt>’.
<a name="index-stdio_002eh-3"></a>
<a name="index-wchar_002eh-13"></a>
</p>
<dl>
<dt><a name="index-fputc"></a><u>Function:</u> int <b>fputc</b><i> (int <var>c</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fputc</code> function converts the character <var>c</var> to type
<code>unsigned char</code>, and writes it to the stream <var>stream</var>.
<code>EOF</code> is returned if a write error occurs; otherwise the
character <var>c</var> is returned.
</p></dd></dl>
<dl>
<dt><a name="index-fputwc"></a><u>Function:</u> wint_t <b>fputwc</b><i> (wchar_t <var>wc</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fputwc</code> function writes the wide character <var>wc</var> to the
stream <var>stream</var>. <code>WEOF</code> is returned if a write error occurs;
otherwise the character <var>wc</var> is returned.
</p></dd></dl>
<dl>
<dt><a name="index-fputc_005funlocked"></a><u>Function:</u> int <b>fputc_unlocked</b><i> (int <var>c</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fputc_unlocked</code> function is equivalent to the <code>fputc</code>
function except that it does not implicitly lock the stream.
</p></dd></dl>
<dl>
<dt><a name="index-fputwc_005funlocked"></a><u>Function:</u> wint_t <b>fputwc_unlocked</b><i> (wint_t <var>wc</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fputwc_unlocked</code> function is equivalent to the <code>fputwc</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-putc"></a><u>Function:</u> int <b>putc</b><i> (int <var>c</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>This is just like <code>fputc</code>, except that most systems implement it as
a macro, making it faster. One consequence is that it may evaluate the
<var>stream</var> argument more than once, which is an exception to the
general rule for macros. <code>putc</code> is usually the best function to
use for writing a single character.
</p></dd></dl>
<dl>
<dt><a name="index-putwc"></a><u>Function:</u> wint_t <b>putwc</b><i> (wchar_t <var>wc</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>This is just like <code>fputwc</code>, except that it can be implement as
a macro, making it faster. One consequence is that it may evaluate the
<var>stream</var> argument more than once, which is an exception to the
general rule for macros. <code>putwc</code> is usually the best function to
use for writing a single wide character.
</p></dd></dl>
<dl>
<dt><a name="index-putc_005funlocked"></a><u>Function:</u> int <b>putc_unlocked</b><i> (int <var>c</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>putc_unlocked</code> function is equivalent to the <code>putc</code>
function except that it does not implicitly lock the stream.
</p></dd></dl>
<dl>
<dt><a name="index-putwc_005funlocked"></a><u>Function:</u> wint_t <b>putwc_unlocked</b><i> (wchar_t <var>wc</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>putwc_unlocked</code> function is equivalent to the <code>putwc</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-putchar"></a><u>Function:</u> int <b>putchar</b><i> (int <var>c</var>)</i></dt>
<dd><p>The <code>putchar</code> function is equivalent to <code>putc</code> with
<code>stdout</code> as the value of the <var>stream</var> argument.
</p></dd></dl>
<dl>
<dt><a name="index-putwchar"></a><u>Function:</u> wint_t <b>putwchar</b><i> (wchar_t <var>wc</var>)</i></dt>
<dd><p>The <code>putwchar</code> function is equivalent to <code>putwc</code> with
<code>stdout</code> as the value of the <var>stream</var> argument.
</p></dd></dl>
<dl>
<dt><a name="index-putchar_005funlocked"></a><u>Function:</u> int <b>putchar_unlocked</b><i> (int <var>c</var>)</i></dt>
<dd><p>The <code>putchar_unlocked</code> function is equivalent to the <code>putchar</code>
function except that it does not implicitly lock the stream.
</p></dd></dl>
<dl>
<dt><a name="index-putwchar_005funlocked"></a><u>Function:</u> wint_t <b>putwchar_unlocked</b><i> (wchar_t <var>wc</var>)</i></dt>
<dd><p>The <code>putwchar_unlocked</code> function is equivalent to the <code>putwchar</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-fputs"></a><u>Function:</u> int <b>fputs</b><i> (const char *<var>s</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The function <code>fputs</code> writes the string <var>s</var> to the stream
<var>stream</var>. The terminating null character is not written.
This function does <em>not</em> add a newline character, either.
It outputs only the characters in the string.
</p>
<p>This function returns <code>EOF</code> if a write error occurs, and otherwise
a non-negative value.
</p>
<p>For example:
</p>
<table><tr><td> </td><td><pre class="smallexample">fputs ("Are ", stdout);
fputs ("you ", stdout);
fputs ("hungry?\n", stdout);
</pre></td></tr></table>
<p>outputs the text ‘<samp>Are you hungry?</samp>’ followed by a newline.
</p></dd></dl>
<dl>
<dt><a name="index-fputws"></a><u>Function:</u> int <b>fputws</b><i> (const wchar_t *<var>ws</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The function <code>fputws</code> writes the wide character string <var>ws</var> to
the stream <var>stream</var>. The terminating null character is not written.
This function does <em>not</em> add a newline character, either. It
outputs only the characters in the string.
</p>
<p>This function returns <code>WEOF</code> if a write error occurs, and otherwise
a non-negative value.
</p></dd></dl>
<dl>
<dt><a name="index-fputs_005funlocked"></a><u>Function:</u> int <b>fputs_unlocked</b><i> (const char *<var>s</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fputs_unlocked</code> function is equivalent to the <code>fputs</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-fputws_005funlocked"></a><u>Function:</u> int <b>fputws_unlocked</b><i> (const wchar_t *<var>ws</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fputws_unlocked</code> function is equivalent to the <code>fputws</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-puts"></a><u>Function:</u> int <b>puts</b><i> (const char *<var>s</var>)</i></dt>
<dd><p>The <code>puts</code> function writes the string <var>s</var> to the stream
<code>stdout</code> followed by a newline. The terminating null character of
the string is not written. (Note that <code>fputs</code> does <em>not</em>
write a newline as this function does.)
</p>
<p><code>puts</code> is the most convenient function for printing simple
messages. For example:
</p>
<table><tr><td> </td><td><pre class="smallexample">puts ("This is a message.");
</pre></td></tr></table>
<p>outputs the text ‘<samp>This is a message.</samp>’ followed by a newline.
</p></dd></dl>
<dl>
<dt><a name="index-putw"></a><u>Function:</u> int <b>putw</b><i> (int <var>w</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>This function writes the word <var>w</var> (that is, an <code>int</code>) to
<var>stream</var>. It is provided for compatibility with SVID, but we
recommend you use <code>fwrite</code> instead (see section <a href="#Block-Input_002fOutput">Block Input/Output</a>).
</p></dd></dl>
<hr size="6">
<a name="Character-Input"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Simple-Output" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Line-Input" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Character-Input-1"></a>
<h2 class="section">12.8 Character Input</h2>
<a name="index-reading-from-a-stream_002c-by-characters"></a>
<p>This section describes functions for performing character-oriented
input. These narrow streams functions are declared in the header file
‘<tt>stdio.h</tt>’ and the wide character functions are declared in
‘<tt>wchar.h</tt>’.
<a name="index-stdio_002eh-4"></a>
<a name="index-wchar_002eh-14"></a>
</p>
<p>These functions return an <code>int</code> or <code>wint_t</code> value (for narrow
and wide stream functions respectively) that is either a character of
input, or the special value <code>EOF</code>/<code>WEOF</code> (usually -1). For
the narrow stream functions it is important to store the result of these
functions in a variable of type <code>int</code> instead of <code>char</code>, even
when you plan to use it only as a character. Storing <code>EOF</code> in a
<code>char</code> variable truncates its value to the size of a character, so
that it is no longer distinguishable from the valid character
‘<samp>(char) -1</samp>’. So always use an <code>int</code> for the result of
<code>getc</code> and friends, and check for <code>EOF</code> after the call; once
you’ve verified that the result is not <code>EOF</code>, you can be sure that
it will fit in a ‘<samp>char</samp>’ variable without loss of information.
</p>
<dl>
<dt><a name="index-fgetc"></a><u>Function:</u> int <b>fgetc</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This function reads the next character as an <code>unsigned char</code> from
the stream <var>stream</var> and returns its value, converted to an
<code>int</code>. If an end-of-file condition or read error occurs,
<code>EOF</code> is returned instead.
</p></dd></dl>
<dl>
<dt><a name="index-fgetwc"></a><u>Function:</u> wint_t <b>fgetwc</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This function reads the next wide character from the stream <var>stream</var>
and returns its value. If an end-of-file condition or read error
occurs, <code>WEOF</code> is returned instead.
</p></dd></dl>
<dl>
<dt><a name="index-fgetc_005funlocked"></a><u>Function:</u> int <b>fgetc_unlocked</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fgetc_unlocked</code> function is equivalent to the <code>fgetc</code>
function except that it does not implicitly lock the stream.
</p></dd></dl>
<dl>
<dt><a name="index-fgetwc_005funlocked"></a><u>Function:</u> wint_t <b>fgetwc_unlocked</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fgetwc_unlocked</code> function is equivalent to the <code>fgetwc</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-getc"></a><u>Function:</u> int <b>getc</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This is just like <code>fgetc</code>, except that it is permissible (and
typical) for it to be implemented as a macro that evaluates the
<var>stream</var> argument more than once. <code>getc</code> is often highly
optimized, so it is usually the best function to use to read a single
character.
</p></dd></dl>
<dl>
<dt><a name="index-getwc"></a><u>Function:</u> wint_t <b>getwc</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This is just like <code>fgetwc</code>, except that it is permissible for it to
be implemented as a macro that evaluates the <var>stream</var> argument more
than once. <code>getwc</code> can be highly optimized, so it is usually the
best function to use to read a single wide character.
</p></dd></dl>
<dl>
<dt><a name="index-getc_005funlocked"></a><u>Function:</u> int <b>getc_unlocked</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>getc_unlocked</code> function is equivalent to the <code>getc</code>
function except that it does not implicitly lock the stream.
</p></dd></dl>
<dl>
<dt><a name="index-getwc_005funlocked"></a><u>Function:</u> wint_t <b>getwc_unlocked</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>getwc_unlocked</code> function is equivalent to the <code>getwc</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-getchar"></a><u>Function:</u> int <b>getchar</b><i> (void)</i></dt>
<dd><p>The <code>getchar</code> function is equivalent to <code>getc</code> with <code>stdin</code>
as the value of the <var>stream</var> argument.
</p></dd></dl>
<dl>
<dt><a name="index-getwchar"></a><u>Function:</u> wint_t <b>getwchar</b><i> (void)</i></dt>
<dd><p>The <code>getwchar</code> function is equivalent to <code>getwc</code> with <code>stdin</code>
as the value of the <var>stream</var> argument.
</p></dd></dl>
<dl>
<dt><a name="index-getchar_005funlocked"></a><u>Function:</u> int <b>getchar_unlocked</b><i> (void)</i></dt>
<dd><p>The <code>getchar_unlocked</code> function is equivalent to the <code>getchar</code>
function except that it does not implicitly lock the stream.
</p></dd></dl>
<dl>
<dt><a name="index-getwchar_005funlocked"></a><u>Function:</u> wint_t <b>getwchar_unlocked</b><i> (void)</i></dt>
<dd><p>The <code>getwchar_unlocked</code> function is equivalent to the <code>getwchar</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<p>Here is an example of a function that does input using <code>fgetc</code>. It
would work just as well using <code>getc</code> instead, or using
<code>getchar ()</code> instead of <code>fgetc (stdin)</code>. The code would
also work the same for the wide character stream functions.
</p>
<table><tr><td> </td><td><pre class="smallexample">int
y_or_n_p (const char *question)
{
fputs (question, stdout);
while (1)
{
int c, answer;
/* <span class="roman">Write a space to separate answer from question.</span> */
fputc (' ', stdout);
/* <span class="roman">Read the first character of the line.</span>
<span class="roman">This should be the answer character, but might not be.</span> */
c = tolower (fgetc (stdin));
answer = c;
/* <span class="roman">Discard rest of input line.</span> */
while (c != '\n' && c != EOF)
c = fgetc (stdin);
/* <span class="roman">Obey the answer if it was valid.</span> */
if (answer == 'y')
return 1;
if (answer == 'n')
return 0;
/* <span class="roman">Answer was invalid: ask for valid answer.</span> */
fputs ("Please answer y or n:", stdout);
}
}
</pre></td></tr></table>
<dl>
<dt><a name="index-getw"></a><u>Function:</u> int <b>getw</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This function reads a word (that is, an <code>int</code>) from <var>stream</var>.
It’s provided for compatibility with SVID. We recommend you use
<code>fread</code> instead (see section <a href="#Block-Input_002fOutput">Block Input/Output</a>). Unlike <code>getc</code>,
any <code>int</code> value could be a valid result. <code>getw</code> returns
<code>EOF</code> when it encounters end-of-file or an error, but there is no
way to distinguish this from an input word with value -1.
</p></dd></dl>
<hr size="6">
<a name="Line-Input"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Character-Input" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Unreading" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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_002dOriented-Input"></a>
<h2 class="section">12.9 Line-Oriented Input</h2>
<p>Since many programs interpret input on the basis of lines, it is
convenient to have functions to read a line of text from a stream.
</p>
<p>Standard C has functions to do this, but they aren’t very safe: null
characters and even (for <code>gets</code>) long lines can confuse them. So
the GNU library provides the nonstandard <code>getline</code> function that
makes it easy to read lines reliably.
</p>
<p>Another GNU extension, <code>getdelim</code>, generalizes <code>getline</code>. It
reads a delimited record, defined as everything through the next
occurrence of a specified delimiter character.
</p>
<p>All these functions are declared in ‘<tt>stdio.h</tt>’.
</p>
<dl>
<dt><a name="index-getline"></a><u>Function:</u> ssize_t <b>getline</b><i> (char **<var>lineptr</var>, size_t *<var>n</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>This function reads an entire line from <var>stream</var>, storing the text
(including the newline and a terminating null character) in a buffer
and storing the buffer address in <code>*<var>lineptr</var></code>.
</p>
<p>Before calling <code>getline</code>, you should place in <code>*<var>lineptr</var></code>
the address of a buffer <code>*<var>n</var></code> bytes long, allocated with
<code>malloc</code>. If this buffer is long enough to hold the line,
<code>getline</code> stores the line in this buffer. Otherwise,
<code>getline</code> makes the buffer bigger using <code>realloc</code>, storing the
new buffer address back in <code>*<var>lineptr</var></code> and the increased size
back in <code>*<var>n</var></code>.
See section <a href="libc_3.html#Unconstrained-Allocation">Unconstrained Allocation</a>.
</p>
<p>If you set <code>*<var>lineptr</var></code> to a null pointer, and <code>*<var>n</var></code>
to zero, before the call, then <code>getline</code> allocates the initial
buffer for you by calling <code>malloc</code>.
</p>
<p>In either case, when <code>getline</code> returns, <code>*<var>lineptr</var></code> is
a <code>char *</code> which points to the text of the line.
</p>
<p>When <code>getline</code> is successful, it returns the number of characters
read (including the newline, but not including the terminating null).
This value enables you to distinguish null characters that are part of
the line from the null character inserted as a terminator.
</p>
<p>This function is a GNU extension, but it is the recommended way to read
lines from a stream. The alternative standard functions are unreliable.
</p>
<p>If an error occurs or end of file is reached without any bytes read,
<code>getline</code> returns <code>-1</code>.
</p></dd></dl>
<dl>
<dt><a name="index-getdelim"></a><u>Function:</u> ssize_t <b>getdelim</b><i> (char **<var>lineptr</var>, size_t *<var>n</var>, int <var>delimiter</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>This function is like <code>getline</code> except that the character which
tells it to stop reading is not necessarily newline. The argument
<var>delimiter</var> specifies the delimiter character; <code>getdelim</code> keeps
reading until it sees that character (or end of file).
</p>
<p>The text is stored in <var>lineptr</var>, including the delimiter character
and a terminating null. Like <code>getline</code>, <code>getdelim</code> makes
<var>lineptr</var> bigger if it isn’t big enough.
</p>
<p><code>getline</code> is in fact implemented in terms of <code>getdelim</code>, just
like this:
</p>
<table><tr><td> </td><td><pre class="smallexample">ssize_t
getline (char **lineptr, size_t *n, FILE *stream)
{
return getdelim (lineptr, n, '\n', stream);
}
</pre></td></tr></table>
</dd></dl>
<dl>
<dt><a name="index-fgets"></a><u>Function:</u> char * <b>fgets</b><i> (char *<var>s</var>, int <var>count</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fgets</code> function reads characters from the stream <var>stream</var>
up to and including a newline character and stores them in the string
<var>s</var>, adding a null character to mark the end of the string. You
must supply <var>count</var> characters worth of space in <var>s</var>, but the
number of characters read is at most <var>count</var> - 1. The extra
character space is used to hold the null character at the end of the
string.
</p>
<p>If the system is already at end of file when you call <code>fgets</code>, then
the contents of the array <var>s</var> are unchanged and a null pointer is
returned. A null pointer is also returned if a read error occurs.
Otherwise, the return value is the pointer <var>s</var>.
</p>
<p><strong>Warning:</strong> If the input data has a null character, you can’t tell.
So don’t use <code>fgets</code> unless you know the data cannot contain a null.
Don’t use it to read files edited by the user because, if the user inserts
a null character, you should either handle it properly or print a clear
error message. We recommend using <code>getline</code> instead of <code>fgets</code>.
</p></dd></dl>
<dl>
<dt><a name="index-fgetws"></a><u>Function:</u> wchar_t * <b>fgetws</b><i> (wchar_t *<var>ws</var>, int <var>count</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fgetws</code> function reads wide characters from the stream
<var>stream</var> up to and including a newline character and stores them in
the string <var>ws</var>, adding a null wide character to mark the end of the
string. You must supply <var>count</var> wide characters worth of space in
<var>ws</var>, but the number of characters read is at most <var>count</var>
- 1. The extra character space is used to hold the null wide
character at the end of the string.
</p>
<p>If the system is already at end of file when you call <code>fgetws</code>, then
the contents of the array <var>ws</var> are unchanged and a null pointer is
returned. A null pointer is also returned if a read error occurs.
Otherwise, the return value is the pointer <var>ws</var>.
</p>
<p><strong>Warning:</strong> If the input data has a null wide character (which are
null bytes in the input stream), you can’t tell. So don’t use
<code>fgetws</code> unless you know the data cannot contain a null. Don’t use
it to read files edited by the user because, if the user inserts a null
character, you should either handle it properly or print a clear error
message.
</p></dd></dl>
<dl>
<dt><a name="index-fgets_005funlocked"></a><u>Function:</u> char * <b>fgets_unlocked</b><i> (char *<var>s</var>, int <var>count</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fgets_unlocked</code> function is equivalent to the <code>fgets</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-fgetws_005funlocked"></a><u>Function:</u> wchar_t * <b>fgetws_unlocked</b><i> (wchar_t *<var>ws</var>, int <var>count</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fgetws_unlocked</code> function is equivalent to the <code>fgetws</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-gets"></a><u>Deprecated function:</u> char * <b>gets</b><i> (char *<var>s</var>)</i></dt>
<dd><p>The function <code>gets</code> reads characters from the stream <code>stdin</code>
up to the next newline character, and stores them in the string <var>s</var>.
The newline character is discarded (note that this differs from the
behavior of <code>fgets</code>, which copies the newline character into the
string). If <code>gets</code> encounters a read error or end-of-file, it
returns a null pointer; otherwise it returns <var>s</var>.
</p>
<p><strong>Warning:</strong> The <code>gets</code> function is <strong>very dangerous</strong>
because it provides no protection against overflowing the string
<var>s</var>. The GNU library includes it for compatibility only. You
should <strong>always</strong> use <code>fgets</code> or <code>getline</code> instead. To
remind you of this, the linker (if using GNU <code>ld</code>) will issue a
warning whenever you use <code>gets</code>.
</p></dd></dl>
<hr size="6">
<a name="Unreading"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Line-Input" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Unreading-Idea" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Unreading-1"></a>
<h2 class="section">12.10 Unreading</h2>
<a name="index-peeking-at-input"></a>
<a name="index-unreading-characters"></a>
<a name="index-pushing-input-back"></a>
<p>In parser programs it is often useful to examine the next character in
the input stream without removing it from the stream. This is called
“peeking ahead” at the input because your program gets a glimpse of
the input it will read next.
</p>
<p>Using stream I/O, you can peek ahead at input by first reading it and
then <em>unreading</em> it (also called <em>pushing it back</em> on the stream).
Unreading a character makes it available to be input again from the stream,
by the next call to <code>fgetc</code> or other input function on that stream.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Unreading-Idea">12.10.1 What Unreading Means</a></td><td> </td><td align="left" valign="top"> An explanation of unreading with pictures.
</td></tr>
<tr><td align="left" valign="top"><a href="#How-Unread">12.10.2 Using <code>ungetc</code> To Do Unreading</a></td><td> </td><td align="left" valign="top"> How to call <code>ungetc</code> to do unreading.
</td></tr>
</table>
<hr size="6">
<a name="Unreading-Idea"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Unreading" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#How-Unread" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Unreading" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="What-Unreading-Means"></a>
<h3 class="subsection">12.10.1 What Unreading Means</h3>
<p>Here is a pictorial explanation of unreading. Suppose you have a
stream reading a file that contains just six characters, the letters
‘<samp>foobar</samp>’. Suppose you have read three characters so far. The
situation looks like this:
</p>
<table><tr><td> </td><td><pre class="smallexample">f o o b a r
^
</pre></td></tr></table>
<p>so the next input character will be ‘<samp>b</samp>’.
</p>
<p>If instead of reading ‘<samp>b</samp>’ you unread the letter ‘<samp>o</samp>’, you get a
situation like this:
</p>
<table><tr><td> </td><td><pre class="smallexample">f o o b a r
|
o--
^
</pre></td></tr></table>
<p>so that the next input characters will be ‘<samp>o</samp>’ and ‘<samp>b</samp>’.
</p>
<p>If you unread ‘<samp>9</samp>’ instead of ‘<samp>o</samp>’, you get this situation:
</p>
<table><tr><td> </td><td><pre class="smallexample">f o o b a r
|
9--
^
</pre></td></tr></table>
<p>so that the next input characters will be ‘<samp>9</samp>’ and ‘<samp>b</samp>’.
</p>
<hr size="6">
<a name="How-Unread"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Unreading-Idea" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Block-Input_002fOutput" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Unreading" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Using-ungetc-To-Do-Unreading"></a>
<h3 class="subsection">12.10.2 Using <code>ungetc</code> To Do Unreading</h3>
<p>The function to unread a character is called <code>ungetc</code>, because it
reverses the action of <code>getc</code>.
</p>
<dl>
<dt><a name="index-ungetc"></a><u>Function:</u> int <b>ungetc</b><i> (int <var>c</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>ungetc</code> function pushes back the character <var>c</var> onto the
input stream <var>stream</var>. So the next input from <var>stream</var> will
read <var>c</var> before anything else.
</p>
<p>If <var>c</var> is <code>EOF</code>, <code>ungetc</code> does nothing and just returns
<code>EOF</code>. This lets you call <code>ungetc</code> with the return value of
<code>getc</code> without needing to check for an error from <code>getc</code>.
</p>
<p>The character that you push back doesn’t have to be the same as the last
character that was actually read from the stream. In fact, it isn’t
necessary to actually read any characters from the stream before
unreading them with <code>ungetc</code>! But that is a strange way to write a
program; usually <code>ungetc</code> is used only to unread a character that
was just read from the same stream. The GNU C library supports this
even on files opened in binary mode, but other systems might not.
</p>
<p>The GNU C library only supports one character of pushback—in other
words, it does not work to call <code>ungetc</code> twice without doing input
in between. Other systems might let you push back multiple characters;
then reading from the stream retrieves the characters in the reverse
order that they were pushed.
</p>
<p>Pushing back characters doesn’t alter the file; only the internal
buffering for the stream is affected. If a file positioning function
(such as <code>fseek</code>, <code>fseeko</code> or <code>rewind</code>; see section <a href="#File-Positioning">File Positioning</a>) is called, any pending pushed-back characters are
discarded.
</p>
<p>Unreading a character on a stream that is at end of file clears the
end-of-file indicator for the stream, because it makes the character of
input available. After you read that character, trying to read again
will encounter end of file.
</p></dd></dl>
<dl>
<dt><a name="index-ungetwc"></a><u>Function:</u> wint_t <b>ungetwc</b><i> (wint_t <var>wc</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>ungetwc</code> function behaves just like <code>ungetc</code> just that it
pushes back a wide character.
</p></dd></dl>
<p>Here is an example showing the use of <code>getc</code> and <code>ungetc</code> to
skip over whitespace characters. When this function reaches a
non-whitespace character, it unreads that character to be seen again on
the next read operation on the stream.
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <stdio.h>
#include <ctype.h>
void
skip_whitespace (FILE *stream)
{
int c;
do
/* <span class="roman">No need to check for <code>EOF</code> because it is not</span>
<span class="roman"><code>isspace</code>, and <code>ungetc</code> ignores <code>EOF</code>.</span> */
c = getc (stream);
while (isspace (c));
ungetc (c, stream);
}
</pre></td></tr></table>
<hr size="6">
<a name="Block-Input_002fOutput"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#How-Unread" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Block-Input_002fOutput-1"></a>
<h2 class="section">12.11 Block Input/Output</h2>
<p>This section describes how to do input and output operations on blocks
of data. You can use these functions to read and write binary data, as
well as to read and write text in fixed-size blocks instead of by
characters or lines.
<a name="index-binary-I_002fO-to-a-stream"></a>
<a name="index-block-I_002fO-to-a-stream"></a>
<a name="index-reading-from-a-stream_002c-by-blocks"></a>
<a name="index-writing-to-a-stream_002c-by-blocks"></a>
</p>
<p>Binary files are typically used to read and write blocks of data in the
same format as is used to represent the data in a running program. In
other words, arbitrary blocks of memory—not just character or string
objects—can be written to a binary file, and meaningfully read in
again by the same program.
</p>
<p>Storing data in binary form is often considerably more efficient than
using the formatted I/O functions. Also, for floating-point numbers,
the binary form avoids possible loss of precision in the conversion
process. On the other hand, binary files can’t be examined or modified
easily using many standard file utilities (such as text editors), and
are not portable between different implementations of the language, or
different kinds of computers.
</p>
<p>These functions are declared in ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-5"></a>
</p>
<dl>
<dt><a name="index-fread"></a><u>Function:</u> size_t <b>fread</b><i> (void *<var>data</var>, size_t <var>size</var>, size_t <var>count</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>This function reads up to <var>count</var> objects of size <var>size</var> into
the array <var>data</var>, from the stream <var>stream</var>. It returns the
number of objects actually read, which might be less than <var>count</var> if
a read error occurs or the end of the file is reached. This function
returns a value of zero (and doesn’t read anything) if either <var>size</var>
or <var>count</var> is zero.
</p>
<p>If <code>fread</code> encounters end of file in the middle of an object, it
returns the number of complete objects read, and discards the partial
object. Therefore, the stream remains at the actual end of the file.
</p></dd></dl>
<dl>
<dt><a name="index-fread_005funlocked"></a><u>Function:</u> size_t <b>fread_unlocked</b><i> (void *<var>data</var>, size_t <var>size</var>, size_t <var>count</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fread_unlocked</code> function is equivalent to the <code>fread</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-fwrite"></a><u>Function:</u> size_t <b>fwrite</b><i> (const void *<var>data</var>, size_t <var>size</var>, size_t <var>count</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>This function writes up to <var>count</var> objects of size <var>size</var> from
the array <var>data</var>, to the stream <var>stream</var>. The return value is
normally <var>count</var>, if the call succeeds. Any other value indicates
some sort of error, such as running out of space.
</p></dd></dl>
<dl>
<dt><a name="index-fwrite_005funlocked"></a><u>Function:</u> size_t <b>fwrite_unlocked</b><i> (const void *<var>data</var>, size_t <var>size</var>, size_t <var>count</var>, FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fwrite_unlocked</code> function is equivalent to the <code>fwrite</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<hr size="6">
<a name="Formatted-Output"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Block-Input_002fOutput" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output-Basics" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Formatted-Output-1"></a>
<h2 class="section">12.12 Formatted Output</h2>
<a name="index-format-string_002c-for-printf"></a>
<a name="index-template_002c-for-printf"></a>
<a name="index-formatted-output-to-a-stream"></a>
<a name="index-writing-to-a-stream_002c-formatted"></a>
<p>The functions described in this section (<code>printf</code> and related
functions) provide a convenient way to perform formatted output. You
call <code>printf</code> with a <em>format string</em> or <em>template string</em>
that specifies how to format the values of the remaining arguments.
</p>
<p>Unless your program is a filter that specifically performs line- or
character-oriented processing, using <code>printf</code> or one of the other
related functions described in this section is usually the easiest and
most concise way to perform output. These functions are especially
useful for printing error messages, tables of data, and the like.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Formatted-Output-Basics">12.12.1 Formatted Output Basics</a></td><td> </td><td align="left" valign="top"> Some examples to get you started.
</td></tr>
<tr><td align="left" valign="top"><a href="#Output-Conversion-Syntax">12.12.2 Output Conversion Syntax</a></td><td> </td><td align="left" valign="top"> General syntax of conversion
specifications.
</td></tr>
<tr><td align="left" valign="top"><a href="#Table-of-Output-Conversions">12.12.3 Table of Output Conversions</a></td><td> </td><td align="left" valign="top"> Summary of output conversions and
what they do.
</td></tr>
<tr><td align="left" valign="top"><a href="#Integer-Conversions">12.12.4 Integer Conversions</a></td><td> </td><td align="left" valign="top"> Details about formatting of integers.
</td></tr>
<tr><td align="left" valign="top"><a href="#Floating_002dPoint-Conversions">12.12.5 Floating-Point Conversions</a></td><td> </td><td align="left" valign="top"> Details about formatting of
floating-point numbers.
</td></tr>
<tr><td align="left" valign="top"><a href="#Other-Output-Conversions">12.12.6 Other Output Conversions</a></td><td> </td><td align="left" valign="top"> Details about formatting of strings,
characters, pointers, and the like.
</td></tr>
<tr><td align="left" valign="top"><a href="#Formatted-Output-Functions">12.12.7 Formatted Output Functions</a></td><td> </td><td align="left" valign="top"> Descriptions of the actual functions.
</td></tr>
<tr><td align="left" valign="top"><a href="#Dynamic-Output">12.12.8 Dynamically Allocating Formatted Output</a></td><td> </td><td align="left" valign="top"> Functions that allocate memory for the output.
</td></tr>
<tr><td align="left" valign="top"><a href="#Variable-Arguments-Output">12.12.9 Variable Arguments Output Functions</a></td><td> </td><td align="left" valign="top"> <code>vprintf</code> and friends.
</td></tr>
<tr><td align="left" valign="top"><a href="#Parsing-a-Template-String">12.12.10 Parsing a Template String</a></td><td> </td><td align="left" valign="top"> What kinds of args does a given template
call for?
</td></tr>
<tr><td align="left" valign="top"><a href="#Example-of-Parsing">12.12.11 Example of Parsing a Template String</a></td><td> </td><td align="left" valign="top"> Sample program using <code>parse_printf_format</code>.
</td></tr>
</table>
<hr size="6">
<a name="Formatted-Output-Basics"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Formatted-Output" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Output-Conversion-Syntax" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Formatted-Output-Basics-1"></a>
<h3 class="subsection">12.12.1 Formatted Output Basics</h3>
<p>The <code>printf</code> function can be used to print any number of arguments.
The template string argument you supply in a call provides
information not only about the number of additional arguments, but also
about their types and what style should be used for printing them.
</p>
<p>Ordinary characters in the template string are simply written to the
output stream as-is, while <em>conversion specifications</em> introduced by
a ‘<samp>%</samp>’ character in the template cause subsequent arguments to be
formatted and written to the output stream. For example,
<a name="index-conversion-specifications-_0028printf_0029"></a>
</p>
<table><tr><td> </td><td><pre class="smallexample">int pct = 37;
char filename[] = "foo.txt";
printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
filename, pct);
</pre></td></tr></table>
<p>produces output like
</p>
<table><tr><td> </td><td><pre class="smallexample">Processing of `foo.txt' is 37% finished.
Please be patient.
</pre></td></tr></table>
<p>This example shows the use of the ‘<samp>%d</samp>’ conversion to specify that
an <code>int</code> argument should be printed in decimal notation, the
‘<samp>%s</samp>’ conversion to specify printing of a string argument, and
the ‘<samp>%%</samp>’ conversion to print a literal ‘<samp>%</samp>’ character.
</p>
<p>There are also conversions for printing an integer argument as an
unsigned value in octal, decimal, or hexadecimal radix (‘<samp>%o</samp>’,
‘<samp>%u</samp>’, or ‘<samp>%x</samp>’, respectively); or as a character value
(‘<samp>%c</samp>’).
</p>
<p>Floating-point numbers can be printed in normal, fixed-point notation
using the ‘<samp>%f</samp>’ conversion or in exponential notation using the
‘<samp>%e</samp>’ conversion. The ‘<samp>%g</samp>’ conversion uses either ‘<samp>%e</samp>’
or ‘<samp>%f</samp>’ format, depending on what is more appropriate for the
magnitude of the particular number.
</p>
<p>You can control formatting more precisely by writing <em>modifiers</em>
between the ‘<samp>%</samp>’ and the character that indicates which conversion
to apply. These slightly alter the ordinary behavior of the conversion.
For example, most conversion specifications permit you to specify a
minimum field width and a flag indicating whether you want the result
left- or right-justified within the field.
</p>
<p>The specific flags and modifiers that are permitted and their
interpretation vary depending on the particular conversion. They’re all
described in more detail in the following sections. Don’t worry if this
all seems excessively complicated at first; you can almost always get
reasonable free-format output without using any of the modifiers at all.
The modifiers are mostly used to make the output look “prettier” in
tables.
</p>
<hr size="6">
<a name="Output-Conversion-Syntax"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Formatted-Output-Basics" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Table-of-Output-Conversions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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-Conversion-Syntax-1"></a>
<h3 class="subsection">12.12.2 Output Conversion Syntax</h3>
<p>This section provides details about the precise syntax of conversion
specifications that can appear in a <code>printf</code> template
string.
</p>
<p>Characters in the template string that are not part of a conversion
specification are printed as-is to the output stream. Multibyte
character sequences (see section <a href="libc_6.html#Character-Set-Handling">Character Set Handling</a>) are permitted in a
template string.
</p>
<p>The conversion specifications in a <code>printf</code> template string have
the general form:
</p>
<table><tr><td> </td><td><pre class="smallexample">% <span class="roman">[</span> <var>param-no</var> <span class="roman">$]</span> <var>flags</var> <var>width</var> <span class="roman">[</span> . <var>precision</var> <span class="roman">]</span> <var>type</var> <var>conversion</var>
</pre></td></tr></table>
<p>or
</p>
<table><tr><td> </td><td><pre class="smallexample">% <span class="roman">[</span> <var>param-no</var> <span class="roman">$]</span> <var>flags</var> <var>width</var> . <span class="roman">*</span> <span class="roman">[</span> <var>param-no</var> <span class="roman">$]</span> <var>type</var> <var>conversion</var>
</pre></td></tr></table>
<p>For example, in the conversion specifier ‘<samp>%-10.8ld</samp>’, the ‘<samp>-</samp>’
is a flag, ‘<samp>10</samp>’ specifies the field width, the precision is
‘<samp>8</samp>’, the letter ‘<samp>l</samp>’ is a type modifier, and ‘<samp>d</samp>’ specifies
the conversion style. (This particular type specifier says to
print a <code>long int</code> argument in decimal notation, with a minimum of
8 digits left-justified in a field at least 10 characters wide.)
</p>
<p>In more detail, output conversion specifications consist of an
initial ‘<samp>%</samp>’ character followed in sequence by:
</p>
<ul>
<li>
An optional specification of the parameter used for this format.
Normally the parameters to the <code>printf</code> function are assigned to the
formats in the order of appearance in the format string. But in some
situations (such as message translation) this is not desirable and this
extension allows an explicit parameter to be specified.
<p>The <var>param-no</var> parts of the format must be integers in the range of
1 to the maximum number of arguments present to the function call. Some
implementations limit this number to a certainly upper bound. The exact
limit can be retrieved by the following constant.
</p>
<dl>
<dt><a name="index-NL_005fARGMAX"></a><u>Macro:</u> <b>NL_ARGMAX</b></dt>
<dd><p>The value of <code>NL_ARGMAX</code> is the maximum value allowed for the
specification of an positional parameter in a <code>printf</code> call. The
actual value in effect at runtime can be retrieved by using
<code>sysconf</code> using the <code>_SC_NL_ARGMAX</code> parameter see section <a href="libc_31.html#Sysconf-Definition">Definition of <code>sysconf</code></a>.
</p>
<p>Some system have a quite low limit such as <em>9</em> for System V
systems. The GNU C library has no real limit.
</p></dd></dl>
<p>If any of the formats has a specification for the parameter position all
of them in the format string shall have one. Otherwise the behavior is
undefined.
</p>
</li><li>
Zero or more <em>flag characters</em> that modify the normal behavior of
the conversion specification.
<a name="index-flag-character-_0028printf_0029"></a>
</li><li>
An optional decimal integer specifying the <em>minimum field width</em>.
If the normal conversion produces fewer characters than this, the field
is padded with spaces to the specified width. This is a <em>minimum</em>
value; if the normal conversion produces more characters than this, the
field is <em>not</em> truncated. Normally, the output is right-justified
within the field.
<a name="index-minimum-field-width-_0028printf_0029"></a>
<p>You can also specify a field width of ‘<samp>*</samp>’. This means that the
next argument in the argument list (before the actual value to be
printed) is used as the field width. The value must be an <code>int</code>.
If the value is negative, this means to set the ‘<samp>-</samp>’ flag (see
below) and to use the absolute value as the field width.
</p>
</li><li>
An optional <em>precision</em> to specify the number of digits to be
written for the numeric conversions. If the precision is specified, it
consists of a period (‘<samp>.</samp>’) followed optionally by a decimal integer
(which defaults to zero if omitted).
<a name="index-precision-_0028printf_0029"></a>
<p>You can also specify a precision of ‘<samp>*</samp>’. This means that the next
argument in the argument list (before the actual value to be printed) is
used as the precision. The value must be an <code>int</code>, and is ignored
if it is negative. If you specify ‘<samp>*</samp>’ for both the field width and
precision, the field width argument precedes the precision argument.
Other C library versions may not recognize this syntax.
</p>
</li><li>
An optional <em>type modifier character</em>, which is used to specify the
data type of the corresponding argument if it differs from the default
type. (For example, the integer conversions assume a type of <code>int</code>,
but you can specify ‘<samp>h</samp>’, ‘<samp>l</samp>’, or ‘<samp>L</samp>’ for other integer
types.)
<a name="index-type-modifier-character-_0028printf_0029"></a>
</li><li>
A character that specifies the conversion to be applied.
</li></ul>
<p>The exact options that are permitted and how they are interpreted vary
between the different conversion specifiers. See the descriptions of the
individual conversions for information about the particular options that
they use.
</p>
<p>With the ‘<samp>-Wformat</samp>’ option, the GNU C compiler checks calls to
<code>printf</code> and related functions. It examines the format string and
verifies that the correct number and types of arguments are supplied.
There is also a GNU C syntax to tell the compiler that a function you
write uses a <code>printf</code>-style format string.
See <a href="../gcc/Function-Attributes.html#Function-Attributes">(gcc.info)Function Attributes</a> section ‘Declaring Attributes of Functions’ in <cite>Using GNU CC</cite>, for more information.
</p>
<hr size="6">
<a name="Table-of-Output-Conversions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Output-Conversion-Syntax" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Integer-Conversions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Table-of-Output-Conversions-1"></a>
<h3 class="subsection">12.12.3 Table of Output Conversions</h3>
<a name="index-output-conversions_002c-for-printf"></a>
<p>Here is a table summarizing what all the different conversions do:
</p>
<dl compact="compact">
<dt> ‘<samp>%d</samp>’, ‘<samp>%i</samp>’</dt>
<dd><p>Print an integer as a signed decimal number. See section <a href="#Integer-Conversions">Integer Conversions</a>, for details. ‘<samp>%d</samp>’ and ‘<samp>%i</samp>’ are synonymous for
output, but are different when used with <code>scanf</code> for input
(see section <a href="#Table-of-Input-Conversions">Table of Input Conversions</a>).
</p>
</dd>
<dt> ‘<samp>%o</samp>’</dt>
<dd><p>Print an integer as an unsigned octal number. See section <a href="#Integer-Conversions">Integer Conversions</a>, for details.
</p>
</dd>
<dt> ‘<samp>%u</samp>’</dt>
<dd><p>Print an integer as an unsigned decimal number. See section <a href="#Integer-Conversions">Integer Conversions</a>, for details.
</p>
</dd>
<dt> ‘<samp>%x</samp>’, ‘<samp>%X</samp>’</dt>
<dd><p>Print an integer as an unsigned hexadecimal number. ‘<samp>%x</samp>’ uses
lower-case letters and ‘<samp>%X</samp>’ uses upper-case. See section <a href="#Integer-Conversions">Integer Conversions</a>, for details.
</p>
</dd>
<dt> ‘<samp>%f</samp>’</dt>
<dd><p>Print a floating-point number in normal (fixed-point) notation.
See section <a href="#Floating_002dPoint-Conversions">Floating-Point Conversions</a>, for details.
</p>
</dd>
<dt> ‘<samp>%e</samp>’, ‘<samp>%E</samp>’</dt>
<dd><p>Print a floating-point number in exponential notation. ‘<samp>%e</samp>’ uses
lower-case letters and ‘<samp>%E</samp>’ uses upper-case. See section <a href="#Floating_002dPoint-Conversions">Floating-Point Conversions</a>, for details.
</p>
</dd>
<dt> ‘<samp>%g</samp>’, ‘<samp>%G</samp>’</dt>
<dd><p>Print a floating-point number in either normal or exponential notation,
whichever is more appropriate for its magnitude. ‘<samp>%g</samp>’ uses
lower-case letters and ‘<samp>%G</samp>’ uses upper-case. See section <a href="#Floating_002dPoint-Conversions">Floating-Point Conversions</a>, for details.
</p>
</dd>
<dt> ‘<samp>%a</samp>’, ‘<samp>%A</samp>’</dt>
<dd><p>Print a floating-point number in a hexadecimal fractional notation which
the exponent to base 2 represented in decimal digits. ‘<samp>%a</samp>’ uses
lower-case letters and ‘<samp>%A</samp>’ uses upper-case. See section <a href="#Floating_002dPoint-Conversions">Floating-Point Conversions</a>, for details.
</p>
</dd>
<dt> ‘<samp>%c</samp>’</dt>
<dd><p>Print a single character. See section <a href="#Other-Output-Conversions">Other Output Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%C</samp>’</dt>
<dd><p>This is an alias for ‘<samp>%lc</samp>’ which is supported for compatibility
with the Unix standard.
</p>
</dd>
<dt> ‘<samp>%s</samp>’</dt>
<dd><p>Print a string. See section <a href="#Other-Output-Conversions">Other Output Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%S</samp>’</dt>
<dd><p>This is an alias for ‘<samp>%ls</samp>’ which is supported for compatibility
with the Unix standard.
</p>
</dd>
<dt> ‘<samp>%p</samp>’</dt>
<dd><p>Print the value of a pointer. See section <a href="#Other-Output-Conversions">Other Output Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%n</samp>’</dt>
<dd><p>Get the number of characters printed so far. See section <a href="#Other-Output-Conversions">Other Output Conversions</a>.
Note that this conversion specification never produces any output.
</p>
</dd>
<dt> ‘<samp>%m</samp>’</dt>
<dd><p>Print the string corresponding to the value of <code>errno</code>.
(This is a GNU extension.)
See section <a href="#Other-Output-Conversions">Other Output Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%%</samp>’</dt>
<dd><p>Print a literal ‘<samp>%</samp>’ character. See section <a href="#Other-Output-Conversions">Other Output Conversions</a>.
</p></dd>
</dl>
<p>If the syntax of a conversion specification is invalid, unpredictable
things will happen, so don’t do this. If there aren’t enough function
arguments provided to supply values for all the conversion
specifications in the template string, or if the arguments are not of
the correct types, the results are unpredictable. If you supply more
arguments than conversion specifications, the extra argument values are
simply ignored; this is sometimes useful.
</p>
<hr size="6">
<a name="Integer-Conversions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Table-of-Output-Conversions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Floating_002dPoint-Conversions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Integer-Conversions-1"></a>
<h3 class="subsection">12.12.4 Integer Conversions</h3>
<p>This section describes the options for the ‘<samp>%d</samp>’, ‘<samp>%i</samp>’,
‘<samp>%o</samp>’, ‘<samp>%u</samp>’, ‘<samp>%x</samp>’, and ‘<samp>%X</samp>’ conversion
specifications. These conversions print integers in various formats.
</p>
<p>The ‘<samp>%d</samp>’ and ‘<samp>%i</samp>’ conversion specifications both print an
<code>int</code> argument as a signed decimal number; while ‘<samp>%o</samp>’,
‘<samp>%u</samp>’, and ‘<samp>%x</samp>’ print the argument as an unsigned octal,
decimal, or hexadecimal number (respectively). The ‘<samp>%X</samp>’ conversion
specification is just like ‘<samp>%x</samp>’ except that it uses the characters
‘<samp>ABCDEF</samp>’ as digits instead of ‘<samp>abcdef</samp>’.
</p>
<p>The following flags are meaningful:
</p>
<dl compact="compact">
<dt> ‘<samp>-</samp>’</dt>
<dd><p>Left-justify the result in the field (instead of the normal
right-justification).
</p>
</dd>
<dt> ‘<samp>+</samp>’</dt>
<dd><p>For the signed ‘<samp>%d</samp>’ and ‘<samp>%i</samp>’ conversions, print a
plus sign if the value is positive.
</p>
</dd>
<dt> ‘<samp> </samp>’</dt>
<dd><p>For the signed ‘<samp>%d</samp>’ and ‘<samp>%i</samp>’ conversions, if the result
doesn’t start with a plus or minus sign, prefix it with a space
character instead. Since the ‘<samp>+</samp>’ flag ensures that the result
includes a sign, this flag is ignored if you supply both of them.
</p>
</dd>
<dt> ‘<samp>#</samp>’</dt>
<dd><p>For the ‘<samp>%o</samp>’ conversion, this forces the leading digit to be
‘<samp>0</samp>’, as if by increasing the precision. For ‘<samp>%x</samp>’ or
‘<samp>%X</samp>’, this prefixes a leading ‘<samp>0x</samp>’ or ‘<samp>0X</samp>’ (respectively)
to the result. This doesn’t do anything useful for the ‘<samp>%d</samp>’,
‘<samp>%i</samp>’, or ‘<samp>%u</samp>’ conversions. Using this flag produces output
which can be parsed by the <code>strtoul</code> function (see section <a href="libc_20.html#Parsing-of-Integers">Parsing of Integers</a>) and <code>scanf</code> with the ‘<samp>%i</samp>’ conversion
(see section <a href="#Numeric-Input-Conversions">Numeric Input Conversions</a>).
</p>
</dd>
<dt> ‘<samp>'</samp>’</dt>
<dd><p>Separate the digits into groups as specified by the locale specified for
the <code>LC_NUMERIC</code> category; see section <a href="libc_7.html#General-Numeric">Generic Numeric Formatting Parameters</a>. This flag is a
GNU extension.
</p>
</dd>
<dt> ‘<samp>0</samp>’</dt>
<dd><p>Pad the field with zeros instead of spaces. The zeros are placed after
any indication of sign or base. This flag is ignored if the ‘<samp>-</samp>’
flag is also specified, or if a precision is specified.
</p></dd>
</dl>
<p>If a precision is supplied, it specifies the minimum number of digits to
appear; leading zeros are produced if necessary. If you don’t specify a
precision, the number is printed with as many digits as it needs. If
you convert a value of zero with an explicit precision of zero, then no
characters at all are produced.
</p>
<p>Without a type modifier, the corresponding argument is treated as an
<code>int</code> (for the signed conversions ‘<samp>%i</samp>’ and ‘<samp>%d</samp>’) or
<code>unsigned int</code> (for the unsigned conversions ‘<samp>%o</samp>’, ‘<samp>%u</samp>’,
‘<samp>%x</samp>’, and ‘<samp>%X</samp>’). Recall that since <code>printf</code> and friends
are variadic, any <code>char</code> and <code>short</code> arguments are
automatically converted to <code>int</code> by the default argument
promotions. For arguments of other integer types, you can use these
modifiers:
</p>
<dl compact="compact">
<dt> ‘<samp>hh</samp>’</dt>
<dd><p>Specifies that the argument is a <code>signed char</code> or <code>unsigned
char</code>, as appropriate. A <code>char</code> argument is converted to an
<code>int</code> or <code>unsigned int</code> by the default argument promotions
anyway, but the ‘<samp>h</samp>’ modifier says to convert it back to a
<code>char</code> again.
</p>
<p>This modifier was introduced in ISO C99.
</p>
</dd>
<dt> ‘<samp>h</samp>’</dt>
<dd><p>Specifies that the argument is a <code>short int</code> or <code>unsigned
short int</code>, as appropriate. A <code>short</code> argument is converted to an
<code>int</code> or <code>unsigned int</code> by the default argument promotions
anyway, but the ‘<samp>h</samp>’ modifier says to convert it back to a
<code>short</code> again.
</p>
</dd>
<dt> ‘<samp>j</samp>’</dt>
<dd><p>Specifies that the argument is a <code>intmax_t</code> or <code>uintmax_t</code>, as
appropriate.
</p>
<p>This modifier was introduced in ISO C99.
</p>
</dd>
<dt> ‘<samp>l</samp>’</dt>
<dd><p>Specifies that the argument is a <code>long int</code> or <code>unsigned long
int</code>, as appropriate. Two ‘<samp>l</samp>’ characters is like the ‘<samp>L</samp>’
modifier, below.
</p>
<p>If used with ‘<samp>%c</samp>’ or ‘<samp>%s</samp>’ the corresponding parameter is
considered as a wide character or wide character string respectively.
This use of ‘<samp>l</samp>’ was introduced in Amendment 1 to ISO C90.
</p>
</dd>
<dt> ‘<samp>L</samp>’</dt>
<dt> ‘<samp>ll</samp>’</dt>
<dt> ‘<samp>q</samp>’</dt>
<dd><p>Specifies that the argument is a <code>long long int</code>. (This type is
an extension supported by the GNU C compiler. On systems that don’t
support extra-long integers, this is the same as <code>long int</code>.)
</p>
<p>The ‘<samp>q</samp>’ modifier is another name for the same thing, which comes
from 4.4 BSD; a <code>long long int</code> is sometimes called a “quad”
<code>int</code>.
</p>
</dd>
<dt> ‘<samp>t</samp>’</dt>
<dd><p>Specifies that the argument is a <code>ptrdiff_t</code>.
</p>
<p>This modifier was introduced in ISO C99.
</p>
</dd>
<dt> ‘<samp>z</samp>’</dt>
<dt> ‘<samp>Z</samp>’</dt>
<dd><p>Specifies that the argument is a <code>size_t</code>.
</p>
<p>‘<samp>z</samp>’ was introduced in ISO C99. ‘<samp>Z</samp>’ is a GNU extension
predating this addition and should not be used in new code.
</p></dd>
</dl>
<p>Here is an example. Using the template string:
</p>
<table><tr><td> </td><td><pre class="smallexample">"|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
</pre></td></tr></table>
<p>to print numbers using the different options for the ‘<samp>%d</samp>’
conversion gives results like:
</p>
<table><tr><td> </td><td><pre class="smallexample">| 0|0 | +0|+0 | 0|00000| | 00|0|
| 1|1 | +1|+1 | 1|00001| 1| 01|1|
| -1|-1 | -1|-1 | -1|-0001| -1| -01|-1|
|100000|100000|+100000|+100000| 100000|100000|100000|100000|100000|
</pre></td></tr></table>
<p>In particular, notice what happens in the last case where the number
is too large to fit in the minimum field width specified.
</p>
<p>Here are some more examples showing how unsigned integers print under
various format options, using the template string:
</p>
<table><tr><td> </td><td><pre class="smallexample">"|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
</pre></td></tr></table>
<table><tr><td> </td><td><pre class="smallexample">| 0| 0| 0| 0| 0| 0| 0| 00000000|
| 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001|
|100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
</pre></td></tr></table>
<hr size="6">
<a name="Floating_002dPoint-Conversions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Integer-Conversions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Other-Output-Conversions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Floating_002dPoint-Conversions-1"></a>
<h3 class="subsection">12.12.5 Floating-Point Conversions</h3>
<p>This section discusses the conversion specifications for floating-point
numbers: the ‘<samp>%f</samp>’, ‘<samp>%e</samp>’, ‘<samp>%E</samp>’, ‘<samp>%g</samp>’, and ‘<samp>%G</samp>’
conversions.
</p>
<p>The ‘<samp>%f</samp>’ conversion prints its argument in fixed-point notation,
producing output of the form
[<code>-</code>]<var>ddd</var><code>.</code><var>ddd</var>,
where the number of digits following the decimal point is controlled
by the precision you specify.
</p>
<p>The ‘<samp>%e</samp>’ conversion prints its argument in exponential notation,
producing output of the form
[<code>-</code>]<var>d</var><code>.</code><var>ddd</var><code>e</code>[<code>+</code>|<code>-</code>]<var>dd</var>.
Again, the number of digits following the decimal point is controlled by
the precision. The exponent always contains at least two digits. The
‘<samp>%E</samp>’ conversion is similar but the exponent is marked with the letter
‘<samp>E</samp>’ instead of ‘<samp>e</samp>’.
</p>
<p>The ‘<samp>%g</samp>’ and ‘<samp>%G</samp>’ conversions print the argument in the style
of ‘<samp>%e</samp>’ or ‘<samp>%E</samp>’ (respectively) if the exponent would be less
than -4 or greater than or equal to the precision; otherwise they use
the ‘<samp>%f</samp>’ style. A precision of <code>0</code>, is taken as 1.
Trailing zeros are removed from the fractional portion of the result and
a decimal-point character appears only if it is followed by a digit.
</p>
<p>The ‘<samp>%a</samp>’ and ‘<samp>%A</samp>’ conversions are meant for representing
floating-point numbers exactly in textual form so that they can be
exchanged as texts between different programs and/or machines. The
numbers are represented is the form
[<code>-</code>]<code>0x</code><var>h</var><code>.</code><var>hhh</var><code>p</code>[<code>+</code>|<code>-</code>]<var>dd</var>.
At the left of the decimal-point character exactly one digit is print.
This character is only <code>0</code> if the number is denormalized.
Otherwise the value is unspecified; it is implementation dependent how many
bits are used. The number of hexadecimal digits on the right side of
the decimal-point character is equal to the precision. If the precision
is zero it is determined to be large enough to provide an exact
representation of the number (or it is large enough to distinguish two
adjacent values if the <code>FLT_RADIX</code> is not a power of 2,
see section <a href="libc_34.html#Floating-Point-Parameters">Floating Point Parameters</a>). For the ‘<samp>%a</samp>’ conversion
lower-case characters are used to represent the hexadecimal number and
the prefix and exponent sign are printed as <code>0x</code> and <code>p</code>
respectively. Otherwise upper-case characters are used and <code>0X</code>
and <code>P</code> are used for the representation of prefix and exponent
string. The exponent to the base of two is printed as a decimal number
using at least one digit but at most as many digits as necessary to
represent the value exactly.
</p>
<p>If the value to be printed represents infinity or a NaN, the output is
[<code>-</code>]<code>inf</code> or <code>nan</code> respectively if the conversion
specifier is ‘<samp>%a</samp>’, ‘<samp>%e</samp>’, ‘<samp>%f</samp>’, or ‘<samp>%g</samp>’ and it is
[<code>-</code>]<code>INF</code> or <code>NAN</code> respectively if the conversion is
‘<samp>%A</samp>’, ‘<samp>%E</samp>’, or ‘<samp>%G</samp>’.
</p>
<p>The following flags can be used to modify the behavior:
</p>
<dl compact="compact">
<dt> ‘<samp>-</samp>’</dt>
<dd><p>Left-justify the result in the field. Normally the result is
right-justified.
</p>
</dd>
<dt> ‘<samp>+</samp>’</dt>
<dd><p>Always include a plus or minus sign in the result.
</p>
</dd>
<dt> ‘<samp> </samp>’</dt>
<dd><p>If the result doesn’t start with a plus or minus sign, prefix it with a
space instead. Since the ‘<samp>+</samp>’ flag ensures that the result includes
a sign, this flag is ignored if you supply both of them.
</p>
</dd>
<dt> ‘<samp>#</samp>’</dt>
<dd><p>Specifies that the result should always include a decimal point, even
if no digits follow it. For the ‘<samp>%g</samp>’ and ‘<samp>%G</samp>’ conversions,
this also forces trailing zeros after the decimal point to be left
in place where they would otherwise be removed.
</p>
</dd>
<dt> ‘<samp>'</samp>’</dt>
<dd><p>Separate the digits of the integer part of the result into groups as
specified by the locale specified for the <code>LC_NUMERIC</code> category;
see section <a href="libc_7.html#General-Numeric">Generic Numeric Formatting Parameters</a>. This flag is a GNU extension.
</p>
</dd>
<dt> ‘<samp>0</samp>’</dt>
<dd><p>Pad the field with zeros instead of spaces; the zeros are placed
after any sign. This flag is ignored if the ‘<samp>-</samp>’ flag is also
specified.
</p></dd>
</dl>
<p>The precision specifies how many digits follow the decimal-point
character for the ‘<samp>%f</samp>’, ‘<samp>%e</samp>’, and ‘<samp>%E</samp>’ conversions. For
these conversions, the default precision is <code>6</code>. If the precision
is explicitly <code>0</code>, this suppresses the decimal point character
entirely. For the ‘<samp>%g</samp>’ and ‘<samp>%G</samp>’ conversions, the precision
specifies how many significant digits to print. Significant digits are
the first digit before the decimal point, and all the digits after it.
If the precision is <code>0</code> or not specified for ‘<samp>%g</samp>’ or ‘<samp>%G</samp>’,
it is treated like a value of <code>1</code>. If the value being printed
cannot be expressed accurately in the specified number of digits, the
value is rounded to the nearest number that fits.
</p>
<p>Without a type modifier, the floating-point conversions use an argument
of type <code>double</code>. (By the default argument promotions, any
<code>float</code> arguments are automatically converted to <code>double</code>.)
The following type modifier is supported:
</p>
<dl compact="compact">
<dt> ‘<samp>L</samp>’</dt>
<dd><p>An uppercase ‘<samp>L</samp>’ specifies that the argument is a <code>long
double</code>.
</p></dd>
</dl>
<p>Here are some examples showing how numbers print using the various
floating-point conversions. All of the numbers were printed using
this template string:
</p>
<table><tr><td> </td><td><pre class="smallexample">"|%13.4a|%13.4f|%13.4e|%13.4g|\n"
</pre></td></tr></table>
<p>Here is the output:
</p>
<table><tr><td> </td><td><pre class="smallexample">| 0x0.0000p+0| 0.0000| 0.0000e+00| 0|
| 0x1.0000p-1| 0.5000| 5.0000e-01| 0.5|
| 0x1.0000p+0| 1.0000| 1.0000e+00| 1|
| -0x1.0000p+0| -1.0000| -1.0000e+00| -1|
| 0x1.9000p+6| 100.0000| 1.0000e+02| 100|
| 0x1.f400p+9| 1000.0000| 1.0000e+03| 1000|
| 0x1.3880p+13| 10000.0000| 1.0000e+04| 1e+04|
| 0x1.81c8p+13| 12345.0000| 1.2345e+04| 1.234e+04|
| 0x1.86a0p+16| 100000.0000| 1.0000e+05| 1e+05|
| 0x1.e240p+16| 123456.0000| 1.2346e+05| 1.235e+05|
</pre></td></tr></table>
<p>Notice how the ‘<samp>%g</samp>’ conversion drops trailing zeros.
</p>
<hr size="6">
<a name="Other-Output-Conversions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Floating_002dPoint-Conversions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output-Functions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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-Output-Conversions-1"></a>
<h3 class="subsection">12.12.6 Other Output Conversions</h3>
<p>This section describes miscellaneous conversions for <code>printf</code>.
</p>
<p>The ‘<samp>%c</samp>’ conversion prints a single character. In case there is no
‘<samp>l</samp>’ modifier the <code>int</code> argument is first converted to an
<code>unsigned char</code>. Then, if used in a wide stream function, the
character is converted into the corresponding wide character. The
‘<samp>-</samp>’ flag can be used to specify left-justification in the field,
but no other flags are defined, and no precision or type modifier can be
given. For example:
</p>
<table><tr><td> </td><td><pre class="smallexample">printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
</pre></td></tr></table>
<p>prints ‘<samp>hello</samp>’.
</p>
<p>If there is a ‘<samp>l</samp>’ modifier present the argument is expected to be
of type <code>wint_t</code>. If used in a multibyte function the wide
character is converted into a multibyte character before being added to
the output. In this case more than one output byte can be produced.
</p>
<p>The ‘<samp>%s</samp>’ conversion prints a string. If no ‘<samp>l</samp>’ modifier is
present the corresponding argument must be of type <code>char *</code> (or
<code>const char *</code>). If used in a wide stream function the string is
first converted in a wide character string. A precision can be
specified to indicate the maximum number of characters to write;
otherwise characters in the string up to but not including the
terminating null character are written to the output stream. The
‘<samp>-</samp>’ flag can be used to specify left-justification in the field,
but no other flags or type modifiers are defined for this conversion.
For example:
</p>
<table><tr><td> </td><td><pre class="smallexample">printf ("%3s%-6s", "no", "where");
</pre></td></tr></table>
<p>prints ‘<samp> nowhere </samp>’.
</p>
<p>If there is a ‘<samp>l</samp>’ modifier present the argument is expected to be of type <code>wchar_t</code> (or <code>const wchar_t *</code>).
</p>
<p>If you accidentally pass a null pointer as the argument for a ‘<samp>%s</samp>’
conversion, the GNU library prints it as ‘<samp>(null)</samp>’. We think this
is more useful than crashing. But it’s not good practice to pass a null
argument intentionally.
</p>
<p>The ‘<samp>%m</samp>’ conversion prints the string corresponding to the error
code in <code>errno</code>. See section <a href="libc_2.html#Error-Messages">Error Messages</a>. Thus:
</p>
<table><tr><td> </td><td><pre class="smallexample">fprintf (stderr, "can't open `%s': %m\n", filename);
</pre></td></tr></table>
<p>is equivalent to:
</p>
<table><tr><td> </td><td><pre class="smallexample">fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
</pre></td></tr></table>
<p>The ‘<samp>%m</samp>’ conversion is a GNU C library extension.
</p>
<p>The ‘<samp>%p</samp>’ conversion prints a pointer value. The corresponding
argument must be of type <code>void *</code>. In practice, you can use any
type of pointer.
</p>
<p>In the GNU system, non-null pointers are printed as unsigned integers,
as if a ‘<samp>%#x</samp>’ conversion were used. Null pointers print as
‘<samp>(nil)</samp>’. (Pointers might print differently in other systems.)
</p>
<p>For example:
</p>
<table><tr><td> </td><td><pre class="smallexample">printf ("%p", "testing");
</pre></td></tr></table>
<p>prints ‘<samp>0x</samp>’ followed by a hexadecimal number—the address of the
string constant <code>"testing"</code>. It does not print the word
‘<samp>testing</samp>’.
</p>
<p>You can supply the ‘<samp>-</samp>’ flag with the ‘<samp>%p</samp>’ conversion to
specify left-justification, but no other flags, precision, or type
modifiers are defined.
</p>
<p>The ‘<samp>%n</samp>’ conversion is unlike any of the other output conversions.
It uses an argument which must be a pointer to an <code>int</code>, but
instead of printing anything it stores the number of characters printed
so far by this call at that location. The ‘<samp>h</samp>’ and ‘<samp>l</samp>’ type
modifiers are permitted to specify that the argument is of type
<code>short int *</code> or <code>long int *</code> instead of <code>int *</code>, but no
flags, field width, or precision are permitted.
</p>
<p>For example,
</p>
<table><tr><td> </td><td><pre class="smallexample">int nchar;
printf ("%d %s%n\n", 3, "bears", &nchar);
</pre></td></tr></table>
<p>prints:
</p>
<table><tr><td> </td><td><pre class="smallexample">3 bears
</pre></td></tr></table>
<p>and sets <code>nchar</code> to <code>7</code>, because ‘<samp>3 bears</samp>’ is seven
characters.
</p>
<p>The ‘<samp>%%</samp>’ conversion prints a literal ‘<samp>%</samp>’ character. This
conversion doesn’t use an argument, and no flags, field width,
precision, or type modifiers are permitted.
</p>
<hr size="6">
<a name="Formatted-Output-Functions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Other-Output-Conversions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Dynamic-Output" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Formatted-Output-Functions-1"></a>
<h3 class="subsection">12.12.7 Formatted Output Functions</h3>
<p>This section describes how to call <code>printf</code> and related functions.
Prototypes for these functions are in the header file ‘<tt>stdio.h</tt>’.
Because these functions take a variable number of arguments, you
<em>must</em> declare prototypes for them before using them. Of course,
the easiest way to make sure you have all the right prototypes is to
just include ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-6"></a>
</p>
<dl>
<dt><a name="index-printf"></a><u>Function:</u> int <b>printf</b><i> (const char *<var>template</var>, …)</i></dt>
<dd><p>The <code>printf</code> function prints the optional arguments under the
control of the template string <var>template</var> to the stream
<code>stdout</code>. It returns the number of characters printed, or a
negative value if there was an output error.
</p></dd></dl>
<dl>
<dt><a name="index-wprintf"></a><u>Function:</u> int <b>wprintf</b><i> (const wchar_t *<var>template</var>, …)</i></dt>
<dd><p>The <code>wprintf</code> function prints the optional arguments under the
control of the wide template string <var>template</var> to the stream
<code>stdout</code>. It returns the number of wide characters printed, or a
negative value if there was an output error.
</p></dd></dl>
<dl>
<dt><a name="index-fprintf"></a><u>Function:</u> int <b>fprintf</b><i> (FILE *<var>stream</var>, const char *<var>template</var>, …)</i></dt>
<dd><p>This function is just like <code>printf</code>, except that the output is
written to the stream <var>stream</var> instead of <code>stdout</code>.
</p></dd></dl>
<dl>
<dt><a name="index-fwprintf"></a><u>Function:</u> int <b>fwprintf</b><i> (FILE *<var>stream</var>, const wchar_t *<var>template</var>, …)</i></dt>
<dd><p>This function is just like <code>wprintf</code>, except that the output is
written to the stream <var>stream</var> instead of <code>stdout</code>.
</p></dd></dl>
<dl>
<dt><a name="index-sprintf"></a><u>Function:</u> int <b>sprintf</b><i> (char *<var>s</var>, const char *<var>template</var>, …)</i></dt>
<dd><p>This is like <code>printf</code>, except that the output is stored in the character
array <var>s</var> instead of written to a stream. A null character is written
to mark the end of the string.
</p>
<p>The <code>sprintf</code> function returns the number of characters stored in
the array <var>s</var>, not including the terminating null character.
</p>
<p>The behavior of this function is undefined if copying takes place
between objects that overlap—for example, if <var>s</var> is also given
as an argument to be printed under control of the ‘<samp>%s</samp>’ conversion.
See section <a href="libc_5.html#Copying-and-Concatenation">Copying and Concatenation</a>.
</p>
<p><strong>Warning:</strong> The <code>sprintf</code> function can be <strong>dangerous</strong>
because it can potentially output more characters than can fit in the
allocation size of the string <var>s</var>. Remember that the field width
given in a conversion specification is only a <em>minimum</em> value.
</p>
<p>To avoid this problem, you can use <code>snprintf</code> or <code>asprintf</code>,
described below.
</p></dd></dl>
<dl>
<dt><a name="index-swprintf"></a><u>Function:</u> int <b>swprintf</b><i> (wchar_t *<var>s</var>, size_t <var>size</var>, const wchar_t *<var>template</var>, …)</i></dt>
<dd><p>This is like <code>wprintf</code>, except that the output is stored in the
wide character array <var>ws</var> instead of written to a stream. A null
wide character is written to mark the end of the string. The <var>size</var>
argument specifies the maximum number of characters to produce. The
trailing null character is counted towards this limit, so you should
allocate at least <var>size</var> wide characters for the string <var>ws</var>.
</p>
<p>The return value is the number of characters generated for the given
input, excluding the trailing null. If not all output fits into the
provided buffer a negative value is returned. You should try again with
a bigger output string. <em>Note:</em> this is different from how
<code>snprintf</code> handles this situation.
</p>
<p>Note that the corresponding narrow stream function takes fewer
parameters. <code>swprintf</code> in fact corresponds to the <code>snprintf</code>
function. Since the <code>sprintf</code> function can be dangerous and should
be avoided the ISO C committee refused to make the same mistake
again and decided to not define an function exactly corresponding to
<code>sprintf</code>.
</p></dd></dl>
<dl>
<dt><a name="index-snprintf"></a><u>Function:</u> int <b>snprintf</b><i> (char *<var>s</var>, size_t <var>size</var>, const char *<var>template</var>, …)</i></dt>
<dd><p>The <code>snprintf</code> function is similar to <code>sprintf</code>, except that
the <var>size</var> argument specifies the maximum number of characters to
produce. The trailing null character is counted towards this limit, so
you should allocate at least <var>size</var> characters for the string <var>s</var>.
</p>
<p>The return value is the number of characters which would be generated
for the given input, excluding the trailing null. If this value is
greater or equal to <var>size</var>, not all characters from the result have
been stored in <var>s</var>. You should try again with a bigger output
string. Here is an example of doing this:
</p>
<table><tr><td> </td><td><pre class="smallexample">/* <span class="roman">Construct a message describing the value of a variable</span>
<span class="roman">whose name is <var>name</var> and whose value is <var>value</var>.</span> */
char *
make_message (char *name, char *value)
{
/* <span class="roman">Guess we need no more than 100 chars of space.</span> */
int size = 100;
char *buffer = (char *) xmalloc (size);
int nchars;
</pre><pre class="smallexample"> if (buffer == NULL)
return NULL;
/* <span class="roman">Try to print in the allocated space.</span> */
nchars = snprintf (buffer, size, "value of %s is %s",
name, value);
</pre><pre class="smallexample"> if (nchars >= size)
{
/* <span class="roman">Reallocate buffer now that we know
how much space is needed.</span> */
size = nchars + 1;
buffer = (char *) xrealloc (buffer, size);
if (buffer != NULL)
/* <span class="roman">Try again.</span> */
snprintf (buffer, size, "value of %s is %s",
name, value);
}
/* <span class="roman">The last call worked, return the string.</span> */
return buffer;
}
</pre></td></tr></table>
<p>In practice, it is often easier just to use <code>asprintf</code>, below.
</p>
<p><strong>Attention:</strong> In versions of the GNU C library prior to 2.1 the
return value is the number of characters stored, not including the
terminating null; unless there was not enough space in <var>s</var> to
store the result in which case <code>-1</code> is returned. This was
changed in order to comply with the ISO C99 standard.
</p></dd></dl>
<hr size="6">
<a name="Dynamic-Output"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Formatted-Output-Functions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Variable-Arguments-Output" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Dynamically-Allocating-Formatted-Output"></a>
<h3 class="subsection">12.12.8 Dynamically Allocating Formatted Output</h3>
<p>The functions in this section do formatted output and place the results
in dynamically allocated memory.
</p>
<dl>
<dt><a name="index-asprintf"></a><u>Function:</u> int <b>asprintf</b><i> (char **<var>ptr</var>, const char *<var>template</var>, …)</i></dt>
<dd><p>This function is similar to <code>sprintf</code>, except that it dynamically
allocates a string (as with <code>malloc</code>; see section <a href="libc_3.html#Unconstrained-Allocation">Unconstrained Allocation</a>) to hold the output, instead of putting the output in a
buffer you allocate in advance. The <var>ptr</var> argument should be the
address of a <code>char *</code> object, and a successful call to
<code>asprintf</code> stores a pointer to the newly allocated string at that
location.
</p>
<p>The return value is the number of characters allocated for the buffer, or
less than zero if an error occurred. Usually this means that the buffer
could not be allocated.
</p>
<p>Here is how to use <code>asprintf</code> to get the same result as the
<code>snprintf</code> example, but more easily:
</p>
<table><tr><td> </td><td><pre class="smallexample">/* <span class="roman">Construct a message describing the value of a variable</span>
<span class="roman">whose name is <var>name</var> and whose value is <var>value</var>.</span> */
char *
make_message (char *name, char *value)
{
char *result;
if (asprintf (&result, "value of %s is %s", name, value) < 0)
return NULL;
return result;
}
</pre></td></tr></table>
</dd></dl>
<dl>
<dt><a name="index-obstack_005fprintf"></a><u>Function:</u> int <b>obstack_printf</b><i> (struct obstack *<var>obstack</var>, const char *<var>template</var>, …)</i></dt>
<dd><p>This function is similar to <code>asprintf</code>, except that it uses the
obstack <var>obstack</var> to allocate the space. See section <a href="libc_3.html#Obstacks">Obstacks</a>.
</p>
<p>The characters are written onto the end of the current object.
To get at them, you must finish the object with <code>obstack_finish</code>
(see section <a href="libc_3.html#Growing-Objects">Growing Objects</a>).
</p></dd></dl>
<hr size="6">
<a name="Variable-Arguments-Output"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Dynamic-Output" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Parsing-a-Template-String" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Variable-Arguments-Output-Functions"></a>
<h3 class="subsection">12.12.9 Variable Arguments Output Functions</h3>
<p>The functions <code>vprintf</code> and friends are provided so that you can
define your own variadic <code>printf</code>-like functions that make use of
the same internals as the built-in formatted output functions.
</p>
<p>The most natural way to define such functions would be to use a language
construct to say, “Call <code>printf</code> and pass this template plus all
of my arguments after the first five.” But there is no way to do this
in C, and it would be hard to provide a way, since at the C language
level there is no way to tell how many arguments your function received.
</p>
<p>Since that method is impossible, we provide alternative functions, the
<code>vprintf</code> series, which lets you pass a <code>va_list</code> to describe
“all of my arguments after the first five.”
</p>
<p>When it is sufficient to define a macro rather than a real function,
the GNU C compiler provides a way to do this much more easily with macros.
For example:
</p>
<table><tr><td> </td><td><pre class="smallexample">#define myprintf(a, b, c, d, e, rest...) \
printf (mytemplate , ## rest)
</pre></td></tr></table>
<p>See <a href="../cpp/Variadic-Macros.html#Variadic-Macros">(cpp)Variadic Macros</a> section ‘Variadic Macros’ in <cite>The C preprocessor</cite>, for details.
But this is limited to macros, and does not apply to real functions at all.
</p>
<p>Before calling <code>vprintf</code> or the other functions listed in this
section, you <em>must</em> call <code>va_start</code> (see section <a href="libc_34.html#Variadic-Functions">Variadic Functions</a>) to initialize a pointer to the variable arguments. Then you
can call <code>va_arg</code> to fetch the arguments that you want to handle
yourself. This advances the pointer past those arguments.
</p>
<p>Once your <code>va_list</code> pointer is pointing at the argument of your
choice, you are ready to call <code>vprintf</code>. That argument and all
subsequent arguments that were passed to your function are used by
<code>vprintf</code> along with the template that you specified separately.
</p>
<p>In some other systems, the <code>va_list</code> pointer may become invalid
after the call to <code>vprintf</code>, so you must not use <code>va_arg</code>
after you call <code>vprintf</code>. Instead, you should call <code>va_end</code>
to retire the pointer from service. However, you can safely call
<code>va_start</code> on another pointer variable and begin fetching the
arguments again through that pointer. Calling <code>vprintf</code> does not
destroy the argument list of your function, merely the particular
pointer that you passed to it.
</p>
<p>GNU C does not have such restrictions. You can safely continue to fetch
arguments from a <code>va_list</code> pointer after passing it to
<code>vprintf</code>, and <code>va_end</code> is a no-op. (Note, however, that
subsequent <code>va_arg</code> calls will fetch the same arguments which
<code>vprintf</code> previously used.)
</p>
<p>Prototypes for these functions are declared in ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-7"></a>
</p>
<dl>
<dt><a name="index-vprintf"></a><u>Function:</u> int <b>vprintf</b><i> (const char *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This function is similar to <code>printf</code> except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer <var>ap</var>.
</p></dd></dl>
<dl>
<dt><a name="index-vwprintf"></a><u>Function:</u> int <b>vwprintf</b><i> (const wchar_t *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This function is similar to <code>wprintf</code> except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer <var>ap</var>.
</p></dd></dl>
<dl>
<dt><a name="index-vfprintf"></a><u>Function:</u> int <b>vfprintf</b><i> (FILE *<var>stream</var>, const char *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This is the equivalent of <code>fprintf</code> with the variable argument list
specified directly as for <code>vprintf</code>.
</p></dd></dl>
<dl>
<dt><a name="index-vfwprintf"></a><u>Function:</u> int <b>vfwprintf</b><i> (FILE *<var>stream</var>, const wchar_t *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This is the equivalent of <code>fwprintf</code> with the variable argument list
specified directly as for <code>vwprintf</code>.
</p></dd></dl>
<dl>
<dt><a name="index-vsprintf"></a><u>Function:</u> int <b>vsprintf</b><i> (char *<var>s</var>, const char *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This is the equivalent of <code>sprintf</code> with the variable argument list
specified directly as for <code>vprintf</code>.
</p></dd></dl>
<dl>
<dt><a name="index-vswprintf"></a><u>Function:</u> int <b>vswprintf</b><i> (wchar_t *<var>s</var>, size_t <var>size</var>, const wchar_t *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This is the equivalent of <code>swprintf</code> with the variable argument list
specified directly as for <code>vwprintf</code>.
</p></dd></dl>
<dl>
<dt><a name="index-vsnprintf"></a><u>Function:</u> int <b>vsnprintf</b><i> (char *<var>s</var>, size_t <var>size</var>, const char *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This is the equivalent of <code>snprintf</code> with the variable argument list
specified directly as for <code>vprintf</code>.
</p></dd></dl>
<dl>
<dt><a name="index-vasprintf"></a><u>Function:</u> int <b>vasprintf</b><i> (char **<var>ptr</var>, const char *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>The <code>vasprintf</code> function is the equivalent of <code>asprintf</code> with the
variable argument list specified directly as for <code>vprintf</code>.
</p></dd></dl>
<dl>
<dt><a name="index-obstack_005fvprintf"></a><u>Function:</u> int <b>obstack_vprintf</b><i> (struct obstack *<var>obstack</var>, const char *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>The <code>obstack_vprintf</code> function is the equivalent of
<code>obstack_printf</code> with the variable argument list specified directly
as for <code>vprintf</code>.
</p></dd></dl>
<p>Here’s an example showing how you might use <code>vfprintf</code>. This is a
function that prints error messages to the stream <code>stderr</code>, along
with a prefix indicating the name of the program
(see section <a href="libc_2.html#Error-Messages">Error Messages</a>, for a description of
<code>program_invocation_short_name</code>).
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <stdio.h>
#include <stdarg.h>
void
eprintf (const char *template, ...)
{
va_list ap;
extern char *program_invocation_short_name;
fprintf (stderr, "%s: ", program_invocation_short_name);
va_start (ap, template);
vfprintf (stderr, template, ap);
va_end (ap);
}
</pre></td></tr></table>
<p>You could call <code>eprintf</code> like this:
</p>
<table><tr><td> </td><td><pre class="smallexample">eprintf ("file `%s' does not exist\n", filename);
</pre></td></tr></table>
<p>In GNU C, there is a special construct you can use to let the compiler
know that a function uses a <code>printf</code>-style format string. Then it
can check the number and types of arguments in each call to the
function, and warn you when they do not match the format string.
For example, take this declaration of <code>eprintf</code>:
</p>
<table><tr><td> </td><td><pre class="smallexample">void eprintf (const char *template, ...)
__attribute__ ((format (printf, 1, 2)));
</pre></td></tr></table>
<p>This tells the compiler that <code>eprintf</code> uses a format string like
<code>printf</code> (as opposed to <code>scanf</code>; see section <a href="#Formatted-Input">Formatted Input</a>);
the format string appears as the first argument;
and the arguments to satisfy the format begin with the second.
See <a href="../gcc/Function-Attributes.html#Function-Attributes">(gcc.info)Function Attributes</a> section ‘Declaring Attributes of Functions’ in <cite>Using GNU CC</cite>, for more information.
</p>
<hr size="6">
<a name="Parsing-a-Template-String"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Variable-Arguments-Output" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Example-of-Parsing" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Parsing-a-Template-String-1"></a>
<h3 class="subsection">12.12.10 Parsing a Template String</h3>
<a name="index-parsing-a-template-string"></a>
<p>You can use the function <code>parse_printf_format</code> to obtain
information about the number and types of arguments that are expected by
a given template string. This function permits interpreters that
provide interfaces to <code>printf</code> to avoid passing along invalid
arguments from the user’s program, which could cause a crash.
</p>
<p>All the symbols described in this section are declared in the header
file ‘<tt>printf.h</tt>’.
</p>
<dl>
<dt><a name="index-parse_005fprintf_005fformat"></a><u>Function:</u> size_t <b>parse_printf_format</b><i> (const char *<var>template</var>, size_t <var>n</var>, int *<var>argtypes</var>)</i></dt>
<dd><p>This function returns information about the number and types of
arguments expected by the <code>printf</code> template string <var>template</var>.
The information is stored in the array <var>argtypes</var>; each element of
this array describes one argument. This information is encoded using
the various ‘<samp>PA_</samp>’ macros, listed below.
</p>
<p>The argument <var>n</var> specifies the number of elements in the array
<var>argtypes</var>. This is the maximum number of elements that
<code>parse_printf_format</code> will try to write.
</p>
<p><code>parse_printf_format</code> returns the total number of arguments required
by <var>template</var>. If this number is greater than <var>n</var>, then the
information returned describes only the first <var>n</var> arguments. If you
want information about additional arguments, allocate a bigger
array and call <code>parse_printf_format</code> again.
</p></dd></dl>
<p>The argument types are encoded as a combination of a basic type and
modifier flag bits.
</p>
<dl>
<dt><a name="index-PA_005fFLAG_005fMASK"></a><u>Macro:</u> int <b>PA_FLAG_MASK</b></dt>
<dd><p>This macro is a bitmask for the type modifier flag bits. You can write
the expression <code>(argtypes[i] & PA_FLAG_MASK)</code> to extract just the
flag bits for an argument, or <code>(argtypes[i] & ~PA_FLAG_MASK)</code> to
extract just the basic type code.
</p></dd></dl>
<p>Here are symbolic constants that represent the basic types; they stand
for integer values.
</p>
<dl compact="compact">
<dt> <code>PA_INT</code>
<a name="index-PA_005fINT"></a>
</dt>
<dd><p>This specifies that the base type is <code>int</code>.
</p>
</dd>
<dt> <code>PA_CHAR</code>
<a name="index-PA_005fCHAR"></a>
</dt>
<dd><p>This specifies that the base type is <code>int</code>, cast to <code>char</code>.
</p>
</dd>
<dt> <code>PA_STRING</code>
<a name="index-PA_005fSTRING"></a>
</dt>
<dd><p>This specifies that the base type is <code>char *</code>, a null-terminated string.
</p>
</dd>
<dt> <code>PA_POINTER</code>
<a name="index-PA_005fPOINTER"></a>
</dt>
<dd><p>This specifies that the base type is <code>void *</code>, an arbitrary pointer.
</p>
</dd>
<dt> <code>PA_FLOAT</code>
<a name="index-PA_005fFLOAT"></a>
</dt>
<dd><p>This specifies that the base type is <code>float</code>.
</p>
</dd>
<dt> <code>PA_DOUBLE</code>
<a name="index-PA_005fDOUBLE"></a>
</dt>
<dd><p>This specifies that the base type is <code>double</code>.
</p>
</dd>
<dt> <code>PA_LAST</code>
<a name="index-PA_005fLAST"></a>
</dt>
<dd><p>You can define additional base types for your own programs as offsets
from <code>PA_LAST</code>. For example, if you have data types ‘<samp>foo</samp>’
and ‘<samp>bar</samp>’ with their own specialized <code>printf</code> conversions,
you could define encodings for these types as:
</p>
<table><tr><td> </td><td><pre class="smallexample">#define PA_FOO PA_LAST
#define PA_BAR (PA_LAST + 1)
</pre></td></tr></table>
</dd>
</dl>
<p>Here are the flag bits that modify a basic type. They are combined with
the code for the basic type using inclusive-or.
</p>
<dl compact="compact">
<dt> <code>PA_FLAG_PTR</code>
<a name="index-PA_005fFLAG_005fPTR"></a>
</dt>
<dd><p>If this bit is set, it indicates that the encoded type is a pointer to
the base type, rather than an immediate value.
For example, ‘<samp>PA_INT|PA_FLAG_PTR</samp>’ represents the type ‘<samp>int *</samp>’.
</p>
</dd>
<dt> <code>PA_FLAG_SHORT</code>
<a name="index-PA_005fFLAG_005fSHORT"></a>
</dt>
<dd><p>If this bit is set, it indicates that the base type is modified with
<code>short</code>. (This corresponds to the ‘<samp>h</samp>’ type modifier.)
</p>
</dd>
<dt> <code>PA_FLAG_LONG</code>
<a name="index-PA_005fFLAG_005fLONG"></a>
</dt>
<dd><p>If this bit is set, it indicates that the base type is modified with
<code>long</code>. (This corresponds to the ‘<samp>l</samp>’ type modifier.)
</p>
</dd>
<dt> <code>PA_FLAG_LONG_LONG</code>
<a name="index-PA_005fFLAG_005fLONG_005fLONG"></a>
</dt>
<dd><p>If this bit is set, it indicates that the base type is modified with
<code>long long</code>. (This corresponds to the ‘<samp>L</samp>’ type modifier.)
</p>
</dd>
<dt> <code>PA_FLAG_LONG_DOUBLE</code>
<a name="index-PA_005fFLAG_005fLONG_005fDOUBLE"></a>
</dt>
<dd><p>This is a synonym for <code>PA_FLAG_LONG_LONG</code>, used by convention with
a base type of <code>PA_DOUBLE</code> to indicate a type of <code>long double</code>.
</p></dd>
</dl>
<hr size="6">
<a name="Example-of-Parsing"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Parsing-a-Template-String" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Customizing-Printf" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Output" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Example-of-Parsing-a-Template-String"></a>
<h3 class="subsection">12.12.11 Example of Parsing a Template String</h3>
<p>Here is an example of decoding argument types for a format string. We
assume this is part of an interpreter which contains arguments of type
<code>NUMBER</code>, <code>CHAR</code>, <code>STRING</code> and <code>STRUCTURE</code> (and
perhaps others which are not valid here).
</p>
<table><tr><td> </td><td><pre class="smallexample">/* <span class="roman">Test whether the <var>nargs</var> specified objects</span>
<span class="roman">in the vector <var>args</var> are valid</span>
<span class="roman">for the format string <var>format</var>:</span>
<span class="roman">if so, return 1.</span>
<span class="roman">If not, return 0 after printing an error message.</span> */
int
validate_args (char *format, int nargs, OBJECT *args)
{
int *argtypes;
int nwanted;
/* <span class="roman">Get the information about the arguments.</span>
<span class="roman">Each conversion specification must be at least two characters</span>
<span class="roman">long, so there cannot be more specifications than half the</span>
<span class="roman">length of the string.</span> */
argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
nwanted = parse_printf_format (string, nelts, argtypes);
/* <span class="roman">Check the number of arguments.</span> */
if (nwanted > nargs)
{
error ("too few arguments (at least %d required)", nwanted);
return 0;
}
/* <span class="roman">Check the C type wanted for each argument</span>
<span class="roman">and see if the object given is suitable.</span> */
for (i = 0; i < nwanted; i++)
{
int wanted;
if (argtypes[i] & PA_FLAG_PTR)
wanted = STRUCTURE;
else
switch (argtypes[i] & ~PA_FLAG_MASK)
{
case PA_INT:
case PA_FLOAT:
case PA_DOUBLE:
wanted = NUMBER;
break;
case PA_CHAR:
wanted = CHAR;
break;
case PA_STRING:
wanted = STRING;
break;
case PA_POINTER:
wanted = STRUCTURE;
break;
}
if (TYPE (args[i]) != wanted)
{
error ("type mismatch for arg number %d", i);
return 0;
}
}
return 1;
}
</pre></td></tr></table>
<hr size="6">
<a name="Customizing-Printf"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Example-of-Parsing" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Registering-New-Conversions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Customizing-printf"></a>
<h2 class="section">12.13 Customizing <code>printf</code></h2>
<a name="index-customizing-printf"></a>
<a name="index-defining-new-printf-conversions"></a>
<a name="index-extending-printf"></a>
<p>The GNU C library lets you define your own custom conversion specifiers
for <code>printf</code> template strings, to teach <code>printf</code> clever ways
to print the important data structures of your program.
</p>
<p>The way you do this is by registering the conversion with the function
<code>register_printf_function</code>; see <a href="#Registering-New-Conversions">Registering New Conversions</a>.
One of the arguments you pass to this function is a pointer to a handler
function that produces the actual output; see <a href="#Defining-the-Output-Handler">Defining the Output Handler</a>, for information on how to write this function.
</p>
<p>You can also install a function that just returns information about the
number and type of arguments expected by the conversion specifier.
See section <a href="#Parsing-a-Template-String">Parsing a Template String</a>, for information about this.
</p>
<p>The facilities of this section are declared in the header file
‘<tt>printf.h</tt>’.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Registering-New-Conversions">12.13.1 Registering New Conversions</a></td><td> </td><td align="left" valign="top"> Using <code>register_printf_function</code>
to register a new output conversion.
</td></tr>
<tr><td align="left" valign="top"><a href="#Conversion-Specifier-Options">12.13.2 Conversion Specifier Options</a></td><td> </td><td align="left" valign="top"> The handler must be able to get
the options specified in the
template when it is called.
</td></tr>
<tr><td align="left" valign="top"><a href="#Defining-the-Output-Handler">12.13.3 Defining the Output Handler</a></td><td> </td><td align="left" valign="top"> Defining the handler and arginfo
functions that are passed as arguments
to <code>register_printf_function</code>.
</td></tr>
<tr><td align="left" valign="top"><a href="#Printf-Extension-Example">12.13.4 <code>printf</code> Extension Example</a></td><td> </td><td align="left" valign="top"> How to define a <code>printf</code>
handler function.
</td></tr>
<tr><td align="left" valign="top"><a href="#Predefined-Printf-Handlers">12.13.5 Predefined <code>printf</code> Handlers</a></td><td> </td><td align="left" valign="top"> Predefined <code>printf</code> handlers.
</td></tr>
</table>
<p><strong>Portability Note:</strong> The ability to extend the syntax of
<code>printf</code> template strings is a GNU extension. ISO standard C has
nothing similar.
</p>
<hr size="6">
<a name="Registering-New-Conversions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Customizing-Printf" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Conversion-Specifier-Options" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Customizing-Printf" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Registering-New-Conversions-1"></a>
<h3 class="subsection">12.13.1 Registering New Conversions</h3>
<p>The function to register a new output conversion is
<code>register_printf_function</code>, declared in ‘<tt>printf.h</tt>’.
<a name="index-printf_002eh"></a>
</p>
<dl>
<dt><a name="index-register_005fprintf_005ffunction"></a><u>Function:</u> int <b>register_printf_function</b><i> (int <var>spec</var>, printf_function <var>handler-function</var>, printf_arginfo_function <var>arginfo-function</var>)</i></dt>
<dd><p>This function defines the conversion specifier character <var>spec</var>.
Thus, if <var>spec</var> is <code>'Y'</code>, it defines the conversion ‘<samp>%Y</samp>’.
You can redefine the built-in conversions like ‘<samp>%s</samp>’, but flag
characters like ‘<samp>#</samp>’ and type modifiers like ‘<samp>l</samp>’ can never be
used as conversions; calling <code>register_printf_function</code> for those
characters has no effect. It is advisable not to use lowercase letters,
since the ISO C standard warns that additional lowercase letters may be
standardized in future editions of the standard.
</p>
<p>The <var>handler-function</var> is the function called by <code>printf</code> and
friends when this conversion appears in a template string.
See section <a href="#Defining-the-Output-Handler">Defining the Output Handler</a>, for information about how to define
a function to pass as this argument. If you specify a null pointer, any
existing handler function for <var>spec</var> is removed.
</p>
<p>The <var>arginfo-function</var> is the function called by
<code>parse_printf_format</code> when this conversion appears in a
template string. See section <a href="#Parsing-a-Template-String">Parsing a Template String</a>, for information
about this.
</p>
<p><strong>Attention:</strong> In the GNU C library versions before 2.0 the
<var>arginfo-function</var> function did not need to be installed unless
the user used the <code>parse_printf_format</code> function. This has changed.
Now a call to any of the <code>printf</code> functions will call this
function when this format specifier appears in the format string.
</p>
<p>The return value is <code>0</code> on success, and <code>-1</code> on failure
(which occurs if <var>spec</var> is out of range).
</p>
<p>You can redefine the standard output conversions, but this is probably
not a good idea because of the potential for confusion. Library routines
written by other people could break if you do this.
</p></dd></dl>
<hr size="6">
<a name="Conversion-Specifier-Options"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Registering-New-Conversions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Defining-the-Output-Handler" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Customizing-Printf" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Conversion-Specifier-Options-1"></a>
<h3 class="subsection">12.13.2 Conversion Specifier Options</h3>
<p>If you define a meaning for ‘<samp>%A</samp>’, what if the template contains
‘<samp>%+23A</samp>’ or ‘<samp>%-#A</samp>’? To implement a sensible meaning for these,
the handler when called needs to be able to get the options specified in
the template.
</p>
<p>Both the <var>handler-function</var> and <var>arginfo-function</var> accept an
argument that points to a <code>struct printf_info</code>, which contains
information about the options appearing in an instance of the conversion
specifier. This data type is declared in the header file
‘<tt>printf.h</tt>’.
<a name="index-printf_002eh-1"></a>
</p>
<dl>
<dt><a name="index-struct-printf_005finfo"></a><u>Type:</u> <b>struct printf_info</b></dt>
<dd><p>This structure is used to pass information about the options appearing
in an instance of a conversion specifier in a <code>printf</code> template
string to the handler and arginfo functions for that specifier. It
contains the following members:
</p>
<dl compact="compact">
<dt> <code>int prec</code></dt>
<dd><p>This is the precision specified. The value is <code>-1</code> if no precision
was specified. If the precision was given as ‘<samp>*</samp>’, the
<code>printf_info</code> structure passed to the handler function contains the
actual value retrieved from the argument list. But the structure passed
to the arginfo function contains a value of <code>INT_MIN</code>, since the
actual value is not known.
</p>
</dd>
<dt> <code>int width</code></dt>
<dd><p>This is the minimum field width specified. The value is <code>0</code> if no
width was specified. If the field width was given as ‘<samp>*</samp>’, the
<code>printf_info</code> structure passed to the handler function contains the
actual value retrieved from the argument list. But the structure passed
to the arginfo function contains a value of <code>INT_MIN</code>, since the
actual value is not known.
</p>
</dd>
<dt> <code>wchar_t spec</code></dt>
<dd><p>This is the conversion specifier character specified. It’s stored in
the structure so that you can register the same handler function for
multiple characters, but still have a way to tell them apart when the
handler function is called.
</p>
</dd>
<dt> <code>unsigned int is_long_double</code></dt>
<dd><p>This is a boolean that is true if the ‘<samp>L</samp>’, ‘<samp>ll</samp>’, or ‘<samp>q</samp>’
type modifier was specified. For integer conversions, this indicates
<code>long long int</code>, as opposed to <code>long double</code> for floating
point conversions.
</p>
</dd>
<dt> <code>unsigned int is_char</code></dt>
<dd><p>This is a boolean that is true if the ‘<samp>hh</samp>’ type modifier was specified.
</p>
</dd>
<dt> <code>unsigned int is_short</code></dt>
<dd><p>This is a boolean that is true if the ‘<samp>h</samp>’ type modifier was specified.
</p>
</dd>
<dt> <code>unsigned int is_long</code></dt>
<dd><p>This is a boolean that is true if the ‘<samp>l</samp>’ type modifier was specified.
</p>
</dd>
<dt> <code>unsigned int alt</code></dt>
<dd><p>This is a boolean that is true if the ‘<samp>#</samp>’ flag was specified.
</p>
</dd>
<dt> <code>unsigned int space</code></dt>
<dd><p>This is a boolean that is true if the ‘<samp> </samp>’ flag was specified.
</p>
</dd>
<dt> <code>unsigned int left</code></dt>
<dd><p>This is a boolean that is true if the ‘<samp>-</samp>’ flag was specified.
</p>
</dd>
<dt> <code>unsigned int showsign</code></dt>
<dd><p>This is a boolean that is true if the ‘<samp>+</samp>’ flag was specified.
</p>
</dd>
<dt> <code>unsigned int group</code></dt>
<dd><p>This is a boolean that is true if the ‘<samp>'</samp>’ flag was specified.
</p>
</dd>
<dt> <code>unsigned int extra</code></dt>
<dd><p>This flag has a special meaning depending on the context. It could
be used freely by the user-defined handlers but when called from
the <code>printf</code> function this variable always contains the value
<code>0</code>.
</p>
</dd>
<dt> <code>unsigned int wide</code></dt>
<dd><p>This flag is set if the stream is wide oriented.
</p>
</dd>
<dt> <code>wchar_t pad</code></dt>
<dd><p>This is the character to use for padding the output to the minimum field
width. The value is <code>'0'</code> if the ‘<samp>0</samp>’ flag was specified, and
<code>' '</code> otherwise.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="Defining-the-Output-Handler"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Conversion-Specifier-Options" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Printf-Extension-Example" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Customizing-Printf" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Defining-the-Output-Handler-1"></a>
<h3 class="subsection">12.13.3 Defining the Output Handler</h3>
<p>Now let’s look at how to define the handler and arginfo functions
which are passed as arguments to <code>register_printf_function</code>.
</p>
<p><strong>Compatibility Note:</strong> The interface changed in GNU libc
version 2.0. Previously the third argument was of type
<code>va_list *</code>.
</p>
<p>You should define your handler functions with a prototype like:
</p>
<table><tr><td> </td><td><pre class="smallexample">int <var>function</var> (FILE *stream, const struct printf_info *info,
const void *const *args)
</pre></td></tr></table>
<p>The <var>stream</var> argument passed to the handler function is the stream to
which it should write output.
</p>
<p>The <var>info</var> argument is a pointer to a structure that contains
information about the various options that were included with the
conversion in the template string. You should not modify this structure
inside your handler function. See section <a href="#Conversion-Specifier-Options">Conversion Specifier Options</a>, for
a description of this data structure.
</p>
<p>The <var>args</var> is a vector of pointers to the arguments data.
The number of arguments was determined by calling the argument
information function provided by the user.
</p>
<p>Your handler function should return a value just like <code>printf</code>
does: it should return the number of characters it has written, or a
negative value to indicate an error.
</p>
<dl>
<dt><a name="index-printf_005ffunction"></a><u>Data Type:</u> <b>printf_function</b></dt>
<dd><p>This is the data type that a handler function should have.
</p></dd></dl>
<p>If you are going to use <code>parse_printf_format</code> in your
application, you must also define a function to pass as the
<var>arginfo-function</var> argument for each new conversion you install with
<code>register_printf_function</code>.
</p>
<p>You have to define these functions with a prototype like:
</p>
<table><tr><td> </td><td><pre class="smallexample">int <var>function</var> (const struct printf_info *info,
size_t n, int *argtypes)
</pre></td></tr></table>
<p>The return value from the function should be the number of arguments the
conversion expects. The function should also fill in no more than
<var>n</var> elements of the <var>argtypes</var> array with information about the
types of each of these arguments. This information is encoded using the
various ‘<samp>PA_</samp>’ macros. (You will notice that this is the same
calling convention <code>parse_printf_format</code> itself uses.)
</p>
<dl>
<dt><a name="index-printf_005farginfo_005ffunction"></a><u>Data Type:</u> <b>printf_arginfo_function</b></dt>
<dd><p>This type is used to describe functions that return information about
the number and type of arguments used by a conversion specifier.
</p></dd></dl>
<hr size="6">
<a name="Printf-Extension-Example"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Defining-the-Output-Handler" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Predefined-Printf-Handlers" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Customizing-Printf" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="printf-Extension-Example"></a>
<h3 class="subsection">12.13.4 <code>printf</code> Extension Example</h3>
<p>Here is an example showing how to define a <code>printf</code> handler function.
This program defines a data structure called a <code>Widget</code> and
defines the ‘<samp>%W</samp>’ conversion to print information about <code>Widget *</code>
arguments, including the pointer value and the name stored in the data
structure. The ‘<samp>%W</samp>’ conversion supports the minimum field width and
left-justification options, but ignores everything else.
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <stdio.h>
#include <stdlib.h>
#include <printf.h>
</pre><pre class="smallexample">typedef struct
{
char *name;
}
Widget;
</pre><pre class="smallexample">
int
print_widget (FILE *stream,
const struct printf_info *info,
const void *const *args)
{
const Widget *w;
char *buffer;
int len;
/* <span class="roman">Format the output into a string.</span> */
w = *((const Widget **) (args[0]));
len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
if (len == -1)
return -1;
/* <span class="roman">Pad to the minimum field width and print to the stream.</span> */
len = fprintf (stream, "%*s",
(info->left ? -info->width : info->width),
buffer);
/* <span class="roman">Clean up and return.</span> */
free (buffer);
return len;
}
int
print_widget_arginfo (const struct printf_info *info, size_t n,
int *argtypes)
{
/* <span class="roman">We always take exactly one argument and this is a pointer to the
structure..</span> */
if (n > 0)
argtypes[0] = PA_POINTER;
return 1;
}
int
main (void)
{
/* <span class="roman">Make a widget to print.</span> */
Widget mywidget;
mywidget.name = "mywidget";
/* <span class="roman">Register the print function for widgets.</span> */
register_printf_function ('W', print_widget, print_widget_arginfo);
/* <span class="roman">Now print the widget.</span> */
printf ("|%W|\n", &mywidget);
printf ("|%35W|\n", &mywidget);
printf ("|%-35W|\n", &mywidget);
return 0;
}
</pre></td></tr></table>
<p>The output produced by this program looks like:
</p>
<table><tr><td> </td><td><pre class="smallexample">|<Widget 0xffeffb7c: mywidget>|
| <Widget 0xffeffb7c: mywidget>|
|<Widget 0xffeffb7c: mywidget> |
</pre></td></tr></table>
<hr size="6">
<a name="Predefined-Printf-Handlers"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Printf-Extension-Example" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Customizing-Printf" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Predefined-printf-Handlers"></a>
<h3 class="subsection">12.13.5 Predefined <code>printf</code> Handlers</h3>
<p>The GNU libc also contains a concrete and useful application of the
<code>printf</code> handler extension. There are two functions available
which implement a special way to print floating-point numbers.
</p>
<dl>
<dt><a name="index-printf_005fsize"></a><u>Function:</u> int <b>printf_size</b><i> (FILE *<var>fp</var>, const struct printf_info *<var>info</var>, const void *const *<var>args</var>)</i></dt>
<dd><p>Print a given floating point number as for the format <code>%f</code> except
that there is a postfix character indicating the divisor for the
number to make this less than 1000. There are two possible divisors:
powers of 1024 or powers of 1000. Which one is used depends on the
format character specified while registered this handler. If the
character is of lower case, 1024 is used. For upper case characters,
1000 is used.
</p>
<p>The postfix tag corresponds to bytes, kilobytes, megabytes, gigabytes,
etc. The full table is:
</p>
<p>The default precision is 3, i.e., 1024 is printed with a lower-case
format character as if it were <code>%.3fk</code> and will yield <code>1.000k</code>.
</p></dd></dl>
<p>Due to the requirements of <code>register_printf_function</code> we must also
provide the function which returns information about the arguments.
</p>
<dl>
<dt><a name="index-printf_005fsize_005finfo"></a><u>Function:</u> int <b>printf_size_info</b><i> (const struct printf_info *<var>info</var>, size_t <var>n</var>, int *<var>argtypes</var>)</i></dt>
<dd><p>This function will return in <var>argtypes</var> the information about the
used parameters in the way the <code>vfprintf</code> implementation expects
it. The format always takes one argument.
</p></dd></dl>
<p>To use these functions both functions must be registered with a call like
</p>
<table><tr><td> </td><td><pre class="smallexample">register_printf_function ('B', printf_size, printf_size_info);
</pre></td></tr></table>
<p>Here we register the functions to print numbers as powers of 1000 since
the format character <code>'B'</code> is an upper-case character. If we
would additionally use <code>'b'</code> in a line like
</p>
<table><tr><td> </td><td><pre class="smallexample">register_printf_function ('b', printf_size, printf_size_info);
</pre></td></tr></table>
<p>we could also print using a power of 1024. Please note that all that is
different in these two lines is the format specifier. The
<code>printf_size</code> function knows about the difference between lower and upper
case format specifiers.
</p>
<p>The use of <code>'B'</code> and <code>'b'</code> is no coincidence. Rather it is
the preferred way to use this functionality since it is available on
some other systems which also use format specifiers.
</p>
<hr size="6">
<a name="Formatted-Input"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Predefined-Printf-Handlers" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input-Basics" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Formatted-Input-1"></a>
<h2 class="section">12.14 Formatted Input</h2>
<a name="index-formatted-input-from-a-stream"></a>
<a name="index-reading-from-a-stream_002c-formatted"></a>
<a name="index-format-string_002c-for-scanf"></a>
<a name="index-template_002c-for-scanf"></a>
<p>The functions described in this section (<code>scanf</code> and related
functions) provide facilities for formatted input analogous to the
formatted output facilities. These functions provide a mechanism for
reading arbitrary values under the control of a <em>format string</em> or
<em>template string</em>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Formatted-Input-Basics">12.14.1 Formatted Input Basics</a></td><td> </td><td align="left" valign="top"> Some basics to get you started.
</td></tr>
<tr><td align="left" valign="top"><a href="#Input-Conversion-Syntax">12.14.2 Input Conversion Syntax</a></td><td> </td><td align="left" valign="top"> Syntax of conversion specifications.
</td></tr>
<tr><td align="left" valign="top"><a href="#Table-of-Input-Conversions">12.14.3 Table of Input Conversions</a></td><td> </td><td align="left" valign="top"> Summary of input conversions and what they do.
</td></tr>
<tr><td align="left" valign="top"><a href="#Numeric-Input-Conversions">12.14.4 Numeric Input Conversions</a></td><td> </td><td align="left" valign="top"> Details of conversions for reading numbers.
</td></tr>
<tr><td align="left" valign="top"><a href="#String-Input-Conversions">12.14.5 String Input Conversions</a></td><td> </td><td align="left" valign="top"> Details of conversions for reading strings.
</td></tr>
<tr><td align="left" valign="top"><a href="#Dynamic-String-Input">12.14.6 Dynamically Allocating String Conversions</a></td><td> </td><td align="left" valign="top"> String conversions that <code>malloc</code> the buffer.
</td></tr>
<tr><td align="left" valign="top"><a href="#Other-Input-Conversions">12.14.7 Other Input Conversions</a></td><td> </td><td align="left" valign="top"> Details of miscellaneous other conversions.
</td></tr>
<tr><td align="left" valign="top"><a href="#Formatted-Input-Functions">12.14.8 Formatted Input Functions</a></td><td> </td><td align="left" valign="top"> Descriptions of the actual functions.
</td></tr>
<tr><td align="left" valign="top"><a href="#Variable-Arguments-Input">12.14.9 Variable Arguments Input Functions</a></td><td> </td><td align="left" valign="top"> <code>vscanf</code> and friends.
</td></tr>
</table>
<hr size="6">
<a name="Formatted-Input-Basics"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Formatted-Input" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Input-Conversion-Syntax" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Formatted-Input-Basics-1"></a>
<h3 class="subsection">12.14.1 Formatted Input Basics</h3>
<p>Calls to <code>scanf</code> are superficially similar to calls to
<code>printf</code> in that arbitrary arguments are read under the control of
a template string. While the syntax of the conversion specifications in
the template is very similar to that for <code>printf</code>, the
interpretation of the template is oriented more towards free-format
input and simple pattern matching, rather than fixed-field formatting.
For example, most <code>scanf</code> conversions skip over any amount of
“white space” (including spaces, tabs, and newlines) in the input
file, and there is no concept of precision for the numeric input
conversions as there is for the corresponding output conversions.
Ordinarily, non-whitespace characters in the template are expected to
match characters in the input stream exactly, but a matching failure is
distinct from an input error on the stream.
<a name="index-conversion-specifications-_0028scanf_0029"></a>
</p>
<p>Another area of difference between <code>scanf</code> and <code>printf</code> is
that you must remember to supply pointers rather than immediate values
as the optional arguments to <code>scanf</code>; the values that are read are
stored in the objects that the pointers point to. Even experienced
programmers tend to forget this occasionally, so if your program is
getting strange errors that seem to be related to <code>scanf</code>, you
might want to double-check this.
</p>
<p>When a <em>matching failure</em> occurs, <code>scanf</code> returns immediately,
leaving the first non-matching character as the next character to be
read from the stream. The normal return value from <code>scanf</code> is the
number of values that were assigned, so you can use this to determine if
a matching error happened before all the expected values were read.
<a name="index-matching-failure_002c-in-scanf"></a>
</p>
<p>The <code>scanf</code> function is typically used for things like reading in
the contents of tables. For example, here is a function that uses
<code>scanf</code> to initialize an array of <code>double</code>:
</p>
<table><tr><td> </td><td><pre class="smallexample">void
readarray (double *array, int n)
{
int i;
for (i=0; i<n; i++)
if (scanf (" %lf", &(array[i])) != 1)
invalid_input_error ();
}
</pre></td></tr></table>
<p>The formatted input functions are not used as frequently as the
formatted output functions. Partly, this is because it takes some care
to use them properly. Another reason is that it is difficult to recover
from a matching error.
</p>
<p>If you are trying to read input that doesn’t match a single, fixed
pattern, you may be better off using a tool such as Flex to generate a
lexical scanner, or Bison to generate a parser, rather than using
<code>scanf</code>. For more information about these tools, see <a href="../flex/index.html#Top">(flex.info)Top</a> section ‘Top’ in <cite>Flex: The Lexical Scanner Generator</cite>, and <a href="../bison/index.html#Top">(bison.info)Top</a> section ‘Top’ in <cite>The Bison Reference Manual</cite>.
</p>
<hr size="6">
<a name="Input-Conversion-Syntax"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Formatted-Input-Basics" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Table-of-Input-Conversions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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-Conversion-Syntax-1"></a>
<h3 class="subsection">12.14.2 Input Conversion Syntax</h3>
<p>A <code>scanf</code> template string is a string that contains ordinary
multibyte characters interspersed with conversion specifications that
start with ‘<samp>%</samp>’.
</p>
<p>Any whitespace character (as defined by the <code>isspace</code> function;
see section <a href="libc_4.html#Classification-of-Characters">Classification of Characters</a>) in the template causes any number
of whitespace characters in the input stream to be read and discarded.
The whitespace characters that are matched need not be exactly the same
whitespace characters that appear in the template string. For example,
write ‘<samp> , </samp>’ in the template to recognize a comma with optional
whitespace before and after.
</p>
<p>Other characters in the template string that are not part of conversion
specifications must match characters in the input stream exactly; if
this is not the case, a matching failure occurs.
</p>
<p>The conversion specifications in a <code>scanf</code> template string
have the general form:
</p>
<table><tr><td> </td><td><pre class="smallexample">% <var>flags</var> <var>width</var> <var>type</var> <var>conversion</var>
</pre></td></tr></table>
<p>In more detail, an input conversion specification consists of an initial
‘<samp>%</samp>’ character followed in sequence by:
</p>
<ul>
<li>
An optional <em>flag character</em> ‘<samp>*</samp>’, which says to ignore the text
read for this specification. When <code>scanf</code> finds a conversion
specification that uses this flag, it reads input as directed by the
rest of the conversion specification, but it discards this input, does
not use a pointer argument, and does not increment the count of
successful assignments.
<a name="index-flag-character-_0028scanf_0029"></a>
</li><li>
An optional flag character ‘<samp>a</samp>’ (valid with string conversions only)
which requests allocation of a buffer long enough to store the string in.
(This is a GNU extension.)
See section <a href="#Dynamic-String-Input">Dynamically Allocating String Conversions</a>.
</li><li>
An optional decimal integer that specifies the <em>maximum field
width</em>. Reading of characters from the input stream stops either when
this maximum is reached or when a non-matching character is found,
whichever happens first. Most conversions discard initial whitespace
characters (those that don’t are explicitly documented), and these
discarded characters don’t count towards the maximum field width.
String input conversions store a null character to mark the end of the
input; the maximum field width does not include this terminator.
<a name="index-maximum-field-width-_0028scanf_0029"></a>
</li><li>
An optional <em>type modifier character</em>. For example, you can
specify a type modifier of ‘<samp>l</samp>’ with integer conversions such as
‘<samp>%d</samp>’ to specify that the argument is a pointer to a <code>long int</code>
rather than a pointer to an <code>int</code>.
<a name="index-type-modifier-character-_0028scanf_0029"></a>
</li><li>
A character that specifies the conversion to be applied.
</li></ul>
<p>The exact options that are permitted and how they are interpreted vary
between the different conversion specifiers. See the descriptions of the
individual conversions for information about the particular options that
they allow.
</p>
<p>With the ‘<samp>-Wformat</samp>’ option, the GNU C compiler checks calls to
<code>scanf</code> and related functions. It examines the format string and
verifies that the correct number and types of arguments are supplied.
There is also a GNU C syntax to tell the compiler that a function you
write uses a <code>scanf</code>-style format string.
See <a href="../gcc/Function-Attributes.html#Function-Attributes">(gcc.info)Function Attributes</a> section ‘Declaring Attributes of Functions’ in <cite>Using GNU CC</cite>, for more information.
</p>
<hr size="6">
<a name="Table-of-Input-Conversions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Input-Conversion-Syntax" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Numeric-Input-Conversions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Table-of-Input-Conversions-1"></a>
<h3 class="subsection">12.14.3 Table of Input Conversions</h3>
<a name="index-input-conversions_002c-for-scanf"></a>
<p>Here is a table that summarizes the various conversion specifications:
</p>
<dl compact="compact">
<dt> ‘<samp>%d</samp>’</dt>
<dd><p>Matches an optionally signed integer written in decimal. See section <a href="#Numeric-Input-Conversions">Numeric Input Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%i</samp>’</dt>
<dd><p>Matches an optionally signed integer in any of the formats that the C
language defines for specifying an integer constant. See section <a href="#Numeric-Input-Conversions">Numeric Input Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%o</samp>’</dt>
<dd><p>Matches an unsigned integer written in octal radix.
See section <a href="#Numeric-Input-Conversions">Numeric Input Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%u</samp>’</dt>
<dd><p>Matches an unsigned integer written in decimal radix.
See section <a href="#Numeric-Input-Conversions">Numeric Input Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%x</samp>’, ‘<samp>%X</samp>’</dt>
<dd><p>Matches an unsigned integer written in hexadecimal radix.
See section <a href="#Numeric-Input-Conversions">Numeric Input Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%e</samp>’, ‘<samp>%f</samp>’, ‘<samp>%g</samp>’, ‘<samp>%E</samp>’, ‘<samp>%G</samp>’</dt>
<dd><p>Matches an optionally signed floating-point number. See section <a href="#Numeric-Input-Conversions">Numeric Input Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%s</samp>’</dt>
<dd>
<p>Matches a string containing only non-whitespace characters.
See section <a href="#String-Input-Conversions">String Input Conversions</a>. The presence of the ‘<samp>l</samp>’ modifier
determines whether the output is stored as a wide character string or a
multibyte string. If ‘<samp>%s</samp>’ is used in a wide character function the
string is converted as with multiple calls to <code>wcrtomb</code> into a
multibyte string. This means that the buffer must provide room for
<code>MB_CUR_MAX</code> bytes for each wide character read. In case
‘<samp>%ls</samp>’ is used in a multibyte function the result is converted into
wide characters as with multiple calls of <code>mbrtowc</code> before being
stored in the user provided buffer.
</p>
</dd>
<dt> ‘<samp>%S</samp>’</dt>
<dd><p>This is an alias for ‘<samp>%ls</samp>’ which is supported for compatibility
with the Unix standard.
</p>
</dd>
<dt> ‘<samp>%[</samp>’</dt>
<dd><p>Matches a string of characters that belong to a specified set.
See section <a href="#String-Input-Conversions">String Input Conversions</a>. The presence of the ‘<samp>l</samp>’ modifier
determines whether the output is stored as a wide character string or a
multibyte string. If ‘<samp>%[</samp>’ is used in a wide character function the
string is converted as with multiple calls to <code>wcrtomb</code> into a
multibyte string. This means that the buffer must provide room for
<code>MB_CUR_MAX</code> bytes for each wide character read. In case
‘<samp>%l[</samp>’ is used in a multibyte function the result is converted into
wide characters as with multiple calls of <code>mbrtowc</code> before being
stored in the user provided buffer.
</p>
</dd>
<dt> ‘<samp>%c</samp>’</dt>
<dd><p>Matches a string of one or more characters; the number of characters
read is controlled by the maximum field width given for the conversion.
See section <a href="#String-Input-Conversions">String Input Conversions</a>.
</p>
<p>If the ‘<samp>%c</samp>’ is used in a wide stream function the read value is
converted from a wide character to the corresponding multibyte character
before storing it. Note that this conversion can produce more than one
byte of output and therefore the provided buffer be large enough for up
to <code>MB_CUR_MAX</code> bytes for each character. If ‘<samp>%lc</samp>’ is used in
a multibyte function the input is treated as a multibyte sequence (and
not bytes) and the result is converted as with calls to <code>mbrtowc</code>.
</p>
</dd>
<dt> ‘<samp>%C</samp>’</dt>
<dd><p>This is an alias for ‘<samp>%lc</samp>’ which is supported for compatibility
with the Unix standard.
</p>
</dd>
<dt> ‘<samp>%p</samp>’</dt>
<dd><p>Matches a pointer value in the same implementation-defined format used
by the ‘<samp>%p</samp>’ output conversion for <code>printf</code>. See section <a href="#Other-Input-Conversions">Other Input Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%n</samp>’</dt>
<dd><p>This conversion doesn’t read any characters; it records the number of
characters read so far by this call. See section <a href="#Other-Input-Conversions">Other Input Conversions</a>.
</p>
</dd>
<dt> ‘<samp>%%</samp>’</dt>
<dd><p>This matches a literal ‘<samp>%</samp>’ character in the input stream. No
corresponding argument is used. See section <a href="#Other-Input-Conversions">Other Input Conversions</a>.
</p></dd>
</dl>
<p>If the syntax of a conversion specification is invalid, the behavior is
undefined. If there aren’t enough function arguments provided to supply
addresses for all the conversion specifications in the template strings
that perform assignments, or if the arguments are not of the correct
types, the behavior is also undefined. On the other hand, extra
arguments are simply ignored.
</p>
<hr size="6">
<a name="Numeric-Input-Conversions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Table-of-Input-Conversions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#String-Input-Conversions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Numeric-Input-Conversions-1"></a>
<h3 class="subsection">12.14.4 Numeric Input Conversions</h3>
<p>This section describes the <code>scanf</code> conversions for reading numeric
values.
</p>
<p>The ‘<samp>%d</samp>’ conversion matches an optionally signed integer in decimal
radix. The syntax that is recognized is the same as that for the
<code>strtol</code> function (see section <a href="libc_20.html#Parsing-of-Integers">Parsing of Integers</a>) with the value
<code>10</code> for the <var>base</var> argument.
</p>
<p>The ‘<samp>%i</samp>’ conversion matches an optionally signed integer in any of
the formats that the C language defines for specifying an integer
constant. The syntax that is recognized is the same as that for the
<code>strtol</code> function (see section <a href="libc_20.html#Parsing-of-Integers">Parsing of Integers</a>) with the value
<code>0</code> for the <var>base</var> argument. (You can print integers in this
syntax with <code>printf</code> by using the ‘<samp>#</samp>’ flag character with the
‘<samp>%x</samp>’, ‘<samp>%o</samp>’, or ‘<samp>%d</samp>’ conversion. See section <a href="#Integer-Conversions">Integer Conversions</a>.)
</p>
<p>For example, any of the strings ‘<samp>10</samp>’, ‘<samp>0xa</samp>’, or ‘<samp>012</samp>’
could be read in as integers under the ‘<samp>%i</samp>’ conversion. Each of
these specifies a number with decimal value <code>10</code>.
</p>
<p>The ‘<samp>%o</samp>’, ‘<samp>%u</samp>’, and ‘<samp>%x</samp>’ conversions match unsigned
integers in octal, decimal, and hexadecimal radices, respectively. The
syntax that is recognized is the same as that for the <code>strtoul</code>
function (see section <a href="libc_20.html#Parsing-of-Integers">Parsing of Integers</a>) with the appropriate value
(<code>8</code>, <code>10</code>, or <code>16</code>) for the <var>base</var> argument.
</p>
<p>The ‘<samp>%X</samp>’ conversion is identical to the ‘<samp>%x</samp>’ conversion. They
both permit either uppercase or lowercase letters to be used as digits.
</p>
<p>The default type of the corresponding argument for the <code>%d</code> and
<code>%i</code> conversions is <code>int *</code>, and <code>unsigned int *</code> for the
other integer conversions. You can use the following type modifiers to
specify other sizes of integer:
</p>
<dl compact="compact">
<dt> ‘<samp>hh</samp>’</dt>
<dd><p>Specifies that the argument is a <code>signed char *</code> or <code>unsigned
char *</code>.
</p>
<p>This modifier was introduced in ISO C99.
</p>
</dd>
<dt> ‘<samp>h</samp>’</dt>
<dd><p>Specifies that the argument is a <code>short int *</code> or <code>unsigned
short int *</code>.
</p>
</dd>
<dt> ‘<samp>j</samp>’</dt>
<dd><p>Specifies that the argument is a <code>intmax_t *</code> or <code>uintmax_t *</code>.
</p>
<p>This modifier was introduced in ISO C99.
</p>
</dd>
<dt> ‘<samp>l</samp>’</dt>
<dd><p>Specifies that the argument is a <code>long int *</code> or <code>unsigned
long int *</code>. Two ‘<samp>l</samp>’ characters is like the ‘<samp>L</samp>’ modifier, below.
</p>
<p>If used with ‘<samp>%c</samp>’ or ‘<samp>%s</samp>’ the corresponding parameter is
considered as a pointer to a wide character or wide character string
respectively. This use of ‘<samp>l</samp>’ was introduced in Amendment 1 to
ISO C90.
</p>
</dd>
<dt> ‘<samp>ll</samp>’</dt>
<dt> ‘<samp>L</samp>’</dt>
<dt> ‘<samp>q</samp>’</dt>
<dd><p>Specifies that the argument is a <code>long long int *</code> or <code>unsigned long long int *</code>. (The <code>long long</code> type is an extension supported by the
GNU C compiler. For systems that don’t provide extra-long integers, this
is the same as <code>long int</code>.)
</p>
<p>The ‘<samp>q</samp>’ modifier is another name for the same thing, which comes
from 4.4 BSD; a <code>long long int</code> is sometimes called a “quad”
<code>int</code>.
</p>
</dd>
<dt> ‘<samp>t</samp>’</dt>
<dd><p>Specifies that the argument is a <code>ptrdiff_t *</code>.
</p>
<p>This modifier was introduced in ISO C99.
</p>
</dd>
<dt> ‘<samp>z</samp>’</dt>
<dd><p>Specifies that the argument is a <code>size_t *</code>.
</p>
<p>This modifier was introduced in ISO C99.
</p></dd>
</dl>
<p>All of the ‘<samp>%e</samp>’, ‘<samp>%f</samp>’, ‘<samp>%g</samp>’, ‘<samp>%E</samp>’, and ‘<samp>%G</samp>’
input conversions are interchangeable. They all match an optionally
signed floating point number, in the same syntax as for the
<code>strtod</code> function (see section <a href="libc_20.html#Parsing-of-Floats">Parsing of Floats</a>).
</p>
<p>For the floating-point input conversions, the default argument type is
<code>float *</code>. (This is different from the corresponding output
conversions, where the default type is <code>double</code>; remember that
<code>float</code> arguments to <code>printf</code> are converted to <code>double</code>
by the default argument promotions, but <code>float *</code> arguments are
not promoted to <code>double *</code>.) You can specify other sizes of float
using these type modifiers:
</p>
<dl compact="compact">
<dt> ‘<samp>l</samp>’</dt>
<dd><p>Specifies that the argument is of type <code>double *</code>.
</p>
</dd>
<dt> ‘<samp>L</samp>’</dt>
<dd><p>Specifies that the argument is of type <code>long double *</code>.
</p></dd>
</dl>
<p>For all the above number parsing formats there is an additional optional
flag ‘<samp>'</samp>’. When this flag is given the <code>scanf</code> function
expects the number represented in the input string to be formatted
according to the grouping rules of the currently selected locale
(see section <a href="libc_7.html#General-Numeric">Generic Numeric Formatting Parameters</a>).
</p>
<p>If the <code>"C"</code> or <code>"POSIX"</code> locale is selected there is no
difference. But for a locale which specifies values for the appropriate
fields in the locale the input must have the correct form in the input.
Otherwise the longest prefix with a correct form is processed.
</p>
<hr size="6">
<a name="String-Input-Conversions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Numeric-Input-Conversions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Dynamic-String-Input" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="String-Input-Conversions-1"></a>
<h3 class="subsection">12.14.5 String Input Conversions</h3>
<p>This section describes the <code>scanf</code> input conversions for reading
string and character values: ‘<samp>%s</samp>’, ‘<samp>%S</samp>’, ‘<samp>%[</samp>’, ‘<samp>%c</samp>’,
and ‘<samp>%C</samp>’.
</p>
<p>You have two options for how to receive the input from these
conversions:
</p>
<ul>
<li>
Provide a buffer to store it in. This is the default. You should
provide an argument of type <code>char *</code> or <code>wchar_t *</code> (the
latter of the ‘<samp>l</samp>’ modifier is present).
<p><strong>Warning:</strong> To make a robust program, you must make sure that the
input (plus its terminating null) cannot possibly exceed the size of the
buffer you provide. In general, the only way to do this is to specify a
maximum field width one less than the buffer size. <strong>If you
provide the buffer, always specify a maximum field width to prevent
overflow.</strong>
</p>
</li><li>
Ask <code>scanf</code> to allocate a big enough buffer, by specifying the
‘<samp>a</samp>’ flag character. This is a GNU extension. You should provide
an argument of type <code>char **</code> for the buffer address to be stored
in. See section <a href="#Dynamic-String-Input">Dynamically Allocating String Conversions</a>.
</li></ul>
<p>The ‘<samp>%c</samp>’ conversion is the simplest: it matches a fixed number of
characters, always. The maximum field width says how many characters to
read; if you don’t specify the maximum, the default is 1. This
conversion doesn’t append a null character to the end of the text it
reads. It also does not skip over initial whitespace characters. It
reads precisely the next <var>n</var> characters, and fails if it cannot get
that many. Since there is always a maximum field width with ‘<samp>%c</samp>’
(whether specified, or 1 by default), you can always prevent overflow by
making the buffer long enough.
</p>
<p>If the format is ‘<samp>%lc</samp>’ or ‘<samp>%C</samp>’ the function stores wide
characters which are converted using the conversion determined at the
time the stream was opened from the external byte stream. The number of
bytes read from the medium is limited by <code>MB_CUR_LEN * <var>n</var></code> but
at most <var>n</var> wide character get stored in the output string.
</p>
<p>The ‘<samp>%s</samp>’ conversion matches a string of non-whitespace characters.
It skips and discards initial whitespace, but stops when it encounters
more whitespace after having read something. It stores a null character
at the end of the text that it reads.
</p>
<p>For example, reading the input:
</p>
<table><tr><td> </td><td><pre class="smallexample"> hello, world
</pre></td></tr></table>
<p>with the conversion ‘<samp>%10c</samp>’ produces <code>" hello, wo"</code>, but
reading the same input with the conversion ‘<samp>%10s</samp>’ produces
<code>"hello,"</code>.
</p>
<p><strong>Warning:</strong> If you do not specify a field width for ‘<samp>%s</samp>’,
then the number of characters read is limited only by where the next
whitespace character appears. This almost certainly means that invalid
input can make your program crash—which is a bug.
</p>
<p>The ‘<samp>%ls</samp>’ and ‘<samp>%S</samp>’ format are handled just like ‘<samp>%s</samp>’
except that the external byte sequence is converted using the conversion
associated with the stream to wide characters with their own encoding.
A width or precision specified with the format do not directly determine
how many bytes are read from the stream since they measure wide
characters. But an upper limit can be computed by multiplying the value
of the width or precision by <code>MB_CUR_MAX</code>.
</p>
<p>To read in characters that belong to an arbitrary set of your choice,
use the ‘<samp>%[</samp>’ conversion. You specify the set between the ‘<samp>[</samp>’
character and a following ‘<samp>]</samp>’ character, using the same syntax used
in regular expressions. As special cases:
</p>
<ul>
<li>
A literal ‘<samp>]</samp>’ character can be specified as the first character
of the set.
</li><li>
An embedded ‘<samp>-</samp>’ character (that is, one that is not the first or
last character of the set) is used to specify a range of characters.
</li><li>
If a caret character ‘<samp>^</samp>’ immediately follows the initial ‘<samp>[</samp>’,
then the set of allowed input characters is the everything <em>except</em>
the characters listed.
</li></ul>
<p>The ‘<samp>%[</samp>’ conversion does not skip over initial whitespace
characters.
</p>
<p>Here are some examples of ‘<samp>%[</samp>’ conversions and what they mean:
</p>
<dl compact="compact">
<dt> ‘<samp>%25[1234567890]</samp>’</dt>
<dd><p>Matches a string of up to 25 digits.
</p>
</dd>
<dt> ‘<samp>%25[][]</samp>’</dt>
<dd><p>Matches a string of up to 25 square brackets.
</p>
</dd>
<dt> ‘<samp>%25[^ \f\n\r\t\v]</samp>’</dt>
<dd><p>Matches a string up to 25 characters long that doesn’t contain any of
the standard whitespace characters. This is slightly different from
‘<samp>%s</samp>’, because if the input begins with a whitespace character,
‘<samp>%[</samp>’ reports a matching failure while ‘<samp>%s</samp>’ simply discards the
initial whitespace.
</p>
</dd>
<dt> ‘<samp>%25[a-z]</samp>’</dt>
<dd><p>Matches up to 25 lowercase characters.
</p></dd>
</dl>
<p>As for ‘<samp>%c</samp>’ and ‘<samp>%s</samp>’ the ‘<samp>%[</samp>’ format is also modified to
produce wide characters if the ‘<samp>l</samp>’ modifier is present. All what
is said about ‘<samp>%ls</samp>’ above is true for ‘<samp>%l[</samp>’.
</p>
<p>One more reminder: the ‘<samp>%s</samp>’ and ‘<samp>%[</samp>’ conversions are
<strong>dangerous</strong> if you don’t specify a maximum width or use the
‘<samp>a</samp>’ flag, because input too long would overflow whatever buffer you
have provided for it. No matter how long your buffer is, a user could
supply input that is longer. A well-written program reports invalid
input with a comprehensible error message, not with a crash.
</p>
<hr size="6">
<a name="Dynamic-String-Input"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#String-Input-Conversions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Other-Input-Conversions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Dynamically-Allocating-String-Conversions"></a>
<h3 class="subsection">12.14.6 Dynamically Allocating String Conversions</h3>
<p>A GNU extension to formatted input lets you safely read a string with no
maximum size. Using this feature, you don’t supply a buffer; instead,
<code>scanf</code> allocates a buffer big enough to hold the data and gives
you its address. To use this feature, write ‘<samp>a</samp>’ as a flag
character, as in ‘<samp>%as</samp>’ or ‘<samp>%a[0-9a-z]</samp>’.
</p>
<p>The pointer argument you supply for where to store the input should have
type <code>char **</code>. The <code>scanf</code> function allocates a buffer and
stores its address in the word that the argument points to. You should
free the buffer with <code>free</code> when you no longer need it.
</p>
<p>Here is an example of using the ‘<samp>a</samp>’ flag with the ‘<samp>%[…]</samp>’
conversion specification to read a “variable assignment” of the form
‘<samp><var>variable</var> = <var>value</var></samp>’.
</p>
<table><tr><td> </td><td><pre class="smallexample">{
char *variable, *value;
if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
&variable, &value))
{
invalid_input_error ();
return 0;
}
…
}
</pre></td></tr></table>
<hr size="6">
<a name="Other-Input-Conversions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Dynamic-String-Input" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input-Functions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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-Input-Conversions-1"></a>
<h3 class="subsection">12.14.7 Other Input Conversions</h3>
<p>This section describes the miscellaneous input conversions.
</p>
<p>The ‘<samp>%p</samp>’ conversion is used to read a pointer value. It recognizes
the same syntax used by the ‘<samp>%p</samp>’ output conversion for
<code>printf</code> (see section <a href="#Other-Output-Conversions">Other Output Conversions</a>); that is, a hexadecimal
number just as the ‘<samp>%x</samp>’ conversion accepts. The corresponding
argument should be of type <code>void **</code>; that is, the address of a
place to store a pointer.
</p>
<p>The resulting pointer value is not guaranteed to be valid if it was not
originally written during the same program execution that reads it in.
</p>
<p>The ‘<samp>%n</samp>’ conversion produces the number of characters read so far
by this call. The corresponding argument should be of type <code>int *</code>.
This conversion works in the same way as the ‘<samp>%n</samp>’ conversion for
<code>printf</code>; see <a href="#Other-Output-Conversions">Other Output Conversions</a>, for an example.
</p>
<p>The ‘<samp>%n</samp>’ conversion is the only mechanism for determining the
success of literal matches or conversions with suppressed assignments.
If the ‘<samp>%n</samp>’ follows the locus of a matching failure, then no value
is stored for it since <code>scanf</code> returns before processing the
‘<samp>%n</samp>’. If you store <code>-1</code> in that argument slot before calling
<code>scanf</code>, the presence of <code>-1</code> after <code>scanf</code> indicates an
error occurred before the ‘<samp>%n</samp>’ was reached.
</p>
<p>Finally, the ‘<samp>%%</samp>’ conversion matches a literal ‘<samp>%</samp>’ character
in the input stream, without using an argument. This conversion does
not permit any flags, field width, or type modifier to be specified.
</p>
<hr size="6">
<a name="Formatted-Input-Functions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Other-Input-Conversions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Variable-Arguments-Input" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Formatted-Input-Functions-1"></a>
<h3 class="subsection">12.14.8 Formatted Input Functions</h3>
<p>Here are the descriptions of the functions for performing formatted
input.
Prototypes for these functions are in the header file ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-8"></a>
</p>
<dl>
<dt><a name="index-scanf"></a><u>Function:</u> int <b>scanf</b><i> (const char *<var>template</var>, …)</i></dt>
<dd><p>The <code>scanf</code> function reads formatted input from the stream
<code>stdin</code> under the control of the template string <var>template</var>.
The optional arguments are pointers to the places which receive the
resulting values.
</p>
<p>The return value is normally the number of successful assignments. If
an end-of-file condition is detected before any matches are performed,
including matches against whitespace and literal characters in the
template, then <code>EOF</code> is returned.
</p></dd></dl>
<dl>
<dt><a name="index-wscanf"></a><u>Function:</u> int <b>wscanf</b><i> (const wchar_t *<var>template</var>, …)</i></dt>
<dd><p>The <code>wscanf</code> function reads formatted input from the stream
<code>stdin</code> under the control of the template string <var>template</var>.
The optional arguments are pointers to the places which receive the
resulting values.
</p>
<p>The return value is normally the number of successful assignments. If
an end-of-file condition is detected before any matches are performed,
including matches against whitespace and literal characters in the
template, then <code>WEOF</code> is returned.
</p></dd></dl>
<dl>
<dt><a name="index-fscanf"></a><u>Function:</u> int <b>fscanf</b><i> (FILE *<var>stream</var>, const char *<var>template</var>, …)</i></dt>
<dd><p>This function is just like <code>scanf</code>, except that the input is read
from the stream <var>stream</var> instead of <code>stdin</code>.
</p></dd></dl>
<dl>
<dt><a name="index-fwscanf"></a><u>Function:</u> int <b>fwscanf</b><i> (FILE *<var>stream</var>, const wchar_t *<var>template</var>, …)</i></dt>
<dd><p>This function is just like <code>wscanf</code>, except that the input is read
from the stream <var>stream</var> instead of <code>stdin</code>.
</p></dd></dl>
<dl>
<dt><a name="index-sscanf"></a><u>Function:</u> int <b>sscanf</b><i> (const char *<var>s</var>, const char *<var>template</var>, …)</i></dt>
<dd><p>This is like <code>scanf</code>, except that the characters are taken from the
null-terminated string <var>s</var> instead of from a stream. Reaching the
end of the string is treated as an end-of-file condition.
</p>
<p>The behavior of this function is undefined if copying takes place
between objects that overlap—for example, if <var>s</var> is also given
as an argument to receive a string read under control of the ‘<samp>%s</samp>’,
‘<samp>%S</samp>’, or ‘<samp>%[</samp>’ conversion.
</p></dd></dl>
<dl>
<dt><a name="index-swscanf"></a><u>Function:</u> int <b>swscanf</b><i> (const wchar_t *<var>ws</var>, const char *<var>template</var>, …)</i></dt>
<dd><p>This is like <code>wscanf</code>, except that the characters are taken from the
null-terminated string <var>ws</var> instead of from a stream. Reaching the
end of the string is treated as an end-of-file condition.
</p>
<p>The behavior of this function is undefined if copying takes place
between objects that overlap—for example, if <var>ws</var> is also given as
an argument to receive a string read under control of the ‘<samp>%s</samp>’,
‘<samp>%S</samp>’, or ‘<samp>%[</samp>’ conversion.
</p></dd></dl>
<hr size="6">
<a name="Variable-Arguments-Input"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Formatted-Input-Functions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#EOF-and-Errors" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Input" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Variable-Arguments-Input-Functions"></a>
<h3 class="subsection">12.14.9 Variable Arguments Input Functions</h3>
<p>The functions <code>vscanf</code> and friends are provided so that you can
define your own variadic <code>scanf</code>-like functions that make use of
the same internals as the built-in formatted output functions.
These functions are analogous to the <code>vprintf</code> series of output
functions. See section <a href="#Variable-Arguments-Output">Variable Arguments Output Functions</a>, for important
information on how to use them.
</p>
<p><strong>Portability Note:</strong> The functions listed in this section were
introduced in ISO C99 and were before available as GNU extensions.
</p>
<dl>
<dt><a name="index-vscanf"></a><u>Function:</u> int <b>vscanf</b><i> (const char *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This function is similar to <code>scanf</code>, but instead of taking
a variable number of arguments directly, it takes an argument list
pointer <var>ap</var> of type <code>va_list</code> (see section <a href="libc_34.html#Variadic-Functions">Variadic Functions</a>).
</p></dd></dl>
<dl>
<dt><a name="index-vwscanf"></a><u>Function:</u> int <b>vwscanf</b><i> (const wchar_t *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This function is similar to <code>wscanf</code>, but instead of taking
a variable number of arguments directly, it takes an argument list
pointer <var>ap</var> of type <code>va_list</code> (see section <a href="libc_34.html#Variadic-Functions">Variadic Functions</a>).
</p></dd></dl>
<dl>
<dt><a name="index-vfscanf"></a><u>Function:</u> int <b>vfscanf</b><i> (FILE *<var>stream</var>, const char *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This is the equivalent of <code>fscanf</code> with the variable argument list
specified directly as for <code>vscanf</code>.
</p></dd></dl>
<dl>
<dt><a name="index-vfwscanf"></a><u>Function:</u> int <b>vfwscanf</b><i> (FILE *<var>stream</var>, const wchar_t *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This is the equivalent of <code>fwscanf</code> with the variable argument list
specified directly as for <code>vwscanf</code>.
</p></dd></dl>
<dl>
<dt><a name="index-vsscanf"></a><u>Function:</u> int <b>vsscanf</b><i> (const char *<var>s</var>, const char *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This is the equivalent of <code>sscanf</code> with the variable argument list
specified directly as for <code>vscanf</code>.
</p></dd></dl>
<dl>
<dt><a name="index-vswscanf"></a><u>Function:</u> int <b>vswscanf</b><i> (const wchar_t *<var>s</var>, const wchar_t *<var>template</var>, va_list <var>ap</var>)</i></dt>
<dd><p>This is the equivalent of <code>swscanf</code> with the variable argument list
specified directly as for <code>vwscanf</code>.
</p></dd></dl>
<p>In GNU C, there is a special construct you can use to let the compiler
know that a function uses a <code>scanf</code>-style format string. Then it
can check the number and types of arguments in each call to the
function, and warn you when they do not match the format string.
For details, see <a href="../gcc/Function-Attributes.html#Function-Attributes">(gcc.info)Function Attributes</a> section ‘Declaring Attributes of Functions’ in <cite>Using GNU CC</cite>.
</p>
<hr size="6">
<a name="EOF-and-Errors"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Variable-Arguments-Input" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Error-Recovery" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="End_002dOf_002dFile-and-Errors"></a>
<h2 class="section">12.15 End-Of-File and Errors</h2>
<a name="index-end-of-file_002c-on-a-stream"></a>
<p>Many of the functions described in this chapter return the value of the
macro <code>EOF</code> to indicate unsuccessful completion of the operation.
Since <code>EOF</code> is used to report both end of file and random errors,
it’s often better to use the <code>feof</code> function to check explicitly
for end of file and <code>ferror</code> to check for errors. These functions
check indicators that are part of the internal state of the stream
object, indicators set if the appropriate condition was detected by a
previous I/O operation on that stream.
</p>
<dl>
<dt><a name="index-EOF"></a><u>Macro:</u> int <b>EOF</b></dt>
<dd><p>This macro is an integer value that is returned by a number of narrow
stream functions to indicate an end-of-file condition, or some other
error situation. With the GNU library, <code>EOF</code> is <code>-1</code>. In
other libraries, its value may be some other negative number.
</p>
<p>This symbol is declared in ‘<tt>stdio.h</tt>’.
</p></dd></dl>
<dl>
<dt><a name="index-WEOF-1"></a><u>Macro:</u> int <b>WEOF</b></dt>
<dd><p>This macro is an integer value that is returned by a number of wide
stream functions to indicate an end-of-file condition, or some other
error situation. With the GNU library, <code>WEOF</code> is <code>-1</code>. In
other libraries, its value may be some other negative number.
</p>
<p>This symbol is declared in ‘<tt>wchar.h</tt>’.
</p></dd></dl>
<dl>
<dt><a name="index-feof"></a><u>Function:</u> int <b>feof</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>feof</code> function returns nonzero if and only if the end-of-file
indicator for the stream <var>stream</var> is set.
</p>
<p>This symbol is declared in ‘<tt>stdio.h</tt>’.
</p></dd></dl>
<dl>
<dt><a name="index-feof_005funlocked"></a><u>Function:</u> int <b>feof_unlocked</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>feof_unlocked</code> function is equivalent to the <code>feof</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p>
<p>This symbol is declared in ‘<tt>stdio.h</tt>’.
</p></dd></dl>
<dl>
<dt><a name="index-ferror"></a><u>Function:</u> int <b>ferror</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>ferror</code> function returns nonzero if and only if the error
indicator for the stream <var>stream</var> is set, indicating that an error
has occurred on a previous operation on the stream.
</p>
<p>This symbol is declared in ‘<tt>stdio.h</tt>’.
</p></dd></dl>
<dl>
<dt><a name="index-ferror_005funlocked"></a><u>Function:</u> int <b>ferror_unlocked</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>ferror_unlocked</code> function is equivalent to the <code>ferror</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p>
<p>This symbol is declared in ‘<tt>stdio.h</tt>’.
</p></dd></dl>
<p>In addition to setting the error indicator associated with the stream,
the functions that operate on streams also set <code>errno</code> in the same
way as the corresponding low-level functions that operate on file
descriptors. For example, all of the functions that perform output to a
stream—such as <code>fputc</code>, <code>printf</code>, and <code>fflush</code>—are
implemented in terms of <code>write</code>, and all of the <code>errno</code> error
conditions defined for <code>write</code> are meaningful for these functions.
For more information about the descriptor-level I/O functions, see
<a href="libc_13.html#Low_002dLevel-I_002fO">Low-Level Input/Output</a>.
</p>
<hr size="6">
<a name="Error-Recovery"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#EOF-and-Errors" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Binary-Streams" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Recovering-from-errors"></a>
<h2 class="section">12.16 Recovering from errors</h2>
<p>You may explicitly clear the error and EOF flags with the <code>clearerr</code>
function.
</p>
<dl>
<dt><a name="index-clearerr"></a><u>Function:</u> void <b>clearerr</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This function clears the end-of-file and error indicators for the
stream <var>stream</var>.
</p>
<p>The file positioning functions (see section <a href="#File-Positioning">File Positioning</a>) also clear the
end-of-file indicator for the stream.
</p></dd></dl>
<dl>
<dt><a name="index-clearerr_005funlocked"></a><u>Function:</u> void <b>clearerr_unlocked</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>clearerr_unlocked</code> function is equivalent to the <code>clearerr</code>
function except that it does not implicitly lock the stream.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<p>Note that it is <em>not</em> correct to just clear the error flag and retry
a failed stream operation. After a failed write, any number of
characters since the last buffer flush may have been committed to the
file, while some buffered data may have been discarded. Merely retrying
can thus cause lost or repeated data.
</p>
<p>A failed read may leave the file pointer in an inappropriate position for
a second try. In both cases, you should seek to a known position before
retrying.
</p>
<p>Most errors that can happen are not recoverable — a second try will
always fail again in the same way. So usually it is best to give up and
report the error to the user, rather than install complicated recovery
logic.
</p>
<p>One important exception is <code>EINTR</code> (see section <a href="libc_24.html#Interrupted-Primitives">Primitives Interrupted by Signals</a>).
Many stream I/O implementations will treat it as an ordinary error, which
can be quite inconvenient. You can avoid this hassle by installing all
signals with the <code>SA_RESTART</code> flag.
</p>
<p>For similar reasons, setting nonblocking I/O on a stream’s file
descriptor is not usually advisable.
</p>
<hr size="6">
<a name="Binary-Streams"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Error-Recovery" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#File-Positioning" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Text-and-Binary-Streams"></a>
<h2 class="section">12.17 Text and Binary Streams</h2>
<p>The GNU system and other POSIX-compatible operating systems organize all
files as uniform sequences of characters. However, some other systems
make a distinction between files containing text and files containing
binary data, and the input and output facilities of ISO C provide for
this distinction. This section tells you how to write programs portable
to such systems.
</p>
<a name="index-text-stream"></a>
<a name="index-binary-stream"></a>
<p>When you open a stream, you can specify either a <em>text stream</em> or a
<em>binary stream</em>. You indicate that you want a binary stream by
specifying the ‘<samp>b</samp>’ modifier in the <var>opentype</var> argument to
<code>fopen</code>; see <a href="#Opening-Streams">Opening Streams</a>. Without this
option, <code>fopen</code> opens the file as a text stream.
</p>
<p>Text and binary streams differ in several ways:
</p>
<ul>
<li>
The data read from a text stream is divided into <em>lines</em> which are
terminated by newline (<code>'\n'</code>) characters, while a binary stream is
simply a long series of characters. A text stream might on some systems
fail to handle lines more than 254 characters long (including the
terminating newline character).
<a name="index-lines-_0028in-a-text-file_0029"></a>
</li><li>
On some systems, text files can contain only printing characters,
horizontal tab characters, and newlines, and so text streams may not
support other characters. However, binary streams can handle any
character value.
</li><li>
Space characters that are written immediately preceding a newline
character in a text stream may disappear when the file is read in again.
</li><li>
More generally, there need not be a one-to-one mapping between
characters that are read from or written to a text stream, and the
characters in the actual file.
</li></ul>
<p>Since a binary stream is always more capable and more predictable than a
text stream, you might wonder what purpose text streams serve. Why not
simply always use binary streams? The answer is that on these operating
systems, text and binary streams use different file formats, and the
only way to read or write “an ordinary file of text” that can work
with other text-oriented programs is through a text stream.
</p>
<p>In the GNU library, and on all POSIX systems, there is no difference
between text streams and binary streams. When you open a stream, you
get the same kind of stream regardless of whether you ask for binary.
This stream can handle any file content, and has none of the
restrictions that text streams sometimes have.
</p>
<hr size="6">
<a name="File-Positioning"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Binary-Streams" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Portable-Positioning" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="File-Positioning-1"></a>
<h2 class="section">12.18 File Positioning</h2>
<a name="index-file-positioning-on-a-stream"></a>
<a name="index-positioning-a-stream"></a>
<a name="index-seeking-on-a-stream"></a>
<p>The <em>file position</em> of a stream describes where in the file the
stream is currently reading or writing. I/O on the stream advances the
file position through the file. In the GNU system, the file position is
represented as an integer, which counts the number of bytes from the
beginning of the file. See section <a href="libc_11.html#File-Position">File Position</a>.
</p>
<p>During I/O to an ordinary disk file, you can change the file position
whenever you wish, so as to read or write any portion of the file. Some
other kinds of files may also permit this. Files which support changing
the file position are sometimes referred to as <em>random-access</em>
files.
</p>
<p>You can use the functions in this section to examine or modify the file
position indicator associated with a stream. The symbols listed below
are declared in the header file ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-9"></a>
</p>
<dl>
<dt><a name="index-ftell"></a><u>Function:</u> long int <b>ftell</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This function returns the current file position of the stream
<var>stream</var>.
</p>
<p>This function can fail if the stream doesn’t support file positioning,
or if the file position can’t be represented in a <code>long int</code>, and
possibly for other reasons as well. If a failure occurs, a value of
<code>-1</code> is returned.
</p></dd></dl>
<dl>
<dt><a name="index-ftello"></a><u>Function:</u> off_t <b>ftello</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>ftello</code> function is similar to <code>ftell</code>, except that it
returns a value of type <code>off_t</code>. Systems which support this type
use it to describe all file positions, unlike the POSIX specification
which uses a long int. The two are not necessarily the same size.
Therefore, using ftell can lead to problems if the implementation is
written on top of a POSIX compliant low-level I/O implementation, and using
<code>ftello</code> is preferable whenever it is available.
</p>
<p>If this function fails it returns <code>(off_t) -1</code>. This can happen due
to missing support for file positioning or internal errors. Otherwise
the return value is the current file position.
</p>
<p>The function is an extension defined in the Unix Single Specification
version 2.
</p>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a
32 bit system this function is in fact <code>ftello64</code>. I.e., the
LFS interface transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-ftello64"></a><u>Function:</u> off64_t <b>ftello64</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This function is similar to <code>ftello</code> with the only difference that
the return value is of type <code>off64_t</code>. This also requires that the
stream <var>stream</var> was opened using either <code>fopen64</code>,
<code>freopen64</code>, or <code>tmpfile64</code> since otherwise the underlying
file operations to position the file pointer beyond the <em>2^31</em>
bytes limit might fail.
</p>
<p>If the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a 32
bits machine this function is available under the name <code>ftello</code>
and so transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-fseek"></a><u>Function:</u> int <b>fseek</b><i> (FILE *<var>stream</var>, long int <var>offset</var>, int <var>whence</var>)</i></dt>
<dd><p>The <code>fseek</code> function is used to change the file position of the
stream <var>stream</var>. The value of <var>whence</var> must be one of the
constants <code>SEEK_SET</code>, <code>SEEK_CUR</code>, or <code>SEEK_END</code>, to
indicate whether the <var>offset</var> is relative to the beginning of the
file, the current file position, or the end of the file, respectively.
</p>
<p>This function returns a value of zero if the operation was successful,
and a nonzero value to indicate failure. A successful call also clears
the end-of-file indicator of <var>stream</var> and discards any characters
that were “pushed back” by the use of <code>ungetc</code>.
</p>
<p><code>fseek</code> either flushes any buffered output before setting the file
position or else remembers it so it will be written later in its proper
place in the file.
</p></dd></dl>
<dl>
<dt><a name="index-fseeko"></a><u>Function:</u> int <b>fseeko</b><i> (FILE *<var>stream</var>, off_t <var>offset</var>, int <var>whence</var>)</i></dt>
<dd><p>This function is similar to <code>fseek</code> but it corrects a problem with
<code>fseek</code> in a system with POSIX types. Using a value of type
<code>long int</code> for the offset is not compatible with POSIX.
<code>fseeko</code> uses the correct type <code>off_t</code> for the <var>offset</var>
parameter.
</p>
<p>For this reason it is a good idea to prefer <code>ftello</code> whenever it is
available since its functionality is (if different at all) closer the
underlying definition.
</p>
<p>The functionality and return value is the same as for <code>fseek</code>.
</p>
<p>The function is an extension defined in the Unix Single Specification
version 2.
</p>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a
32 bit system this function is in fact <code>fseeko64</code>. I.e., the
LFS interface transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-fseeko64"></a><u>Function:</u> int <b>fseeko64</b><i> (FILE *<var>stream</var>, off64_t <var>offset</var>, int <var>whence</var>)</i></dt>
<dd><p>This function is similar to <code>fseeko</code> with the only difference that
the <var>offset</var> parameter is of type <code>off64_t</code>. This also
requires that the stream <var>stream</var> was opened using either
<code>fopen64</code>, <code>freopen64</code>, or <code>tmpfile64</code> since otherwise
the underlying file operations to position the file pointer beyond the
<em>2^31</em> bytes limit might fail.
</p>
<p>If the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a 32
bits machine this function is available under the name <code>fseeko</code>
and so transparently replaces the old interface.
</p></dd></dl>
<p><strong>Portability Note:</strong> In non-POSIX systems, <code>ftell</code>,
<code>ftello</code>, <code>fseek</code> and <code>fseeko</code> might work reliably only
on binary streams. See section <a href="#Binary-Streams">Text and Binary Streams</a>.
</p>
<p>The following symbolic constants are defined for use as the <var>whence</var>
argument to <code>fseek</code>. They are also used with the <code>lseek</code>
function (see section <a href="libc_13.html#I_002fO-Primitives">Input and Output Primitives</a>) and to specify offsets for file locks
(see section <a href="libc_13.html#Control-Operations">Control Operations on Files</a>).
</p>
<dl>
<dt><a name="index-SEEK_005fSET"></a><u>Macro:</u> int <b>SEEK_SET</b></dt>
<dd><p>This is an integer constant which, when used as the <var>whence</var>
argument to the <code>fseek</code> or <code>fseeko</code> function, specifies that
the offset provided is relative to the beginning of the file.
</p></dd></dl>
<dl>
<dt><a name="index-SEEK_005fCUR"></a><u>Macro:</u> int <b>SEEK_CUR</b></dt>
<dd><p>This is an integer constant which, when used as the <var>whence</var>
argument to the <code>fseek</code> or <code>fseeko</code> function, specifies that
the offset provided is relative to the current file position.
</p></dd></dl>
<dl>
<dt><a name="index-SEEK_005fEND"></a><u>Macro:</u> int <b>SEEK_END</b></dt>
<dd><p>This is an integer constant which, when used as the <var>whence</var>
argument to the <code>fseek</code> or <code>fseeko</code> function, specifies that
the offset provided is relative to the end of the file.
</p></dd></dl>
<dl>
<dt><a name="index-rewind"></a><u>Function:</u> void <b>rewind</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>rewind</code> function positions the stream <var>stream</var> at the
beginning of the file. It is equivalent to calling <code>fseek</code> or
<code>fseeko</code> on the <var>stream</var> with an <var>offset</var> argument of
<code>0L</code> and a <var>whence</var> argument of <code>SEEK_SET</code>, except that
the return value is discarded and the error indicator for the stream is
reset.
</p></dd></dl>
<p>These three aliases for the ‘<samp>SEEK_…</samp>’ constants exist for the
sake of compatibility with older BSD systems. They are defined in two
different header files: ‘<tt>fcntl.h</tt>’ and ‘<tt>sys/file.h</tt>’.
</p>
<dl compact="compact">
<dt> <code>L_SET</code></dt>
<dd><a name="index-L_005fSET"></a>
<p>An alias for <code>SEEK_SET</code>.
</p>
</dd>
<dt> <code>L_INCR</code></dt>
<dd><a name="index-L_005fINCR"></a>
<p>An alias for <code>SEEK_CUR</code>.
</p>
</dd>
<dt> <code>L_XTND</code></dt>
<dd><a name="index-L_005fXTND"></a>
<p>An alias for <code>SEEK_END</code>.
</p></dd>
</dl>
<hr size="6">
<a name="Portable-Positioning"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#File-Positioning" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Stream-Buffering" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Portable-File_002dPosition-Functions"></a>
<h2 class="section">12.19 Portable File-Position Functions</h2>
<p>On the GNU system, the file position is truly a character count. You
can specify any character count value as an argument to <code>fseek</code> or
<code>fseeko</code> and get reliable results for any random access file.
However, some ISO C systems do not represent file positions in this
way.
</p>
<p>On some systems where text streams truly differ from binary streams, it
is impossible to represent the file position of a text stream as a count
of characters from the beginning of the file. For example, the file
position on some systems must encode both a record offset within the
file, and a character offset within the record.
</p>
<p>As a consequence, if you want your programs to be portable to these
systems, you must observe certain rules:
</p>
<ul>
<li>
The value returned from <code>ftell</code> on a text stream has no predictable
relationship to the number of characters you have read so far. The only
thing you can rely on is that you can use it subsequently as the
<var>offset</var> argument to <code>fseek</code> or <code>fseeko</code> to move back to
the same file position.
</li><li>
In a call to <code>fseek</code> or <code>fseeko</code> on a text stream, either the
<var>offset</var> must be zero, or <var>whence</var> must be <code>SEEK_SET</code> and
the <var>offset</var> must be the result of an earlier call to <code>ftell</code>
on the same stream.
</li><li>
The value of the file position indicator of a text stream is undefined
while there are characters that have been pushed back with <code>ungetc</code>
that haven’t been read or discarded. See section <a href="#Unreading">Unreading</a>.
</li></ul>
<p>But even if you observe these rules, you may still have trouble for long
files, because <code>ftell</code> and <code>fseek</code> use a <code>long int</code> value
to represent the file position. This type may not have room to encode
all the file positions in a large file. Using the <code>ftello</code> and
<code>fseeko</code> functions might help here since the <code>off_t</code> type is
expected to be able to hold all file position values but this still does
not help to handle additional information which must be associated with
a file position.
</p>
<p>So if you do want to support systems with peculiar encodings for the
file positions, it is better to use the functions <code>fgetpos</code> and
<code>fsetpos</code> instead. These functions represent the file position
using the data type <code>fpos_t</code>, whose internal representation varies
from system to system.
</p>
<p>These symbols are declared in the header file ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-10"></a>
</p>
<dl>
<dt><a name="index-fpos_005ft"></a><u>Data Type:</u> <b>fpos_t</b></dt>
<dd><p>This is the type of an object that can encode information about the
file position of a stream, for use by the functions <code>fgetpos</code> and
<code>fsetpos</code>.
</p>
<p>In the GNU system, <code>fpos_t</code> is an opaque data structure that
contains internal data to represent file offset and conversion state
information. In other systems, it might have a different internal
representation.
</p>
<p>When compiling with <code>_FILE_OFFSET_BITS == 64</code> on a 32 bit machine
this type is in fact equivalent to <code>fpos64_t</code> since the LFS
interface transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-fpos64_005ft"></a><u>Data Type:</u> <b>fpos64_t</b></dt>
<dd><p>This is the type of an object that can encode information about the
file position of a stream, for use by the functions <code>fgetpos64</code> and
<code>fsetpos64</code>.
</p>
<p>In the GNU system, <code>fpos64_t</code> is an opaque data structure that
contains internal data to represent file offset and conversion state
information. In other systems, it might have a different internal
representation.
</p></dd></dl>
<dl>
<dt><a name="index-fgetpos"></a><u>Function:</u> int <b>fgetpos</b><i> (FILE *<var>stream</var>, fpos_t *<var>position</var>)</i></dt>
<dd><p>This function stores the value of the file position indicator for the
stream <var>stream</var> in the <code>fpos_t</code> object pointed to by
<var>position</var>. If successful, <code>fgetpos</code> returns zero; otherwise
it returns a nonzero value and stores an implementation-defined positive
value in <code>errno</code>.
</p>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a
32 bit system the function is in fact <code>fgetpos64</code>. I.e., the LFS
interface transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-fgetpos64"></a><u>Function:</u> int <b>fgetpos64</b><i> (FILE *<var>stream</var>, fpos64_t *<var>position</var>)</i></dt>
<dd><p>This function is similar to <code>fgetpos</code> but the file position is
returned in a variable of type <code>fpos64_t</code> to which <var>position</var>
points.
</p>
<p>If the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a 32
bits machine this function is available under the name <code>fgetpos</code>
and so transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-fsetpos"></a><u>Function:</u> int <b>fsetpos</b><i> (FILE *<var>stream</var>, const fpos_t *<var>position</var>)</i></dt>
<dd><p>This function sets the file position indicator for the stream <var>stream</var>
to the position <var>position</var>, which must have been set by a previous
call to <code>fgetpos</code> on the same stream. If successful, <code>fsetpos</code>
clears the end-of-file indicator on the stream, discards any characters
that were “pushed back” by the use of <code>ungetc</code>, and returns a value
of zero. Otherwise, <code>fsetpos</code> returns a nonzero value and stores
an implementation-defined positive value in <code>errno</code>.
</p>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a
32 bit system the function is in fact <code>fsetpos64</code>. I.e., the LFS
interface transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-fsetpos64"></a><u>Function:</u> int <b>fsetpos64</b><i> (FILE *<var>stream</var>, const fpos64_t *<var>position</var>)</i></dt>
<dd><p>This function is similar to <code>fsetpos</code> but the file position used
for positioning is provided in a variable of type <code>fpos64_t</code> to
which <var>position</var> points.
</p>
<p>If the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a 32
bits machine this function is available under the name <code>fsetpos</code>
and so transparently replaces the old interface.
</p></dd></dl>
<hr size="6">
<a name="Stream-Buffering"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Portable-Positioning" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Buffering-Concepts" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Stream-Buffering-1"></a>
<h2 class="section">12.20 Stream Buffering</h2>
<a name="index-buffering-of-streams"></a>
<p>Characters that are written to a stream are normally accumulated and
transmitted asynchronously to the file in a block, instead of appearing
as soon as they are output by the application program. Similarly,
streams often retrieve input from the host environment in blocks rather
than on a character-by-character basis. This is called <em>buffering</em>.
</p>
<p>If you are writing programs that do interactive input and output using
streams, you need to understand how buffering works when you design the
user interface to your program. Otherwise, you might find that output
(such as progress or prompt messages) doesn’t appear when you intended
it to, or displays some other unexpected behavior.
</p>
<p>This section deals only with controlling when characters are transmitted
between the stream and the file or device, and <em>not</em> with how
things like echoing, flow control, and the like are handled on specific
classes of devices. For information on common control operations on
terminal devices, see <a href="libc_17.html#Low_002dLevel-Terminal-Interface">Low-Level Terminal Interface</a>.
</p>
<p>You can bypass the stream buffering facilities altogether by using the
low-level input and output functions that operate on file descriptors
instead. See section <a href="libc_13.html#Low_002dLevel-I_002fO">Low-Level Input/Output</a>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Buffering-Concepts">12.20.1 Buffering Concepts</a></td><td> </td><td align="left" valign="top"> Terminology is defined here.
</td></tr>
<tr><td align="left" valign="top"><a href="#Flushing-Buffers">12.20.2 Flushing Buffers</a></td><td> </td><td align="left" valign="top"> How to ensure that output buffers are flushed.
</td></tr>
<tr><td align="left" valign="top"><a href="#Controlling-Buffering">12.20.3 Controlling Which Kind of Buffering</a></td><td> </td><td align="left" valign="top"> How to specify what kind of buffering to use.
</td></tr>
</table>
<hr size="6">
<a name="Buffering-Concepts"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Stream-Buffering" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Flushing-Buffers" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Stream-Buffering" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Buffering-Concepts-1"></a>
<h3 class="subsection">12.20.1 Buffering Concepts</h3>
<p>There are three different kinds of buffering strategies:
</p>
<ul>
<li>
Characters written to or read from an <em>unbuffered</em> stream are
transmitted individually to or from the file as soon as possible.
<a name="index-unbuffered-stream"></a>
</li><li>
Characters written to a <em>line buffered</em> stream are transmitted to
the file in blocks when a newline character is encountered.
<a name="index-line-buffered-stream"></a>
</li><li>
Characters written to or read from a <em>fully buffered</em> stream are
transmitted to or from the file in blocks of arbitrary size.
<a name="index-fully-buffered-stream"></a>
</li></ul>
<p>Newly opened streams are normally fully buffered, with one exception: a
stream connected to an interactive device such as a terminal is
initially line buffered. See section <a href="#Controlling-Buffering">Controlling Which Kind of Buffering</a>, for information
on how to select a different kind of buffering. Usually the automatic
selection gives you the most convenient kind of buffering for the file
or device you open.
</p>
<p>The use of line buffering for interactive devices implies that output
messages ending in a newline will appear immediately—which is usually
what you want. Output that doesn’t end in a newline might or might not
show up immediately, so if you want them to appear immediately, you
should flush buffered output explicitly with <code>fflush</code>, as described
in <a href="#Flushing-Buffers">Flushing Buffers</a>.
</p>
<hr size="6">
<a name="Flushing-Buffers"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Buffering-Concepts" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Controlling-Buffering" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Stream-Buffering" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Flushing-Buffers-1"></a>
<h3 class="subsection">12.20.2 Flushing Buffers</h3>
<a name="index-flushing-a-stream"></a>
<p><em>Flushing</em> output on a buffered stream means transmitting all
accumulated characters to the file. There are many circumstances when
buffered output on a stream is flushed automatically:
</p>
<ul>
<li>
When you try to do output and the output buffer is full.
</li><li>
When the stream is closed. See section <a href="#Closing-Streams">Closing Streams</a>.
</li><li>
When the program terminates by calling <code>exit</code>.
See section <a href="libc_25.html#Normal-Termination">Normal Termination</a>.
</li><li>
When a newline is written, if the stream is line buffered.
</li><li>
Whenever an input operation on <em>any</em> stream actually reads data
from its file.
</li></ul>
<p>If you want to flush the buffered output at another time, call
<code>fflush</code>, which is declared in the header file ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-11"></a>
</p>
<dl>
<dt><a name="index-fflush"></a><u>Function:</u> int <b>fflush</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This function causes any buffered output on <var>stream</var> to be delivered
to the file. If <var>stream</var> is a null pointer, then
<code>fflush</code> causes buffered output on <em>all</em> open output streams
to be flushed.
</p>
<p>This function returns <code>EOF</code> if a write error occurs, or zero
otherwise.
</p></dd></dl>
<dl>
<dt><a name="index-fflush_005funlocked"></a><u>Function:</u> int <b>fflush_unlocked</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>fflush_unlocked</code> function is equivalent to the <code>fflush</code>
function except that it does not implicitly lock the stream.
</p></dd></dl>
<p>The <code>fflush</code> function can be used to flush all streams currently
opened. While this is useful in some situations it does often more than
necessary since it might be done in situations when terminal input is
required and the program wants to be sure that all output is visible on
the terminal. But this means that only line buffered streams have to be
flushed. Solaris introduced a function especially for this. It was
always available in the GNU C library in some form but never officially
exported.
</p>
<dl>
<dt><a name="index-_005fflushlbf"></a><u>Function:</u> void <b>_flushlbf</b><i> (void)</i></dt>
<dd><p>The <code>_flushlbf</code> function flushes all line buffered streams
currently opened.
</p>
<p>This function is declared in the ‘<tt>stdio_ext.h</tt>’ header.
</p></dd></dl>
<p><strong>Compatibility Note:</strong> Some brain-damaged operating systems have
been known to be so thoroughly fixated on line-oriented input and output
that flushing a line buffered stream causes a newline to be written!
Fortunately, this “feature” seems to be becoming less common. You do
not need to worry about this in the GNU system.
</p>
<p>In some situations it might be useful to not flush the output pending
for a stream but instead simply forget it. If transmission is costly
and the output is not needed anymore this is valid reasoning. In this
situation a non-standard function introduced in Solaris and available in
the GNU C library can be used.
</p>
<dl>
<dt><a name="index-_005f_005ffpurge"></a><u>Function:</u> void <b>__fpurge</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>__fpurge</code> function causes the buffer of the stream
<var>stream</var> to be emptied. If the stream is currently in read mode all
input in the buffer is lost. If the stream is in output mode the
buffered output is not written to the device (or whatever other
underlying storage) and the buffer the cleared.
</p>
<p>This function is declared in ‘<tt>stdio_ext.h</tt>’.
</p></dd></dl>
<hr size="6">
<a name="Controlling-Buffering"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Flushing-Buffers" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Other-Kinds-of-Streams" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Stream-Buffering" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Controlling-Which-Kind-of-Buffering"></a>
<h3 class="subsection">12.20.3 Controlling Which Kind of Buffering</h3>
<p>After opening a stream (but before any other operations have been
performed on it), you can explicitly specify what kind of buffering you
want it to have using the <code>setvbuf</code> function.
<a name="index-buffering_002c-controlling"></a>
</p>
<p>The facilities listed in this section are declared in the header
file ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-12"></a>
</p>
<dl>
<dt><a name="index-setvbuf"></a><u>Function:</u> int <b>setvbuf</b><i> (FILE *<var>stream</var>, char *<var>buf</var>, int <var>mode</var>, size_t <var>size</var>)</i></dt>
<dd><p>This function is used to specify that the stream <var>stream</var> should
have the buffering mode <var>mode</var>, which can be either <code>_IOFBF</code>
(for full buffering), <code>_IOLBF</code> (for line buffering), or
<code>_IONBF</code> (for unbuffered input/output).
</p>
<p>If you specify a null pointer as the <var>buf</var> argument, then <code>setvbuf</code>
allocates a buffer itself using <code>malloc</code>. This buffer will be freed
when you close the stream.
</p>
<p>Otherwise, <var>buf</var> should be a character array that can hold at least
<var>size</var> characters. You should not free the space for this array as
long as the stream remains open and this array remains its buffer. You
should usually either allocate it statically, or <code>malloc</code>
(see section <a href="libc_3.html#Unconstrained-Allocation">Unconstrained Allocation</a>) the buffer. Using an automatic array
is not a good idea unless you close the file before exiting the block
that declares the array.
</p>
<p>While the array remains a stream buffer, the stream I/O functions will
use the buffer for their internal purposes. You shouldn’t try to access
the values in the array directly while the stream is using it for
buffering.
</p>
<p>The <code>setvbuf</code> function returns zero on success, or a nonzero value
if the value of <var>mode</var> is not valid or if the request could not
be honored.
</p></dd></dl>
<dl>
<dt><a name="index-_005fIOFBF"></a><u>Macro:</u> int <b>_IOFBF</b></dt>
<dd><p>The value of this macro is an integer constant expression that can be
used as the <var>mode</var> argument to the <code>setvbuf</code> function to
specify that the stream should be fully buffered.
</p></dd></dl>
<dl>
<dt><a name="index-_005fIOLBF"></a><u>Macro:</u> int <b>_IOLBF</b></dt>
<dd><p>The value of this macro is an integer constant expression that can be
used as the <var>mode</var> argument to the <code>setvbuf</code> function to
specify that the stream should be line buffered.
</p></dd></dl>
<dl>
<dt><a name="index-_005fIONBF"></a><u>Macro:</u> int <b>_IONBF</b></dt>
<dd><p>The value of this macro is an integer constant expression that can be
used as the <var>mode</var> argument to the <code>setvbuf</code> function to
specify that the stream should be unbuffered.
</p></dd></dl>
<dl>
<dt><a name="index-BUFSIZ"></a><u>Macro:</u> int <b>BUFSIZ</b></dt>
<dd><p>The value of this macro is an integer constant expression that is good
to use for the <var>size</var> argument to <code>setvbuf</code>. This value is
guaranteed to be at least <code>256</code>.
</p>
<p>The value of <code>BUFSIZ</code> is chosen on each system so as to make stream
I/O efficient. So it is a good idea to use <code>BUFSIZ</code> as the size
for the buffer when you call <code>setvbuf</code>.
</p>
<p>Actually, you can get an even better value to use for the buffer size
by means of the <code>fstat</code> system call: it is found in the
<code>st_blksize</code> field of the file attributes. See section <a href="libc_14.html#Attribute-Meanings">The meaning of the File Attributes</a>.
</p>
<p>Sometimes people also use <code>BUFSIZ</code> as the allocation size of
buffers used for related purposes, such as strings used to receive a
line of input with <code>fgets</code> (see section <a href="#Character-Input">Character Input</a>). There is no
particular reason to use <code>BUFSIZ</code> for this instead of any other
integer, except that it might lead to doing I/O in chunks of an
efficient size.
</p></dd></dl>
<dl>
<dt><a name="index-setbuf"></a><u>Function:</u> void <b>setbuf</b><i> (FILE *<var>stream</var>, char *<var>buf</var>)</i></dt>
<dd><p>If <var>buf</var> is a null pointer, the effect of this function is
equivalent to calling <code>setvbuf</code> with a <var>mode</var> argument of
<code>_IONBF</code>. Otherwise, it is equivalent to calling <code>setvbuf</code>
with <var>buf</var>, and a <var>mode</var> of <code>_IOFBF</code> and a <var>size</var>
argument of <code>BUFSIZ</code>.
</p>
<p>The <code>setbuf</code> function is provided for compatibility with old code;
use <code>setvbuf</code> in all new programs.
</p></dd></dl>
<dl>
<dt><a name="index-setbuffer"></a><u>Function:</u> void <b>setbuffer</b><i> (FILE *<var>stream</var>, char *<var>buf</var>, size_t <var>size</var>)</i></dt>
<dd><p>If <var>buf</var> is a null pointer, this function makes <var>stream</var> unbuffered.
Otherwise, it makes <var>stream</var> fully buffered using <var>buf</var> as the
buffer. The <var>size</var> argument specifies the length of <var>buf</var>.
</p>
<p>This function is provided for compatibility with old BSD code. Use
<code>setvbuf</code> instead.
</p></dd></dl>
<dl>
<dt><a name="index-setlinebuf"></a><u>Function:</u> void <b>setlinebuf</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>This function makes <var>stream</var> be line buffered, and allocates the
buffer for you.
</p>
<p>This function is provided for compatibility with old BSD code. Use
<code>setvbuf</code> instead.
</p></dd></dl>
<p>It is possible to query whether a given stream is line buffered or not
using a non-standard function introduced in Solaris and available in the
GNU C library.
</p>
<dl>
<dt><a name="index-_005f_005fflbf"></a><u>Function:</u> int <b>__flbf</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>__flbf</code> function will return a nonzero value in case the
stream <var>stream</var> is line buffered. Otherwise the return value is
zero.
</p>
<p>This function is declared in the ‘<tt>stdio_ext.h</tt>’ header.
</p></dd></dl>
<p>Two more extensions allow to determine the size of the buffer and how
much of it is used. These functions were also introduced in Solaris.
</p>
<dl>
<dt><a name="index-_005f_005ffbufsize"></a><u>Function:</u> size_t <b>__fbufsize</b><i> (FILE *<var>stream</var>)</i></dt>
<dd><p>The <code>__fbufsize</code> function return the size of the buffer in the
stream <var>stream</var>. This value can be used to optimize the use of the
stream.
</p>
<p>This function is declared in the ‘<tt>stdio_ext.h</tt>’ header.
</p></dd></dl>
<dl>
<dt><a name="index-_005f_005ffpending"></a><u>Function:</u> size_t <b>__fpending</b><i> (FILE *<var>stream</var>) The <code>__fpending</code></i></dt>
<dd><p>function returns the number of bytes currently in the output buffer.
For wide-oriented stream the measuring unit is wide characters. This
function should not be used on buffers in read mode or opened read-only.
</p>
<p>This function is declared in the ‘<tt>stdio_ext.h</tt>’ header.
</p></dd></dl>
<hr size="6">
<a name="Other-Kinds-of-Streams"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Controlling-Buffering" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#String-Streams" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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-Kinds-of-Streams-1"></a>
<h2 class="section">12.21 Other Kinds of Streams</h2>
<p>The GNU library provides ways for you to define additional kinds of
streams that do not necessarily correspond to an open file.
</p>
<p>One such type of stream takes input from or writes output to a string.
These kinds of streams are used internally to implement the
<code>sprintf</code> and <code>sscanf</code> functions. You can also create such a
stream explicitly, using the functions described in <a href="#String-Streams">String Streams</a>.
</p>
<p>More generally, you can define streams that do input/output to arbitrary
objects using functions supplied by your program. This protocol is
discussed in <a href="#Custom-Streams">Programming Your Own Custom Streams</a>.
</p>
<p><strong>Portability Note:</strong> The facilities described in this section are
specific to GNU. Other systems or C implementations might or might not
provide equivalent functionality.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#String-Streams">12.21.1 String Streams</a></td><td> </td><td align="left" valign="top"> Streams that get data from or put data in
a string or memory buffer.
</td></tr>
<tr><td align="left" valign="top"><a href="#Custom-Streams">12.21.2 Programming Your Own Custom Streams</a></td><td> </td><td align="left" valign="top"> Defining your own streams with an arbitrary
input data source and/or output data sink.
</td></tr>
</table>
<hr size="6">
<a name="String-Streams"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Other-Kinds-of-Streams" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Custom-Streams" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Other-Kinds-of-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="String-Streams-1"></a>
<h3 class="subsection">12.21.1 String Streams</h3>
<a name="index-stream_002c-for-I_002fO-to-a-string"></a>
<a name="index-string-stream"></a>
<p>The <code>fmemopen</code> and <code>open_memstream</code> functions allow you to do
I/O to a string or memory buffer. These facilities are declared in
‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-13"></a>
</p>
<dl>
<dt><a name="index-fmemopen"></a><u>Function:</u> FILE * <b>fmemopen</b><i> (void *<var>buf</var>, size_t <var>size</var>, const char *<var>opentype</var>)</i></dt>
<dd><p>This function opens a stream that allows the access specified by the
<var>opentype</var> argument, that reads from or writes to the buffer specified
by the argument <var>buf</var>. This array must be at least <var>size</var> bytes long.
</p>
<p>If you specify a null pointer as the <var>buf</var> argument, <code>fmemopen</code>
dynamically allocates an array <var>size</var> bytes long (as with <code>malloc</code>;
see section <a href="libc_3.html#Unconstrained-Allocation">Unconstrained Allocation</a>). This is really only useful
if you are going to write things to the buffer and then read them back
in again, because you have no way of actually getting a pointer to the
buffer (for this, try <code>open_memstream</code>, below). The buffer is
freed when the stream is closed.
</p>
<p>The argument <var>opentype</var> is the same as in <code>fopen</code>
(see section <a href="#Opening-Streams">Opening Streams</a>). If the <var>opentype</var> specifies
append mode, then the initial file position is set to the first null
character in the buffer. Otherwise the initial file position is at the
beginning of the buffer.
</p>
<p>When a stream open for writing is flushed or closed, a null character
(zero byte) is written at the end of the buffer if it fits. You
should add an extra byte to the <var>size</var> argument to account for this.
Attempts to write more than <var>size</var> bytes to the buffer result
in an error.
</p>
<p>For a stream open for reading, null characters (zero bytes) in the
buffer do not count as “end of file”. Read operations indicate end of
file only when the file position advances past <var>size</var> bytes. So, if
you want to read characters from a null-terminated string, you should
supply the length of the string as the <var>size</var> argument.
</p></dd></dl>
<p>Here is an example of using <code>fmemopen</code> to create a stream for
reading from a string:
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <stdio.h>
static char buffer[] = "foobar";
int
main (void)
{
int ch;
FILE *stream;
stream = fmemopen (buffer, strlen (buffer), "r");
while ((ch = fgetc (stream)) != EOF)
printf ("Got %c\n", ch);
fclose (stream);
return 0;
}
</pre></td></tr></table>
<p>This program produces the following output:
</p>
<table><tr><td> </td><td><pre class="smallexample">Got f
Got o
Got o
Got b
Got a
Got r
</pre></td></tr></table>
<dl>
<dt><a name="index-open_005fmemstream"></a><u>Function:</u> FILE * <b>open_memstream</b><i> (char **<var>ptr</var>, size_t *<var>sizeloc</var>)</i></dt>
<dd><p>This function opens a stream for writing to a buffer. The buffer is
allocated dynamically and grown as necessary, using <code>malloc</code>.
After you’ve closed the stream, this buffer is your responsibility to
clean up using <code>free</code> or <code>realloc</code>. See section <a href="libc_3.html#Unconstrained-Allocation">Unconstrained Allocation</a>.
</p>
<p>When the stream is closed with <code>fclose</code> or flushed with
<code>fflush</code>, the locations <var>ptr</var> and <var>sizeloc</var> are updated to
contain the pointer to the buffer and its size. The values thus stored
remain valid only as long as no further output on the stream takes
place. If you do more output, you must flush the stream again to store
new values before you use them again.
</p>
<p>A null character is written at the end of the buffer. This null character
is <em>not</em> included in the size value stored at <var>sizeloc</var>.
</p>
<p>You can move the stream’s file position with <code>fseek</code> or
<code>fseeko</code> (see section <a href="#File-Positioning">File Positioning</a>). Moving the file position past
the end of the data already written fills the intervening space with
zeroes.
</p></dd></dl>
<p>Here is an example of using <code>open_memstream</code>:
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <stdio.h>
int
main (void)
{
char *bp;
size_t size;
FILE *stream;
stream = open_memstream (&bp, &size);
fprintf (stream, "hello");
fflush (stream);
printf ("buf = `%s', size = %d\n", bp, size);
fprintf (stream, ", world");
fclose (stream);
printf ("buf = `%s', size = %d\n", bp, size);
return 0;
}
</pre></td></tr></table>
<p>This program produces the following output:
</p>
<table><tr><td> </td><td><pre class="smallexample">buf = `hello', size = 5
buf = `hello, world', size = 12
</pre></td></tr></table>
<hr size="6">
<a name="Custom-Streams"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#String-Streams" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Streams-and-Cookies" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Other-Kinds-of-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Programming-Your-Own-Custom-Streams"></a>
<h3 class="subsection">12.21.2 Programming Your Own Custom Streams</h3>
<a name="index-custom-streams"></a>
<a name="index-programming-your-own-streams"></a>
<p>This section describes how you can make a stream that gets input from an
arbitrary data source or writes output to an arbitrary data sink
programmed by you. We call these <em>custom streams</em>. The functions
and types described here are all GNU extensions.
</p>
<hr size="6">
<a name="Streams-and-Cookies"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Custom-Streams" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Hook-Functions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Custom-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Streams-and-Cookies">12.21.2.1 Custom Streams and Cookies</a></td><td> </td><td align="left" valign="top"> The <em>cookie</em> records where to fetch or
store data that is read or written.
</td></tr>
<tr><td align="left" valign="top"><a href="#Hook-Functions">12.21.2.2 Custom Stream Hook Functions</a></td><td> </td><table class="menu" border="0" cellspacing="0">
How you should define the four <em>hook
<p><em> functions that a custom stream needs.
</em></p>@end menu
</em></table>
</table>
<a name="Custom-Streams-and-Cookies"></a>
<h4 class="subsubsection">12.21.2.1 Custom Streams and Cookies</h4>
<a name="index-cookie_002c-for-custom-stream"></a>
<p>Inside every custom stream is a special object called the <em>cookie</em>.
This is an object supplied by you which records where to fetch or store
the data read or written. It is up to you to define a data type to use
for the cookie. The stream functions in the library never refer
directly to its contents, and they don’t even know what the type is;
they record its address with type <code>void *</code>.
</p>
<p>To implement a custom stream, you must specify <em>how</em> to fetch or
store the data in the specified place. You do this by defining
<em>hook functions</em> to read, write, change “file position”, and close
the stream. All four of these functions will be passed the stream’s
cookie so they can tell where to fetch or store the data. The library
functions don’t know what’s inside the cookie, but your functions will
know.
</p>
<p>When you create a custom stream, you must specify the cookie pointer,
and also the four hook functions stored in a structure of type
<code>cookie_io_functions_t</code>.
</p>
<p>These facilities are declared in ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-14"></a>
</p>
<dl>
<dt><a name="index-cookie_005fio_005ffunctions_005ft"></a><u>Data Type:</u> <b>cookie_io_functions_t</b></dt>
<dd><p>This is a structure type that holds the functions that define the
communications protocol between the stream and its cookie. It has
the following members:
</p>
<dl compact="compact">
<dt> <code>cookie_read_function_t *read</code></dt>
<dd><p>This is the function that reads data from the cookie. If the value is a
null pointer instead of a function, then read operations on this stream
always return <code>EOF</code>.
</p>
</dd>
<dt> <code>cookie_write_function_t *write</code></dt>
<dd><p>This is the function that writes data to the cookie. If the value is a
null pointer instead of a function, then data written to the stream is
discarded.
</p>
</dd>
<dt> <code>cookie_seek_function_t *seek</code></dt>
<dd><p>This is the function that performs the equivalent of file positioning on
the cookie. If the value is a null pointer instead of a function, calls
to <code>fseek</code> or <code>fseeko</code> on this stream can only seek to
locations within the buffer; any attempt to seek outside the buffer will
return an <code>ESPIPE</code> error.
</p>
</dd>
<dt> <code>cookie_close_function_t *close</code></dt>
<dd><p>This function performs any appropriate cleanup on the cookie when
closing the stream. If the value is a null pointer instead of a
function, nothing special is done to close the cookie when the stream is
closed.
</p></dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-fopencookie"></a><u>Function:</u> FILE * <b>fopencookie</b><i> (void *<var>cookie</var>, const char *<var>opentype</var>, cookie_io_functions_t <var>io-functions</var>)</i></dt>
<dd><p>This function actually creates the stream for communicating with the
<var>cookie</var> using the functions in the <var>io-functions</var> argument.
The <var>opentype</var> argument is interpreted as for <code>fopen</code>;
see <a href="#Opening-Streams">Opening Streams</a>. (But note that the “truncate on
open” option is ignored.) The new stream is fully buffered.
</p>
<p>The <code>fopencookie</code> function returns the newly created stream, or a null
pointer in case of an error.
</p></dd></dl>
<hr size="6">
<a name="Hook-Functions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Streams-and-Cookies" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Messages" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Custom-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Custom-Stream-Hook-Functions"></a>
<h4 class="subsubsection">12.21.2.2 Custom Stream Hook Functions</h4>
<a name="index-hook-functions-_0028of-custom-streams_0029"></a>
<p>Here are more details on how you should define the four hook functions
that a custom stream needs.
</p>
<p>You should define the function to read data from the cookie as:
</p>
<table><tr><td> </td><td><pre class="smallexample">ssize_t <var>reader</var> (void *<var>cookie</var>, char *<var>buffer</var>, size_t <var>size</var>)
</pre></td></tr></table>
<p>This is very similar to the <code>read</code> function; see <a href="libc_13.html#I_002fO-Primitives">Input and Output Primitives</a>. Your function should transfer up to <var>size</var> bytes into
the <var>buffer</var>, and return the number of bytes read, or zero to
indicate end-of-file. You can return a value of <code>-1</code> to indicate
an error.
</p>
<p>You should define the function to write data to the cookie as:
</p>
<table><tr><td> </td><td><pre class="smallexample">ssize_t <var>writer</var> (void *<var>cookie</var>, const char *<var>buffer</var>, size_t <var>size</var>)
</pre></td></tr></table>
<p>This is very similar to the <code>write</code> function; see <a href="libc_13.html#I_002fO-Primitives">Input and Output Primitives</a>. Your function should transfer up to <var>size</var> bytes from
the buffer, and return the number of bytes written. You can return a
value of <code>-1</code> to indicate an error.
</p>
<p>You should define the function to perform seek operations on the cookie
as:
</p>
<table><tr><td> </td><td><pre class="smallexample">int <var>seeker</var> (void *<var>cookie</var>, off64_t *<var>position</var>, int <var>whence</var>)
</pre></td></tr></table>
<p>For this function, the <var>position</var> and <var>whence</var> arguments are
interpreted as for <code>fgetpos</code>; see <a href="#Portable-Positioning">Portable File-Position Functions</a>.
</p>
<p>After doing the seek operation, your function should store the resulting
file position relative to the beginning of the file in <var>position</var>.
Your function should return a value of <code>0</code> on success and <code>-1</code>
to indicate an error.
</p>
<p>You should define the function to do cleanup operations on the cookie
appropriate for closing the stream as:
</p>
<table><tr><td> </td><td><pre class="smallexample">int <var>cleaner</var> (void *<var>cookie</var>)
</pre></td></tr></table>
<p>Your function should return <code>-1</code> to indicate an error, and <code>0</code>
otherwise.
</p>
<dl>
<dt><a name="index-cookie_005fread_005ffunction"></a><u>Data Type:</u> <b>cookie_read_function</b></dt>
<dd><p>This is the data type that the read function for a custom stream should have.
If you declare the function as shown above, this is the type it will have.
</p></dd></dl>
<dl>
<dt><a name="index-cookie_005fwrite_005ffunction"></a><u>Data Type:</u> <b>cookie_write_function</b></dt>
<dd><p>The data type of the write function for a custom stream.
</p></dd></dl>
<dl>
<dt><a name="index-cookie_005fseek_005ffunction"></a><u>Data Type:</u> <b>cookie_seek_function</b></dt>
<dd><p>The data type of the seek function for a custom stream.
</p></dd></dl>
<dl>
<dt><a name="index-cookie_005fclose_005ffunction"></a><u>Data Type:</u> <b>cookie_close_function</b></dt>
<dd><p>The data type of the close function for a custom stream.
</p></dd></dl>
<hr size="6">
<a name="Formatted-Messages"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Hook-Functions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Printing-Formatted-Messages" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Formatted-Messages-1"></a>
<h2 class="section">12.22 Formatted Messages</h2>
<a name="index-formatted-messages"></a>
<p>On systems which are based on System V messages of programs (especially
the system tools) are printed in a strict form using the <code>fmtmsg</code>
function. The uniformity sometimes helps the user to interpret messages
and the strictness tests of the <code>fmtmsg</code> function ensure that the
programmer follows some minimal requirements.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Printing-Formatted-Messages">12.22.1 Printing Formatted Messages</a></td><td> </td><td align="left" valign="top"> The <code>fmtmsg</code> function.
</td></tr>
<tr><td align="left" valign="top"><a href="#Adding-Severity-Classes">12.22.2 Adding Severity Classes</a></td><td> </td><td align="left" valign="top"> Add more severity classes.
</td></tr>
<tr><td align="left" valign="top"><a href="#Example">12.22.3 How to use <code>fmtmsg</code> and <code>addseverity</code></a></td><td> </td><td align="left" valign="top"></td></tr>
</table>
<hr size="6">
<a name="Printing-Formatted-Messages"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Formatted-Messages" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Adding-Severity-Classes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Messages" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Printing-Formatted-Messages-1"></a>
<h3 class="subsection">12.22.1 Printing Formatted Messages</h3>
<p>Messages can be printed to standard error and/or to the console. To
select the destination the programmer can use the following two values,
bitwise OR combined if wanted, for the <var>classification</var> parameter of
<code>fmtmsg</code>:
</p>
<dl compact="compact">
<dt> <code>MM_PRINT</code>
<a name="index-MM_005fPRINT"></a>
</dt>
<dd><p>Display the message in standard error.
</p></dd>
<dt> <code>MM_CONSOLE</code>
<a name="index-MM_005fCONSOLE"></a>
</dt>
<dd><p>Display the message on the system console.
</p></dd>
</dl>
<p>The erroneous piece of the system can be signalled by exactly one of the
following values which also is bitwise ORed with the
<var>classification</var> parameter to <code>fmtmsg</code>:
</p>
<dl compact="compact">
<dt> <code>MM_HARD</code>
<a name="index-MM_005fHARD"></a>
</dt>
<dd><p>The source of the condition is some hardware.
</p></dd>
<dt> <code>MM_SOFT</code>
<a name="index-MM_005fSOFT"></a>
</dt>
<dd><p>The source of the condition is some software.
</p></dd>
<dt> <code>MM_FIRM</code>
<a name="index-MM_005fFIRM"></a>
</dt>
<dd><p>The source of the condition is some firmware.
</p></dd>
</dl>
<p>A third component of the <var>classification</var> parameter to <code>fmtmsg</code>
can describe the part of the system which detects the problem. This is
done by using exactly one of the following values:
</p>
<dl compact="compact">
<dt> <code>MM_APPL</code>
<a name="index-MM_005fAPPL"></a>
</dt>
<dd><p>The erroneous condition is detected by the application.
</p></dd>
<dt> <code>MM_UTIL</code>
<a name="index-MM_005fUTIL"></a>
</dt>
<dd><p>The erroneous condition is detected by a utility.
</p></dd>
<dt> <code>MM_OPSYS</code>
<a name="index-MM_005fOPSYS"></a>
</dt>
<dd><p>The erroneous condition is detected by the operating system.
</p></dd>
</dl>
<p>A last component of <var>classification</var> can signal the results of this
message. Exactly one of the following values can be used:
</p>
<dl compact="compact">
<dt> <code>MM_RECOVER</code>
<a name="index-MM_005fRECOVER"></a>
</dt>
<dd><p>It is a recoverable error.
</p></dd>
<dt> <code>MM_NRECOV</code>
<a name="index-MM_005fNRECOV"></a>
</dt>
<dd><p>It is a non-recoverable error.
</p></dd>
</dl>
<dl>
<dt><a name="index-fmtmsg"></a><u>Function:</u> int <b>fmtmsg</b><i> (long int <var>classification</var>, const char *<var>label</var>, int <var>severity</var>, const char *<var>text</var>, const char *<var>action</var>, const char *<var>tag</var>)</i></dt>
<dd><p>Display a message described by its parameters on the device(s) specified
in the <var>classification</var> parameter. The <var>label</var> parameter
identifies the source of the message. The string should consist of two
colon separated parts where the first part has not more than 10 and the
second part not more than 14 characters. The <var>text</var> parameter
describes the condition of the error, the <var>action</var> parameter possible
steps to recover from the error and the <var>tag</var> parameter is a
reference to the online documentation where more information can be
found. It should contain the <var>label</var> value and a unique
identification number.
</p>
<p>Each of the parameters can be a special value which means this value
is to be omitted. The symbolic names for these values are:
</p>
<dl compact="compact">
<dt> <code>MM_NULLLBL</code>
<a name="index-MM_005fNULLLBL"></a>
</dt>
<dd><p>Ignore <var>label</var> parameter.
</p></dd>
<dt> <code>MM_NULLSEV</code>
<a name="index-MM_005fNULLSEV"></a>
</dt>
<dd><p>Ignore <var>severity</var> parameter.
</p></dd>
<dt> <code>MM_NULLMC</code>
<a name="index-MM_005fNULLMC"></a>
</dt>
<dd><p>Ignore <var>classification</var> parameter. This implies that nothing is
actually printed.
</p></dd>
<dt> <code>MM_NULLTXT</code>
<a name="index-MM_005fNULLTXT"></a>
</dt>
<dd><p>Ignore <var>text</var> parameter.
</p></dd>
<dt> <code>MM_NULLACT</code>
<a name="index-MM_005fNULLACT"></a>
</dt>
<dd><p>Ignore <var>action</var> parameter.
</p></dd>
<dt> <code>MM_NULLTAG</code>
<a name="index-MM_005fNULLTAG"></a>
</dt>
<dd><p>Ignore <var>tag</var> parameter.
</p></dd>
</dl>
<p>There is another way certain fields can be omitted from the output to
standard error. This is described below in the description of
environment variables influencing the behavior.
</p>
<p>The <var>severity</var> parameter can have one of the values in the following
table:
<a name="index-severity-class"></a>
</p>
<dl compact="compact">
<dt> <code>MM_NOSEV</code>
<a name="index-MM_005fNOSEV"></a>
</dt>
<dd><p>Nothing is printed, this value is the same as <code>MM_NULLSEV</code>.
</p></dd>
<dt> <code>MM_HALT</code>
<a name="index-MM_005fHALT"></a>
</dt>
<dd><p>This value is printed as <code>HALT</code>.
</p></dd>
<dt> <code>MM_ERROR</code>
<a name="index-MM_005fERROR"></a>
</dt>
<dd><p>This value is printed as <code>ERROR</code>.
</p></dd>
<dt> <code>MM_WARNING</code>
<a name="index-MM_005fWARNING"></a>
</dt>
<dd><p>This value is printed as <code>WARNING</code>.
</p></dd>
<dt> <code>MM_INFO</code>
<a name="index-MM_005fINFO"></a>
</dt>
<dd><p>This value is printed as <code>INFO</code>.
</p></dd>
</dl>
<p>The numeric value of these five macros are between <code>0</code> and
<code>4</code>. Using the environment variable <code>SEV_LEVEL</code> or using the
<code>addseverity</code> function one can add more severity levels with their
corresponding string to print. This is described below
(see section <a href="#Adding-Severity-Classes">Adding Severity Classes</a>).
</p>
<p>If no parameter is ignored the output looks like this:
</p>
<table><tr><td> </td><td><pre class="smallexample"><var>label</var>: <var>severity-string</var>: <var>text</var>
TO FIX: <var>action</var> <var>tag</var>
</pre></td></tr></table>
<p>The colons, new line characters and the <code>TO FIX</code> string are
inserted if necessary, i.e., if the corresponding parameter is not
ignored.
</p>
<p>This function is specified in the X/Open Portability Guide. It is also
available on all systems derived from System V.
</p>
<p>The function returns the value <code>MM_OK</code> if no error occurred. If
only the printing to standard error failed, it returns <code>MM_NOMSG</code>.
If printing to the console fails, it returns <code>MM_NOCON</code>. If
nothing is printed <code>MM_NOTOK</code> is returned. Among situations where
all outputs fail this last value is also returned if a parameter value
is incorrect.
</p></dd></dl>
<p>There are two environment variables which influence the behavior of
<code>fmtmsg</code>. The first is <code>MSGVERB</code>. It is used to control the
output actually happening on standard error (<em>not</em> the console
output). Each of the five fields can explicitly be enabled. To do
this the user has to put the <code>MSGVERB</code> variable with a format like
the following in the environment before calling the <code>fmtmsg</code> function
the first time:
</p>
<table><tr><td> </td><td><pre class="smallexample">MSGVERB=<var>keyword</var>[:<var>keyword</var>[:…]]
</pre></td></tr></table>
<p>Valid <var>keyword</var>s are <code>label</code>, <code>severity</code>, <code>text</code>,
<code>action</code>, and <code>tag</code>. If the environment variable is not given
or is the empty string, a not supported keyword is given or the value is
somehow else invalid, no part of the message is masked out.
</p>
<p>The second environment variable which influences the behavior of
<code>fmtmsg</code> is <code>SEV_LEVEL</code>. This variable and the change in the
behavior of <code>fmtmsg</code> is not specified in the X/Open Portability
Guide. It is available in System V systems, though. It can be used to
introduce new severity levels. By default, only the five severity levels
described above are available. Any other numeric value would make
<code>fmtmsg</code> print nothing.
</p>
<p>If the user puts <code>SEV_LEVEL</code> with a format like
</p>
<table><tr><td> </td><td><pre class="smallexample">SEV_LEVEL=[<var>description</var>[:<var>description</var>[:…]]]
</pre></td></tr></table>
<p>in the environment of the process before the first call to
<code>fmtmsg</code>, where <var>description</var> has a value of the form
</p>
<table><tr><td> </td><td><pre class="smallexample"><var>severity-keyword</var>,<var>level</var>,<var>printstring</var>
</pre></td></tr></table>
<p>The <var>severity-keyword</var> part is not used by <code>fmtmsg</code> but it has
to be present. The <var>level</var> part is a string representation of a
number. The numeric value must be a number greater than 4. This value
must be used in the <var>severity</var> parameter of <code>fmtmsg</code> to select
this class. It is not possible to overwrite any of the predefined
classes. The <var>printstring</var> is the string printed when a message of
this class is processed by <code>fmtmsg</code> (see above, <code>fmtsmg</code> does
not print the numeric value but instead the string representation).
</p>
<hr size="6">
<a name="Adding-Severity-Classes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Printing-Formatted-Messages" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Example" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Messages" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="Adding-Severity-Classes-1"></a>
<h3 class="subsection">12.22.2 Adding Severity Classes</h3>
<a name="index-severity-class-1"></a>
<p>There is another possibility to introduce severity classes besides using
the environment variable <code>SEV_LEVEL</code>. This simplifies the task of
introducing new classes in a running program. One could use the
<code>setenv</code> or <code>putenv</code> function to set the environment variable,
but this is toilsome.
</p>
<dl>
<dt><a name="index-addseverity"></a><u>Function:</u> int <b>addseverity</b><i> (int <var>severity</var>, const char *<var>string</var>)</i></dt>
<dd><p>This function allows the introduction of new severity classes which can be
addressed by the <var>severity</var> parameter of the <code>fmtmsg</code> function.
The <var>severity</var> parameter of <code>addseverity</code> must match the value
for the parameter with the same name of <code>fmtmsg</code>, and <var>string</var>
is the string printed in the actual messages instead of the numeric
value.
</p>
<p>If <var>string</var> is <code>NULL</code> the severity class with the numeric value
according to <var>severity</var> is removed.
</p>
<p>It is not possible to overwrite or remove one of the default severity
classes. All calls to <code>addseverity</code> with <var>severity</var> set to one
of the values for the default classes will fail.
</p>
<p>The return value is <code>MM_OK</code> if the task was successfully performed.
If the return value is <code>MM_NOTOK</code> something went wrong. This could
mean that no more memory is available or a class is not available when
it has to be removed.
</p>
<p>This function is not specified in the X/Open Portability Guide although
the <code>fmtsmg</code> function is. It is available on System V systems.
</p></dd></dl>
<hr size="6">
<a name="Example"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Adding-Severity-Classes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Formatted-Messages" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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="How-to-use-fmtmsg-and-addseverity"></a>
<h3 class="subsection">12.22.3 How to use <code>fmtmsg</code> and <code>addseverity</code></h3>
<p>Here is a simple example program to illustrate the use of the both
functions described in this section.
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <fmtmsg.h>
int
main (void)
{
addseverity (5, "NOTE2");
fmtmsg (MM_PRINT, "only1field", MM_INFO, "text2", "action2", "tag2");
fmtmsg (MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to manual",
"UX:cat:001");
fmtmsg (MM_PRINT, "label:foo", 6, "text", "action", "tag");
return 0;
}
</pre></td></tr></table>
<p>The second call to <code>fmtmsg</code> illustrates a use of this function as
it usually occurs on System V systems, which heavily use this function.
It seems worthwhile to give a short explanation here of how this system
works on System V. The value of the
<var>label</var> field (<code>UX:cat</code>) says that the error occurred in the
Unix program <code>cat</code>. The explanation of the error follows and the
value for the <var>action</var> parameter is <code>"refer to manual"</code>. One
could be more specific here, if necessary. The <var>tag</var> field contains,
as proposed above, the value of the string given for the <var>label</var>
parameter, and additionally a unique ID (<code>001</code> in this case). For
a GNU environment this string could contain a reference to the
corresponding node in the Info page for the program.
</p>
<p>Running this program without specifying the <code>MSGVERB</code> and
<code>SEV_LEVEL</code> function produces the following output:
</p>
<table><tr><td> </td><td><pre class="smallexample">UX:cat: NOTE2: invalid syntax
TO FIX: refer to manual UX:cat:001
</pre></td></tr></table>
<p>We see the different fields of the message and how the extra glue (the
colons and the <code>TO FIX</code> string) are printed. But only one of the
three calls to <code>fmtmsg</code> produced output. The first call does not
print anything because the <var>label</var> parameter is not in the correct
form. The string must contain two fields, separated by a colon
(see section <a href="#Printing-Formatted-Messages">Printing Formatted Messages</a>). The third <code>fmtmsg</code> call
produced no output since the class with the numeric value <code>6</code> is
not defined. Although a class with numeric value <code>5</code> is also not
defined by default, the call to <code>addseverity</code> introduces it and
the second call to <code>fmtmsg</code> produces the above output.
</p>
<p>When we change the environment of the program to contain
<code>SEV_LEVEL=XXX,6,NOTE</code> when running it we get a different result:
</p>
<table><tr><td> </td><td><pre class="smallexample">UX:cat: NOTE2: invalid syntax
TO FIX: refer to manual UX:cat:001
label:foo: NOTE: text
TO FIX: action tag
</pre></td></tr></table>
<p>Now the third call to <code>fmtmsg</code> produced some output and we see how
the string <code>NOTE</code> from the environment variable appears in the
message.
</p>
<p>Now we can reduce the output by specifying which fields we are
interested in. If we additionally set the environment variable
<code>MSGVERB</code> to the value <code>severity:label:action</code> we get the
following output:
</p>
<table><tr><td> </td><td><pre class="smallexample">UX:cat: NOTE2
TO FIX: refer to manual
label:foo: NOTE
TO FIX: action
</pre></td></tr></table>
<p>I.e., the output produced by the <var>text</var> and the <var>tag</var> parameters
to <code>fmtmsg</code> vanished. Please also note that now there is no colon
after the <code>NOTE</code> and <code>NOTE2</code> strings in the output. This is
not necessary since there is no more output on this line because the text
is missing.
</p><hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#I_002fO-on-Streams" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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>
|