This file is indexed.

/usr/share/doc/qdbm-doc/spex.html is in qdbm-doc 1.8.78-6build3.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="author" content="Mikio Hirabayashi" />
<meta name="keywords" content="QDBM, DBM, database, hash, B+ tree" />
<meta name="description" content="fundamental specifications of QDBM" />
<link rel="contents" href="./" />
<link rel="alternate" href="spex-ja.html" hreflang="ja" title="the Japanese version" />
<link rev="made" href="mailto:mikio@fallabs.com" />
<title>Specifications of QDBM Version 1</title>
<style type="text/css">html { margin: 0em 0em; padding: 0em 0em; background: #eeeeee none; }
body { margin: 2em 2em; padding: 0em 0em;
  background: #eeeeee none; color: #111111;
  font-style: normal; font-weight: normal; }
h1 { margin-top: 1.8em; margin-bottom: 1.3em; font-weight: bold; }
h2 { margin-top: 1.8em; margin-bottom: 1.1em; font-weight: bold;
  border-left: solid 0.6em #445555; border-bottom: solid 1pt #bbbbbb;
  padding: 0.5em 0.5em; width: 60%; }
h3 { margin-top: 1.8em; margin-bottom: 0.8em; font-weight: bold; }
hr { margin-top: 2.5em; margin-bottom: 1.5em; height: 1pt;
  color: #999999; background-color: #999999; border: none; }
div.note,div.navi { text-align: right; }
div.logo { text-align: center; margin: 3em 0em; }
div.logo img { border: inset 2pt #ccccdd; }
p { margin: 0.8em 0em; line-height: 140%; }
p,dd { text-indent: 0.8em; }
div,pre { margin-left: 1.7em; margin-right: 1.7em; }
pre { background-color: #ddddee; padding: 0.2em; border: 1pt solid #bbbbcc; font-size: smaller; }
kbd { color: #111111; font-style: normal; font-weight: bold; }
a { color: #0022aa; text-decoration: none; }
a:hover,a:focus { color: #0033ee; text-decoration: underline; }
a.head { color: #111111; text-decoration: none; }
table { padding: 1pt 2pt 1pt 2pt; border: none; margin-left: 1.7em; border-collapse: collapse; }
th { padding: 1pt 4pt 1pt 4pt; border-style: none;
  text-align: left; vertical-align: bottom; }
td { padding: 1pt 4pt 1pt 4pt; border: 1pt solid #333333;
  text-align: left; vertical-align: top; }
ul,ol,dl { line-height: 140%; }
dt { margin-left: 1.2em; }
dd { margin-left: 2.0em; }
ul.lines { list-style-type: none; }
@media print {
  html,body { margin: 0em 0em; background-color: #ffffff; color: #000000; }
  h1 { padding: 8em 0em 0.5em 0em; text-align: center; }
  h2 { page-break-before: always; }
  div.note { text-align: center; }
  div.navi,div.logo { display: none }
  hr { display: none; }
  pre { margin: 0.8em 0.8em; background-color: #ffffff;
    border: 1pt solid #aaaaaa; font-size: smaller; }
  a,kbd { color: #000000; text-decoration: none; }
  h1,h2,h3 { font-family: sans-serif; }
  p,div,li,dt,dd { font-family: serif; }
  pre,kbd { font-family: monospace; }
  dd { font-size: smaller; }
}
</style>
</head>

<body>

<h1>Fundamental Specifications of QDBM Version 1</h1>

<div class="note">Copyright (C) 2000-2007 Mikio Hirabayashi</div>
<div class="note">Last Update: Thu, 26 Oct 2006 15:00:20 +0900</div>
<div class="navi">[<a href="spex-ja.html" hreflang="ja">Japanese</a>]</div>

<hr />

<h2>Table of Contents</h2>

<ol>
<li><a href="#overview">Overview</a></li>
<li><a href="#features">Features</a></li>
<li><a href="#installation">Installation</a></li>
<li><a href="#depotapi">Depot: Basic API</a></li>
<li><a href="#depotcli">Commands for Depot</a></li>
<li><a href="#curiaapi">Curia: Extended API</a></li>
<li><a href="#curiacli">Commands for Curia</a></li>
<li><a href="#relicapi">Relic: NDBM-compatible API</a></li>
<li><a href="#reliccli">Commands for Relic</a></li>
<li><a href="#hovelapi">Hovel: GDBM-compatible API</a></li>
<li><a href="#hovelcli">Commands for Hovel</a></li>
<li><a href="#cabinapi">Cabin: Utility API</a></li>
<li><a href="#cabincli">Commands for Cabin</a></li>
<li><a href="#villaapi">Villa: Advanced API</a></li>
<li><a href="#villacli">Commands for Villa</a></li>
<li><a href="#odeumapi">Odeum: Inverted API</a></li>
<li><a href="#odeumcli">Commands for Odeum</a></li>
<li><a href="#fileformat">File Format</a></li>
<li><a href="#porting">Porting</a></li>
<li><a href="#bugs">Bugs</a></li>
<li><a href="#faq">Frequently Asked Questions</a></li>
<li><a href="#copying">Copying</a></li>
</ol>

<hr />

<h2><a name="overview" id="overview" class="head">Overview</a></h2>

<p>QDBM is a library of routines for managing a database.  The database is a simple data file containing records, each is a pair of a key and a value.  Every key and value is serial bytes with variable length.  Both binary data and character string can be used as a key and a value.  There is neither concept of data tables nor data types.  Records are organized in hash table or B+ tree.</p>

<p>As for database of hash table, each key must be unique within a database, so it is impossible to store two or more records with a key overlaps.  The following access methods are provided to the database: storing a record with a key and a value, deleting a record by a key, retrieving a record by a key.  Moreover, traversal access to every key are provided, although the order is arbitrary.  These access methods are similar to ones of DBM (or its followers: NDBM and GDBM) library defined in the UNIX standard.  QDBM is an alternative for DBM because of its higher performance.</p>

<p>As for database of B+ tree, records whose keys are duplicated can be stored.  Access methods of storing, deleting, and retrieving are provided as with the database of hash table.  Records are stored in order by a comparing function assigned by a user.  It is possible to access each record with the cursor in ascending or descending order.  According to this mechanism, forward matching search for strings and range search for integers are realized.  Moreover, transaction is available in database of B+ tree.</p>

<p>QDBM is written in C, and provided as APIs of C, C++, Java, Perl, and Ruby.  QDBM is available on platforms which have API conforming to POSIX.  QDBM is a free software licensed under the GNU Lesser General Public License.</p>

<hr />

<h2><a name="features" id="features" class="head">Features</a></h2>

<h3>Effective Implementation of Hash Database</h3>

<p>QDBM is developed referring to GDBM for the purpose of the following three points: higher processing speed, smaller size of a database file, and simpler API.  They have been achieved.  Moreover, as with GDBM, the following three restrictions of traditional DBM: a process can handle only one database, the size of a key and a value is bounded, a database file is sparse, are cleared.</p>

<p>QDBM uses hash algorithm to retrieve records.  If a bucket array has sufficient number of elements, the time complexity of retrieval is `O(1)'.  That is, time required for retrieving a record is constant, regardless of the scale of a database.  It is also the same about storing and deleting.  Collision of hash values is managed by separate chaining.  Data structure of the chains is binary search tree.  Even if a bucket array has unusually scarce elements, the time complexity of retrieval is `O(log n)'.</p>

<p>QDBM attains improvement in retrieval by loading RAM with the whole of a bucket array.  If a bucket array is on RAM, it is possible to access a region of a target record by about one path of file operations.  A bucket array saved in a file is not read into RAM with the `read' call but directly mapped to RAM with the `mmap' call.  Therefore, preparation time on connecting to a database is very short, and two or more processes can share the same memory map.</p>

<p>If the number of elements of a bucket array is about half of records stored within a database, although it depends on characteristic of the input, the probability of collision of hash values is about 56.7% (36.8% if the same, 21.3% if twice, 11.5% if four times, 6.0% if eight times).  In such case, it is possible to retrieve a record by two or less paths of file operations.  If it is made into a performance index, in order to handle a database containing one million of records, a bucket array with half a million of elements is needed.  The size of each element is 4 bytes.  That is, if 2M bytes of RAM is available, a database containing one million records can be handled.</p>

<p>QDBM provides two modes to connect to a database: `reader' and `writer'.  A reader can perform retrieving but neither storing nor deleting.  A writer can perform all access methods.  Exclusion control between processes is performed when connecting to a database by file locking.  While a writer is connected to a database, neither readers nor writers can be connected.  While a reader is connected to a database, other readers can be connect, but writers can not.  According to this mechanism, data consistency is guaranteed with simultaneous connections in multitasking environment.</p>

<p>Traditional DBM provides two modes of the storing operations: `insert' and `replace'.  In the case a key overlaps an existing record, the insert mode keeps the existing value, while the replace mode transposes it to the specified value.  In addition to the two modes, QDBM provides `concatenate' mode.  In the mode, the specified value is concatenated at the end of the existing value and stored.  This feature is useful when adding a element to a value as an array.  Moreover, although DBM has a method to fetch out a value from a database only by reading the whole of a region of a record, QDBM has a method to fetch out a part of a region of a value.  When a value is treated as an array, this feature is also useful.</p>

<p>Generally speaking, while succession of updating, fragmentation of available regions occurs, and the size of a database grows rapidly.  QDBM deal with this problem by coalescence of dispensable regions and reuse of them, and featuring of optimization of a database.  When overwriting a record with a value whose size is greater than the existing one, it is necessary to remove the region to another position of the file.  Because the time complexity of the operation depends on the size of the region of a record, extending values successively is inefficient.  However, QDBM deal with this problem by alignment.  If increment can be put in padding, it is not necessary to remove the region.</p>

<p>As for many file systems, it is impossible to handle a file whose size is more than 2GB.  To deal with this problem, QDBM provides a directory database containing multiple database files.  Due to this feature, it is possible to handle a database whose total size is up to 1TB in theory.  Moreover, because database files can be deployed on multiple disks, the speed of updating operations can be improved as with RAID-0 (striping).  It is also possible for the database files to deploy on multiple file servers using NFS and so on.</p>

<h3>Useful Implementation of B+ Tree Database</h3>

<p>Although B+ tree database is slower than hash database, it features ordering access to each record.  The order can be assigned by users.  Records of B+ tree are sorted and arranged in logical pages.  Sparse index organized in B tree that is multiway balanced tree are maintained for each page.  Thus, the time complexity of retrieval and so on is `O(log n)'.  Cursor is provided to access each record in order.  The cursor can jump to a position specified by a key and can step forward or backward from the current position.  Because each page is arranged as double linked list, the time complexity of stepping cursor is `O(1)'.</p>

<p>B+ tree database is implemented, based on above hash database.  Because each page of B+ tree is stored as each record of hash database, B+ tree database inherits efficiency of storage management of hash database.  Because the header of each record is smaller and alignment of each page is adjusted according to the page size, in most cases, the size of database file is cut by half compared to one of hash database.  Although operation of many pages are required to update B+ tree, QDBM expedites the process by caching pages and reducing file operations.  In most cases, because whole of the sparse index is cached on memory, it is possible to retrieve a record by one or less path of file operations.</p>

<p>B+ tree database features transaction mechanism.  It is possible to commit a series of operations between the beginning and the end of the transaction in a lump, or to abort the transaction and perform rollback to the state before the transaction.  Even if the process of an application is crashed while the transaction, the database file is not broken.</p>

<p>In case that QDBM was built with ZLIB, LZO, or BZIP2 enabled, a lossless data-compression library, the content of each page of B+ tree is compressed and stored in a file.  Because each record in a page has similar patterns, high efficiency of compression is expected due to the Lempel-Ziv algorithm and the like.  In case handling text data, the size of a database is reduced to about 25%.  If the scale of a database is large and disk I/O is the bottleneck, featuring compression makes the processing speed improved to a large extent.</p>

<h3>Simple but Various Interfaces</h3>

<p>QDBM provides very simple APIs.  You can perform database I/O as usual file I/O with `FILE' pointer defined in ANSI C.  In the basic API of QDBM, entity of a database is recorded as one file.  In the extended API, entity of a database is recorded as several files in one directory.  Because the two APIs are very similar with each other, porting an application from one to the other is easy.</p>

<p>APIs which are compatible with NDBM and GDBM are also provided.  As there are a lot of applications using NDBM or GDBM, it is easy to port them onto QDBM.  In most cases, it is completed only by replacement of header including (#include) and re-compiling.  However, QDBM can not handle database files made by the original NDBM or GDBM.</p>

<p>In order to handle records on memory easily, the utility API is provided.  It implements memory allocating functions, sorting functions, extensible datum, array list, hash map, and so on.  Using them, you can handle records in C language cheaply as in such script languages as Perl or Ruby.</p>

<p>B+ tree database is used with the advanced API.  The advanced API is implemented using the basic API and the utility API.  Because the advanced API is also similar to the basic API and the extended API, it is easy to learn how to use it.</p>

<p>In order to handle an inverted index which is used by full-text search systems, the inverted API is provided.  If it is easy to handle an inverted index of documents, an application can focus on text processing and natural language processing.  Because this API does not depend on character codes nor languages, it is possible to implement a full-text search system which can respond to various requests from users.</p>

<p>Along with APIs for C, QDBM provides APIs for C++, Java, Perl, and Ruby.  APIs for C are composed of seven kinds: the basic API, the extended API, the NDBM-compatible API, the GDBM-compatible API, the utility API, the advanced API, and the inverted API.  Command line interfaces corresponding to each API are also provided.  They are useful for prototyping, testing, debugging, and so on.  The C++ API encapsulates database handling functions of the basic API, the extended API, and the advanced API with class mechanism of C++.  The Java API has native methods calling the basic API, the extended API, and the advanced API with Java Native Interface.  The Perl API has methods calling the basic API, the extended API, and the advanced API with XS language.  The Ruby API has method calling the basic API, the extended API, and the advanced API as modules of Ruby.  Moreover, CGI scripts for administration of databases, file uploading, and full-text search are provided.</p>

<h3>Wide Portability</h3>

<p>QDBM is implemented being based on syntax of ANSI C (C89) and using only APIs defined in ANSI C or POSIX.  Thus, QDBM works on most UNIX and its compatible OSs.  As for C API, checking operations have been done at least on the following platforms.</p>

<ul>
<li>Linux (2.2, 2.4, 2.6) (IA32, IA64, AMD64, PA-RISC, Alpha, PowerPC, M68000, ARM)</li>
<li>FreeBSD (4.9, 5.0, 5.1, 5.2, 5.3) (IA32, IA64, SPARC, Alpha)</li>
<li>NetBSD (1.6) (IA32)</li>
<li>OpenBSD (3.4) (IA32)</li>
<li>SunOS (5.6, 5.7, 5.8, 5.9, 5.10) (IA32, SPARC)</li>
<li>HP-UX (11.11, 11.23) (IA64, PA-RISC)</li>
<li>AIX (5.2) (POWER)</li>
<li>Windows (2000, XP) (IA32, IA64, AMD64) (Cygwin, MinGW, Visual C++)</li>
<li>Mac OS X (10.2, 10.3, 10.4) (IA32, PowerPC)</li>
<li>Tru64 (5.1) (Alpha)</li>
<li>RISC OS (5.03) (ARM)</li>
</ul>

<p>Although a database file created by QDBM depends on byte order of the processor, to do with it, utilities to dump data in format which is independent to byte orders are provided.</p>

<hr />

<h2><a name="installation" id="installation" class="head">Installation</a></h2>

<h3>Preparation</h3>

<p>To install QDBM from a source package, GCC of 2.8 or later version and `make' are required.</p>

<p>When an archive file of QDBM is extracted, change the current working directory to the generated directory and perform installation.</p>

<h3>Usual Steps</h3>

<p>Follow the procedures below on Linux, BSD, or SunOS.</p>

<p>Run the configuration script.</p>

<pre>./configure
</pre>

<p>Build programs.</p>

<pre>make
</pre>

<p>Perform self-diagnostic test.</p>

<pre>make check
</pre>

<p>Install programs.  This operation must be carried out by the root user.</p>

<pre>make install
</pre>

<h3>Using GNU Libtool</h3>

<p>If above steps do not work, try the following steps.  This way needs GNU Libtool of 1.5 or later version.</p>

<p>Run the configuration script.</p>

<pre>./configure
</pre>

<p>Build programs.</p>

<pre>make -f LTmakefile
</pre>

<p>Perform self-diagnostic test.</p>

<pre>make -f LTmakefile check
</pre>

<p>Install programs.  This operation must be carried out by the root user.</p>

<pre>make -f LTmakefile install
</pre>

<h3>Result</h3>

<p>When a series of work finishes, the following files will be installed.  As for the rest, manuals will be installed under `/usr/local/man/man1' and '/usr/local/man/man3', other documents will be installed under `/usr/local/share/qdbm'.  A configuration file for `pkg-config' will be installed under `/usr/local/lib/pkgconfig'.</p>

<pre>/usr/local/include/depot.h
/usr/local/include/curia.h
/usr/local/include/relic.h
/usr/local/include/hovel.h
/usr/local/include/cabin.h
/usr/local/include/villa.h
/usr/local/include/vista.h
/usr/local/include/odeum.h
/usr/local/lib/libqdbm.a
/usr/local/lib/libqdbm.so.14.14.0
/usr/local/lib/libqdbm.so.14
/usr/local/lib/libqdbm.so
/usr/local/bin/dpmgr
/usr/local/bin/dptest
/usr/local/bin/dptsv
/usr/local/bin/crmgr
/usr/local/bin/crtest
/usr/local/bin/crtsv
/usr/local/bin/rlmgr
/usr/local/bin/rltest
/usr/local/bin/hvmgr
/usr/local/bin/hvtest
/usr/local/bin/cbtest
/usr/local/bin/cbcodec
/usr/local/bin/vlmgr
/usr/local/bin/vltest
/usr/local/bin/vltsv
/usr/local/bin/odmgr
/usr/local/bin/odtest
/usr/local/bin/odidx
/usr/local/bin/qmttest
</pre>

<p>When you run a program linked dynamically to `libqdbm.so', the library search path should include `/usr/local/lib'.  You can set the library search path with the environment variable `LD_LIBRARY_PATH'.</p>

<p>To uninstall QDBM, execute the following command after `./configure'.  This operation must be carried out by the root user.</p>

<pre>make uninstall
</pre>

<p>If an old version of QDBM is installed on your system, uninstall it before installation of a new one.</p>

<p>The other APIs except for C nor CGI scripts are not installed by default.  Refer to `plus/xspex.html' to know how to install the C++ API.  Refer to `java/jspex.html' to know how to install the Java API.  Refer to `perl/plspex.html' to know how to install the Perl API.  Refer to `ruby/rbspex.html' to know how to install the Ruby API.  Refer to `cgi/cgispex.html' to know how to install the CGI script.</p>

<p>To install QDBM from such a binary package as RPM, refer to the manual of the package manager.  For example, if you use RPM, execute like the following command by the root user.</p>

<pre>rpm -ivh qdbm-1.x.x-x.i386.rpm
</pre>

<h3>For Windows</h3>

<p>On Windows (Cygwin), you should follow the procedures below for installation.</p>

<p>Run the configuration script.</p>

<pre>./configure
</pre>

<p>Build programs.</p>

<pre>make win
</pre>

<p>Perform self-diagnostic test.</p>

<pre>make check-win
</pre>

<p>Install programs.  As well, perform `make uninstall-win' to uninstall them.</p>

<pre>make install-win
</pre>

<p>On Windows, the import library `libqdbm.dll.a' is created as well as the static library `libqdbm.a', and the dynamic linking library `qdbm.dll' is created instead of such shared libraries as `libqdbm.so'.  `qdbm.dll' is installed into `/usr/local/bin'.</p>

<p>In order to build QDBM using MinGW on Cygwin, you should perform `make mingw' instead of `make win'.  With the UNIX emulation layer of Cygwin, generated programs depend on `cygwin1.dll' (they come under GNU GPL).  This problem is solved by linking them to the Win32 native DLL with MinGW.</p>

<p>In order to build QDBM using Visual C++, you should edit `VCmakefile' and set the search paths for libraries and headers.  And perform `nmake /f VCMakefile'.  Applications linking to `qdbm.dll' should link to `msvcrt.dll' by `/MD' or `/MDd' option of the compiler.  Refer to `VCmakefile' for detail configurations.</p>

<h3>For Mac OS X</h3>

<p>On Mac OS X (Darwin), you should follow the procedures below for installation.</p>

<p>Run the configuration script.</p>

<pre>./configure
</pre>

<p>Build programs.</p>

<pre>make mac
</pre>

<p>Perform self-diagnostic test.</p>

<pre>make check-mac
</pre>

<p>Install programs.  As well, perform `make uninstall-mac' to uninstall them.</p>

<pre>make install-mac
</pre>

<p>On Mac OS X, `libqdbm.dylib' and so on are created instead of `libqdbm.so' and so on.  You can set the library search path with the environment variable `DYLD_LIBRARY_PATH'.</p>

<h3>For HP-UX</h3>

<p>On HP-UX, you should follow the procedures below for installation.</p>

<p>Run the configuration script.</p>

<pre>./configure
</pre>

<p>Build programs.</p>

<pre>make hpux
</pre>

<p>Perform self-diagnostic test.</p>

<pre>make check-hpux
</pre>

<p>Install programs.  As well, perform `make uninstall-hpux' to uninstall them.</p>

<pre>make install-hpux
</pre>

<p>On HP-UX, `libqdbm.sl' is created instead of `libqdbm.so' and so on.  You can set the library search path with the environment variable `SHLIB_PATH'.</p>

<h3>For RISC OS</h3>

<p>On RISC OS, you should follow the procedures below for installation.</p>

<p>Build programs.  As `cc' is used for compilation by default, if you want to use `gcc', add the argument `CC=gcc'.</p>

<pre>make -f RISCmakefile
</pre>

<p>When a series of work finishes, the library file `libqdbm' and such commands as `dpmgr' are generated.  Because how to install them is not defined, copy them manually for installation.  As with it, such header files as `depot.h' should be installed manually.</p>

<h3>Detail Configurations</h3>

<p>You can configure building processes by the following optional arguments of `./configure'.</p>

<ul class="lines">
<li><kbd>--enable-debug</kbd> : build for debugging.  Enable debugging symbols, do not perform optimization, and perform static linking.</li>
<li><kbd>--enable-devel</kbd> : build for development.  Enable debugging symbols, perform optimization, and perform dynamic linking.</li>
<li><kbd>--enable-stable</kbd> : build for stable release.  Perform conservative optimization, and perform dynamic linking.</li>
<li><kbd>--enable-pthread</kbd> : feature POSIX thread and treat global variables as thread specific data.</li>
<li><kbd>--disable-lock</kbd> : build for environments without file locking.</li>
<li><kbd>--disable-mmap</kbd> : build for environments without memory mapping.</li>
<li><kbd>--enable-zlib</kbd> : feature ZLIB compression for B+ tree and inverted index.</li>
<li><kbd>--enable-lzo</kbd> : feature LZO compression for B+ tree and inverted index.</li>
<li><kbd>--enable-bzip</kbd> : feature BZIP2 compression for B+ tree and inverted index.</li>
<li><kbd>--enable-iconv</kbd> : feature ICONV utilities for conversion of character encodings.</li>
</ul>

<p>Usually, QDBM and its applications can be built without any dependency on non-standard libraries except for `libqdbm.*'.   However, they depend on `libpthread.*' if POSIX thread is enabled, and they depend on `libz.*' if ZLIB is enabled, and they depend on `liblzo2.*' if LZO is enabled, and they depend on `libbz2.*' if BZIP2 is enabled, and they depend on `libiconv.*' if ICONV is enabled.</p>

<p>Because the license of LZO is GNU GPL, note that applications linking to `liblzo2.*' should meet commitments of GNU GPL.</p>

<hr />

<h2><a name="depotapi" id="depotapi" class="head">Depot: Basic API</a></h2>

<h3>Overview</h3>

<p>Depot is the basic API of QDBM.  Almost all features for managing a database provided by QDBM are implemented by Depot.  Other APIs are no more than wrappers of Depot.  Depot is the fastest in all APIs of QDBM.</p>

<p>In order to use Depot, you should include `depot.h' and `stdlib.h' in the source files.  Usually, the following description will be near the beginning of a source file.</p>

<dl>
<dt><kbd>#include &lt;depot.h&gt;</kbd></dt>
<dt><kbd>#include &lt;stdlib.h&gt;</kbd></dt>
</dl>

<p>A pointer to `DEPOT' is used as a database handle.  It is like that some file I/O routines of `stdio.h' use a pointer to `FILE'.  A database handle is opened with the function `dpopen' and closed with `dpclose'.  You should not refer directly to any member of the handle.  If a fatal error occurs in a database, any access method via the handle except `dpclose' will not work and return error status.  Although a process is allowed to use multiple database handles at the same time, handles of the same database file should not be used.</p>

<h3>API</h3>

<p>The external variable `dpversion' is the string containing the version information.</p>

<dl>
<dt><kbd>extern const char *dpversion;</kbd></dt>
</dl>

<p>The external variable `dpecode' is assigned with the last happened error code.  Refer to `depot.h' for details of the error codes.</p>

<dl>
<dt><kbd>extern int dpecode;</kbd></dt>
<dd>The initial value of this variable is `DP_ENOERR'.  The other values are `DP_EFATAL', `DP_EMODE', `DP_EBROKEN', `DP_EKEEP', `DP_ENOITEM', `DP_EALLOC', `DP_EMAP', `DP_EOPEN', `DP_ECLOSE', `DP_ETRUNC', `DP_ESYNC', `DP_ESTAT', `DP_ESEEK', `DP_EREAD', `DP_EWRITE', `DP_ELOCK', `DP_EUNLINK', `DP_EMKDIR', `DP_ERMDIR', and `DP_EMISC'.</dd>
</dl>

<p>The function `dperrmsg' is used in order to get a message string corresponding to an error code.</p>

<dl>
<dt><kbd>const char *dperrmsg(int <var>ecode</var>);</kbd></dt>
<dd>`ecode' specifies an error code.  The return value is the message string of the error code.  The region of the return value is not writable.</dd>
</dl>

<p>The function `dpopen' is used in order to get a database handle.</p>

<dl>
<dt><kbd>DEPOT *dpopen(const char *<var>name</var>, int <var>omode</var>, int <var>bnum</var>);</kbd></dt>
<dd>`name' specifies the name of a database file.  `omode' specifies the connection mode: `DP_OWRITER' as a writer, `DP_OREADER' as a reader.  If the mode is `DP_OWRITER', the following may be added by bitwise or: `DP_OCREAT', which means it creates a new database if not exist, `DP_OTRUNC', which means it creates a new database regardless if one exists.  Both of `DP_OREADER' and `DP_OWRITER' can be added to by bitwise or: `DP_ONOLCK', which means it opens a database file without file locking, or `DP_OLCKNB', which means locking is performed without blocking.  `DP_OCREAT' can be added to by bitwise or: `DP_OSPARSE', which means it creates a database file as a sparse file.  `bnum' specifies the number of elements of the bucket array.  If it is not more than 0, the default value is specified.  The size of a bucket array is determined on creating, and can not be changed except for by optimization of the database.  Suggested size of a bucket array is about from 0.5 to 4 times of the number of all records to store.  The return value is the database handle or `NULL' if it is not successful.  While connecting as a writer, an exclusive lock is invoked to the database file.  While connecting as a reader, a shared lock is invoked to the database file.  The thread blocks until the lock is achieved.  If `DP_ONOLCK' is used, the application is responsible for exclusion control.</dd>
</dl>

<p>The function `dpclose' is used in order to close a database handle.</p>

<dl>
<dt><kbd>int dpclose(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  If successful, the return value is true, else, it is false.  Because the region of a closed handle is released, it becomes impossible to use the handle.  Updating a database is assured to be written when the handle is closed.  If a writer opens a database but does not close it appropriately, the database will be broken.</dd>
</dl>

<p>The function `dpput' is used in order to store a record.</p>

<dl>
<dt><kbd>int dpput(DEPOT *<var>depot</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, const char *<var>vbuf</var>, int <var>vsiz</var>, int <var>dmode</var>);</kbd></dt>
<dd>`depot' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `vbuf' specifies the pointer to the region of a value.  `vsiz' specifies the size of the region of the value.  If it is negative, the size is assigned with `strlen(vbuf)'.  `dmode' specifies behavior when the key overlaps, by the following values: `DP_DOVER', which means the specified value overwrites the existing one, `DP_DKEEP', which means the existing value is kept, `DP_DCAT', which means the specified value is concatenated at the end of the existing value.  If successful, the return value is true, else, it is false.</dd>
</dl>

<p>The function `dpout' is used in order to delete a record.</p>

<dl>
<dt><kbd>int dpout(DEPOT *<var>depot</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`depot' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is true, else, it is false.  False is returned when no record corresponds to the specified key.</dd>
</dl>

<p>The function `dpget' is used in order to retrieve a record.</p>

<dl>
<dt><kbd>char *dpget(DEPOT *<var>depot</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int <var>start</var>, int <var>max</var>, int *<var>sp</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `start' specifies the offset address of the beginning of the region of the value to be read.  `max' specifies the max size to be read.  If it is negative, the size to read is unlimited.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the value of the corresponding record, else, it is `NULL'.  `NULL' is returned when no record corresponds to the specified key or the size of the value of the corresponding record is less than `start'.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `dpgetwb' is used in order to retrieve a record and write the value into a buffer.</p>

<dl>
<dt><kbd>int dpgetwb(DEPOT *<var>depot</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int <var>start</var>, int <var>max</var>, char *<var>vbuf</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `start' specifies the offset address of the beginning of the region of the value to be read.  `max' specifies the max size to be read.  It shuld be equal to or less than the size of the writing buffer.  `vbuf' specifies the pointer to a buffer into which the value of the corresponding record is written.  If successful, the return value is the size of the written data, else, it is -1.  -1 is returned when no record corresponds to the specified key or the size of the value of the corresponding record is less than `start'.  Note that no additional zero code is appended at the end of the region of the writing buffer.</dd>
</dl>

<p>The function `dpvsiz' is used in order to get the size of the value of a record.</p>

<dl>
<dt><kbd>int dpvsiz(DEPOT *<var>depot</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is the size of the value of the corresponding record, else, it is -1.  Because this function does not read the entity of a record, it is faster than `dpget'.</dd>
</dl>

<p>The function `dpiterinit' is used in order to initialize the iterator of a database handle.</p>

<dl>
<dt><kbd>int dpiterinit(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  If successful, the return value is true, else, it is false.  The iterator is used in order to access the key of every record stored in a database.</dd>
</dl>

<p>The function `dpiternext' is used in order to get the next key of the iterator.</p>

<dl>
<dt><kbd>char *dpiternext(DEPOT *<var>depot</var>, int *<var>sp</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the next key, else, it is `NULL'.  `NULL' is returned when no record is to be get out of the iterator.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  It is possible to access every record by iteration of calling this function.  However, it is not assured if updating the database is occurred while the iteration.  Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.</dd>
</dl>

<p>The function `dpsetalign' is used in order to set alignment of a database handle.</p>

<dl>
<dt><kbd>int dpsetalign(DEPOT *<var>depot</var>, int <var>align</var>);</kbd></dt>
<dd>`depot' specifies a database handle connected as a writer.  `align' specifies the size of alignment.  If successful, the return value is true, else, it is false.  If alignment is set to a database, the efficiency of overwriting values is improved.  The size of alignment is suggested to be average size of the values of the records to be stored.  If alignment is positive, padding whose size is multiple number of the alignment is placed.  If alignment is negative, as `vsiz' is the size of a value, the size of padding is calculated with `(vsiz / pow(2, abs(align) - 1))'.  Because alignment setting is not saved in a database, you should specify alignment every opening a database.</dd>
</dl>

<p>The function `dpsetfbpsiz' is used in order to set the size of the free block pool of a database handle.</p>

<dl>
<dt><kbd>int dpsetfbpsiz(DEPOT *<var>depot</var>, int <var>size</var>);</kbd></dt>
<dd>`depot' specifies a database handle connected as a writer.  `size' specifies the size of the free block pool of a database.  If successful, the return value is true, else, it is false.  The default size of the free block pool is 16.  If the size is greater, the space efficiency of overwriting values is improved with the time efficiency sacrificed.</dd>
</dl>

<p>The function `dpsync' is used in order to synchronize updating contents with the file and the device.</p>

<dl>
<dt><kbd>int dpsync(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle connected as a writer.  If successful, the return value is true, else, it is false.  This function is useful when another process uses the connected database file.</dd>
</dl>

<p>The function `dpoptimize' is used in order to optimize a database.</p>

<dl>
<dt><kbd>int dpoptimize(DEPOT *<var>depot</var>, int <var>bnum</var>);</kbd></dt>
<dd>`depot' specifies a database handle connected as a writer.  `bnum' specifies the number of the elements of the bucket array.  If it is not more than 0, the default value is specified.  If successful, the return value is true, else, it is false.  In an alternating succession of deleting and storing with overwrite or concatenate, dispensable regions accumulate.  This function is useful to do away with them.</dd>
</dl>

<p>The function `dpname' is used in order to get the name of a database.</p>

<dl>
<dt><kbd>char *dpname(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  If successful, the return value is the pointer to the region of the name of the database, else, it is `NULL'.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `dpfsiz' is used in order to get the size of a database file.</p>

<dl>
<dt><kbd>int dpfsiz(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  If successful, the return value is the size of the database file, else, it is -1.</dd>
</dl>

<p>The function `dpbnum' is used in order to get the number of the elements of the bucket array.</p>

<dl>
<dt><kbd>int dpbnum(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  If successful, the return value is the number of the elements of the bucket array, else, it is -1.</dd>
</dl>

<p>The function `dpbusenum' is used in order to get the number of the used elements of the bucket array.</p>

<dl>
<dt><kbd>int dpbusenum(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  If successful, the return value is the number of the used elements of the bucket array, else, it is -1.  This function is inefficient because it accesses all elements of the bucket array.</dd>
</dl>

<p>The function `dprnum' is used in order to get the number of the records stored in a database.</p>

<dl>
<dt><kbd>int dprnum(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  If successful, the return value is the number of the records stored in the database, else, it is -1.</dd>
</dl>

<p>The function `dpwritable' is used in order to check whether a database handle is a writer or not.</p>

<dl>
<dt><kbd>int dpwritable(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  The return value is true if the handle is a writer, false if not.</dd>
</dl>

<p>The function `dpfatalerror' is used in order to check whether a database has a fatal error or not.</p>

<dl>
<dt><kbd>int dpfatalerror(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  The return value is true if the database has a fatal error, false if not.</dd>
</dl>

<p>The function `dpinode' is used in order to get the inode number of a database file.</p>

<dl>
<dt><kbd>int dpinode(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  The return value is the inode number of the database file.</dd>
</dl>

<p>The function `dpmtime' is used in order to get the last modified time of a database.</p>

<dl>
<dt><kbd>time_t dpmtime(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  The return value is the last modified time of the database.</dd>
</dl>

<p>The function `dpfdesc' is used in order to get the file descriptor of a database file.</p>

<dl>
<dt><kbd>int dpfdesc(DEPOT *<var>depot</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  The return value is the file descriptor of the database file.  Handling the file descriptor of a database file directly is not suggested.</dd>
</dl>

<p>The function `dpremove' is used in order to remove a database file.</p>

<dl>
<dt><kbd>int dpremove(const char *<var>name</var>);</kbd></dt>
<dd>`name' specifies the name of a database file.  If successful, the return value is true, else, it is false.</dd>
</dl>

<p>The function `dprepair' is used in order to repair a broken database file.</p>

<dl>
<dt><kbd>int dprepair(const char *<var>name</var>);</kbd></dt>
<dd>`name' specifies the name of a database file.  If successful, the return value is true, else, it is false.  There is no guarantee that all records in a repaired database file correspond to the original or expected state.</dd>
</dl>

<p>The function `dpexportdb' is used in order to dump all records as endian independent data.</p>

<dl>
<dt><kbd>int dpexportdb(DEPOT *<var>depot</var>, const char *<var>name</var>);</kbd></dt>
<dd>`depot' specifies a database handle.  `name' specifies the name of an output file.  If successful, the return value is true, else, it is false.</dd>
</dl>

<p>The function `dpimportdb' is used in order to load all records from endian independent data.</p>

<dl>
<dt><kbd>int dpimportdb(DEPOT *<var>depot</var>, const char *<var>name</var>);</kbd></dt>
<dd>`depot' specifies a database handle connected as a writer.  The database of the handle must be empty.  `name' specifies the name of an input file.  If successful, the return value is true, else, it is false.</dd>
</dl>

<p>The function `dpsnaffle' is used in order to retrieve a record directly from a database file.</p>

<dl>
<dt><kbd>char *dpsnaffle(const char *<var>name</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int *<var>sp</var>);</kbd></dt>
<dd>`name' specifies the name of a database file.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the value of the corresponding record, else, it is `NULL'.  `NULL' is returned when no record corresponds to the specified key.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  Although this function can be used even while the database file is locked by another process, it is not assured that recent updated is reflected.</dd>
</dl>

<p>The function `dpinnerhash' is a hash function used inside Depot.</p>

<dl>
<dt><kbd>int dpinnerhash(const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  The return value is the hash value of 31 bits length computed from the key.  This function is useful when an application calculates the state of the inside bucket array.</dd>
</dl>

<p>The function `dpouterhash' is a hash function which is independent from the hash functions used inside Depot.</p>

<dl>
<dt><kbd>int dpouterhash(const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  The return value is the hash value of 31 bits length computed from the key.  This function is useful when an application uses its own hash algorithm outside Depot.</dd>
</dl>

<p>The function `dpprimenum' is used in order to get a natural prime number not less than a number.</p>

<dl>
<dt><kbd>int dpprimenum(int <var>num</var>);</kbd></dt>
<dd>`num' specified a natural number.  The return value is a natural prime number not less than the specified number.  This function is useful when an application determines the size of a bucket array of its own hash algorithm.</dd>
</dl>

<h3>Examples</h3>

<p>The following example stores and retrieves a phone number, using the name as the key.</p>

<pre>#include &lt;depot.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;

#define NAME     "mikio"
#define NUMBER   "000-1234-5678"
#define DBNAME   "book"

int main(int argc, char **argv){
  DEPOT *depot;
  char *val;

  /* open the database */
  if(!(depot = dpopen(DBNAME, DP_OWRITER | DP_OCREAT, -1))){
    fprintf(stderr, "dpopen: %s\n", dperrmsg(dpecode));
    return 1;
  }

  /* store the record */
  if(!dpput(depot, NAME, -1, NUMBER, -1, DP_DOVER)){
    fprintf(stderr, "dpput: %s\n", dperrmsg(dpecode));
  }

  /* retrieve the record */
  if(!(val = dpget(depot, NAME, -1, 0, -1, NULL))){
    fprintf(stderr, "dpget: %s\n", dperrmsg(dpecode));
  } else {
    printf("Name: %s\n", NAME);
    printf("Number: %s\n", val);
    free(val);
  }

  /* close the database */
  if(!dpclose(depot)){
    fprintf(stderr, "dpclose: %s\n", dperrmsg(dpecode));
    return 1;
  }

  return 0;
}
</pre>

<p>The following example shows all records of the database.</p>

<pre>#include &lt;depot.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;

#define DBNAME   "book"

int main(int argc, char **argv){
  DEPOT *depot;
  char *key, *val;

  /* open the database */
  if(!(depot = dpopen(DBNAME, DP_OREADER, -1))){
    fprintf(stderr, "dpopen: %s\n", dperrmsg(dpecode));
    return 1;
  }

  /* initialize the iterator */
  if(!dpiterinit(depot)){
    fprintf(stderr, "dpiterinit: %s\n", dperrmsg(dpecode));
  }

  /* scan with the iterator */
  while((key = dpiternext(depot, NULL)) != NULL){
    if(!(val = dpget(depot, key, -1, 0, -1, NULL))){
      fprintf(stderr, "dpget: %s\n", dperrmsg(dpecode));
      free(key);
      break;
    }
    printf("%s: %s\n", key, val);
    free(val);
    free(key);
  }

  /* close the database */
  if(!dpclose(depot)){
    fprintf(stderr, "dpclose: %s\n", dperrmsg(dpecode));
    return 1;
  }

  return 0;
}
</pre>

<h3>Notes</h3>

<p>For building a program using Depot, the program should be linked with a library file `libqdbm.a' or `libqdbm.so'.  For example, the following command is executed to build `sample' from `sample.c'.</p>

<pre>gcc -I/usr/local/include -o sample sample.c -L/usr/local/lib -lqdbm
</pre>

<p>If QDBM was built with POSIX thread enabled, the global variable `dpecode' is treated as thread specific data, and functions of Depot are reentrant.  In that case, they are thread-safe as long as a handle is not accessed by threads at the same time, on the assumption that `errno', `malloc', and so on are thread-safe.</p>

<hr />

<h2><a name="depotcli" id="depotcli" class="head">Commands for Depot</a></h2>

<p>Depot has the following command line interfaces.</p>

<p>The command `dpmgr' is a utility for debugging Depot and its applications.  It features editing and checking of a database.  It can be used for database applications with shell scripts.  This command is used in the following format.  `name' specifies a database name.  `key' specifies the key of a record.  `val' specifies the value of a record.</p>

<dl>
<dt><kbd>dpmgr create [-s] [-bnum <var>num</var>] <var>name</var></kbd></dt>
<dd>Create a database file.</dd>
<dt><kbd>dpmgr put [-kx|-ki] [-vx|-vi|-vf] [-keep|-cat] [-na] <var>name</var> <var>key</var> <var>val</var></kbd></dt>
<dd>Store a record with a key and a value.</dd>
<dt><kbd>dpmgr out [-kx|-ki] <var>name</var> <var>key</var></kbd></dt>
<dd>Delete a record with a key.</dd>
<dt><kbd>dpmgr get [-nl] [-kx|-ki] [-start <var>num</var>] [-max <var>num</var>] [-ox] [-n] <var>name</var> <var>key</var></kbd></dt>
<dd>Retrieve a record with a key and output it to the standard output.</dd>
<dt><kbd>dpmgr list [-nl] [-k|-v] [-ox] <var>name</var></kbd></dt>
<dd>List all keys and values delimited with tab and line-feed to the standard output.</dd>
<dt><kbd>dpmgr optimize [-bnum <var>num</var>] [-na] <var>name</var></kbd></dt>
<dd>Optimize a database.</dd>
<dt><kbd>dpmgr inform [-nl] <var>name</var></kbd></dt>
<dd>Output miscellaneous information to the standard output.</dd>
<dt><kbd>dpmgr remove <var>name</var></kbd></dt>
<dd>Remove a database file.</dd>
<dt><kbd>dpmgr repair <var>name</var></kbd></dt>
<dd>Repair a broken database file.</dd>
<dt><kbd>dpmgr exportdb <var>name</var> <var>file</var></kbd></dt>
<dd>Dump all records as endian independent data.</dd>
<dt><kbd>dpmgr importdb [-bnum <var>num</var>] <var>name</var> <var>file</var></kbd></dt>
<dd>Load all records from endian independent data.</dd>
<dt><kbd>dpmgr snaffle [-kx|-ki] [-ox] [-n] <var>name</var> <var>key</var></kbd></dt>
<dd>Retrieve a record from a locked database with a key and output it to the standard output.</dd>
<dt><kbd>dpmgr version</kbd></dt>
<dd>Output version information of QDBM to the standard output.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-s</kbd> : make the file sparse.</li>
<li><kbd>-bnum <var>num</var></kbd> : specify the number of the elements of the bucket array.</li>
<li><kbd>-kx</kbd> : treat `key' as a binary expression of hexadecimal notation.</li>
<li><kbd>-ki</kbd> : treat `key' as an integer expression of decimal notation.</li>
<li><kbd>-vx</kbd> : treat `val' as a binary expression of hexadecimal notation.</li>
<li><kbd>-vi</kbd> : treat `val' as an integer expression of decimal notation.</li>
<li><kbd>-vf</kbd> : read the value from a file specified with `val'.</li>
<li><kbd>-keep</kbd> : specify the storing mode for `DP_DKEEP'.</li>
<li><kbd>-cat</kbd> : specify the storing mode for `DP_DCAT'.</li>
<li><kbd>-na</kbd> : do not set alignment.</li>
<li><kbd>-nl</kbd> : open the database without file locking.</li>
<li><kbd>-start</kbd> : specify the beginning offset of a value to fetch.</li>
<li><kbd>-max</kbd> : specify the max size of a value to fetch.</li>
<li><kbd>-ox</kbd> : treat the output as a binary expression of hexadecimal notation.</li>
<li><kbd>-n</kbd> : do not output the tailing newline.</li>
<li><kbd>-k</kbd> : output keys only.</li>
<li><kbd>-v</kbd> : output values only.</li>
</ul>

<p>This command returns 0 on success, another on failure.  The environment variable `QDBMDBGFD' specifies the file descriptor to output the history of updating the variable `dpecode'.</p>

<p>The command `dptest' is a utility for facility test and performance test.  Check a database generated by the command or measure the execution time of the command.  This command is used in the following format.  `name' specifies a database name.  `rnum' specifies the number of the records.  `bnum' specifies the number of the elements of the bucket array.  `pnum' specifies the number of patterns of the keys.  `align' specifies the basic size of alignment.  `fbpsiz' specifies the size of the free block pool.</p>

<dl>
<dt><kbd>dptest write [-s] <var>name</var> <var>rnum</var> <var>bnum</var></kbd></dt>
<dd>Store records with keys of 8 bytes.  They change as `00000001', `00000002'...</dd>
<dt><kbd>dptest read [-wb] <var>name</var></kbd></dt>
<dd>Retrieve all records of the database above.</dd>
<dt><kbd>dptest rcat [-c] <var>name</var> <var>rnum</var> <var>bnum</var> <var>pnum</var> <var>align</var> <var>fbpsiz</var></kbd></dt>
<dd>Store records with partway duplicated keys using concatenate mode.</dd>
<dt><kbd>dptest combo <var>name</var></kbd></dt>
<dd>Perform combination test of various operations.</dd>
<dt><kbd>dptest wicked [-c] <var>name</var> <var>rnum</var></kbd></dt>
<dd>Perform updating operations selected at random.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-s</kbd> : make the file sparse.</li>
<li><kbd>-wb</kbd> : use the function `dpgetwb' instead of the function `dpget'.</li>
<li><kbd>-c</kbd> : perform comparison test with map of Cabin.</li>
</ul>

<p>This command returns 0 on success, another on failure.  The environment variable `QDBMDBGFD' specifies the file descriptor to output the history of updating the variable `dpecode'.</p>

<p>The command `dptsv' features mutual conversion between a database of Depot and a TSV text.  This command is useful when data exchange with another version of QDBM or another DBM, or when data exchange between systems which have different byte orders.  This command is used in the following format.  `name' specifies a database name.  The subcommand `export' reads TSV data from the standard input.  If a key overlaps, the latter is adopted.  `-bnum' specifies the number of the elements of the bucket array.  The subcommand `import' writes TSV data to the standard output.</p>

<dl>
<dt><kbd>dptsv import [-bnum <var>num</var>] [-bin] <var>name</var></kbd></dt>
<dd>Create a database from TSV.</dd>
<dt><kbd>dptsv export [-bin] <var>name</var></kbd></dt>
<dd>Write TSV data of a database.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-bnum <var>num</var></kbd> : specify the number of the elements of the bucket array.</li>
<li><kbd>-bin</kbd> : treat records as Base64 format.</li>
</ul>

<p>This command returns 0 on success, another on failure.</p>

<p>Commands of Depot realize a simple database system.  For example, to make a database to search `/etc/password' by a user name, perform the following command.</p>

<pre>cat /etc/passwd | tr ':' '\t' | dptsv import casket
</pre>

<p>Thus, to retrieve the information of a user `mikio', perform the following command.</p>

<pre>dpmgr get casket mikio
</pre>

<p>It is easy to implement functions upsides with these commands, using the API of Depot.</p>

<hr />

<h2><a name="curiaapi" id="curiaapi" class="head">Curia: Extended API</a></h2>

<h3>Overview</h3>

<p>Curia is the extended API of QDBM.  It provides routines for managing multiple database files in a directory.  Restrictions of some file systems that the size of each file is limited are escaped by dividing a database file into two or more.  If the database files deploy on multiple devices, the scalability is improved.</p>

<p>Although Depot creates a database with a file name, Curia creates a database with a directory name.  A database file named as `depot' is placed in the specified directory.  Although it keeps the attribute of the database, it does not keep the entities of the records.  Besides, sub directories are created by the number of division of the database, named with 4 digits.  The database files are placed in the subdirectories.  The entities of the records are stored in the database file.  For example, in the case that a database directory named as `casket' and the number of division is 3, `casket/depot', `casket/0001/depot', `casket/0002/depot' and `casket/0003/depot' are created.  No error occurs even if the namesake directory exists when creating a database.  So, if sub directories exists and some devices are mounted on the sub directories, the database files deploy on the multiple devices.</p>

<p>Curia features managing large objects.  Although usual records are stored in some database files, records of large objects are stored in individual files.  Because the files of large objects are deployed in different directories named with the hash values, the access speed is part-way robust although it is slower than the speed of usual records.  Large and not often accessed data should be secluded as large objects.  By doing this, the access speed of usual records is improved.  The directory hierarchies of large objects are placed in the directory named as `lob' in the sub directories of the database.  Because the key spaces of the usual records and the large objects are different, the operations keep out of each other.</p>

<p>In order to use Curia, you should include `depot.h', `curia.h' and `stdlib.h' in the source files.  Usually, the following description will be near the beginning of a source file.</p>

<dl>
<dt><kbd>#include &lt;depot.h&gt;</kbd></dt>
<dt><kbd>#include &lt;curia.h&gt;</kbd></dt>
<dt><kbd>#include &lt;stdlib.h&gt;</kbd></dt>
</dl>

<p>A pointer to `CURIA' is used as a database handle.  It is like that some file I/O routines of `stdio.h' use a pointer to `FILE'.  A database handle is opened with the function `cropen' and closed with `crclose'.  You should not refer directly to any member of the handle.  If a fatal error occurs in a database, any access method via the handle except `crclose' will not work and return error status.  Although a process is allowed to use multiple database handles at the same time, handles of the same database directory should not be used.</p>

<p>Curia also assign the external variable `dpecode' with the error code.  The function `dperrmsg' is used in order to get the message of the error code.</p>

<h3>API</h3>

<p>The function `cropen' is used in order to get a database handle.</p>

<dl>
<dt><kbd>CURIA *cropen(const char *<var>name</var>, int <var>omode</var>, int <var>bnum</var>, int <var>dnum</var>);</kbd></dt>
<dd>`name' specifies the name of a database directory.  `omode' specifies the connection mode: `CR_OWRITER' as a writer, `CR_OREADER' as a reader.  If the mode is `CR_OWRITER', the following may be added by bitwise or: `CR_OCREAT', which means it creates a new database if not exist, `CR_OTRUNC', which means it creates a new database regardless if one exists.  Both of `CR_OREADER' and `CR_OWRITER' can be added to by bitwise or: `CR_ONOLCK', which means it opens a database directory without file locking, or `CR_OLCKNB', which means locking is performed without blocking.  `CR_OCREAT' can be added to by bitwise or: `CR_OSPARSE', which means it creates database files as sparse files.  `bnum' specifies the number of elements of each bucket array.  If it is not more than 0, the default value is specified.  The size of each bucket array is determined on creating, and can not be changed except for by optimization of the database.  Suggested size of each bucket array is about from 0.5 to 4 times of the number of all records to store.  `dnum' specifies the number of division of the database.  If it is not more than 0, the default value is specified.  The number of division can not be changed from the initial value.  The max number of division is 512.  The return value is the database handle or `NULL' if it is not successful.  While connecting as a writer, an exclusive lock is invoked to the database directory.  While connecting as a reader, a shared lock is invoked to the database directory.  The thread blocks until the lock is achieved.  If `CR_ONOLCK' is used, the application is responsible for exclusion control.</dd>
</dl>

<p>The function `crclose' is used in order to close a database handle.</p>

<dl>
<dt><kbd>int crclose(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  If successful, the return value is true, else, it is false.  Because the region of a closed handle is released, it becomes impossible to use the handle.  Updating a database is assured to be written when the handle is closed.  If a writer opens a database but does not close it appropriately, the database will be broken.</dd>
</dl>

<p>The function `crput' is used in order to store a record.</p>

<dl>
<dt><kbd>int crput(CURIA *<var>curia</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, const char *<var>vbuf</var>, int <var>vsiz</var>, int <var>dmode</var>);</kbd></dt>
<dd>`curia' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `vbuf' specifies the pointer to the region of a value.  `vsiz' specifies the size of the region of the value.  If it is negative, the size is assigned with `strlen(vbuf)'.  `dmode' specifies behavior when the key overlaps, by the following values: `CR_DOVER', which means the specified value overwrites the existing one, `CR_DKEEP', which means the existing value is kept, `CR_DCAT', which means the specified value is concatenated at the end of the existing value.  If successful, the return value is true, else, it is false.</dd>
</dl>

<p>The function `crout' is used in order to delete a record.</p>

<dl>
<dt><kbd>int crout(CURIA *<var>curia</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`curia' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is true, else, it is false.  False is returned when no record corresponds to the specified key.</dd>
</dl>

<p>The function `crget' is used in order to retrieve a record.</p>

<dl>
<dt><kbd>char *crget(CURIA *<var>curia</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int <var>start</var>, int <var>max</var>, int *<var>sp</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `start' specifies the offset address of the beginning of the region of the value to be read.  `max' specifies the max size to be read.  If it is negative, the size to read is unlimited.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the value of the corresponding record, else, it is `NULL'.  `NULL' is returned when no record corresponds to the specified key or the size of the value of the corresponding record is less than `start'.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `crgetwb' is used in order to retrieve a record and write the value into a buffer.</p>

<dl>
<dt><kbd>int crgetwb(CURIA *<var>curia</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int <var>start</var>, int <var>max</var>, char *<var>vbuf</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `start' specifies the offset address of the beginning of the region of the value to be read.  `max' specifies the max size to be read.  It shuld be equal to or less than the size of the writing buffer.  `vbuf' specifies the pointer to a buffer into which the value of the corresponding record is written.  If successful, the return value is the size of the written data, else, it is -1.  -1 is returned when no record corresponds to the specified key or the size of the value of the corresponding record is less than `start'.  Note that no additional zero code is appended at the end of the region of the writing buffer.</dd>
</dl>

<p>The function `crvsiz' is used in order to get the size of the value of a record.</p>

<dl>
<dt><kbd>int crvsiz(CURIA *<var>curia</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is the size of the value of the corresponding record, else, it is -1.  Because this function does not read the entity of a record, it is faster than `crget'.</dd>
</dl>

<p>The function `criterinit' is used in order to initialize the iterator of a database handle.</p>

<dl>
<dt><kbd>int criterinit(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  If successful, the return value is true, else, it is false.  The iterator is used in order to access the key of every record stored in a database.</dd>
</dl>

<p>The function `criternext' is used in order to get the next key of the iterator.</p>

<dl>
<dt><kbd>char *criternext(CURIA *<var>curia</var>, int *<var>sp</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the next key, else, it is `NULL'.  `NULL' is returned when no record is to be get out of the iterator.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  It is possible to access every record by iteration of calling this function.  However, it is not assured if updating the database is occurred while the iteration.  Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.</dd>
</dl>

<p>The function `crsetalign' is used in order to set alignment of a database handle.</p>

<dl>
<dt><kbd>int crsetalign(CURIA *<var>curia</var>, int <var>align</var>);</kbd></dt>
<dd>`curia' specifies a database handle connected as a writer.  `align' specifies the size of alignment.  If successful, the return value is true, else, it is false.  If alignment is set to a database, the efficiency of overwriting values is improved.  The size of alignment is suggested to be average size of the values of the records to be stored.  If alignment is positive, padding whose size is multiple number of the alignment is placed.  If alignment is negative, as `vsiz' is the size of a value, the size of padding is calculated with `(vsiz / pow(2, abs(align) - 1))'.  Because alignment setting is not saved in a database, you should specify alignment every opening a database.</dd>
</dl>

<p>The function `crsetfbpsiz' is used in order to set the size of the free block pool of a database handle.</p>

<dl>
<dt><kbd>int crsetfbpsiz(CURIA *<var>curia</var>, int <var>size</var>);</kbd></dt>
<dd>`curia' specifies a database handle connected as a writer.  `size' specifies the size of the free block pool of a database.  If successful, the return value is true, else, it is false.  The default size of the free block pool is 16.  If the size is greater, the space efficiency of overwriting values is improved with the time efficiency sacrificed.</dd>
</dl>

<p>The function `crsync' is used in order to synchronize updating contents with the files and the devices.</p>

<dl>
<dt><kbd>int crsync(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle connected as a writer.  If successful, the return value is true, else, it is false.  This function is useful when another process uses the connected database directory.</dd>
</dl>

<p>The function `croptimize' is used in order to optimize a database.</p>

<dl>
<dt><kbd>int croptimize(CURIA *<var>curia</var>, int <var>bnum</var>);</kbd></dt>
<dd>`curia' specifies a database handle connected as a writer.  `bnum' specifies the number of the elements of each bucket array.  If it is not more than 0, the default value is specified.  In an alternating succession of deleting and storing with overwrite or concatenate, dispensable regions accumulate.  This function is useful to do away with them.</dd>
</dl>

<p>The function `crname' is used in order to get the name of a database.</p>

<dl>
<dt><kbd>char *crname(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  If successful, the return value is the pointer to the region of the name of the database, else, it is `NULL'.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `crfsiz' is used in order to get the total size of database files.</p>

<dl>
<dt><kbd>int crfsiz(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  If successful, the return value is the total size of the database files, else, it is -1.  If the total size is more than 2GB, the return value overflows.</dd>
</dl>

<p>The function `crfsizd' is used in order to get the total size of database files as double-precision floating-point number.</p>

<dl>
<dt><kbd>double crfsizd(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  If successful, the return value is the total size of the database files, else, it is -1.0.</dd>
</dl>

<p>The function `crbnum' is used in order to get the total number of the elements of each bucket array.</p>

<dl>
<dt><kbd>int crbnum(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  If successful, the return value is the total number of the elements of each bucket array, else, it is -1.</dd>
</dl>

<p>The function `crbusenum' is used in order to get the total number of the used elements of each bucket array.</p>

<dl>
<dt><kbd>int crbusenum(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  If successful, the return value is the total number of the used elements of each bucket array, else, it is -1.  This function is inefficient because it accesses all elements of each bucket array.</dd>
</dl>

<p>The function `crrnum' is used in order to get the number of the records stored in a database.</p>

<dl>
<dt><kbd>int crrnum(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  If successful, the return value is the number of the records stored in the database, else, it is -1.</dd>
</dl>

<p>The function `crwritable' is used in order to check whether a database handle is a writer or not.</p>

<dl>
<dt><kbd>int crwritable(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  The return value is true if the handle is a writer, false if not.</dd>
</dl>

<p>The function `crfatalerror' is used in order to check whether a database has a fatal error or not.</p>

<dl>
<dt><kbd>int crfatalerror(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  The return value is true if the database has a fatal error, false if not.</dd>
</dl>

<p>The function `crinode' is used in order to get the inode number of a database directory.</p>

<dl>
<dt><kbd>int crinode(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  The return value is the inode number of the database directory.</dd>
</dl>

<p>The function `crmtime' is used in order to get the last modified time of a database.</p>

<dl>
<dt><kbd>time_t crmtime(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  The return value is the last modified time of the database.</dd>
</dl>

<p>The function `crremove' is used in order to remove a database directory.</p>

<dl>
<dt><kbd>int crremove(const char *<var>name</var>);</kbd></dt>
<dd>`name' specifies the name of a database directory.  If successful, the return value is true, else, it is false.</dd>
</dl>

<p>The function `crrepair' is used in order to repair a broken database directory.</p>

<dl>
<dt><kbd>int crrepair(const char *<var>name</var>);</kbd></dt>
<dd>`name' specifies the name of a database directory.  If successful, the return value is true, else, it is false.  There is no guarantee that all records in a repaired database directory correspond to the original or expected state.</dd>
</dl>

<p>The function `crexportdb' is used in order to dump all records as endian independent data.</p>

<dl>
<dt><kbd>int crexportdb(CURIA *<var>curia</var>, const char *<var>name</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  `name' specifies the name of an output directory.  If successful, the return value is true, else, it is false.  Note that large objects are ignored.</dd>
</dl>

<p>The function `crimportdb' is used in order to load all records from endian independent data.</p>

<dl>
<dt><kbd>int crimportdb(CURIA *<var>curia</var>, const char *<var>name</var>);</kbd></dt>
<dd>`curia' specifies a database handle connected as a writer.  The database of the handle must be empty.  `name' specifies the name of an input directory.  If successful, the return value is true, else, it is false.  Note that large objects are ignored.</dd>
</dl>

<p>The function `crsnaffle' is used in order to retrieve a record directly from a database directory.</p>

<dl>
<dt><kbd>char *crsnaffle(const char *<var>name</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int *<var>sp</var>);</kbd></dt>
<dd>`name' specifies the name of a database directory.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the value of the corresponding record, else, it is `NULL'.  `NULL' is returned when no record corresponds to the specified key.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  Although this function can be used even while the database directory is locked by another process, it is not assured that recent updated is reflected.</dd>
</dl>

<p>The function `crputlob' is used in order to store a large object.</p>

<dl>
<dt><kbd>int crputlob(CURIA *<var>curia</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, const char *<var>vbuf</var>, int <var>vsiz</var>, int <var>dmode</var>);</kbd></dt>
<dd>`curia' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `vbuf' specifies the pointer to the region of a value.  `vsiz' specifies the size of the region of the value.  If it is negative, the size is assigned with `strlen(vbuf)'.  `dmode' specifies behavior when the key overlaps, by the following values: `CR_DOVER', which means the specified value overwrites the existing one, `CR_DKEEP', which means the existing value is kept, `CR_DCAT', which means the specified value is concatenated at the end of the existing value.  If successful, the return value is true, else, it is false.</dd>
</dl>

<p>The function `croutlob' is used in order to delete a large object.</p>

<dl>
<dt><kbd>int croutlob(CURIA *<var>curia</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`curia' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is true, else, it is false.  false is returned when no large object corresponds to the specified key.</dd>
</dl>

<p>The function `crgetlob' is used in order to retrieve a large object.</p>

<dl>
<dt><kbd>char *crgetlob(CURIA *<var>curia</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int <var>start</var>, int <var>max</var>, int *<var>sp</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `start' specifies the offset address of the beginning of the region of the value to be read.  `max' specifies the max size to be read.  If it is negative, the size to read is unlimited.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the value of the corresponding large object, else, it is `NULL'.  `NULL' is returned when no large object corresponds to the specified key or the size of the value of the corresponding large object is less than `start'.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `crgetlobfd' is used in order to get the file descriptor of a large object.</p>

<dl>
<dt><kbd>int crgetlobfd(CURIA *<var>curia</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is the file descriptor of the corresponding large object, else, it is -1.  -1 is returned when no large object corresponds to the specified key.  The returned file descriptor is opened with the `open' call.  If the database handle was opened as a writer, the descriptor is writable (O_RDWR), else, it is not writable (O_RDONLY).  The descriptor should be closed with the `close' call if it is no longer in use.</dd>
</dl>

<p>The function `crvsizlob' is used in order to get the size of the value of a large object.</p>

<dl>
<dt><kbd>int crvsizlob(CURIA *<var>curia</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is the size of the value of the corresponding large object, else, it is -1.  Because this function does not read the entity of a large object, it is faster than `crgetlob'.</dd>
</dl>

<p>The function `crrnumlob' is used in order to get the number of the large objects stored in a database.</p>

<dl>
<dt><kbd>int crrnumlob(CURIA *<var>curia</var>);</kbd></dt>
<dd>`curia' specifies a database handle.  If successful, the return value is the number of the large objects stored in the database, else, it is -1.</dd>
</dl>

<h3>Examples</h3>

<p>The following example stores and retrieves a phone number, using the name as the key.</p>

<pre>#include &lt;depot.h&gt;
#include &lt;curia.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;

#define NAME     "mikio"
#define NUMBER   "000-1234-5678"
#define DBNAME   "book"

int main(int argc, char **argv){
  CURIA *curia;
  char *val;

  /* open the database */
  if(!(curia = cropen(DBNAME, CR_OWRITER | CR_OCREAT, -1, -1))){
    fprintf(stderr, "cropen: %s\n", dperrmsg(dpecode));
    return 1;
  }

  /* store the record */
  if(!crput(curia, NAME, -1, NUMBER, -1, CR_DOVER)){
    fprintf(stderr, "crput: %s\n", dperrmsg(dpecode));
  }

  /* retrieve the record */
  if(!(val = crget(curia, NAME, -1, 0, -1, NULL))){
    fprintf(stderr, "crget: %s\n", dperrmsg(dpecode));
  } else {
    printf("Name: %s\n", NAME);
    printf("Number: %s\n", val);
    free(val);
  }

  /* close the database */
  if(!crclose(curia)){
    fprintf(stderr, "crclose: %s\n", dperrmsg(dpecode));
    return 1;
  }

  return 0;
}
</pre>

<p>The following example shows all records of the database.</p>

<pre>#include &lt;depot.h&gt;
#include &lt;curia.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;

#define DBNAME   "book"

int main(int argc, char **argv){
  CURIA *curia;
  char *key, *val;

  /* open the database */
  if(!(curia = cropen(DBNAME, CR_OREADER, -1, -1))){
    fprintf(stderr, "cropen: %s\n", dperrmsg(dpecode));
    return 1;
  }

  /* initialize the iterator */
  if(!criterinit(curia)){
    fprintf(stderr, "criterinit: %s\n", dperrmsg(dpecode));
  }

  /* scan with the iterator */
  while((key = criternext(curia, NULL)) != NULL){
    if(!(val = crget(curia, key, -1, 0, -1, NULL))){
      fprintf(stderr, "crget: %s\n", dperrmsg(dpecode));
      free(key);
      break;
    }
    printf("%s: %s\n", key, val);
    free(val);
    free(key);
  }

  /* close the iterator */
  if(!crclose(curia)){
    fprintf(stderr, "crclose: %s\n", dperrmsg(dpecode));
    return 1;
  }

  return 0;
}
</pre>

<h3>Notes</h3>

<p>How to build programs using Curia is the same as the case of Depot.</p>

<pre>gcc -I/usr/local/include -o sample sample.c -L/usr/local/lib -lqdbm
</pre>

<p>If QDBM was built with POSIX thread enabled, the global variable `dpecode' is treated as thread specific data, and functions of Curia are reentrant.  In that case, they are thread-safe as long as a handle is not accessed by threads at the same time, on the assumption that `errno', `malloc', and so on are thread-safe.</p>

<hr />

<h2><a name="curiacli" id="curiacli" class="head">Commands for Curia</a></h2>

<p>Curia has the following command line interfaces.</p>

<p>The command `crmgr' is a utility for debugging Curia and its applications.  It features editing and checking of a database.  It can be used for the database applications with shell scripts.  This command is used in the following format.  `name' specifies a database name.  `key' specifies the key of a record.  `val' specifies the value of a record.</p>

<dl>
<dt><kbd>crmgr create [-s] [-bnum <var>num</var>] [-dnum <var>num</var>] <var>name</var></kbd></dt>
<dd>Create a database file.</dd>
<dt><kbd>crmgr put [-kx|-ki] [-vx|-vi|-vf] [-keep|-cat] [-lob] [-na] <var>name</var> <var>key</var> <var>val</var></kbd></dt>
<dd>Store a record with a key and a value.</dd>
<dt><kbd>crmgr out [-kx|-ki] [-lob] <var>name</var> <var>key</var></kbd></dt>
<dd>Delete a record with a key.</dd>
<dt><kbd>crmgr get [-nl] [-kx|-ki] [-start <var>num</var>] [-max <var>num</var>] [-ox] [-lob] [-n] <var>name</var> <var>key</var></kbd></dt>
<dd>Retrieve a record with a key and output it to the standard output.</dd>
<dt><kbd>crmgr list [-nl] [-k|-v] [-ox] <var>name</var></kbd></dt>
<dd>List all keys and values delimited with tab and line-feed to the standard output.</dd>
<dt><kbd>crmgr optimize [-bnum <var>num</var>] [-na] <var>name</var></kbd></dt>
<dd>Optimize a database.</dd>
<dt><kbd>crmgr inform [-nl] <var>name</var></kbd></dt>
<dd>Output miscellaneous information to the standard output.</dd>
<dt><kbd>crmgr remove <var>name</var></kbd></dt>
<dd>Remove a database directory.</dd>
<dt><kbd>crmgr repair <var>name</var></kbd></dt>
<dd>Repair a broken database directory.</dd>
<dt><kbd>crmgr exportdb <var>name</var> <var>dir</var></kbd></dt>
<dd>Dump all records as endian independent data.</dd>
<dt><kbd>crmgr importdb [-bnum <var>num</var>] [-dnum <var>num</var>] <var>name</var> <var>dir</var></kbd></dt>
<dd>Load all records from endian independent data.</dd>
<dt><kbd>crmgr snaffle [-kx|-ki] [-ox] [-n] <var>name</var> <var>key</var></kbd></dt>
<dd>Retrieve a record from a locked database with a key and output it to the standard output.</dd>
<dt><kbd>crmgr version</kbd></dt>
<dd>Output version information of QDBM to the standard output.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-s</kbd> : make the files sparse.</li>
<li><kbd>-bnum <var>num</var></kbd> : specify the number of elements of each bucket array.</li>
<li><kbd>-dnum <var>num</var></kbd> : specify the number of division of the database.</li>
<li><kbd>-kx</kbd> : treat `key' as a binary expression of hexadecimal notation.</li>
<li><kbd>-ki</kbd> : treat `key' as an integer expression of decimal notation.</li>
<li><kbd>-vx</kbd> : treat `val' as a binary expression of hexadecimal notation.</li>
<li><kbd>-vi</kbd> : treat `val' as an integer expression of decimal notation.</li>
<li><kbd>-vf</kbd> : read the value from a file specified with `val'.</li>
<li><kbd>-keep</kbd> : specify the storing mode for `CR_DKEEP'.</li>
<li><kbd>-cat</kbd> : specify the storing mode for `CR_DCAT'.</li>
<li><kbd>-na</kbd> : do not set alignment.</li>
<li><kbd>-nl</kbd> : open the database without file locking.</li>
<li><kbd>-start</kbd> : specify the beginning offset of a value to fetch.</li>
<li><kbd>-max</kbd> : specify the max size of a value to fetch.</li>
<li><kbd>-ox</kbd> : treat the output as a binary expression of hexadecimal notation.</li>
<li><kbd>-lob</kbd> : handle large objects.</li>
<li><kbd>-n</kbd> : do not output the tailing newline.</li>
<li><kbd>-k</kbd> : output keys only.</li>
<li><kbd>-v</kbd> : output values only.</li>
</ul>

<p>This command returns 0 on success, another on failure.  The environment variable `QDBMDBGFD' specifies the file descriptor to output the history of updating the variable `dpecode'.</p>

<p>The command `crtest' is a utility for facility test and performance test.  Check a database generated by the command or measure the execution time of the command.  This command is used in the following format.  `name' specifies a database name.  `rnum' specifies the number of records.  `bnum' specifies the number of elements of a bucket array.  `dnum' specifies the number of division of a database.  `pnum' specifies the number of patterns of the keys.  `align' specifies the basic size of alignment.  `fbpsiz' specifies the size of the free block pool.</p>

<dl>
<dt><kbd>crtest write [-s] [-lob] <var>name</var> <var>rnum</var> <var>bnum</var> <var>dnum</var></kbd></dt>
<dd>Store records with keys of 8 bytes.  They change as `00000001', `00000002'...</dd>
<dt><kbd>crtest read [-wb] [-lob] <var>name</var></kbd></dt>
<dd>Retrieve all records of the database above.</dd>
<dt><kbd>crtest rcat [-c] <var>name</var> <var>rnum</var> <var>bnum</var> <var>dnum</var> <var>pnum</var> <var>align</var> <var>fbpsiz</var></kbd></dt>
<dd>Store records with partway duplicated keys using concatenate mode.</dd>
<dt><kbd>crtest combo <var>name</var></kbd></dt>
<dd>Perform combination test of various operations.</dd>
<dt><kbd>crtest wicked [-c] <var>name</var> <var>rnum</var></kbd></dt>
<dd>Perform updating operations selected at random.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-s</kbd> : make the files sparse.</li>
<li><kbd>-lob</kbd> : handle large objects.</li>
<li><kbd>-wb</kbd> : use the function `crgetwb' instead of the function `crget'.</li>
<li><kbd>-c</kbd> : perform comparison test with map of Cabin.</li>
</ul>

<p>This command returns 0 on success, another on failure.  The environment variable `QDBMDBGFD' specifies the file descriptor to output the history of updating the variable `dpecode'.</p>

<p>The command `crtsv' features mutual conversion between a database of Curia and a TSV text.  This command is useful when data exchange with another version of QDBM or another DBM, or when data exchange between systems which have different byte orders.  This command is used in the following format.  `name' specifies a database name.  The subcommand `export' reads TSV data from the standard input.  If a key overlaps, the latter is adopted.  `-bnum' specifies the number of the elements of the bucket array.  `-dnum' specifies the number of division of the database.  The subcommand `import' writes TSV data to the standard output.</p>

<dl>
<dt><kbd>crtsv import [-bnum <var>num</var>] [-dnum <var>num</var>] [-bin] <var>name</var></kbd></dt>
<dd>Create a database from TSV.</dd>
<dt><kbd>crtsv export [-bin] <var>name</var></kbd></dt>
<dd>Write TSV data of a database.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-bnum <var>num</var></kbd> : specify the number of the elements of the bucket array.</li>
<li><kbd>-dnum <var>num</var></kbd> : specify the number of division of the database.</li>
<li><kbd>-bin</kbd> : treat records as Base64 format.</li>
</ul>

<p>This command returns 0 on success, another on failure.</p>

<p>Commands of Curia realize a simple database system.  For example, to make a database to search `/etc/password' by a user name, perform the following command.</p>

<pre>cat /etc/passwd | tr ':' '\t' | crtsv import casket
</pre>

<p>Thus, to retrieve the information of a user `mikio', perform the following command.</p>

<pre>crmgr get casket mikio
</pre>

<p>It is easy to implement functions upsides with these commands, using the API of Curia.</p>

<hr />

<h2><a name="relicapi" id="relicapi" class="head">Relic: NDBM-compatible API</a></h2>

<h3>Overview</h3>

<p>Relic is the API which is compatible with NDBM.  So, Relic wraps functions of Depot as API of NDBM.  It is easy to port an application from NDBM to QDBM.  In most cases, you should only replace the includings of `ndbm.h' with `relic.h' and replace the linking option `-lndbm' with `-lqdbm'.</p>

<p>The original NDBM treats a database as a pair of files.  One, `a directory file', has a name with suffix `.dir' and stores a bit map of keys.  The other, `a data file', has a name with suffix `.pag' and stores entities of each records.  Relic creates the directory file as a mere dummy file and creates the data file as a database.  Relic has no restriction about the size of each record.  Relic can not handle database files made by the original NDBM.</p>

<p>In order to use Relic, you should include `relic.h', `stdlib.h', `sys/types.h', `sys/stat.h' and `fcntl.h' in the source files.  Usually, the following description will be near the beginning of a source file.</p>

<dl>
<dt><kbd>#include &lt;relic.h&gt;</kbd></dt>
<dt><kbd>#include &lt;stdlib.h&gt;</kbd></dt>
<dt><kbd>#include &lt;sys/types.h&gt;</kbd></dt>
<dt><kbd>#include &lt;sys/stat.h&gt;</kbd></dt>
<dt><kbd>#include &lt;fcntl.h&gt;</kbd></dt>
</dl>

<p>A pointer to `DBM' is used as a database handle.  A database handle is opened with the function `dbm_open' and closed with `dbm_close'.  You should not refer directly to any member of a handle.</p>

<h3>API</h3>

<p>Structures of `datum' type is used in order to give and receive data of keys and values with functions of Relic.</p>

<dl>
<dt><kbd>typedef struct { void *dptr; size_t dsize; } datum;</kbd></dt>
<dd>`dptr' specifies the pointer to the region of a key or a value. `dsize' specifies the size of the region.</dd>
</dl>

<p>The function `dbm_open' is used in order to get a database handle.</p>

<dl>
<dt><kbd>DBM *dbm_open(char *<var>name</var>, int <var>flags</var>, int <var>mode</var>);</kbd></dt>
<dd>`name' specifies the name of a database.  The file names are concatenated with suffixes.  `flags' is the same as the one of `open' call, although `O_WRONLY' is treated as `O_RDWR' and additional flags except for `O_CREAT' and `O_TRUNC' have no effect.  `mode' specifies the mode of the database file as the one of `open' call does.  The return value is the database handle or `NULL' if it is not successful.</dd>
</dl>

<p>The function `dbm_close' is used in order to close a database handle.</p>

<dl>
<dt><kbd>void dbm_close(DBM *<var>db</var>);</kbd></dt>
<dd>`db' specifies a database handle.  Because the region of the closed handle is released, it becomes impossible to use the handle.</dd>
</dl>

<p>The function `dbm_store' is used in order to store a record.</p>

<dl>
<dt><kbd>int dbm_store(DBM *<var>db</var>, datum <var>key</var>, datum <var>content</var>, int <var>flags</var>);</kbd></dt>
<dd>`db' specifies a database handle.  `key' specifies a structure of a key.  `content' specifies a structure of a value.  `flags' specifies behavior when the key overlaps, by the following values: `DBM_REPLACE', which means the specified value overwrites the existing one, `DBM_INSERT', which means the existing value is kept.  The return value is 0 if it is successful, 1 if it gives up because of overlaps of the key, -1 if other error occurs.</dd>
</dl>

<p>The function `dbm_delete' is used in order to delete a record.</p>

<dl>
<dt><kbd>int dbm_delete(DBM *<var>db</var>, datum <var>key</var>);</kbd></dt>
<dd>`db' specifies a database handle.  `key' specifies a structure of a key.  The return value is 0 if it is successful, -1 if some errors occur.</dd>
</dl>

<p>The function `dbm_fetch' is used in order to retrieve a record.</p>

<dl>
<dt><kbd>datum dbm_fetch(DBM *<var>db</var>, datum <var>key</var>);</kbd></dt>
<dd>`db' specifies a database handle.  `key' specifies a structure of a key.  The return value is a structure of the result.  If a record corresponds, the member `dptr' of the structure is the pointer to the region of the value.  If no record corresponds or some errors occur, `dptr' is `NULL'.  `dptr' points to the region related with the handle.  The region is available until the next time of calling this function with the same handle.</dd>
</dl>

<p>The function `dbm_firstkey' is used in order to get the first key of a database.</p>

<dl>
<dt><kbd>datum dbm_firstkey(DBM *<var>db</var>);</kbd></dt>
<dd>`db' specifies a database handle.  The return value is a structure of the result.  If a record corresponds, the member `dptr' of the structure is the pointer to the region of the first key.  If no record corresponds or some errors occur, `dptr' is `NULL'.  `dptr' points to the region related with the handle.  The region is available until the next time of calling this function or the function `dbm_nextkey' with the same handle.</dd>
</dl>

<p>The function `dbm_nextkey' is used in order to get the next key of a database.</p>

<dl>
<dt><kbd>datum dbm_nextkey(DBM *<var>db</var>);</kbd></dt>
<dd>`db' specifies a database handle.  The return value is a structure of the result.  If a record corresponds, the member `dptr' of the structure is the pointer to the region of the next key.  If no record corresponds or some errors occur, `dptr' is `NULL'.  `dptr' points to the region related with the handle.  The region is available until the next time of calling this function or the function `dbm_firstkey' with the same handle.</dd>
</dl>

<p>The function `dbm_error' is used in order to check whether a database has a fatal error or not.</p>

<dl>
<dt><kbd>int dbm_error(DBM *<var>db</var>);</kbd></dt>
<dd>`db' specifies a database handle.  The return value is true if the database has a fatal error, false if not.</dd>
</dl>

<p>The function `dbm_clearerr' has no effect.</p>

<dl>
<dt><kbd>int dbm_clearerr(DBM *<var>db</var>);</kbd></dt>
<dd>`db' specifies a database handle.  The return value is 0.  The function is only for compatibility.</dd>
</dl>

<p>The function `dbm_rdonly' is used in order to check whether a handle is read-only or not.</p>

<dl>
<dt><kbd>int dbm_rdonly(DBM *<var>db</var>);</kbd></dt>
<dd>`db' specifies a database handle.  The return value is true if the handle is read-only, or false if not read-only.</dd>
</dl>

<p>The function `dbm_dirfno' is used in order to get the file descriptor of a directory file.</p>

<dl>
<dt><kbd>int dbm_dirfno(DBM *<var>db</var>);</kbd></dt>
<dd>`db' specifies a database handle.  The return value is the file descriptor of the directory file.</dd>
</dl>

<p>The function `dbm_pagfno' is used in order to get the file descriptor of a data file.</p>

<dl>
<dt><kbd>int dbm_pagfno(DBM *<var>db</var>);</kbd></dt>
<dd>`db' specifies a database handle.  The return value is the file descriptor of the data file.</dd>
</dl>

<h3>Examples</h3>

<p>The following example stores and retrieves a phone number, using the name as the key.</p>

<pre>#include &lt;relic.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;sys/stat.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;

#define NAME     "mikio"
#define NUMBER   "000-1234-5678"
#define DBNAME   "book"

int main(int argc, char **argv){
  DBM *db;
  datum key, val;
  int i;

  /* open the database */
  if(!(db = dbm_open(DBNAME, O_RDWR | O_CREAT, 00644))){
    perror("dbm_open");
    return 1;
  }

  /* prepare the record */
  key.dptr = NAME;
  key.dsize = strlen(NAME);
  val.dptr = NUMBER;
  val.dsize = strlen(NUMBER);

  /* store the record */
  if(dbm_store(db, key, val, DBM_REPLACE) != 0){
    perror("dbm_store");
  }

  /* retrieve the record */
  val = dbm_fetch(db, key);
  if(val.dptr){
    printf("Name: %s\n", NAME);
    printf("Number: ");
    for(i = 0; i &lt; val.dsize; i++){
      putchar(((char *)val.dptr)[i]);
    }
    putchar('\n');
  } else {
    perror("dbm_fetch");
  }

  /* close the database */
  dbm_close(db);

  return 0;
}
</pre>

<h3>Notes</h3>

<p>How to build programs using Relic is the same as the case of Depot.  Note that an option to be given to a linker is not `-lndbm', but `-lqdbm'.</p>

<pre>gcc -I/usr/local/include -o sample sample.c -L/usr/local/lib -lqdbm
</pre>

<p>Functions of Relic are thread-safe as long as a handle is not accessed by threads at the same time, on the assumption that `errno', `malloc', and so on are thread-safe.</p>

<hr />

<h2><a name="reliccli" id="reliccli" class="head">Commands for Relic</a></h2>

<p>Relic has the following command line interfaces.</p>

<p>The command `rlmgr' is a utility for debugging Relic and its applications.  It features editing and checking of a database.  It can be used for database applications with shell scripts.  This command is used in the following format.  `name' specifies a database name.  `key' specifies the key of a record.  `val' specifies the value of a record.</p>

<dl>
<dt><kbd>rlmgr create <var>name</var></kbd></dt>
<dd>Create a database file.</dd>
<dt><kbd>rlmgr store [-kx] [-vx|-vf] [-insert] <var>name</var> <var>key</var> <var>val</var></kbd></dt>
<dd>Store a record with a key and a value.</dd>
<dt><kbd>rlmgr delete [-kx] <var>name</var> <var>key</var></kbd></dt>
<dd>Delete a record with a key.</dd>
<dt><kbd>rlmgr fetch [-kx] [-ox] [-n] <var>name</var> <var>key</var></kbd></dt>
<dd>Retrieve a record with a key and output to the standard output.</dd>
<dt><kbd>rlmgr list [-ox] <var>name</var></kbd></dt>
<dd>List all keys and values delimited with tab and line-feed to the standard output.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-kx</kbd> : treat `key' as a binary expression of hexadecimal notation.</li>
<li><kbd>-vx</kbd> : treat `val' as a binary expression of hexadecimal notation.</li>
<li><kbd>-vf</kbd> : read the value from a file specified with `val'.</li>
<li><kbd>-insert</kbd> : specify the storing mode for `DBM_INSERT'.</li>
<li><kbd>-ox</kbd> : treat the output as a binary expression of hexadecimal notation.</li>
<li><kbd>-n</kbd> : do not output the tailing newline.</li>
</ul>

<p>This command returns 0 on success, another on failure.</p>

<p>The command `rltest' is a utility for facility test and performance test.  Check a database generated by the command or measure the execution time of the command.  This command is used in the following format.  `name' specifies a database name.  `rnum' specifies the number of records.</p>

<dl>
<dt><kbd>rltest write <var>name</var> <var>rnum</var></kbd></dt>
<dd>Store records with keys of 8 bytes.  They change as `00000001', `00000002'...</dd>
<dt><kbd>rltest read <var>name</var> <var>rnum</var></kbd></dt>
<dd>Retrieve records of the database above.</dd>
</dl>

<p>This command returns 0 on success, another on failure.</p>

<hr />

<h2><a name="hovelapi" id="hovelapi" class="head">Hovel: GDBM-compatible API</a></h2>

<h3>Overview</h3>

<p>Hovel is the API which is compatible with GDBM.  So, Hovel wraps functions of Depot and Curia as API of GDBM.  It is easy to port an application from GDBM to QDBM.  In most cases, you should only replace the includings of `gdbm.h' with `hovel.h' and replace the linking option `-lgdbm' with `-lqdbm'.  Hovel can not handle database files made by the original GDBM.</p>

<p>In order to use Hovel, you should include `hovel.h', `stdlib.h', `sys/types.h' and `sys/stat.h' in the source files.  Usually, the following description will be near the beginning of a source file.</p>

<dl>
<dt><kbd>#include &lt;hovel.h&gt;</kbd></dt>
<dt><kbd>#include &lt;stdlib.h&gt;</kbd></dt>
<dt><kbd>#include &lt;sys/types.h&gt;</kbd></dt>
<dt><kbd>#include &lt;sys/stat.h&gt;</kbd></dt>
</dl>

<p>An object of `GDBM_FILE' is used as a database handle.  A database handle is opened with the function `gdbm_open' and closed with `gdbm_close'.  You should not refer directly to any member of a handle.  Although Hovel works as a wrapper of Depot and handles a database file usually, if you use the function `gdbm_open2' to open the handle, it is possible to make behavior of a handle as a wrapper of Curia and treat a database directory.</p>

<h3>API</h3>

<p>Structures of `datum' type is used in order to give and receive data of keys and values with functions of Hovel.</p>

<dl>
<dt><kbd>typedef struct { char *dptr; size_t dsize; } datum;</kbd></dt>
<dd>`dptr' specifies the pointer to the region of a key or a value.  `dsize' specifies the size of the region.</dd>
</dl>

<p>The external variable `gdbm_version' is the string containing the version information.</p>

<dl>
<dt><kbd>extern char *gdbm_version;</kbd></dt>
</dl>

<p>The external variable `gdbm_errno' is assigned with the last happened error code.  Refer to `hovel.h' for details of the error codes.</p>

<dl>
<dt><kbd>extern gdbm_error gdbm_errno;</kbd></dt>
<dd>The initial value of this variable is `GDBM_NO_ERROR'.  The other values are `GDBM_MALLOC_ERROR', `GDBM_BLOCK_SIZE_ERROR', `GDBM_FILE_OPEN_ERROR', `GDBM_FILE_WRITE_ERROR', `GDBM_FILE_SEEK_ERROR', `GDBM_FILE_READ_ERROR', `GDBM_BAD_MAGIC_NUMBER', `GDBM_EMPTY_DATABASE', `GDBM_CANT_BE_READER', `GDBM_CANT_BE_WRITER', `GDBM_READER_CANT_DELETE', `GDBM_READER_CANT_STORE', `GDBM_READER_CANT_REORGANIZE', `GDBM_UNKNOWN_UPDATE', `GDBM_ITEM_NOT_FOUND', `GDBM_REORGANIZE_FAILED', `GDBM_CANNOT_REPLACE', `GDBM_ILLEGAL_DATA', `GDBM_OPT_ALREADY_SET', and `GDBM_OPT_ILLEGAL'.</dd>
</dl>

<p>The function `gdbm_strerror' is used in order to get a message string corresponding to an error code.</p>

<dl>
<dt><kbd>char *gdbm_strerror(gdbm_error <var>gdbmerrno</var>);</kbd></dt>
<dd>`gdbmerrno' specifies an error code.  The return value is the message string of the error code.  The region of the return value is not writable.</dd>
</dl>

<p>The function `gdbm_open' is used in order to get a database handle after the fashion of GDBM.</p>

<dl>
<dt><kbd>GDBM_FILE gdbm_open(char *<var>name</var>, int <var>block_size</var>, int <var>read_write</var>, int <var>mode</var>, void (*<var>fatal_func</var>)(void));</kbd></dt>
<dd>`name' specifies the name of a database.  `block_size' is ignored.  `read_write' specifies the connection mode: `GDBM_READER' as a reader, `GDBM_WRITER', `GDBM_WRCREAT' and `GDBM_NEWDB' as a writer.  `GDBM_WRCREAT' makes a database file or directory if it does not exist.  `GDBM_NEWDB' makes a new database even if it exists.  You can add the following to writer modes by bitwise or: `GDBM_SYNC', `GDBM_NOLOCK', `GDBM_LOCKNB', `GDBM_FAST', and `GDBM_SPARSE'.  `GDBM_SYNC' means a database is synchronized after every updating method.  `GDBM_NOLOCK' means a database is opened without file locking.  `GDBM_LOCKNB' means file locking is performed without blocking.  `GDBM_FAST' is ignored.  `GDBM_SPARSE' is an original mode of QDBM and makes database a sparse file.  `mode' specifies mode of a database file as the one of `open' call does.  `fatal_func' is ignored.  The return value is the database handle or `NULL' if it is not successful.</dd>
</dl>

<p>The function `gdbm_open2' is used in order to get a database handle after the fashion of QDBM.</p>

<dl>
<dt><kbd>GDBM_FILE gdbm_open2(char *<var>name</var>, int <var>read_write</var>, int <var>mode</var>, int <var>bnum</var>, int <var>dnum</var>, int <var>align</var>);</kbd></dt>
<dd>`name' specifies the name of a database.  `read_write' specifies the connection mode: `GDBM_READER' as a reader, `GDBM_WRITER', `GDBM_WRCREAT' and `GDBM_NEWDB' as a writer.  `GDBM_WRCREAT' makes a database file or directory if it does not exist.  `GDBM_NEWDB' makes a new database even if it exists.  You can add the following to writer modes by bitwise or: `GDBM_SYNC', `GDBM_NOLOCK', 'GDBM_LOCKNB', `GDBM_FAST', and `GDBM_SPARSE'.  `GDBM_SYNC' means a database is synchronized after every updating method.  `GDBM_NOLOCK' means a database is opened without file locking.  `GDBM_LOCKNB' means file locking is performed without blocking.  `GDBM_FAST' is ignored.  `GDBM_SPARSE' is an original mode of QDBM and makes database sparse files.  `mode' specifies a mode of a database file or a database directory as the one of `open' or `mkdir' call does.  `bnum' specifies the number of elements of each bucket array.  If it is not more than 0, the default value is specified.  `dnum' specifies the number of division of the database.  If it is not more than 0, the returning handle is created as a wrapper of Depot, else, it is as a wrapper of Curia.  `align' specifies the basic size of alignment.  The return value is the database handle or `NULL' if it is not successful.  If the database already exists, whether it is one of Depot or Curia is measured automatically.</dd>
</dl>

<p>The function `gdbm_close' is used in order to close a database handle.</p>

<dl>
<dt><kbd>void gdbm_close(GDBM_FILE <var>dbf</var>);</kbd></dt>
<dd>`dbf' specifies a database handle.  Because the region of the closed handle is released, it becomes impossible to use the handle.</dd>
</dl>

<p>The function `gdbm_store' is used in order to store a record.</p>

<dl>
<dt><kbd>int gdbm_store(GDBM_FILE <var>dbf</var>, datum <var>key</var>, datum <var>content</var>, int <var>flag</var>);</kbd></dt>
<dd>`dbf' specifies a database handle connected as a writer.  `key' specifies a structure of a key.  `content' specifies a structure of a value.  `flag' specifies behavior when the key overlaps, by the following values: `GDBM_REPLACE', which means the specified value overwrites the existing one, `GDBM_INSERT', which means the existing value is kept.  The return value is 0 if it is successful, 1 if it gives up because of overlaps of the key, -1 if other error occurs.</dd>
</dl>

<p>The function `gdbm_delete' is used in order to delete a record.</p>

<dl>
<dt><kbd>int gdbm_delete(GDBM_FILE <var>dbf</var>, datum <var>key</var>);</kbd></dt>
<dd>`dbf' specifies a database handle connected as a writer.  `key' specifies a structure of a key.  The return value is 0 if it is successful, -1 if some errors occur.</dd>
</dl>

<p>The function `gdbm_fetch' is used in order to retrieve a record.</p>

<dl>
<dt><kbd>datum gdbm_fetch(GDBM_FILE <var>dbf</var>, datum <var>key</var>);</kbd></dt>
<dd>`dbf' specifies a database handle.  `key' specifies a structure of a key.  The return value is a structure of the result.  If a record corresponds, the member `dptr' of the structure is the pointer to the region of the value.  If no record corresponds or some errors occur, `dptr' is `NULL'.  Because the region pointed to by `dptr' is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `gdbm_exists' is used in order to check whether a record exists or not.</p>

<dl>
<dt><kbd>int gdbm_exists(GDBM_FILE <var>dbf</var>, datum <var>key</var>);</kbd></dt>
<dd>`dbf' specifies a database handle.  `key' specifies a structure of a key.  The return value is true if a record corresponds and no error occurs, or false, else, it is false.</dd>
</dl>

<p>The function `gdbm_firstkey' is used in order to get the first key of a database.</p>

<dl>
<dt><kbd>datum gdbm_firstkey(GDBM_FILE <var>dbf</var>);</kbd></dt>
<dd>`dbf' specifies a database handle.  The return value is a structure of the result.  If a record corresponds, the member `dptr' of the structure is the pointer to the region of the first key.  If no record corresponds or some errors occur, `dptr' is `NULL'.  Because the region pointed to by `dptr' is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `gdbm_nextkey' is used in order to get the next key of a database.</p>

<dl>
<dt><kbd>datum gdbm_nextkey(GDBM_FILE <var>dbf</var>, datum <var>key</var>);</kbd></dt>
<dd>`dbf' specifies a database handle.  The return value is a structure of the result.  If a record corresponds, the member `dptr' of the structure is the pointer to the region of the next key.  If no record corresponds or some errors occur, `dptr' is `NULL'.  Because the region pointed to by `dptr' is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `gdbm_sync' is used in order to synchronize updating contents with the file and the device.</p>

<dl>
<dt><kbd>void gdbm_sync(GDBM_FILE <var>dbf</var>);</kbd></dt>
<dd>`dbf' specifies a database handle connected as a writer.</dd>
</dl>

<p>The function `gdbm_reorganize' is used in order to reorganize a database.</p>

<dl>
<dt><kbd>int gdbm_reorganize(GDBM_FILE <var>dbf</var>);</kbd></dt>
<dd>`dbf' specifies a database handle connected as a writer.  If successful, the return value is 0, else -1.</dd>
</dl>

<p>The function `gdbm_fdesc' is used in order to get the file descriptor of a database file.</p>

<dl>
<dt><kbd>int gdbm_fdesc(GDBM_FILE <var>dbf</var>);</kbd></dt>
<dd>`dbf' specifies a database handle connected as a writer.  The return value is the file descriptor of the database file.  If the database is a directory the return value is -1.</dd>
</dl>

<p>The function `gdbm_setopt' has no effect.</p>

<dl>
<dt><kbd>int gdbm_setopt(GDBM_FILE <var>dbf</var>, int <var>option</var>, int *<var>value</var>, int <var>size</var>);</kbd></dt>
<dd>`dbf' specifies a database handle.  `option' is ignored.  `size' is ignored.  The return value is 0.  The function is only for compatibility.</dd>
</dl>

<h3>Examples</h3>

<p>The following example stores and retrieves a phone number, using the name as the key.</p>

<pre>#include &lt;hovel.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;sys/types.h&gt;
#include &lt;sys/stat.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;

#define NAME     "mikio"
#define NUMBER   "000-1234-5678"
#define DBNAME   "book"

int main(int argc, char **argv){
  GDBM_FILE dbf;
  datum key, val;
  int i;

  /* open the database */
  if(!(dbf = gdbm_open(DBNAME, 0, GDBM_WRCREAT, 00644, NULL))){
    fprintf(stderr, "gdbm_open: %s\n", gdbm_strerror(gdbm_errno));
    return 1;
  }

  /* prepare the record */
  key.dptr = NAME;
  key.dsize = strlen(NAME);
  val.dptr = NUMBER;
  val.dsize = strlen(NUMBER);

  /* store the record */
  if(gdbm_store(dbf, key, val, GDBM_REPLACE) != 0){
    fprintf(stderr, "gdbm_store: %s\n", gdbm_strerror(gdbm_errno));
  }

  /* retrieve the record */
  val = gdbm_fetch(dbf, key);
  if(val.dptr){
    printf("Name: %s\n", NAME);
    printf("Number: ");
    for(i = 0; i &lt; val.dsize; i++){
      putchar(val.dptr[i]);
    }
    putchar('\n');
    free(val.dptr);
  } else {
    fprintf(stderr, "gdbm_fetch: %s\n", gdbm_strerror(gdbm_errno));
  }

  /* close the database */
  gdbm_close(dbf);

  return 0;
}
</pre>

<h3>Notes</h3>

<p>How to build programs using Hovel is the same as the case of Depot.  Note that an option to be given to a linker is not `-lgdbm', but `-lqdbm'.</p>

<pre>gcc -I/usr/local/include -o sample sample.c -L/usr/local/lib -lqdbm
</pre>

<p>If QDBM was built with POSIX thread enabled, the global variable `gdbm_errno' is treated as thread specific data, and functions of Hovel are reentrant.  In that case, they are thread-safe as long as a handle is not accessed by threads at the same time, on the assumption that `errno', `malloc', and so on are thread-safe.</p>

<hr />

<h2><a name="hovelcli" id="hovelcli" class="head">Commands for Hovel</a></h2>

<p>Hovel has the following command line interfaces.</p>

<p>The command `hvmgr' is a utility for debugging Hovel and its applications.  It features editing and checking of a database.  It can be used for database applications with shell scripts.  This command is used in the following format.  `name' specifies a database name.  `key' specifies the key of a record.  `val' specifies the value of a record.</p>

<dl>
<dt><kbd>hvmgr create [-qdbm bnum dnum] [-s] <var>name</var></kbd></dt>
<dd>Create a database file.</dd>
<dt><kbd>hvmgr store [-qdbm] [-kx] [-vx|-vf] [-insert] <var>name</var> <var>key</var> <var>val</var></kbd></dt>
<dd>Store a record with a key and a value.</dd>
<dt><kbd>hvmgr delete [-qdbm] [-kx] <var>name</var> <var>key</var></kbd></dt>
<dd>Delete a record with a key.</dd>
<dt><kbd>hvmgr fetch [-qdbm] [-kx] [-ox] [-n] <var>name</var> <var>key</var></kbd></dt>
<dd>Retrieve a record with a key and output to the standard output.</dd>
<dt><kbd>hvmgr list [-qdbm] [-ox] <var>name</var></kbd></dt>
<dd>List all keys and values delimited with tab and line-feed to the standard output.</dd>
<dt><kbd>hvmgr optimize [-qdbm] <var>name</var></kbd></dt>
<dd>Optimize a database.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-qdbm [<var>bnum</var> <var>dnum</var>]</kbd> : use `gdbm_open2' to open the database.  `bnum' specifies the number of the elements of the bucket array.  `dnum' specifies the number of division of the database.</li>
<li><kbd>-s</kbd> : make the file sparse.</li>
<li><kbd>-kx</kbd> : treat `key' as a binary expression of hexadecimal notation.</li>
<li><kbd>-vx</kbd> : treat `val' as a binary expression of hexadecimal notation.</li>
<li><kbd>-vf</kbd> : read the value from a file specified with `val'.</li>
<li><kbd>-insert</kbd> : specify the storing mode for `GDBM_INSERT'.</li>
<li><kbd>-ox</kbd> : treat the output as a binary expression of hexadecimal notation.</li>
<li><kbd>-n</kbd> : do not output the trailing newline.</li>
</ul>

<p>This command returns 0 on success, another on failure.</p>

<p>The command `hvtest' is a utility for facility test and performance test.  Check a database generated by the command or measure the execution time of the command.  This command is used in the following format.  `name' specifies a database name.  `rnum' specifies the number of records.</p>

<dl>
<dt><kbd>hvtest write [-qdbm] [-s] <var>name</var> <var>rnum</var></kbd></dt>
<dd>Store records with keys of 8 bytes.  They changes as `00000001', `00000002'...</dd>
<dt><kbd>hvtest read [-qdbm] <var>name</var> <var>rnum</var></kbd></dt>
<dd>Retrieve records of the database above.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-qdbm</kbd> : use `gdbm_open2' and open the handle as Curia.</li>
<li><kbd>-s</kbd> : make the file sparse.</li>
</ul>

<p>This command returns 0 on success, another on failure.</p>

<hr />

<h2><a name="cabinapi" id="cabinapi" class="head">Cabin: Utility API</a></h2>

<h3>Overview</h3>

<p>Cabin is the utility API which provides memory allocating functions, sorting functions, extensible datum, array list, hash map, heap array, and so on for handling records easily on memory.  This API features also parsing MIME, CSV, and XML, and features various types of encoding and decoding.</p>

<p>In order to use Cabin, you should include `cabin.h' and `stdlib.h' in the source files.  Usually, the following description will be near the beginning of a source file.</p>

<dl>
<dt><kbd>#include &lt;cabin.h&gt;</kbd></dt>
<dt><kbd>#include &lt;stdlib.h&gt;</kbd></dt>
</dl>

<p>A pointer to `CBDATUM' is used as a handle of an extensible datum.  A datum handle is opened with the function `cbdatumopen' and closed with `cbdatumclose'.  A pointer to `CBLIST' is used as a handle of an array list.  A list handle is opened with the function `cblistopen' and closed with `cblistclose'.  A pointer to `CBMAP' is used as a handle of a hash map.  A map handle is opened with the function `cbmapopen' and closed with `cbmapclose'.  A pointer to `CBHEAP' is used as a handle of a heap array.  A heap handle is opened with the function `cbheapopen' and closed with `cbheapclose'.  You should not refer directly to any member of each handles.</p>

<h3>API</h3>

<p>The external variable `cbfatalfunc' is the pointer to call back function for handling a fatal error.</p>

<dl>
<dt><kbd>extern void (*cbfatalfunc)(const char *);</kbd></dt>
<dd>The argument specifies the error message.  The initial value of this variable is `NULL'.  If the value is `NULL', the default function is called when a fatal error occurs.  A fatal error occurs when memory allocation is failed.</dd>
</dl>

<p>The function `cbmalloc' is used in order to allocate a region on memory.</p>

<dl>
<dt><kbd>void *cbmalloc(size_t <var>size</var>);</kbd></dt>
<dd>`size' specifies the size of the region.  The return value is the pointer to the allocated region.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbrealloc' is used in order to re-allocate a region on memory.</p>

<dl>
<dt><kbd>void *cbrealloc(void *<var>ptr</var>, size_t <var>size</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  The return value is the pointer to the re-allocated region.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbmemdup' is used in order to duplicate a region on memory.</p>

<dl>
<dt><kbd>char *cbmemdup(const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  The return value is the pointer to the allocated region of the duplicate.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbfree' is used in order to free a region on memory.</p>

<dl>
<dt><kbd>void cbfree(void *<var>ptr</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  If it is `NULL', this function has no effect.  Although this function is just a wrapper of `free' call, this is useful in applications using another package of the `malloc' series.</dd>
</dl>

<p>The function `cbglobalgc' is used in order to register the pointer or handle of an object to the global garbage collector.</p>

<dl>
<dt><kbd>void cbglobalgc(void *<var>ptr</var>, void (*<var>func</var>)(void *));</kbd></dt>
<dd>`ptr' specifies the pointer or handle of an object.  `func' specifies the pointer to a function to release resources of the object.  Its argument is the pointer or handle of the object to release.  This function assures that resources of an object are released when the process exits normally by returning from the `main' function or calling the `exit' function.</dd>
</dl>

<p>The function `cbggcsweep' is used in order to exercise the global garbage collector explicitly.</p>

<dl>
<dt><kbd>void cbggcsweep(void);</kbd></dt>
<dd>Note that you should not use objects registered to the global garbage collector any longer after calling this function.  Because the global garbage collector is initialized and you can register new objects into it.</dd>
</dl>

<p>The function `cbvmemavail' is used in order to check availability of allocation of the virtual memory.</p>

<dl>
<dt><kbd>int cbvmemavail(size_t <var>size</var>);</kbd></dt>
<dd>`size' specifies the size of region to be allocated newly.  The return value is true if allocation should be success, or false if not.</dd>
</dl>

<p>The function `cbisort' is used in order to sort an array using insert sort.</p>

<dl>
<dt><kbd>void cbisort(void *<var>base</var>, int <var>nmemb</var>, int <var>size</var>, int(*<var>compar</var>)(const void *, const void *));</kbd></dt>
<dd>`base' specifies the pointer to an array.  `nmemb' specifies the number of elements of the array.  `size' specifies the size of each element.  `compar' specifies the pointer to comparing function.  The two arguments specify the pointers of elements.  The comparing function should returns positive if the former is big, negative if the latter is big, 0 if both are equal.  Insert sort is useful only if most elements have been sorted already.</dd>
</dl>

<p>The function `cbssort' is used in order to sort an array using shell sort.</p>

<dl>
<dt><kbd>void cbssort(void *<var>base</var>, int <var>nmemb</var>, int <var>size</var>, int(*<var>compar</var>)(const void *, const void *));</kbd></dt>
<dd>`base' specifies the pointer to an array.  `nmemb' specifies the number of elements of the array.  `size' specifies the size of each element.  `compar' specifies the pointer to comparing function.  The two arguments specify the pointers of elements.  The comparing function should returns positive if the former is big, negative if the latter is big, 0 if both are equal.  If most elements have been sorted, shell sort may be faster than heap sort or quick sort.</dd>
</dl>

<p>The function `cbhsort' is used in order to sort an array using heap sort.</p>

<dl>
<dt><kbd>void cbhsort(void *<var>base</var>, int <var>nmemb</var>, int <var>size</var>, int(*<var>compar</var>)(const void *, const void *));</kbd></dt>
<dd>`base' specifies the pointer to an array.  `nmemb' specifies the number of elements of the array.  `size' specifies the size of each element. `compar' specifies the pointer to comparing function.  The two arguments specify the pointers of elements.  The comparing function should returns positive if the former is big, negative if the latter is big, 0 if both are equal.  Although heap sort is robust against bias of input, quick sort is faster in most cases.</dd>
</dl>

<p>The function `cbqsort' is used in order to sort an array using quick sort.</p>

<dl>
<dt><kbd>void cbqsort(void *<var>base</var>, int <var>nmemb</var>, int <var>size</var>, int(*<var>compar</var>)(const void *, const void *));</kbd></dt>
<dd>`base' specifies the pointer to an array.  `nmemb' specifies the number of elements of the array.  `size' specifies the size of each element. `compar' specifies the pointer to comparing function.  The two arguments specify the pointers of elements.  The comparing function should returns positive if the former is big, negative if the latter is big, 0 if both are equal.  Being sensitive to bias of input, quick sort is the fastest sorting algorithm.</dd>
</dl>

<p>The function `cbstricmp' is used in order to compare two strings with case insensitive evaluation.</p>

<dl>
<dt><kbd>int cbstricmp(const char *<var>astr</var>, const char *<var>bstr</var>);</kbd></dt>
<dd>`astr' specifies the pointer of one string.  `astr' specifies the pointer of the other string.  The return value is positive if the former is big, negative if the latter is big, 0 if both are equivalent.  Upper cases and lower cases of alphabets in ASCII code are not distinguished.</dd>
</dl>

<p>The function `cbstrfwmatch' is used in order to check whether a string begins with a key.</p>

<dl>
<dt><kbd>int cbstrfwmatch(const char *<var>str</var>, const char *<var>key</var>);</kbd></dt>
<dd>`str' specifies the pointer of a target string.  `key' specifies the pointer of a forward matching key string.  The return value is true if the target string begins with the key, else, it is false.</dd>
</dl>

<p>The function `cbstrfwimatch' is used in order to check whether a string begins with a key, with case insensitive evaluation.</p>

<dl>
<dt><kbd>int cbstrfwimatch(const char *<var>str</var>, const char *<var>key</var>);</kbd></dt>
<dd>`str' specifies the pointer of a target string.  `key' specifies the pointer of a forward matching key string.  The return value is true if the target string begins with the key, else, it is false.  Upper cases and lower cases of alphabets in ASCII code are not distinguished.</dd>
</dl>

<p>The function `cbstrbwmatch' is used in order to check whether a string ends with a key.</p>

<dl>
<dt><kbd>int cbstrbwmatch(const char *<var>str</var>, const char *<var>key</var>);</kbd></dt>
<dd>`str' specifies the pointer of a target string.  `key' specifies the pointer of a backward matching key string.  The return value is true if the target string ends with the key, else, it is false.</dd>
</dl>

<p>The function `cbstrbwimatch' is used in order to check whether a string ends with a key, with case insensitive evaluation.</p>

<dl>
<dt><kbd>int cbstrbwimatch(const char *<var>str</var>, const char *<var>key</var>);</kbd></dt>
<dd>`str' specifies the pointer of a target string.  `key' specifies the pointer of a backward matching key string.  The return value is true if the target string ends with the key, else, it is false.  Upper cases and lower cases of alphabets in ASCII code are not distinguished.</dd>
</dl>

<p>The function `cbstrstrkmp' is used in order to locate a substring in a string using KMP method.</p>

<dl>
<dt><kbd>char *cbstrstrkmp(const char *<var>haystack</var>, const char *<var>needle</var>);</kbd></dt>
<dd>`haystack' specifies the pointer of a target string.  `needle' specifies the pointer of a substring to be found.  The return value is the pointer to the beginning of the substring or `NULL' if the substring is not found.  In most cases, `strstr' as a built-in function of the compiler is faster than this function.</dd>
</dl>

<p>The function `cbstrstrkmp' is used in order to locate a substring in a string using BM method.</p>

<dl>
<dt><kbd>char *cbstrstrbm(const char *<var>haystack</var>, const char *<var>needle</var>);</kbd></dt>
<dd>`haystack' specifies the pointer of a target string.  `needle' specifies the pointer of a substring to be found.  The return value is the pointer to the beginning of the substring or `NULL' if the substring is not found.  In most cases, `strstr' as a built-in function of the compiler is faster than this function.</dd>
</dl>

<p>The function `cbstrtoupper' is used in order to convert the letters of a string to upper case.</p>

<dl>
<dt><kbd>char *cbstrtoupper(char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer of a string to convert.  The return value is the pointer to the string.</dd>
</dl>

<p>The function `cbstrtolower' is used in order to convert the letters of a string to lower case.</p>

<dl>
<dt><kbd>char *cbstrtolower(char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer of a string to convert.  The return value is the pointer to the string.</dd>
</dl>

<p>The function `cbstrtrim' is used in order to cut space characters at head or tail of a string.</p>

<dl>
<dt><kbd>char *cbstrtrim(char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer of a string to convert.  The return value is the pointer to the string.</dd>
</dl>

<p>The function `cbstrsqzspc' is used in order to squeeze space characters in a string and trim it.</p>

<dl>
<dt><kbd>char *cbstrsqzspc(char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer of a string to convert.  The return value is the pointer to the string.</dd>
</dl>

<p>The function `cbstrcountutf' is used in order to count the number of characters in a string of UTF-8.</p>

<dl>
<dt><kbd>int cbstrcountutf(const char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer of a string of UTF-8.  The return value is the number of characters in the string.</dd>
</dl>

<p>The function `cbstrcututf' is used in order to cut a string of UTF-8 at the specified number of characters.</p>

<dl>
<dt><kbd>char *cbstrcututf(char *<var>str</var>, int <var>num</var>);</kbd></dt>
<dd>`str' specifies the pointer of a string of UTF-8.  `num' specifies the number of characters to be kept.  The return value is the pointer to the string.</dd>
</dl>

<p>The function `cbdatumopen' is used in order to get a datum handle.</p>

<dl>
<dt><kbd>CBDATUM *cbdatumopen(const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to the region of the initial content.  If it is `NULL', an empty datum is created.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  The return value is a datum handle.</dd>
</dl>

<p>The function `cbdatumdup' is used in order to copy a datum.</p>

<dl>
<dt><kbd>CBDATUM *cbdatumdup(const CBDATUM *<var>datum</var>);</kbd></dt>
<dd>`datum' specifies a datum handle.  The return value is a new datum handle.</dd>
</dl>

<p>The function `cbdatumclose' is used in order to free a datum handle.</p>

<dl>
<dt><kbd>void cbdatumclose(CBDATUM *<var>datum</var>);</kbd></dt>
<dd>`datum' specifies a datum handle.  Because the region of a closed handle is released, it becomes impossible to use the handle.</dd>
</dl>

<p>The function `cbdatumcat' is used in order to concatenate a datum and a region.</p>

<dl>
<dt><kbd>void cbdatumcat(CBDATUM *<var>datum</var>, const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`datum' specifies a datum handle.  `ptr' specifies the pointer to the region to be appended.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.</dd>
</dl>

<p>The function `cbdatumptr' is used in order to get the pointer of the region of a datum.</p>

<dl>
<dt><kbd>const char *cbdatumptr(const CBDATUM *<var>datum</var>);</kbd></dt>
<dd>`datum' specifies a datum handle.  The return value is the pointer of the region of a datum.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.</dd>
</dl>

<p>The function `cbdatumsize' is used in order to get the size of the region of a datum.</p>

<dl>
<dt><kbd>int cbdatumsize(const CBDATUM *<var>datum</var>);</kbd></dt>
<dd>`datum' specifies a datum handle.  The return value is the size of the region of a datum.</dd>
</dl>

<p>The function `cbdatumsetsize' is used in order to change the size of the region of a datum.</p>

<dl>
<dt><kbd>void cbdatumsetsize(CBDATUM *<var>datum</var>, int <var>size</var>);</kbd></dt>
<dd>`datum' specifies a datum handle.  `size' specifies the new size of the region.  If the new size is bigger than the one of old, the surplus region is filled with zero codes.</dd>
</dl>

<p>The function `cbdatumprintf' is used in order to perform formatted output into a datum.</p>

<dl>
<dt><kbd>void cbdatumprintf(CBDATUM *<var>datum</var>, const char *<var>format</var>, ...);</kbd></dt>
<dd>`format' specifies a printf-like format string.  The conversion character `%' can be used with such flag characters as `s', `d', `o', `u', `x', `X', `c', `e', `E', `f', `g', `G', `@', `?', `:', `%'.  `@' works as with `s' but escapes meta characters of XML.  `?' works as with `s' but escapes meta characters of URL.  `:' works as with `s' but performs MIME encoding as UTF-8.  The other conversion character work as with each original.</dd>
</dl>

<p>The function `cbdatumtomalloc' is used in order to convert a datum to an allocated region.</p>

<dl>
<dt><kbd>char *cbdatumtomalloc(CBDATUM *<var>datum</var>, int *<var>sp</var>);</kbd></dt>
<dd>`datum' specifies a datum handle.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the region of the datum.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  Because the region of the original datum is released, it should not be released again.</dd>
</dl>

<p>The function `cblistopen' is used in order to get a list handle.</p>

<dl>
<dt><kbd>CBLIST *cblistopen(void);</kbd></dt>
<dd>The return value is a list handle.</dd>
</dl>

<p>The function `cblistdup' is used in order to copy a list.</p>

<dl>
<dt><kbd>CBLIST *cblistdup(const CBLIST *<var>list</var>);</kbd></dt>
<dd>`list' specifies a list handle.  The return value is a new list handle.</dd>
</dl>

<p>The function `cblistclose' is used in order to close a list handle.</p>

<dl>
<dt><kbd>void cblistclose(CBLIST *<var>list</var>);</kbd></dt>
<dd>`list' specifies a list handle.  Because the region of a closed handle is released, it becomes impossible to use the handle.</dd>
</dl>

<p>The function `cblistnum' is used in order to get the number of elements of a list.</p>

<dl>
<dt><kbd>int cblistnum(const CBLIST *<var>list</var>);</kbd></dt>
<dd>`list' specifies a list handle.  The return value is the number of elements of the list.</dd>
</dl>

<p>The function `cblistval' is used in order to get the pointer to the region of an element of a list.</p>

<dl>
<dt><kbd>const char *cblistval(const CBLIST *<var>list</var>, int <var>index</var>, int *<var>sp</var>);</kbd></dt>
<dd>`list' specifies a list handle.  `index' specifies the index of an element.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the region of the element.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  If `index' is equal to or more than the number of elements, the return value is `NULL'.</dd>
</dl>

<p>The function `cblistpush' is used in order to add an element at the end of a list.</p>

<dl>
<dt><kbd>void cblistpush(CBLIST *<var>list</var>, const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`list' specifies a list handle.  `ptr' specifies the pointer to the region of an element.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.</dd>
</dl>

<p>The function `cblistpop' is used in order to remove an element of the end of a list.</p>

<dl>
<dt><kbd>char *cblistpop(CBLIST *<var>list</var>, int *<var>sp</var>);</kbd></dt>
<dd>`list' specifies a list handle.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the region of the value.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  If the list is empty, the return value is `NULL'.</dd>
</dl>

<p>The function `cblistunshift' is used in order to add an element at the top of a list.</p>

<dl>
<dt><kbd>void cblistunshift(CBLIST *<var>list</var>, const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`list' specifies a list handle.  `ptr' specifies the pointer to the region of an element.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.</dd>
</dl>

<p>The function `cblistshift' is used in order to remove an element of the top of a list.</p>

<dl>
<dt><kbd>char *cblistshift(CBLIST *<var>list</var>, int *<var>sp</var>);</kbd></dt>
<dd>`list' specifies a list handle.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the region of the value.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  If the list is empty, the return value is `NULL'.</dd>
</dl>

<p>The function `cblistinsert' is used in order to add an element at the specified location of a list.</p>

<dl>
<dt><kbd>void cblistinsert(CBLIST *<var>list</var>, int <var>index</var>, const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`list' specifies a list handle.  `index' specifies the index of an element.  `ptr' specifies the pointer to the region of the element.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.</dd>
</dl>

<p>The function `cblistremove' is used in order to remove an element at the specified location of a list.</p>

<dl>
<dt><kbd>char *cblistremove(CBLIST *<var>list</var>, int <var>index</var>, int *<var>sp</var>);</kbd></dt>
<dd>`list' specifies a list handle.  `index' specifies the index of an element.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the region of the value.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  If `index' is equal to or more than the number of elements, no element is removed and the return value is `NULL'.</dd>
</dl>

<p>The function `cblistover' is used in order to overwrite an element at the specified location of a list.</p>

<dl>
<dt><kbd>void cblistover(CBLIST *<var>list</var>, int <var>index</var>, const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`list' specifies a list handle.  `index' specifies the index of an element.  `ptr' specifies the pointer to the region of the new content.  `size' specifies the size of the new content.  If it is negative, the size is assigned with `strlen(ptr)'.  If `index' is equal to or more than the number of elements, this function has no effect.</dd>
</dl>

<p>The function `cblistsort' is used in order to sort elements of a list in lexical order.</p>

<dl>
<dt><kbd>void cblistsort(CBLIST *<var>list</var>);</kbd></dt>
<dd>`list' specifies a list handle.  Quick sort is used for sorting.</dd>
</dl>

<p>The function `cblistlsearch' is used in order to search a list for an element using liner search.</p>

<dl>
<dt><kbd>int cblistlsearch(const CBLIST *<var>list</var>, const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`list' specifies a list handle.  `ptr' specifies the pointer to the region of a key.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  The return value is the index of a corresponding element or -1 if there is no corresponding element.  If two or more elements corresponds, the former returns.</dd>
</dl>

<p>The function `cblistbsearch' is used in order to search a list for an element using binary search.</p>

<dl>
<dt><kbd>int cblistbsearch(const CBLIST *<var>list</var>, const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`list' specifies a list handle.  It should be sorted in lexical order.  `ptr' specifies the pointer to the region of a key.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  The return value is the index of a corresponding element or -1 if there is no corresponding element.  If two or more elements corresponds, which returns is not defined.</dd>
</dl>

<p>The function `cblistdump' is used in order to serialize a list into a byte array.</p>

<dl>
<dt><kbd>char *cblistdump(const CBLIST *<var>list</var>, int *<var>sp</var>);</kbd></dt>
<dd>`list' specifies a list handle.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  The return value is the pointer to the region of the result serial region.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cblistload' is used in order to redintegrate a serialized list.</p>

<dl>
<dt><kbd>CBLIST *cblistload(const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a byte array.  `size' specifies the size of the region.  The return value is a new list handle.</dd>
</dl>

<p>The function `cbmapopen' is used in order to get a map handle.</p>

<dl>
<dt><kbd>CBMAP *cbmapopen(void);</kbd></dt>
<dd>The return value is a map handle.</dd>
</dl>

<p>The function `cbmapdup' is used in order to copy a map.</p>

<dl>
<dt><kbd>CBMAP *cbmapdup(CBMAP *<var>map</var>);</kbd></dt>
<dd>`map' specifies a map handle.  The return value is a new map handle.  The iterator of the source map is initialized.</dd>
</dl>

<p>The function `cbmapclose' is used in order to close a map handle.</p>

<dl>
<dt><kbd>void cbmapclose(CBMAP *<var>map</var>);</kbd></dt>
<dd>`map' specifies a map handle.  Because the region of a closed handle is released, it becomes impossible to use the handle.</dd>
</dl>

<p>The function `cbmapput' is used in order to store a record into a map.</p>

<dl>
<dt><kbd>int cbmapput(CBMAP *<var>map</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, const char *<var>vbuf</var>, int <var>vsiz</var>, int <var>over</var>);</kbd></dt>
<dd>`map' specifies a map handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `vbuf' specifies the pointer to the region of a value.  `vsiz' specifies the size of the region of the value.  If it is negative, the size is assigned with `strlen(vbuf)'.  `over' specifies whether the value of the duplicated record is overwritten or not.  If `over' is false and the key duplicated, the return value is false, else, it is true.</dd>
</dl>

<p>The function `cbmapputcat' is used in order to concatenate a value at the end of the value of the existing record.</p>

<dl>
<dt><kbd>void cbmapputcat(CBMAP *<var>map</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, const char *<var>vbuf</var>, int <var>vsiz</var>);</kbd></dt>
<dd>`map' specifies a map handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `vbuf' specifies the pointer to the region of a value.  `vsiz' specifies the size of the region of the value.  If it is negative, the size is assigned with `strlen(vbuf)'.  If there is no corresponding record, a new record is created.</dd>
</dl>

<p>The function `cbmapout' is used in order to delete a record of a map.</p>

<dl>
<dt><kbd>int cbmapout(CBMAP *<var>map</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`map' specifies a map handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is true.  False is returned when no record corresponds to the specified key.</dd>
</dl>

<p>The function `cbmapget' is used in order to retrieve a record of a map.</p>

<dl>
<dt><kbd>const char *cbmapget(const CBMAP *<var>map</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int *<var>sp</var>);</kbd></dt>
<dd>`map' specifies a map handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the value of the corresponding record.  `NULL' is returned when no record corresponds.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.</dd>
</dl>

<p>The function `cbmapmove' is used in order to move a record to the edge of a map.</p>

<dl>
<dt><kbd>int cbmapmove(CBMAP *<var>map</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int <var>head</var>);</kbd></dt>
<dd>`map' specifies a map handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `head' specifies the destination which is head if it is true or tail if else.  If successful, the return value is true.  False is returned when no record corresponds to the specified key.</dd>
</dl>

<p>The function `cbmapiterinit' is used in order to initialize the iterator of a map.</p>

<dl>
<dt><kbd>void cbmapiterinit(CBMAP *<var>map</var>);</kbd></dt>
<dd>`map' specifies a map handle.  The iterator is used in order to access the key of every record stored in a map.</dd>
</dl>

<p>The function `cbmapiternext' is used in order to get the next key of the iterator of a map.</p>

<dl>
<dt><kbd>const char *cbmapiternext(CBMAP *<var>map</var>, int *<var>sp</var>);</kbd></dt>
<dd>`map' specifies a map handle.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the next key, else, it is `NULL'.  `NULL' is returned when no record is to be get out of the iterator.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  The order of iteration is assured to be the same of the one of storing.</dd>
</dl>

<p>The function `cbmapiterval' is used in order to get the value binded to the key fetched from the iterator of a map.</p>

<dl>
<dt><kbd>const char *cbmapiterval(const char *<var>kbuf</var>, int *<var>sp</var>);</kbd></dt>
<dd>`kbuf' specifies the pointer to the region of a iteration key.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the region of the value of the corresponding record.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.</dd>
</dl>

<p>The function `cbmaprnum' is used in order to get the number of the records stored in a map.</p>

<dl>
<dt><kbd>int cbmaprnum(const CBMAP *<var>map</var>);</kbd></dt>
<dd>`map' specifies a map handle.  The return value is the number of the records stored in the map.</dd>
</dl>

<p>The function `cbmapkeys' is used in order to get the list handle contains all keys in a map.</p>

<dl>
<dt><kbd>CBLIST *cbmapkeys(CBMAP *<var>map</var>);</kbd></dt>
<dd>`map' specifies a map handle.  The return value is the list handle contains all keys in the map.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose' if it is no longer in use.</dd>
</dl>

<p>The function `cbmapvals' is used in order to get the list handle contains all values in a map.</p>

<dl>
<dt><kbd>CBLIST *cbmapvals(CBMAP *<var>map</var>);</kbd></dt>
<dd>`map' specifies a map handle.  The return value is the list handle contains all values in the map.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose' if it is no longer in use.</dd>
</dl>

<p>The function `cbmapdump' is used in order to serialize a map into a byte array.</p>

<dl>
<dt><kbd>char *cbmapdump(const CBMAP *<var>map</var>, int *<var>sp</var>);</kbd></dt>
<dd>`map' specifies a map handle.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  The return value is the pointer to the region of the result serial region.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbmapload' is used in order to redintegrate a serialized map.</p>

<dl>
<dt><kbd>CBMAP *cbmapload(const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a byte array.  `size' specifies the size of the region.  The return value is a new map handle.</dd>
</dl>

<p>The function `cbmaploadone' is used in order to extract a record from a serialized map.</p>

<dl>
<dt><kbd>char *cbmaploadone(const char *<var>ptr</var>, int <var>size</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int *<var>sp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a byte array.  `size' specifies the size of the region.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the value of the corresponding record.  `NULL' is returned when no record corresponds.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.</dd>
</dl>


<p>The function `cbheapopen' is used in order to get a heap handle.</p>

<dl>
<dt><kbd>CBHEAP *cbheapopen(int <var>size</var>, int <var>max</var>, int(*<var>compar</var>)(const void *, const void *));</kbd></dt>
<dd>`size' specifies the size of each record.  `max' specifies the maximum number of records in the heap.  `compar' specifies the pointer to comparing function.  The two arguments specify the pointers of records.  The comparing function should returns positive if the former is big, negative if the latter is big, 0 if both are equal.  The return value is a heap handle.</dd>
</dl>

<p>The function `cbheapdup' is used in order to copy a heap.</p>

<dl>
<dt><kbd>CBHEAP *cbheapdup(CBHEAP *<var>heap</var>);</kbd></dt>
<dd>`heap' specifies a heap handle.  The return value is a new heap handle.</dd>
</dl>

<p>The function `cbheapclose' is used in order to close a heap handle.</p>

<dl>
<dt><kbd>void cbheapclose(CBHEAP *<var>heap</var>);</kbd></dt>
<dd>`heap' specifies a heap handle.  Because the region of a closed handle is released, it becomes impossible to use the handle.</dd>
</dl>

<p>The function `cbheapnum' is used in order to get the number of the records stored in a heap.</p>

<dl>
<dt><kbd>int cbheapnum(CBHEAP *<var>heap</var>);</kbd></dt>
<dd>`heap' specifies a heap handle.  The return value is the number of the records stored in the heap.</dd>
</dl>

<p>The function `cbheapinsert' is used in order to insert a record into a heap.</p>

<dl>
<dt><kbd>int cbheapinsert(CBHEAP *<var>heap</var>, const void *<var>ptr</var>);</kbd></dt>
<dd>`heap' specifies a heap handle.  `ptr' specifies the pointer to the region of a record.  The return value is true if the record is added, else false.  If the new record is bigger than the biggest existing regord, the new record is not added.  If the new record is added and the number of records exceeds the maximum number, the biggest existing record is removed.</dd>
</dl>

<p>The function `cbheapval' is used in order to get the pointer to the region of a record in a heap.</p>

<dl>
<dt><kbd>void *cbheapval(CBHEAP *<var>heap</var>, int <var>index</var>);</kbd></dt>
<dd>`heap' specifies a heap handle.  `index' specifies the index of a record.  The return value is the pointer to the region of the record.  If `index' is equal to or more than the number of records, the return value is `NULL'.  Note that records are organized by the nagative order the comparing function.</dd>
</dl>

<p>The function `cbheaptomalloc' is used in order to convert a heap to an allocated region.</p>

<dl>
<dt><kbd>void *cbheaptomalloc(CBHEAP *<var>heap</var>, int *<var>np</var>);</kbd></dt>
<dd>`heap' specifies a heap handle.  `np' specifies the pointer to a variable to which the number of records of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the region of the heap.  Records are sorted.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  Because the region of the original heap is released, it should not be released again.</dd>
</dl>

<p>The function `cbsprintf' is used in order to allocate a formatted string on memory.</p>

<dl>
<dt><kbd>char *cbsprintf(const char *<var>format</var>, ...);</kbd></dt>
<dd>`format' specifies a printf-like format string.  The conversion character `%' can be used with such flag characters as `d', `o', `u', `x', `X', `e', `E', `f', `g', `G', `c', `s', and `%'.  Specifiers of the field length and the precision can be put between the conversion characters and the flag characters.  The specifiers consist of decimal characters, `.', `+', `-', and the space character.  The other arguments are used according to the format string.  The return value is the pointer to the allocated region of the result string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbreplace' is used in order to replace some patterns in a string.</p>

<dl>
<dt><kbd>char *cbreplace(const char *<var>str</var>, CBMAP *<var>pairs</var>);</kbd></dt>
<dd>`str' specifies the pointer to a source string.  `pairs' specifies the handle of a map composed of pairs of replacement.  The key of each pair specifies a pattern before replacement and its value specifies the pattern after replacement.  The return value is the pointer to the allocated region of the result string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbsplit' is used in order to make a list by splitting a serial datum.</p>

<dl>
<dt><kbd>CBLIST *cbsplit(const char *<var>ptr</var>, int <var>size</var>, const char *<var>delim</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to the region of the source content.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  `delim' specifies a string containing delimiting characters.  If it is `NULL', zero code is used as a delimiter.  The return value is a list handle.  If two delimiters are successive, it is assumed that an empty element is between the two.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose'.</dd>
</dl>

<p>The function `cbreadfile' is used in order to read whole data of a file.</p>

<dl>
<dt><kbd>char *cbreadfile(const char *<var>name</var>, int *<var>sp</var>);</kbd></dt>
<dd>`name' specifies the name of a file.    If it is `NULL', the standard input is specified.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the allocated region of the read data.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbwritefile' is used in order to write a serial datum into a file.</p>

<dl>
<dt><kbd>int cbwritefile(const char *<var>name</var>, const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`name specifies the name of a file.  If it is `NULL', the standard output is specified.  `ptr' specifies the pointer to the region of the source content.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  If successful, the return value is true, else, it is false.  If the file exists, it is overwritten.  Else, a new file is created.</dd>
</dl>

<p>The function `cbreadlines' is used in order to read every line of a file.</p>

<dl>
<dt><kbd>CBLIST *cbreadlines(const char *<var>name</var>);</kbd></dt>
<dd>`name' specifies the name of a file.  If it is `NULL', the standard input is specified.  The return value is a list handle of the lines if successful, else it is NULL.  Line separators are cut out.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose' if it is no longer in use.</dd>
</dl>

<p>The function `cbdirlist' is used in order to read names of files in a directory.</p>

<dl>
<dt><kbd>CBLIST *cbdirlist(const char *<var>name</var>);</kbd></dt>
<dd>`name' specifies the name of a directory.  The return value is a list handle of names if successful, else it is NULL.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose' if it is no longer in use.</dd>
</dl>

<p>The function `cbfilestat' is used in order to get the status of a file or a directory.</p>

<dl>
<dt><kbd>int cbfilestat(const char *<var>name</var>, int *<var>isdirp</var>, int *<var>sizep</var>, int *<var>mtimep</var>);</kbd></dt>
<dd>`name' specifies the name of a file or a directory.  `dirp' specifies the pointer to a variable to which whether the file is a directory is assigned.  If it is `NULL', it is not used.  `sizep' specifies the pointer to a variable to which the size of the file is assigned.  If it is `NULL', it is not used.  `mtimep' specifies the pointer to a variable to which the last modified time of the file is assigned.  If it is `NULL', it is not used.  If successful, the return value is true, else, false.  False is returned when the file does not exist or the permission is denied.</dd>
</dl>

<p>The function `cbremove' is used in order to remove a file or a directory and its sub ones recursively.</p>

<dl>
<dt><kbd>int cbremove(const char *<var>name</var>);</kbd></dt>
<dd>`name' specifies the name of a file or a directory.  If successful, the return value is true, else, false.  False is returned when the file does not exist or the permission is denied.</dd>
</dl>

<p>The function `cburlbreak' is used in order to break up a URL into elements.</p>

<dl>
<dt><kbd>CBMAP *cburlbreak(const char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer to a string of URL.  The return value is a map handle.  Each key of the map is the name of an element.  The key "self" specifies the URL itself.  The key "scheme" specifies the scheme.  The key "host" specifies the host of the server.  The key "port" specifies the port number of the server.  The key "authority" specifies the authority information.  The key "path" specifies the path of the resource.  The key "file" specifies the file name without the directory section.  The key "query" specifies the query string.  The key "fragment" specifies the fragment string.  Supported schema are HTTP, HTTPS, FTP, and FILE.  Absolute URL and relative URL are supported.  Because the handle of the return value is opened with the function `cbmapopen', it should be closed with the function `cbmapclose' if it is no longer in use.</dd>
</dl>

<p>The runction `cburlresolve' is used in order to resolve a relative URL with another absolute URL.</p>

<dl>
<dt><kbd>char *cburlresolve(const char *<var>base</var>, const char *<var>target</var>);</kbd></dt>
<dd>`base' specifies an absolute URL of a base location.  `target' specifies a URL to be resolved.  The return value is a resolved URL.  If the target URL is relative, a new URL of relative location from the base location is returned.  Else, a copy of the target URL is returned.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cburlencode' is used in order to encode a serial object with URL encoding.</p>

<dl>
<dt><kbd>char *cburlencode(const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  The return value is the pointer to the result string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cburldecode' is used in order to decode a string encoded with URL encoding.</p>

<dl>
<dt><kbd>char *cburldecode(const char *<var>str</var>, int *<var>sp</var>);</kbd></dt>
<dd>`str' specifies the pointer to a source string.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the region of the result.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbbaseencode' is used in order to encode a serial object with Base64 encoding.</p>

<dl>
<dt><kbd>char *cbbaseencode(const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  The return value is the pointer to the result string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbbasedecode' is used in order to decode a string encoded with Base64 encoding.</p>

<dl>
<dt><kbd>char *cbbasedecode(const char *<var>str</var>, int *<var>sp</var>);</kbd></dt>
<dd>`str' specifies the pointer to a source string.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the region of the result.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbquoteencode' is used in order to encode a serial object with quoted-printable encoding.</p>

<dl>
<dt><kbd>char *cbquoteencode(const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  The return value is the pointer to the result string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbquotedecode' is used in order to decode a string encoded with quoted-printable encoding.</p>

<dl>
<dt><kbd>char *cbquotedecode(const char *<var>str</var>, int *<var>sp</var>);</kbd></dt>
<dd>`str' specifies the pointer to a source string.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer to the region of the result.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>


<p>The function `cbmimebreak' is used in order to split a string of MIME into headers and the body.</p>

<dl>
<dt><kbd>char *cbmimebreak(const char *<var>ptr</var>, int <var>size</var>, CBMAP *<var>attrs</var>, int *<var>sp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to the region of MIME data.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  `attrs' specifies a map handle to store attributes.  If it is `NULL', it is not used.  Each key of the map is an attribute name uncapitalized.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  The return value is the pointer of the body data.  If the content type is defined, the attribute map has the key "TYPE" specifying the type.  If the character encoding is defined, the key "CHARSET" specifies the encoding name.  If the boundary string of multipart is defined, the key "BOUNDARY" specifies the string.  If the content disposition is defined, the key "DISPOSITION" specifies the direction.  If the file name is defined, the key "FILENAME" specifies the name.  If the attribute name is defined, the key "NAME" specifies the name.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbmimeparts' is used in order to split multipart data of MIME into its parts.</p>

<dl>
<dt><kbd>CBLIST *cbmimeparts(const char *<var>ptr</var>, int <var>size</var>, const char *<var>boundary</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to the region of multipart data of MIME.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  `boundary' specifies the pointer to the region of the boundary string.  The return value is a list handle.  Each element of the list is the string of a part.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose' if it is no longer in use.</dd>
</dl>

<p>The function `cbmimeencode' is used in order to encode a string with MIME encoding.</p>

<dl>
<dt><kbd>char *cbmimeencode(const char *<var>str</var>, const char *<var>encname</var>, int <var>base</var>);</kbd></dt>
<dd>`str' specifies the pointer to a string.  `encname' specifies a string of the name of the character encoding.  The return value is the pointer to the result string.  `base' specifies whether to use Base64 encoding.  If it is false, quoted-printable is used.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbmimedecode' is used in order to decode a string encoded with MIME encoding.</p>

<dl>
<dt><kbd>char *cbmimedecode(const char *<var>str</var>, char *<var>enp</var>);</kbd></dt>
<dd>`str' specifies the pointer to an encoded string.  `enp' specifies the pointer to a region into which the name of encoding is written.  If it is `NULL', it is not used.  The size of the buffer should be equal to or more than 32 bytes.  The return value is the pointer to the result string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbcsvrows' is used in order to split a string of CSV into rows.</p>

<dl>
<dt><kbd>CBLIST *cbcsvrows(const char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer to the region of an CSV string.  The return value is a list handle.  Each element of the list is a string of a row.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose' if it is no longer in use.  The character encoding of the input string should be US-ASCII, UTF-8, ISO-8859-*, EUC-*, or Shift_JIS.  Being compatible with MS-Excel, these functions for CSV can handle cells including such meta characters as comma, between double quotation marks.</dd>
</dl>

<p>The function `cbcsvcells' is used in order to split the string of a row of CSV into cells.</p>

<dl>
<dt><kbd>CBLIST *cbcsvcells(const char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer to the region of a row of CSV.  The return value is a list handle.  Each element of the list is the unescaped string of a cell of the row.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose' if it is no longer in use.</dd>
</dl>

<p>The function `cbcsvescape' is used in order to escape a string with the meta characters of CSV.</p>

<dl>
<dt><kbd>char *cbcsvescape(const char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer to the region of a string.  The return value is the pointer to the escaped string sanitized of meta characters.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbcsvunescape' is used in order to unescape a string with the escaped meta characters of CSV.</p>

<dl>
<dt><kbd>char *cbcsvunescape(const char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer to the region of a string with meta characters.  The return value is the pointer to the unescaped string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbxmlbreak' is used in order to split a string of XML into tags and text sections.</p>

<dl>
<dt><kbd>CBLIST *cbxmlbreak(const char *<var>str</var>, int <var>cr</var>);</kbd></dt>
<dd>`str' specifies the pointer to the region of an XML string.  `cr' specifies whether to remove comments.  The return value is a list handle.  Each element of the list is the string of a tag or a text section.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose' if it is no longer in use.  The character encoding of the input string should be US-ASCII, UTF-8, ISO-8859-*, EUC-*, or Shift_JIS.  Because these functions for XML are not XML parser with validation check, it can handle also HTML and SGML.</dd>
</dl>

<p>The function `cbxmlattrs' is used in order to get the map of attributes of an XML tag.</p>

<dl>
<dt><kbd>CBMAP *cbxmlattrs(const char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer to the region of a tag string.  The return value is a map handle.  Each key of the map is the name of an attribute.  Each value is unescaped.  You can get the name of the tag with the key of an empty string.  Because the handle of the return value is opened with the function `cbmapopen', it should be closed with the function `cbmapclose' if it is no longer in use.</dd>
</dl>

<p>The function `cbxmlescape' is used in order to escape a string with the meta characters of XML.</p>

<dl>
<dt><kbd>char *cbxmlescape(const char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer to the region of a string.  The return value is the pointer to the escaped string sanitized of meta characters.  This function converts only `&amp;', `&lt;', `&gt;', and `&quot;'.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbxmlunescape' is used in order to unescape a string with the entity references of XML.</p>

<dl>
<dt><kbd>char *cbxmlunescape(const char *<var>str</var>);</kbd></dt>
<dd>`str' specifies the pointer to the region of a string.  The return value is the pointer to the unescaped string.  This function restores only `&amp;amp;', `&amp;lt;', `&amp;gt;', and `&amp;quot;'.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbdeflate' is used in order to compress a serial object with ZLIB.</p>

<dl>
<dt><kbd>char *cbdeflate(const char *<var>ptr</var>, int <var>size</var>, int *<var>sp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If successful, the return value is the pointer to the result object, else, it is `NULL'.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  This function is available only if QDBM was built with ZLIB enabled.</dd>
</dl>

<p>The function `cbinflate' is used in order to decompress a serial object compressed with ZLIB.</p>

<dl>
<dt><kbd>char *cbinflate(const char *<var>ptr</var>, int <var>size</var>, int *<var>sp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the result object, else, it is `NULL'.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  This function is available only if QDBM was built with ZLIB enabled.</dd>
</dl>

<p>The function `cbgzencode' is used in order to compress a serial object with GZIP.</p>

<dl>
<dt><kbd>char *cbgzencode(const char *<var>ptr</var>, int <var>size</var>, int *<var>sp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If successful, the return value is the pointer to the result object, else, it is `NULL'.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  This function is available only if QDBM was built with ZLIB enabled.</dd>
</dl>

<p>The function `cbgzdecode' is used in order to decompress a serial object compressed with GZIP.</p>

<dl>
<dt><kbd>char *cbgzdecode(const char *<var>ptr</var>, int <var>size</var>, int *<var>sp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the result object, else, it is `NULL'.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  This function is available only if QDBM was built with ZLIB enabled.</dd>
</dl>

<p>The function `cbgetcrc' is used in order to get the CRC32 checksum of a serial object.</p>

<dl>
<dt><kbd>unsigned int cbgetcrc(const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  The return value is the CRC32 checksum of the object.  This function is available only if QDBM was built with ZLIB enabled.</dd>
</dl>

<p>The function `cblzoencode' is used in order to compress a serial object with LZO.</p>

<dl>
<dt><kbd>char *cblzoencode(const char *<var>ptr</var>, int <var>size</var>, int *<var>sp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If successful, the return value is the pointer to the result object, else, it is `NULL'.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  This function is available only if QDBM was built with LZO enabled.</dd>
</dl>

<p>The function `cblzodecode' is used in order to decompress a serial object compressed with LZO.</p>

<dl>
<dt><kbd>char *cblzodecode(const char *<var>ptr</var>, int <var>size</var>, int *<var>sp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the result object, else, it is `NULL'.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  This function is available only if QDBM was built with LZO enabled.</dd>
</dl>

<p>The function `cbbzencode' is used in order to compress a serial object with BZIP2.</p>

<dl>
<dt><kbd>char *cbbzencode(const char *<var>ptr</var>, int <var>size</var>, int *<var>sp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If successful, the return value is the pointer to the result object, else, it is `NULL'.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  This function is available only if QDBM was built with BZIP2 enabled.</dd>
</dl>

<p>The function `cbbzdecode' is used in order to decompress a serial object compressed with BZIP2.</p>

<dl>
<dt><kbd>char *cbbzdecode(const char *<var>ptr</var>, int <var>size</var>, int *<var>sp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the result object, else, it is `NULL'.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  This function is available only if QDBM was built with BZIP2 enabled.</dd>
</dl>

<p>The function `cbiconv' is used in order to convert the character encoding of a string.</p>

<dl>
<dt><kbd>char *cbiconv(const char *<var>ptr</var>, int <var>size</var>, const char *<var>icode</var>, const char *<var>ocode</var>, int *<var>sp</var>, int *<var>mp</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  `icode' specifies the name of encoding of the input string.  `ocode' specifies the name of encoding of the output string.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  `mp' specifies the pointer to a variable to which the number of missing characters by failure of conversion is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the result object, else, it is `NULL'.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  This function is available only if QDBM was built with ICONV enabled.</dd>
</dl>

<p>The function `cbencname' is used in order to detect the encoding of a string automatically.</p>

<dl>
<dt><kbd>const char *cbencname(const char *<var>ptr</var>, int <var>size</var>);</kbd></dt>
<dd>`ptr' specifies the pointer to a region.  `size' specifies the size of the region.  If it is negative, the size is assigned with `strlen(ptr)'.  The return value is the string of the encoding name of the string.  As it stands, US-ASCII, ISO-2022-JP, Shift_JIS, CP932, EUC-JP, UTF-8, UTF-16, UTF-16BE, and UTF-16LE are supported.  If none of them matches, ISO-8859-1 is selected.  This function is available only if QDBM was built with ICONV enabled.</dd>
</dl>

<p>The function `cbjetlag' is used in order to get the jet lag of the local time in seconds.</p>

<dl>
<dt><kbd>int cbjetlag(void);</kbd></dt>
<dd>The return value is the jet lag of the local time in seconds.</dd>
</dl>

<p>The function `cbcalendar' is used in order to get the Gregorian calendar of a time.</p>

<dl>
<dt><kbd>void cbcalendar(time_t <var>t</var>, int <var>jl</var>, int *<var>yearp</var>, int *<var>monp</var>, int *<var>dayp</var>, int *<var>hourp</var>, int *<var>minp</var>, int *<var>secp</var>);</kbd></dt>
<dd>`t' specifies a source time.  If it is negative, the current time is specified.  `jl' specifies the jet lag of a location in seconds.  `yearp' specifies the pointer to a variable to which the year is assigned.  If it is `NULL', it is not used.  `monp' specifies the pointer to a variable to which the month is assigned.  If it is `NULL', it is not used.  1 means January and 12 means December.  `dayp' specifies the pointer to a variable to which the day of the month is assigned.  If it is `NULL', it is not used.  `hourp' specifies the pointer to a variable to which the hours is assigned.  If it is `NULL', it is not used.  `minp' specifies the pointer to a variable to which the minutes is assigned.  If it is `NULL', it is not used.  `secp' specifies the pointer to a variable to which the seconds is assigned.  If it is `NULL', it is not used.</dd>
</dl>

<p>The function `cbdayofweek' is used in order to get the day of week of a date.</p>

<dl>
<dt><kbd>int cbdayofweek(int <var>year</var>, int <var>mon</var>, int <var>day</var>);</kbd></dt>
<dd>`year' specifies the year of a date.  `mon' specifies the month of the date.  `day' specifies the day of the date.  The return value is the day of week of the date.  0 means Sunday and 6 means Saturday.</dd>
</dl>

<p>The function `cbdatestrwww' is used in order to get the string for a date in W3CDTF.</p>

<dl>
<dt><kbd>char *cbdatestrwww(time_t <var>t</var>, int <var>jl</var>);</kbd></dt>
<dd>`t' specifies a source time.  If it is negative, the current time is specified.  `jl' specifies the jet lag of a location in seconds.  The return value is the string of the date in W3CDTF (YYYY-MM-DDThh:mm:ddTZD).  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbdatestrhttp' is used in order to get the string for a date in RFC 1123 format.</p>

<dl>
<dt><kbd>char *cbdatestrhttp(time_t <var>t</var>, int <var>jl</var>);</kbd></dt>
<dd>`t' specifies a source time.  If it is negative, the current time is specified.  `jl' specifies the jet lag of a location in seconds.  The return value is the string of the date in RFC 1123 format (Wdy, DD-Mon-YYYY hh:mm:dd TZD).  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `cbstrmktime' is used in order to get the time value of a date string in decimal, hexadecimal, W3CDTF, or RFC 822 (1123).</p>

<dl>
<dt><kbd>time_t cbstrmktime(const char *<var>str</var>);</kbd></dt>
<dd>`str' specifies a date string in decimal, hexadecimal, W3CDTF, or RFC 822 (1123).  The return value is the time value of the date or -1 if the format is invalid.  Decimal can be trailed by "s" for in seconds, "m" for in minutes, "h" for in hours, and "d" for in days.</dd>
</dl>

<p>The function `cbproctime' is used in order to get user and system processing times.</p>

<dl>
<dt><kbd>void cbproctime(double *<var>usrp</var>, double *<var>sysp</var>);</kbd></dt>
<dd>`usrp' specifies the pointer to a variable to which the user processing time is assigned.  If it is `NULL', it is not used.  The unit of time is seconds.  `sysp' specifies the pointer to a variable to which the system processing time is assigned.  If it is `NULL', it is not used.  The unit of time is seconds.</dd>
</dl>

<p>The function `cbstdiobin' is used in order to ensure that the standard I/O is binary mode.</p>

<dl>
<dt><kbd>void cbstdiobin(void);</kbd></dt>
<dd>This function is useful for applications on dosish file systems.</dd>
</dl>

<h3>Examples</h3>

<p>The following example is typical use.</p>

<pre>#include &lt;cabin.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;

int main(int argc, char **argv){
  CBDATUM *datum;
  CBLIST *list;
  CBMAP *map;
  char *buf1, *buf2;
  int i;

  /* open the datum handle */
  datum = cbdatumopen("123", -1);
  /* concatenate the data */
  cbdatumcat(datum, "abc", -1);
  /* print the datum */
  printf("%s\n", cbdatumptr(datum));
  /* close the datum handle */
  cbdatumclose(datum);

  /* open the list handle */
  list = cblistopen();
  /* add elements into the list */
  cblistpush(list, "apple", -1);
  cblistpush(list, "orange", -1);
  /* print all elements */
  for(i = 0; i &lt; cblistnum(list); i++){
    printf("%s\n", cblistval(list, i, NULL));
  }
  /* close the list handle */
  cblistclose(list);

  /* open the map handle */
  map = cbmapopen();
  /* add records into the map */
  cbmapput(map, "dog", -1, "bowwow", -1, 1);
  cbmapput(map, "cat", -1, "meow", -1, 1);
  /* search for values and print them */
  printf("%s\n", cbmapget(map, "dog", -1, NULL));
  printf("%s\n", cbmapget(map, "cat", -1, NULL));
  /* close the map */
  cbmapclose(map);

  /* Base64 encoding */
  buf1 = cbbaseencode("I miss you.", -1);
  printf("%s\n", buf1);
  /* Base64 decoding */
  buf2 = cbbasedecode(buf1, NULL);
  printf("%s\n", buf2);
  /* release the resources */
  free(buf2);
  free(buf1);

  /* register a plain pointer to the global garbage collector */
  buf1 = cbmemdup("Take it easy.", -1);
  cbglobalgc(buf1, free);
  /* the pointer is available but you don't have to release it */
  printf("%s\n", buf1);
  
  /* register a list to the global garbage collector */
  list = cblistopen();
  cbglobalgc(list, (void (*)(void *))cblistclose);
  /* the handle is available but you don't have to close it */
  cblistpush(list, "Don't hesitate.", -1);
  for(i = 0; i &lt; cblistnum(list); i++){
    printf("%s\n", cblistval(list, i, NULL));    
  }

  return 0;
}
</pre>

<h3>Notes</h3>

<p>How to build programs using Cabin is the same as the case of Depot.</p>

<pre>gcc -I/usr/local/include -o sample sample.c -L/usr/local/lib -lqdbm
</pre>

<p>Functions of Cabin except for `cbglobalgc' are thread-safe as long as a handle is not accessed by threads at the same time, on the assumption that `errno', `malloc', and so on are thread-safe.</p>

<hr />

<h2><a name="cabincli" id="cabincli" class="head">Commands for Cabin</a></h2>

<p>Cabin has the following command line interfaces.</p>

<p>The command `cbtest' is a utility for facility test and performance test.  Measure the execution time of the command.  This command is used in the following format.  `rnum' specifies the number of records.</p>

<dl>
<dt><kbd>cbtest sort [-d] <var>rnum</var></kbd></dt>
<dd>Perform test of sorting algorithms.</dd>
<dt><kbd>cbtest strstr [-d] <var>rnum</var></kbd></dt>
<dd>Perform test of string locating algorithms.</dd>
<dt><kbd>cbtest list [-d] <var>rnum</var></kbd></dt>
<dd>Perform writing test of list.</dd>
<dt><kbd>cbtest map [-d] <var>rnum</var></kbd></dt>
<dd>Perform writing test of map.</dd>
<dt><kbd>cbtest wicked <var>rnum</var></kbd></dt>
<dd>Perform updating operations of list and map selected at random.</dd>
<dt><kbd>cbtest misc</kbd></dt>
<dd>Perform test of miscellaneous routines.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-d</kbd> : read and show data of the result.</li>
</ul>

<p>This command returns 0 on success, another on failure.</p>

<p>The command `cbcodec' is a tool to use encoding and decoding features provided by Cabin.  This command is used in the following format.  `file' specifies a input file.  If it is omitted, the standard input is read.</p>

<dl>
<dt><kbd>cbcodec url [-d] [-br] [-rs <var>base</var> <var>target</var>] [-l] [-e <var>expr</var>] [<var>file</var>]</kbd></dt>
<dd>Perform URL encoding and its decoding.</dd>
<dt><kbd>cbcodec base [-d] [-l] [-c <var>num</var>] [-e <var>expr</var>] [<var>file</var>]</kbd></dt>
<dd>Perform Base64 encoding and its decoding.</dd>
<dt><kbd>cbcodec quote [-d] [-l] [-c <var>num</var>] [-e <var>expr</var>] [<var>file</var>]</kbd></dt>
<dd>Perform quoted-printable encoding and its decoding.</dd>
<dt><kbd>cbcodec mime [-d] [-hd] [-bd] [-part <var>num</var>] [-l] [-ec <var>code</var>] [-qp] [-dc] [-e <var>expr</var>] [<var>file</var>]</kbd></dt>
<dd>Perform MIME encoding and its decoding.</dd>
<dt><kbd>cbcodec csv [-d] [-t] [-l] [-e <var>expr</var>] [-html] [<var>file</var>]</kbd></dt>
<dd>Process CSV.  By default, escape meta characters.</dd>
<dt><kbd>cbcodec xml [-d] [-p] [-l] [-e <var>expr</var>] [-tsv] [<var>file</var>]</kbd></dt>
<dd>Process XML.  By default, escape meta characters.</dd>
<dt><kbd>cbcodec zlib [-d] [-gz] [-crc] [<var>file</var>]</kbd></dt>
<dd>Perform deflation and inflation with ZLIB.  It is available only if QDBM was built with ZLIB enabled.</dd>
<dt><kbd>cbcodec lzo [-d] [<var>file</var>]</kbd></dt>
<dd>Perform compression and decompression with LZO.  It is available only if QDBM was built with LZO enabled.</dd>
<dt><kbd>cbcodec bzip [-d] [<var>file</var>]</kbd></dt>
<dd>Perform compression and decompression with BZIP2.  It is available only if QDBM was built with BZIP2 enabled.</dd>
<dt><kbd>cbcodec iconv [-ic <var>code</var>] [-oc <var>code</var>] [-ol <var>ltype</var>] [-cn] [-um] [-wc] [<var>file</var>]</kbd></dt>
<dd>Convert character encoding with ICONV.  It is available only if QDBM was built with ICONV enabled.</dd>
<dt><kbd>cbcodec date [-wf] [-rf] [-utc] [<var>str</var>]</kbd></dt>
<dd>Convert a date string specified `str'.  By default, UNIX time is output.  If `str' is omitted, the current date is dealt.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-d</kbd> : perform decoding (unescaping), not encoding (escaping).</li>
<li><kbd>-br</kbd> : break up URL into elements.</li>
<li><kbd>-rs</kbd> : resolve relative URL.</li>
<li><kbd>-l</kbd> : output the tailing newline.</li>
<li><kbd>-e <var>expr</var></kbd> : specify input data directly.</li>
<li><kbd>-c <var>num</var></kbd> : limit the number of columns of the encoded data.</li>
<li><kbd>-hd</kbd> : parse MIME and extract headers in TSV format.</li>
<li><kbd>-bd</kbd> : parse MIME and extract the body.</li>
<li><kbd>-part <var>num</var></kbd> : parse MIME and extract a part.</li>
<li><kbd>-ec <var>code</var></kbd> : specify the input encoding, which is UTF-8 by default.</li>
<li><kbd>-qp</kbd> : use quoted-printable encoding, which is Base64 by default.</li>
<li><kbd>-dc</kbd> : output the encoding name instead of the result string when decoding.</li>
<li><kbd>-t</kbd> : parse CSV.  Convert the data into TSV.  Tab and new-line in a cell are deleted.</li>
<li><kbd>-html</kbd> : parse CSV.  Convert the data into HTML.</li>
<li><kbd>-p</kbd> : parse XML.  Show tags and text sections with dividing headers.</li>
<li><kbd>-tsv</kbd> : parse XML.  Show the result in TSV format.  Characters of tabs and new-lines are URL-encoded.</li>
<li><kbd>-gz</kbd> : use GZIP format.</li>
<li><kbd>-crc</kbd> : output the CRC32 checksum as hexadecimal and big endian.</li>
<li><kbd>-ic <var>code</var></kbd> : specify the input encoding, which is detected automatically by default.</li>
<li><kbd>-oc <var>code</var></kbd> : specify the output encoding, which is UTF-8 by default.</li>
<li><kbd>-ol <var>ltype</var></kbd> : convert line feed characters, with `unix'(LF), `dos'(CRLF), and `mac'(CR).</li>
<li><kbd>-cn</kbd> : detect the input encoding and show its name.</li>
<li><kbd>-wc</kbd> : count the number of characters of the input string of UTF-8.</li>
<li><kbd>-um</kbd> : output mappings of UCS-2 characters and C strings of UTF-16BE and UTF-8.</li>
<li><kbd>-wf</kbd> : output in W3CDTF format.</li>
<li><kbd>-rf</kbd> : output in RFC 1123 format.</li>
<li><kbd>-utc</kbd> : output the coordinate universal time.</li>
</ul>

<p>This command returns 0 on success, another on failure.</p>

<hr />

<h2><a name="villaapi" id="villaapi" class="head">Villa: Advanced API</a></h2>

<h3>Overview</h3>

<p>Villa is the advanced API of QDBM.  It provides routines for managing a database file of B+ tree.  Each record is stored being sorted in order defined by a user.  As for hash databases, retrieving method is provided only as complete accord.  However, with Villa, it is possible to retrieve records specified by range.  Cursor is used in order to access each record in order.  It is possible to store records duplicating keys in a database.  Moreover, according to the transaction mechanism, you can commit or abort operations of a database in a lump.</p>

<p>Villa is implemented, based on Depot and Cabin.  A database file of Villa is actual one of Depot.  Although processing speed of retrieving and storing is slower than Depot, the size of a database is smaller.</p>

<p>In order to use Villa, you should include `depot.h', `cabin.h', `villa.h' and `stdlib.h' in the source files.  Usually, the following description will be near the beginning of a source file.</p>

<dl>
<dt><kbd>#include &lt;depot.h&gt;</kbd></dt>
<dt><kbd>#include &lt;cabin.h&gt;</kbd></dt>
<dt><kbd>#include &lt;villa.h&gt;</kbd></dt>
<dt><kbd>#include &lt;stdlib.h&gt;</kbd></dt>
</dl>

<p>A pointer to `VILLA' is used as a database handle. It is like that some file I/O routines of `stdio.h' use a pointer to `FILE'.  A database handle is opened with the function `vlopen' and closed with `vlclose'.  You should not refer directly to any member of the handle.  If a fatal error occurs in a database, any access method via the handle except `vlclose' will not work and return error status.  Although a process is allowed to use multiple database handles at the same time, handles of the same database file should not be used.  Before the cursor is used, it should be initialized by one of `vlcurfirst', `vlcurlast' or `vlcurjump'.  Also after storing or deleting a record with functions except for `vlcurput' and `vlcurout', the cursor should be initialized.</p>

<p>Villa also assign the external variable `dpecode' with the error code. The function `dperrmsg' is used in order to get the message of the error code.</p>

<h3>API</h3>

<p>You can define a comparing function to specify the order of records.  The function should be the following type.</p>

<dl>
<dt><kbd>typedef int(*VLCFUNC)(const char *<var>aptr</var>, int <var>asiz</var>, const char *<var>bptr</var>, int <var>bsiz</var>);</kbd></dt>
<dd>`aptr' specifies the pointer to the region of one key.  `asiz' specifies the size of the region of one key.  `bptr' specifies the pointer to the region of the other key.  `bsiz' specifies the size of the region of the other key.  The return value is positive if the former is big, negative if the latter is big, 0 if both are equivalent.</dd>
</dl>

<p>The function `vlopen' is used in order to get a database handle.</p>

<dl>
<dt><kbd>VILLA *vlopen(const char *<var>name</var>, int <var>omode</var>, VLCFUNC <var>cmp</var>);</kbd></dt>
<dd>`name' specifies the name of a database file.  `omode' specifies the connection mode: `VL_OWRITER' as a writer, `VL_OREADER' as a reader.  If the mode is `VL_OWRITER', the following may be added by bitwise or: `VL_OCREAT', which means it creates a new database if not exist, `VL_OTRUNC', which means it creates a new database regardless if one exists, `VL_OZCOMP', which means leaves in the database are compressed with ZLIB, `VL_OYCOMP', which means leaves in the database are compressed with LZO, `VL_OXCOMP', which means leaves in the database are compressed with BZIP2.  Both of `VL_OREADER' and `VL_OWRITER' can be added to by bitwise or: `VL_ONOLCK', which means it opens a database file without file locking, or `VL_OLCKNB', which means locking is performed without blocking.  `cmp' specifies the comparing function: `VL_CMPLEX' comparing keys in lexical order, `VL_CMPINT' comparing keys as objects of `int' in native byte order, `VL_CMPNUM' comparing keys as numbers of big endian, `VL_CMPDEC' comparing keys as decimal strings.  Any function based on the declaration of the type `VLCFUNC' can be assigned to the comparing function.  The comparing function should be kept same in the life of a database.  The return value is the database handle or `NULL' if it is not successful.  While connecting as a writer, an exclusive lock is invoked to the database file.  While connecting as a reader, a shared lock is invoked to the database file.  The thread blocks until the lock is achieved.  `VL_OZCOMP', `VL_OYCOMP', and `VL_OXCOMP' are available only if QDBM was built each with ZLIB, LZO, and BZIP2 enabled.  If `VL_ONOLCK' is used, the application is responsible for exclusion control.</dd>
</dl>

<p>The function `vlclose' is used in order to close a database handle.</p>

<dl>
<dt><kbd>int vlclose(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  If successful, the return value is true, else, it is false.  Because the region of a closed handle is released, it becomes impossible to use the handle.  Updating a database is assured to be written when the handle is closed.  If a writer opens a database but does not close it appropriately, the database will be broken.  If the transaction is activated and not committed, it is aborted.</dd>
</dl>

<p>The function `vlput' is used in order to store a record.</p>

<dl>
<dt><kbd>int vlput(VILLA *<var>villa</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, const char *<var>vbuf</var>, int <var>vsiz</var>, int <var>dmode</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `vbuf' specifies the pointer to the region of a value.  `vsiz' specifies the size of the region of the value.  If it is negative, the size is assigned with `strlen(vbuf)'.  `dmode' specifies behavior when the key overlaps, by the following values: `VL_DOVER', which means the specified value overwrites the existing one, `VL_DKEEP', which means the existing value is kept, `VL_DCAT', which means the specified value is concatenated at the end of the existing value, `VL_DDUP', which means duplication of keys is allowed and the specified value is added as the last one, `VL_DDUPR', which means duplication of keys is allowed and the specified value is added as the first one.  If successful, the return value is true, else, it is false.  The cursor becomes unavailable due to updating database.</dd>
</dl>

<p>The function `vlout' is used in order to delete a record.</p>

<dl>
<dt><kbd>int vlout(VILLA *<var>villa</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is true, else, it is false.  False is returned when no record corresponds to the specified key.  When the key of duplicated records is specified, the first record of the same key is deleted.  The cursor becomes unavailable due to updating database.</dd>
</dl>

<p>The function `vlget' is used in order to retrieve a record.</p>

<dl>
<dt><kbd>char *vlget(VILLA *<var>villa</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int *<var>sp</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the value of the corresponding record, else, it is `NULL'.  `NULL' is returned when no record corresponds to the specified key.  When the key of duplicated records is specified, the value of the first record of the same key is selected.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `vlvsiz' is used in order to get the size of the value of a record.</p>

<dl>
<dt><kbd>int vlvsiz(VILLA *<var>villa</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is the size of the value of the corresponding record, else, it is -1.  If multiple records correspond, the size of the first is returned.</dd>
</dl>

<p>The function `vlvnum' is used in order to get the number of records corresponding a key.</p>

<dl>
<dt><kbd>int vlvnum(VILLA *<var>villa</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  The return value is the number of corresponding records.  If no record corresponds, 0 is returned.</dd>
</dl>

<p>The function `vlputlist' is used in order to store plural records corresponding a key.</p>

<dl>
<dt><kbd>int vlputlist(VILLA *<var>villa</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, const CBLIST *<var>vals</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `vals' specifies a list handle of values.  The list should not be empty.  If successful, the return value is true, else, it is false.  The cursor becomes unavailable due to updating database.</dd>
</dl>

<p>The function `vloutlist' is used in order to delete all records corresponding a key.</p>

<dl>
<dt><kbd>int vloutlist(VILLA *<var>villa</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is true, else, it is false.  False is returned when no record corresponds to the specified key.  The cursor becomes unavailable due to updating database.</dd>
</dl>

<p>The function `vlgetlist' is used in order to retrieve values of all records corresponding a key.</p>

<dl>
<dt><kbd>CBLIST *vlgetlist(VILLA *<var>villa</var>, const char *<var>kbuf</var>, int <var>ksiz</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is a list handle of the values of the corresponding records, else, it is `NULL'.  `NULL' is returned when no record corresponds to the specified key.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose' if it is no longer in use.</dd>
</dl>

<p>The function `vlgetcat' is used in order to retrieve concatenated values of all records corresponding a key.</p>

<dl>
<dt><kbd>char *vlgetcat(VILLA *<var>villa</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int *<var>sp</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the concatenated values of the corresponding record, else, it is `NULL'.  `NULL' is returned when no record corresponds to the specified key.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free'  call if it is no longer in use.</dd>
</dl>

<p>The function `vlcurfirst' is used in order to move the cursor to the first record.</p>

<dl>
<dt><kbd>int vlcurfirst(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  If successful, the return value is true, else, it is false.  False is returned if there is no record in the database.</dd>
</dl>

<p>The function `vlcurlast' is used in order to move the cursor to the last record.</p>

<dl>
<dt><kbd>int vlcurlast(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  If successful, the return value is true, else, it is false.  False is returned if there is no record in the database.</dd>
</dl>

<p>The function `vlcurprev' is used in order to move the cursor to the previous record.</p>

<dl>
<dt><kbd>int vlcurprev(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  If successful, the return value is true, else, it is false.  False is returned if there is no previous record.</dd>
</dl>

<p>The function `vlcurnext' is used in order to move the cursor to the next record.</p>

<dl>
<dt><kbd>int vlcurnext(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  If successful, the return value is true, else, it is false.  False is returned if there is no next record.</dd>
</dl>

<p>The function `vlcurjump' is used in order to move the cursor to a position around a record.</p>

<dl>
<dt><kbd>int vlcurjump(VILLA *<var>villa</var>, const char *<var>kbuf</var>, int <var>ksiz</var>, int <var>jmode</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `jmode' specifies detail adjustment: `VL_JFORWARD', which means that the cursor is set to the first record of the same key and that the cursor is set to the next substitute if completely matching record does not exist, `VL_JBACKWARD', which means that the cursor is set to the last record of the same key and that the cursor is set to the previous substitute if completely matching record does not exist.  If successful, the return value is true, else, it is false.  False is returned if there is no record corresponding the condition.</dd>
</dl>

<p>The function `vlcurkey' is used in order to get the key of the record where the cursor is.</p>

<dl>
<dt><kbd>char *vlcurkey(VILLA *<var>villa</var>, int *<var>sp</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the key of the corresponding record, else, it is `NULL'.  `NULL' is returned when no record corresponds to the cursor.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `vlcurval' is used in order to get the value of the record where the cursor is.</p>

<dl>
<dt><kbd>char *vlcurval(VILLA *<var>villa</var>, int *<var>sp</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the value of the corresponding record, else, it is `NULL'.  `NULL' is returned when no record corresponds to the cursor.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `vlcurput' is used in order to insert a record around the cursor.</p>

<dl>
<dt><kbd>int vlcurput(VILLA *<var>villa</var>, const char *<var>vbuf</var>, int <var>vsiz</var>, int <var>cpmode</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  `vbuf' specifies the pointer to the region of a value.  `vsiz' specifies the size of the region of the value.  If it is negative, the size is assigned with `strlen(vbuf)'.  `cpmode' specifies detail adjustment: `VL_CPCURRENT', which means that the value of the current record is overwritten, `VL_CPBEFORE', which means that a new record is inserted before the current record, `VL_CPAFTER', which means that a new record is inserted after the current record.  If successful, the return value is true, else, it is false.  False is returned when no record corresponds to the cursor.  After insertion, the cursor is moved to the inserted record.</dd>
</dl>

<p>The function `vlcurout' is used in order to delete the record where the cursor is.</p>

<dl>
<dt><kbd>int vlcurout(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  If successful, the return value is true, else, it is false.  False is returned when no record corresponds to the cursor.  After deletion, the cursor is moved to the next record if possible.</dd>
</dl>

<p>The function `vlsettuning' is used in order to set the tuning parameters for performance.</p>

<dl>
<dt><kbd>void vlsettuning(VILLA *<var>villa</var>, int <var>lrecmax</var>, int <var>nidxmax</var>, int <var>lcnum</var>, int <var>ncnum</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  `lrecmax' specifies the max number of records in a leaf node of B+ tree.  If it is not more than 0, the default value is specified.  `nidxmax' specifies the max number of indexes in a non-leaf node of B+ tree.  If it is not more than 0, the default value is specified.  `lcnum' specifies the max number of caching leaf nodes.  If it is not more than 0, the default value is specified.  `ncnum' specifies the max number of caching non-leaf nodes.  If it is not more than 0, the default value is specified.  The default setting is equivalent to `vlsettuning(49, 192, 1024, 512)'.  Because tuning parameters are not saved in a database, you should specify them every opening a database.</dd>
</dl>

<p>The function `vlsetfbpsiz' is used in order to set the size of the free block pool of a database handle.</p>

<dl>
<dt><kbd>int vlsetfbpsiz(VILLA *<var>villa</var>, int <var>size</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  `size' specifies the size of the free block pool of a database.  If successful, the return value is true, else, it is false.  The default size of the free block pool is 256.  If the size is greater, the space efficiency of overwriting values is improved with the time efficiency sacrificed.</dd>
</dl>

<p>The function `vlsync' is used in order to synchronize updating contents with the file and the device.</p>

<dl>
<dt><kbd>int vlsync(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  If successful, the return value is true, else, it is false.  This function is useful when another process uses the connected database file.  This function should not be used while the transaction is activated.</dd>
</dl>

<p>The function `vloptimize' is used in order to optimize a database.</p>

<dl>
<dt><kbd>int vloptimize(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  If successful, the return value is true, else, it is false.  In an alternating succession of deleting and storing with overwrite or concatenate, dispensable regions accumulate.  This function is useful to do away with them.  This function should not be used while the transaction is activated.</dd>
</dl>

<p>The function `vlname' is used in order to get the name of a database.</p>

<dl>
<dt><kbd>char *vlname(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  If successful, the return value is the pointer to the region of the name of the database, else, it is `NULL'.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `vlfsiz' is used in order to get the size of a database file.</p>

<dl>
<dt><kbd>int vlfsiz(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  If successful, the return value is the size of the database file, else, it is -1.  Because of the I/O buffer, the return value may be less than the hard size.</dd>
</dl>

<p>The function `vllnum' is used in order to get the number of the leaf nodes of B+ tree.</p>

<dl>
<dt><kbd>int vllnum(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  If successful, the return value is the number of the leaf nodes, else, it is -1.</dd>
</dl>

<p>The function `vlnnum' is used in order to get the number of the non-leaf nodes of B+ tree.</p>

<dl>
<dt><kbd>int vlnnum(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  If successful, the return value is the number of the non-leaf nodes, else, it is -1.</dd>
</dl>

<p>The function `vlrnum' is used in order to get the number of the records stored in a database.</p>

<dl>
<dt><kbd>int vlrnum(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  If successful, the return value is the number of the records stored in the database, else, it is -1.</dd>
</dl>

<p>The function `vlwritable' is used in order to check whether a database handle is a writer or not.</p>

<dl>
<dt><kbd>int vlwritable(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  The return value is true if the handle is a writer, false if not.</dd>
</dl>

<p>The function `vlfatalerror' is used in order to check whether a database has a fatal error or not.</p>

<dl>
<dt><kbd>int vlfatalerror(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  The return value is true if the database has a fatal error, false if not.</dd>
</dl>

<p>The function `vlinode' is used in order to get the inode number of a database file.</p>

<dl>
<dt><kbd>int vlinode(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  The return value is the inode number of the database file.</dd>
</dl>

<p>The function `vlmtime' is used in order to get the last modified time of a database.</p>

<dl>
<dt><kbd>time_t vlmtime(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  The return value is the last modified time of the database.</dd>
</dl>

<p>The function `vltranbegin' is used in order to begin the transaction.</p>

<dl>
<dt><kbd>int vltranbegin(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  If successful, the return value is true, else, it is false.  Because this function does not perform mutual exclusion control in multi-thread, the application is responsible for it.  Only one transaction can be activated with a database handle at the same time.</dd>
</dl>

<p>The function `vltrancommit' is used in order to commit the transaction.</p>

<dl>
<dt><kbd>int vltrancommit(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  If successful, the return value is true, else, it is false.  Updating a database in the transaction is fixed when it is committed successfully.</dd>
</dl>

<p>The function `vltranabort' is used in order to abort the transaction.</p>

<dl>
<dt><kbd>int vltranabort(VILLA *<var>villa</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  If successful, the return value is true, else, it is false.  Updating a database in the transaction is discarded when it is aborted.  The state of the database is rollbacked to before transaction.</dd>
</dl>

<p>The function `vlremove' is used in order to remove a database file.</p>

<dl>
<dt><kbd>int vlremove(const char *<var>name</var>);</kbd></dt>
<dd>`name' specifies the name of a database file.  If successful, the return value is true, else, it is false.</dd>
</dl>

<p>The function `vlrepair' is used in order to repair a broken database file.</p>

<dl>
<dt><kbd>int vlrepair(const char *<var>name</var>, VLCFUNC <var>cmp</var>);</kbd></dt>
<dd>`name' specifies the name of a database file.  `cmp' specifies the comparing function of the database file.  If successful, the return value is true, else, it is false.  There is no guarantee that all records in a repaired database file correspond to the original or expected state.</dd>
</dl>

<p>The function `vlexportdb' is used in order to dump all records as endian independent data.</p>

<dl>
<dt><kbd>int vlexportdb(VILLA *<var>villa</var>, const char *<var>name</var>);</kbd></dt>
<dd>`villa' specifies a database handle.  `name' specifies the name of an output file.  If successful, the return value is true, else, it is false.</dd>
</dl>

<p>The function `vlimportdb' is used in order to load all records from endian independent data.</p>

<dl>
<dt><kbd>int vlimportdb(VILLA *<var>villa</var>, const char *<var>name</var>);</kbd></dt>
<dd>`villa' specifies a database handle connected as a writer.  The database of the handle must be empty.  `name' specifies the name of an input file.  If successful, the return value is true, else, it is false.</dd>
</dl>

<h3>Examples</h3>

<p>The following example stores and retrieves a phone number, using the name as the key.</p>

<pre>#include &lt;depot.h&gt;
#include &lt;cabin.h&gt;
#include &lt;villa.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;

#define NAME     "mikio"
#define NUMBER   "000-1234-5678"
#define DBNAME   "book"

int main(int argc, char **argv){
  VILLA *villa;
  char *val;

  /* open the database */
  if(!(villa = vlopen(DBNAME, VL_OWRITER | VL_OCREAT, VL_CMPLEX))){
    fprintf(stderr, "vlopen: %s\n", dperrmsg(dpecode));
    return 1;
  }

  /* store the record */
  if(!vlput(villa, NAME, -1, NUMBER, -1, VL_DOVER)){
    fprintf(stderr, "vlput: %s\n", dperrmsg(dpecode));
  }

  /* retrieve the record */
  if(!(val = vlget(villa, NAME, -1, NULL))){
    fprintf(stderr, "vlget: %s\n", dperrmsg(dpecode));
  } else {
    printf("Name: %s\n", NAME);
    printf("Number: %s\n", val);
    free(val);
  }

  /* close the database */
  if(!vlclose(villa)){
    fprintf(stderr, "vlclose: %s\n", dperrmsg(dpecode));
    return 1;
  }

  return 0;
}
</pre>

<p>The following example performs forward matching search for strings.</p>

<pre>#include &lt;depot.h&gt;
#include &lt;cabin.h&gt;
#include &lt;villa.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;

#define DBNAME   "words"
#define PREFIX   "apple"

int main(int argc, char **argv){
  VILLA *villa;
  char *key, *val;

  /* open the database */
  if(!(villa = vlopen(DBNAME, VL_OWRITER | VL_OCREAT, VL_CMPLEX))){
    fprintf(stderr, "vlopen: %s\n", dperrmsg(dpecode));
    return 1;
  }

  /* store records */
  if(!vlput(villa, "applet", -1, "little application", -1, VL_DDUP) ||
     !vlput(villa, "aurora", -1, "polar wonderwork", -1, VL_DDUP) ||
     !vlput(villa, "apple", -1, "delicious fruit", -1, VL_DDUP) ||
     !vlput(villa, "amigo", -1, "good friend", -1, VL_DDUP) ||
     !vlput(villa, "apple", -1, "big city", -1, VL_DDUP)){
    fprintf(stderr, "vlput: %s\n", dperrmsg(dpecode));
  }

  /* set the cursor at the top of candidates */
  vlcurjump(villa, PREFIX, -1, VL_JFORWARD);

  /* scan with the cursor */
  while((key = vlcurkey(villa, NULL)) != NULL){
    if(strstr(key, PREFIX) != key){
      free(key);
      break;
    }
    if(!(val = vlcurval(villa, NULL))){
      fprintf(stderr, "vlcurval: %s\n", dperrmsg(dpecode));
      free(key);
      break;
    }
    printf("%s: %s\n", key, val);
    free(val);
    free(key);
    vlcurnext(villa);
  }

  /* close the database */
  if(!vlclose(villa)){
    fprintf(stderr, "vlclose: %s\n", dperrmsg(dpecode));
    return 1;
  }

  return 0;
}
</pre>

<h3>Notes</h3>

<p>How to build programs using Villa is the same as the case of Depot.</p>

<pre>gcc -I/usr/local/include -o sample sample.c -L/usr/local/lib -lqdbm
</pre>

<p>If QDBM was built with POSIX thread enabled, the global variable `dpecode' is treated as thread specific data, and functions of Villa are reentrant.  In that case, they are thread-safe as long as a handle is not accessed by threads at the same time, on the assumption that `errno', `malloc', and so on are thread-safe.</p>

<h3>Vista: Extended Advanced API</h3>

<p>Vista is the extended API of Villa.  To compensate for the defect that Villa can not handle a file whose size is more than 2GB, Vista does not use Depot but Curia for handling its internal database.  While Vista provides data structure and operations of B+ tree as with Villa, its database is realized as a directory.</p>

<p>In order to use Vista, you should include `vista.h' instead of `villa.h'.  Because Vista is implemented by overriding symbols of Villa, it can be used as with Villa.  That is, Signatures of Villa and Vista is all the same.  However, as its adverse effect, modules (compilation unit) using Vista can not use Villa (do not include `villa.h').</p>

<hr />

<h2><a name="villacli" id="villacli" class="head">Commands for Villa</a></h2>

<p>Villa has the following command line interfaces.</p>

<p>The command `vlmgr' is a utility for debugging Villa and its applications.  It features editing and checking of a database.  It can be used for database applications with shell scripts.  This command is used in the following format.  `name' specifies a database name.  `key' specifies the key of a record.  `val' specifies the value of a record.</p>

<dl>
<dt><kbd>vlmgr create [-cz|-cy|-cx] <var>name</var></kbd></dt>
<dd>Create a database file.</dd>
<dt><kbd>vlmgr put [-kx|-ki] [-vx|-vi|-vf] [-keep|-cat|-dup] <var>name</var> <var>key</var> <var>val</var></kbd></dt>
<dd>Store a record with a key and a value.</dd>
<dt><kbd>vlmgr out [-l] [-kx|-ki] <var>name</var> <var>key</var></kbd></dt>
<dd>Delete a record with a key.</dd>
<dt><kbd>vlmgr get [-nl] [-l] [-kx|-ki] [-ox] [-n] <var>name</var> <var>key</var></kbd></dt>
<dd>Retrieve a record with a key and output it to the standard output.</dd>
<dt><kbd>vlmgr list [-nl] [-k|-v] [-kx|-ki] [-ox] [-top <var>key</var>] [-bot <var>key</var>] [-gt] [-lt] [-max <var>num</var>] [-desc] <var>name</var></kbd></dt>
<dd>List all keys and values delimited with tab and line-feed to the standard output.</dd>
<dt><kbd>vlmgr optimize <var>name</var></kbd></dt>
<dd>Optimize a database.</dd>
<dt><kbd>vlmgr inform [-nl] <var>name</var></kbd></dt>
<dd>Output miscellaneous information to the standard output.</dd>
<dt><kbd>vlmgr remove <var>name</var></kbd></dt>
<dd>Remove a database file.</dd>
<dt><kbd>vlmgr repair [-ki] <var>name</var></kbd></dt>
<dd>Repair a broken database file.</dd>
<dt><kbd>vlmgr exportdb [-ki] <var>name</var> <var>file</var></kbd></dt>
<dd>Dump all records as endian independent data.</dd>
<dt><kbd>vlmgr importdb [-ki] <var>name</var> <var>file</var></kbd></dt>
<dd>Load all records from endian independent data.</dd>
<dt><kbd>vlmgr version</kbd></dt>
<dd>Output version information of QDBM to the standard output.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-cz</kbd> : compress leaves in the database with ZLIB.</li>
<li><kbd>-cy</kbd> : compress leaves in the database with LZO.</li>
<li><kbd>-cx</kbd> : compress leaves in the database with BZIP2.</li>
<li><kbd>-l</kbd> : all records corresponding the key are dealt.</li>
<li><kbd>-kx</kbd> : treat `key' as a binary expression of hexadecimal notation.</li>
<li><kbd>-ki</kbd> : treat `key' as an integer expression of decimal notation.</li>
<li><kbd>-vx</kbd> : treat `val' as a binary expression of hexadecimal notation.</li>
<li><kbd>-vi</kbd> : treat `val' as an integer expression of decimal notation.</li>
<li><kbd>-vf</kbd> : read the value from a file specified with `val'.</li>
<li><kbd>-keep</kbd> : specify the storing mode for `VL_DKEEP'.</li>
<li><kbd>-cat</kbd> : specify the storing mode for `VL_DCAT'.</li>
<li><kbd>-dup</kbd> : specify the storing mode for `VL_DDUP'.</li>
<li><kbd>-nl</kbd> : open the database without file locking.</li>
<li><kbd>-top <var>key</var></kbd> : specify the top key of listing.</li>
<li><kbd>-bot <var>key</var></kbd> : specify the bottom key of listing.</li>
<li><kbd>-gt</kbd> : do not include the top key of listing.</li>
<li><kbd>-lt</kbd> : do not include the bottom key of listing.</li>
<li><kbd>-max <var>num</var></kbd> : specify the max number of listing.</li>
<li><kbd>-desc</kbd> : list in descending order.</li>
<li><kbd>-ox</kbd> : treat the output as a binary expression of hexadecimal notation.</li>
<li><kbd>-n</kbd> : do not output the tailing newline.</li>
<li><kbd>-k</kbd> : output keys only.</li>
<li><kbd>-v</kbd> : output values only.</li>
</ul>

<p>This command returns 0 on success, another on failure.  The environment variable `QDBMDBGFD' specifies the file descriptor to output the history of updating the variable `dpecode'.</p>

<p>The command `vltest' is a utility for facility test and performance test.  Check a database generated by the command or measure the execution time of the command.  This command is used in the following format.  `name' specifies a database name.  `rnum' specifies the number of the records.</p>

<dl>
<dt><kbd>vltest write [-int] [-cz|-cy|-cx] [-tune <var>lrecmax</var> <var>nidxmax</var> <var>lcnum</var> <var>ncnum</var>] [-fbp <var>num</var>] <var>name</var> <var>rnum</var></kbd></dt>
<dd>Store records with keys of 8 bytes.  They change as `00000001', `00000002'...</dd>
<dt><kbd>vltest read [-int] [-vc] <var>name</var></kbd></dt>
<dd>Retrieve all records of the database above.</dd>
<dt><kbd>vltest rdup [-int] [-cz|-cy|-cx] [-cc] [-tune <var>lrecmax</var> <var>nidxmax</var> <var>lcnum</var> <var>ncnum</var>] [-fbp <var>num</var>] <var>name</var> <var>rnum</var> <var>pnum</var></kbd></dt>
<dd>Store records with partway duplicated keys using duplicate mode.</dd>
<dt><kbd>vltest combo [-cz|-cy|-cx] <var>name</var></kbd></dt>
<dd>Perform combination test of various operations.</dd>
<dt><kbd>vltest wicked [-cz|-cy|-cx] <var>name</var> <var>rnum</var></kbd></dt>
<dd>Perform updating operations selected at random.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-int</kbd> : treat keys and values as objects of `int', and use comparing function `VL_CMPINT'.</li>
<li><kbd>-cz</kbd> : compress leaves in the database with ZLIB.</li>
<li><kbd>-cy</kbd> : compress leaves in the database with LZO.</li>
<li><kbd>-cx</kbd> : compress leaves in the database with BZIP2.</li>
<li><kbd>-vc</kbd> : refer to volatile cache.</li>
<li><kbd>-cc</kbd> : select `VL_DCAT' or `VL_DDUP' at random.</li>
<li><kbd>-tune <var>lrecmax</var> <var>nidxmax</var> <var>lcnum</var> <var>ncnum</var></kbd> : set tuning parameters.</li>
<li><kbd>-fbp <var>num</var></kbd> : set the size of the free block pool.</li>
<li><kbd>-c</kbd> : perform comparison test with map of Cabin.</li>
</ul>

<p>This command returns 0 on success, another on failure.  The environment variable `QDBMDBGFD' specifies the file descriptor to output the history of updating the variable `dpecode'.</p>

<p>The command `vltsv' features mutual conversion between a database of Villa and a TSV text.  This command is useful when data exchange with another version of QDBM or another DBM, or when data exchange between systems which have different byte orders.  This command is used in the following format.  `name' specifies a database name.  The subcommand `export' reads TSV data from the standard input.  The subcommand `import' writes TSV data to the standard output.</p>

<dl>
<dt><kbd>vltsv import [-bin] <var>name</var></kbd></dt>
<dd>Create a database from TSV.</dd>
<dt><kbd>vltsv export [-bin] <var>name</var></kbd></dt>
<dd>Write TSV data of a database.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-bin</kbd> : treat records as Base64 format.</li>
</ul>

<p>This command returns 0 on success, another on failure.</p>

<p>Commands of Villa realize a simple database system.  For example, to make a database to search `/etc/password' by a user name, perform the following command.</p>

<pre>cat /etc/passwd | tr ':' '\t' | vltsv import casket
</pre>

<p>Thus, to retrieve the information of a user `mikio', perform the following command.</p>

<pre>vlmgr get casket mikio
</pre>

<p>It is easy to implement functions upsides with these commands, using the API of Villa.</p>

<p>The command `qmttest' checks multi-thread safety of Depot, Curia, and Villa.  This command works with multi threads only if QDBM was built with POSIX thread.  This command is used in the following format.  `name' specifies the prefix of each database.  `rnum' specifies the number of records to be stored in each database.  `tnum' specifies the number of threads.</p>

<dl>
<dt><kbd>qmttest <var>name</var> <var>rnum</var> <var>tnum</var></kbd></dt>
<dd>Check multi-thread safety.</dd>
</dl>

<p>This command returns 0 on success, another on failure.</p>

<hr />

<h2><a name="odeumapi" id="odeumapi" class="head">Odeum: Inverted API</a></h2>

<h3>Overview</h3>

<p>Odeum is the API which handles an inverted index.  An inverted index is a data structure to retrieve a list of some documents that include one of words which were extracted from a population of documents.  It is easy to realize a full-text search system with an inverted index.  Odeum provides an abstract data structure which consists of words and attributes of a document.  It is used when an application stores a document into a database and when an application retrieves some documents from a database.</p>

<p>Odeum does not provide methods to extract the text from the original data of a document.  It should be implemented by applications.  Although Odeum provides utilities to extract words from a text, it is oriented to such languages whose words are separated with space characters as English.  If an application handles such languages which need morphological analysis or N-gram analysis as Japanese, or if an application perform more such rarefied analysis of natural languages as stemming, its own analyzing method can be adopted.  Result of search is expressed as an array contains elements which are structures composed of the ID number of documents and its score.  In order to search with two or more words, Odeum provides utilities of set operations.</p>

<p>Odeum is implemented, based on Curia, Cabin, and Villa.  Odeum creates a database with a directory name.  Some databases of Curia and Villa are placed in the specified directory.  For example, `casket/docs', `casket/index', and `casket/rdocs' are created in the case that a database directory named as `casket'.  `docs' is a database directory of Curia.  The key of each record is the ID number of a document, and the value is such attributes as URI.  `index' is a database directory of Curia.  The key of each record is the normalized form of a word, and the value is an array whose element is a pair of the ID number of a document including the word and its score.  `rdocs' is a database file of Villa.  The key of each record is the URI of a document, and the value is its ID number.</p>

<p>In order to use Odeum, you should include `depot.h', `cabin.h', `odeum.h' and `stdlib.h' in the source files.  Usually, the following description will be near the beginning of a source file.</p>

<dl>
<dt><kbd>#include &lt;depot.h&gt;</kbd></dt>
<dt><kbd>#include &lt;cabin.h&gt;</kbd></dt>
<dt><kbd>#include &lt;odeum.h&gt;</kbd></dt>
<dt><kbd>#include &lt;stdlib.h&gt;</kbd></dt>
</dl>

<p>A pointer to `ODEUM' is used as a database handle.  A database handle is opened with the function `odopen' and closed with `odclose'.  You should not refer directly to any member of the handle.  If a fatal error occurs in a database, any access method via the handle except `odclose' will not work and return error status.  Although a process is allowed to use multiple database handles at the same time, handles of the same database file should not be used.</p>

<p>A pointer to `ODDOC' is used as a document handle.  A document handle is opened with the function `oddocopen' and closed with `oddocclose'.  You should not refer directly to any member of the handle.  A document consists of attributes and words.  Each word is expressed as a pair of a normalized form and a appearance form.</p>

<p>Odeum also assign the external variable `dpecode' with the error code. The function `dperrmsg' is used in order to get the message of the error code.</p>

<h3>API</h3>

<p>Structures of `ODPAIR' type is used in order to handle results of search.</p>

<dl>
<dt><kbd>typedef struct { int id; int score; } ODPAIR;</kbd></dt>
<dd>`id' specifies the ID number of a document.  `score' specifies the score calculated from the number of searching words in the document.</dd>
</dl>

<p>The function `odopen' is used in order to get a database handle.</p>

<dl>
<dt><kbd>ODEUM *odopen(const char *<var>name</var>, int <var>omode</var>);</kbd></dt>
<dd>`name' specifies the name of a database directory.  `omode' specifies the connection mode: `OD_OWRITER' as a writer, `OD_OREADER' as a reader.  If the mode is `OD_OWRITER', the following may be added by bitwise or: `OD_OCREAT', which means it creates a new database if not exist, `OD_OTRUNC', which means it creates a new database regardless if one exists.  Both of `OD_OREADER' and `OD_OWRITER' can be added to by bitwise or: `OD_ONOLCK', which means it opens a database directory without file locking, or `OD_OLCKNB', which means locking is performed without blocking.  The return value is the database handle or `NULL' if it is not successful.  While connecting as a writer, an exclusive lock is invoked to the database directory.  While connecting as a reader, a shared lock is invoked to the database directory.  The thread blocks until the lock is achieved.  If `OD_ONOLCK' is used, the application is responsible for exclusion control.</dd>
</dl>

<p>The function `odclose' is used in order to close a database handle.</p>

<dl>
<dt><kbd>int odclose(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  If successful, the return value is true, else, it is false.  Because the region of a closed handle is released, it becomes impossible to use the handle.  Updating a database is assured to be written when the handle is closed.  If a writer opens a database but does not close it appropriately, the database will be broken.</dd>
</dl>

<p>The function `odput' is used in order to store a document.</p>

<dl>
<dt><kbd>int odput(ODEUM *<var>odeum</var>, const ODDOC *<var>doc</var>, int <var>wmax</var>, int <var>over</var>);</kbd></dt>
<dd>`odeum' specifies a database handle connected as a writer.  `doc' specifies a document handle.  `wmax' specifies the max number of words to be stored in the document database.  If it is negative, the number is unlimited.  `over' specifies whether the data of the duplicated document is overwritten or not.  If it is false and the URI of the document is duplicated, the function returns as an error.  If successful, the return value is true, else, it is false.</dd>
</dl>

<p>The function `odout' is used in order to delete a document specified by a URI.</p>

<dl>
<dt><kbd>int odout(ODEUM *<var>odeum</var>, const char *<var>uri</var>);</kbd></dt>
<dd>`odeum' specifies a database handle connected as a writer.  `uri' specifies the string of the URI of a document.  If successful, the return value is true, else, it is false.  False is returned when no document corresponds to the specified URI.</dd>
</dl>

<p>The function `odoutbyid' is used in order to delete a document specified by an ID number.</p>

<dl>
<dt><kbd>int odoutbyid(ODEUM *<var>odeum</var>, int <var>id</var>);</kbd></dt>
<dd>`odeum' specifies a database handle connected as a writer.  `id' specifies the ID number of a document.  If successful, the return value is true, else, it is false.  False is returned when no document corresponds to the specified ID number.</dd>
</dl>

<p>The function `odget' is used in order to retrieve a document specified by a URI.</p>

<dl>
<dt><kbd>ODDOC *odget(ODEUM *<var>odeum</var>, const char *<var>uri</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  `uri' specifies the string of the URI of a document.  If successful, the return value is the handle of the corresponding document, else, it is `NULL'.  `NULL' is returned when no document corresponds to the specified URI.  Because the handle of the return value is opened with the function `oddocopen', it should be closed with the function `oddocclose'.</dd>
</dl>

<p>The function `odgetbyid' is used in order to retrieve a document by an ID number.</p>

<dl>
<dt><kbd>ODDOC *odgetbyid(ODEUM *<var>odeum</var>, int <var>id</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  `id' specifies the ID number of a document.  If successful, the return value is the handle of the corresponding document, else, it is `NULL'.  `NULL' is returned when no document corresponds to the specified ID number.  Because the handle of the return value is opened with the function `oddocopen', it should be closed with the function `oddocclose'.</dd>
</dl>

<p>The function `odgetidbyuri' is used in order to retrieve the ID of the document specified by a URI.</p>

<dl>
<dt><kbd>int odgetidbyuri(ODEUM *<var>odeum</var>, const char *<var>uri</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  `uri' specifies the string the URI of a document.  If successful, the return value is the ID number of the document, else, it is -1.  -1 is returned when no document corresponds to the specified URI.</dd>
</dl>

<p>The function `odcheck' is used in order to check whether the document specified by an ID number exists.</p>

<dl>
<dt><kbd>int odcheck(ODEUM *<var>odeum</var>, int <var>id</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  `id' specifies the ID number of a document.  The return value is true if the document exists, else, it is false.</dd>
</dl>

<p>The function `odsearch' is used in order to search the inverted index for documents including a particular word.</p>

<dl>
<dt><kbd>ODPAIR *odsearch(ODEUM *<var>odeum</var>, const char *<var>word</var>, int <var>max</var>, int *<var>np</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  `word' specifies a searching word.  `max' specifies the max number of documents to be retrieve.  `np' specifies the pointer to a variable to which the number of the elements of the return value is assigned.  If successful, the return value is the pointer to an array, else, it is `NULL'.  Each element of the array is a pair of the ID number and the score of a document, and sorted in descending order of their scores.  Even if no document corresponds to the specified word, it is not error but returns an dummy array.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  Note that each element of the array of the return value can be data of a deleted document.</dd>
</dl>

<p>The function `odsearchnum' is used in order to get the number of documents including a word.</p>

<dl>
<dt><kbd>int odsearchdnum(ODEUM *<var>odeum</var>, const char *<var>word</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  `word' specifies a searching word.  If successful, the return value is the number of documents including the word, else, it is -1.  Because this function does not read the entity of the inverted index, it is faster than `odsearch'.</dd>
</dl>

<p>The function `oditerinit' is used in order to initialize the iterator of a database handle.</p>

<dl>
<dt><kbd>int oditerinit(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  If successful, the return value is true, else, it is false.  The iterator is used in order to access every document stored in a database.</dd>
</dl>

<p>The function `oditernext' is used in order to get the next key of the iterator.</p>

<dl>
<dt><kbd>ODDOC *oditernext(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  If successful, the return value is the handle of the next document, else, it is `NULL'.  `NULL' is returned when no document is to be get out of the iterator.  It is possible to access every document by iteration of calling this function.  However, it is not assured if updating the database is occurred while the iteration.  Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of string matches the one of the traversal access.  Because the handle of the return value is opened with the function `oddocopen', it should be closed with the function `oddocclose'.</dd>
</dl>

<p>The function `odsync' is used in order to synchronize updating contents with the files and the devices.</p>

<dl>
<dt><kbd>int odsync(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle connected as a writer.  If successful, the return value is true, else, it is false.  This function is useful when another process uses the connected database directory.</dd>
</dl>

<p>The function `odoptimize' is used in order to optimize a database.</p>

<dl>
<dt><kbd>int odoptimize(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle connected as a writer.  If successful, the return value is true, else, it is false.  Elements of the deleted documents in the inverted index are purged.</dd>
</dl>

<p>The function `odname' is used in order to get the name of a database.</p>

<dl>
<dt><kbd>char *odname(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  If successful, the return value is the pointer to the region of the name of the database, else, it is `NULL'.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `odfsiz' is used in order to get the total size of database files.</p>

<dl>
<dt><kbd>double odfsiz(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  If successful, the return value is the total size of the database files, else, it is -1.0.</dd>
</dl>

<p>The function `odbnum' is used in order to get the total number of the elements of the bucket arrays in the inverted index.</p>

<dl>
<dt><kbd>int odbnum(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  If successful, the return value is the total number of the elements of the bucket arrays, else, it is -1.</dd>
</dl>

<p>The function `odbusenum' is used in order to get the total number of the used elements of the bucket arrays in the inverted index.</p>

<dl>
<dt><kbd>int odbusenum(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  If successful, the return value is the total number of the used elements of the bucket arrays, else, it is -1.</dd>
</dl>

<p>The function `oddnum' is used in order to get the number of the documents stored in a database.</p>

<dl>
<dt><kbd>int oddnum(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  If successful, the return value is the number of the documents stored in the database, else, it is -1.</dd>
</dl>

<p>The function `odwnum' is used in order to get the number of the words stored in a database.</p>

<dl>
<dt><kbd>int odwnum(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  If successful, the return value is the number of the words stored in the database, else, it is -1.  Because of the I/O buffer, the return value may be less than the hard number.</dd>
</dl>

<p>The function `odwritable' is used in order to check whether a database handle is a writer or not.</p>

<dl>
<dt><kbd>int odwritable(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  The return value is true if the handle is a writer, false if not.</dd>
</dl>

<p>The function `odfatalerror' is used in order to check whether a database has a fatal error or not.</p>

<dl>
<dt><kbd>int odfatalerror(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  The return value is true if the database has a fatal error, false if not.</dd>
</dl>

<p>The function `odinode' is used in order to get the inode number of a database directory.</p>

<dl>
<dt><kbd>int odinode(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  The return value is the inode number of the database directory.</dd>
</dl>

<p>The function `odmtime' is used in order to get the last modified time of a database.</p>

<dl>
<dt><kbd>time_t odmtime(ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  The return value is the last modified time of the database.</dd>
</dl>

<p>The function `odmerge' is used in order to merge plural database directories.</p>

<dl>
<dt><kbd>int odmerge(const char *<var>name</var>, const CBLIST *<var>elemnames</var>);</kbd></dt>
<dd>`name' specifies the name of a database directory to create.  `elemnames' specifies a list of names of element databases.  If successful, the return value is true, else, it is false.  If two or more documents which have the same URL come in, the first one is adopted and the others are ignored.</dd>
</dl>

<p>The function `odremove' is used in order to remove a database directory.</p>

<dl>
<dt><kbd>int odremove(const char *<var>name</var>);</kbd></dt>
<dd>`name' specifies the name of a database directory.  If successful, the return value is true, else, it is false.  A database directory can contain databases of other APIs of QDBM, they are also removed by this function.</dd>
</dl>

<p>The function `oddocopen' is used in order to get a document handle.</p>

<dl>
<dt><kbd>ODDOC *oddocopen(const char *<var>uri</var>);</kbd></dt>
<dd>`uri' specifies the URI of a document.  The return value is a document handle.  The ID number of a new document is not defined.  It is defined when the document is stored in a database.</dd>
</dl>

<p>The function `oddocclose' is used in order to close a document handle.</p>

<dl>
<dt><kbd>void oddocclose(ODDOC *<var>doc</var>);</kbd></dt>
<dd>`doc' specifies a document handle.  Because the region of a closed handle is released, it becomes impossible to use the handle.</dd>
</dl>

<p>The function `oddocaddattr' is used in order to add an attribute to a document.</p>

<dl>
<dt><kbd>void oddocaddattr(ODDOC *<var>doc</var>, const char *<var>name</var>, const char *<var>value</var>);</kbd></dt>
<dd>`doc' specifies a document handle.  `name' specifies the string of the name of an attribute.  `value' specifies the string of the value of the attribute.</dd>
</dl>

<p>The function `oddocaddword' is used in order to add a word to a document.</p>

<dl>
<dt><kbd>void oddocaddword(ODDOC *<var>doc</var>, const char *<var>normal</var>, const char *<var>asis</var>);</kbd></dt>
<dd>`doc' specifies a document handle.  `normal' specifies the string of the normalized form of a word.  Normalized forms are treated as keys of the inverted index.  If the normalized form of a word is an empty string, the word is not reflected in the inverted index.  `asis' specifies the string of the appearance form of the word.  Appearance forms are used after the document is retrieved by an application.</dd>
</dl>

<p>The function `oddocid' is used in order to get the ID number of a document.</p>

<dl>
<dt><kbd>int oddocid(const ODDOC *<var>doc</var>);</kbd></dt>
<dd>`doc' specifies a document handle.  The return value is the ID number of a document.</dd>
</dl>

<p>The function `oddocuri' is used in order to get the URI of a document.</p>

<dl>
<dt><kbd>const char *oddocuri(const ODDOC *<var>doc</var>);</kbd></dt>
<dd>`doc' specifies a document handle.  The return value is the string of the URI of a document.</dd>
</dl>

<p>The function `oddocgetattr' is used in order to get the value of an attribute of a document.</p>

<dl>
<dt><kbd>const char *oddocgetattr(const ODDOC *<var>doc</var>, const char *<var>name</var>);</kbd></dt>
<dd>`doc' specifies a document handle.  `name' specifies the string of the name of an attribute.  The return value is the string of the value of the attribute, or `NULL' if no attribute corresponds.</dd>
</dl>

<p>The function `oddocnwords' is used in order to get the list handle contains words in normalized form of a document.</p>

<dl>
<dt><kbd>const CBLIST *oddocnwords(const ODDOC *<var>doc</var>);</kbd></dt>
<dd>`doc' specifies a document handle.  The return value is the list handle contains words in normalized form.</dd>
</dl>

<p>The function `oddocawords' is used in order to get the list handle contains words in appearance form of a document.</p>

<dl>
<dt><kbd>const CBLIST *oddocawords(const ODDOC *<var>doc</var>);</kbd></dt>
<dd>`doc' specifies a document handle.  The return value is the list handle contains words in appearance form.</dd>
</dl>

<p>The function `oddocscores' is used in order to get the map handle contains keywords in normalized form and their scores.</p>

<dl>
<dt><kbd>CBMAP *oddocscores(const ODDOC *<var>doc</var>, int <var>max</var>, ODEUM *<var>odeum</var>);</kbd></dt>
<dd>`doc' specifies a document handle.  `max' specifies the max number of keywords to get.  `odeum' specifies a database handle with which the IDF for weighting is calculate.  If it is `NULL', it is not used.  The return value is the map handle contains keywords and their scores.  Scores are expressed as decimal strings.  Because the handle of the return value is opened with the function `cbmapopen', it should be closed with the function `cbmapclose' if it is no longer in use.</dd>
</dl>

<p>The function `odbreaktext' is used in order to break a text into words in appearance form.</p>

<dl>
<dt><kbd>CBLIST *odbreaktext(const char *<var>text</var>);</kbd></dt>
<dd>`text' specifies the string of a text.  The return value is the list handle contains words in appearance form.  Words are separated with space characters and such delimiters as period, comma and so on.  Because the handle of the return value is opened with the function `cblistopen', it should be closed with the function `cblistclose' if it is no longer in use.</dd>
</dl>

<p>The function `odnormalizeword' is used in order to make the normalized form of a word.</p>

<dl>
<dt><kbd>char *odnormalizeword(const char *<var>asis</var>);</kbd></dt>
<dd>`asis' specifies the string of the appearance form of a word.  The return value is is the string of the normalized form of the word.  Alphabets of the ASCII code are unified into lower cases.  Words composed of only delimiters are treated as empty strings.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `odpairsand' is used in order to get the common elements of two sets of documents.</p>

<dl>
<dt><kbd>ODPAIR *odpairsand(ODPAIR *<var>apairs</var>, int <var>anum</var>, ODPAIR *<var>bpairs</var>, int <var>bnum</var>, int *<var>np</var>);</kbd></dt>
<dd>`apairs' specifies the pointer to the former document array.  `anum' specifies the number of the elements of the former document array.  `bpairs' specifies the pointer to the latter document array.  `bnum' specifies the number of the elements of the latter document array.  `np' specifies the pointer to a variable to which the number of the elements of the return value is assigned.  The return value is the pointer to a new document array whose elements commonly belong to the specified two sets.  Elements of the array are sorted in descending order of their scores.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `odpairsor' is used in order to get the sum of elements of two sets of documents.</p>

<dl>
<dt><kbd>ODPAIR *odpairsor(ODPAIR *<var>apairs</var>, int <var>anum</var>, ODPAIR *<var>bpairs</var>, int <var>bnum</var>, int *<var>np</var>);</kbd></dt>
<dd>`apairs' specifies the pointer to the former document array.  `anum' specifies the number of the elements of the former document array.  `bpairs' specifies the pointer to the latter document array.  `bnum' specifies the number of the elements of the latter document array.  `np' specifies the pointer to a variable to which the number of the elements of the return value is assigned.  The return value is the pointer to a new document array whose elements belong to both or either of the specified two sets.  Elements of the array are sorted in descending order of their scores.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `odpairsnotand' is used in order to get the difference set of documents.</p>

<dl>
<dt><kbd>ODPAIR *odpairsnotand(ODPAIR *<var>apairs</var>, int <var>anum</var>, ODPAIR *<var>bpairs</var>, int <var>bnum</var>, int *<var>np</var>);</kbd></dt>
<dd>`apairs' specifies the pointer to the former document array.  `anum' specifies the number of the elements of the former document array.  `bpairs' specifies the pointer to the latter document array of the sum of elements.  `bnum' specifies the number of the elements of the latter document array.  `np' specifies the pointer to a variable to which the number of the elements of the return value is assigned.  The return value is the pointer to a new document array whose elements belong to the former set but not to the latter set.  Elements of the array are sorted in descending order of their scores.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.</dd>
</dl>

<p>The function `odpairssort' is used in order to sort a set of documents in descending order of scores.</p>

<dl>
<dt><kbd>void odpairssort(ODPAIR *<var>pairs</var>, int <var>pnum</var>);</kbd></dt>
<dd>`pairs' specifies the pointer to a document array.  `pnum' specifies the number of the elements of the document array.</dd>
</dl>

<p>The function `odlogarithm' is used in order to get the natural logarithm of a number.</p>

<dl>
<dt><kbd>double odlogarithm(double <var>x</var>);</kbd></dt>
<dd>`x' specifies a number.  The return value is the natural logarithm of the number.  If the number is equal to or less than 1.0, the return value is 0.0.  This function is useful when an application calculates the IDF of search results.</dd>
</dl>

<p>The function `odvectorcosine' is used in order to get the cosine of the angle of two vectors.</p>

<dl>
<dt><kbd>double odvectorcosine(const int *<var>avec</var>, const int *<var>bvec</var>, int <var>vnum</var>);</kbd></dt>
<dd>`avec' specifies the pointer to one array of numbers.  `bvec' specifies the pointer to the other array of numbers.  `vnum' specifies the number of elements of each array.  The return value is the cosine of the angle of two vectors.  This function is useful when an application calculates similarity of documents.</dd>
</dl>

<p>The function `odsettuning' is used in order to set the global tuning parameters.</p>

<dl>
<dt><kbd>void odsettuning(int <var>ibnum</var>, int <var>idnum</var>, int <var>cbnum</var>, int <var>csiz</var>);</kbd></dt>
<dd>`ibnum' specifies the number of buckets for inverted indexes.  `idnum' specifies the division number of inverted index.  `cbnum' specifies the number of buckets for dirty buffers.  `csiz' specifies the maximum bytes to use memory for dirty buffers.  The default setting is equivalent to `odsettuning(32749, 7, 262139, 8388608)'.  This function should be called before opening a handle.</dd>
</dl>

<p>The function `odanalyzetext' is used in order to break a text into words and store appearance forms and normalized form into lists.</p>

<dl>
<dt><kbd>void odanalyzetext(ODEUM *<var>odeum</var>, const char *<var>text</var>, CBLIST *<var>awords</var>, CBLIST *<var>nwords</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  `text' specifies the string of a text.  `awords' specifies a list handle into which appearance form is store.  `nwords' specifies a list handle into which normalized form is store.  If it is `NULL', it is ignored.  Words are separated with space characters and such delimiters as period, comma and so on.</dd>
</dl>

<p>The function `odsetcharclass' is used in order to set the classes of characters used by `odanalyzetext'.</p>

<dl>
<dt><kbd>void odsetcharclass(ODEUM *<var>odeum</var>, const char *<var>spacechars</var>, const char *<var>delimchars</var>, const char *<var>gluechars</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  `spacechars' spacifies a string contains space characters.  `delimchars' spacifies a string contains delimiter characters.  `gluechars' spacifies a string contains glue characters.</dd>
</dl>

<p>The function `odquery' is used in order to query a database using a small boolean query language.</p>

<dl>
<dt><kbd>ODPAIR *odquery(ODEUM *<var>odeum</var>, const char *<var>query</var>, int *<var>np</var>, CBLIST *<var>errors</var>);</kbd></dt>
<dd>`odeum' specifies a database handle.  'query' specifies the text of the query.  `np' specifies the pointer to a variable to which the number of the elements of the return value is assigned.  `errors' specifies a list handle into which error messages are stored.  If it is `NULL', it is ignored.  If successful, the return value is the pointer to an array, else, it is `NULL'.  Each element of the array is a pair of the ID number and the score of a document, and sorted in descending order of their scores.  Even if no document corresponds to the specified condition, it is not error but returns an dummy array.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.  Note that each element of the array of the return value can be data of a deleted document.</dd>
</dl>

<h3>Examples</h3>

<p>The following example stores a document into the database.</p>

<pre>#include &lt;depot.h&gt;
#include &lt;cabin.h&gt;
#include &lt;odeum.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;

#define DBNAME   "index"

int main(int argc, char **argv){
  ODEUM *odeum;
  ODDOC *doc;
  CBLIST *awords;
  const char *asis;
  char *normal;
  int i;

  /* open the database */
  if(!(odeum = odopen(DBNAME, OD_OWRITER | OD_OCREAT))){
    fprintf(stderr, "odopen: %s\n", dperrmsg(dpecode));
    return 1;
  }

  /* get the document handle */
  doc = oddocopen("http://www.foo.bar/baz.txt");

  /* set attributes of the document */
  oddocaddattr(doc, "title", "Balcony Scene");
  oddocaddattr(doc, "author", "Shakespeare");

  /* break the text and get the word list */
  awords = odbreaktext("Parting is such sweet sorrow.");

  /* set each word into the document handle */
  for(i = 0; i &lt; cblistnum(awords); i++){
    /* get one word of the list */
    asis = cblistval(awords, i, NULL);
    /* get the normalized form from the appearance form */
    normal = odnormalizeword(asis);
    /* add the word into the document handle */
    oddocaddword(doc, normal, asis);
    /* release the region of the normalized form */
    free(normal);
  }

  /* store the document into the database */
  if(!odput(odeum, doc, -1, 1)){
    fprintf(stderr, "odput: %s\n", dperrmsg(dpecode));
  }

  /* release the word list */
  cblistclose(awords);

  /* release the document handle */
  oddocclose(doc);

  /* close the database */
  if(!odclose(odeum)){
    fprintf(stderr, "odclose: %s\n", dperrmsg(dpecode));
    return 1;
  }

  return 0;
}
</pre>

<p>The following example retrieves documents.</p>

<pre>#include &lt;depot.h&gt;
#include &lt;cabin.h&gt;
#include &lt;odeum.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;

#define DBNAME   "index"

int main(int argc, char **argv){
  ODEUM *odeum;
  ODPAIR *pairs;
  ODDOC *doc;
  const CBLIST *words;
  const char *title, *author, *asis;
  int i, j, pnum;

  /* open the database */
  if(!(odeum = odopen(DBNAME, OD_OREADER))){
    fprintf(stderr, "odopen: %s\n", dperrmsg(dpecode));
    return 1;
  }

  /* retrieve documents */
  if((pairs = odsearch(odeum, "sorrow", -1, &amp;pnum)) != NULL){

    /* scan each element of the document array */
    for(i = 0; i &lt; pnum; i++){
      /* get the document handle */
      if(!(doc = odgetbyid(odeum, pairs[i].id))) continue;
      /* show the attributes */
      printf("URI: %s\n", oddocuri(doc));
      title = oddocgetattr(doc, "title");
      if(title) printf("TITLE: %s\n", title);
      author = oddocgetattr(doc, "author");
      if(author) printf("AUTHOR: %s\n", author);
      /* show words in appearance form */
      printf("WORDS:");
      words = oddocawords(doc);
      for(j = 0; j &lt; cblistnum(words); j++){
        asis = cblistval(words, j, NULL);
        printf(" %s", asis);
      }
      putchar('\n');
      /* release the document handle */
      oddocclose(doc);
    }

    /* release the document array */
    free(pairs);

  } else {
    fprintf(stderr, "odsearch: %s\n", dperrmsg(dpecode));
  }

  /* close the database */
  if(!odclose(odeum)){
    fprintf(stderr, "odclose: %s\n", dperrmsg(dpecode));
    return 1;
  }

  return 0;
}
</pre>

<h3>Notes</h3>

<p>How to build programs using Odeum is the same as the case of Depot.</p>

<pre>gcc -I/usr/local/include -o sample sample.c -L/usr/local/lib -lqdbm
</pre>

<p>If QDBM was built with POSIX thread enabled, the global variable `dpecode' is treated as thread specific data, and functions of Odeum are reentrant.  In that case, they are thread-safe as long as a handle is not accessed by threads at the same time, on the assumption that `errno', `malloc', and so on are thread-safe.</p>

<p>If QDBM was built with ZLIB enabled, records in the database for document attributes are compressed.  In that case, the size of the database is reduced to 30% or less.  Thus, you should enable ZLIB if you use Odeum.  A database of Odeum created without ZLIB enabled is not available on environment with ZLIB enabled, and vice versa.  If ZLIB was not enabled but LZO, LZO is used instead.</p>

<h3>Query Language</h3>

<p>The query language of the function `odquery' is a basic language following this grammar:</p>

<pre>expr ::= subexpr ( op subexpr )*
subexpr ::= WORD
subexpr ::= LPAREN expr RPAREN
</pre>

<p>Operators are "&amp;" (AND), "|" (OR), and "!" (NOTAND).  You can use parenthesis to group sub-expressions together in order to change order of operations.  The given query is broken up using the function `odanalyzetext', so if you want to specify different text breaking rules, then make sure that you at least set "&amp;", "|", "!", "(", and ")" to be delimiter characters.  Consecutive words are treated as having an implicit "&amp;" operator between them, so "zed shaw" is actually "zed &amp; shaw".</p>

<p>The encoding of the query text should be the same with the encoding of target documents.  Moreover, each of space characters, delimiter characters, and glue characters should be single byte.</p>

<hr />

<h2><a name="odeumcli" id="odeumcli" class="head">Commands for Odeum</a></h2>

<p>Odeum has the following command line interfaces.</p>

<p>The command `odmgr' is a utility for debugging Odeum and its applications.  It features editing and checking of a database.  It can be used for full-text search systems with shell scripts.  This command is used in the following format.  `name' specifies a database name.  `file' specifies a file name, `expr' specifies the URI or the ID number of a document, `words' specifies searching words.  `elems' specifies element databases.</p>

<dl>
<dt><kbd>odmgr create <var>name</var></kbd></dt>
<dd>Create a database file.</dd>
<dt><kbd>odmgr put [-uri <var>str</var>] [-title <var>str</var>] [-author <var>str</var>] [-date <var>str</var>] [-wmax <var>num</var>] [-keep] <var>name</var> [<var>file</var>]</kbd></dt>
<dd>Add a document by reading a file.  If `file' is omitted, the standard input is read and URI is needed.</dd>
<dt><kbd>odmgr out [-id] <var>name</var> <var>expr</var></kbd></dt>
<dd>Delete a document specified by a URI.</dd>
<dt><kbd>odmgr get [-id] [-t|-h] <var>name</var> <var>expr</var></kbd></dt>
<dd>Show a document specified by a URI.  The output is the ID number and the URI of a document, in tab separated format.</dd>
<dt><kbd>odmgr search [-max <var>num</var>] [-or] [-idf] [-t|-h|-n] <var>name</var> <var>words</var>...</kbd></dt>
<dd>Retrieve documents including specified words.  The first line of the output is the total number of hits and each word with its number of hits, in tab separated format.  The second line and below are the ID numbers and the scores of documents, in tab separated format.</dd>
<dt><kbd>odmgr list [-t|-h] <var>name</var></kbd></dt>
<dd>Show all documents in a database.  Each line of the output is the ID number and the score of a document, in tab separated format.</dd>
<dt><kbd>odmgr optimize <var>name</var></kbd></dt>
<dd>Optimize a database.</dd>
<dt><kbd>odmgr inform <var>name</var></kbd></dt>
<dd>Output miscellaneous information.</dd>
<dt><kbd>odmgr merge <var>name</var> <var>elems</var>...</kbd></dt>
<dd>Merge plural databases.</dd>
<dt><kbd>odmgr remove <var>name</var></kbd></dt>
<dd>Remove a database directory.</dd>
<dt><kbd>odmgr break [-h|-k|-s] [<var>file</var>]</kbd></dt>
<dd>Read a file and output words in the text.  Each line of the output is the appearance form and the normalized form of a word, in tab separated format.</dd>
<dt><kbd>odmgr version</kbd></dt>
<dd>Output version information of QDBM.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-uri <var>str</var></kbd> : specify the URI of the document explicitly.</li>
<li><kbd>-title <var>str</var></kbd> : specify the title of the document.</li>
<li><kbd>-author <var>str</var></kbd> : specify the author of the document.</li>
<li><kbd>-date <var>str</var></kbd> : specify the modified date of the document.</li>
<li><kbd>-wmax <var>num</var></kbd> : specify the max number of words to be stored.</li>
<li><kbd>-keep</kbd> : the storing mode is not to be overwrite.</li>
<li><kbd>-id</kbd> : specify a document not by a URI but by an ID number.</li>
<li><kbd>-t</kbd> : output the details of a document in tab separated format.</li>
<li><kbd>-h</kbd> : output the details of a document in human-readable format.</li>
<li><kbd>-k</kbd> : output keywords of a document.</li>
<li><kbd>-s</kbd> : output summary of a document.</li>
<li><kbd>-max <var>num</var></kbd> : specify the max number of documents of the output.</li>
<li><kbd>-or</kbd> : perform OR search, nut AND search.</li>
<li><kbd>-idf</kbd> : tune scores with IDF.</li>
<li><kbd>-n</kbd> : show ID numbers and scores only.</li>
</ul>

<p>This command returns 0 on success, another on failure.  The environment variable `QDBMDBGFD' specifies the file descriptor to output the history of updating the variable `dpecode'.</p>

<p>The command `odtest' is a utility for facility test and performance test.  Check a database generated by the command or measure the execution time of the command.  This command is used in the following format.  `name' specifies a database name.  `dnum' specifies the number of the documents.  `wnum' specifies the number of words per document.  `pnum' specifies the number of patterns of words.</p>

<dl>
<dt><kbd>odtest write [-tune <var>ibnum</var> <var>idnum</var> <var>cbnum</var> <var>csiz</var>] <var>name</var> <var>dnum</var> <var>wnum</var> <var>pnum</var></kbd></dt>
<dd>Store documents with random attributes and random words.</dd>
<dt><kbd>odtest read <var>name</var></kbd></dt>
<dd>Retrieve all documents of the database above.</dd>
<dt><kbd>odtest combo <var>name</var></kbd></dt>
<dd>Perform combination test of various operations.</dd>
<dt><kbd>odtest wicked <var>name</var> <var>dnum</var></kbd></dt>
<dd>Perform updating operations selected at random.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-tune <var>ibnum</var> <var>idnum</var> <var>cbnum</var> <var>csiz</var></kbd> : set tuning parameters.</li>
</ul>

<p>This command returns 0 on success, another on failure.  The environment variable `QDBMDBGFD' specifies the file descriptor to output the history of updating the variable `dpecode'.</p>

<p>The command `odidx' is a utility for indexing files on the local file system.  This command is useful for a full-text search system of a Web site.  Supported file format are plain text and HTML.  Supported character encoding are US-ASCII and ISO-8859-1.  The URI of each document is specified with the path of its file.  Attributes named as `title' and `date' are given to each documents.  When a document is already existing in the database, it is registered if its last modification time is newer, or it is ignored.  Modification times are stored in the sub database `_mtime' in the main database directory.  Score information are stored in the sub database `_score' in the main database directory.  This command is used in the following format.  `name' specifies a database name.  `dir' specifies a directory name.</p>

<dl>
<dt><kbd>odidx register [-l <var>file</var>] [-wmax <var>num</var>] [-tsuf <var>sufs</var>] [-hsuf <var>sufs</var>] <var>name</var> [<var>dir</var>]</kbd></dt>
<dd>Register files in the specified directory.  If `dir' is omitted, the current directory is specified.</dd>
<dt><kbd>odidx relate <var>name</var></kbd></dt>
<dd>Add score information for relational document search to each documents in the database.</dd>
<dt><kbd>odidx purge <var>name</var></kbd></dt>
<dd>Purge documents which are not existing on the local files system.</dd>
</dl>

<p>Options feature the following.</p>

<ul class="lines">
<li><kbd>-l <var>file</var></kbd> : read a file and get list of paths of files to register.  If `-' is specified, the standard input is read.</li>
<li><kbd>-wmax <var>num</var></kbd> : specify the max number of words to be stored in the document database.</li>
<li><kbd>-tsuf <var>sufs</var></kbd> : specify suffixes of plain text files in comma separated format.  The default is `-tsuf .txt,.text'.</li>
<li><kbd>-hsuf <var>sufs</var></kbd> : specify suffixes of HTML files in comma separated format.  The default is `-hsuf .html,.htm'.</li>
</ul>

<p>This command returns 0 on success, another on failure.</p>

<p>Commands of Odeum make it easy to realize a full-text search system.  For example, to register files which are under `/home/mikio' and whose suffix are `.txt', `.c', or `.h', perform the following command.</p>

<pre>odidx register -tsuf ".txt,.c,.h" -hsuf "" casket /home/mikio
</pre>

<p>Thus, to retrieve documents which include `unix' and `posix' and show the top 8 terms, perform the following command.</p>

<pre>odmgr search -max 8 -h casket "unix posix"
</pre>

<p>A database generated by `odidx' is available with the CGI script which is included in QDBM for full-text search.</p>

<hr />

<h2><a name="fileformat" id="fileformat" class="head">File Format</a></h2>

<h3>File Format of Depot</h3>

<p>The contents of a database file managed by Depot is divided roughly into the following three sections: the header section, the bucket section and the record section.</p>

<p>The header section places at the beginning of the file and its length is constant 48 bytes.  The following information are stored in the header section.</p>

<ol>
<li>magic number: from offset 0, contains "[DEPOT]\n\f" for big endian or "[depot]\n\f" for little endian.</li>
<li>version number: decimal string of the version number of the library.</li>
<li>flags for wrappers: from offset 16, type of `int'.</li>
<li>file size: from offset 24, type of `int'.</li>
<li>number of the bucket: from offset 32, type of `int'.</li>
<li>number of records: from offset 40, type of `int'.</li>
</ol>

<p>The bucket section places after the header section and its length is determined according to the number of the bucket.  Each element of the bucket stores an offset of the root node of each separate chain.</p>

<p>The record section places after the bucket section and occupies to the end of the file.  The element of the record section contains the following information.</p>

<ol>
<li>flags: type of `int'.</li>
<li>second hash value: type of `int'.</li>
<li>size of the key: type of `int'.</li>
<li>size of the value: type of `int'.</li>
<li>size of the padding: type of `int'.</li>
<li>offset of the left child: type of `int'.</li>
<li>offset of the right child: type of `int'.</li>
<li>entity of the key: serial bytes with variable length.</li>
<li>entity of the value: serial bytes with variable length.</li>
<li>padding data: void serial bytes with variable length.</li>
</ol>

<h3>File Format of Villa</h3>

<p>Every data handled by Villa is stored in a database of Depot.  Storing data is divided into meta data and logical pages.  Logical pages can be classified into leaf nodes and non-leaf nodes.  Meta data are such managing information as the number of records.  Both of its key and its value are type of `int'.  Leaf nodes hold records.  Non-leaf nodes hold sparse index referring to pages.</p>

<p>Villa uses variable length numeric format (BER compression) to handle small natural number with frugal storage.  A variable length numeric object is parsed from the top of the region and parsing ends at the byte of positive value.  Each byte are evaluated as absolute value and calculated as little endian number based on the radix 128.</p>

<p>Record is logical unit of user data.  Some records overlapping keys are shaped into one physical record.  A Physical record is serialized in the following format.</p>

<ol>
<li>size of the key: type of variable length number</li>
<li>entity of the key: serial bytes with variable length</li>
<li>number of values: type of variable length number</li>
<li>list of values: serial bytes repeating the following expressions<ol>
<li>size: type of variable length number</li>
<li>entity of the key: serial bytes with variable length</li>
</ol></li>
</ol>

<p>Leaf node is physical unit to store a set of records.  The key of a leaf node is its ID whose type is `int'.  A leaf node is stored in a database of Depot with the following values.  Its records are sorted in ascending order of each key.</p>

<ol>
<li>ID of the previous leaf: type of variable length number</li>
<li>ID of the next leaf: type of variable length number</li>
<li>list of records: concatenation of serialized records</li>
</ol>

<p>Index is logical unit of a pointer to search for pages.  An index is serialized int the following format.</p>

<ol>
<li>ID of the referring page: type of variable length number</li>
<li>size of the key: type of variable length number</li>
<li>entity of the key: serial bytes with variable length</li>
</ol>

<p>Non-leaf node is physical unit to store a set of indexes.  The key of a non-leaf node is its ID whose type is `int'.  A non-leaf node is stored in a database of Depot with the following values.  Its indexes are sorted in ascending order of each key.</p>

<ol>
<li>ID of the first child node: type of variable length number</li>
<li>list of indexes: concatenation of serialized indexes</li>
</ol>

<h3>Notes</h3>

<p>Because the database file is not sparse, move, copy, unlink, ftp, and so on with the file are possible.  Because Depot reads and writes data without normalization of byte order, it is impossible to share the same file between the environment with different byte order.</p>

<p>When you distribute a database file of Depot or Villa via network, the MIME type suggested to be `application/x-qdbm'.  Suffix of the file name is suggested to be `.qdb'.  When you distribute a database directory of Curia, you may convert the directory tree to an archive of such type as TAR.</p>

<p>For the command `file' to recognize database files, append the following expressions into `magic' file.</p>

<pre>0       string          [DEPOT]\n\f     QDBM, big endian
&gt;12     string          x               \b, version=%s
&gt;19     byte            ^1              \b, Hash
&gt;19     byte            &amp;1              \b, B+ tree
&gt;19     byte            &amp;2              \b (deflated:ZLIB)
&gt;19     byte            &amp;4              \b (deflated:LZO)
&gt;19     byte            &amp;8              \b (deflated:BZIP2)
&gt;24     belong          x               \b, filesize=%d
&gt;32     belong          x               \b, buckets=%d
&gt;40     belong          x               \b, records=%d
0       string          [depot]\n\f     QDBM, little endian
&gt;12     string          x               \b, version=%s
&gt;16     byte            ^1              \b, Hash
&gt;16     byte            &amp;1              \b, B+ tree
&gt;16     byte            &amp;2              \b (deflated:ZLIB)
&gt;16     byte            &amp;4              \b (deflated:LZO)
&gt;16     byte            &amp;8              \b (deflated:BZIP2)
&gt;24     lelong          x               \b, filesize=%d
&gt;32     lelong          x               \b, buckets=%d
&gt;40     lelong          x               \b, records=%d
</pre>

<hr />

<h2><a name="porting" id="porting" class="head">Porting</a></h2>

<p>One of the goal of QDBM is to work on all platforms which conform to POSIX. Even if some APIs are not implemented, QDBM should work.  Moreover, it should be possible to build QDBM using compilers other than GCC.  Porting to various platforms is performed to add a new `Makefile' or modify some parts of source files.  As for APIs of C, some of the following files should be modified.  Otherwise, you can create new files based on them.</p>

<ul class="lines">
<li><kbd>Makefile.in</kbd> : base of `Makefile', used by `./configure'.</li>
<li><kbd>myconf.h</kbd> : configuration of system dependency.</li>
<li><kbd>depot.h</kbd> : header of the basic API.</li>
<li><kbd>curia.h</kbd> : header of the extended API.</li>
<li><kbd>relic.h</kbd> : header of the NDBM-compatible API.</li>
<li><kbd>hovel.h</kbd> : header of the GDBM-compatible API.</li>
<li><kbd>cabin.h</kbd> : header of the utility API.</li>
<li><kbd>villa.h</kbd> : header of the advanced API.</li>
<li><kbd>vista.h</kbd> : header of the extended advanced API.</li>
<li><kbd>odeum.h</kbd> : header of the inverted API.</li>
<li><kbd>myconf.c</kbd> : implementation of system dependency.</li>
<li><kbd>depot.c</kbd> : implementation of the basic API.</li>
<li><kbd>curia.c</kbd> : implementation of the extended API.</li>
<li><kbd>relic.c</kbd> : implementation of the NDBM-compatible API.</li>
<li><kbd>hovel.c</kbd> : implementation of the GDBM-compatible API.</li>
<li><kbd>cabin.c</kbd> : implementation of the utility API.</li>
<li><kbd>villa.c</kbd> : implementation of the advanced API.</li>
<li><kbd>vista.c</kbd> : implementation of the extended advanced API.</li>
<li><kbd>odeum.c</kbd> : implementation of the inverted API.</li>
</ul>

<p>On platforms which do not support file locking with `fcntl' call, you should append `-DMYNOLOCK' to the macro `CFLAGS' defined in `Makefile'.  In that case, you should consider another exclusion control.  As with it, on platforms without `mmap' call, you should append `-DMYNOMMAP' to `CFLAGS'.  As for `mmap', its emulation using `malloc' and so on is provided.  If other system calls are not implemented, you should define emulation by modification of `myconf.h' and `myconf.c'.</p>

<p>Because POSIX thread is used in C++ API, it is impossible to port C++ API to platforms without the package.  Because JNI is used in Java API, you should pay attention to location of the headers and libraries.  Moreover, you should consider such type definitions as `long long' or `int64'.  Because APIs of Perl and Ruby use building commands provided with each language system, you should be knowledgeable about their specifications.</p>

<hr />

<h2><a name="bugs" id="bugs" class="head">Bugs</a></h2>

<p>Each document of QDBM should be calibrated by native English speakers.</p>

<p>There is no such bug which are found but not fixed, as crash by segmentation fault, unexpected data vanishing, memory leak and so on.</p>

<p>If you find any bug, report it to the author, with the information of the version of QDBM, the operating system and the compiler.</p>

<p>Databases created with QDBM version 1.7.13 or earlier are not compatible to ones of the later versions.</p>

<hr />

<h2><a name="faq" id="faq" class="head">Frequently Asked Questions</a></h2>

<dl>
<dt>Q. : Does QDBM support SQL?</dt>
<dd>A. : No, it does not.  QDBM is not a RDBMS (Relational Database Management System).  If you want an embedded RDBMS, use SQLite and so on.</dd>
<dt>Q. : After all, how different from GDBM (NDBM, SDBM, Berkeley DB)?</dt>
<dd>A. : Processing speed is higher, a database file is smaller, API is simpler.  A highly important thing is that efficiency in time and space is very good when records are frequently overwritten, so, scalability in practical use is high.  Moreover, even when constructing such a large database that the number of storing record is more than one million, processing speed does not slowdown deathly, filesize does not grow extremely.   However, because other DBM or DBMS may be more suitable in some cases, comparing performance and functionality by yourself is suggested.</dd>
<dt>Q. : Which API should I use?</dt>
<dd>A. : If you search for records as complete accord, try Depot.  If the scale is large, try Curia.  If you access records in some order, try Villa.  If the scale is large, try Vista.  If you pursue the greatest number of records, build QDBM with ZLIB or LZO enabled and use Vista.</dd>
<dt>Q. : What is bibliography?</dt>
<dd>A. : Algorithms of QDBM are mainly based on the descriptions in `Data Structures and Algorithms' by Aho et al and `Algorithms in C' by Sedgewick.</dd>
<dt>Q. : Are there good sample codes for applications?</dt>
<dd>A. : Refer to the source code of commands of each API.  `dptsv.c', `crtsv.c' and `vltsv.c' are simplest.</dd>
<dt>Q. : My database file has been broken.  Why?</dt>
<dd>A. : In most cases, the reason is that your application did not close the database on exit.  No matter whether it is a demon process or a CGI script, any application should close handling databases when it exits.  Moreover, we should remember that a process of CGI may be killed by SIGPIPE or SIGTERM.</dd>
<dt>Q. : How robust are databases of QDBM?</dt>
<dd>A. : QDBM does not assure absolute robustness.  A database may be broken if your operating system crashes.  Although transaction of Villa can save a database from crashes of applications, it is inadequate to crashes of operating systems.  So, you should consider multiplexing of a database or backup system if you use QDBM for mission critical applications.</dd>
<dt>Q: How should I use alignment of Depot and Curia?</dt>
<dd>A: If your application repeats writing with overwrite or concatenate mode.  Alignment saves the rapid growth of the size of the database file.  Because the best suited size of alignment of each application is different, you should learn it by experiment.  For the meantime, about 32 is suitable.</dd>
<dt>Q. : How should I tune performance parameters of Villa?</dt>
<dd>A. : If you perform mainly ordering access, `lrecmax' and `nidxmax' should be larger.  If you perform mainly random access, they should be less.  If RAM of your system is abundant, `lcnum' and `ncnum' should be increased in order to improve performance.  If ZLIB, LZO, or BZIP2 is enabled, increase `lrecmax' and compression efficiency is improved.</dd>
<dt>Q. : Which is the most preferable of ZLIB, LZO or BZIP2 for Villa?</dt>
<dd>A. : BZIP2 has the best compression retio.  LZO has the best compression speed.  ZLIB takes a mean position of them.  If you don't have any special reason, using ZLIB is suggested.  However, if updating of the database is frequent, LZO is more preferable.  If updating of the database is very infrequently, BZIP2 is more preferable.  Note that the license of LZO is the GNU LGPL.</dd>
<dt>Q. : What is `sparse file'?</dt>
<dd>A. : It is a file where some holes are.  `Hole' means a block where any data has never written in.  If a file system supports sparse file, holes are not allocated into any physical storage.  As for QDBM, if a database is created with such flags as DP_OSPARSE, the bucket array is not initialized and its blocks become holes.  According to that mechanism, you can use greatly huge hash tables.  However, its performance is strongly depends on the setting of the file system.</dd>
<dt>Q. : Why Depot and Curia do not feature transaction?</dt>
<dd>A. : If an application implements its own transaction, inner transaction of database is superfluous.  You can implement transaction for application easily with hash map provided by Cabin.</dd>
<dt>Q. : How should I tune the system for performance?</dt>
<dd>A. : Install more RAM on your machine than the size of a database.  Then, enlarge I/O buffer and cut down on flushing dirty buffers.  File system is also important.  On Linux, although EXT2 is usually fastest, EXT3 is faster in some cases.  ReiserFS is okey.  The other modes of EXT3 are very slow.  About other file systems, you should learn them by experiment.</dd>
<dt>Q. : Can I build QDBM using `cc' instead of `gcc'?</dt>
<dd>A. : Yes.  Try to build QDBM with `LTmakefile'.</dd>
<dt>Q. : Can I build QDBM using Visual C++?</dt>
<dd>A. : Yes.  Use `VCmakefile' instead of `Makefile'.</dd>
<dt>Q. : Can I use QDBM in other languages?</dt>
<dd>A. : As for PHP, Scheme (Gauche), and OCaml, interfaces of QDBM have been released.  If you need it for another language, try to turn it out.</dd>
<dt>Q. : What does `QDBM' mean?</dt>
<dd>A. : `QDBM' stands for `Quick Database Manager'.  It means that processing speed is high, and that you can write applications quickly.</dd>
</dl>

<hr />

<h2><a name="copying" id="copying" class="head">Copying</a></h2>

<p>QDBM is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License or any later version.</p>

<p>QDBM is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.</p>

<p>You should have received a copy of the GNU Lesser General Public License along with QDBM (See the file `COPYING'); if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.</p>

<p>QDBM was written by Mikio Hirabayashi.  You can contact the author by e-mail to `mikio@fallabs.com'.</p>

<hr />

</body>

</html>

<!-- END OF FILE -->