Couchbase C Client  2.10.1
Asynchronous C Client for Couchbase
Setting List

Detailed Description

Adjust tunables for the client.


The constants in this file are used to control the behavior of the library. All of the operations above may be passed as the cmd parameter to the lcb_cntl() function, thus:

char something;
rv = lcb_cntl(instance, LCB_CNTL_GET, LCB_CNTL_FOO, &something);

will retrieve the setting of LCB_CNTL_FOO into something.

You may also use the lcb_cntl_string() function, which operates on strings and can set various configuration properties fairly simply. Note however that string names are subject to change, and not all configuration directives have a string alias:

rv = lcb_cntl_string("operation_timeout", "5.0");

Of the commands listed below, some will be read-only (i.e. you may only read the setting using the LCB_CNTL_GET mode), some will be write-only (i.e. you may only modify the setting, and use LCB_CNTL_SET for the mode) and some will be both readable and writable.

Along the documentation of each specific command, there is a table displaying the modes supported and the expected pointer type to be passed as the arg value into lcb_cntl(). Note that some read-write commands require different pointer types depending on whether the mode is retrieval or storage.

Timeout and Time Value Settings

There are various settings on the library that control behavior with respect to wall clock time.

Timeout settings control how long the library will wait for a certain event before proceeding to the next course of action (which may either be to try a different operation or fail the current one, depending on the specific timeout).

Other settings may configure how often the library proactively polls for a configuration update, retries various interally retried operations and so forth.

Time values are specified in microseconds stored within an lcb_U32.

When specified as an argument to lcb_cntl_string() or through the connection string, it will be parsed from a string float value where the integer-part is in seconds and the fractional-part is in fractions of a second.

