Couchbase C Client  3.0.4
Asynchronous C Client for Couchbase

Detailed Description

Get/Set Library Options.

The lcb_cntl() function and its various helpers are the means by which to modify settings within the library

See also


 Setting List
 Adjust tunables for the client.


lcb_STATUS lcb_cntl (lcb_INSTANCE *instance, int mode, int cmd, void *arg)
 This function exposes an ioctl/fcntl-like interface to read and write various configuration properties to and from an lcb_INSTANCE *handle. More...
lcb_STATUS lcb_cntl_string (lcb_INSTANCE *instance, const char *key, const char *value)
 Alternatively one may change configuration settings by passing a string key and value. More...
lcb_STATUS lcb_cntl_setu32 (lcb_INSTANCE *instance, int cmd, lcb_U32 arg)
 Convenience function to set a value as an lcb_U32. More...
lcb_U32 lcb_cntl_getu32 (lcb_INSTANCE *instance, int cmd)
 Retrieve an lcb_U32 setting. More...
int lcb_cntl_exists (int ctl)
 Determine if a specific control code exists. More...
void lcb_refresh_config (lcb_INSTANCE *instance)
 Force the library to refetch the cluster configuration. More...

Function Documentation

◆ lcb_cntl()

lcb_STATUS lcb_cntl ( lcb_INSTANCE instance,
int  mode,
int  cmd,
void *  arg 

This function exposes an ioctl/fcntl-like interface to read and write various configuration properties to and from an lcb_INSTANCE *handle.

instanceThe instance to modify
modeOne of LCB_CNTL_GET (to retrieve a setting) or LCB_CNTL_SET (to modify a setting). Note that not all configuration properties support SET.
cmdThe specific command/property to modify. This is one of the LCB_CNTL_* constants defined in this file. Note that it is safe (and even recommanded) to use the raw numeric value (i.e. to be backwards and forwards compatible with libcouchbase versions), as they are not subject to change.

Using the actual value may be useful in ensuring your application will still compile with an older libcouchbase version (though you may get a runtime error (see return) if the command is not supported

argThe argument passed to the configuration handler. The actual type of this pointer is dependent on the command in question. Typically for GET operations, the value of 'arg' is set to the current configuration value; and for SET operations, the current configuration is updated with the contents of *arg.
::LCB_ERR_UNSUPPORTED_OPERATION if the code is unrecognized
::LCB_ERR_INVALID_ARGUMENT if there was a problem with the argument (typically for LCB_CNTL_SET) other error codes depending on the command.

The following error codes are returned if the LCB_CNTL_DETAILED_ERRCODES are enabled.

::LCB_ECTL_UNKNOWN if the code is unrecognized
::LCB_ECTL_UNSUPPMODE An invalid mode was passed
::LCB_ERR_CONTROL_INVALID_ARGUMENT if the value was invalid
See also
example/analytics/analytics.c, example/fts/fts.c, and example/minimal/query.c.

◆ lcb_cntl_string()

lcb_STATUS lcb_cntl_string ( lcb_INSTANCE instance,
const char *  key,
const char *  value 

Alternatively one may change configuration settings by passing a string key and value.

This may be used to provide a simple interface from a command line or higher level language to allow the setting of specific key-value pairs.

The format for the value is dependent on the option passed, the following value types exist:

  • Timeval. A timeval value can either be specified as fractional seconds ("1.5" for 1.5 seconds), or in microseconds ("1500000"). In releases prior to libcouchbase 2.8, this was called timeout.
  • Number. This is any valid numerical value. This may be signed or unsigned depending on the setting.
  • Boolean. This specifies a boolean. A true value is either a positive numeric value (i.e. "1") or the string "true". A false value is a zero (i.e. "0") or the string "false".
  • Float. This is like a Number, but also allows fractional specification, e.g. "2.4".
  • String. Arbitrary string as char *, e.g. for client identification string.
  • Path. File path.
  • FILE*, Path. Set file stream pointer (lcb_cntl() style) or file path (lcb_cntl_string() style).
Code Name Type
LCB_CNTL_OP_TIMEOUT "operation_timeout" Timeval
LCB_CNTL_VIEW_TIMEOUT "view_timeout" Timeval
LCB_CNTL_QUERY_TIMEOUT "n1ql_timeout" Timeval
LCB_CNTL_HTTP_TIMEOUT "http_timeout" Timeval
LCB_CNTL_CONFIG_POLL_INTERVAL "config_poll_interval" Timeval
LCB_CNTL_CONFERRTHRESH "error_thresh_count" Number (Positive)
LCB_CNTL_CONFIGURATION_TIMEOUT "config_total_timeout" Timeval
LCB_CNTL_CONFIG_NODE_TIMEOUT "config_node_timeout" Timeval
LCB_CNTL_CONFDELAY_THRESH "error_thresh_delay" Timeval
LCB_CNTL_DURABILITY_TIMEOUT "durability_timeout" Timeval
LCB_CNTL_DURABILITY_INTERVAL "durability_interval" Timeval
LCB_CNTL_CONFIGCACHE "config_cache" Path
LCB_CNTL_DETAILED_ERRCODES "detailed_errcodes" Boolean
LCB_CNTL_RETRY_INTERVAL "retry_interval" Timeval
LCB_CNTL_HTTP_POOLSIZE "http_poolsize" Number
LCB_CNTL_VBGUESS_PERSIST "vbguess_persist" Boolean
LCB_CNTL_CONLOGGER_LEVEL "console_log_level" Number (enum #lcb_log_severity_t)
LCB_CNTL_ENABLE_MUTATION_TOKENS "enable_mutation_tokens" Boolean
LCB_CNTL_TCP_NODELAY "tcp_nodelay" Boolean
LCB_CNTL_CONLOGGER_FP "console_log_file" FILE*, Path
LCB_CNTL_CLIENT_STRING "client_string" String
LCB_CNTL_TCP_KEEPALIVE "tcp_keepalive" Boolean
LCB_CNTL_CONFIG_POLL_INTERVAL "config_poll_interval" Timeval
LCB_CNTL_IP6POLICY "ipv6" String ("disabled", "only", "allow")
  • Note, the actual API call is considered committed and will not disappear, however the existence of the various string settings are dependendent on the actual settings they map to. It is recommended that applications use the numerical lcb_cntl() as the string names are subject to change.
See also

◆ lcb_cntl_setu32()

lcb_STATUS lcb_cntl_setu32 ( lcb_INSTANCE instance,
int  cmd,
lcb_U32  arg 

Convenience function to set a value as an lcb_U32.

cmdsetting to modify
argthe new value
see lcb_cntl() for details

◆ lcb_cntl_getu32()

lcb_U32 lcb_cntl_getu32 ( lcb_INSTANCE instance,
int  cmd 

Retrieve an lcb_U32 setting.

cmdsetting to retrieve
the value.
This function does not return an error code. Ensure that the cntl is correct for this version, or use lcb_cntl() directly.

◆ lcb_cntl_exists()

int lcb_cntl_exists ( int  ctl)

Determine if a specific control code exists.

ctlthe code to check for
0 if it does not exist, nonzero if it exists.

◆ lcb_refresh_config()

void lcb_refresh_config ( lcb_INSTANCE instance)

Force the library to refetch the cluster configuration.


The library by default employs various heuristics to determine if a new configuration is needed from the cluster. However there are some situations in which an application may wish to force a refresh of the configuration:

  • If a specific node has been failed over and the library has received a configuration in which there is no master node for a given key, the library will immediately return the error LCB_ERR_NO_MATCHING_SERVER for the given item and will not request a new configuration. In this state, the client will not perform any network I/O until a request has been made to it using a key that is mapped to a known active node.
  • The library's heuristics may have failed to detect an error warranting a configuration change, but the application either through its own heuristics, or through an out-of-band channel knows that the configuration has changed.

This function is provided as an aid to assist in such situations

If you wish for your application to block until a new configuration is received, you must call lcb_wait() with the LCB_WAIT_NO_CHECK flag as this function call is not bound to a specific operation. Additionally there is no status notification as to whether this operation succeeded or failed (the configuration callback via lcb_set_configuration_callback() may provide hints as to whether a configuration was received or not, but by no means should be considered to be part of this function's control flow).

In general the use pattern of this function is like so:

unsigned retries = 5;
do {
err = lcb_get(instance, cookie, ncmds, cmds);
lcb_wait(instance, LCB_WAIT_NO_CHECK);
} else {
} while (retries);
if (err == LCB_SUCCESS) {
lcb_wait(instance, 0); // equivalent to lcb_wait(instance, LCB_WAIT_DEFAULT);
} else {
printf("Tried multiple times to fetch the key, but its node is down\n");
lcb_STATUS lcb_wait(lcb_INSTANCE *instance, lcb_WAITFLAGS flags)
Wait for completion of scheduled operations.
Error codes returned by the library.
Definition: error.h:202
void lcb_refresh_config(lcb_INSTANCE *instance)
Force the library to refetch the cluster configuration.