MirOS Manual: rcdb(3), rcdb_close(3), rcdb_delete(3), rcdb_lookup(3), rcdb_modify(3), rcdb_open(3), rcdb_read(3), rcdb_retrieve(3), rcdb_store(3), rcdb_write(3)

RCDB(3)                    BSD Programmer's Manual                     RCDB(3)

NAME

     rcdb - plain-text key/value pair database

SYNOPSIS

     #include <sys/types.h>
     #include <db.h>

     DBT *
     rcdb_alloc(void *item, const size_t length);

     DBT *
     rcdb_string(char *text);

     void
     rcdb_split(RCDB *handle, int64_t *value, char **key);

     RCDB *
     rcdb_open(const char * const dbfile);

     int
     rcdb_close(RCDB *handle);

     int
     rcdb_rawread(RCDB *handle, recno_t nr, char **bstr);

     int
     rcdb_rawrite(RCDB *handle, recno_t nr, char **bstr);

     int
     rcdb_delete(RCDB *handle, recno_t nr);

     recno_t
     rcdb_lookup(RCDB *handle, const char *const searchkey);

     int
     rcdb_retrieve(RCDB *handle, recno_t nr, int64_t *value, char **key);

     int
     rcdb_read(RCDB *handle, recno_t nr, int64_t *value);

     int
     rcdb_modify(RCDB *handle, recno_t nr, int64_t value,
             const char *const key);

     int
     rcdb_write(RCDB *handle, recno_t nr, int64_t value);

     recno_t
     rcdb_store(RCDB *handle, int64_t value, const char *const key);

DESCRIPTION

     The rcdb function suite has been developed as an interface to the
     dbopen(3) suite of functions with a recno(3) back-end and database file.
     rcdb databases save key/value pairs, with the key consisting of a C
     string and the value being a signed 64-bit integer. In this implementa-
     tion, the value is being saved as a hexadecimal value by default, but oc-
     tal and decimal values can be written into the exposed database manually
     as well due to usage of the strtoll(3) function to parse the values
     (called reference counts in former versions of this manual page).

     The character set to be used is ISO_646.irv:1991, which limits the
     separator character to be within the range of 1 to 126 decimally, or 0x01
     to 0x7E hexadecimal, including the range boundaries, but excluding the
     newline character (10 or 0x0A by default). If you want to save a more
     broad range of characters within the key or raw string, you are en-
     couraged to use the UTF-7 encoding of the recent Unicode character set,
     because UTF-8 peruses the eigth bit and is not guaranteed to be handled
     the same on all operating environments. On the other hand, using UTF-8
     makes the support for high-bit characters transparent and allows strictly
     conforming systems to still look up keys which only use plain ascii(7).

     The rcdb function suite is defined in the <db.h> include file and is
     drawn around the following structure:

     typedef struct {
             DB *database;
             recno_t key;
             recno_t currec;
             recno_t lastrec;
             DBT dbt_key;
             DBT dbt_data;
             char sep;
     } RCDB;

     Direct access to the database, circumventing the rcdb routines, is possi-
     ble via the RCDB->database field, but this should be avoided if possible.
     You actually can change the newline character, but the resulting database
     might not be binary-compatible. Optimally, the RCDB structure should be
     handled as opaque. The separator character, '|' by default, can appear
     within the key.

API LEVEL

     Within <db.h>, the _DB_RCDB_API macro is defined to the version of the
     current application programming interface level. This version of the rcdb
     manual page describes API version 3. The _DB_RCDB_MAJOR macro is defined
     as the lowest API supported by that version of <db.h>.