Note that timeouts in libcouchbase are implemented via an event loop scheduler. As such their accuracy and promptness is limited by how often the event loop is invoked and how much wall time is spent in each of their handlers. Specifically if you issue long running blocking calls within any of the handlers (and this means any of the library's callbacks) then the timeout accuracy will be impacted.

Further behavior is dependent on the event loop plugin itself and how it schedules timeouts.

Configuration Stability Attributes
Configuration parameters are still subject to the API classification used in Interface Attributes. For deprecated control commands, lcb_cntl() will either perform the operation, or consider it a no-op, or return an error code.
Stability
Internal:

Macros

#define LCB_CNTL_SERVER_COMMON_FIELDS
 
#define LCB_CNTL_MEMDNODE_INFO
 
Get information about a memcached node. More...
 
#define LCB_CNTL_CONFIGNODE_INFO
 
Get information about the configuration node. More...
 
#define LCB_CNTL_IOPS_DEFAULT_TYPES
 
Get the default IOPS types for this build. More...
 
#define LCB_CNTL_CONFIG_HTTP_NODES
 
Set the nodes for the HTTP provider. More...
 
#define LCB_CNTL_CONFIG_CCCP_NODES
 
Set the nodes for the CCCP provider. More...
 
#define LCB_CNTL_CONFIG_ALL_NODES
 
Set the config nodes for the relevant providers. More...
 
#define LCB_CNTL_REINIT_CONNSTR
 
Reinitialize the instance using a connection string. More...
 
#define LCB_CNTL_RDBALLOCFACTORY
 
Set the allocator factory used by libcouchbase. More...
 
#define LCB_CNTL_VBGUESS_PERSIST
 
Persist heuristic vbucket information across updates. More...
 
#define LCB_CNTL_UNSAFE_OPTIMIZE
 
This is a collection of various options which sacrifice data safety for speed. More...
 
#define LCB_CNTL_TCP_NODELAY
 
Disable or enable Nagle's algorithm. More...
 
#define LCB_CNTL_KVTIMINGS
 
Get the lcb_HISTOGRAM object for key-value timings More...
 
#define LCB_CNTL_METRICS
 
More...
 
#define LCB_CNTL_USE_COLLECTIONS
 
#define LCB_CNTL_VB_NOREMAP
 
Do not use fast-forward map from cluster configuration. More...
 
#define LCB_CNTL_WAIT_FOR_CONFIG
 
Do not wait for GET_CLUSTER_CONFIG request to finish in lcb_wait(), when it is the only request in retry queue. More...
 
#define LCB_CNTL_OP_TIMEOUT
 
Operation Timeout More...
 
#define LCB_CNTL_VIEW_TIMEOUT
 
Views Timeout This is the I/O timeout for HTTP requests issues with LCB_HTTP_TYPE_VIEWS More...
 
#define LCB_CNTL_N1QL_TIMEOUT
 
N1QL Timeout This is the I/O timeout for N1QL queries, issued via lcb_n1ql_query() More...
 
#define LCB_CNTL_BUCKETNAME
 
Get the name of the bucket This returns the name of the bucket this instance is connected to, or NULL if not yet connected to a bucket More...
 
#define LCB_CNTL_BUCKETTYPE
 
Get the bucket type. More...
 
#define LCB_CNTL_HANDLETYPE
 
Get the handle type. More...
 
#define LCB_CNTL_VBCONFIG
 Get the vBucket handle. More...
 
#define LCB_CNTL_IOPS
 Get the iops implementation instance. More...
 
#define LCB_CNTL_VBMAP
 
Get the vBucket ID for a given key, based on the current configuration More...
 
#define LCB_CNTL_IP6POLICY
 
IPv4/IPv6 selection policy More...
 
#define LCB_CNTL_CONFERRTHRESH
 
Configuration error threshold. More...
 
#define LCB_CNTL_DURABILITY_TIMEOUT
 
Default timeout for lcb_durability_poll()
This is the time the client will spend sending repeated probes to a given key's vBucket masters and replicas before they are deemed not to have satisfied the durability requirements More...
 
#define LCB_CNTL_DURABILITY_INTERVAL
 
Polling grace interval for lcb_durability_poll() More...
 
#define LCB_CNTL_HTTP_TIMEOUT
 
Timeout for otherwise unspecified HTTP requests More...
 
#define LCB_CNTL_IOPS_DLOPEN_DEBUG
 
Print verbose plugin load information to console More...
 
#define LCB_CNTL_CONFIGURATION_TIMEOUT
 Initial bootstrap timeout. More...
 
#define LCB_CNTL_RANDOMIZE_BOOTSTRAP_HOSTS
 
Randomize order of bootstrap nodes. More...
 
#define LCB_CNTL_CONFIG_CACHE_LOADED
 
Determine if file-based configuration has been loaded More...
 
#define LCB_CNTL_FORCE_SASL_MECH
 
Force a specific SASL mechanism More...
 
#define LCB_CNTL_MAX_REDIRECTS
 
Maximum number of HTTP redirects to follow Set how many redirects the library should follow for the single request. More...
 
#define LCB_CNTL_CONFDELAY_THRESH
 
Refresh Throttling More...
 
#define LCB_CNTL_CONFIG_TRANSPORT
 
Get the transport used to fetch cluster configuration. More...
 
#define LCB_CNTL_CONFIG_NODE_TIMEOUT
 
Per-node configuration timeout. More...
 
#define LCB_CNTL_HTCONFIG_IDLE_TIMEOUT
 
Idling/Persistence for HTTP bootstrap More...
 
#define LCB_CNTL_CHANGESET
 
Get the current SCM changeset for the library binary More...
 
#define LCB_CNTL_CONFIGCACHE
 
File used for the configuration cache. More...
 
#define LCB_CNTL_CONFIGCACHE_RO
 File used for read-only configuration cache. More...
 
#define LCB_CNTL_SSL_MODE
 
Get SSL Mode More...
 
#define LCB_CNTL_SSL_CERT
 
Get SSL Certificate path More...
 
#define LCB_CNTL_SSL_KEY
 
Get SSL private key path More...
 
#define LCB_CNTL_SSL_TRUSTSTORE
 
Get SSL trust store path More...
 
#define LCB_CNTL_SSL_CACERT
 Alias for LCB_CNTL_SSL_CERT for backward compatibility. More...
 
#define LCB_RETRYOPT_CREATE(mode, policy)
 Create a retry setting value. More...
 
#define LCB_RETRYOPT_GETMODE(u)
 Get mode from retry setting value.
 
#define LCB_RETRYOPT_GETPOLICY(u)
 Get policy from retry setting value.
 
#define LCB_CNTL_RETRYMODE
 
Set retry policies More...
 
#define LCB_CNTL_HTCONFIG_URLTYPE
 
Set the URL selection mode. More...
 
#define LCB_CNTL_SYNCDESTROY
 
Determines whether to run the event loop internally within lcb_destroy() until no more I/O resources remain for the library. More...
 
#define LCB_CNTL_CONLOGGER_LEVEL
 
Sets the logging level for the console logger. More...
 
#define LCB_CNTL_CONLOGGER_FP
 Sets the output file (as a FILE*) for the console logger. More...
 
#define LCB_CNTL_DETAILED_ERRCODES
 
Sets the behavior for reporting network errors. More...
 
#define LCB_CNTL_RETRY_INTERVAL
 Sets the interval at which the retry queue will attempt to resend a failed operation. More...
 
#define LCB_CNTL_RETRY_BACKOFF
 When an operation has been retried more than once and it has still not succeeded, the library will attempt to back off for the operation by scheduling it to be retried in LCB_CNTL_RETRY_INTEVAL * ${n} microseconds, where ${n} is the factor controlled by this setting. More...
 
#define LCB_CNTL_RETRY_NMV_IMM
 
Whether commands are retried immediately upon receipt of not-my-vbucket replies. More...
 
#define LCB_CNTL_HTTP_POOLSIZE
 
Set the maximum pool size for pooled http (view request) sockets. More...
 
#define LCB_CNTL_HTTP_REFRESH_CONFIG_ON_ERROR
 
Determine whether or not a new configuration should be received when an error is received over the HTTP API (i.e. More...
 
#define LCB_CNTL_SCHED_IMPLICIT_FLUSH
 
Set the behavior of the lcb_sched_leave() API call. More...
 
#define LCB_CNTL_FETCH_MUTATION_TOKENS
 Request the server to return an additional 16 bytes of data for each mutation operation. More...
 
#define LCB_CNTL_DURABILITY_MUTATION_TOKENS
 
This setting determines whether the lcb_durability_poll() function will transparently attempt to use mutation token functionality (rather than checking the CAS). More...
 
#define LCB_CNTL_MUTATION_TOKENS_SUPPORTED
 
This read-only property determines if the mutation token mechanism is supported on the cluster itself. More...
 
#define LCB_CNTL_RESET_TIMEOUT_ON_WAIT
 
This setting determines if calls to lcb_wait() and lcb_wait3() will reset the timeout of pending operations to the time that lcb_wait() was called, rather than having the operation maintain the time of the call which scheduled it. More...
 
#define LCB_CNTL_N1QL_CLEARACHE
 
Clears the internal prepared statement cache for N1QL More...
 
#define LCB_CNTL_CLIENT_STRING
 
Sets additional text for negotiation. More...
 
#define LCB_CNTL_BUCKET_CRED
 Set credentials for a bucket. More...
 
#define LCB_CNTL_RETRY_NMV_INTERVAL
 
Set the amount of time the client should wait before retrying a not-my-vbucket response packet. More...
 
#define LCB_CNTL_READ_CHUNKSIZE
 
Limit the number of bytes to be read (and thereby processed) during I/O read operations. More...
 
#define LCB_CNTL_ENABLE_ERRMAP
 
Enable/Disable the Error Map feature. More...
 
#define LCB_CNTL_SELECT_BUCKET
 
Enable/Disable sending the SELECT_BUCKET command after authentication. More...
 
#define LCB_CNTL_TCP_KEEPALIVE
 
Enable/Disable setting the TCP_KEEPALIVE option on created sockets. More...
 
#define LCB_CNTL_CONFIG_POLL_INTERVAL
 
Set the amount of time to wait in between polling for a new configuration. More...
 
#define LCB_CNTL_SEND_HELLO
 
From version 2.7.4, the C library sends a HELLO command before authentication. More...
 
#define LCB_CNTL_LOG_REDACTION
 
Once redaction is enabled, anything at ERROR, WARN and INFO will wrap sensitive information with special tags, for further processing with the goal to remove or encrypt that information. More...
 
#define LCB_CNTL_ENABLE_TRACING
 
Activate/deactivate end-to-end tracing. More...
 
#define LCB_CNTL_TRACING_ORPHANED_QUEUE_FLUSH_INTERVAL
 
Flush interval for orphaned spans queue in default tracer. More...
 
#define LCB_CNTL_TRACING_ORPHANED_QUEUE_SIZE
 
Size of orphaned spans queue in default tracer. More...
 
#define LCB_CNTL_TRACING_THRESHOLD_QUEUE_FLUSH_INTERVAL
 
Flush interval for spans with total time over threshold in default tracer. More...
 
#define LCB_CNTL_TRACING_THRESHOLD_QUEUE_SIZE
 
Size of threshold queue in default tracer. More...
 
#define LCB_CNTL_TRACING_THRESHOLD_KV
 
Minimum time for the tracing span of KV service to be considered by threshold tracer. More...
 
#define LCB_CNTL_TRACING_THRESHOLD_N1QL
 
Minimum time for the tracing span of N1QL service to be considered by threshold tracer. More...
 
#define LCB_CNTL_TRACING_THRESHOLD_VIEW
 
Minimum time for the tracing span of VIEW service to be considered by threshold tracer. More...
 
#define LCB_CNTL_TRACING_THRESHOLD_FTS
 
Minimum time for the tracing span of FTS service to be considered by threshold tracer. More...
 
#define LCB_CNTL_TRACING_THRESHOLD_ANALYTICS
 
Minimum time for the tracing span of ANALYTICS service to be considered by threshold tracer. More...
 
#define LCB_CNTL_COMPRESSION_OPTS
 
Control how the library handles compression and deflation to and from the server. More...
 
#define LCB_CNTL_COMPRESSION_MIN_SIZE
 
Minimum size of the document payload to be compressed when compression enabled. More...
 
#define LCB_CNTL_COMPRESSION_MIN_RATIO
 
Minimum compression ratio (compressed / original) of the compressed payload to allow sending it to cluster. More...
 
#define LCB_CNTL_NETWORK
 
Select type of network (alternative addresses). More...
 
#define LCB_CNTL_HTTP_POOL_TIMEOUT
 
The amount of time the pool should wait before closing idle connections. More...
 
#define LCB_CNTL__MAX
 
This is not a command, but rather an indicator of the last item. More...
 

Typedefs

typedef struct rdb_ALLOCATOR *(* lcb_RDBALLOCFACTORY) (void)
 
typedef const char * lcb_BUCKETCRED[2]
 

Enumerations

enum  lcb_ipv6_t
 Modes for handling IPv6 in the IO layer. More...
 
enum  lcb_SSLOPTS
 
SSL options More...
 
enum  lcb_RETRYMODEOPTS
 Select retry mode to manipulate. More...
 
enum  lcb_RETRYCMDOPTS
 
enum  lcb_HTCONFIG_URLTYPE
 Enumeration representing various URL forms to use for the configuration stream. More...
 
enum  lcbtrace_THRESHOLDOPTS
 
enum  lcb_COMPRESSOPTS
 
Options for how to handle compression More...
 

Modes

Modes for the lcb_cntl() mode argument

#define LCB_CNTL_SET
 Modify a setting.
 
#define LCB_CNTL_GET
 Retrieve a setting.
 

Logging

Verbose logging may be enabled by default using the environment variable LCB_LOGLEVEL and setting it to a number > 1; higher values produce more verbose output.

The maximum level is 5.

You may also install your own logger using lcb_cntl() and the LCB_CNTL_LOGGER constant. Note that the logger functions will not be called rapidly from within hot paths.

enum  lcb_log_severity_t
 
Logging Levels More...
 
typedef void(* lcb_logging_callback) (struct lcb_logprocs_st *procs, unsigned int iid, const char *subsys, int severity, const char *srcfile, int srcline, const char *fmt, va_list ap)
 Logger callback. More...
 
#define LCB_CNTL_LOGGER
 
Access the lcb_logprocs structure More...
 
#define LCB_LOG_SPEC(fmt)
 Helper to express printf spec for sensitive data. More...
 
#define LCB_LOG_UD_OTAG
 
#define LCB_LOG_UD_CTAG
 
#define LCB_LOG_UD(instance, val)
 User data is data that is stored into Couchbase by the application user account. More...
 
#define LCB_LOG_MD_OTAG
 
#define LCB_LOG_MD_CTAG
 
#define LCB_LOG_MD(instance, val)
 Metadata is logical data needed by Couchbase to store and process user data. More...
 
#define LCB_LOG_SD_OTAG
 
#define LCB_LOG_SD_CTAG
 
#define LCB_LOG_SD(instance, val)
 System data is data from other parts of the system Couchbase interacts with over the network. More...
 

Data Structure Documentation

◆ lcb_cntl_server_t

struct lcb_cntl_server_t


Information describing the server

Stability
Internal:
Data Fields
int version Structure version.
union lcb_cntl_server_t v

◆ lcb_cntl_server_t.v.v1

struct lcb_cntl_server_t.v.v1

Current information here.

Data Fields
LCB_CNTL_SERVER_COMMON_FIELDS const char * sasl_mech Chosen SASL mechanism.

◆ lcb_cntl_iops_info_st

struct lcb_cntl_iops_info_st

Information about the I/O plugin.

Stability
Internal:
Data Fields
int version
union lcb_cntl_iops_info_st v

◆ lcb_cntl_rdballocfactory

struct lcb_cntl_rdballocfactory

Structure being used because function pointers can't technically be cast to void*.

Data Fields
lcb_RDBALLOCFACTORY factory

◆ lcb_cntl_vbinfo_t

struct lcb_cntl_vbinfo_t

Structure containing mapping information for a key.

Data Fields
int version
union lcb_cntl_vbinfo_t v

◆ lcb_cntl_vbinfo_t.v.v0

struct lcb_cntl_vbinfo_t.v.v0

v0

Data Fields
const void * key Input Key
lcb_SIZE nkey Input Length of key
int vbucket Output Mapped vBucket
int server_index Output Server index for vBucket

◆ lcb_logprocs

struct lcb_logprocs


Logging context

Stability
Volatile:

This structure defines the logging handlers. Currently there is only a single field defined which is the default callback for the loggers. This API may change.

Data Fields
int version
union lcb_logprocs v

Macro Definition Documentation

◆ LCB_CNTL_SERVER_COMMON_FIELDS

#define LCB_CNTL_SERVER_COMMON_FIELDS
Stability
Internal:

◆ LCB_CNTL_MEMDNODE_INFO

#define LCB_CNTL_MEMDNODE_INFO


Get information about a memcached node.

Stability
Internal:

This function will populate a structure containing various information about the specific host

Note that all fields in the structure are only valid until the following happens (whichever is first)

  1. Another libcouchbase API function is called
  2. The event loop regains control
Argument
Modes A
Get lcb_cntl_server_t*
Stability
Volatile:

◆ LCB_CNTL_CONFIGNODE_INFO

#define LCB_CNTL_CONFIGNODE_INFO


Get information about the configuration node.

Stability
Internal:

Note that this may not be available if the configuration mode is not HTTP

Argument
Modes A
Get lcb_cntl_server_t*
Stability
Volatile:

◆ LCB_CNTL_IOPS_DEFAULT_TYPES

#define LCB_CNTL_IOPS_DEFAULT_TYPES


Get the default IOPS types for this build.

Stability
Internal:

This provides a convenient way to determine what libcouchbase will use for IO when not explicitly specifying an iops structure to lcb_create()

Argument
Modes A
Get lcb_cntl_io_ops_info_st*
Note
You may pass NULL to lcb_cntl for the 'instance' parameter, as this does not read anything specific on the handle
Stability
Uncommitted:

◆ LCB_CNTL_CONFIG_HTTP_NODES

#define LCB_CNTL_CONFIG_HTTP_NODES


Set the nodes for the HTTP provider.

Stability
Internal:
Stability
Uncommitted:

This sets the initial list for the nodes to be used for bootstrapping the cluster. This may also be used subsequently in runtime to provide an updated list of nodes if the current list malfunctions.

The argument for this cntl accepts a NUL-terminated string containing one or more nodes. The format for this string is the same as the host parameter in lcb_create_st

Ports should specify the REST API port.

Argument
Modes A
Set char** (Array of strings)

◆ LCB_CNTL_CONFIG_CCCP_NODES

#define LCB_CNTL_CONFIG_CCCP_NODES


Set the nodes for the CCCP provider.

Stability
Internal:

Similar to LCB_CNTL_CONFIG_HTTP_NODES, but affects the CCCP provider instead. Ports should specify the memcached port

Argument
Modes A
Set char** (Array of strings)
Stability
Uncommitted:

◆ LCB_CNTL_CONFIG_ALL_NODES

#define LCB_CNTL_CONFIG_ALL_NODES


Set the config nodes for the relevant providers.

Stability
Internal:

This is passed an lcb_create_st2 structure which is used to initialize the providers. Useful if you wish to reinitialize or modify the provider settings after the instance itself has already been constructed.

Note that the username, password, bucket, and io fields are ignored.

Argument
Modes A
Set lcb_create_st2*
Stability
Uncommitted:

◆ LCB_CNTL_REINIT_CONNSTR

#define LCB_CNTL_REINIT_CONNSTR


Reinitialize the instance using a connection string.

Only options and the hostlists are used from this string. The bucket in the string (if specified) and any SSL options (i.e. couchbases:// or ssl=no_verify) are ignored.

This is the newer variant of LCB_CNTL_CONFIG_ALL_NODES

Argument
Modes A
Set const char *
Stability
Internal:

◆ LCB_CNTL_RDBALLOCFACTORY

#define LCB_CNTL_RDBALLOCFACTORY


Set the allocator factory used by libcouchbase.

The allocator factory is a function invoked with no arguments which yields a new rdb_ALLOCATOR object. Currently the use and API of this object is considered internal and its API and header files are in src/rdb.

Mode Arg
Set, Get lcb_cntl_rdballocfactory*
Stability
Volatile:

◆ LCB_CNTL_VBGUESS_PERSIST

#define LCB_CNTL_VBGUESS_PERSIST


Persist heuristic vbucket information across updates.

As of version 2.4.8 this option no longer has any effect, and vBucket heuristics are always retained for a maximum of 20 seconds.

Argument
Modes A
Get, Set int*
Stability
Volatile:

◆ LCB_CNTL_UNSAFE_OPTIMIZE

#define LCB_CNTL_UNSAFE_OPTIMIZE


This is a collection of various options which sacrifice data safety for speed.

Stability
Volatile:

◆ LCB_CNTL_TCP_NODELAY

#define LCB_CNTL_TCP_NODELAY


Disable or enable Nagle's algorithm.

The default is to disable it, as it will typically reduce latency. In general it is recommended not to touch this setting. It is here mainly for debugging.

Conventionally, the option to disable Nagle's algorithm is called "TCP_NODELAY", thus if this value is one, Nagle is off, and vice versa.

Stability
Volatile:

◆ LCB_CNTL_KVTIMINGS

#define LCB_CNTL_KVTIMINGS


Get the lcb_HISTOGRAM object for key-value timings

Argument
Modes A
Get lcb_HISTOGRAM**
Stability
Volatile:

◆ LCB_CNTL_METRICS

#define LCB_CNTL_METRICS


Stability
Volatile:
Activate/Get library metrics per-server

If using LCB_CNTL_SET, then this will activate the metrics, and should be called immediately after lcb_create. The arg parameter should be a pointer to an integer with the activation value (any non-zero value to activate).

If using LCB_CNTL_GET, the arg parameter should be a lcb_METRICS** variable, which will contain the pointer to the metrics upon completion.

◆ LCB_CNTL_USE_COLLECTIONS

#define LCB_CNTL_USE_COLLECTIONS
Argument
Modes A
Get, Set int (as boolean)
Stability
Volatile:

◆ LCB_CNTL_VB_NOREMAP

#define LCB_CNTL_VB_NOREMAP


Do not use fast-forward map from cluster configuration.

Use vb_noremap in the connection string

Argument
Modes A
Get, Set int* (as boolean)
Stability
Uncommitted:

◆ LCB_CNTL_WAIT_FOR_CONFIG

#define LCB_CNTL_WAIT_FOR_CONFIG


Do not wait for GET_CLUSTER_CONFIG request to finish in lcb_wait(), when it is the only request in retry queue.

Consider such retry queue as empty, and breakout to the place where lcb_wait() was invoked.

Argument
Modes A
Get, Set int* (as boolean)
Stability
Uncommitted:

◆ LCB_CNTL_OP_TIMEOUT

#define LCB_CNTL_OP_TIMEOUT


Operation Timeout

The operation timeout is the maximum amount of time the library will wait for an operation to receive a response before invoking its callback with a failure status.

An operation may timeout if:

  • A server is taking too long to respond
  • An updated cluster configuration has not been promptly received
lcb_U32 tmo = 3500000;
Argument
Modes A
Get, Set lcbU32*
Stability
Committed:
See also
lcb-time-info

◆ LCB_CNTL_VIEW_TIMEOUT

#define LCB_CNTL_VIEW_TIMEOUT


Views Timeout This is the I/O timeout for HTTP requests issues with LCB_HTTP_TYPE_VIEWS

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_N1QL_TIMEOUT

#define LCB_CNTL_N1QL_TIMEOUT


N1QL Timeout This is the I/O timeout for N1QL queries, issued via lcb_n1ql_query()

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_BUCKETNAME

#define LCB_CNTL_BUCKETNAME


Get the name of the bucket This returns the name of the bucket this instance is connected to, or NULL if not yet connected to a bucket

Argument
Modes A
Get const char*
Stability
Committed:
Examples:
example/analytics/analytics.c, example/fts/fts.c, and example/minimal/query.c.

◆ LCB_CNTL_BUCKETTYPE

#define LCB_CNTL_BUCKETTYPE


Get the bucket type.

This returns the bucket type - which is either of the following:

  • LCB_BTYPE_UNSPEC
  • LCB_BTYPE_COUCHBASE
  • LCB_BTYPE_EPHEMERAL
  • LCB_BTYPE_MEMCACHED
See also
https://developer.couchbase.com/documentation/server/current/architecture/core-data-access-buckets.html
Argument
Modes A
Get lcb_BTYPE*

◆ LCB_CNTL_HANDLETYPE

#define LCB_CNTL_HANDLETYPE


Get the handle type.

This returns the handle type - which is either LCB_TYPE_CLUSTER or LCB_TYPE_BUCKET

Argument
Modes A
Get lcb_type_t*

◆ LCB_CNTL_VBCONFIG

#define LCB_CNTL_VBCONFIG

Get the vBucket handle.

Obtains the current cluster configuration from the client.

Argument
Modes A
Get lcbvb_CONFIG**

◆ LCB_CNTL_IOPS

#define LCB_CNTL_IOPS

Get the iops implementation instance.

Argument
Modes A
Get lcb_io_opt_t*
Stability
Uncommitted:

◆ LCB_CNTL_VBMAP

#define LCB_CNTL_VBMAP


Get the vBucket ID for a given key, based on the current configuration

Argument
Modes A
Get lcb_cntl_vbinfo_t*
Stability
Committed:

◆ LCB_CNTL_IP6POLICY

#define LCB_CNTL_IP6POLICY


IPv4/IPv6 selection policy

Setting which controls whether hostname lookups should prefer IPv4 or IPv6

Use ipv6 in the connection string (e.g. "ipv6=allow" or "ipv6=only")

Argument
Modes A
Get, Set lcb_ipv6_t*
Stability
Committed:

◆ LCB_CNTL_CONFERRTHRESH

#define LCB_CNTL_CONFERRTHRESH


Configuration error threshold.

This number indicates how many network/mapping/not-my-vbucket errors are received before a configuration update is requested again.

Argument
Modes A
Get, Set lcb_SIZE*

◆ LCB_CNTL_DURABILITY_TIMEOUT

#define LCB_CNTL_DURABILITY_TIMEOUT


Default timeout for lcb_durability_poll()
This is the time the client will spend sending repeated probes to a given key's vBucket masters and replicas before they are deemed not to have satisfied the durability requirements

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_DURABILITY_INTERVAL

#define LCB_CNTL_DURABILITY_INTERVAL


Polling grace interval for lcb_durability_poll()

This is the time the client will wait between repeated probes to a given server.

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_HTTP_TIMEOUT

#define LCB_CNTL_HTTP_TIMEOUT


Timeout for otherwise unspecified HTTP requests

Examples of these kinds of HTTP requests might be cluster management, user management, etc.

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_IOPS_DLOPEN_DEBUG

#define LCB_CNTL_IOPS_DLOPEN_DEBUG


Print verbose plugin load information to console

This modifies a static, global setting regarding whether to print verbose information when trying to dynamically load an IO plugin. The information printed can be useful in determining why a plugin failed to load. This setting can also be controlled via the "LIBCOUCHBASE_DLOPEN_DEBUG" environment variable (and if enabled from the environment, will override the setting mentioned here).

Argument
Modes A
Get, Set int*
Note
Pass NULL to lcb_cntl for the 'instance' parameter.
Stability
Volatile:

◆ LCB_CNTL_CONFIGURATION_TIMEOUT

#define LCB_CNTL_CONFIGURATION_TIMEOUT

Initial bootstrap timeout.

This is how long the client will wait to obtain the initial configuration.

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_RANDOMIZE_BOOTSTRAP_HOSTS

#define LCB_CNTL_RANDOMIZE_BOOTSTRAP_HOSTS


Randomize order of bootstrap nodes.

This controls whether the connection attempts for configuration retrievals should be done in the supplied order or whether they should be randomized.

For the initial connection the supplied order is the list of hosts provided in the lcb_create_st structure. For subsequent connections this is the order of nodes as received by the server.

Argument
Modes A
Get, Set int*
Stability
Committed:

◆ LCB_CNTL_CONFIG_CACHE_LOADED

#define LCB_CNTL_CONFIG_CACHE_LOADED


Determine if file-based configuration has been loaded

If the configuration cache is in use, the argument pointer will be set to a true value. If the configuration cache was not used, the argument pointer will be set to false.

A false value may indicates that the client will need to load the configuration from the network. This may be caused by the following:

  • The configuration cache did not exist or was empty
  • The configuration cache contained stale information
Argument
Modes A
Get int*
Stability
Uncommitted:

◆ LCB_CNTL_FORCE_SASL_MECH

#define LCB_CNTL_FORCE_SASL_MECH


Force a specific SASL mechanism

Force a specific SASL mechanism to use for authentication. This can allow a user to ensure a certain level of security and have the connection fail if the desired mechanism is not available.

When setting this value, the arg parameter shall be a NUL-terminated string or a NULL pointer (to unset). When retrieving this value, the parameter shall be set to a char **. Note that this value (in LCB_CNTL_GET) is valid only until the next call to a libcouchbase API, after which it may have been freed.

Argument
Modes A
Get char**
Set char*

◆ LCB_CNTL_MAX_REDIRECTS

#define LCB_CNTL_MAX_REDIRECTS


Maximum number of HTTP redirects to follow Set how many redirects the library should follow for the single request.

Set to -1 to remove limit at all.

Argument
Modes A
Get, Set int*
Stability
Uncommitted:

◆ LCB_CNTL_LOGGER

#define LCB_CNTL_LOGGER


Access the lcb_logprocs structure

Stability
Uncommitted:

The lcb_logoprocs structure passed must not be freed until the instance is completely destroyed. This will only happen once the destruction callback is called (see lcb_set_destroy_callback()).

Argument
Modes A
Get lcb_logprocs**
Set lcb_logprocs*

◆ LCB_LOG_SPEC

#define LCB_LOG_SPEC (   fmt)

Helper to express printf spec for sensitive data.

Usage:

printf("Logged as " LCB_LOG_SPEC("%s") " user", LCB_LOG_UD(instance, doc->username));

◆ LCB_LOG_UD

#define LCB_LOG_UD (   instance,
  val 
)

User data is data that is stored into Couchbase by the application user account.

  • Key and value pairs in JSON documents, or the key exclusively
  • Application/Admin usernames that identify the human person
  • Names and email addresses asked during product registration and alerting
  • Usernames
  • Document xattrs
  • Query statements included in the log file collected by support that leak the document fields (Select floor_price from stock).

◆ LCB_LOG_MD

#define LCB_LOG_MD (   instance,
  val 
)

Metadata is logical data needed by Couchbase to store and process user data.

  • Cluster name
  • Bucket names
  • DDoc/view names
  • View code
  • Index names
  • Mapreduce Design Doc Name and Definition (IP)
  • XDCR Replication Stream Names
  • And other couchbase resource specific meta data

◆ LCB_LOG_SD

#define LCB_LOG_SD (   instance,
  val 
)

