This file is indexed.

/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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Working-Directory" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="libc_13.html#Low_002dLevel-I_002fO" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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&rsquo;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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">              A file that &ldquo;points to&rdquo; a file name.
</td></tr>
<tr><td align="left" valign="top"><a href="#Deleting-Files">14.6 Deleting Files</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">              Changing a file&rsquo;s name.
</td></tr>
<tr><td align="left" valign="top"><a href="#Creating-Directories">14.8 Creating Directories</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Accessing-Directories" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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&rsquo;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
&lsquo;<tt>unistd.h</tt>&rsquo;.
<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&rsquo;s <code>getcwd (NULL, 0)</code>
using only the standard behavior of <code>getcwd</code>:
</p>
<table><tr><td>&nbsp;</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&rsquo;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&rsquo;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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Directory-Entries" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Opening-a-Directory" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>dirent.h</tt>&rsquo;.
</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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Reading_002fClosing-Directory" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>dirent.h</tt>&rsquo;.
</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&rsquo;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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Simple-Directory-Lister" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>dirent.h</tt>&rsquo;.
</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 &lsquo;<tt>.</tt>&rsquo; and &lsquo;<tt>..</tt>&rsquo;, 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&rsquo;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>&nbsp;</td><td><pre class="smallexample">  union
  {
    struct dirent d;
    char b[offsetof (struct dirent, d_name) + NAME_MAX + 1];
  } u;

  if (readdir_r (dir, &amp;u.d, &amp;res) == 0)
    &hellip;
