rcdb_lookup man page on MirBSD

Man page or keyword search:  
man Server   6113 pages
apropos Keyword Search (all sections)
Output format
MirBSD logo
[printable version]

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
[top]

List of man pages available for MirBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net