System data is data from other parts of the system Couchbase interacts with over the network.

  • IP addresses
  • IP tables
  • Hosts names
  • Ports
  • DNS topology

◆ LCB_CNTL_CONFDELAY_THRESH

#define LCB_CNTL_CONFDELAY_THRESH


Refresh Throttling

Modify the amount of time (in microseconds) before the LCB_CNTL_CONFERRTHRESH will forcefully be set to its maximum number forcing a configuration refresh.

Note that if you expect a high number of timeouts in your operations, you should set this to a high number (along with CONFERRTHRESH). If you are using the default timeout setting, then this value is likely optimal.

Argument
Modes A
Get, Set lcb_U32*
See also
LCB_CNTL_CONFERRTHRESH

◆ LCB_CNTL_CONFIG_TRANSPORT

#define LCB_CNTL_CONFIG_TRANSPORT


Get the transport used to fetch cluster configuration.

Argument
Modes A
Get lcb_config_transport_t*
Stability
Uncommitted:

◆ LCB_CNTL_CONFIG_NODE_TIMEOUT

#define LCB_CNTL_CONFIG_NODE_TIMEOUT


Per-node configuration timeout.

The per-node configuration timeout sets the amount of time to wait for each node within the bootstrap/configuration process. This interval is a subset of the LCB_CNTL_CONFIGURATION_TIMEOUT option mentioned above and is intended to ensure that the bootstrap process does not wait too long for a given node. Nodes that are physically offline may never respond and it may take a long time until they are detected as being offline. See CCBC-261 and CCBC-313 for more reasons.

