summaryrefslogtreecommitdiffstats
path: root/tdb/docs/README
diff options
context:
space:
mode:
authorSimo Sorce <ssorce@redhat.com>2009-02-25 16:43:57 -0500
committerSimo Sorce <ssorce@redhat.com>2009-02-26 09:13:32 -0500
commit77454c07ba109a3ea6af0da86ba954b28b1fd02f (patch)
tree5e5be00f9b77c42e697617acb9fd695f7c6a0e58 /tdb/docs/README
parentc9f6d2795fde2f9bf80277d425df2b44bc860226 (diff)
downloadsssd-77454c07ba109a3ea6af0da86ba954b28b1fd02f.tar.gz
sssd-77454c07ba109a3ea6af0da86ba954b28b1fd02f.tar.xz
sssd-77454c07ba109a3ea6af0da86ba954b28b1fd02f.zip
Remove our copies of the samba libraries.
Packages are already available in debian unstable and will soon land in Fedora. See BUILD.TXT for details. We still keep libreplace as we still use its configure macros, until we find time to extract only waht we need and have our own macros.
Diffstat (limited to 'tdb/docs/README')
-rw-r--r--tdb/docs/README238
1 files changed, 0 insertions, 238 deletions
diff --git a/tdb/docs/README b/tdb/docs/README
deleted file mode 100644
index 63fcf5e04..000000000
--- a/tdb/docs/README
+++ /dev/null
@@ -1,238 +0,0 @@
-tdb - a trivial database system
-tridge@linuxcare.com December 1999
-==================================
-
-This is a simple database API. It was inspired by the realisation that
-in Samba we have several ad-hoc bits of code that essentially
-implement small databases for sharing structures between parts of
-Samba. As I was about to add another I realised that a generic
-database module was called for to replace all the ad-hoc bits.
-
-I based the interface on gdbm. I couldn't use gdbm as we need to be
-able to have multiple writers to the databases at one time.
-
-Compilation
------------
-
-add HAVE_MMAP=1 to use mmap instead of read/write
-add NOLOCK=1 to disable locking code
-
-Testing
--------
-
-Compile tdbtest.c and link with gdbm for testing. tdbtest will perform
-identical operations via tdb and gdbm then make sure the result is the
-same
-
-Also included is tdbtool, which allows simple database manipulation
-on the commandline.
-
-tdbtest and tdbtool are not built as part of Samba, but are included
-for completeness.
-
-Interface
----------
-
-The interface is very similar to gdbm except for the following:
-
-- different open interface. The tdb_open call is more similar to a
- traditional open()
-- no tdbm_reorganise() function
-- no tdbm_sync() function. No operations are cached in the library anyway
-- added a tdb_traverse() function for traversing the whole database
-- added transactions support
-
-A general rule for using tdb is that the caller frees any returned
-TDB_DATA structures. Just call free(p.dptr) to free a TDB_DATA
-return value called p. This is the same as gdbm.
-
-here is a full list of tdb functions with brief descriptions.
-
-
-----------------------------------------------------------------------
-TDB_CONTEXT *tdb_open(char *name, int hash_size, int tdb_flags,
- int open_flags, mode_t mode)
-
- open the database, creating it if necessary
-
- The open_flags and mode are passed straight to the open call on the database
- file. A flags value of O_WRONLY is invalid
-
- The hash size is advisory, use zero for a default value.
-
- return is NULL on error
-
- possible tdb_flags are:
- TDB_CLEAR_IF_FIRST - clear database if we are the only one with it open
- TDB_INTERNAL - don't use a file, instaed store the data in
- memory. The filename is ignored in this case.
- TDB_NOLOCK - don't do any locking
- TDB_NOMMAP - don't use mmap
- TDB_NOSYNC - don't synchronise transactions to disk
-
-----------------------------------------------------------------------
-TDB_CONTEXT *tdb_open_ex(char *name, int hash_size, int tdb_flags,
- int open_flags, mode_t mode,
- tdb_log_func log_fn,
- tdb_hash_func hash_fn)
-
-This is like tdb_open(), but allows you to pass an initial logging and
-hash function. Be careful when passing a hash function - all users of
-the database must use the same hash function or you will get data
-corruption.
-
-
-----------------------------------------------------------------------
-char *tdb_error(TDB_CONTEXT *tdb);
-
- return a error string for the last tdb error
-
-----------------------------------------------------------------------
-int tdb_close(TDB_CONTEXT *tdb);
-
- close a database
-
-----------------------------------------------------------------------
-int tdb_update(TDB_CONTEXT *tdb, TDB_DATA key, TDB_DATA dbuf);
-
- update an entry in place - this only works if the new data size
- is <= the old data size and the key exists.
- on failure return -1
-
-----------------------------------------------------------------------
-TDB_DATA tdb_fetch(TDB_CONTEXT *tdb, TDB_DATA key);
-
- fetch an entry in the database given a key
- if the return value has a null dptr then a error occurred
-
- caller must free the resulting data
-
-----------------------------------------------------------------------
-int tdb_exists(TDB_CONTEXT *tdb, TDB_DATA key);
-
- check if an entry in the database exists
-
- note that 1 is returned if the key is found and 0 is returned if not found
- this doesn't match the conventions in the rest of this module, but is
- compatible with gdbm
-
-----------------------------------------------------------------------
-int tdb_traverse(TDB_CONTEXT *tdb, int (*fn)(TDB_CONTEXT *tdb,
- TDB_DATA key, TDB_DATA dbuf, void *state), void *state);
-
- traverse the entire database - calling fn(tdb, key, data, state) on each
- element.
-
- return -1 on error or the record count traversed
-
- if fn is NULL then it is not called
-
- a non-zero return value from fn() indicates that the traversal
- should stop. Traversal callbacks may not start transactions.
-
- WARNING: The data buffer given to the callback fn does NOT meet the
- alignment restrictions malloc gives you.
-
-----------------------------------------------------------------------
-int tdb_traverse_read(TDB_CONTEXT *tdb, int (*fn)(TDB_CONTEXT *tdb,
- TDB_DATA key, TDB_DATA dbuf, void *state), void *state);
-
- traverse the entire database - calling fn(tdb, key, data, state) on
- each element, but marking the database read only during the
- traversal, so any write operations will fail. This allows tdb to
- use read locks, which increases the parallelism possible during the
- traversal.
-
- return -1 on error or the record count traversed
-
- if fn is NULL then it is not called
-
- a non-zero return value from fn() indicates that the traversal
- should stop. Traversal callbacks may not start transactions.
-
-----------------------------------------------------------------------
-TDB_DATA tdb_firstkey(TDB_CONTEXT *tdb);
-
- find the first entry in the database and return its key
-
- the caller must free the returned data
-
-----------------------------------------------------------------------
-TDB_DATA tdb_nextkey(TDB_CONTEXT *tdb, TDB_DATA key);
-
- find the next entry in the database, returning its key
-
- the caller must free the returned data
-
-----------------------------------------------------------------------
-int tdb_delete(TDB_CONTEXT *tdb, TDB_DATA key);
-
- delete an entry in the database given a key
-
-----------------------------------------------------------------------
-int tdb_store(TDB_CONTEXT *tdb, TDB_DATA key, TDB_DATA dbuf, int flag);
-
- store an element in the database, replacing any existing element
- with the same key
-
- If flag==TDB_INSERT then don't overwrite an existing entry
- If flag==TDB_MODIFY then don't create a new entry
-
- return 0 on success, -1 on failure
-
-----------------------------------------------------------------------
-int tdb_writelock(TDB_CONTEXT *tdb);
-
- lock the database. If we already have it locked then don't do anything
-
-----------------------------------------------------------------------
-int tdb_writeunlock(TDB_CONTEXT *tdb);
- unlock the database
-
-----------------------------------------------------------------------
-int tdb_lockchain(TDB_CONTEXT *tdb, TDB_DATA key);
-
- lock one hash chain. This is meant to be used to reduce locking
- contention - it cannot guarantee how many records will be locked
-
-----------------------------------------------------------------------
-int tdb_unlockchain(TDB_CONTEXT *tdb, TDB_DATA key);
-
- unlock one hash chain
-
-----------------------------------------------------------------------
-int tdb_transaction_start(TDB_CONTEXT *tdb)
-
- start a transaction. All operations after the transaction start can
- either be committed with tdb_transaction_commit() or cancelled with
- tdb_transaction_cancel().
-
- If you call tdb_transaction_start() again on the same tdb context
- while a transaction is in progress, then the same transaction
- buffer is re-used. The number of tdb_transaction_{commit,cancel}
- operations must match the number of successful
- tdb_transaction_start() calls.
-
- Note that transactions are by default disk synchronous, and use a
- recover area in the database to automatically recover the database
- on the next open if the system crashes during a transaction. You
- can disable the synchronous transaction recovery setup using the
- TDB_NOSYNC flag, which will greatly speed up operations at the risk
- of corrupting your database if the system crashes.
-
- Operations made within a transaction are not visible to other users
- of the database until a successful commit.
-
-----------------------------------------------------------------------
-int tdb_transaction_cancel(TDB_CONTEXT *tdb)
-
- cancel a current transaction, discarding all write and lock
- operations that have been made since the transaction started.
-
-
-----------------------------------------------------------------------
-int tdb_transaction_commit(TDB_CONTEXT *tdb)
-
- commit a current transaction, updating the database and releasing
- the transaction locks.
-