TCRDB(3)

📦 version 1.1.41, in nixos 26.05, nixpkgs unstable

TCRDB(3) — Tokyo Tyrant 💅

okay bestie, this is the remote database API, and it's giving very serious Tokyo Cabinet + Tokyo Tyrant server energy. Every function, argument, default, error code, and caveat is here — no cap. 🫶

🌸 NAME 🌸

tcrdb — the remote database API. 💖

✨ DESCRIPTION ✨

Remote database is a set of interfaces to use an abstract database of Tokyo Cabinet, mediated by a server of Tokyo Tyrant.

To use the remote database API, include tcrdb.h and related standard header files. Usually, write the following description near the front of a source file.

#include <tcrdb.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>

Objects whose type is pointer to TCRDB are used to handle remote databases. A remote database object is created with the function tcrdbnew and is deleted with the function tcrdbdel. To avoid memory leak, it is important to delete every object when it is no longer in use. 😭 please don't leak, bestie.

Before operations to store or retrieve records, it is necessary to connect the remote database object to the server. The function tcrdbopen is used to open a database connection and the function tcrdbclose is used to close the connection. 🎀

💜 DESCRIPTION 💜

now the function-by-function tea ☕ — same section name, more slay.

🧰 the function squad

🩷 `tcrdberrmsg`

Use tcrdberrmsg to get the message string corresponding to an error code.

const char *tcrdberrmsg(int ecode);

ecode specifies the error code. The return value is the message string of the error code.

🩷 `tcrdbnew`

Use tcrdbnew to create a remote database object.

TCRDB *tcrdbnew(void);

The return value is the new remote database object.

🩷 `tcrdbdel`

Use tcrdbdel to delete a remote database object.

void tcrdbdel(TCRDB *rdb);

rdb specifies the remote database object.

🩷 `tcrdbecode`

Use tcrdbecode to get the last happened error code of a remote database object.

int tcrdbecode(TCRDB *rdb);

rdb specifies the remote database object. The return value is the last happened error code. The following error code is defined:

TTESUCCESS for success
TTEINVALID for invalid operation
TTENOHOST for host not found
TTEREFUSED for connection refused
TTESEND for send error
TTERECV for recv error
TTEKEEP for existing record
TTENOREC for no record found
TTEMISC for miscellaneous error

🩷 `tcrdbtune`

Use tcrdbtune to set the tuning parameters of a hash database object.

bool tcrdbtune(TCRDB *rdb, double timeout, int opts);

rdb specifies the remote database object. timeout specifies the timeout of each query in seconds. If it is not more than 0, the timeout is not specified. opts specifies options by bitwise-or: RDBTRECON specifies that the connection is recovered automatically when it is disconnected. If successful, the return value is true, else, it is false.

⚠️ Note that the tuning parameters should be set before the database is opened. fr fr, do it early.

🩷 `tcrdbopen`

Use tcrdbopen to open a remote database.

bool tcrdbopen(TCRDB *rdb, const char *host, int port);

rdb specifies the remote database object. host specifies the name or the address of the server. port specifies the port number. If it is not more than 0, UNIX domain socket is used and the path of the socket file is specified by the host parameter. If successful, the return value is true, else, it is false.

🩷 `tcrdbopen2`

Use tcrdbopen2 to open a remote database with a simple server expression.

bool tcrdbopen2(TCRDB *rdb, const char *expr);

rdb specifies the remote database object. expr specifies the simple server expression. It is composed of two substrings separated by ":". The former field specifies the name or the address of the server. The latter field specifies the port number. If the latter field is omitted, the default port number is specified. If successful, the return value is true, else, it is false.

🩷 `tcrdbclose`

Use tcrdbclose to close a remote database object.

bool tcrdbclose(TCRDB *rdb);

rdb specifies the remote database object. If successful, the return value is true, else, it is false.

🩷 `tcrdbput`

Use tcrdbput to store a record into a remote database object.