Note
the CONFIGURATION_TIMEOUT should be higher than this number. No check is made to ensure that this is the case, however.
Argument
Modes A
Get, Set lcb_U32*
See also
LCB_CNTL_CONFIGURATION_TIMEOUT
Stability
Committed:

◆ LCB_CNTL_HTCONFIG_IDLE_TIMEOUT

#define LCB_CNTL_HTCONFIG_IDLE_TIMEOUT


Idling/Persistence for HTTP bootstrap

By default the behavior of the library for HTTP bootstrap is to keep the stream open at all times (opening a new stream on a different host if the existing one is broken) in order to proactively receive configuration updates.

The default value for this setting is -1. Changing this to another number invokes the following semantics:

  • The configuration stream is not kept alive indefinitely. It is kept open for the number of seconds specified in this setting. The socket is closed after a period of inactivity (indicated by this setting).
  • If the stream is broken (and no current refresh was requested by the client) then a new stream is not opened.
Argument
Modes A
Get, Set lcb_U32*
Stability
Volatile:

◆ LCB_CNTL_CHANGESET

#define LCB_CNTL_CHANGESET


Get the current SCM changeset for the library binary

Argument
Modes A
Get char**

◆ LCB_CNTL_CONFIGCACHE

#define LCB_CNTL_CONFIGCACHE