API FUNCTIONS

     rcdb_alloc(item, length)
             allocates storage for a DBT structure using malloc(3) and ini-
             tializes it to point to item and contain length. In case of an
             error, NULL is returned, else a pointer to the newly allocated
             DBT structure.
             This function is __DBINTERFACE_PRIVATE.

     rcdb_string(text)
             calls rcdb_alloc(3) with text and its length (without the trail-
             ing zero byte) as parameters.
             This function is __DBINTERFACE_PRIVATE.

     rcdb_split(handle, value, key)
             splits the contents of the DBT data component into two com-
             ponents. The first one is assumed being a signed 64-bit integer
             in decimal notation (octal if starting with a zero, hexadecimal
             if starting with 0x). Separated by the separator character, the
             second value until the end of the data string but before the end
             mark, is assumed to be the key. Appropriate space for the key is
             allocated using malloc(3). If handle or handle->dbt_data.data was
             NULL, no action is performed at all. If an error occured, key is
             guaranteed to contain NULL. If the separator character was found
             to be invalid, EDOM is stored in the global variable errno, and
             EFTYPE if the separator character is missing (opaque raw access).
             This function is __DBINTERFACE_PRIVATE.

     rcdb_open(dbfile)
             calls dbopen(3) to open the recno(3) database file dbfile. It al-
             locates storage for an RCDB structure using malloc(3) and ini-
             tializes it, then returns a pointer to the structure. If an error
             occurs, NULL is returned.

     rcdb_close(handle)
             takes an RCDB handle and tries to close the database and free(3)
             the memory associated with it. If the RCDB pointer or the
             RCDB->database pointer are already NULL, no action is taken on
             them. If the database was open and the attempt to close it was
             successful, 0 is returned, else 1 is returned. In any case, the
             memory associated with the handle is freed.

     rcdb_rawread(handle, nr, bstr)
             reads the record nr from the database and stores a copy of its
             content in *bstr unless bstr is NULL (in which case you can use
             handle->dbt_data to access the content). On error, -1 is returned
             and *bstr is set to NULL if possible.

     rcdb_rawrite(handle, nr, bstr)
             writes the data contained in the C string *bstr into the data-
             base, overwriting record nr unless nr is zero, in which case a
             new record is created and appended at the end of the database
             text file. On error, -1 is returned. *bstr is never modified.

     rcdb_lookup(handle, searchkey)
             searches the database from beginning to the end for a record wirh
             the key searchkey. In case of an error, (recno_t)-1 is returned.
             If the record is found, its number is returned, else zero. So-
             called opaque records, these on which rcdb_split(3) returns EF-
             TYPE, that is, are skipped during the comparison and do not con-
             stitute an error.

     rcdb_retrieve(handle, nr, value, key)
             retrieves the record with the number nr and writes its key into
             *key and its value into *value. If an error occurs, -1 is re-
             turned, the content of *value is undefined, and *key is most
             likely set to NULL. If the operation was successful, 0 is re-
             turned. An invalid separator character causes an error of EDOM,
             and EINVAL is yielded if the record number is zero.

     rcdb_read(handle, nr, value)
             retrieves the record with the recno nr and writes its value into
             *value. If an error occurs, -1 is returned and the content of
             *value is undefined, else the result is 0.

     rcdb_delete(handle, nr)
             tries to delete the record nr and returns 0 on success and -1 on
             failure.

     rcdb_modify(handle, nr, value, key)
             allocates necessary space to handle a record containing a hexade-
             cimal 64-bit number preceded by 0x and followed by the separator
             character and key, trailed by the zero character. It then fills
             the space with content generated from value and key, and writes
             it into the database. If nr is zero, a new record is appended at
             the end of the file. If a record to be overwritten does not ex-
             ist, the behaviour is unspecified due to a limitation in the
             underlying libdb. Memory allocated during the operation is freed
             before exit. If the operation fails, -1 is returned, else zero.
             This function is not intended to be called by an end-user, be-
             cause rcdb_write(3) and rcdb_store(3) already provide powerful
             interfaces to the database. However, if you know what you are do-
             ing, this function is most likely more performant and thus not
             private. This is the most low-level write interface.

     rcdb_write(handle, nr, value)
             can be used to write a new value to a known key/recno into the
             database.

     rcdb_store(handle, value, key)
             writes the key/value pair into the database, overwriting a prob-
             ably already existing entry with the same key, appending if it
             did not already exist. It is the high-level write interface to
             this library. If an error occured, -1 is returned, else the recno
             of the record just written.

RETURN VALUES

     The return values of the functions are already described in the API
     FUNCTIONS section above. As a rule of thumb, the functions return -1 if
     an error occured, and 0 or a recno if the operation completed successful-
     ly.

     Caveat: rcdb_lookup() and rcdb_store() return -1 casted to recno_t on er-
     ror, so be sure to compare it to (recno_t)-1 because in the current im-
     plementation, the value is unsigned.

ERRORS

     In most cases, if an error occured, the db, recno or rcdb functions are
     setting errno to an appropriate error number. In addition to this rule,
     the recno(3) and dbopen(3) manual pages also describe return values which
     can be yielded from the rcdb functions. The memory allocation functions
     can also write to errno.

SEE ALSO

     ascii(7), dbopen(3), recno(3)

HISTORY

     rcdb appeared in MirOS MirPorts in 2004.

AUTHORS

     Copyright (c) 2004 Thorsten Glaser <tg@mirbsd.org>

     This product includes material provided by Thorsten Glaser.

BUGS

     Probably some. If you encounter one, feedback is highly appreciated.

MirOS BSD #10-current          August 13, 2011                               3

Generated on 2014-04-02 20:57:59 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.