</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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Random-Access-Directory" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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&rsquo;s a simple program that prints the names of the files in
the current working directory:
</p>
<table><tr><td>&nbsp;</td><td><pre class="smallexample">#include &lt;stdio.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;dirent.h&gt;
</pre><pre class="smallexample">
int
main (void)
{
  DIR *dp;
  struct dirent *ep;

  dp = opendir (&quot;./&quot;);
  if (dp != NULL)
    {
      while (ep = readdir (dp))
        puts (ep-&gt;d_name);
      (void) closedir (dp);
    }
  else
    perror (&quot;Couldn't open the directory&quot;);

  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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Scanning-Directory-Content" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>dirent.h</tt>&rsquo;.
</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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Simple-Directory-Lister-Mark-II" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Working-with-Directory-Trees" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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>&nbsp;</td><td><pre class="smallexample">#include &lt;stdio.h&gt;
#include &lt;dirent.h&gt;
</pre><pre class="smallexample">
static int
one (const struct dirent *unused)
{
  return 1;
}

int
main (void)
{
  struct dirent **eps;
  int n;

  n = scandir (&quot;./&quot;, &amp;eps, one, alphasort);
  if (n &gt;= 0)
    {
      int cnt;
      for (cnt = 0; cnt &lt; n; ++cnt)
        puts (eps[cnt]-&gt;d_name);
    }
  else
    perror (&quot;Couldn't open the directory&quot;);

  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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Hard-Links" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>ftw.h</tt>&rsquo;
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>&nbsp;</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 &lsquo;<tt>ftw.h</tt>&rsquo; 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>&nbsp;</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>&nbsp;</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>&nbsp;</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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Symbolic-Links" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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&rsquo;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 &lsquo;<tt>unistd.h</tt>&rsquo;.
<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&rsquo;t exist.  You can&rsquo;t make a link to
a file that doesn&rsquo;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&rsquo;t be modified because it&rsquo;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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Deleting-Files" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &ldquo;file&rdquo; 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 &lsquo;<tt>sys/param.h</tt>&rsquo; 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
&lsquo;<tt>unistd.h</tt>&rsquo;.
<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>&nbsp;</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 &lt; 0)
        {
          free (buffer);
          return NULL;
        }
      if (nchars &lt; 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 &lsquo;<tt>stdlib.h</tt>&rsquo;.
</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 &lsquo;<tt>stdlib.h</tt>&rsquo;.
</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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Renaming-Files" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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&rsquo;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&rsquo;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 &lsquo;<tt>unistd.h</tt>&rsquo;.
</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&rsquo;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&rsquo;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&rsquo;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 &lsquo;<tt>.</tt>&rsquo; and &lsquo;<tt>..</tt>&rsquo;.
</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
&lsquo;<tt>unistd.h</tt>&rsquo;.
<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 &lsquo;<tt>stdio.h</tt>&rsquo;.
<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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Creating-Directories" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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&rsquo;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&mdash;which
is inconsistent.  We don&rsquo;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 &ldquo;atomically&rdquo; 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 &ldquo;in between&rdquo; 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&rsquo;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&rsquo;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&rsquo;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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#File-Attributes" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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&rsquo;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
&lsquo;<tt>sys/stat.h</tt>&rsquo;.
<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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Attribute-Meanings" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<samp>ls -l</samp>&rsquo; 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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">           Distinguishing ordinary files,
                                 directories, links&hellip;
</td></tr>
<tr><td align="left" valign="top"><a href="#File-Owner">14.9.4 File Owner</a></td><td>&nbsp;&nbsp;</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>&nbsp;&nbsp;</td><td align="left" valign="top">             How information about a file&rsquo;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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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>&nbsp;&nbsp;</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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Reading-Attributes" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>sys/stat.h</tt>&rsquo; 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&rsquo;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&rsquo;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&mdash;it may have
&ldquo;holes&rdquo; 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>&nbsp;</td><td><pre class="smallexample">(st.st_blocks * 512 &lt; 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&rsquo;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&rsquo;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 &lsquo;<tt>sys/types.h</tt>&rsquo; as well as in &lsquo;<tt>sys/stat.h</tt>&rsquo;.
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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Testing-File-Type" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>sys/stat.h</tt>&rsquo;.
</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&rsquo;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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#File-Owner" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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
&lsquo;<tt>sys/stat.h</tt>&rsquo;.
<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>&nbsp;</td><td><pre class="smallexample">S_ISCHR (<var>mode</var>)
</pre></td></tr></table>

<p>is equivalent to:
</p>
<table><tr><td>&nbsp;</td><td><pre class="smallexample">((<var>mode</var> &amp; 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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Permission-Bits" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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&rsquo;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&rsquo;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 &lsquo;<tt>unistd.h</tt>&rsquo;.
</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&rsquo;s owner can change the file&rsquo;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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Access-Permission" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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
&lsquo;<tt>sys/stat.h</tt>&rsquo;.
<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 &lsquo;<samp>(S_IRUSR | S_IWUSR | S_IXUSR)</samp>&rsquo;.
</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 &lsquo;<samp>(S_IRGRP | S_IWGRP | S_IXGRP)</samp>&rsquo;.
</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 &lsquo;<samp>(S_IROTH | S_IWOTH | S_IXOTH)</samp>&rsquo;.
</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&mdash;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 &lsquo;<tt>/tmp</tt>&rsquo; 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&rsquo;s memory, so it is a
waste of the server&rsquo;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&rsquo;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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Setting-Permissions" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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&rsquo;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 &ldquo;user&rdquo; (or &ldquo;owner&rdquo;) 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 &ldquo;group&rdquo; bits.  Otherwise, permissions are controlled
by the &ldquo;other&rdquo; bits.
</p>
<p>Privileged users, like &lsquo;<samp>root</samp>&rsquo;, 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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Testing-File-Access" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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&rsquo;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 &ldquo;other&rdquo; access bits in the mask, then newly created
files are not accessible at all to processes in the &ldquo;other&rdquo; 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&rsquo;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&rsquo;s login
shell (using the <code>umask</code> shell command), and inherited by all
subprocesses.  Application programs normally don&rsquo;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 &lsquo;<tt>sys/stat.h</tt>&rsquo;.
<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>&nbsp;</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&rsquo;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&rsquo;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 &ldquo;sticky bit&rdquo;) 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&rsquo;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&rsquo;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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#File-Times" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>/etc/passwd</tt>&rsquo;, 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&rsquo;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&rsquo;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 &lsquo;<tt>unistd.h</tt>&rsquo;.
</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&rsquo;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 &lsquo;<tt>unistd.h</tt>&rsquo; 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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#File-Size" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>time.h</tt>&rsquo;.
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&mdash;all except the attribute change time.  You
need to include the header file &lsquo;<tt>utime.h</tt>&rsquo; 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&rsquo;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 &lsquo;<tt>sys/time.h</tt>&rsquo;.
<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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Making-Special-Files" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &quot;append-only&quot; or &quot;immutable&quot;.
</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 &quot;append-only&quot; or &quot;immutable&quot;.
</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>&nbsp;</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 &gt; len)
    {
      /* Resize the file and remap.  */
      size_t ps = sysconf (_SC_PAGESIZE);
      size_t ns = (at + size + ps - 1) &amp; ~(ps - 1);
      void *np;
      if (ftruncate (fd, ns) &lt; 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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Temporary-Files" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>sys/stat.h</tt>&rsquo;.
<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&rsquo;t be modified because it&rsquo;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"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="#File-System-Interface" title="Beginning of this chapter or previous chapter"> &lt;&lt; </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"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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 &lsquo;<tt>stdio.h</tt>&rsquo;.
<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>&quot;wb+&quot;</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 &lsquo;<tt>/tmp</tt>&rsquo;.
</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 &lsquo;<samp>XXXXXX</samp>&rsquo;.  These six &lsquo;<samp>X</samp>&rsquo;s
are replaced with six characters which make the whole string a unique
file name.  Usually the template string is something like
&lsquo;<samp>/tmp/<var>prefix</var>XXXXXX</samp>&rsquo;, 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 &lsquo;<tt>stdlib.h</tt>&rsquo;.
<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 &lsquo;<samp>XXXXXX</samp>&rsquo;, <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 &lsquo;<samp>XXXXXX</samp>&rsquo;, <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
&lsquo;<samp>XXXXXX</samp>&rsquo;.
</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 &lsquo;<samp>XXXXXX</samp>&rsquo;, <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"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="libc_15.html#Pipes-and-FIFOs" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </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>