File used for the configuration cache.

The configuration cache allows to bootstrap from a cluster without using the initial bootstrap connection, considerably reducing latency. If the file passed does not exist, the normal bootstrap process is performed and the file is written to with the current information. File will be updated as the configuration in the cluster changes. Multiple instances may race to update the file, and that is the intended behavior.

Note
The leading directories for the file must exist, otherwise the file will never be created.
Configuration cache is not supported for memcached buckets
Argument
Modes A
Get char**
Set char*
Stability
Uncommitted:
See also
LCB_CNTL_CONFIG_CACHE_LOADED

◆ LCB_CNTL_CONFIGCACHE_RO

#define LCB_CNTL_CONFIGCACHE_RO

File used for read-only configuration cache.

This is identical to the LCB_CNTL_CONFIGCACHE directive, except that it guarantees that the library will never overwrite or otherwise modify the path specified.

See also
LCB_CNTL_CONFIGCACHE

◆ LCB_CNTL_SSL_MODE

#define LCB_CNTL_SSL_MODE


Get SSL Mode

Retrieve the SSL mode currently in use by the library. This is a read-only setting. To set the SSL mode at the library, specify the appropriate values within the connection string. See lcb_create_st3 for details.

Argument
Modes A
Get int* (value is one of lcb_SSLOPTS)
Stability
Committed:

◆ LCB_CNTL_SSL_CERT

#define LCB_CNTL_SSL_CERT


Get SSL Certificate path

Retrieve the path to the CA certificate (if any) being used.

Argument
Modes A
Get char**
See also
LCB_CNTL_SSL_MODE
Stability
Committed:

◆ LCB_CNTL_SSL_KEY

#define LCB_CNTL_SSL_KEY


Get SSL private key path

Retrieve the path to the private key (if any) being used. When key specified, the library will use it to authenticate on the services, skipping all other authentication mechanisms (SASL, HTTP Basic auth, etc)

Argument
Modes A
Get char**
See also
LCB_CNTL_SSL_MODE
https://developer.couchbase.com/documentation/server/5.0/security/security-certs-auth.html
Stability
Committed:

◆ LCB_CNTL_SSL_TRUSTSTORE

#define LCB_CNTL_SSL_TRUSTSTORE


Get SSL trust store path

Trust store might be NULL, in this case the library expects it to be concatenated with certificate.

Argument
Modes A
Get char**
See also
LCB_CNTL_SSL_MODE
https://developer.couchbase.com/documentation/server/5.0/security/security-certs-auth.html
Stability
Committed:

◆ LCB_CNTL_SSL_CACERT

#define LCB_CNTL_SSL_CACERT

Alias for LCB_CNTL_SSL_CERT for backward compatibility.

Deprecated:

◆ LCB_RETRYOPT_CREATE

#define LCB_RETRYOPT_CREATE (   mode,
  policy 
)

Create a retry setting value.

Parameters
modethe mode to set (
See also
lcb_RETRYMODEOPTS)
Parameters
policythe policy determining which commands should be retried (
See also
lcb_RETRYCMDOPTS)
Returns
a value which can be assigned to an lcb_U32 and passed to the LCB_CNTL_RETRYMODE setting

