.TH libnmdb 3 "11/Sep/2006" .SH NAME libnmdb - Library for interacting with a nmdb server .SH SYNOPSYS .nf .B #include .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_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 "int nmdb_get(nmdb_t *" db "," .BI " const unsigned char *" key ", size_t " ksize "," .BI " unsigned char *" val ", size_t " vsize ");" .BI "int 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 ")" .fi .SH DESCRIPTION libnmdb is a library for interacting with a nmdb(1) server. For more information about it, see nmdb(1) or http://auriga.wearlab.de/~alb/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() , .B nmdb_add_tcp_server() and .BR nmdb_add_udp_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 four kinds of operations: .IR set , which sets pairs; .IR get , which gets pairs; .IR del , which removes pairs; and .IR cas , which compares-and-sets values. 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 ), 0 if the requested key was not in the database (or cache, if the cache variant is used), or < 0 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 successfuly, or < 0 on failure. The cache and synchronous variant return 1 if the key was removed successfuly, 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, and < 0 on failure. .SH SEE ALSO .BR nmdb (1), .B TIPC (http://tipc.sf.net). .SH AUTHORS Created by Alberto Bertogli (albertito@gmail.com).