.TH libnmdb 3 "11/Sep/2006"
.SH NAME
libnmdb - Library for interacting with a nmdb server
.SH SYNOPSIS
.nf
.B #include <nmdb.h>
.sp
.BI "nmdb_t *nmdb_init();"
.BI "int nmdb_add_tipc_server(nmdb_t *" db ", int " port ");"
.BI "int nmdb_add_tcp_server(nmdb_t *" db ", const char * " addr ", int " port ");"
.BI "int nmdb_add_udp_server(nmdb_t *" db ", const char * " addr ", int " port ");"
.BI "int nmdb_add_sctp_server(nmdb_t *" db ", const char * " addr ", int " port ");"
.BI "int nmdb_free(nmdb_t *" db ");"
.sp
.BI "int nmdb_set(nmdb_t *" db ","
.BI " const unsigned char *" key ", size_t " ksize ","
.BI " const unsigned char *" val ", size_t " vsize ");"
.BI "int nmdb_set_sync(nmdb_t *" db ","
.BI " const unsigned char *" key ", size_t " ksize ","
.BI " const unsigned char *" val ", size_t " vsize ");"
.BI "int nmdb_cache_set(nmdb_t *" db ","
.BI " const unsigned char *" key ", size_t " ksize ","
.BI " const unsigned char *" val ", size_t " vsize ");"
.sp
.BI "ssize_t nmdb_get(nmdb_t *" db ","
.BI " const unsigned char *" key ", size_t " ksize ","
.BI " unsigned char *" val ", size_t " vsize ");"
.BI "ssize_t nmdb_cache_get(nmdb_t *" db ","
.BI " const unsigned char *" key ", size_t " ksize ","
.BI " unsigned char *" val ", size_t " vsize ");"
.sp
.BI "int nmdb_del(nmdb_t *" db ","
.BI " const unsigned char *" key ", size_t " ksize ");"
.BI "int nmdb_del_sync(nmdb_t *" db ","
.BI " const unsigned char *" key ", size_t " ksize ");"
.BI "int nmdb_cache_del(nmdb_t *" db ","
.BI " const unsigned char *" key ", size_t " ksize ");"
.sp
.BI "int nmdb_cas(nmdb_t *" db ","
.BI " const unsigned char *" key " , size_t " ksize ","
.BI " const unsigned char *" oldval ", size_t " ovsize ","
.BI " const unsigned char *" newval ", size_t " nvsize ");"
.BI "int nmdb_cache_cas(nmdb_t *" db ","
.BI " const unsigned char *" key " , size_t " ksize ","
.BI " const unsigned char *" oldval ", size_t " ovsize ","
.BI " const unsigned char *" newval ", size_t " nvsize ");"
.sp
.BI "int nmdb_incr(nmdb_t *" db ","
.BI " const unsigned char *" key " , size_t " ksize ","
.BI " int64_t " increment ", int64_t *" newval ");"
.BI "int nmdb_cache_incr(nmdb_t *" db ","
.BI " const unsigned char *" key " , size_t " ksize ","
.BI " int64_t " increment ", int64_t *" newval ");"
.fi
.SH DESCRIPTION
libnmdb is a library for interacting with a nmdb(1) server. For more
information about it, see nmdb(1) or http://blitiri.com.ar/p/nmdb.
The first step to access a server is to call
.BR nmdb_init ()
to initialize the data. It will return an opaque pointer of
.B nmdb_t
type, which well be used as the first argument for the rest of the functions
and identifies a connection to the server.
Optionally, you can add more servers to the server pool, using
.BR nmdb_add_*_server ().
You can add any number of servers, and each time a request is made, one will
be selected. Be aware that you should add all the servers before start using
the database. For
.BR nmdb_add_tipc_server() ,
.BR nmdb_add_tcp_server() ,
.B nmdb_add_udp_server()
and
.BR nmdb_add_sctp_server() ,
if you pass -1 as the port, it will select the default one. They return 1 on
success or 0 on error (or if the specified protocol was not compiled in).
To dispose a connection, use
.BR nmdb_free ().
The functions often take
.I key
and
.I ksize
arguments, as well as
.I val
and
.IR vsize .
These represent a key and a value, respectively, along with their
corresponding sizes, in bytes. The following restrictions regarding the size
of the keys and values apply: keys can't exceed 64Kb, values can't exceed
64Kb, and the size of a key + the size of it's associated value can't exceed
64Kb.
There are five kinds of operations:
.IR set ,
which sets pairs;
.IR get ,
which gets pairs;
.IR del ,
which removes pairs;
.IR cas ,
which compares-and-sets values;
and
.IR incr ,
which atomically increments a value. The normal set and del operations return
as soon as they've been queued on the server for asynchronous completion. Note
that in this case no message is sent to the client when the operation
completes.
Each operation has variants, that make it behave in a different way. All three
have "cache" variants, that only affect the cache and not the database; and
.I set
and
.I del
have "sync" variants that make the operation return only after it's been
acknowledge complete by the database backend. All variants behave the same way
as the original operation unless noted, so the following descriptions document
them implicitly.
.BR nmdb_set ()
is used to set the value associated with the given key. It returns 1 on
success, or < 0 on failure.
.BR nmdb_get ()
is used to retrieve the value for the given key, if there is any.
The
.I val
parameter should be pointing to a buffer where the value will be placed, and
.I vsize
will be the size of that buffer. It's highly recommended that the buffer is
greater than 64kb in size to make room for the largest possible value. It will
return the size of the retrieved key (which will be put in the buffer pointed
at by
.IR val ),
-1 if the requested key was not in the database (or cache, if the cache
variant is used), or -2 on failure.
.BR nmdb_del ()
is used to remove a given key (and it's associated value). The normal variant
returns 1 if it was queued successfully, or < 0 on failure. The cache and
synchronous variant return 1 if the key was removed successfully, 0 if the key
was not in the database/cache, or < 0 on failure.
.BR nmdb_cas ()
is used to compare-and-swap a key's value. It takes an old value to compare
with the one in the database, and if they match, it sets the key to the given
new value. Returns 2 if the swap was performed, 1 if the values didn't match,
0 if the key was not on in the database/cache, or < 0 on failure.
.BR nmdb_incr ()
is used to atomically increment (or decrement) a key's value. It takes a 64
bit number to add to the value (it can be negative), and returns 2 if the
increment was performed, 1 if the value was not in the appropriate format, 0
if the key was not in the database/cache, or < 0 on failure.
The value MUST be a NULL-terminated string with only a number in base 10 in it
(i.e. it must be parseable by strtoll(3)). If the number was incremented
correctly and the
.I newval
parameter is not NULL, it will be set to the resulted value.
.SH SEE ALSO
.BR nmdb (1),
.B TIPC
(http://tipc.sf.net).
.SH AUTHORS
Created by Alberto Bertogli (albertito@blitiri.com.ar).
.SH CONTACT
If you want to report bugs, or have any questions or comments, just let me
know at albertito@blitiri.com.ar.