◆ LCB_CNTL_RETRYMODE

#define LCB_CNTL_RETRYMODE


Set retry policies

Stability
Volatile:

This function sets the retry behavior. The retry behavior is the action the library should take when a command has failed because of a failure which may be a result of environmental and/or topology issues. In such cases it may be possible to retry the command internally and have it succeed a second time without propagating an error back to the application.

The behavior consists of a mode and command selectors. The command selector indicates which commands should be retried (and which should be propagated up to the user) whereas the mode indicates under which circumstances should the command policy be used.

Disable retries anywhere:

for (int ii = 0; ii < LCB_RETRY_ON_MAX; ++ii) {
}

Only retry simple GET operations when retry is needed because of topology changes:

Determine the behavior of the library when a NOT_MY_VBUCKET is received:

Argument
Modes A
Get, Set lcb_U32 *

◆ LCB_CNTL_HTCONFIG_URLTYPE

#define LCB_CNTL_HTCONFIG_URLTYPE


Set the URL selection mode.

The URL type can be a mask of the lcb_HTCONFIG_URLTYPE constants which indicate which URLs the HTTP provider should use.

The default is to use the 25PLUS URI first, and fallback on the compat uri if the terse one fails with an HTTP 404 (Not Found). The new-style URI is considered more efficient on cluster resources and can help the cluster maintain many more streaming connections than the compat version, however it is only available in Couchbase Server 2.5 and greater.

This setting is only used when CCCP is disabled. This will typically be for older clusters or for memcached buckets.

Argument
Modes A
Get, Set int* (value is one of lcb_HTCONFIG_URLTYPE)
Stability
Volatile:
Primarily here to support tests and buggy HTTP servers/proxies which do not like to maintain a connection upon receipt of a 404.

◆ LCB_CNTL_SYNCDESTROY

#define LCB_CNTL_SYNCDESTROY


Determines whether to run the event loop internally within lcb_destroy() until no more I/O resources remain for the library.

This is usually only necessary if you are creating a lot of instances and/or are using memory leak analysis tools.

Argument
Modes A
Get, Set int* (as a boolean)
See also
lcb_destroy_async() and lcb_set_destroy_callback()
Stability
Volatile:

◆ LCB_CNTL_CONLOGGER_LEVEL

#define LCB_CNTL_CONLOGGER_LEVEL


Sets the logging level for the console logger.

