/usr/share/doc/glibc-doc/html/libc_14.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 | <!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: 14. File System Interface</title>
<meta name="description" content="The GNU C Library: 14. File System Interface">
<meta name="keywords" content="The GNU C Library: 14. File System Interface">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="File-System-Interface"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="libc_13.html#IOCTLs" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Working-Directory" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" 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_15.html#Pipes-and-FIFOs" 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-System-Interface-1"></a>
<h1 class="chapter">14. File System Interface</h1>
<p>This chapter describes the GNU C library’s functions for manipulating
files. Unlike the input and output functions (see section <a href="libc_12.html#I_002fO-on-Streams">Input/Output on Streams</a>;
see section <a href="libc_13.html#Low_002dLevel-I_002fO">Low-Level Input/Output</a>), these functions are concerned with operating
on the files themselves rather than on their contents.
</p>
<p>Among the facilities described in this chapter are functions for
examining or modifying directories, functions for renaming and deleting
files, and functions for examining and setting file attributes such as
access permissions and modification times.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Working-Directory">14.1 Working Directory</a></td><td> </td><td align="left" valign="top"> This is used to resolve relative
file names.
</td></tr>
<tr><td align="left" valign="top"><a href="#Accessing-Directories">14.2 Accessing Directories</a></td><td> </td><td align="left" valign="top"> Finding out what files a directory
contains.
</td></tr>
<tr><td align="left" valign="top"><a href="#Working-with-Directory-Trees">14.3 Working with Directory Trees</a></td><td> </td><td align="left" valign="top"> Apply actions to all files or a selectable
subset of a directory hierarchy.
</td></tr>
<tr><td align="left" valign="top"><a href="#Hard-Links">14.4 Hard Links</a></td><td> </td><td align="left" valign="top"> Adding alternate names to a file.
</td></tr>
<tr><td align="left" valign="top"><a href="#Symbolic-Links">14.5 Symbolic Links</a></td><td> </td><td align="left" valign="top"> A file that “points to” a file name.
</td></tr>
<tr><td align="left" valign="top"><a href="#Deleting-Files">14.6 Deleting Files</a></td><td> </td><td align="left" valign="top"> How to delete a file, and what that means.
</td></tr>
<tr><td align="left" valign="top"><a href="#Renaming-Files">14.7 Renaming Files</a></td><td> </td><td align="left" valign="top"> Changing a file’s name.
</td></tr>
<tr><td align="left" valign="top"><a href="#Creating-Directories">14.8 Creating Directories</a></td><td> </td><td align="left" valign="top"> A system call just for creating a directory.
</td></tr>
<tr><td align="left" valign="top"><a href="#File-Attributes">14.9 File Attributes</a></td><td> </td><td align="left" valign="top"> Attributes of individual files.
</td></tr>
<tr><td align="left" valign="top"><a href="#Making-Special-Files">14.10 Making Special Files</a></td><td> </td><td align="left" valign="top"> How to create special files.
</td></tr>
<tr><td align="left" valign="top"><a href="#Temporary-Files">14.11 Temporary Files</a></td><td> </td><td align="left" valign="top"> Naming and creating temporary files.
</td></tr>
</table>
<hr size="6">
<a name="Working-Directory"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#File-System-Interface" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Accessing-Directories" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Working-Directory-1"></a>
<h2 class="section">14.1 Working Directory</h2>
<a name="index-current-working-directory"></a>
<a name="index-working-directory"></a>
<a name="index-change-working-directory"></a>
<p>Each process has associated with it a directory, called its <em>current
working directory</em> or simply <em>working directory</em>, that is used in
the resolution of relative file names (see section <a href="libc_11.html#File-Name-Resolution">File Name Resolution</a>).
</p>
<p>When you log in and begin a new session, your working directory is
initially set to the home directory associated with your login account
in the system user database. You can find any user’s home directory
using the <code>getpwuid</code> or <code>getpwnam</code> functions; see <a href="libc_29.html#User-Database">User Database</a>.
</p>
<p>Users can change the working directory using shell commands like
<code>cd</code>. The functions described in this section are the primitives
used by those commands and by other programs for examining and changing
the working directory.
<a name="index-cd"></a>
</p>
<p>Prototypes for these functions are declared in the header file
‘<tt>unistd.h</tt>’.
<a name="index-unistd_002eh-4"></a>
</p>
<dl>
<dt><a name="index-getcwd"></a><u>Function:</u> char * <b>getcwd</b><i> (char *<var>buffer</var>, size_t <var>size</var>)</i></dt>
<dd><p>The <code>getcwd</code> function returns an absolute file name representing
the current working directory, storing it in the character array
<var>buffer</var> that you provide. The <var>size</var> argument is how you tell
the system the allocation size of <var>buffer</var>.
</p>
<p>The GNU library version of this function also permits you to specify a
null pointer for the <var>buffer</var> argument. Then <code>getcwd</code>
allocates a buffer automatically, as with <code>malloc</code>
(see section <a href="libc_3.html#Unconstrained-Allocation">Unconstrained Allocation</a>). If the <var>size</var> is greater than
zero, then the buffer is that large; otherwise, the buffer is as large
as necessary to hold the result.
</p>
<p>The return value is <var>buffer</var> on success and a null pointer on failure.
The following <code>errno</code> error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EINVAL</code></dt>
<dd><p>The <var>size</var> argument is zero and <var>buffer</var> is not a null pointer.
</p>
</dd>
<dt> <code>ERANGE</code></dt>
<dd><p>The <var>size</var> argument is less than the length of the working directory
name. You need to allocate a bigger array and try again.
</p>
</dd>
<dt> <code>EACCES</code></dt>
<dd><p>Permission to read or search a component of the file name was denied.
</p></dd>
</dl>
</dd></dl>
<p>You could implement the behavior of GNU’s <code>getcwd (NULL, 0)</code>
using only the standard behavior of <code>getcwd</code>:
</p>
<table><tr><td> </td><td><pre class="smallexample">char *
gnu_getcwd ()
{
size_t size = 100;
while (1)
{
char *buffer = (char *) xmalloc (size);
if (getcwd (buffer, size) == buffer)
return buffer;
free (buffer);
if (errno != ERANGE)
return 0;
size *= 2;
}
}
</pre></td></tr></table>
<p>See section <a href="libc_3.html#Malloc-Examples">Examples of <code>malloc</code></a>, for information about <code>xmalloc</code>, which is
not a library function but is a customary name used in most GNU
software.
</p>
<dl>
<dt><a name="index-getwd"></a><u>Deprecated Function:</u> char * <b>getwd</b><i> (char *<var>buffer</var>)</i></dt>
<dd><p>This is similar to <code>getcwd</code>, but has no way to specify the size of
the buffer. The GNU library provides <code>getwd</code> only
for backwards compatibility with BSD.
</p>
<p>The <var>buffer</var> argument should be a pointer to an array at least
<code>PATH_MAX</code> bytes long (see section <a href="libc_31.html#Limits-for-Files">Limits on File System Capacity</a>). In the GNU
system there is no limit to the size of a file name, so this is not
necessarily enough space to contain the directory name. That is why
this function is deprecated.
</p></dd></dl>
<dl>
<dt><a name="index-get_005fcurrent_005fdir_005fname"></a><u>Function:</u> char * <b>get_current_dir_name</b><i> (void)</i></dt>
<dd><a name="index-PWD"></a>
<p>This <code>get_current_dir_name</code> function is basically equivalent to
<code>getcwd (NULL, 0)</code>. The only difference is that the value of
the <code>PWD</code> variable is returned if this value is correct. This is a
subtle difference which is visible if the path described by the
<code>PWD</code> value is using one or more symbol links in which case the
value returned by <code>getcwd</code> can resolve the symbol links and
therefore yield a different result.
</p>
<p>This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-chdir"></a><u>Function:</u> int <b>chdir</b><i> (const char *<var>filename</var>)</i></dt>
<dd><p>This function is used to set the process’s working directory to
<var>filename</var>.
</p>
<p>The normal, successful return value from <code>chdir</code> is <code>0</code>. A
value of <code>-1</code> is returned to indicate an error. The <code>errno</code>
error conditions defined for this function are the usual file name
syntax errors (see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), plus <code>ENOTDIR</code> if the
file <var>filename</var> is not a directory.
</p></dd></dl>
<dl>
<dt><a name="index-fchdir"></a><u>Function:</u> int <b>fchdir</b><i> (int <var>filedes</var>)</i></dt>
<dd><p>This function is used to set the process’s working directory to
directory associated with the file descriptor <var>filedes</var>.
</p>
<p>The normal, successful return value from <code>fchdir</code> is <code>0</code>. A
value of <code>-1</code> is returned to indicate an error. The following
<code>errno</code> error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EACCES</code></dt>
<dd><p>Read permission is denied for the directory named by <code>dirname</code>.
</p>
</dd>
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> argument is not a valid file descriptor.
</p>
</dd>
<dt> <code>ENOTDIR</code></dt>
<dd><p>The file descriptor <var>filedes</var> is not associated with a directory.
</p>
</dd>
<dt> <code>EINTR</code></dt>
<dd><p>The function call was interrupt by a signal.
</p>
</dd>
<dt> <code>EIO</code></dt>
<dd><p>An I/O error occurred.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="Accessing-Directories"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Working-Directory" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Directory-Entries" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Accessing-Directories-1"></a>
<h2 class="section">14.2 Accessing Directories</h2>
<a name="index-accessing-directories"></a>
<a name="index-reading-from-a-directory"></a>
<a name="index-directories_002c-accessing"></a>
<p>The facilities described in this section let you read the contents of a
directory file. This is useful if you want your program to list all the
files in a directory, perhaps as part of a menu.
</p>
<a name="index-directory-stream"></a>
<p>The <code>opendir</code> function opens a <em>directory stream</em> whose
elements are directory entries. Alternatively <code>fdopendir</code> can be
used which can have advantages if the program needs to have more
control over the way the directory is opened for reading. This
allows, for instance, to pass the <code>O_NOATIME</code> flag to
<code>open</code>.
</p>
<p>You use the <code>readdir</code> function on the directory stream to
retrieve these entries, represented as <code>struct dirent</code>
objects. The name of the file for each entry is stored in the
<code>d_name</code> member of this structure. There are obvious parallels
here to the stream facilities for ordinary files, described in
<a href="libc_12.html#I_002fO-on-Streams">Input/Output on Streams</a>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Directory-Entries">14.2.1 Format of a Directory Entry</a></td><td> </td><td align="left" valign="top"> Format of one directory entry.
</td></tr>
<tr><td align="left" valign="top"><a href="#Opening-a-Directory">14.2.2 Opening a Directory Stream</a></td><td> </td><td align="left" valign="top"> How to open a directory stream.
</td></tr>
<tr><td align="left" valign="top"><a href="#Reading_002fClosing-Directory">14.2.3 Reading and Closing a Directory Stream</a></td><td> </td><td align="left" valign="top"> How to read directory entries from the stream.
</td></tr>
<tr><td align="left" valign="top"><a href="#Simple-Directory-Lister">14.2.4 Simple Program to List a Directory</a></td><td> </td><td align="left" valign="top"> A very simple directory listing program.
</td></tr>
<tr><td align="left" valign="top"><a href="#Random-Access-Directory">14.2.5 Random Access in a Directory Stream</a></td><td> </td><td align="left" valign="top"> Rereading part of the directory
already read with the same stream.
</td></tr>
<tr><td align="left" valign="top"><a href="#Scanning-Directory-Content">14.2.6 Scanning the Content of a Directory</a></td><td> </td><td align="left" valign="top"> Get entries for user selected subset of
contents in given directory.
</td></tr>
<tr><td align="left" valign="top"><a href="#Simple-Directory-Lister-Mark-II">14.2.7 Simple Program to List a Directory, Mark II</a></td><td> </td><td align="left" valign="top"> Revised version of the program.
</td></tr>
</table>
<hr size="6">
<a name="Directory-Entries"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Accessing-Directories" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Opening-a-Directory" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Accessing-Directories" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Format-of-a-Directory-Entry"></a>
<h3 class="subsection">14.2.1 Format of a Directory Entry</h3>
<a name="index-dirent_002eh-1"></a>
<p>This section describes what you find in a single directory entry, as you
might obtain it from a directory stream. All the symbols are declared
in the header file ‘<tt>dirent.h</tt>’.
</p>
<dl>
<dt><a name="index-struct-dirent"></a><u>Data Type:</u> <b>struct dirent</b></dt>
<dd><p>This is a structure type used to return information about directory
entries. It contains the following fields:
</p>
<dl compact="compact">
<dt> <code>char d_name[]</code></dt>
<dd><p>This is the null-terminated file name component. This is the only
field you can count on in all POSIX systems.
</p>
</dd>
<dt> <code>ino_t d_fileno</code></dt>
<dd><p>This is the file serial number. For BSD compatibility, you can also
refer to this member as <code>d_ino</code>. In the GNU system and most POSIX
systems, for most files this the same as the <code>st_ino</code> member that
<code>stat</code> will return for the file. See section <a href="#File-Attributes">File Attributes</a>.
</p>
</dd>
<dt> <code>unsigned char d_namlen</code></dt>
<dd><p>This is the length of the file name, not including the terminating null
character. Its type is <code>unsigned char</code> because that is the integer
type of the appropriate size
</p>
</dd>
<dt> <code>unsigned char d_type</code></dt>
<dd><p>This is the type of the file, possibly unknown. The following constants
are defined for its value:
</p>
<dl compact="compact">
<dt> <code>DT_UNKNOWN</code>
<a name="index-DT_005fUNKNOWN"></a>
</dt>
<dd><p>The type is unknown. On some systems this is the only value returned.
</p>
</dd>
<dt> <code>DT_REG</code>
<a name="index-DT_005fREG"></a>
</dt>
<dd><p>A regular file.
</p>
</dd>
<dt> <code>DT_DIR</code>
<a name="index-DT_005fDIR"></a>
</dt>
<dd><p>A directory.
</p>
</dd>
<dt> <code>DT_FIFO</code>
<a name="index-DT_005fFIFO"></a>
</dt>
<dd><p>A named pipe, or FIFO. See section <a href="libc_15.html#FIFO-Special-Files">FIFO Special Files</a>.
</p>
</dd>
<dt> <code>DT_SOCK</code>
<a name="index-DT_005fSOCK"></a>
</dt>
<dd><p>A local-domain socket. </p>
</dd>
<dt> <code>DT_CHR</code>
<a name="index-DT_005fCHR"></a>
</dt>
<dd><p>A character device.
</p>
</dd>
<dt> <code>DT_BLK</code>
<a name="index-DT_005fBLK"></a>
</dt>
<dd><p>A block device.
</p></dd>
</dl>
<p>This member is a BSD extension. The symbol <code>_DIRENT_HAVE_D_TYPE</code>
is defined if this member is available. On systems where it is used, it
corresponds to the file type bits in the <code>st_mode</code> member of
<code>struct statbuf</code>. If the value cannot be determine the member
value is DT_UNKNOWN. These two macros convert between <code>d_type</code>
values and <code>st_mode</code> values:
</p>
<dl>
<dt><a name="index-IFTODT"></a><u>Function:</u> int <b>IFTODT</b><i> (mode_t <var>mode</var>)</i></dt>
<dd><p>This returns the <code>d_type</code> value corresponding to <var>mode</var>.
</p></dd></dl>
<dl>
<dt><a name="index-DTTOIF"></a><u>Function:</u> mode_t <b>DTTOIF</b><i> (int <var>dtype</var>)</i></dt>
<dd><p>This returns the <code>st_mode</code> value corresponding to <var>dtype</var>.
</p></dd></dl>
</dd>
</dl>
<p>This structure may contain additional members in the future. Their
availability is always announced in the compilation environment by a
macro names <code>_DIRENT_HAVE_D_<var>xxx</var></code> where <var>xxx</var> is replaced
by the name of the new member. For instance, the member <code>d_reclen</code>
available on some systems is announced through the macro
<code>_DIRENT_HAVE_D_RECLEN</code>.
</p>
<p>When a file has multiple names, each name has its own directory entry.
The only way you can tell that the directory entries belong to a
single file is that they have the same value for the <code>d_fileno</code>
field.
</p>
<p>File attributes such as size, modification times etc., are part of the
file itself, not of any particular directory entry. See section <a href="#File-Attributes">File Attributes</a>.
</p></dd></dl>
<hr size="6">
<a name="Opening-a-Directory"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Directory-Entries" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Reading_002fClosing-Directory" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Accessing-Directories" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Opening-a-Directory-Stream"></a>
<h3 class="subsection">14.2.2 Opening a Directory Stream</h3>
<a name="index-dirent_002eh-2"></a>
<p>This section describes how to open a directory stream. All the symbols
are declared in the header file ‘<tt>dirent.h</tt>’.
</p>
<dl>
<dt><a name="index-DIR"></a><u>Data Type:</u> <b>DIR</b></dt>
<dd><p>The <code>DIR</code> data type represents a directory stream.
</p></dd></dl>
<p>You shouldn’t ever allocate objects of the <code>struct dirent</code> or
<code>DIR</code> data types, since the directory access functions do that for
you. Instead, you refer to these objects using the pointers returned by
the following functions.
</p>
<dl>
<dt><a name="index-opendir"></a><u>Function:</u> DIR * <b>opendir</b><i> (const char *<var>dirname</var>)</i></dt>
<dd><p>The <code>opendir</code> function opens and returns a directory stream for
reading the directory whose file name is <var>dirname</var>. The stream has
type <code>DIR *</code>.
</p>
<p>If unsuccessful, <code>opendir</code> returns a null pointer. In addition to
the usual file name errors (see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), the
following <code>errno</code> error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EACCES</code></dt>
<dd><p>Read permission is denied for the directory named by <code>dirname</code>.
</p>
</dd>
<dt> <code>EMFILE</code></dt>
<dd><p>The process has too many files open.
</p>
</dd>
<dt> <code>ENFILE</code></dt>
<dd><p>The entire system, or perhaps the file system which contains the
directory, cannot support any additional open files at the moment.
(This problem cannot happen on the GNU system.)
</p>
</dd>
<dt> <code>ENOMEM</code></dt>
<dd><p>Not enough memory available.
</p></dd>
</dl>
<p>The <code>DIR</code> type is typically implemented using a file descriptor,
and the <code>opendir</code> function in terms of the <code>open</code> function.
See section <a href="libc_13.html#Low_002dLevel-I_002fO">Low-Level Input/Output</a>. Directory streams and the underlying
file descriptors are closed on <code>exec</code> (see section <a href="libc_26.html#Executing-a-File">Executing a File</a>).
</p></dd></dl>
<p>The directory which is opened for reading by <code>opendir</code> is
identified by the name. In some situations this is not sufficient.
Or the way <code>opendir</code> implicitly creates a file descriptor for the
directory is not the way a program might want it. In these cases an
alternative interface can be used.
</p>
<dl>
<dt><a name="index-fdopendir"></a><u>Function:</u> DIR * <b>fdopendir</b><i> (int <var>fd</var>)</i></dt>
<dd><p>The <code>fdopendir</code> function works just like <code>opendir</code> but
instead of taking a file name and opening a file descriptor for the
directory the caller is required to provide a file descriptor. This
file descriptor is then used in subsequent uses of the returned
directory stream object.
</p>
<p>The caller must make sure the file descriptor is associated with a
directory and it allows reading.
</p>
<p>If the <code>fdopendir</code> call returns successfully the file descriptor
is now under the control of the system. It can be used in the same
way the descriptor implicitly created by <code>opendir</code> can be used
but the program must not close the descriptor.
</p>
<p>In case the function is unsuccessful it returns a null pointer and the
file descriptor remains to be usable by the program. The following
<code>errno</code> error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The file descriptor is not valid.
</p>
</dd>
<dt> <code>ENOTDIR</code></dt>
<dd><p>The file descriptor is not associated with a directory.
</p>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p>The descriptor does not allow reading the directory content.
</p>
</dd>
<dt> <code>ENOMEM</code></dt>
<dd><p>Not enough memory available.
</p></dd>
</dl>
</dd></dl>
<p>In some situations it can be desirable to get hold of the file
descriptor which is created by the <code>opendir</code> call. For instance,
to switch the current working directory to the directory just read the
<code>fchdir</code> function could be used. Historically the <code>DIR</code> type
was exposed and programs could access the fields. This does not happen
in the GNU C library. Instead a separate function is provided to allow
access.
</p>
<dl>
<dt><a name="index-dirfd"></a><u>Function:</u> int <b>dirfd</b><i> (DIR *<var>dirstream</var>)</i></dt>
<dd><p>The function <code>dirfd</code> returns the file descriptor associated with
the directory stream <var>dirstream</var>. This descriptor can be used until
the directory is closed with <code>closedir</code>. If the directory stream
implementation is not using file descriptors the return value is
<code>-1</code>.
</p></dd></dl>
<hr size="6">
<a name="Reading_002fClosing-Directory"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Opening-a-Directory" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Simple-Directory-Lister" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Accessing-Directories" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Reading-and-Closing-a-Directory-Stream"></a>
<h3 class="subsection">14.2.3 Reading and Closing a Directory Stream</h3>
<a name="index-dirent_002eh-3"></a>
<p>This section describes how to read directory entries from a directory
stream, and how to close the stream when you are done with it. All the
symbols are declared in the header file ‘<tt>dirent.h</tt>’.
</p>
<dl>
<dt><a name="index-readdir"></a><u>Function:</u> struct dirent * <b>readdir</b><i> (DIR *<var>dirstream</var>)</i></dt>
<dd><p>This function reads the next entry from the directory. It normally
returns a pointer to a structure containing information about the file.
This structure is statically allocated and can be rewritten by a
subsequent call.
</p>
<p><strong>Portability Note:</strong> On some systems <code>readdir</code> may not
return entries for ‘<tt>.</tt>’ and ‘<tt>..</tt>’, even though these are always
valid file names in any directory. See section <a href="libc_11.html#File-Name-Resolution">File Name Resolution</a>.
</p>
<p>If there are no more entries in the directory or an error is detected,
<code>readdir</code> returns a null pointer. The following <code>errno</code> error
conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>dirstream</var> argument is not valid.
</p></dd>
</dl>
<p><code>readdir</code> is not thread safe. Multiple threads using
<code>readdir</code> on the same <var>dirstream</var> may overwrite the return
value. Use <code>readdir_r</code> when this is critical.
</p></dd></dl>
<dl>
<dt><a name="index-readdir_005fr"></a><u>Function:</u> int <b>readdir_r</b><i> (DIR *<var>dirstream</var>, struct dirent *<var>entry</var>, struct dirent **<var>result</var>)</i></dt>
<dd><p>This function is the reentrant version of <code>readdir</code>. Like
<code>readdir</code> it returns the next entry from the directory. But to
prevent conflicts between simultaneously running threads the result is
not stored in statically allocated memory. Instead the argument
<var>entry</var> points to a place to store the result.
</p>
<p>Normally <code>readdir_r</code> returns zero and sets <code>*<var>result</var></code>
to <var>entry</var>. If there are no more entries in the directory or an
error is detected, <code>readdir_r</code> sets <code>*<var>result</var></code> to a
null pointer and returns a nonzero error code, also stored in
<code>errno</code>, as described for <code>readdir</code>.
</p>
<p><strong>Portability Note:</strong> On some systems <code>readdir_r</code> may not
return a NUL terminated string for the file name, even when there is no
<code>d_reclen</code> field in <code>struct dirent</code> and the file
name is the maximum allowed size. Modern systems all have the
<code>d_reclen</code> field, and on old systems multi-threading is not
critical. In any case there is no such problem with the <code>readdir</code>
function, so that even on systems without the <code>d_reclen</code> member one
could use multiple threads by using external locking.
</p>
<p>It is also important to look at the definition of the <code>struct
dirent</code> type. Simply passing a pointer to an object of this type for
the second parameter of <code>readdir_r</code> might not be enough. Some
systems don’t define the <code>d_name</code> element sufficiently long. In
this case the user has to provide additional space. There must be room
for at least <code>NAME_MAX + 1</code> characters in the <code>d_name</code> array.
Code to call <code>readdir_r</code> could look like this:
</p>
<table><tr><td> </td><td><pre class="smallexample"> union
{
struct dirent d;
char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];
} u;
if (readdir_r (dir, &u.d, &res) == 0)
…
</pre></td></tr></table>
</dd></dl>
<p>To support large filesystems on 32-bit machines there are LFS variants
of the last two functions.
</p>
<dl>
<dt><a name="index-readdir64"></a><u>Function:</u> struct dirent64 * <b>readdir64</b><i> (DIR *<var>dirstream</var>)</i></dt>
<dd><p>The <code>readdir64</code> function is just like the <code>readdir</code> function
except that it returns a pointer to a record of type <code>struct
dirent64</code>. Some of the members of this data type (notably <code>d_ino</code>)
might have a different size to allow large filesystems.
</p>
<p>In all other aspects this function is equivalent to <code>readdir</code>.
</p></dd></dl>
<dl>
<dt><a name="index-readdir64_005fr"></a><u>Function:</u> int <b>readdir64_r</b><i> (DIR *<var>dirstream</var>, struct dirent64 *<var>entry</var>, struct dirent64 **<var>result</var>)</i></dt>
<dd><p>The <code>readdir64_r</code> function is equivalent to the <code>readdir_r</code>
function except that it takes parameters of base type <code>struct
dirent64</code> instead of <code>struct dirent</code> in the second and third
position. The same precautions mentioned in the documentation of
<code>readdir_r</code> also apply here.
</p></dd></dl>
<dl>
<dt><a name="index-closedir"></a><u>Function:</u> int <b>closedir</b><i> (DIR *<var>dirstream</var>)</i></dt>
<dd><p>This function closes the directory stream <var>dirstream</var>. It returns
<code>0</code> on success and <code>-1</code> on failure.
</p>
<p>The following <code>errno</code> error conditions are defined for this
function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>dirstream</var> argument is not valid.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="Simple-Directory-Lister"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Reading_002fClosing-Directory" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Random-Access-Directory" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Accessing-Directories" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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-Program-to-List-a-Directory"></a>
<h3 class="subsection">14.2.4 Simple Program to List a Directory</h3>
<p>Here’s a simple program that prints the names of the files in
the current working directory:
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <stdio.h>
#include <sys/types.h>
#include <dirent.h>
</pre><pre class="smallexample">
int
main (void)
{
DIR *dp;
struct dirent *ep;
dp = opendir ("./");
if (dp != NULL)
{
while (ep = readdir (dp))
puts (ep->d_name);
(void) closedir (dp);
}
else
perror ("Couldn't open the directory");
return 0;
}
</pre></td></tr></table>
<p>The order in which files appear in a directory tends to be fairly
random. A more useful program would sort the entries (perhaps by
alphabetizing them) before printing them; see
<a href="#Scanning-Directory-Content">Scanning the Content of a Directory</a>, and <a href="libc_9.html#Array-Sort-Function">Array Sort Function</a>.
</p>
<hr size="6">
<a name="Random-Access-Directory"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Simple-Directory-Lister" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Scanning-Directory-Content" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Accessing-Directories" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Random-Access-in-a-Directory-Stream"></a>
<h3 class="subsection">14.2.5 Random Access in a Directory Stream</h3>
<a name="index-dirent_002eh-4"></a>
<p>This section describes how to reread parts of a directory that you have
already read from an open directory stream. All the symbols are
declared in the header file ‘<tt>dirent.h</tt>’.
</p>
<dl>
<dt><a name="index-rewinddir"></a><u>Function:</u> void <b>rewinddir</b><i> (DIR *<var>dirstream</var>)</i></dt>
<dd><p>The <code>rewinddir</code> function is used to reinitialize the directory
stream <var>dirstream</var>, so that if you call <code>readdir</code> it
returns information about the first entry in the directory again. This
function also notices if files have been added or removed to the
directory since it was opened with <code>opendir</code>. (Entries for these
files might or might not be returned by <code>readdir</code> if they were
added or removed since you last called <code>opendir</code> or
<code>rewinddir</code>.)
</p></dd></dl>
<dl>
<dt><a name="index-int"></a><u>Function:</u> long <b>int</b><i> telldir (DIR *<var>dirstream</var>)</i></dt>
<dd><p>The <code>telldir</code> function returns the file position of the directory
stream <var>dirstream</var>. You can use this value with <code>seekdir</code> to
restore the directory stream to that position.
</p></dd></dl>
<dl>
<dt><a name="index-seekdir"></a><u>Function:</u> void <b>seekdir</b><i> (DIR *<var>dirstream</var>, long int <var>pos</var>)</i></dt>
<dd><p>The <code>seekdir</code> function sets the file position of the directory
stream <var>dirstream</var> to <var>pos</var>. The value <var>pos</var> must be the
result of a previous call to <code>telldir</code> on this particular stream;
closing and reopening the directory can invalidate values returned by
<code>telldir</code>.
</p></dd></dl>
<hr size="6">
<a name="Scanning-Directory-Content"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Random-Access-Directory" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Simple-Directory-Lister-Mark-II" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Accessing-Directories" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Scanning-the-Content-of-a-Directory"></a>
<h3 class="subsection">14.2.6 Scanning the Content of a Directory</h3>
<p>A higher-level interface to the directory handling functions is the
<code>scandir</code> function. With its help one can select a subset of the
entries in a directory, possibly sort them and get a list of names as
the result.
</p>
<dl>
<dt><a name="index-scandir"></a><u>Function:</u> int <b>scandir</b><i> (const char *<var>dir</var>, struct dirent ***<var>namelist</var>, int (*<var>selector</var>) (const struct dirent *), int (*<var>cmp</var>) (const void *, const void *))</i></dt>
<dd>
<p>The <code>scandir</code> function scans the contents of the directory selected
by <var>dir</var>. The result in *<var>namelist</var> is an array of pointers to
structure of type <code>struct dirent</code> which describe all selected
directory entries and which is allocated using <code>malloc</code>. Instead
of always getting all directory entries returned, the user supplied
function <var>selector</var> can be used to decide which entries are in the
result. Only the entries for which <var>selector</var> returns a non-zero
value are selected.
</p>
<p>Finally the entries in *<var>namelist</var> are sorted using the
user-supplied function <var>cmp</var>. The arguments passed to the <var>cmp</var>
function are of type <code>struct dirent **</code>, therefore one cannot
directly use the <code>strcmp</code> or <code>strcoll</code> functions; instead see
the functions <code>alphasort</code> and <code>versionsort</code> below.
</p>
<p>The return value of the function is the number of entries placed in
*<var>namelist</var>. If it is <code>-1</code> an error occurred (either the
directory could not be opened for reading or the malloc call failed) and
the global variable <code>errno</code> contains more information on the error.
</p></dd></dl>
<p>As described above the fourth argument to the <code>scandir</code> function
must be a pointer to a sorting function. For the convenience of the
programmer the GNU C library contains implementations of functions which
are very helpful for this purpose.
</p>
<dl>
<dt><a name="index-alphasort"></a><u>Function:</u> int <b>alphasort</b><i> (const void *<var>a</var>, const void *<var>b</var>)</i></dt>
<dd><p>The <code>alphasort</code> function behaves like the <code>strcoll</code> function
(see section <a href="libc_5.html#String_002fArray-Comparison">String/Array Comparison</a>). The difference is that the arguments
are not string pointers but instead they are of type
<code>struct dirent **</code>.
</p>
<p>The return value of <code>alphasort</code> is less than, equal to, or greater
than zero depending on the order of the two entries <var>a</var> and <var>b</var>.
</p></dd></dl>
<dl>
<dt><a name="index-versionsort"></a><u>Function:</u> int <b>versionsort</b><i> (const void *<var>a</var>, const void *<var>b</var>)</i></dt>
<dd><p>The <code>versionsort</code> function is like <code>alphasort</code> except that it
uses the <code>strverscmp</code> function internally.
</p></dd></dl>
<p>If the filesystem supports large files we cannot use the <code>scandir</code>
anymore since the <code>dirent</code> structure might not able to contain all
the information. The LFS provides the new type <code>struct
dirent64</code>. To use this we need a new function.
</p>
<dl>
<dt><a name="index-scandir64"></a><u>Function:</u> int <b>scandir64</b><i> (const char *<var>dir</var>, struct dirent64 ***<var>namelist</var>, int (*<var>selector</var>) (const struct dirent64 *), int (*<var>cmp</var>) (const void *, const void *))</i></dt>
<dd><p>The <code>scandir64</code> function works like the <code>scandir</code> function
except that the directory entries it returns are described by elements
of type <code>struct dirent64</code>. The function pointed to by
<var>selector</var> is again used to select the desired entries, except that
<var>selector</var> now must point to a function which takes a
<code>struct dirent64 *</code> parameter.
</p>
<p>Similarly the <var>cmp</var> function should expect its two arguments to be
of type <code>struct dirent64 **</code>.
</p></dd></dl>
<p>As <var>cmp</var> is now a function of a different type, the functions
<code>alphasort</code> and <code>versionsort</code> cannot be supplied for that
argument. Instead we provide the two replacement functions below.
</p>
<dl>
<dt><a name="index-alphasort64"></a><u>Function:</u> int <b>alphasort64</b><i> (const void *<var>a</var>, const void *<var>b</var>)</i></dt>
<dd><p>The <code>alphasort64</code> function behaves like the <code>strcoll</code> function
(see section <a href="libc_5.html#String_002fArray-Comparison">String/Array Comparison</a>). The difference is that the arguments
are not string pointers but instead they are of type
<code>struct dirent64 **</code>.
</p>
<p>Return value of <code>alphasort64</code> is less than, equal to, or greater
than zero depending on the order of the two entries <var>a</var> and <var>b</var>.
</p></dd></dl>
<dl>
<dt><a name="index-versionsort64"></a><u>Function:</u> int <b>versionsort64</b><i> (const void *<var>a</var>, const void *<var>b</var>)</i></dt>
<dd><p>The <code>versionsort64</code> function is like <code>alphasort64</code>, excepted that it
uses the <code>strverscmp</code> function internally.
</p></dd></dl>
<p>It is important not to mix the use of <code>scandir</code> and the 64-bit
comparison functions or vice versa. There are systems on which this
works but on others it will fail miserably.
</p>
<hr size="6">
<a name="Simple-Directory-Lister-Mark-II"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Scanning-Directory-Content" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Working-with-Directory-Trees" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Accessing-Directories" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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-Program-to-List-a-Directory_002c-Mark-II"></a>
<h3 class="subsection">14.2.7 Simple Program to List a Directory, Mark II</h3>
<p>Here is a revised version of the directory lister found above
(see section <a href="#Simple-Directory-Lister">Simple Program to List a Directory</a>). Using the <code>scandir</code> function we
can avoid the functions which work directly with the directory contents.
After the call the returned entries are available for direct use.
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <stdio.h>
#include <dirent.h>
</pre><pre class="smallexample">
static int
one (const struct dirent *unused)
{
return 1;
}
int
main (void)
{
struct dirent **eps;
int n;
n = scandir ("./", &eps, one, alphasort);
if (n >= 0)
{
int cnt;
for (cnt = 0; cnt < n; ++cnt)
puts (eps[cnt]->d_name);
}
else
perror ("Couldn't open the directory");
return 0;
}
</pre></td></tr></table>
<p>Note the simple selector function in this example. Since we want to see
all directory entries we always return <code>1</code>.
</p>
<hr size="6">
<a name="Working-with-Directory-Trees"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Simple-Directory-Lister-Mark-II" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Hard-Links" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Working-with-Directory-Trees-1"></a>
<h2 class="section">14.3 Working with Directory Trees</h2>
<a name="index-directory-hierarchy"></a>
<a name="index-hierarchy_002c-directory"></a>
<a name="index-tree_002c-directory"></a>
<p>The functions described so far for handling the files in a directory
have allowed you to either retrieve the information bit by bit, or to
process all the files as a group (see <code>scandir</code>). Sometimes it is
useful to process whole hierarchies of directories and their contained
files. The X/Open specification defines two functions to do this. The
simpler form is derived from an early definition in System V systems
and therefore this function is available on SVID-derived systems. The
prototypes and required definitions can be found in the ‘<tt>ftw.h</tt>’
header.
</p>
<p>There are four functions in this family: <code>ftw</code>, <code>nftw</code> and
their 64-bit counterparts <code>ftw64</code> and <code>nftw64</code>. These
functions take as one of their arguments a pointer to a callback
function of the appropriate type.
</p>
<dl>
<dt><a name="index-_005f_005fftw_005ffunc_005ft"></a><u>Data Type:</u> <b>__ftw_func_t</b></dt>
<dd>
<table><tr><td> </td><td><pre class="smallexample">int (*) (const char *, const struct stat *, int)
</pre></td></tr></table>
<p>The type of callback functions given to the <code>ftw</code> function. The
first parameter points to the file name, the second parameter to an
object of type <code>struct stat</code> which is filled in for the file named
in the first parameter.
</p>
<p>The last parameter is a flag giving more information about the current
file. It can have the following values:
</p>
<dl compact="compact">
<dt> <code>FTW_F</code>
<a name="index-FTW_005fF"></a>
</dt>
<dd><p>The item is either a normal file or a file which does not fit into one
of the following categories. This could be special files, sockets etc.
</p></dd>
<dt> <code>FTW_D</code>
<a name="index-FTW_005fD"></a>
</dt>
<dd><p>The item is a directory.
</p></dd>
<dt> <code>FTW_NS</code>
<a name="index-FTW_005fNS"></a>
</dt>
<dd><p>The <code>stat</code> call failed and so the information pointed to by the
second paramater is invalid.
</p></dd>
<dt> <code>FTW_DNR</code>
<a name="index-FTW_005fDNR"></a>
</dt>
<dd><p>The item is a directory which cannot be read.
</p></dd>
<dt> <code>FTW_SL</code>
<a name="index-FTW_005fSL"></a>
</dt>
<dd><p>The item is a symbolic link. Since symbolic links are normally followed
seeing this value in a <code>ftw</code> callback function means the referenced
file does not exist. The situation for <code>nftw</code> is different.
</p>
<p>This value is only available if the program is compiled with
<code>_BSD_SOURCE</code> or <code>_XOPEN_EXTENDED</code> defined before including
the first header. The original SVID systems do not have symbolic links.
</p></dd>
</dl>
<p>If the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> this
type is in fact <code>__ftw64_func_t</code> since this mode changes
<code>struct stat</code> to be <code>struct stat64</code>.
</p></dd></dl>
<p>For the LFS interface and for use in the function <code>ftw64</code>, the
header ‘<tt>ftw.h</tt>’ defines another function type.
</p>
<dl>
<dt><a name="index-_005f_005fftw64_005ffunc_005ft"></a><u>Data Type:</u> <b>__ftw64_func_t</b></dt>
<dd>
<table><tr><td> </td><td><pre class="smallexample">int (*) (const char *, const struct stat64 *, int)
</pre></td></tr></table>
<p>This type is used just like <code>__ftw_func_t</code> for the callback
function, but this time is called from <code>ftw64</code>. The second
parameter to the function is a pointer to a variable of type
<code>struct stat64</code> which is able to represent the larger values.
</p></dd></dl>
<dl>
<dt><a name="index-_005f_005fnftw_005ffunc_005ft"></a><u>Data Type:</u> <b>__nftw_func_t</b></dt>
<dd>
<table><tr><td> </td><td><pre class="smallexample">int (*) (const char *, const struct stat *, int, struct FTW *)
</pre></td></tr></table>
<a name="index-FTW_005fDP"></a>
<a name="index-FTW_005fSLN"></a>
<p>The first three arguments are the same as for the <code>__ftw_func_t</code>
type. However for the third argument some additional values are defined
to allow finer differentiation:
</p><dl compact="compact">
<dt> <code>FTW_DP</code></dt>
<dd><p>The current item is a directory and all subdirectories have already been
visited and reported. This flag is returned instead of <code>FTW_D</code> if
the <code>FTW_DEPTH</code> flag is passed to <code>nftw</code> (see below).
</p></dd>
<dt> <code>FTW_SLN</code></dt>
<dd><p>The current item is a stale symbolic link. The file it points to does
not exist.
</p></dd>
</dl>
<p>The last parameter of the callback function is a pointer to a structure
with some extra information as described below.
</p>
<p>If the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> this
type is in fact <code>__nftw64_func_t</code> since this mode changes
<code>struct stat</code> to be <code>struct stat64</code>.
</p></dd></dl>
<p>For the LFS interface there is also a variant of this data type
available which has to be used with the <code>nftw64</code> function.
</p>
<dl>
<dt><a name="index-_005f_005fnftw64_005ffunc_005ft"></a><u>Data Type:</u> <b>__nftw64_func_t</b></dt>
<dd>
<table><tr><td> </td><td><pre class="smallexample">int (*) (const char *, const struct stat64 *, int, struct FTW *)
</pre></td></tr></table>
<p>This type is used just like <code>__nftw_func_t</code> for the callback
function, but this time is called from <code>nftw64</code>. The second
parameter to the function is this time a pointer to a variable of type
<code>struct stat64</code> which is able to represent the larger values.
</p></dd></dl>
<dl>
<dt><a name="index-struct-FTW"></a><u>Data Type:</u> <b>struct FTW</b></dt>
<dd><p>The information contained in this structure helps in interpreting the
name parameter and gives some information about the current state of the
traversal of the directory hierarchy.
</p>
<dl compact="compact">
<dt> <code>int base</code></dt>
<dd><p>The value is the offset into the string passed in the first parameter to
the callback function of the beginning of the file name. The rest of
the string is the path of the file. This information is especially
important if the <code>FTW_CHDIR</code> flag was set in calling <code>nftw</code>
since then the current directory is the one the current item is found
in.
</p></dd>
<dt> <code>int level</code></dt>
<dd><p>Whilst processing, the code tracks how many directories down it has gone
to find the current file. This nesting level starts at <em>0</em> for
files in the initial directory (or is zero for the initial file if a
file was passed).
</p></dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-ftw"></a><u>Function:</u> int <b>ftw</b><i> (const char *<var>filename</var>, __ftw_func_t <var>func</var>, int <var>descriptors</var>)</i></dt>
<dd><p>The <code>ftw</code> function calls the callback function given in the
parameter <var>func</var> for every item which is found in the directory
specified by <var>filename</var> and all directories below. The function
follows symbolic links if necessary but does not process an item twice.
If <var>filename</var> is not a directory then it itself is the only object
returned to the callback function.
</p>
<p>The file name passed to the callback function is constructed by taking
the <var>filename</var> parameter and appending the names of all passed
directories and then the local file name. So the callback function can
use this parameter to access the file. <code>ftw</code> also calls
<code>stat</code> for the file and passes that information on to the callback
function. If this <code>stat</code> call was not successful the failure is
indicated by setting the third argument of the callback function to
<code>FTW_NS</code>. Otherwise it is set according to the description given
in the account of <code>__ftw_func_t</code> above.
</p>
<p>The callback function is expected to return <em>0</em> to indicate that no
error occurred and that processing should continue. If an error
occurred in the callback function or it wants <code>ftw</code> to return
immediately, the callback function can return a value other than
<em>0</em>. This is the only correct way to stop the function. The
program must not use <code>setjmp</code> or similar techniques to continue
from another place. This would leave resources allocated by the
<code>ftw</code> function unfreed.
</p>
<p>The <var>descriptors</var> parameter to <code>ftw</code> specifies how many file
descriptors it is allowed to consume. The function runs faster the more
descriptors it can use. For each level in the directory hierarchy at
most one descriptor is used, but for very deep ones any limit on open
file descriptors for the process or the system may be exceeded.
Moreover, file descriptor limits in a multi-threaded program apply to
all the threads as a group, and therefore it is a good idea to supply a
reasonable limit to the number of open descriptors.
</p>
<p>The return value of the <code>ftw</code> function is <em>0</em> if all callback
function calls returned <em>0</em> and all actions performed by the
<code>ftw</code> succeeded. If a function call failed (other than calling
<code>stat</code> on an item) the function returns <em>-1</em>. If a callback
function returns a value other than <em>0</em> this value is returned as
the return value of <code>ftw</code>.
</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>ftw64</code>, i.e., the LFS
interface transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-ftw64"></a><u>Function:</u> int <b>ftw64</b><i> (const char *<var>filename</var>, __ftw64_func_t <var>func</var>, int <var>descriptors</var>)</i></dt>
<dd><p>This function is similar to <code>ftw</code> but it can work on filesystems
with large files. File information is reported using a variable of type
<code>struct stat64</code> which is passed by reference to the callback
function.
</p>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a
32-bit system this function is available under the name <code>ftw</code> and
transparently replaces the old implementation.
</p></dd></dl>
<dl>
<dt><a name="index-nftw"></a><u>Function:</u> int <b>nftw</b><i> (const char *<var>filename</var>, __nftw_func_t <var>func</var>, int <var>descriptors</var>, int <var>flag</var>)</i></dt>
<dd><p>The <code>nftw</code> function works like the <code>ftw</code> functions. They call
the callback function <var>func</var> for all items found in the directory
<var>filename</var> and below. At most <var>descriptors</var> file descriptors
are consumed during the <code>nftw</code> call.
</p>
<p>One difference is that the callback function is of a different type. It
is of type <code>struct FTW *</code> and provides the callback function
with the extra information described above.
</p>
<p>A second difference is that <code>nftw</code> takes a fourth argument, which
is <em>0</em> or a bitwise-OR combination of any of the following values.
</p>
<dl compact="compact">
<dt> <code>FTW_PHYS</code>
<a name="index-FTW_005fPHYS"></a>
</dt>
<dd><p>While traversing the directory symbolic links are not followed. Instead
symbolic links are reported using the <code>FTW_SL</code> value for the type
parameter to the callback function. If the file referenced by a
symbolic link does not exist <code>FTW_SLN</code> is returned instead.
</p></dd>
<dt> <code>FTW_MOUNT</code>
<a name="index-FTW_005fMOUNT"></a>
</dt>
<dd><p>The callback function is only called for items which are on the same
mounted filesystem as the directory given by the <var>filename</var>
parameter to <code>nftw</code>.
</p></dd>
<dt> <code>FTW_CHDIR</code>
<a name="index-FTW_005fCHDIR"></a>
</dt>
<dd><p>If this flag is given the current working directory is changed to the
directory of the reported object before the callback function is called.
When <code>ntfw</code> finally returns the current directory is restored to
its original value.
</p></dd>
<dt> <code>FTW_DEPTH</code>
<a name="index-FTW_005fDEPTH"></a>
</dt>
<dd><p>If this option is specified then all subdirectories and files within
them are processed before processing the top directory itself
(depth-first processing). This also means the type flag given to the
callback function is <code>FTW_DP</code> and not <code>FTW_D</code>.
</p></dd>
<dt> <code>FTW_ACTIONRETVAL</code>
<a name="index-FTW_005fACTIONRETVAL"></a>
</dt>
<dd><p>If this option is specified then return values from callbacks
are handled differently. If the callback returns <code>FTW_CONTINUE</code>,
walking continues normally. <code>FTW_STOP</code> means walking stops
and <code>FTW_STOP</code> is returned to the caller. If <code>FTW_SKIP_SUBTREE</code>
is returned by the callback with <code>FTW_D</code> argument, the subtree
is skipped and walking continues with next sibling of the directory.
If <code>FTW_SKIP_SIBLINGS</code> is returned by the callback, all siblings
of the current entry are skipped and walking continues in its parent.
No other return values should be returned from the callbacks if
this option is set. This option is a GNU extension.
</p></dd>
</dl>
<p>The return value is computed in the same way as for <code>ftw</code>.
<code>nftw</code> returns <em>0</em> if no failures occurred and all callback
functions returned <em>0</em>. In case of internal errors, such as memory
problems, the return value is <em>-1</em> and <var>errno</var> is set
accordingly. If the return value of a callback invocation was non-zero
then that value is returned.
</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>nftw64</code>, i.e., the LFS
interface transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-nftw64"></a><u>Function:</u> int <b>nftw64</b><i> (const char *<var>filename</var>, __nftw64_func_t <var>func</var>, int <var>descriptors</var>, int <var>flag</var>)</i></dt>
<dd><p>This function is similar to <code>nftw</code> but it can work on filesystems
with large files. File information is reported using a variable of type
<code>struct stat64</code> which is passed by reference to the callback
function.
</p>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> on a
32-bit system this function is available under the name <code>nftw</code> and
transparently replaces the old implementation.
</p></dd></dl>
<hr size="6">
<a name="Hard-Links"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Working-with-Directory-Trees" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Symbolic-Links" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Hard-Links-1"></a>
<h2 class="section">14.4 Hard Links</h2>
<a name="index-hard-link"></a>
<a name="index-link_002c-hard"></a>
<a name="index-multiple-names-for-one-file"></a>
<a name="index-file-names_002c-multiple"></a>
<p>In POSIX systems, one file can have many names at the same time. All of
the names are equally real, and no one of them is preferred to the
others.
</p>
<p>To add a name to a file, use the <code>link</code> function. (The new name is
also called a <em>hard link</em> to the file.) Creating a new link to a
file does not copy the contents of the file; it simply makes a new name
by which the file can be known, in addition to the file’s existing name
or names.
</p>
<p>One file can have names in several directories, so the organization
of the file system is not a strict hierarchy or tree.
</p>
<p>In most implementations, it is not possible to have hard links to the
same file in multiple file systems. <code>link</code> reports an error if you
try to make a hard link to the file from another file system when this
cannot be done.
</p>
<p>The prototype for the <code>link</code> function is declared in the header
file ‘<tt>unistd.h</tt>’.
<a name="index-unistd_002eh-5"></a>
</p>
<dl>
<dt><a name="index-link-1"></a><u>Function:</u> int <b>link</b><i> (const char *<var>oldname</var>, const char *<var>newname</var>)</i></dt>
<dd><p>The <code>link</code> function makes a new link to the existing file named by
<var>oldname</var>, under the new name <var>newname</var>.
</p>
<p>This function returns a value of <code>0</code> if it is successful and
<code>-1</code> on failure. In addition to the usual file name errors
(see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>) for both <var>oldname</var> and <var>newname</var>, the
following <code>errno</code> error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EACCES</code></dt>
<dd><p>You are not allowed to write to the directory in which the new link is
to be written.
</p>
</dd>
<dt> <code>EEXIST</code></dt>
<dd><p>There is already a file named <var>newname</var>. If you want to replace
this link with a new link, you must remove the old link explicitly first.
</p>
</dd>
<dt> <code>EMLINK</code></dt>
<dd><p>There are already too many links to the file named by <var>oldname</var>.
(The maximum number of links to a file is <code>LINK_MAX</code>; see
<a href="libc_31.html#Limits-for-Files">Limits on File System Capacity</a>.)
</p>
</dd>
<dt> <code>ENOENT</code></dt>
<dd><p>The file named by <var>oldname</var> doesn’t exist. You can’t make a link to
a file that doesn’t exist.
</p>
</dd>
<dt> <code>ENOSPC</code></dt>
<dd><p>The directory or file system that would contain the new link is full
and cannot be extended.
</p>
</dd>
<dt> <code>EPERM</code></dt>
<dd><p>In the GNU system and some others, you cannot make links to directories.
Many systems allow only privileged users to do so. This error
is used to report the problem.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The directory containing the new link can’t be modified because it’s on
a read-only file system.
</p>
</dd>
<dt> <code>EXDEV</code></dt>
<dd><p>The directory specified in <var>newname</var> is on a different file system
than the existing file.
</p>
</dd>
<dt> <code>EIO</code></dt>
<dd><p>A hardware error occurred while trying to read or write the to filesystem.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="Symbolic-Links"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Hard-Links" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Deleting-Files" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Symbolic-Links-1"></a>
<h2 class="section">14.5 Symbolic Links</h2>
<a name="index-soft-link"></a>
<a name="index-link_002c-soft"></a>
<a name="index-symbolic-link"></a>
<a name="index-link_002c-symbolic"></a>
<p>The GNU system supports <em>soft links</em> or <em>symbolic links</em>. This
is a kind of “file” that is essentially a pointer to another file
name. Unlike hard links, symbolic links can be made to directories or
across file systems with no restrictions. You can also make a symbolic
link to a name which is not the name of any file. (Opening this link
will fail until a file by that name is created.) Likewise, if the
symbolic link points to an existing file which is later deleted, the
symbolic link continues to point to the same file name even though the
name no longer names any file.
</p>
<p>The reason symbolic links work the way they do is that special things
happen when you try to open the link. The <code>open</code> function realizes
you have specified the name of a link, reads the file name contained in
the link, and opens that file name instead. The <code>stat</code> function
likewise operates on the file that the symbolic link points to, instead
of on the link itself.
</p>
<p>By contrast, other operations such as deleting or renaming the file
operate on the link itself. The functions <code>readlink</code> and
<code>lstat</code> also refrain from following symbolic links, because their
purpose is to obtain information about the link. <code>link</code>, the
function that makes a hard link, does too. It makes a hard link to the
symbolic link, which one rarely wants.
</p>
<p>Some systems have for some functions operating on files have a limit on
how many symbolic links are followed when resolving a path name. The
limit if it exists is published in the ‘<tt>sys/param.h</tt>’ header file.
</p>
<dl>
<dt><a name="index-MAXSYMLINKS"></a><u>Macro:</u> int <b>MAXSYMLINKS</b></dt>
<dd>
<p>The macro <code>MAXSYMLINKS</code> specifies how many symlinks some function
will follow before returning <code>ELOOP</code>. Not all functions behave the
same and this value is not the same a that returned for
<code>_SC_SYMLOOP</code> by <code>sysconf</code>. In fact, the <code>sysconf</code>
result can indicate that there is no fixed limit although
<code>MAXSYMLINKS</code> exists and has a finite value.
</p></dd></dl>
<p>Prototypes for most of the functions listed in this section are in
‘<tt>unistd.h</tt>’.
<a name="index-unistd_002eh-6"></a>
</p>
<dl>
<dt><a name="index-symlink"></a><u>Function:</u> int <b>symlink</b><i> (const char *<var>oldname</var>, const char *<var>newname</var>)</i></dt>
<dd><p>The <code>symlink</code> function makes a symbolic link to <var>oldname</var> named
<var>newname</var>.
</p>
<p>The normal return value from <code>symlink</code> is <code>0</code>. A return value
of <code>-1</code> indicates an error. In addition to the usual file name
syntax errors (see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), the following <code>errno</code>
error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EEXIST</code></dt>
<dd><p>There is already an existing file named <var>newname</var>.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The file <var>newname</var> would exist on a read-only file system.
</p>
</dd>
<dt> <code>ENOSPC</code></dt>
<dd><p>The directory or file system cannot be extended to make the new link.
</p>
</dd>
<dt> <code>EIO</code></dt>
<dd><p>A hardware error occurred while reading or writing data on the disk.
</p>
</dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-readlink"></a><u>Function:</u> int <b>readlink</b><i> (const char *<var>filename</var>, char *<var>buffer</var>, size_t <var>size</var>)</i></dt>
<dd><p>The <code>readlink</code> function gets the value of the symbolic link
<var>filename</var>. The file name that the link points to is copied into
<var>buffer</var>. This file name string is <em>not</em> null-terminated;
<code>readlink</code> normally returns the number of characters copied. The
<var>size</var> argument specifies the maximum number of characters to copy,
usually the allocation size of <var>buffer</var>.
</p>
<p>If the return value equals <var>size</var>, you cannot tell whether or not
there was room to return the entire name. So make a bigger buffer and
call <code>readlink</code> again. Here is an example:
</p>
<table><tr><td> </td><td><pre class="smallexample">char *
readlink_malloc (const char *filename)
{
int size = 100;
char *buffer = NULL;
while (1)
{
buffer = (char *) xrealloc (buffer, size);
int nchars = readlink (filename, buffer, size);
if (nchars < 0)
{
free (buffer);
return NULL;
}
if (nchars < size)
return buffer;
size *= 2;
}
}
</pre></td></tr></table>
<p>A value of <code>-1</code> is returned in case of error. In addition to the
usual file name errors (see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), the following
<code>errno</code> error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EINVAL</code></dt>
<dd><p>The named file is not a symbolic link.
</p>
</dd>
<dt> <code>EIO</code></dt>
<dd><p>A hardware error occurred while reading or writing data on the disk.
</p></dd>
</dl>
</dd></dl>
<p>In some situations it is desirable to resolve all the
symbolic links to get the real
name of a file where no prefix names a symbolic link which is followed
and no filename in the path is <code>.</code> or <code>..</code>. This is for
instance desirable if files have to be compare in which case different
names can refer to the same inode.
</p>
<dl>
<dt><a name="index-canonicalize_005ffile_005fname"></a><u>Function:</u> char * <b>canonicalize_file_name</b><i> (const char *<var>name</var>)</i></dt>
<dd>
<p>The <code>canonicalize_file_name</code> function returns the absolute name of
the file named by <var>name</var> which contains no <code>.</code>, <code>..</code>
components nor any repeated path separators (<code>/</code>) or symlinks. The
result is passed back as the return value of the function in a block of
memory allocated with <code>malloc</code>. If the result is not used anymore
the memory should be freed with a call to <code>free</code>.
</p>
<p>If any of the path components is missing the function returns a NULL
pointer. This is also what is returned if the length of the path
reaches or exceeds <code>PATH_MAX</code> characters. In any case
<code>errno</code> is set accordingly.
</p>
<dl compact="compact">
<dt> <code>ENAMETOOLONG</code></dt>
<dd><p>The resulting path is too long. This error only occurs on systems which
have a limit on the file name length.
</p>
</dd>
<dt> <code>EACCES</code></dt>
<dd><p>At least one of the path components is not readable.
</p>
</dd>
<dt> <code>ENOENT</code></dt>
<dd><p>The input file name is empty.
</p>
</dd>
<dt> <code>ENOENT</code></dt>
<dd><p>At least one of the path components does not exist.
</p>
</dd>
<dt> <code>ELOOP</code></dt>
<dd><p>More than <code>MAXSYMLINKS</code> many symlinks have been followed.
</p></dd>
</dl>
<p>This function is a GNU extension and is declared in ‘<tt>stdlib.h</tt>’.
</p></dd></dl>
<p>The Unix standard includes a similar function which differs from
<code>canonicalize_file_name</code> in that the user has to provide the buffer
where the result is placed in.
</p>
<dl>
<dt><a name="index-realpath"></a><u>Function:</u> char * <b>realpath</b><i> (const char *restrict <var>name</var>, char *restrict <var>resolved</var>)</i></dt>
<dd>
<p>A call to <code>realpath</code> where the <var>resolved</var> parameter is
<code>NULL</code> behaves exactly like <code>canonicalize_file_name</code>. The
function allocates a buffer for the file name and returns a pointer to
it. If <var>resolved</var> is not <code>NULL</code> it points to a buffer into
which the result is copied. It is the callers responsibility to
allocate a buffer which is large enough. On systems which define
<code>PATH_MAX</code> this means the buffer must be large enough for a
pathname of this size. For systems without limitations on the pathname
length the requirement cannot be met and programs should not call
<code>realpath</code> with anything but <code>NULL</code> for the second parameter.
</p>
<p>One other difference is that the buffer <var>resolved</var> (if nonzero) will
contain the part of the path component which does not exist or is not
readable if the function returns <code>NULL</code> and <code>errno</code> is set to
<code>EACCES</code> or <code>ENOENT</code>.
</p>
<p>This function is declared in ‘<tt>stdlib.h</tt>’.
</p></dd></dl>
<p>The advantage of using this function is that it is more widely
available. The drawback is that it reports failures for long path on
systems which have no limits on the file name length.
</p>
<hr size="6">
<a name="Deleting-Files"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Symbolic-Links" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Renaming-Files" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Deleting-Files-1"></a>
<h2 class="section">14.6 Deleting Files</h2>
<a name="index-deleting-a-file"></a>
<a name="index-removing-a-file"></a>
<a name="index-unlinking-a-file"></a>
<p>You can delete a file with <code>unlink</code> or <code>remove</code>.
</p>
<p>Deletion actually deletes a file name. If this is the file’s only name,
then the file is deleted as well. If the file has other remaining names
(see section <a href="#Hard-Links">Hard Links</a>), it remains accessible under those names.
</p>
<dl>
<dt><a name="index-unlink"></a><u>Function:</u> int <b>unlink</b><i> (const char *<var>filename</var>)</i></dt>
<dd><p>The <code>unlink</code> function deletes the file name <var>filename</var>. If
this is a file’s sole name, the file itself is also deleted. (Actually,
if any process has the file open when this happens, deletion is
postponed until all processes have closed the file.)
</p>
<a name="index-unistd_002eh-7"></a>
<p>The function <code>unlink</code> is declared in the header file ‘<tt>unistd.h</tt>’.
</p>
<p>This function returns <code>0</code> on successful completion, and <code>-1</code>
on error. In addition to the usual file name errors
(see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), the following <code>errno</code> error conditions are
defined for this function:
</p>
<dl compact="compact">
<dt> <code>EACCES</code></dt>
<dd><p>Write permission is denied for the directory from which the file is to be
removed, or the directory has the sticky bit set and you do not own the file.
</p>
</dd>
<dt> <code>EBUSY</code></dt>
<dd><p>This error indicates that the file is being used by the system in such a
way that it can’t be unlinked. For example, you might see this error if
the file name specifies the root directory or a mount point for a file
system.
</p>
</dd>
<dt> <code>ENOENT</code></dt>
<dd><p>The file name to be deleted doesn’t exist.
</p>
</dd>
<dt> <code>EPERM</code></dt>
<dd><p>On some systems <code>unlink</code> cannot be used to delete the name of a
directory, or at least can only be used this way by a privileged user.
To avoid such problems, use <code>rmdir</code> to delete directories. (In the
GNU system <code>unlink</code> can never delete the name of a directory.)
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The directory containing the file name to be deleted is on a read-only
file system and can’t be modified.
</p></dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-rmdir"></a><u>Function:</u> int <b>rmdir</b><i> (const char *<var>filename</var>)</i></dt>
<dd><a name="index-directories_002c-deleting"></a>
<a name="index-deleting-a-directory"></a>
<p>The <code>rmdir</code> function deletes a directory. The directory must be
empty before it can be removed; in other words, it can only contain
entries for ‘<tt>.</tt>’ and ‘<tt>..</tt>’.
</p>
<p>In most other respects, <code>rmdir</code> behaves like <code>unlink</code>. There
are two additional <code>errno</code> error conditions defined for
<code>rmdir</code>:
</p>
<dl compact="compact">
<dt> <code>ENOTEMPTY</code></dt>
<dt> <code>EEXIST</code></dt>
<dd><p>The directory to be deleted is not empty.
</p></dd>
</dl>
<p>These two error codes are synonymous; some systems use one, and some use
the other. The GNU system always uses <code>ENOTEMPTY</code>.
</p>
<p>The prototype for this function is declared in the header file
‘<tt>unistd.h</tt>’.
<a name="index-unistd_002eh-8"></a>
</p></dd></dl>
<dl>
<dt><a name="index-remove"></a><u>Function:</u> int <b>remove</b><i> (const char *<var>filename</var>)</i></dt>
<dd><p>This is the ISO C function to remove a file. It works like
<code>unlink</code> for files and like <code>rmdir</code> for directories.
<code>remove</code> is declared in ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-16"></a>
</p></dd></dl>
<hr size="6">
<a name="Renaming-Files"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Deleting-Files" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Creating-Directories" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Renaming-Files-1"></a>
<h2 class="section">14.7 Renaming Files</h2>
<p>The <code>rename</code> function is used to change a file’s name.
</p>
<a name="index-renaming-a-file"></a>
<dl>
<dt><a name="index-rename"></a><u>Function:</u> int <b>rename</b><i> (const char *<var>oldname</var>, const char *<var>newname</var>)</i></dt>
<dd><p>The <code>rename</code> function renames the file <var>oldname</var> to
<var>newname</var>. The file formerly accessible under the name
<var>oldname</var> is afterwards accessible as <var>newname</var> instead. (If
the file had any other names aside from <var>oldname</var>, it continues to
have those names.)
</p>
<p>The directory containing the name <var>newname</var> must be on the same file
system as the directory containing the name <var>oldname</var>.
</p>
<p>One special case for <code>rename</code> is when <var>oldname</var> and
<var>newname</var> are two names for the same file. The consistent way to
handle this case is to delete <var>oldname</var>. However, in this case
POSIX requires that <code>rename</code> do nothing and report success—which
is inconsistent. We don’t know what your operating system will do.
</p>
<p>If <var>oldname</var> is not a directory, then any existing file named
<var>newname</var> is removed during the renaming operation. However, if
<var>newname</var> is the name of a directory, <code>rename</code> fails in this
case.
</p>
<p>If <var>oldname</var> is a directory, then either <var>newname</var> must not
exist or it must name a directory that is empty. In the latter case,
the existing directory named <var>newname</var> is deleted first. The name
<var>newname</var> must not specify a subdirectory of the directory
<code>oldname</code> which is being renamed.
</p>
<p>One useful feature of <code>rename</code> is that the meaning of <var>newname</var>
changes “atomically” from any previously existing file by that name to
its new meaning (i.e., the file that was called <var>oldname</var>). There is
no instant at which <var>newname</var> is non-existent “in between” the old
meaning and the new meaning. If there is a system crash during the
operation, it is possible for both names to still exist; but
<var>newname</var> will always be intact if it exists at all.
</p>
<p>If <code>rename</code> fails, it returns <code>-1</code>. In addition to the usual
file name errors (see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), the following
<code>errno</code> error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EACCES</code></dt>
<dd><p>One of the directories containing <var>newname</var> or <var>oldname</var>
refuses write permission; or <var>newname</var> and <var>oldname</var> are
directories and write permission is refused for one of them.
</p>
</dd>
<dt> <code>EBUSY</code></dt>
<dd><p>A directory named by <var>oldname</var> or <var>newname</var> is being used by
the system in a way that prevents the renaming from working. This includes
directories that are mount points for filesystems, and directories
that are the current working directories of processes.
</p>
</dd>
<dt> <code>ENOTEMPTY</code></dt>
<dt> <code>EEXIST</code></dt>
<dd><p>The directory <var>newname</var> isn’t empty. The GNU system always returns
<code>ENOTEMPTY</code> for this, but some other systems return <code>EEXIST</code>.
</p>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p><var>oldname</var> is a directory that contains <var>newname</var>.
</p>
</dd>
<dt> <code>EISDIR</code></dt>
<dd><p><var>newname</var> is a directory but the <var>oldname</var> isn’t.
</p>
</dd>
<dt> <code>EMLINK</code></dt>
<dd><p>The parent directory of <var>newname</var> would have too many links
(entries).
</p>
</dd>
<dt> <code>ENOENT</code></dt>
<dd><p>The file <var>oldname</var> doesn’t exist.
</p>
</dd>
<dt> <code>ENOSPC</code></dt>
<dd><p>The directory that would contain <var>newname</var> has no room for another
entry, and there is no space left in the file system to expand it.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The operation would involve writing to a directory on a read-only file
system.
</p>
</dd>
<dt> <code>EXDEV</code></dt>
<dd><p>The two file names <var>newname</var> and <var>oldname</var> are on different
file systems.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="Creating-Directories"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Renaming-Files" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Creating-Directories-1"></a>
<h2 class="section">14.8 Creating Directories</h2>
<a name="index-creating-a-directory"></a>
<a name="index-directories_002c-creating"></a>
<a name="index-mkdir"></a>
<p>Directories are created with the <code>mkdir</code> function. (There is also
a shell command <code>mkdir</code> which does the same thing.)
</p>
<dl>
<dt><a name="index-mkdir-1"></a><u>Function:</u> int <b>mkdir</b><i> (const char *<var>filename</var>, mode_t <var>mode</var>)</i></dt>
<dd><p>The <code>mkdir</code> function creates a new, empty directory with name
<var>filename</var>.
</p>
<p>The argument <var>mode</var> specifies the file permissions for the new
directory file. See section <a href="#Permission-Bits">The Mode Bits for Access Permission</a>, for more information about
this.
</p>
<p>A return value of <code>0</code> indicates successful completion, and
<code>-1</code> indicates failure. In addition to the usual file name syntax
errors (see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), the following <code>errno</code> error
conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EACCES</code></dt>
<dd><p>Write permission is denied for the parent directory in which the new
directory is to be added.
</p>
</dd>
<dt> <code>EEXIST</code></dt>
<dd><p>A file named <var>filename</var> already exists.
</p>
</dd>
<dt> <code>EMLINK</code></dt>
<dd><p>The parent directory has too many links (entries).
</p>
<p>Well-designed file systems never report this error, because they permit
more links than your disk could possibly hold. However, you must still
take account of the possibility of this error, as it could result from
network access to a file system on another machine.
</p>
</dd>
<dt> <code>ENOSPC</code></dt>
<dd><p>The file system doesn’t have enough room to create the new directory.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The parent directory of the directory being created is on a read-only
file system and cannot be modified.
</p></dd>
</dl>
<p>To use this function, your program should include the header file
‘<tt>sys/stat.h</tt>’.
<a name="index-sys_002fstat_002eh-1"></a>
</p></dd></dl>
<hr size="6">
<a name="File-Attributes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Creating-Directories" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Attribute-Meanings" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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-Attributes-1"></a>
<h2 class="section">14.9 File Attributes</h2>
<a name="index-ls"></a>
<p>When you issue an ‘<samp>ls -l</samp>’ shell command on a file, it gives you
information about the size of the file, who owns it, when it was last
modified, etc. These are called the <em>file attributes</em>, and are
associated with the file itself and not a particular one of its names.
</p>
<p>This section contains information about how you can inquire about and
modify the attributes of a file.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Attribute-Meanings">14.9.1 The meaning of the File Attributes</a></td><td> </td><td align="left" valign="top"> The names of the file attributes,
and what their values mean.
</td></tr>
<tr><td align="left" valign="top"><a href="#Reading-Attributes">14.9.2 Reading the Attributes of a File</a></td><td> </td><td align="left" valign="top"> How to read the attributes of a file.
</td></tr>
<tr><td align="left" valign="top"><a href="#Testing-File-Type">14.9.3 Testing the Type of a File</a></td><td> </td><td align="left" valign="top"> Distinguishing ordinary files,
directories, links…
</td></tr>
<tr><td align="left" valign="top"><a href="#File-Owner">14.9.4 File Owner</a></td><td> </td><td align="left" valign="top"> How ownership for new files is determined,
and how to change it.
</td></tr>
<tr><td align="left" valign="top"><a href="#Permission-Bits">14.9.5 The Mode Bits for Access Permission</a></td><td> </td><td align="left" valign="top"> How information about a file’s access
mode is stored.
</td></tr>
<tr><td align="left" valign="top"><a href="#Access-Permission">14.9.6 How Your Access to a File is Decided</a></td><td> </td><td align="left" valign="top"> How the system decides who can access a file.
</td></tr>
<tr><td align="left" valign="top"><a href="#Setting-Permissions">14.9.7 Assigning File Permissions</a></td><td> </td><td align="left" valign="top"> How permissions for new files are assigned,
and how to change them.
</td></tr>
<tr><td align="left" valign="top"><a href="#Testing-File-Access">14.9.8 Testing Permission to Access a File</a></td><td> </td><td align="left" valign="top"> How to find out if your process can
access a file.
</td></tr>
<tr><td align="left" valign="top"><a href="#File-Times">14.9.9 File Times</a></td><td> </td><td align="left" valign="top"> About the time attributes of a file.
</td></tr>
<tr><td align="left" valign="top"><a href="#File-Size">14.9.10 File Size</a></td><td> </td><td align="left" valign="top"> Manually changing the size of a file.
</td></tr>
</table>
<hr size="6">
<a name="Attribute-Meanings"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#File-Attributes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Reading-Attributes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="The-meaning-of-the-File-Attributes"></a>
<h3 class="subsection">14.9.1 The meaning of the File Attributes</h3>
<a name="index-status-of-a-file"></a>
<a name="index-attributes-of-a-file"></a>
<a name="index-file-attributes"></a>
<p>When you read the attributes of a file, they come back in a structure
called <code>struct stat</code>. This section describes the names of the
attributes, their data types, and what they mean. For the functions
to read the attributes of a file, see <a href="#Reading-Attributes">Reading the Attributes of a File</a>.
</p>
<p>The header file ‘<tt>sys/stat.h</tt>’ declares all the symbols defined
in this section.
<a name="index-sys_002fstat_002eh-2"></a>
</p>
<dl>
<dt><a name="index-struct-stat"></a><u>Data Type:</u> <b>struct stat</b></dt>
<dd><p>The <code>stat</code> structure type is used to return information about the
attributes of a file. It contains at least the following members:
</p>
<dl compact="compact">
<dt> <code>mode_t st_mode</code></dt>
<dd><p>Specifies the mode of the file. This includes file type information
(see section <a href="#Testing-File-Type">Testing the Type of a File</a>) and the file permission bits
(see section <a href="#Permission-Bits">The Mode Bits for Access Permission</a>).
</p>
</dd>
<dt> <code>ino_t st_ino</code></dt>
<dd><p>The file serial number, which distinguishes this file from all other
files on the same device.
</p>
</dd>
<dt> <code>dev_t st_dev</code></dt>
<dd><p>Identifies the device containing the file. The <code>st_ino</code> and
<code>st_dev</code>, taken together, uniquely identify the file. The
<code>st_dev</code> value is not necessarily consistent across reboots or
system crashes, however.
</p>
</dd>
<dt> <code>nlink_t st_nlink</code></dt>
<dd><p>The number of hard links to the file. This count keeps track of how
many directories have entries for this file. If the count is ever
decremented to zero, then the file itself is discarded as soon as no
process still holds it open. Symbolic links are not counted in the
total.
</p>
</dd>
<dt> <code>uid_t st_uid</code></dt>
<dd><p>The user ID of the file’s owner. See section <a href="#File-Owner">File Owner</a>.
</p>
</dd>
<dt> <code>gid_t st_gid</code></dt>
<dd><p>The group ID of the file. See section <a href="#File-Owner">File Owner</a>.
</p>
</dd>
<dt> <code>off_t st_size</code></dt>
<dd><p>This specifies the size of a regular file in bytes. For files that are
really devices this field isn’t usually meaningful. For symbolic links
this specifies the length of the file name the link refers to.
</p>
</dd>
<dt> <code>time_t st_atime</code></dt>
<dd><p>This is the last access time for the file. See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>unsigned long int st_atime_usec</code></dt>
<dd><p>This is the fractional part of the last access time for the file.
See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>time_t st_mtime</code></dt>
<dd><p>This is the time of the last modification to the contents of the file.
See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>unsigned long int st_mtime_usec</code></dt>
<dd><p>This is the fractional part of the time of the last modification to the
contents of the file. See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>time_t st_ctime</code></dt>
<dd><p>This is the time of the last modification to the attributes of the file.
See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>unsigned long int st_ctime_usec</code></dt>
<dd><p>This is the fractional part of the time of the last modification to the
attributes of the file. See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>blkcnt_t st_blocks</code></dt>
<dd><p>This is the amount of disk space that the file occupies, measured in
units of 512-byte blocks.
</p>
<p>The number of disk blocks is not strictly proportional to the size of
the file, for two reasons: the file system may use some blocks for
internal record keeping; and the file may be sparse—it may have
“holes” which contain zeros but do not actually take up space on the
disk.
</p>
<p>You can tell (approximately) whether a file is sparse by comparing this
value with <code>st_size</code>, like this:
</p>
<table><tr><td> </td><td><pre class="smallexample">(st.st_blocks * 512 < st.st_size)
</pre></td></tr></table>
<p>This test is not perfect because a file that is just slightly sparse
might not be detected as sparse at all. For practical applications,
this is not a problem.
</p>
</dd>
<dt> <code>unsigned int st_blksize</code></dt>
<dd><p>The optimal block size for reading of writing this file, in bytes. You
might use this size for allocating the buffer space for reading of
writing the file. (This is unrelated to <code>st_blocks</code>.)
</p></dd>
</dl>
</dd></dl>
<p>The extensions for the Large File Support (LFS) require, even on 32-bit
machines, types which can handle file sizes up to <em>2^63</em>.
Therefore a new definition of <code>struct stat</code> is necessary.
</p>
<dl>
<dt><a name="index-struct-stat64"></a><u>Data Type:</u> <b>struct stat64</b></dt>
<dd><p>The members of this type are the same and have the same names as those
in <code>struct stat</code>. The only difference is that the members
<code>st_ino</code>, <code>st_size</code>, and <code>st_blocks</code> have a different
type to support larger values.
</p>
<dl compact="compact">
<dt> <code>mode_t st_mode</code></dt>
<dd><p>Specifies the mode of the file. This includes file type information
(see section <a href="#Testing-File-Type">Testing the Type of a File</a>) and the file permission bits
(see section <a href="#Permission-Bits">The Mode Bits for Access Permission</a>).
</p>
</dd>
<dt> <code>ino64_t st_ino</code></dt>
<dd><p>The file serial number, which distinguishes this file from all other
files on the same device.
</p>
</dd>
<dt> <code>dev_t st_dev</code></dt>
<dd><p>Identifies the device containing the file. The <code>st_ino</code> and
<code>st_dev</code>, taken together, uniquely identify the file. The
<code>st_dev</code> value is not necessarily consistent across reboots or
system crashes, however.
</p>
</dd>
<dt> <code>nlink_t st_nlink</code></dt>
<dd><p>The number of hard links to the file. This count keeps track of how
many directories have entries for this file. If the count is ever
decremented to zero, then the file itself is discarded as soon as no
process still holds it open. Symbolic links are not counted in the
total.
</p>
</dd>
<dt> <code>uid_t st_uid</code></dt>
<dd><p>The user ID of the file’s owner. See section <a href="#File-Owner">File Owner</a>.
</p>
</dd>
<dt> <code>gid_t st_gid</code></dt>
<dd><p>The group ID of the file. See section <a href="#File-Owner">File Owner</a>.
</p>
</dd>
<dt> <code>off64_t st_size</code></dt>
<dd><p>This specifies the size of a regular file in bytes. For files that are
really devices this field isn’t usually meaningful. For symbolic links
this specifies the length of the file name the link refers to.
</p>
</dd>
<dt> <code>time_t st_atime</code></dt>
<dd><p>This is the last access time for the file. See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>unsigned long int st_atime_usec</code></dt>
<dd><p>This is the fractional part of the last access time for the file.
See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>time_t st_mtime</code></dt>
<dd><p>This is the time of the last modification to the contents of the file.
See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>unsigned long int st_mtime_usec</code></dt>
<dd><p>This is the fractional part of the time of the last modification to the
contents of the file. See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>time_t st_ctime</code></dt>
<dd><p>This is the time of the last modification to the attributes of the file.
See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>unsigned long int st_ctime_usec</code></dt>
<dd><p>This is the fractional part of the time of the last modification to the
attributes of the file. See section <a href="#File-Times">File Times</a>.
</p>
</dd>
<dt> <code>blkcnt64_t st_blocks</code></dt>
<dd><p>This is the amount of disk space that the file occupies, measured in
units of 512-byte blocks.
</p>
</dd>
<dt> <code>unsigned int st_blksize</code></dt>
<dd><p>The optimal block size for reading of writing this file, in bytes. You
might use this size for allocating the buffer space for reading of
writing the file. (This is unrelated to <code>st_blocks</code>.)
</p></dd>
</dl>
</dd></dl>
<p>Some of the file attributes have special data type names which exist
specifically for those attributes. (They are all aliases for well-known
integer types that you know and love.) These typedef names are defined
in the header file ‘<tt>sys/types.h</tt>’ as well as in ‘<tt>sys/stat.h</tt>’.
Here is a list of them.
</p>
<dl>
<dt><a name="index-mode_005ft"></a><u>Data Type:</u> <b>mode_t</b></dt>
<dd><p>This is an integer data type used to represent file modes. In the
GNU system, this is equivalent to <code>unsigned int</code>.
</p></dd></dl>
<a name="index-inode-number"></a>
<dl>
<dt><a name="index-ino_005ft"></a><u>Data Type:</u> <b>ino_t</b></dt>
<dd><p>This is an arithmetic data type used to represent file serial numbers.
(In Unix jargon, these are sometimes called <em>inode numbers</em>.)
In the GNU system, this type is equivalent to <code>unsigned long int</code>.
</p>
<p>If the source is compiled with <code>_FILE_OFFSET_BITS == 64</code> this type
is transparently replaced by <code>ino64_t</code>.
</p></dd></dl>
<dl>
<dt><a name="index-ino64_005ft"></a><u>Data Type:</u> <b>ino64_t</b></dt>
<dd><p>This is an arithmetic data type used to represent file serial numbers
for the use in LFS. In the GNU system, this type is equivalent to
<code>unsigned long long int</code>.
</p>
<p>When compiling with <code>_FILE_OFFSET_BITS == 64</code> this type is
available under the name <code>ino_t</code>.
</p></dd></dl>
<dl>
<dt><a name="index-dev_005ft"></a><u>Data Type:</u> <b>dev_t</b></dt>
<dd><p>This is an arithmetic data type used to represent file device numbers.
In the GNU system, this is equivalent to <code>int</code>.
</p></dd></dl>
<dl>
<dt><a name="index-nlink_005ft"></a><u>Data Type:</u> <b>nlink_t</b></dt>
<dd><p>This is an arithmetic data type used to represent file link counts.
In the GNU system, this is equivalent to <code>unsigned short int</code>.
</p></dd></dl>
<dl>
<dt><a name="index-blkcnt_005ft"></a><u>Data Type:</u> <b>blkcnt_t</b></dt>
<dd><p>This is an arithmetic data type used to represent block counts.
In the GNU system, this is equivalent to <code>unsigned long int</code>.
</p>
<p>If the source is compiled with <code>_FILE_OFFSET_BITS == 64</code> this type
is transparently replaced by <code>blkcnt64_t</code>.
</p></dd></dl>
<dl>
<dt><a name="index-blkcnt64_005ft"></a><u>Data Type:</u> <b>blkcnt64_t</b></dt>
<dd><p>This is an arithmetic data type used to represent block counts for the
use in LFS. In the GNU system, this is equivalent to <code>unsigned
long long int</code>.
</p>
<p>When compiling with <code>_FILE_OFFSET_BITS == 64</code> this type is
available under the name <code>blkcnt_t</code>.
</p></dd></dl>
<hr size="6">
<a name="Reading-Attributes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Attribute-Meanings" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Testing-File-Type" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Reading-the-Attributes-of-a-File"></a>
<h3 class="subsection">14.9.2 Reading the Attributes of a File</h3>
<p>To examine the attributes of files, use the functions <code>stat</code>,
<code>fstat</code> and <code>lstat</code>. They return the attribute information in
a <code>struct stat</code> object. All three functions are declared in the
header file ‘<tt>sys/stat.h</tt>’.
</p>
<dl>
<dt><a name="index-stat"></a><u>Function:</u> int <b>stat</b><i> (const char *<var>filename</var>, struct stat *<var>buf</var>)</i></dt>
<dd><p>The <code>stat</code> function returns information about the attributes of the
file named by <var>filename</var> in the structure pointed to by <var>buf</var>.
</p>
<p>If <var>filename</var> is the name of a symbolic link, the attributes you get
describe the file that the link points to. If the link points to a
nonexistent file name, then <code>stat</code> fails reporting a nonexistent
file.
</p>
<p>The return value is <code>0</code> if the operation is successful, or
<code>-1</code> on failure. In addition to the usual file name errors
(see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>, the following <code>errno</code> error conditions
are defined for this function:
</p>
<dl compact="compact">
<dt> <code>ENOENT</code></dt>
<dd><p>The file named by <var>filename</var> doesn’t exist.
</p></dd>
</dl>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> this
function is in fact <code>stat64</code> since the LFS interface transparently
replaces the normal implementation.
</p></dd></dl>
<dl>
<dt><a name="index-stat64"></a><u>Function:</u> int <b>stat64</b><i> (const char *<var>filename</var>, struct stat64 *<var>buf</var>)</i></dt>
<dd><p>This function is similar to <code>stat</code> but it is also able to work on
files larger then <em>2^31</em> bytes on 32-bit systems. To be able to do
this the result is stored in a variable of type <code>struct stat64</code> to
which <var>buf</var> must point.
</p>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> this
function is available under the name <code>stat</code> and so transparently
replaces the interface for small files on 32-bit machines.
</p></dd></dl>
<dl>
<dt><a name="index-fstat"></a><u>Function:</u> int <b>fstat</b><i> (int <var>filedes</var>, struct stat *<var>buf</var>)</i></dt>
<dd><p>The <code>fstat</code> function is like <code>stat</code>, except that it takes an
open file descriptor as an argument instead of a file name.
See section <a href="libc_13.html#Low_002dLevel-I_002fO">Low-Level Input/Output</a>.
</p>
<p>Like <code>stat</code>, <code>fstat</code> returns <code>0</code> on success and <code>-1</code>
on failure. The following <code>errno</code> error conditions are defined for
<code>fstat</code>:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> argument is not a valid file descriptor.
</p></dd>
</dl>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> this
function is in fact <code>fstat64</code> since the LFS interface transparently
replaces the normal implementation.
</p></dd></dl>
<dl>
<dt><a name="index-fstat64"></a><u>Function:</u> int <b>fstat64</b><i> (int <var>filedes</var>, struct stat64 *<var>buf</var>)</i></dt>
<dd><p>This function is similar to <code>fstat</code> but is able to work on large
files on 32-bit platforms. For large files the file descriptor
<var>filedes</var> should be obtained by <code>open64</code> or <code>creat64</code>.
The <var>buf</var> pointer points to a variable of type <code>struct stat64</code>
which is able to represent the larger values.
</p>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> this
function is available under the name <code>fstat</code> and so transparently
replaces the interface for small files on 32-bit machines.
</p></dd></dl>
<dl>
<dt><a name="index-lstat"></a><u>Function:</u> int <b>lstat</b><i> (const char *<var>filename</var>, struct stat *<var>buf</var>)</i></dt>
<dd><p>The <code>lstat</code> function is like <code>stat</code>, except that it does not
follow symbolic links. If <var>filename</var> is the name of a symbolic
link, <code>lstat</code> returns information about the link itself; otherwise
<code>lstat</code> works like <code>stat</code>. See section <a href="#Symbolic-Links">Symbolic Links</a>.
</p>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> this
function is in fact <code>lstat64</code> since the LFS interface transparently
replaces the normal implementation.
</p></dd></dl>
<dl>
<dt><a name="index-lstat64"></a><u>Function:</u> int <b>lstat64</b><i> (const char *<var>filename</var>, struct stat64 *<var>buf</var>)</i></dt>
<dd><p>This function is similar to <code>lstat</code> but it is also able to work on
files larger then <em>2^31</em> bytes on 32-bit systems. To be able to do
this the result is stored in a variable of type <code>struct stat64</code> to
which <var>buf</var> must point.
</p>
<p>When the sources are compiled with <code>_FILE_OFFSET_BITS == 64</code> this
function is available under the name <code>lstat</code> and so transparently
replaces the interface for small files on 32-bit machines.
</p></dd></dl>
<hr size="6">
<a name="Testing-File-Type"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Reading-Attributes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#File-Owner" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Testing-the-Type-of-a-File"></a>
<h3 class="subsection">14.9.3 Testing the Type of a File</h3>
<p>The <em>file mode</em>, stored in the <code>st_mode</code> field of the file
attributes, contains two kinds of information: the file type code, and
the access permission bits. This section discusses only the type code,
which you can use to tell whether the file is a directory, socket,
symbolic link, and so on. For details about access permissions see
<a href="#Permission-Bits">The Mode Bits for Access Permission</a>.
</p>
<p>There are two ways you can access the file type information in a file
mode. Firstly, for each file type there is a <em>predicate macro</em>
which examines a given file mode and returns whether it is of that type
or not. Secondly, you can mask out the rest of the file mode to leave
just the file type code, and compare this against constants for each of
the supported file types.
</p>
<p>All of the symbols listed in this section are defined in the header file
‘<tt>sys/stat.h</tt>’.
<a name="index-sys_002fstat_002eh-3"></a>
</p>
<p>The following predicate macros test the type of a file, given the value
<var>m</var> which is the <code>st_mode</code> field returned by <code>stat</code> on
that file:
</p>
<dl>
<dt><a name="index-S_005fISDIR"></a><u>Macro:</u> int <b>S_ISDIR</b><i> (mode_t <var>m</var>)</i></dt>
<dd><p>This macro returns non-zero if the file is a directory.
</p></dd></dl>
<dl>
<dt><a name="index-S_005fISCHR"></a><u>Macro:</u> int <b>S_ISCHR</b><i> (mode_t <var>m</var>)</i></dt>
<dd><p>This macro returns non-zero if the file is a character special file (a
device like a terminal).
</p></dd></dl>
<dl>
<dt><a name="index-S_005fISBLK"></a><u>Macro:</u> int <b>S_ISBLK</b><i> (mode_t <var>m</var>)</i></dt>
<dd><p>This macro returns non-zero if the file is a block special file (a device
like a disk).
</p></dd></dl>
<dl>
<dt><a name="index-S_005fISREG"></a><u>Macro:</u> int <b>S_ISREG</b><i> (mode_t <var>m</var>)</i></dt>
<dd><p>This macro returns non-zero if the file is a regular file.
</p></dd></dl>
<dl>
<dt><a name="index-S_005fISFIFO"></a><u>Macro:</u> int <b>S_ISFIFO</b><i> (mode_t <var>m</var>)</i></dt>
<dd><p>This macro returns non-zero if the file is a FIFO special file, or a
pipe. See section <a href="libc_15.html#Pipes-and-FIFOs">Pipes and FIFOs</a>.
</p></dd></dl>
<dl>
<dt><a name="index-S_005fISLNK"></a><u>Macro:</u> int <b>S_ISLNK</b><i> (mode_t <var>m</var>)</i></dt>
<dd><p>This macro returns non-zero if the file is a symbolic link.
See section <a href="#Symbolic-Links">Symbolic Links</a>.
</p></dd></dl>
<dl>
<dt><a name="index-S_005fISSOCK"></a><u>Macro:</u> int <b>S_ISSOCK</b><i> (mode_t <var>m</var>)</i></dt>
<dd><p>This macro returns non-zero if the file is a socket. See section <a href="libc_16.html#Sockets">Sockets</a>.
</p></dd></dl>
<p>An alternate non-POSIX method of testing the file type is supported for
compatibility with BSD. The mode can be bitwise AND-ed with
<code>S_IFMT</code> to extract the file type code, and compared to the
appropriate constant. For example,
</p>
<table><tr><td> </td><td><pre class="smallexample">S_ISCHR (<var>mode</var>)
</pre></td></tr></table>
<p>is equivalent to:
</p>
<table><tr><td> </td><td><pre class="smallexample">((<var>mode</var> & S_IFMT) == S_IFCHR)
</pre></td></tr></table>
<dl>
<dt><a name="index-S_005fIFMT"></a><u>Macro:</u> int <b>S_IFMT</b></dt>
<dd><p>This is a bit mask used to extract the file type code from a mode value.
</p></dd></dl>
<p>These are the symbolic names for the different file type codes:
</p>
<dl compact="compact">
<dt> <code>S_IFDIR</code></dt>
<dd><a name="index-S_005fIFDIR"></a>
<p>This is the file type constant of a directory file.
</p>
</dd>
<dt> <code>S_IFCHR</code></dt>
<dd><a name="index-S_005fIFCHR"></a>
<p>This is the file type constant of a character-oriented device file.
</p>
</dd>
<dt> <code>S_IFBLK</code></dt>
<dd><a name="index-S_005fIFBLK"></a>
<p>This is the file type constant of a block-oriented device file.
</p>
</dd>
<dt> <code>S_IFREG</code></dt>
<dd><a name="index-S_005fIFREG"></a>
<p>This is the file type constant of a regular file.
</p>
</dd>
<dt> <code>S_IFLNK</code></dt>
<dd><a name="index-S_005fIFLNK"></a>
<p>This is the file type constant of a symbolic link.
</p>
</dd>
<dt> <code>S_IFSOCK</code></dt>
<dd><a name="index-S_005fIFSOCK"></a>
<p>This is the file type constant of a socket.
</p>
</dd>
<dt> <code>S_IFIFO</code></dt>
<dd><a name="index-S_005fIFIFO"></a>
<p>This is the file type constant of a FIFO or pipe.
</p></dd>
</dl>
<p>The POSIX.1b standard introduced a few more objects which possibly can
be implemented as object in the filesystem. These are message queues,
semaphores, and shared memory objects. To allow differentiating these
objects from other files the POSIX standard introduces three new test
macros. But unlike the other macros it does not take the value of the
<code>st_mode</code> field as the parameter. Instead they expect a pointer to
the whole <code>struct stat</code> structure.
</p>
<dl>
<dt><a name="index-S_005fTYPEISMQ"></a><u>Macro:</u> int <b>S_TYPEISMQ</b><i> (struct stat *<var>s</var>)</i></dt>
<dd><p>If the system implement POSIX message queues as distinct objects and the
file is a message queue object, this macro returns a non-zero value.
In all other cases the result is zero.
</p></dd></dl>
<dl>
<dt><a name="index-S_005fTYPEISSEM"></a><u>Macro:</u> int <b>S_TYPEISSEM</b><i> (struct stat *<var>s</var>)</i></dt>
<dd><p>If the system implement POSIX semaphores as distinct objects and the
file is a semaphore object, this macro returns a non-zero value.
In all other cases the result is zero.
</p></dd></dl>
<dl>
<dt><a name="index-S_005fTYPEISSHM"></a><u>Macro:</u> int <b>S_TYPEISSHM</b><i> (struct stat *<var>s</var>)</i></dt>
<dd><p>If the system implement POSIX shared memory objects as distinct objects
and the file is an shared memory object, this macro returns a non-zero
value. In all other cases the result is zero.
</p></dd></dl>
<hr size="6">
<a name="File-Owner"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Testing-File-Type" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Permission-Bits" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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-Owner-1"></a>
<h3 class="subsection">14.9.4 File Owner</h3>
<a name="index-file-owner"></a>
<a name="index-owner-of-a-file"></a>
<a name="index-group-owner-of-a-file"></a>
<p>Every file has an <em>owner</em> which is one of the registered user names
defined on the system. Each file also has a <em>group</em> which is one of
the defined groups. The file owner can often be useful for showing you
who edited the file (especially when you edit with GNU Emacs), but its
main purpose is for access control.
</p>
<p>The file owner and group play a role in determining access because the
file has one set of access permission bits for the owner, another set
that applies to users who belong to the file’s group, and a third set of
bits that applies to everyone else. See section <a href="#Access-Permission">How Your Access to a File is Decided</a>, for the
details of how access is decided based on this data.
</p>
<p>When a file is created, its owner is set to the effective user ID of the
process that creates it (see section <a href="libc_29.html#Process-Persona">The Persona of a Process</a>). The file’s group ID
may be set to either the effective group ID of the process, or the group
ID of the directory that contains the file, depending on the system
where the file is stored. When you access a remote file system, it
behaves according to its own rules, not according to the system your
program is running on. Thus, your program must be prepared to encounter
either kind of behavior no matter what kind of system you run it on.
</p>
<a name="index-chown"></a>
<a name="index-chgrp"></a>
<p>You can change the owner and/or group owner of an existing file using
the <code>chown</code> function. This is the primitive for the <code>chown</code>
and <code>chgrp</code> shell commands.
</p>
<a name="index-unistd_002eh-9"></a>
<p>The prototype for this function is declared in ‘<tt>unistd.h</tt>’.
</p>
<dl>
<dt><a name="index-chown-1"></a><u>Function:</u> int <b>chown</b><i> (const char *<var>filename</var>, uid_t <var>owner</var>, gid_t <var>group</var>)</i></dt>
<dd><p>The <code>chown</code> function changes the owner of the file <var>filename</var> to
<var>owner</var>, and its group owner to <var>group</var>.
</p>
<p>Changing the owner of the file on certain systems clears the set-user-ID
and set-group-ID permission bits. (This is because those bits may not
be appropriate for the new owner.) Other file permission bits are not
changed.
</p>
<p>The return value is <code>0</code> on success and <code>-1</code> on failure.
In addition to the usual file name errors (see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>),
the following <code>errno</code> error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EPERM</code></dt>
<dd><p>This process lacks permission to make the requested change.
</p>
<p>Only privileged users or the file’s owner can change the file’s group.
On most file systems, only privileged users can change the file owner;
some file systems allow you to change the owner if you are currently the
owner. When you access a remote file system, the behavior you encounter
is determined by the system that actually holds the file, not by the
system your program is running on.
</p>
<p>See section <a href="libc_31.html#Options-for-Files">Optional Features in File Support</a>, for information about the
<code>_POSIX_CHOWN_RESTRICTED</code> macro.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The file is on a read-only file system.
</p></dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-fchown"></a><u>Function:</u> int <b>fchown</b><i> (int <var>filedes</var>, int <var>owner</var>, int <var>group</var>)</i></dt>
<dd><p>This is like <code>chown</code>, except that it changes the owner of the open
file with descriptor <var>filedes</var>.
</p>
<p>The return value from <code>fchown</code> is <code>0</code> on success and <code>-1</code>
on failure. The following <code>errno</code> error codes are defined for this
function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> argument is not a valid file descriptor.
</p>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p>The <var>filedes</var> argument corresponds to a pipe or socket, not an ordinary
file.
</p>
</dd>
<dt> <code>EPERM</code></dt>
<dd><p>This process lacks permission to make the requested change. For details
see <code>chmod</code> above.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The file resides on a read-only file system.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="Permission-Bits"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#File-Owner" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Access-Permission" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="The-Mode-Bits-for-Access-Permission"></a>
<h3 class="subsection">14.9.5 The Mode Bits for Access Permission</h3>
<p>The <em>file mode</em>, stored in the <code>st_mode</code> field of the file
attributes, contains two kinds of information: the file type code, and
the access permission bits. This section discusses only the access
permission bits, which control who can read or write the file.
See section <a href="#Testing-File-Type">Testing the Type of a File</a>, for information about the file type code.
</p>
<p>All of the symbols listed in this section are defined in the header file
‘<tt>sys/stat.h</tt>’.
<a name="index-sys_002fstat_002eh-4"></a>
</p>
<a name="index-file-permission-bits"></a>
<p>These symbolic constants are defined for the file mode bits that control
access permission for the file:
</p>
<dl compact="compact">
<dt> <code>S_IRUSR</code></dt>
<dd><a name="index-S_005fIRUSR"></a>
</dd>
<dt> <code>S_IREAD</code></dt>
<dd><a name="index-S_005fIREAD"></a>
<p>Read permission bit for the owner of the file. On many systems this bit
is 0400. <code>S_IREAD</code> is an obsolete synonym provided for BSD
compatibility.
</p>
</dd>
<dt> <code>S_IWUSR</code></dt>
<dd><a name="index-S_005fIWUSR"></a>
</dd>
<dt> <code>S_IWRITE</code></dt>
<dd><a name="index-S_005fIWRITE"></a>
<p>Write permission bit for the owner of the file. Usually 0200.
<code>S_IWRITE</code> is an obsolete synonym provided for BSD compatibility.
</p>
</dd>
<dt> <code>S_IXUSR</code></dt>
<dd><a name="index-S_005fIXUSR"></a>
</dd>
<dt> <code>S_IEXEC</code></dt>
<dd><a name="index-S_005fIEXEC"></a>
<p>Execute (for ordinary files) or search (for directories) permission bit
for the owner of the file. Usually 0100. <code>S_IEXEC</code> is an obsolete
synonym provided for BSD compatibility.
</p>
</dd>
<dt> <code>S_IRWXU</code></dt>
<dd><a name="index-S_005fIRWXU"></a>
<p>This is equivalent to ‘<samp>(S_IRUSR | S_IWUSR | S_IXUSR)</samp>’.
</p>
</dd>
<dt> <code>S_IRGRP</code></dt>
<dd><a name="index-S_005fIRGRP"></a>
<p>Read permission bit for the group owner of the file. Usually 040.
</p>
</dd>
<dt> <code>S_IWGRP</code></dt>
<dd><a name="index-S_005fIWGRP"></a>
<p>Write permission bit for the group owner of the file. Usually 020.
</p>
</dd>
<dt> <code>S_IXGRP</code></dt>
<dd><a name="index-S_005fIXGRP"></a>
<p>Execute or search permission bit for the group owner of the file.
Usually 010.
</p>
</dd>
<dt> <code>S_IRWXG</code></dt>
<dd><a name="index-S_005fIRWXG"></a>
<p>This is equivalent to ‘<samp>(S_IRGRP | S_IWGRP | S_IXGRP)</samp>’.
</p>
</dd>
<dt> <code>S_IROTH</code></dt>
<dd><a name="index-S_005fIROTH"></a>
<p>Read permission bit for other users. Usually 04.
</p>
</dd>
<dt> <code>S_IWOTH</code></dt>
<dd><a name="index-S_005fIWOTH"></a>
<p>Write permission bit for other users. Usually 02.
</p>
</dd>
<dt> <code>S_IXOTH</code></dt>
<dd><a name="index-S_005fIXOTH"></a>
<p>Execute or search permission bit for other users. Usually 01.
</p>
</dd>
<dt> <code>S_IRWXO</code></dt>
<dd><a name="index-S_005fIRWXO"></a>
<p>This is equivalent to ‘<samp>(S_IROTH | S_IWOTH | S_IXOTH)</samp>’.
</p>
</dd>
<dt> <code>S_ISUID</code></dt>
<dd><a name="index-S_005fISUID"></a>
<p>This is the set-user-ID on execute bit, usually 04000.
See section <a href="libc_29.html#How-Change-Persona">How an Application Can Change Persona</a>.
</p>
</dd>
<dt> <code>S_ISGID</code></dt>
<dd><a name="index-S_005fISGID"></a>
<p>This is the set-group-ID on execute bit, usually 02000.
See section <a href="libc_29.html#How-Change-Persona">How an Application Can Change Persona</a>.
</p>
<a name="index-sticky-bit"></a>
</dd>
<dt> <code>S_ISVTX</code></dt>
<dd><a name="index-S_005fISVTX"></a>
<p>This is the <em>sticky</em> bit, usually 01000.
</p>
<p>For a directory it gives permission to delete a file in that directory
only if you own that file. Ordinarily, a user can either delete all the
files in a directory or cannot delete any of them (based on whether the
user has write permission for the directory). The same restriction
applies—you must have both write permission for the directory and own
the file you want to delete. The one exception is that the owner of the
directory can delete any file in the directory, no matter who owns it
(provided the owner has given himself write permission for the
directory). This is commonly used for the ‘<tt>/tmp</tt>’ directory, where
anyone may create files but not delete files created by other users.
</p>
<p>Originally the sticky bit on an executable file modified the swapping
policies of the system. Normally, when a program terminated, its pages
in core were immediately freed and reused. If the sticky bit was set on
the executable file, the system kept the pages in core for a while as if
the program were still running. This was advantageous for a program
likely to be run many times in succession. This usage is obsolete in
modern systems. When a program terminates, its pages always remain in
core as long as there is no shortage of memory in the system. When the
program is next run, its pages will still be in core if no shortage
arose since the last run.
</p>
<p>On some modern systems where the sticky bit has no useful meaning for an
executable file, you cannot set the bit at all for a non-directory.
If you try, <code>chmod</code> fails with <code>EFTYPE</code>;
see section <a href="#Setting-Permissions">Assigning File Permissions</a>.
</p>
<p>Some systems (particularly SunOS) have yet another use for the sticky
bit. If the sticky bit is set on a file that is <em>not</em> executable,
it means the opposite: never cache the pages of this file at all. The
main use of this is for the files on an NFS server machine which are
used as the swap area of diskless client machines. The idea is that the
pages of the file will be cached in the client’s memory, so it is a
waste of the server’s memory to cache them a second time. With this
usage the sticky bit also implies that the filesystem may fail to record
the file’s modification time onto disk reliably (the idea being that
no-one cares for a swap file).
</p>
<p>This bit is only available on BSD systems (and those derived from
them). Therefore one has to use the <code>_BSD_SOURCE</code> feature select
macro to get the definition (see section <a href="libc_1.html#Feature-Test-Macros">Feature Test Macros</a>).
</p></dd>
</dl>
<p>The actual bit values of the symbols are listed in the table above
so you can decode file mode values when debugging your programs.
These bit values are correct for most systems, but they are not
guaranteed.
</p>
<p><strong>Warning:</strong> Writing explicit numbers for file permissions is bad
practice. Not only is it not portable, it also requires everyone who
reads your program to remember what the bits mean. To make your program
clean use the symbolic names.
</p>
<hr size="6">
<a name="Access-Permission"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Permission-Bits" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Setting-Permissions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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-Your-Access-to-a-File-is-Decided"></a>
<h3 class="subsection">14.9.6 How Your Access to a File is Decided</h3>
<a name="index-permission-to-access-a-file"></a>
<a name="index-access-permission-for-a-file"></a>
<a name="index-file-access-permission"></a>
<p>Recall that the operating system normally decides access permission for
a file based on the effective user and group IDs of the process and its
supplementary group IDs, together with the file’s owner, group and
permission bits. These concepts are discussed in detail in <a href="libc_29.html#Process-Persona">The Persona of a Process</a>.
</p>
<p>If the effective user ID of the process matches the owner user ID of the
file, then permissions for read, write, and execute/search are
controlled by the corresponding “user” (or “owner”) bits. Likewise,
if any of the effective group ID or supplementary group IDs of the
process matches the group owner ID of the file, then permissions are
controlled by the “group” bits. Otherwise, permissions are controlled
by the “other” bits.
</p>
<p>Privileged users, like ‘<samp>root</samp>’, can access any file regardless of
its permission bits. As a special case, for a file to be executable
even by a privileged user, at least one of its execute bits must be set.
</p>
<hr size="6">
<a name="Setting-Permissions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Access-Permission" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Testing-File-Access" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Assigning-File-Permissions"></a>
<h3 class="subsection">14.9.7 Assigning File Permissions</h3>
<a name="index-file-creation-mask"></a>
<a name="index-umask"></a>
<p>The primitive functions for creating files (for example, <code>open</code> or
<code>mkdir</code>) take a <var>mode</var> argument, which specifies the file
permissions to give the newly created file. This mode is modified by
the process’s <em>file creation mask</em>, or <em>umask</em>, before it is
used.
</p>
<p>The bits that are set in the file creation mask identify permissions
that are always to be disabled for newly created files. For example, if
you set all the “other” access bits in the mask, then newly created
files are not accessible at all to processes in the “other” category,
even if the <var>mode</var> argument passed to the create function would
permit such access. In other words, the file creation mask is the
complement of the ordinary access permissions you want to grant.
</p>
<p>Programs that create files typically specify a <var>mode</var> argument that
includes all the permissions that make sense for the particular file.
For an ordinary file, this is typically read and write permission for
all classes of users. These permissions are then restricted as
specified by the individual user’s own file creation mask.
</p>
<a name="index-chmod"></a>
<p>To change the permission of an existing file given its name, call
<code>chmod</code>. This function uses the specified permission bits and
ignores the file creation mask.
</p>
<a name="index-umask-1"></a>
<p>In normal use, the file creation mask is initialized by the user’s login
shell (using the <code>umask</code> shell command), and inherited by all
subprocesses. Application programs normally don’t need to worry about
the file creation mask. It will automatically do what it is supposed to
do.
</p>
<p>When your program needs to create a file and bypass the umask for its
access permissions, the easiest way to do this is to use <code>fchmod</code>
after opening the file, rather than changing the umask. In fact,
changing the umask is usually done only by shells. They use the
<code>umask</code> function.
</p>
<p>The functions in this section are declared in ‘<tt>sys/stat.h</tt>’.
<a name="index-sys_002fstat_002eh-5"></a>
</p>
<dl>
<dt><a name="index-umask-2"></a><u>Function:</u> mode_t <b>umask</b><i> (mode_t <var>mask</var>)</i></dt>
<dd><p>The <code>umask</code> function sets the file creation mask of the current
process to <var>mask</var>, and returns the previous value of the file
creation mask.
</p>
<p>Here is an example showing how to read the mask with <code>umask</code>
without changing it permanently:
</p>
<table><tr><td> </td><td><pre class="smallexample">mode_t
read_umask (void)
{
mode_t mask = umask (0);
umask (mask);
return mask;
}
</pre></td></tr></table>
<p>However, it is better to use <code>getumask</code> if you just want to read
the mask value, because it is reentrant (at least if you use the GNU
operating system).
</p></dd></dl>
<dl>
<dt><a name="index-getumask"></a><u>Function:</u> mode_t <b>getumask</b><i> (void)</i></dt>
<dd><p>Return the current value of the file creation mask for the current
process. This function is a GNU extension.
</p></dd></dl>
<dl>
<dt><a name="index-chmod-1"></a><u>Function:</u> int <b>chmod</b><i> (const char *<var>filename</var>, mode_t <var>mode</var>)</i></dt>
<dd><p>The <code>chmod</code> function sets the access permission bits for the file
named by <var>filename</var> to <var>mode</var>.
</p>
<p>If <var>filename</var> is a symbolic link, <code>chmod</code> changes the
permissions of the file pointed to by the link, not those of the link
itself.
</p>
<p>This function returns <code>0</code> if successful and <code>-1</code> if not. In
addition to the usual file name errors (see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), the following <code>errno</code> error conditions are defined for
this function:
</p>
<dl compact="compact">
<dt> <code>ENOENT</code></dt>
<dd><p>The named file doesn’t exist.
</p>
</dd>
<dt> <code>EPERM</code></dt>
<dd><p>This process does not have permission to change the access permissions
of this file. Only the file’s owner (as judged by the effective user ID
of the process) or a privileged user can change them.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The file resides on a read-only file system.
</p>
</dd>
<dt> <code>EFTYPE</code></dt>
<dd><p><var>mode</var> has the <code>S_ISVTX</code> bit (the “sticky bit”) set,
and the named file is not a directory. Some systems do not allow setting the
sticky bit on non-directory files, and some do (and only some of those
assign a useful meaning to the bit for non-directory files).
</p>
<p>You only get <code>EFTYPE</code> on systems where the sticky bit has no useful
meaning for non-directory files, so it is always safe to just clear the
bit in <var>mode</var> and call <code>chmod</code> again. See section <a href="#Permission-Bits">The Mode Bits for Access Permission</a>,
for full details on the sticky bit.
</p></dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-fchmod"></a><u>Function:</u> int <b>fchmod</b><i> (int <var>filedes</var>, int <var>mode</var>)</i></dt>
<dd><p>This is like <code>chmod</code>, except that it changes the permissions of the
currently open file given by <var>filedes</var>.
</p>
<p>The return value from <code>fchmod</code> is <code>0</code> on success and <code>-1</code>
on failure. The following <code>errno</code> error codes are defined for this
function:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> argument is not a valid file descriptor.
</p>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p>The <var>filedes</var> argument corresponds to a pipe or socket, or something
else that doesn’t really have access permissions.
</p>
</dd>
<dt> <code>EPERM</code></dt>
<dd><p>This process does not have permission to change the access permissions
of this file. Only the file’s owner (as judged by the effective user ID
of the process) or a privileged user can change them.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The file resides on a read-only file system.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="Testing-File-Access"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Setting-Permissions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#File-Times" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Testing-Permission-to-Access-a-File"></a>
<h3 class="subsection">14.9.8 Testing Permission to Access a File</h3>
<a name="index-testing-access-permission"></a>
<a name="index-access_002c-testing-for"></a>
<a name="index-setuid-programs-and-file-access"></a>
<p>In some situations it is desirable to allow programs to access files or
devices even if this is not possible with the permissions granted to the
user. One possible solution is to set the setuid-bit of the program
file. If such a program is started the <em>effective</em> user ID of the
process is changed to that of the owner of the program file. So to
allow write access to files like ‘<tt>/etc/passwd</tt>’, which normally can
be written only by the super-user, the modifying program will have to be
owned by <code>root</code> and the setuid-bit must be set.
</p>
<p>But beside the files the program is intended to change the user should
not be allowed to access any file to which s/he would not have access
anyway. The program therefore must explicitly check whether <em>the
user</em> would have the necessary access to a file, before it reads or
writes the file.
</p>
<p>To do this, use the function <code>access</code>, which checks for access
permission based on the process’s <em>real</em> user ID rather than the
effective user ID. (The setuid feature does not alter the real user ID,
so it reflects the user who actually ran the program.)
</p>
<p>There is another way you could check this access, which is easy to
describe, but very hard to use. This is to examine the file mode bits
and mimic the system’s own access computation. This method is
undesirable because many systems have additional access control
features; your program cannot portably mimic them, and you would not
want to try to keep track of the diverse features that different systems
have. Using <code>access</code> is simple and automatically does whatever is
appropriate for the system you are using.
</p>
<p><code>access</code> is <em>only</em> only appropriate to use in setuid programs.
A non-setuid program will always use the effective ID rather than the
real ID.
</p>
<a name="index-unistd_002eh-10"></a>
<p>The symbols in this section are declared in ‘<tt>unistd.h</tt>’.
</p>
<dl>
<dt><a name="index-access"></a><u>Function:</u> int <b>access</b><i> (const char *<var>filename</var>, int <var>how</var>)</i></dt>
<dd><p>The <code>access</code> function checks to see whether the file named by
<var>filename</var> can be accessed in the way specified by the <var>how</var>
argument. The <var>how</var> argument either can be the bitwise OR of the
flags <code>R_OK</code>, <code>W_OK</code>, <code>X_OK</code>, or the existence test
<code>F_OK</code>.
</p>
<p>This function uses the <em>real</em> user and group IDs of the calling
process, rather than the <em>effective</em> IDs, to check for access
permission. As a result, if you use the function from a <code>setuid</code>
or <code>setgid</code> program (see section <a href="libc_29.html#How-Change-Persona">How an Application Can Change Persona</a>), it gives
information relative to the user who actually ran the program.
</p>
<p>The return value is <code>0</code> if the access is permitted, and <code>-1</code>
otherwise. (In other words, treated as a predicate function,
<code>access</code> returns true if the requested access is <em>denied</em>.)
</p>
<p>In addition to the usual file name errors (see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), the following <code>errno</code> error conditions are defined for
this function:
</p>
<dl compact="compact">
<dt> <code>EACCES</code></dt>
<dd><p>The access specified by <var>how</var> is denied.
</p>
</dd>
<dt> <code>ENOENT</code></dt>
<dd><p>The file doesn’t exist.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>Write permission was requested for a file on a read-only file system.
</p></dd>
</dl>
</dd></dl>
<p>These macros are defined in the header file ‘<tt>unistd.h</tt>’ for use
as the <var>how</var> argument to the <code>access</code> function. The values
are integer constants.
<a name="index-unistd_002eh-11"></a>
</p>
<dl>
<dt><a name="index-R_005fOK"></a><u>Macro:</u> int <b>R_OK</b></dt>
<dd><p>Flag meaning test for read permission.
</p></dd></dl>
<dl>
<dt><a name="index-W_005fOK"></a><u>Macro:</u> int <b>W_OK</b></dt>
<dd><p>Flag meaning test for write permission.
</p></dd></dl>
<dl>
<dt><a name="index-X_005fOK"></a><u>Macro:</u> int <b>X_OK</b></dt>
<dd><p>Flag meaning test for execute/search permission.
</p></dd></dl>
<dl>
<dt><a name="index-F_005fOK"></a><u>Macro:</u> int <b>F_OK</b></dt>
<dd><p>Flag meaning test for existence of the file.
</p></dd></dl>
<hr size="6">
<a name="File-Times"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Testing-File-Access" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#File-Size" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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-Times-1"></a>
<h3 class="subsection">14.9.9 File Times</h3>
<a name="index-file-access-time"></a>
<a name="index-file-modification-time"></a>
<a name="index-file-attribute-modification-time"></a>
<p>Each file has three time stamps associated with it: its access time,
its modification time, and its attribute modification time. These
correspond to the <code>st_atime</code>, <code>st_mtime</code>, and <code>st_ctime</code>
members of the <code>stat</code> structure; see <a href="#File-Attributes">File Attributes</a>.
</p>
<p>All of these times are represented in calendar time format, as
<code>time_t</code> objects. This data type is defined in ‘<tt>time.h</tt>’.
For more information about representation and manipulation of time
values, see <a href="libc_21.html#Calendar-Time">Calendar Time</a>.
<a name="index-time_002eh"></a>
</p>
<p>Reading from a file updates its access time attribute, and writing
updates its modification time. When a file is created, all three
time stamps for that file are set to the current time. In addition, the
attribute change time and modification time fields of the directory that
contains the new entry are updated.
</p>
<p>Adding a new name for a file with the <code>link</code> function updates the
attribute change time field of the file being linked, and both the
attribute change time and modification time fields of the directory
containing the new name. These same fields are affected if a file name
is deleted with <code>unlink</code>, <code>remove</code> or <code>rmdir</code>. Renaming
a file with <code>rename</code> affects only the attribute change time and
modification time fields of the two parent directories involved, and not
the times for the file being renamed.
</p>
<p>Changing the attributes of a file (for example, with <code>chmod</code>)
updates its attribute change time field.
</p>
<p>You can also change some of the time stamps of a file explicitly using
the <code>utime</code> function—all except the attribute change time. You
need to include the header file ‘<tt>utime.h</tt>’ to use this facility.
<a name="index-utime_002eh"></a>
</p>
<dl>
<dt><a name="index-struct-utimbuf"></a><u>Data Type:</u> <b>struct utimbuf</b></dt>
<dd><p>The <code>utimbuf</code> structure is used with the <code>utime</code> function to
specify new access and modification times for a file. It contains the
following members:
</p>
<dl compact="compact">
<dt> <code>time_t actime</code></dt>
<dd><p>This is the access time for the file.
</p>
</dd>
<dt> <code>time_t modtime</code></dt>
<dd><p>This is the modification time for the file.
</p></dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-utime"></a><u>Function:</u> int <b>utime</b><i> (const char *<var>filename</var>, const struct utimbuf *<var>times</var>)</i></dt>
<dd><p>This function is used to modify the file times associated with the file
named <var>filename</var>.
</p>
<p>If <var>times</var> is a null pointer, then the access and modification times
of the file are set to the current time. Otherwise, they are set to the
values from the <code>actime</code> and <code>modtime</code> members (respectively)
of the <code>utimbuf</code> structure pointed to by <var>times</var>.
</p>
<p>The attribute modification time for the file is set to the current time
in either case (since changing the time stamps is itself a modification
of the file attributes).
</p>
<p>The <code>utime</code> function returns <code>0</code> if successful and <code>-1</code>
on failure. In addition to the usual file name errors
(see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), the following <code>errno</code> error conditions
are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EACCES</code></dt>
<dd><p>There is a permission problem in the case where a null pointer was
passed as the <var>times</var> argument. In order to update the time stamp on
the file, you must either be the owner of the file, have write
permission for the file, or be a privileged user.
</p>
</dd>
<dt> <code>ENOENT</code></dt>
<dd><p>The file doesn’t exist.
</p>
</dd>
<dt> <code>EPERM</code></dt>
<dd><p>If the <var>times</var> argument is not a null pointer, you must either be
the owner of the file or be a privileged user.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The file lives on a read-only file system.
</p></dd>
</dl>
</dd></dl>
<p>Each of the three time stamps has a corresponding microsecond part,
which extends its resolution. These fields are called
<code>st_atime_usec</code>, <code>st_mtime_usec</code>, and <code>st_ctime_usec</code>;
each has a value between 0 and 999,999, which indicates the time in
microseconds. They correspond to the <code>tv_usec</code> field of a
<code>timeval</code> structure; see <a href="libc_21.html#High_002dResolution-Calendar">High-Resolution Calendar</a>.
</p>
<p>The <code>utimes</code> function is like <code>utime</code>, but also lets you specify
the fractional part of the file times. The prototype for this function is
in the header file ‘<tt>sys/time.h</tt>’.
<a name="index-sys_002ftime_002eh"></a>
</p>
<dl>
<dt><a name="index-utimes"></a><u>Function:</u> int <b>utimes</b><i> (const char *<var>filename</var>, struct timeval <var>tvp</var><tt>[2]</tt>)</i></dt>
<dd><p>This function sets the file access and modification times of the file
<var>filename</var>. The new file access time is specified by
<code><var>tvp</var>[0]</code>, and the new modification time by
<code><var>tvp</var>[1]</code>. Similar to <code>utime</code>, if <var>tvp</var> is a null
pointer then the access and modification times of the file are set to
the current time. This function comes from BSD.
</p>
<p>The return values and error conditions are the same as for the <code>utime</code>
function.
</p></dd></dl>
<dl>
<dt><a name="index-lutimes"></a><u>Function:</u> int <b>lutimes</b><i> (const char *<var>filename</var>, struct timeval <var>tvp</var><tt>[2]</tt>)</i></dt>
<dd><p>This function is like <code>utimes</code>, except that it does not follow
symbolic links. If <var>filename</var> is the name of a symbolic link,
<code>lutimes</code> sets the file access and modification times of the
symbolic link special file itself (as seen by <code>lstat</code>;
see section <a href="#Symbolic-Links">Symbolic Links</a>) while <code>utimes</code> sets the file access and
modification times of the file the symbolic link refers to. This
function comes from FreeBSD, and is not available on all platforms (if
not available, it will fail with <code>ENOSYS</code>).
</p>
<p>The return values and error conditions are the same as for the <code>utime</code>
function.
</p></dd></dl>
<dl>
<dt><a name="index-futimes"></a><u>Function:</u> int <b>futimes</b><i> (int <var>fd</var>, struct timeval <var>tvp</var><tt>[2]</tt>)</i></dt>
<dd><p>This function is like <code>utimes</code>, except that it takes an open file
descriptor as an argument instead of a file name. See section <a href="libc_13.html#Low_002dLevel-I_002fO">Low-Level Input/Output</a>. This function comes from FreeBSD, and is not available on all
platforms (if not available, it will fail with <code>ENOSYS</code>).
</p>
<p>Like <code>utimes</code>, <code>futimes</code> returns <code>0</code> on success and <code>-1</code>
on failure. The following <code>errno</code> error conditions are defined for
<code>futimes</code>:
</p>
<dl compact="compact">
<dt> <code>EACCES</code></dt>
<dd><p>There is a permission problem in the case where a null pointer was
passed as the <var>times</var> argument. In order to update the time stamp on
the file, you must either be the owner of the file, have write
permission for the file, or be a privileged user.
</p>
</dd>
<dt> <code>EBADF</code></dt>
<dd><p>The <var>filedes</var> argument is not a valid file descriptor.
</p>
</dd>
<dt> <code>EPERM</code></dt>
<dd><p>If the <var>times</var> argument is not a null pointer, you must either be
the owner of the file or be a privileged user.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The file lives on a read-only file system.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="File-Size"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#File-Times" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Making-Special-Files" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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-Size-1"></a>
<h3 class="subsection">14.9.10 File Size</h3>
<p>Normally file sizes are maintained automatically. A file begins with a
size of <em>0</em> and is automatically extended when data is written past
its end. It is also possible to empty a file completely by an
<code>open</code> or <code>fopen</code> call.
</p>
<p>However, sometimes it is necessary to <em>reduce</em> the size of a file.
This can be done with the <code>truncate</code> and <code>ftruncate</code> functions.
They were introduced in BSD Unix. <code>ftruncate</code> was later added to
POSIX.1.
</p>
<p>Some systems allow you to extend a file (creating holes) with these
functions. This is useful when using memory-mapped I/O
(see section <a href="libc_13.html#Memory_002dmapped-I_002fO">Memory-mapped I/O</a>), where files are not automatically extended.
However, it is not portable but must be implemented if <code>mmap</code>
allows mapping of files (i.e., <code>_POSIX_MAPPED_FILES</code> is defined).
</p>
<p>Using these functions on anything other than a regular file gives
<em>undefined</em> results. On many systems, such a call will appear to
succeed, without actually accomplishing anything.
</p>
<dl>
<dt><a name="index-truncate"></a><u>Function:</u> int <b>truncate</b><i> (const char *<var>filename</var>, off_t <var>length</var>)</i></dt>
<dd>
<p>The <code>truncate</code> function changes the size of <var>filename</var> to
<var>length</var>. If <var>length</var> is shorter than the previous length, data
at the end will be lost. The file must be writable by the user to
perform this operation.
</p>
<p>If <var>length</var> is longer, holes will be added to the end. However, some
systems do not support this feature and will leave the file unchanged.
</p>
<p>When the source file is compiled with <code>_FILE_OFFSET_BITS == 64</code> the
<code>truncate</code> function is in fact <code>truncate64</code> and the type
<code>off_t</code> has 64 bits which makes it possible to handle files up to
<em>2^63</em> bytes in length.
</p>
<p>The return value is <em>0</em> for success, or <em>-1</em> for an error. In
addition to the usual file name errors, the following errors may occur:
</p>
<dl compact="compact">
<dt> <code>EACCES</code></dt>
<dd><p>The file is a directory or not writable.
</p>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p><var>length</var> is negative.
</p>
</dd>
<dt> <code>EFBIG</code></dt>
<dd><p>The operation would extend the file beyond the limits of the operating system.
</p>
</dd>
<dt> <code>EIO</code></dt>
<dd><p>A hardware I/O error occurred.
</p>
</dd>
<dt> <code>EPERM</code></dt>
<dd><p>The file is "append-only" or "immutable".
</p>
</dd>
<dt> <code>EINTR</code></dt>
<dd><p>The operation was interrupted by a signal.
</p>
</dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-truncate64"></a><u>Function:</u> int <b>truncate64</b><i> (const char *<var>name</var>, off64_t <var>length</var>)</i></dt>
<dd><p>This function is similar to the <code>truncate</code> function. The
difference is that the <var>length</var> argument is 64 bits wide even on 32
bits machines, which allows the handling of files with sizes up to
<em>2^63</em> bytes.
</p>
<p>When the source file is compiled with <code>_FILE_OFFSET_BITS == 64</code> on a
32 bits machine this function is actually available under the name
<code>truncate</code> and so transparently replaces the 32 bits interface.
</p></dd></dl>
<dl>
<dt><a name="index-ftruncate"></a><u>Function:</u> int <b>ftruncate</b><i> (int <var>fd</var>, off_t <var>length</var>)</i></dt>
<dd>
<p>This is like <code>truncate</code>, but it works on a file descriptor <var>fd</var>
for an opened file instead of a file name to identify the object. The
file must be opened for writing to successfully carry out the operation.
</p>
<p>The POSIX standard leaves it implementation defined what happens if the
specified new <var>length</var> of the file is bigger than the original size.
The <code>ftruncate</code> function might simply leave the file alone and do
nothing or it can increase the size to the desired size. In this later
case the extended area should be zero-filled. So using <code>ftruncate</code>
is no reliable way to increase the file size but if it is possible it is
probably the fastest way. The function also operates on POSIX shared
memory segments if these are implemented by the system.
</p>
<p><code>ftruncate</code> is especially useful in combination with <code>mmap</code>.
Since the mapped region must have a fixed size one cannot enlarge the
file by writing something beyond the last mapped page. Instead one has
to enlarge the file itself and then remap the file with the new size.
The example below shows how this works.
</p>
<p>When the source file is compiled with <code>_FILE_OFFSET_BITS == 64</code> the
<code>ftruncate</code> function is in fact <code>ftruncate64</code> and the type
<code>off_t</code> has 64 bits which makes it possible to handle files up to
<em>2^63</em> bytes in length.
</p>
<p>The return value is <em>0</em> for success, or <em>-1</em> for an error. The
following errors may occur:
</p>
<dl compact="compact">
<dt> <code>EBADF</code></dt>
<dd><p><var>fd</var> does not correspond to an open file.
</p>
</dd>
<dt> <code>EACCES</code></dt>
<dd><p><var>fd</var> is a directory or not open for writing.
</p>
</dd>
<dt> <code>EINVAL</code></dt>
<dd><p><var>length</var> is negative.
</p>
</dd>
<dt> <code>EFBIG</code></dt>
<dd><p>The operation would extend the file beyond the limits of the operating system.
</p>
</dd>
<dt> <code>EIO</code></dt>
<dd><p>A hardware I/O error occurred.
</p>
</dd>
<dt> <code>EPERM</code></dt>
<dd><p>The file is "append-only" or "immutable".
</p>
</dd>
<dt> <code>EINTR</code></dt>
<dd><p>The operation was interrupted by a signal.
</p>
</dd>
</dl>
</dd></dl>
<dl>
<dt><a name="index-ftruncate64"></a><u>Function:</u> int <b>ftruncate64</b><i> (int <var>id</var>, off64_t <var>length</var>)</i></dt>
<dd><p>This function is similar to the <code>ftruncate</code> function. The
difference is that the <var>length</var> argument is 64 bits wide even on 32
bits machines which allows the handling of files with sizes up to
<em>2^63</em> bytes.
</p>
<p>When the source file is compiled with <code>_FILE_OFFSET_BITS == 64</code> on a
32 bits machine this function is actually available under the name
<code>ftruncate</code> and so transparently replaces the 32 bits interface.
</p></dd></dl>
<p>As announced here is a little example of how to use <code>ftruncate</code> in
combination with <code>mmap</code>:
</p>
<table><tr><td> </td><td><pre class="smallexample">int fd;
void *start;
size_t len;
int
add (off_t at, void *block, size_t size)
{
if (at + size > len)
{
/* Resize the file and remap. */
size_t ps = sysconf (_SC_PAGESIZE);
size_t ns = (at + size + ps - 1) & ~(ps - 1);
void *np;
if (ftruncate (fd, ns) < 0)
return -1;
np = mmap (NULL, ns, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
if (np == MAP_FAILED)
return -1;
start = np;
len = ns;
}
memcpy ((char *) start + at, block, size);
return 0;
}
</pre></td></tr></table>
<p>The function <code>add</code> writes a block of memory at an arbitrary
position in the file. If the current size of the file is too small it
is extended. Note the it is extended by a round number of pages. This
is a requirement of <code>mmap</code>. The program has to keep track of the
real size, and when it has finished a final <code>ftruncate</code> call should
set the real size of the file.
</p>
<hr size="6">
<a name="Making-Special-Files"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#File-Size" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Temporary-Files" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Making-Special-Files-1"></a>
<h2 class="section">14.10 Making Special Files</h2>
<a name="index-creating-special-files"></a>
<a name="index-special-files"></a>
<p>The <code>mknod</code> function is the primitive for making special files,
such as files that correspond to devices. The GNU library includes
this function for compatibility with BSD.
</p>
<p>The prototype for <code>mknod</code> is declared in ‘<tt>sys/stat.h</tt>’.
<a name="index-sys_002fstat_002eh-6"></a>
</p>
<dl>
<dt><a name="index-mknod"></a><u>Function:</u> int <b>mknod</b><i> (const char *<var>filename</var>, int <var>mode</var>, int <var>dev</var>)</i></dt>
<dd><p>The <code>mknod</code> function makes a special file with name <var>filename</var>.
The <var>mode</var> specifies the mode of the file, and may include the various
special file bits, such as <code>S_IFCHR</code> (for a character special file)
or <code>S_IFBLK</code> (for a block special file). See section <a href="#Testing-File-Type">Testing the Type of a File</a>.
</p>
<p>The <var>dev</var> argument specifies which device the special file refers to.
Its exact interpretation depends on the kind of special file being created.
</p>
<p>The return value is <code>0</code> on success and <code>-1</code> on error. In addition
to the usual file name errors (see section <a href="libc_11.html#File-Name-Errors">File Name Errors</a>), the
following <code>errno</code> error conditions are defined for this function:
</p>
<dl compact="compact">
<dt> <code>EPERM</code></dt>
<dd><p>The calling process is not privileged. Only the superuser can create
special files.
</p>
</dd>
<dt> <code>ENOSPC</code></dt>
<dd><p>The directory or file system that would contain the new file is full
and cannot be extended.
</p>
</dd>
<dt> <code>EROFS</code></dt>
<dd><p>The directory containing the new file can’t be modified because it’s on
a read-only file system.
</p>
</dd>
<dt> <code>EEXIST</code></dt>
<dd><p>There is already a file named <var>filename</var>. If you want to replace
this file, you must remove the old file explicitly first.
</p></dd>
</dl>
</dd></dl>
<hr size="6">
<a name="Temporary-Files"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Making-Special-Files" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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="Temporary-Files-1"></a>
<h2 class="section">14.11 Temporary Files</h2>
<p>If you need to use a temporary file in your program, you can use the
<code>tmpfile</code> function to open it. Or you can use the <code>tmpnam</code>
(better: <code>tmpnam_r</code>) function to provide a name for a temporary
file and then you can open it in the usual way with <code>fopen</code>.
</p>
<p>The <code>tempnam</code> function is like <code>tmpnam</code> but lets you choose
what directory temporary files will go in, and something about what
their file names will look like. Important for multi-threaded programs
is that <code>tempnam</code> is reentrant, while <code>tmpnam</code> is not since it
returns a pointer to a static buffer.
</p>
<p>These facilities are declared in the header file ‘<tt>stdio.h</tt>’.
<a name="index-stdio_002eh-17"></a>
</p>
<dl>
<dt><a name="index-tmpfile"></a><u>Function:</u> FILE * <b>tmpfile</b><i> (void)</i></dt>
<dd><p>This function creates a temporary binary file for update mode, as if by
calling <code>fopen</code> with mode <code>"wb+"</code>. The file is deleted
automatically when it is closed or when the program terminates. (On
some other ISO C systems the file may fail to be deleted if the program
terminates abnormally).
</p>
<p>This function is reentrant.
</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>tmpfile64</code>, i.e., the LFS
interface transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-tmpfile64"></a><u>Function:</u> FILE * <b>tmpfile64</b><i> (void)</i></dt>
<dd><p>This function is similar to <code>tmpfile</code>, but the stream it returns a
pointer to was opened using <code>tmpfile64</code>. Therefore this stream can
be used for 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>tmpfile</code>
and so transparently replaces the old interface.
</p></dd></dl>
<dl>
<dt><a name="index-tmpnam"></a><u>Function:</u> char * <b>tmpnam</b><i> (char *<var>result</var>)</i></dt>
<dd><p>This function constructs and returns a valid file name that does not
refer to any existing file. If the <var>result</var> argument is a null
pointer, the return value is a pointer to an internal static string,
which might be modified by subsequent calls and therefore makes this
function non-reentrant. Otherwise, the <var>result</var> argument should be
a pointer to an array of at least <code>L_tmpnam</code> characters, and the
result is written into that array.
</p>
<p>It is possible for <code>tmpnam</code> to fail if you call it too many times
without removing previously-created files. This is because the limited
length of the temporary file names gives room for only a finite number
of different names. If <code>tmpnam</code> fails it returns a null pointer.
</p>
<p><strong>Warning:</strong> Between the time the pathname is constructed and the
file is created another process might have created a file with the same
name using <code>tmpnam</code>, leading to a possible security hole. The
implementation generates names which can hardly be predicted, but when
opening the file you should use the <code>O_EXCL</code> flag. Using
<code>tmpfile</code> or <code>mkstemp</code> is a safe way to avoid this problem.
</p></dd></dl>
<dl>
<dt><a name="index-tmpnam_005fr"></a><u>Function:</u> char * <b>tmpnam_r</b><i> (char *<var>result</var>)</i></dt>
<dd><p>This function is nearly identical to the <code>tmpnam</code> function, except
that if <var>result</var> is a null pointer it returns a null pointer.
</p>
<p>This guarantees reentrancy because the non-reentrant situation of
<code>tmpnam</code> cannot happen here.
</p>
<p><strong>Warning</strong>: This function has the same security problems as
<code>tmpnam</code>.
</p></dd></dl>
<dl>
<dt><a name="index-L_005ftmpnam"></a><u>Macro:</u> int <b>L_tmpnam</b></dt>
<dd><p>The value of this macro is an integer constant expression that
represents the minimum size of a string large enough to hold a file name
generated by the <code>tmpnam</code> function.
</p></dd></dl>
<dl>
<dt><a name="index-TMP_005fMAX"></a><u>Macro:</u> int <b>TMP_MAX</b></dt>
<dd><p>The macro <code>TMP_MAX</code> is a lower bound for how many temporary names
you can create with <code>tmpnam</code>. You can rely on being able to call
<code>tmpnam</code> at least this many times before it might fail saying you
have made too many temporary file names.
</p>
<p>With the GNU library, you can create a very large number of temporary
file names. If you actually created the files, you would probably run
out of disk space before you ran out of names. Some other systems have
a fixed, small limit on the number of temporary files. The limit is
never less than <code>25</code>.
</p></dd></dl>
<dl>
<dt><a name="index-tempnam"></a><u>Function:</u> char * <b>tempnam</b><i> (const char *<var>dir</var>, const char *<var>prefix</var>)</i></dt>
<dd><p>This function generates a unique temporary file name. If <var>prefix</var>
is not a null pointer, up to five characters of this string are used as
a prefix for the file name. The return value is a string newly
allocated with <code>malloc</code>, so you should release its storage with
<code>free</code> when it is no longer needed.
</p>
<p>Because the string is dynamically allocated this function is reentrant.
</p>
<p>The directory prefix for the temporary file name is determined by
testing each of the following in sequence. The directory must exist and
be writable.
</p>
<ul>
<li>
The environment variable <code>TMPDIR</code>, if it is defined. For security
reasons this only happens if the program is not SUID or SGID enabled.
</li><li>
The <var>dir</var> argument, if it is not a null pointer.
</li><li>
The value of the <code>P_tmpdir</code> macro.
</li><li>
The directory ‘<tt>/tmp</tt>’.
</li></ul>
<p>This function is defined for SVID compatibility.
</p>
<p><strong>Warning:</strong> Between the time the pathname is constructed and the
file is created another process might have created a file with the same
name using <code>tempnam</code>, leading to a possible security hole. The
implementation generates names which can hardly be predicted, but when
opening the file you should use the <code>O_EXCL</code> flag. Using
<code>tmpfile</code> or <code>mkstemp</code> is a safe way to avoid this problem.
</p></dd></dl>
<a name="index-TMPDIR-environment-variable"></a>
<dl>
<dt><a name="index-P_005ftmpdir"></a><u>SVID Macro:</u> char * <b>P_tmpdir</b></dt>
<dd><p>This macro is the name of the default directory for temporary files.
</p></dd></dl>
<p>Older Unix systems did not have the functions just described. Instead
they used <code>mktemp</code> and <code>mkstemp</code>. Both of these functions
work by modifying a file name template string you pass. The last six
characters of this string must be ‘<samp>XXXXXX</samp>’. These six ‘<samp>X</samp>’s
are replaced with six characters which make the whole string a unique
file name. Usually the template string is something like
‘<samp>/tmp/<var>prefix</var>XXXXXX</samp>’, and each program uses a unique <var>prefix</var>.
</p>
<p><strong>NB:</strong> Because <code>mktemp</code> and <code>mkstemp</code> modify the
template string, you <em>must not</em> pass string constants to them.
String constants are normally in read-only storage, so your program
would crash when <code>mktemp</code> or <code>mkstemp</code> tried to modify the
string. These functions are declared in the header file ‘<tt>stdlib.h</tt>’.
<a name="index-stdlib_002eh-10"></a>
</p>
<dl>
<dt><a name="index-mktemp"></a><u>Function:</u> char * <b>mktemp</b><i> (char *<var>template</var>)</i></dt>
<dd><p>The <code>mktemp</code> function generates a unique file name by modifying
<var>template</var> as described above. If successful, it returns
<var>template</var> as modified. If <code>mktemp</code> cannot find a unique file
name, it makes <var>template</var> an empty string and returns that. If
<var>template</var> does not end with ‘<samp>XXXXXX</samp>’, <code>mktemp</code> returns a
null pointer.
</p>
<p><strong>Warning:</strong> Between the time the pathname is constructed and the
file is created another process might have created a file with the same
name using <code>mktemp</code>, leading to a possible security hole. The
implementation generates names which can hardly be predicted, but when
opening the file you should use the <code>O_EXCL</code> flag. Using
<code>mkstemp</code> is a safe way to avoid this problem.
</p></dd></dl>
<dl>
<dt><a name="index-mkstemp"></a><u>Function:</u> int <b>mkstemp</b><i> (char *<var>template</var>)</i></dt>
<dd><p>The <code>mkstemp</code> function generates a unique file name just as
<code>mktemp</code> does, but it also opens the file for you with <code>open</code>
(see section <a href="libc_13.html#Opening-and-Closing-Files">Opening and Closing Files</a>). If successful, it modifies
<var>template</var> in place and returns a file descriptor for that file open
for reading and writing. If <code>mkstemp</code> cannot create a
uniquely-named file, it returns <code>-1</code>. If <var>template</var> does not
end with ‘<samp>XXXXXX</samp>’, <code>mkstemp</code> returns <code>-1</code> and does not
modify <var>template</var>.
</p>
<p>The file is opened using mode <code>0600</code>. If the file is meant to be
used by other users this mode must be changed explicitly.
</p></dd></dl>
<p>Unlike <code>mktemp</code>, <code>mkstemp</code> is actually guaranteed to create a
unique file that cannot possibly clash with any other program trying to
create a temporary file. This is because it works by calling
<code>open</code> with the <code>O_EXCL</code> flag, which says you want to create a
new file and get an error if the file already exists.
</p>
<dl>
<dt><a name="index-mkdtemp"></a><u>Function:</u> char * <b>mkdtemp</b><i> (char *<var>template</var>)</i></dt>
<dd><p>The <code>mkdtemp</code> function creates a directory with a unique name. If
it succeeds, it overwrites <var>template</var> with the name of the
directory, and returns <var>template</var>. As with <code>mktemp</code> and
<code>mkstemp</code>, <var>template</var> should be a string ending with
‘<samp>XXXXXX</samp>’.
</p>
<p>If <code>mkdtemp</code> cannot create an uniquely named directory, it returns
<code>NULL</code> and sets <var>errno</var> appropriately. If <var>template</var> does
not end with ‘<samp>XXXXXX</samp>’, <code>mkdtemp</code> returns <code>NULL</code> and does
not modify <var>template</var>. <var>errno</var> will be set to <code>EINVAL</code> in
this case.
</p>
<p>The directory is created using mode <code>0700</code>.
</p></dd></dl>
<p>The directory created by <code>mkdtemp</code> cannot clash with temporary
files or directories created by other users. This is because directory
creation always works like <code>open</code> with <code>O_EXCL</code>.
See section <a href="#Creating-Directories">Creating Directories</a>.
</p>
<p>The <code>mkdtemp</code> function comes from OpenBSD.
</p><hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" 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>
|