bool tcrdbput(TCRDB *rdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

rdb specifies the remote database object. kbuf specifies the pointer to the region of the key. ksiz specifies the size of the region of the key. vbuf specifies the pointer to the region of the value. vsiz specifies the size of the region of the value. If successful, the return value is true, else, it is false. If a record with the same key exists in the database, it is overwritten.

🩷 `tcrdbput2`

Use tcrdbput2 to store a string record into a remote object.

bool tcrdbput2(TCRDB *rdb, const char *kstr, const char *vstr);

rdb specifies the remote database object. kstr specifies the string of the key. vstr specifies the string of the value. If successful, the return value is true, else, it is false. If a record with the same key exists in the database, it is overwritten.

🩷 `tcrdbputkeep`

Use tcrdbputkeep to store a new record into a remote database object.

bool tcrdbputkeep(TCRDB *rdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

🩷 `tcrdbputkeep2`

Use tcrdbputkeep2 to store a new string record into a remote database object.

bool tcrdbputkeep2(TCRDB *rdb, const char *kstr, const char *vstr);

🩷 `tcrdbputcat`

Use tcrdbputcat to concatenate a value at the end of the existing record in a remote database object.

bool tcrdbputcat(TCRDB *rdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

rdb specifies the remote database object. kbuf specifies the pointer to the region of the key. ksiz specifies the size of the region of the key. vbuf specifies the pointer to the region of the value. vsiz specifies the size of the region of the value. If successful, the return value is true, else, it is false. If there is no corresponding record, a new record is created.

🩷 `tcrdbputcat2`

Use tcrdbputcat2 to concatenate a string value at the end of the existing record in a remote database object.

bool tcrdbputcat2(TCRDB *rdb, const char *kstr, const char *vstr);

rdb specifies the remote database object. kstr specifies the string of the key. vstr specifies the string of the value. If successful, the return value is true, else, it is false. If there is no corresponding record, a new record is created.

🩷 `tcrdbputshl`

Use tcrdbputshl to concatenate a value at the end of the existing record and shift it to the left.

bool tcrdbputshl(TCRDB *rdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz, int width);

rdb specifies the remote database object. kbuf specifies the pointer to the region of the key. ksiz specifies the size of the region of the key. vbuf specifies the pointer to the region of the value. vsiz specifies the size of the region of the value. width specifies the width of the record. If successful, the return value is true, else, it is false. If there is no corresponding record, a new record is created. 🌀 shifting left, iconic behavior.

🩷 `tcrdbputshl2`

Use tcrdbputshl2 to concatenate a string value at the end of the existing record and shift it to the left.

bool tcrdbputshl2(TCRDB *rdb, const char *kstr, const char *vstr, int width);

rdb specifies the remote database object. kstr specifies the string of the key. vstr specifies the string of the value. width specifies the width of the record. If successful, the return value is true, else, it is false. If there is no corresponding record, a new record is created.

🩷 `tcrdbputnr`

Use tcrdbputnr to store a record into a remote database object without response from the server.

bool tcrdbputnr(TCRDB *rdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);

okay so next up is the put-with-no-response situation 👀

tcrdbputnr2 is the "fire and forget" bestie of the family — you use it to stash a string record into a remote object without waiting for a response from the server 🫶

bool tcrdbputnr2(TCRDB *rdb, const char *kstr, const char *vstr);

rdb — the remote database object, obvs.
kstr — the string of the key.
vstr — the string of the value.

If it works, the return value is true; if not, it's false. And if a record with the same key is already chilling in the database, it gets overwritten — no cap, it's gone 🫡

tcrdbout is the delete button for a record of a remote database object. bye bestie 💅

bool tcrdbout(TCRDB *rdb, const void *kbuf, int ksiz);

rdb — the remote database object.
kbuf — the pointer to the region of the key.
ksiz — the size of the region of the key.

Successful? true. Not successful? false. That's the whole vibe check ✨

tcrdbout2 does the exact same delete, but the string-key version — much more your speed if you're not out here juggling buffers 💖

bool tcrdbout2(TCRDB *rdb, const char *kstr);

rdb — the remote database object.
kstr — the string of the key.

true if it slayed, false if it flopped 🎀

🌸 the getting-it-back era

tcrdbget is how you retrieve a record out of a remote database object 🔥

void *tcrdbget(TCRDB *rdb, const void *kbuf, int ksiz, int *sp);

rdb — the remote database object.
kbuf — the pointer to the region of the key.
ksiz — the size of the region of the key.
sp — the pointer to the variable where the size of the region of the return value gets assigned.

If it's a success, the return value is the pointer to the region of the value of the corresponding record. NULL comes back if no record corresponds 😭

✨ cute detail: because an additional zero code is appended at the end of the region of the return value, you can literally treat the return value as a character string.

And because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use. yes bestie, that means you. free it. 🧚

tcrdbget2 is the string-flavored get — same energy, way less pointer admin 💜

char *tcrdbget2(TCRDB *rdb, const char *kstr);

rdb — the remote database object.
kstr — the string of the key.

Success = the string of the value of the corresponding record. NULL = no record corresponds, tragic 😭

Because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use — same rule, icon behavior only 💅

tcrdbget3 is the group-chat version: it retrieves records plural, all at once 👑

bool tcrdbget3(TCRDB *rdb, TCMAP *recs);

rdb — the remote database object.
recs — a map object containing the retrieval keys. as a result of this function, keys existing in the database have the corresponding values, and keys not existing in the database are removed 😳 (yes, it edits your map, that's the whole bit)

Return value is true if successful, else false 🌈

🦋 size check era

tcrdbvsiz — how big is the value of a record in a remote database object? this function knows 💖

int tcrdbvsiz(TCRDB *rdb, const void *kbuf, int ksiz);

rdb — the remote database object.
kbuf — the pointer to the region of the key.
ksiz — the size of the region of the key.

If successful, the return value is the size of the value of the corresponding record. else, it is -1 💀

tcrdbvsiz2 — same size situation, but for a string record ✨

int tcrdbvsiz2(TCRDB *rdb, const char *kstr);

rdb — the remote database object.
kstr — the string of the key.

Successful → the size of the value of the corresponding record. otherwise → -1 🙈

🎀 iterator hours

tcrdbiterinit initializes the iterator of a remote database object — think of it as resetting the little cursor back to the start 🔄

bool tcrdbiterinit(TCRDB *rdb);

rdb — the remote database object.

true if successful, else false. and like — what's the iterator even for? it's used in order to access the key of every record stored in a database. iconique ✨

tcrdbiternext is the "gimme the next key" call on that iterator 🏃‍♀️

void *tcrdbiternext(TCRDB *rdb, int *sp);

rdb — the remote database object.
sp — the pointer to the variable into which the size of the region of the return value is assigned.

Success = pointer to the region of the next key. otherwise = NULL. and NULL is also what you get when no record is to be get out of the iterator — i.e. you've reached the end, congrats 🎉

because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.

because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use. (are we sensing a theme? we are. free it.) 💅

⚠️ real talk though: the iterator can be updated by multiple connections, and then it is not assured that every record is traversed. so like, don't @ me if you skip one 😭

tcrdbiternext2 — the next key, but as a string, because we're not doing buffer math today 🍓

char *tcrdbiternext2(TCRDB *rdb);

rdb — the remote database object.

Success = the string of the next key, else NULL. NULL also happens when no record is to be get out of the iterator, so don't panic 🫶

Because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use.

same warning, same energy: the iterator can be updated by multiple connections and then it is not assured that every record is traversed. fr fr 🌸

👑 forward matching keys

tcrdbfwmkeys fetches forward matching keys in a remote database object — basically "gimme everything that starts with this prefix" 💫

TCLIST *tcrdbfwmkeys(TCRDB *rdb, const void *pbuf, int psiz, int max);

rdb — the remote database object.
pbuf — the pointer to the region of the prefix.
psiz — the size of the region of the prefix.
max — the maximum number of keys to be fetched. if it is negative, no limit is specified 🤯

The return value is a list object of the corresponding keys. key detail: this function does never fail. it returns an empty list even if no key corresponds. no drama, just an empty list 💅

Because the object of the return value is created with the function tclistnew, it should be deleted with the function tclistdel when it is no longer in use ✨

tcrdbfwmkeys2 — same forward matching era, but the prefix is a string 🎀

TCLIST *tcrdbfwmkeys2(TCRDB *rdb, const char *pstr, int max);

rdb — the remote database object.
pstr — the string of the prefix.
max — the maximum number of keys to be fetched. if it is negative, no limit is specified.

Return value = a list object of the corresponding keys. again: this function does never fail. empty list even if no key corresponds. it simply doesn't miss 😌

Because the object of the return value is created with the function tclistnew, it should be deleted with the function tclistdel when it is no longer in use 🔥

🌈 number-crunching besties

tcrdbaddint adds an integer to a record in a remote database object ➕

int tcrdbaddint(TCRDB *rdb, const void *kbuf, int ksiz, int num);

rdb — the remote database object.
kbuf — the pointer to the region of the key.
ksiz — the size of the region of the key.
num — the additional value.

Success = the summation value. else = INT_MIN 💀 and here's the little mechanic: if the corresponding record exists, the value is treated as an integer and is added to. if no record corresponds, a new record of the additional value is stored 🫶

tcrdbadddouble is the same bit but with a real number 💖

double tcrdbadddouble(TCRDB *rdb, const void *kbuf, int ksiz, double num);

rdb — the remote database object.
kbuf — the pointer to the region of the key.
ksiz — the size of the region of the key.
num — the additional value.

Success = the summation value, else = Not-a-Number 😭 If the corresponding record exists, the value is treated as a real number and is added to. if no record corresponds, a new record of the additional value is stored. same rules, floatier vibes ⭐

tcrdbext is used in order to call a function of the script language extension —

Because an extra zero code gets tacked onto the end of the return-value region, you can literally treat the return value as a character string — so convenient 💚. And because that region is allocated with the malloc call, bestie please release it with the free call the moment you're done with it, ok? Don't leave it hanging 😭

The function tcrdbext2 is used in order to call a function of the script language extension with string parameters.

char *tcrdbext2(TCRDB *rdb, const char *name, int opts, const char *kstr, const char *vstr);

rdb specifies the remote database object.
name specifies the function name.
opts specifies options by bitwise-or: RDBXOLCKREC for record locking, RDBXOLCKGLB for global locking.
kstr specifies the string of the key.
vstr specifies the string of the value.

If it works out, the return value is the string of the value of the response ✨. NULL is returned on failure, sad but true.

Because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use 💅

The function tcrdbsync is used in order to synchronize updated contents of a remote database object with the file and the device.

bool tcrdbsync(TCRDB *rdb);

rdb specifies the remote database object.

If successful, the return value is true, else, it is false 🫶

The function tcrdboptimize is used in order to optimize the storage of a remove database object.

bool tcrdboptimize(TCRDB *rdb, const char *params);

rdb specifies the remote database object.
params specifies the string of the tuning parameters. If it is NULL, it is not used.

If successful, the return value is true, else, it is false 🌸

The function tcrdbvanish is used in order to remove all records of a remote database object.

bool tcrdbvanish(TCRDB *rdb);

rdb specifies the remote database object.

If successful, the return value is true, else, it is false 💀 (yes, all the records. gone. periodt.)

The function tcrdbcopy is used in order to copy the database file of a remote database object.

bool tcrdbcopy(TCRDB *rdb, const char *path);

rdb specifies the remote database object.
path specifies the path of the destination file. If it begins with @, the trailing substring is executed as a command line 👀

If successful, the return value is true, else, it is false. False is returned if the executed command returns non-zero code.

The database file is assured to be kept synchronized and not modified while the copying or executing operation is in progress 🎀. So yeah, this function is genuinely useful to create a backup file of the database file — iconic behaviour honestly.

The function tcrdbrestore is used in order to restore the database file of a remote database object from the update log.

bool tcrdbrestore(TCRDB *rdb, const char *path, uint64_t ts, int opts);

rdb specifies the remote database object.
path specifies the path of the update log directory.
opts specifies options by bitwise-or: RDBROCHKCON for consistency checking.
ts specifies the beginning time stamp in microseconds.

If successful, the return value is true, else, it is false 💖

The function tcrdbsetmst is used in order to set the replication master of a remote database object.

bool tcrdbsetmst(TCRDB *rdb, const char *host, int port, uint64_t ts, int opts);

rdb specifies the remote database object.
host specifies the name or the address of the server. If it is NULL, replication of the database is disabled 🚫
port specifies the port number.
ts specifies the beginning timestamp in microseconds.
opts specifies options by bitwise-or: RDBROCHKCON for consistency checking.

If successful, the return value is true, else, it is false ✨

The function tcrdbsetmst2 is used in order to set the replication master of a remote database object with a simple server expression.

bool tcrdbsetmst2(TCRDB *rdb, const char *expr, uint64_t ts, int opts);

rdb specifies the remote database object.
expr specifies the simple server expression. It is composed of two substrings separated by ":". The former field specifies the name or the address of the server. The latter field specifies the port number. If the latter field is omitted, the default port number is specified 👑
ts specifies the beginning timestamp in microseconds.
opts specifies options by bitwise-or: RDBROCHKCON for consistency checking.

If successful, the return value is true, else, it is false 🦋

The function tcrdbrnum is used in order to get the number of records of a remote database object.

uint64_t tcrdbrnum(TCRDB *rdb);

rdb specifies the remote database object.

The return value is the number of records or 0 if the object does not connect to any database server 😭

The function tcrdbsize is used in order to get the size of the database of a remote database object.

uint64_t tcrdbsize(TCRDB *rdb);

rdb specifies the remote database object.

The return value is the size of the database or 0 if the object does not connect to any database server 💜

The function tcrdbstat is used in order to get the status string of the database of a remote database object.

char *tcrdbstat(TCRDB *rdb);

rdb specifies the remote database object.

The return value is the status message of the database or NULL if the object does not connect to any database server. The message format is TSV 📋. The first field of each line means the parameter name and the second field means the value — iykyk.

Because the region of the return value is allocated with the malloc call, it should be released with the free call when it is no longer in use 🧚

The function tcrdbmisc is used in order to call a versatile function for miscellaneous operations of a remote database object.

TCLIST *tcrdbmisc(TCRDB *rdb, const char *name, int opts, const TCLIST *args);

rdb specifies the remote database object.
name specifies the name of the function. All databases support "put", "out", "get", "putlist", "outlist", and "getlist" ✨
- "put" is to store a record. It receives a key and a value, and returns an empty list.
- "out" is to remove a record. It receives a key, and returns an empty list.
- "get" is to retrieve a record. It receives a key, and returns a list of the values.
- "putlist" is to store records. It receives keys and values one after the other, and returns an empty list.
- "outlist" is to remove records. It receives keys, and returns an empty list.
- "getlist" is to retrieve records. It receives keys, and returns keys and values of corresponding records one after the other 🔥
opts specifies options by bitwise-or: RDBMONOULOG for omission of the update log.
args specifies a list object containing arguments.

If successful, the return value is a list object of the result. NULL is returned on failure 😔

Because the object of the return value is created with the function tclistnew, it should be deleted with the function tclistdel when it is no longer in use — don't forget, bestie 💅

🎀 TABLE EXTENSION 🎀

The function tcrdbtblput is used in order to store a record into a remote database object.

bool tcrdbtblput(TCRDB *rdb, const void *pkbuf, int pksiz, TCMAP *cols);

rdb specifies the remote database object.
pkbuf specifies the pointer to the region of the primary key.
pksiz specifies the size of the region of the primary key.
cols specifies a map object containing columns.

If successful, the return value is true, else, it is false 🌈

If a record with the same key exists in the database, it is overwritten — no warning, it just goes 🙈

The function tcrdbtblputkeep is used in order to store a new record into a remote database object.

tcrdbtblputkeep is the table-put that's like, “new key only, bestie.” If a record with the same key already exists in the database, this function has no effect — it literally just minds its business.

bool tcrdbtblputkeep(TCRDB *rdb, const void *pkbuf, int pksiz,
              TCMAP *cols);

rdb — the remote database object.
pkbuf — pointer to the region of the primary key.
pksiz — size of the region of the primary key.
cols — a map object containing columns.
If successful, the return value is true; else, it is false.

tcrdbtblputcat is used in order to concatenate columns of the existing record in a remote database object. If there’s no corresponding record, a new record is created — so it’s giving “merge or make it happen.” 🫶

bool tcrdbtblputcat(TCRDB *rdb, const void *pkbuf, int pksiz,
              TCMAP *cols);

rdb — the remote database object.
pkbuf — pointer to the region of the primary key.
pksiz — size of the region of the primary key.
cols — a map object containing columns.
If successful, the return value is true; else, it is false.

tcrdbtblout is used in order to remove a record of a remote database object. Bye-bye, record. 💅

bool tcrdbtblout(TCRDB *rdb, const void *pkbuf, int pksiz);

rdb — the remote database object.
pkbuf — pointer to the region of the primary key.
pksiz — size of the region of the primary key.
If successful, the return value is true; else, it is false.

tcrdbtblget is used in order to retrieve a record in a remote database object. It’s the “come through, columns” function. ✨

TCMAP *tcrdbtblget(TCRDB *rdb, const void *pkbuf, int pksiz);

rdb — the remote database object.
pkbuf — pointer to the region of the primary key.
pksiz — size of the region of the primary key.
If successful, the return value is a map object of the columns of the corresponding record. NULL is returned if no record corresponds.
Because the object of the return value is created with the function tcmapnew, it should be deleted with the function tcmapdel when it is no longer in use.

Bestie, don’t forget the tcmapdel — that’s your cleanup era. 🎀

tcrdbtblsetindex is used in order to set a column index to a remote database object. If the name of an existing index is specified, the index is rebuilt. An empty string means the primary key.

bool tcrdbtblsetindex(TCRDB *rdb, const char *name, int type);

rdb — the remote database object.
name — the name of a column. If the name of an existing index is specified, the index is rebuilt. An empty string means the primary key.
type — the index type:
- RDBITLEXICAL — lexical string
- RDBITDECIMAL — decimal string
- RDBITTOKEN — token inverted index
- RDBITQGRAM — q-gram inverted index
- RDBITOPT — the index is optimized
- RDBITVOID — the index is removed
- RDBITKEEP — if added by bitwise-or and the index exists, this function merely returns failure
If successful, the return value is true; else, it is false.

tcrdbtblgenuid is used in order to generate a unique ID number of a remote database object. Fresh ID, no duplicates, main character energy. 👑

int64_t tcrdbtblgenuid(TCRDB *rdb);

rdb — the remote database object.
The return value is the new unique ID number or -1 on failure.

tcrdbqrynew is used in order to create a query object.

RDBQRY *tcrdbqrynew(TCRDB *rdb);

rdb — the remote database object.
The return value is the new query object.

tcrdbqrydel is used in order to delete a query object. Clean up your query, bestie.

void tcrdbqrydel(RDBQRY *qry);

qry — the query object.

tcrdbqryaddcond is used in order to add a narrowing condition to a query object. It’s the “be more specific” button, and honestly? Obsessed.

void tcrdbqryaddcond(RDBQRY *qry, const char *name, int op, const
              char *expr);

qry — the query object.
name — the name of a column. An empty string means the primary key.
op — an operation type:
- RDBQCSTREQ — string which is equal to the expression
- RDBQCSTRINC — string which is included in the expression
- RDBQCSTRBW — string which begins with the expression
- RDBQCSTREW — string which ends with the expression
- RDBQCSTRAND — string which includes all tokens in the expression
- RDBQCSTROR — string which includes at least one token in the expression
- RDBQCSTROREQ — string which is equal to at least one token in the expression
- RDBQCSTRRX — string which matches regular expressions of the expression
- RDBQCNUMEQ — number which is equal to the expression
- RDBQCNUMGT — number which is greater than the expression
- RDBQCNUMGE — number which is greater than or equal to the expression
- RDBQCNUMLT — number which is less than the expression
- RDBQCNUMLE — number which is less than or equal to the expression
- RDBQCNUMBT — number which is between two tokens of the expression
- RDBQCNUMOREQ — number which is equal to at least one token in the expression
- RDBQCFTSPH — full-text search with the phrase of the expression
- RDBQCFTSAND — full-text search with all tokens in the expression
- RDBQCFTSOR — full-text search with at least one token in the expression
- RDBQCFTSEX — full-text search with the compound expression
- All operations can be flagged by bitwise-or: RDBQCNEGATE for negation, RDBQCNOIDX for using no index.
expr — specifies an operand exression.

tcrdbqrysetorder is used in order to set the order of a query object. Sorting? We love a sorted result. 💖

void tcrdbqrysetorder(RDBQRY *qry, const char *name, int type);

qry — the query object.
name — the name of a column. An empty string means the primary key.
type — the order type:
- RDBQOSTRASC — string ascending
- RDBQOSTRDESC — string descending
- RDBQONUMASC — number ascending
- RDBQONUMDESC — number descending

tcrdbqrysetlimit is used in order to set the limit number of records of the result of a query object. Boundaries, but make it cute. 🦋

void tcrdbqrysetlimit(RDBQRY *qry, int max, int skip);

qry — the query object.
max — the maximum number of records of the result. If it is negative, no limit is specified.
skip — the number of skipped records of the result. If it is not more than 0, no record is skipped.

tcrdbqrysearch is used in order to execute the search of a query object.

TCLIST *tcrdbqrysearch(RDBQRY *qry);

qry — the query object.
The return value is a list object of the primary keys of the corresponding records.
This function does never fail. It returns an empty list even if no record corresponds.
Because the object of the return value is created with the function tclistnew, it should be deleted with the function tclistdel when it is no longer in use.

Empty list still ate, okay? It’s valid. 💀

tcrdbqrysearchout is used in order to remove each record corresponding to a query object.

bool tcrdbqrysearchout(RDBQRY *qry);

qry — the query object of the database.
If successful, the return value is true; else, it is false.

tcrdbqrysearchget is used in order to get records corresponding to the search of a query object.

TCLIST *tcrdbqrysearchget(RDBQRY *qry);

qry — the query object.
The return value is a list object of zero separated columns of the corresponding records.
This function does never fail. It returns an empty list even if no record corresponds.
Each element of the list can be treated with the function tcrdbqryrescols.
Because the object of the return value is created with the function tclistnew, it should be deleted with the function tclistdel when it is no longer in use.

tcrdbqryrescols is used in order to get columns of a record in a search result.

TCMAP *tcrdbqryrescols(TCLIST *res, int index);

res — a list of zero separated columns of the search result.
index — the index of an element of the search result.
The return value is a map object containing columns.
Because the object of the return value is created with the function tcmapnew, it should be deleted with the function tcmapdel when it is no longer in use.

tcrdbqrysearchcount is used in order to get the count of corresponding records of a query object.

int tcrdbqrysearchcount(RDBQRY *qry);

qry — the query object.
The return value is the count of corresponding records or 0 on failure.

tcrdbqryhint is used in order to get the hint string of a query object.

const char *tcrdbqryhint(RDBQRY *qry);

qry — the query object.
The return value is the hint string.
This function should be called after the query execution by tcrdbqrysearch and so on.
The region of the return value is overwritten when this function is called again.

Read it, enjoy it, don’t hold onto the pointer forever — it gets overwritten. 🎀

tcrdbmetasearch is used in order to retrieve records with multiple query objects and get the set of the result.

okay so tcrdbmetasearch is the group-chat organizer of query objects — it takes a whole array and does set math on them 💅

TCLIST *tcrdbmetasearch(RDBQRY **qrys, int num, int type);

qrys — an array of the query objects, bestie. Like, all of them.
num — how many elements are in that array.
type — the set operation vibe: RDBMSUNION for the union set, RDBMSISECT for the intersection set, RDBMSDIFF for the difference set. Pick your fighter ✨

The return value is a list object of the primary keys of the corresponding records. This function does never fail — no cap. It returns an empty list even if no record corresponds, so don’t panic if it’s giving nothing. If the first query object has the order setting, the result array is sorted by the order. And because the object of the return value is created with the function tclistnew, it should be deleted with the function tclistdel when it is no longer in use. Clean up after yourself, queen 👑

The function tcrdbparasearch is used in order to search records for multiple servers in parallel — parallel bestie behavior, highkey iconic 🦋

TCLIST *tcrdbparasearch(RDBQRY **qrys, int num);

qrys — an array of the query objects.
num — the number of elements of the array.

The return value is a list object of zero separated columns of the corresponding records. This function does never fail. It returns an empty list even if no record corresponds. Each element of the list can be treated with the function tcrdbqryrescols. And because the object of the return value is created with the function tclistnew, it should be deleted with the function tclistdel when it is no longer in use. Same cleanup rule, same main character energy 🫶

👀 SEE ALSO 👀

That’s the whole TCRDB(3) page, bestie — footer vibes say 2010-08-05, and we are officially out 💅✨🎀

📦 where this page comes from

nixos 26.05: tokyotyrant 1.1.41
nixpkgs unstable: tokyotyrant 1.1.41
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

TCRDB(3)

TCRDB(3) — Tokyo Tyrant 💅

🌸 NAME 🌸

✨ DESCRIPTION ✨

💜 DESCRIPTION 💜

🧰 the function squad

🩷 tcrdberrmsg

🩷 tcrdbnew

🩷 tcrdbdel

🩷 tcrdbecode

🩷 tcrdbtune

🩷 tcrdbopen

🩷 tcrdbopen2

🩷 tcrdbclose

🩷 tcrdbput

🩷 tcrdbput2

🩷 tcrdbputkeep

🩷 tcrdbputkeep2

🩷 tcrdbputcat

🩷 tcrdbputcat2

🩷 tcrdbputshl

🩷 tcrdbputshl2

🩷 tcrdbputnr