If a logger is already initialized (either from the environment, or via lcb_cntl_logger() then this operation does nothing.

This is mainly useful for applications which want to proxy the built in logging options via command line options and the like, rather than setting it from the environment.

The argument passed to lcb_cntl() is an integer of 0 until LCB_LOG_MAX, though the actual type is of lcb_U32 rather than an enum type lcb_log_severity_t.

Argument
Modes A
Set const lcb_U32 *
See also
LCB_CNTL_LOGGER

◆ LCB_CNTL_CONLOGGER_FP

#define LCB_CNTL_CONLOGGER_FP

Sets the output file (as a FILE*) for the console logger.

Note that any existing file pointer will be cleared (but not fclose()d.

If used with lcb_cntl_string(), (using the console_log_file parameter), the third argument is taken as the name of a file. Note that the user is responsible for closing the file.

This setting does not require a library handle and therefore the first argument to lcb_cntl() should be NULL.

Argument
Modes A
Get FILE**
Set FILE*
See also
LCB_CNTL_LOGGER
LCB_CNTL_CONLOGGER_LEVEL

◆ LCB_CNTL_DETAILED_ERRCODES

#define LCB_CNTL_DETAILED_ERRCODES


Sets the behavior for reporting network errors.

By default network errors are returned as LCB_NETWORK_ERROR return codes for compatibility reasons. More detailed error codes may be available by enabling this option which will return appropriate error codes which have a category of LCB_ERRTYPE_NETWORK

Using this option means your programming model is centered around the various LCB_EIF* macros (see <libcouchbase/error.h>) rather than individual codes.

Argument
Modes A
Get, Set int * (As a boolean)

◆ LCB_CNTL_RETRY_INTERVAL

#define LCB_CNTL_RETRY_INTERVAL

Sets the interval at which the retry queue will attempt to resend a failed operation.

When an operation fails and the retry policy (see LCB_CNTL_RETRYMODE) allows the operation to be retried, it shall be placed into a queue, and then be retried within a given interval.

Setting a high value will be friendlier on the network but also potentially increase latency, while setting this to a low value may cause unnecessary network traffic for operations which are not yet ready to be retried.

Argument
Modes A
Get, Set lcb_U32* (microseconds)
See also
LCB_CNTL_RETRY_BACKOFF

◆ LCB_CNTL_RETRY_BACKOFF

#define LCB_CNTL_RETRY_BACKOFF

When an operation has been retried more than once and it has still not succeeded, the library will attempt to back off for the operation by scheduling it to be retried in LCB_CNTL_RETRY_INTEVAL * ${n} microseconds, where ${n} is the factor controlled by this setting.

Argument
Modes A
Get, Set float*

◆ LCB_CNTL_RETRY_NMV_IMM

#define LCB_CNTL_RETRY_NMV_IMM


Whether commands are retried immediately upon receipt of not-my-vbucket replies.

Since version 2.4.8, packets by default are retried immediately on a different node if it had previously failed with a not-my-vbucket response, and is thus not subject to the LCB_CNTL_RETRY_INTERVAL and LCB_CNTL_RETRY_BACKOFF settings. Disabling this setting will restore the older behavior. This may be used in case there are problems with the default heuristic/retry algorithm.

Stability
Volatile:

◆ LCB_CNTL_HTTP_POOLSIZE

#define LCB_CNTL_HTTP_POOLSIZE


Set the maximum pool size for pooled http (view request) sockets.

This should be set to 1 (the default) unless you plan to execute concurrent view requests. You may set this to 0 to disable pooling

Argument
Modes A
Get, Set lcb_SIZE
Stability
Volatile:

◆ LCB_CNTL_HTTP_REFRESH_CONFIG_ON_ERROR

#define LCB_CNTL_HTTP_REFRESH_CONFIG_ON_ERROR


Determine whether or not a new configuration should be received when an error is received over the HTTP API (i.e.

via lcb_make_http_request().

The default value is true, however you may wish to disable this if you are expectedly issuing a lot of requests which may result in an error.

Argument
Modes A
Get, Set int (as boolean)
Stability
Uncommitted:

◆ LCB_CNTL_SCHED_IMPLICIT_FLUSH

#define LCB_CNTL_SCHED_IMPLICIT_FLUSH


Set the behavior of the lcb_sched_leave() API call.

By default the lcb_sched_leave() will also set up the necessary requirements for flushing to the network. If this option is off then an explicit call to lcb_sched_flush() must be performed instead.

Argument
Modes A
Get, Set int (as boolean)
Stability
Volatile:

◆ LCB_CNTL_FETCH_MUTATION_TOKENS

#define LCB_CNTL_FETCH_MUTATION_TOKENS

Request the server to return an additional 16 bytes of data for each mutation operation.

This extra information may help with more reliable durability polling, but will also increase the size of the response packet.

This should be set on the instance before issuing lcb_connect(). While this may also be set after lcb_connect() is called, it will currently only take effect when a server reconnects (which itself may be undefined).

Argument
Modes A
Get, Set int (as boolean)

◆ LCB_CNTL_DURABILITY_MUTATION_TOKENS

#define LCB_CNTL_DURABILITY_MUTATION_TOKENS


This setting determines whether the lcb_durability_poll() function will transparently attempt to use mutation token functionality (rather than checking the CAS).

This option is most useful for older code which does explicitly use mutation tokens but would like to use its benefits when ensuring durability constraints are satisfied.

This option is enabled by default. Users may wish to disable this if they are performing durability operations against items stored from different client instances, as this will make use of a client-global state which is derived on a per-vBucket basis. This means that the last mutation performed on a given vBucket for the client will be used, which in some cases may be older or newer than the mutations passed to the lcb_durability_poll() function.

Argument
Modes A
Get, Set int (as boolean)
Stability
Volatile:

◆ LCB_CNTL_MUTATION_TOKENS_SUPPORTED

#define LCB_CNTL_MUTATION_TOKENS_SUPPORTED


This read-only property determines if the mutation token mechanism is supported on the cluster itself.

This will only be accurate once a single operation has been performed on the cluster - or in other words, once a connection to a data node has been established for the purposes of normal operations.

Argument
Modes A
Get int (as boolean)
Stability
Uncommitted:

◆ LCB_CNTL_RESET_TIMEOUT_ON_WAIT

#define LCB_CNTL_RESET_TIMEOUT_ON_WAIT


This setting determines if calls to lcb_wait() and lcb_wait3() will reset the timeout of pending operations to the time that lcb_wait() was called, rather than having the operation maintain the time of the call which scheduled it.

If the time between lcb_store3() and family and the lcb_wait() functions is long, it is recommended to disable this setting in order to avoid prematurely having operations time out.

Argument
Modes A
Get, Set int (as boolean)
Stability
Uncommitted:

Use "readj_wait_tmo" for the string version

◆ LCB_CNTL_N1QL_CLEARACHE

#define LCB_CNTL_N1QL_CLEARACHE


Clears the internal prepared statement cache for N1QL

This does not take any arguments, and is valid only on LCB_CNTL_SET

Stability
Uncommitted:

◆ LCB_CNTL_CLIENT_STRING

#define LCB_CNTL_CLIENT_STRING


Sets additional text for negotiation.

This allows wrappers or applications to add additional identifying information which can then be seen in the server logs.

Argument
Modes A
Get const char**
Set const char*

Use "client_string" for the string version

◆ LCB_CNTL_BUCKET_CRED

#define LCB_CNTL_BUCKET_CRED

Set credentials for a bucket.

This is used for N1QL and CBFT APIs to allow access to multiple buckets. It can also be used to set the password of the current bucket when reconnecting (in case it changes).

The format for the credentials is an array of two nul-terminated strings, the first refers to the bucket and the second refers to the password.

◆ LCB_CNTL_RETRY_NMV_INTERVAL

#define LCB_CNTL_RETRY_NMV_INTERVAL


Set the amount of time the client should wait before retrying a not-my-vbucket response packet.

The default is 100ms. The value should be specified in microseconds.

Use "retry_nmv_interval" with lcb_cntl_string()

Argument
Modes A
Get, Set lcb_U32*

◆ LCB_CNTL_READ_CHUNKSIZE

#define LCB_CNTL_READ_CHUNKSIZE


Limit the number of bytes to be read (and thereby processed) during I/O read operations.

This setting may be useful when the network is faster than processing resources.

Note
This setting only works for event-style I/O plugins. This means it has no effect on completion style plugins such as libuv or Windows IOCP
Argument
Modes A
Get, Set lcb_U32*

◆ LCB_CNTL_ENABLE_ERRMAP

#define LCB_CNTL_ENABLE_ERRMAP


Enable/Disable the Error Map feature.

This is disabled by default. Works only on servers which support error map

Use enable_errmap in the connection string

Argument
Modes A
Get, Set int* (as boolean)

◆ LCB_CNTL_SELECT_BUCKET

#define LCB_CNTL_SELECT_BUCKET


Enable/Disable sending the SELECT_BUCKET command after authentication.

This is useful to test auth, and should not be set by end-users.

Note that even if this feature is enabled (the default), the client will only send SELECT_BUCKET if the server indicates that it is supported during negotiation.

Use select_bucket in the connection string

Argument
Modes A
Get, Set int* (as boolean)

◆ LCB_CNTL_TCP_KEEPALIVE

#define LCB_CNTL_TCP_KEEPALIVE


Enable/Disable setting the TCP_KEEPALIVE option on created sockets.

This is enabled by default for I/O backends which support it.

The keepalive interval will be set to the operating system default.

Argument
Modes A
Get, Set int* (as boolean)

◆ LCB_CNTL_CONFIG_POLL_INTERVAL

#define LCB_CNTL_CONFIG_POLL_INTERVAL


Set the amount of time to wait in between polling for a new configuration.

This will have no effect if connected to a Memcached buckets, or using HTTP or File-based configurations (see the bootstrap_on connection string option).

This option facilitates 'fast failover' - in that the client can preemptively check for any cluster topology updates before encountering an error.

Argument
Modes A
Get, Set lcb_U32*

The value for this option is a time value. See the top of this header in respect to how to specify this.

Using a value of 0 disables this feature.

You can also use config_poll_interval in the connection string.

Note
Background polling is implemented in the library's non-blocking event loop. Synchronous clients (i.e. those using lcb_wait()) will only be able to poll as often as the library's event loop is active. If the library is suspended, that is, if not inside an lcb_wait() call, the library will be unable to do any kind of background polling.

◆ LCB_CNTL_SEND_HELLO

#define LCB_CNTL_SEND_HELLO


From version 2.7.4, the C library sends a HELLO command before authentication.

This works on all modern server versions, but may cause disconnects on more ancient variants (Couchbase 2.x for example).

This setting will disable the sending of the HELLO command (which older servers don't understand anyway). To disable the sending of hello, set this value to false.

Argument
Modes A
Get, Set int* (as boolean)
Stability
Committed:

You can also use send_hello=false in the connection string.

◆ LCB_CNTL_LOG_REDACTION

#define LCB_CNTL_LOG_REDACTION


Once redaction is enabled, anything at ERROR, WARN and INFO will wrap sensitive information with special tags, for further processing with the goal to remove or encrypt that information.

DEBUG or TRACE level logging are expected to have specific info.

Use log_redaction in the connection string

Argument
Modes A
Get, Set int* (as boolean)
Stability
Committed:

◆ LCB_CNTL_ENABLE_TRACING

#define LCB_CNTL_ENABLE_TRACING


Activate/deactivate end-to-end tracing.

Use enable_tracing in the connection string

Argument
Modes A
Get, Set int* (as boolean)
See also
lcb-tracing-api
Stability
Committed:

◆ LCB_CNTL_TRACING_ORPHANED_QUEUE_FLUSH_INTERVAL

#define LCB_CNTL_TRACING_ORPHANED_QUEUE_FLUSH_INTERVAL


Flush interval for orphaned spans queue in default tracer.

This is the time the tracer will wait between repeated attempts to flush most recent orphaned spans.

Use tracing_orphaned_queue_flush_interval in the connection string

lcb_U32 tmo = 10000000; // 10 seconds in microseconds
rv = lcb_cntl_string("tracing_orphaned_queue_flush_interval", "10.0");
Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_TRACING_ORPHANED_QUEUE_SIZE

#define LCB_CNTL_TRACING_ORPHANED_QUEUE_SIZE


Size of orphaned spans queue in default tracer.

Queues in default tracer has fixed size, and it will remove information about older spans, when the limit will be reached before flushing time.

Use tracing_orphaned_queue_size in the connection string

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_TRACING_THRESHOLD_QUEUE_FLUSH_INTERVAL

#define LCB_CNTL_TRACING_THRESHOLD_QUEUE_FLUSH_INTERVAL


Flush interval for spans with total time over threshold in default tracer.

This is the time the tracer will wait between repeated attempts to flush threshold queue.

Use tracing_threshold_queue_flush_interval in the connection string

lcb_U32 tmo = 10000000; // 10 seconds in microseconds
rv = lcb_cntl_string("tracing_threshold_queue_flush_interval", "10.0");
Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_TRACING_THRESHOLD_QUEUE_SIZE

#define LCB_CNTL_TRACING_THRESHOLD_QUEUE_SIZE


Size of threshold queue in default tracer.

Queues in default tracer has fixed size, and it will remove information about older spans, when the limit will be reached before flushing time.

Use tracing_threshold_queue_size in the connection string

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_TRACING_THRESHOLD_KV

#define LCB_CNTL_TRACING_THRESHOLD_KV


Minimum time for the tracing span of KV service to be considered by threshold tracer.

Use tracing_threshold_kv in the connection string

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_TRACING_THRESHOLD_N1QL

#define LCB_CNTL_TRACING_THRESHOLD_N1QL


Minimum time for the tracing span of N1QL service to be considered by threshold tracer.

Use tracing_threshold_n1ql in the connection string

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_TRACING_THRESHOLD_VIEW

#define LCB_CNTL_TRACING_THRESHOLD_VIEW


Minimum time for the tracing span of VIEW service to be considered by threshold tracer.

Use tracing_threshold_view in the connection string

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_TRACING_THRESHOLD_FTS

#define LCB_CNTL_TRACING_THRESHOLD_FTS


Minimum time for the tracing span of FTS service to be considered by threshold tracer.

Use tracing_threshold_fts in the connection string

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_TRACING_THRESHOLD_ANALYTICS

#define LCB_CNTL_TRACING_THRESHOLD_ANALYTICS


Minimum time for the tracing span of ANALYTICS service to be considered by threshold tracer.

Use tracing_threshold_analytics in the connection string

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_COMPRESSION_OPTS

#define LCB_CNTL_COMPRESSION_OPTS


Control how the library handles compression and deflation to and from the server.

Starting in Couchbase Server 3.0, compression can optionally be applied to incoming and outcoming data. For incoming (i.e. GET requests) the data may be received in compressed format and then allow the client to inflate the data upon receipt. For outgoing (i.e. SET requests) the data may be compressed on the client side and then be stored and recognized on the server itself.

The default behavior is to transparently handle compression for both incoming and outgoing data.

Note that if the lcb_STORECMDv0::datatype field is set with compression flags, the data will never be compressed by the library as this is an indication that it is already compressed.

Argument
Modes A
Get, Set int* (value is one of lcb_COMPRESSOPTS)
Stability
Committed:

◆ LCB_CNTL_COMPRESSION_MIN_SIZE

#define LCB_CNTL_COMPRESSION_MIN_SIZE


Minimum size of the document payload to be compressed when compression enabled.

Use compression_min_size in the connection string

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_COMPRESSION_MIN_RATIO

#define LCB_CNTL_COMPRESSION_MIN_RATIO


Minimum compression ratio (compressed / original) of the compressed payload to allow sending it to cluster.

Use compression_min_ratio in the connection string

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL_NETWORK

#define LCB_CNTL_NETWORK


Select type of network (alternative addresses).

Use network in the connection string

Argument
Modes A
Get const char**
Set const char*
Stability
Uncommitted:

◆ LCB_CNTL_HTTP_POOL_TIMEOUT

#define LCB_CNTL_HTTP_POOL_TIMEOUT


The amount of time the pool should wait before closing idle connections.

Use http_pool_timeout in the connection string

Argument
Modes A
Get, Set lcb_U32*
Stability
Committed:

◆ LCB_CNTL__MAX

#define LCB_CNTL__MAX


This is not a command, but rather an indicator of the last item.

Stability
Internal:

Typedef Documentation

◆ lcb_logging_callback

typedef void(* lcb_logging_callback) (struct lcb_logprocs_st *procs, unsigned int iid, const char *subsys, int severity, const char *srcfile, int srcline, const char *fmt, va_list ap)

Logger callback.

This callback is invoked for each logging message emitted

Parameters
procsthe logging structure provided
iidinstance id
subsysa string describing the module which emitted the message
severityone of the LCB_LOG_* severity constants.
srcfilethe source file which emitted this message
srclinethe line of the file for the message
fmta printf format string
apa va_list for vprintf

Enumeration Type Documentation

◆ lcb_ipv6_t

enum lcb_ipv6_t

Modes for handling IPv6 in the IO layer.

Enumerator
LCB_IPV6_DISABLED 

disable IPv6

LCB_IPV6_ONLY 

enforce only IPv6

LCB_IPV6_ALLOW 

use both IPv6 and IPv4

◆ lcb_log_severity_t


Logging Levels

Stability
Committed:
Enumerator
LCB_LOG_TRACE 

the most verbose level

LCB_LOG_DEBUG 

diagnostic information, required to investigate problems

LCB_LOG_INFO 

useful notices, not often

LCB_LOG_WARN 

error notifications

LCB_LOG_ERROR 

error messages, usually the library have to re-initialize connection instance

LCB_LOG_FATAL 

fatal errors, the library cannot proceed

LCB_LOG_MAX 

internal value for total number of levels

◆ lcb_SSLOPTS


SSL options

Stability
Committed:
Enumerator
LCB_SSL_ENABLED 

Use SSL.

LCB_SSL_NOVERIFY 

Don't verify certificates.

LCB_SSL_NOGLOBALINIT 

Do not call SSL's global init functions.

◆ lcb_RETRYMODEOPTS

Select retry mode to manipulate.

Enumerator
LCB_RETRY_ON_TOPOCHANGE 

Select retry for topology.

LCB_RETRY_ON_SOCKERR 

Select retry for network errors.

LCB_RETRY_ON_VBMAPERR 

Select retry for NOT_MY_VBUCKET responses.

LCB_RETRY_ON_MISSINGNODE 

Retry when there is no node for the item.

This case is special as the cmd setting is treated as a boolean rather than a bitmask

LCB_RETRY_ON_MAX 

< maximum index

◆ lcb_RETRYCMDOPTS

Enumerator
LCB_RETRY_CMDS_NONE 

Don't retry any commands.

A command which has been forwarded to a server and a not-my-vbucket has been received in response for it will result in a failure.

LCB_RETRY_CMDS_GET 

Only retry simple retrieval operations (excludes touch, get-and-touch, and get-locked) which may be retried many numbers of times without risking unintended data manipulation.

LCB_RETRY_CMDS_SAFE 

Retry operations which may potentially fail because they have been accepted by a previous server, but will not silently corrupt data.

Such commands include mutation operations containing a CAS.

LCB_RETRY_CMDS_ALL 

Retry all commands, disregarding any potential unintended receipt of errors or data mutation.

◆ lcb_HTCONFIG_URLTYPE

Enumeration representing various URL forms to use for the configuration stream.

Enumerator
LCB_HTCONFIG_URLTYPE_25PLUS 

/pools/default/b[s]/$bucket: Introduced in Couchbase Server 2.5

LCB_HTCONFIG_URLTYPE_COMPAT 

/pools/default/buckets[Streaming]/$bucket.

LCB_HTCONFIG_URLTYPE_TRYALL 

Try 25PLUS first and fallback to COMPAT

◆ lcb_COMPRESSOPTS


Options for how to handle compression

Stability
Committed:
Enumerator
LCB_COMPRESS_NONE 

Do not perform compression in any direction.

Data which is received compressed via the server will be indicated as such by having the LCB_VALUE_F_SNAPPYCOMP flag set in the lcb_GETRESPv0::datatype field

LCB_COMPRESS_IN 

Decompress incoming data, if the data has been compressed at the server.

If this is set, the datatype field in responses will always be stripped of the LCB_VALUE_F_SNAPPYCOMP flag.

LCB_COMPRESS_OUT 

Compress outgoing data.

Note that if the datatype field contains the LCB_VALUE_F_SNAPPYCOMP flag, then the data will never be compressed as it is assumed that it is already compressed.

LCB_COMPRESS_FORCE 

By default the library will send a HELLO command to the server to determine whether compression is supported or not.

Because commands may be pipelined prior to the scheduing of the HELLO command it is possible that the first few commands may not be compressed when schedule due to the library not yet having negotiated settings with the server. Setting this flag will force the client to assume that all servers support compression despite a HELLO not having been intially negotiated.