TXTDB(3) BSD Library Functions Manual TXTDB(3) NAME txtdb_dbopen, txtdb_append, txtdb_readopen, txtdb_next, txtdb_readclose, txtdb_err, txtdb_dbclose, -- text-file database SYNOPSIS #include db_t txtdb_dbopen(const char *path, char *errbuf, int buflen); int txtdb_append(db_t db, const char *class, const struct keyval *kv); cursor_t txtdb_readopen(db_t db, const char *class, const struct keyval *filter, unsigned int lastn); struct keyval * txtdb_next(cursor_t c); int txtdb_readclose(cursor_t c); char * txtdb_err(db_t db, char *errbuf, int buflen); void txtdb_dbclose(db_t db); DESCRIPTION txtdb provides a simple, portable, transparent, persistent data store for online and offline application developers. All data is stored in text files that can be independently read or written by other programs. txtdb attempts to satisfy the following three goals: (1) A new user not famil- iar with databases should be able to learn and use the system in about 15 minutes. (2) It should prevent multiple txtdb application threads or pro- cesses from corrupting data. (3) The data store must be human readable and editable. Unlike traditional database systems that typically force clients to con- nect to a separate database daemon, txtdb is a library that is linked in with an application. Consistency between different threads and different processes is provided using system-level advisory locks. txtdb is an append-only database. Yep, no delete. This means that as data changes, those changes are simply appended to the database. For example, if txtdb is used to store user account information then each change (say an updated password) is just appended to the data store. The next time the affected user's credentials are checked, the application reads only that last entry for that user in the database which has the correct data (in our case the updated password). txtdb is a library that is statically linked in with an application and operates as closely to the existing unix file access model as possible. You open a database by specifying a base path using txtdb_dbopen(). You can then append to file at unix style path using txtdb_append(). The main difference between txtdb and reading and writing normal text files is that you operate on key value pairs. To help clarify the data model txtdb adopts a slightly different termi- nology for data operations. You append a set of key-value pairs under a given classification. For example, you could append the key-value pair 'user:bob' under the classification 'account'. Classifications are hier- archical and constructed like a unix path. For example, one might append 'salary:1.00' under the classification 'accounts/sjobs/personal' and 'title:ceo' under 'accounts/sjobs/public'. We now present a simple walkthrough of the different txtdb library calls. The first step is to open a database handle using txtdb_dbopen() which takes a unix path, an error string, and an error string length. It returns a handle to a database instance at the specified path. This call does not write any files or modify the file system in any way. Once we have a database handle we can append a set of key-value pairs under a given classification in the data using txtdb_append(). The parameters to this call are const char *class, a string indicating the classification and const struct keyval *kv, a pointer to the start of a linked list of key-value pairs. Each node in the key-value linked list should have the following structure: struct keyval { char *k; char *v; struct keyval *next; }; The next field should point to the next keyval structure or NULL of there are no more key-values. To read back sets of key-value pairs from the database we first need to open a read session to a specific classification using the txtdb_readopen() call. txtdb_readopen() also takes a filter parameter which provides the ability to restrict which set of key-value pairs are returned and a lastn parameter which can restrict the tuples returned to only the last N. The filter parameter is a pointer to the start of a linked list of key-value pairs as in the txtdb_append() function or NULL for no filter. The key-value sets returned have a key-value pair that exactly matches each key-value pair in the filter. The lastn parameter provides the capability to return only the last N matching key-value set in the classification. For example, if a system were collecting sensor data the lastn parameter could be set to 100 so only the 100 most recent data point are returned. The filter and lastn parameter can be specified independently or together. txtdb_readopen() returns a read cursor that can then be used to read back sets key-value pairs in the order they were written. txtdb_next() takes the read cursor as a parameter and returns a struct keyval pointer to the next set of key value pairs. For example, if we appended 'fruit:apple' and then 'fruit:banana' with separate calls to txtdb_append() then the first call to txtdb_next() would return 'fruit:apple', and the next call to txtdb_next() would return 'fruit:banana'. Unlike other databases, each append call is independent so duplicate keys are permitted as long as the duplicates appear in separate calls to txtdb_append(). Finally, txtdb_readclose() should be called when done reading a classifi- cation and txtdb_dbclose() should be called when done reading and writing to the database. Lastly, most calls will return either NULL or -1 on error. Use txtdb_err() to fetch a string representation of the error. NOTES Wow, you got through the man page! AUTHORS txtdb was developed by Evan Cooke BSD June 12, 2006 BSD