The functions, handles and methods applications use to access and manage data with WiredTiger. More...

Classes
struct	WT_ITEM
	A raw item of data to be managed. More...

struct	WT_CURSOR
	A WT_CURSOR handle is the interface to a cursor. More...

struct	WT_SESSION
	All data operations are performed in the context of a WT_SESSION. More...

struct	WT_CONNECTION
	A connection to a WiredTiger database. More...

struct	WT_EVENT_HANDLER
	The interface implemented by applications to handle error, informational and progress messages. More...

Macros
#define	WT_INTPACK64_MAXSIZE
	The maximum packed size of a 64-bit integer.

#define	WT_INTPACK32_MAXSIZE
	The maximum packed size of a 32-bit integer.

Functions
int	wiredtiger_open (const char home, WT_EVENT_HANDLER errhandler, const char config, WT_CONNECTION *connectionp)
	Open a connection to a database.

const char *	wiredtiger_strerror (int err)
	Return information about an error as a string; wiredtiger_strerror is a superset of the ISO C99/POSIX 1003.1-2001 function strerror.

int	wiredtiger_struct_pack (WT_SESSION session, void buffer, size_t size, const char *format,...)
	Pack a structure into a buffer.

int	wiredtiger_struct_size (WT_SESSION session, size_t sizep, const char *format,...)
	Calculate the size required to pack a structure.

int	wiredtiger_struct_unpack (WT_SESSION session, const void buffer, size_t size, const char *format,...)
	Unpack a structure from a buffer.

const char *	wiredtiger_version (int majorp, int minorp, int *patchp)
	Get version information.

Error returns
Most functions and methods in WiredTiger return an integer code indicating whether the operation succeeded or failed. A return of zero indicates success, all non-zero return values indicate some kind of failure. WiredTiger reserves all values from -31,800 to -31,999 as possible error return values. WiredTiger may also return C99/POSIX error codes such as `ENOMEM`, `EINVAL` and `ENOTSUP`, with the usual meanings. The following are all of the WiredTiger-specific error returns:
#define	WT_DEADLOCK
	Conflict between concurrent operations.

#define	WT_DUPLICATE_KEY
	Attempt to insert an existing key.

#define	WT_ERROR
	Non-specific WiredTiger error.

#define	WT_NOTFOUND
	Cursor item not found.

#define	WT_PANIC
	WiredTiger library panic.

Connection statistics
Statistics are accessed through cursors with `"statistics:"` URIs. Individual statistics can be queried through the cursor using the following keys. See Statistics Data for more information.
#define	WT_STAT_CONN_BLOCK_BYTE_READ
	bytes read by the block manager

#define	WT_STAT_CONN_BLOCK_BYTE_WRITE
	bytes written by the block manager

#define	WT_STAT_CONN_BLOCK_READ
	blocks read by the block manager

#define	WT_STAT_CONN_BLOCK_WRITE
	blocks written by the block manager

#define	WT_STAT_CONN_CACHE_BYTES_DIRTY
	cache: tracked dirty bytes in the cache

#define	WT_STAT_CONN_CACHE_BYTES_INUSE
	cache: bytes currently in the cache

#define	WT_STAT_CONN_CACHE_BYTES_MAX
	cache: maximum bytes configured

#define	WT_STAT_CONN_CACHE_BYTES_READ
	cache: bytes read into cache

#define	WT_STAT_CONN_CACHE_BYTES_WRITE
	cache: bytes written from cache

#define	WT_STAT_CONN_CACHE_EVICTION_CLEAN
	cache: unmodified pages evicted

#define	WT_STAT_CONN_CACHE_EVICTION_DIRTY
	cache: modified pages evicted

#define	WT_STAT_CONN_CACHE_EVICTION_FAIL
	cache: pages selected for eviction unable to be evicted

#define	WT_STAT_CONN_CACHE_EVICTION_HAZARD
	cache: eviction unable to acquire hazard pointer

#define	WT_STAT_CONN_CACHE_EVICTION_INTERNAL
	cache: internal pages evicted

#define	WT_STAT_CONN_CACHE_EVICTION_SLOW
	cache: eviction server unable to reach eviction goal

#define	WT_STAT_CONN_CACHE_PAGES_DIRTY
	cache: tracked dirty pages in the cache

#define	WT_STAT_CONN_CACHE_PAGES_INUSE
	cache: pages currently held in the cache

#define	WT_STAT_CONN_CACHE_READ
	cache: pages read into cache

#define	WT_STAT_CONN_CACHE_WRITE
	cache: pages written from cache

#define	WT_STAT_CONN_COND_WAIT
	pthread mutex condition wait calls

#define	WT_STAT_CONN_FILE_OPEN
	files currently open

#define	WT_STAT_CONN_MEMORY_ALLOCATION
	total heap memory allocations

#define	WT_STAT_CONN_MEMORY_FREE
	total heap memory frees

#define	WT_STAT_CONN_READ_IO
	total read I/Os

#define	WT_STAT_CONN_RWLOCK_READ
	pthread mutex shared lock read-lock calls

#define	WT_STAT_CONN_RWLOCK_WRITE
	pthread mutex shared lock write-lock calls

#define	WT_STAT_CONN_TXN_ANCIENT
	ancient transactions

#define	WT_STAT_CONN_TXN_BEGIN
	transactions

#define	WT_STAT_CONN_TXN_CHECKPOINT
	transaction checkpoints

#define	WT_STAT_CONN_TXN_COMMIT
	transactions committed

#define	WT_STAT_CONN_TXN_FAIL_CACHE
	transaction failures due to cache overflow

#define	WT_STAT_CONN_TXN_ROLLBACK
	transactions rolled-back

#define	WT_STAT_CONN_WRITE_IO
	total write I/Os

Statistics for data sources

#define	WT_STAT_DSRC_BLOCK_ALLOC
	blocks allocated

#define	WT_STAT_DSRC_BLOCK_ALLOCSIZE
	block manager file allocation unit size

#define	WT_STAT_DSRC_BLOCK_CHECKPOINT_SIZE
	checkpoint size

#define	WT_STAT_DSRC_BLOCK_EXTENSION
	block allocations requiring file extension

#define	WT_STAT_DSRC_BLOCK_FREE
	blocks freed

#define	WT_STAT_DSRC_BLOCK_MAGIC
	file magic number

#define	WT_STAT_DSRC_BLOCK_MAJOR
	file major version number

#define	WT_STAT_DSRC_BLOCK_MINOR
	minor version number

#define	WT_STAT_DSRC_BLOCK_SIZE
	block manager size

#define	WT_STAT_DSRC_BLOOM_COUNT
	bloom filters in the LSM tree

#define	WT_STAT_DSRC_BLOOM_FALSE_POSITIVE
	bloom filter false positives

#define	WT_STAT_DSRC_BLOOM_HIT
	bloom filter hits

#define	WT_STAT_DSRC_BLOOM_MISS
	bloom filter misses

#define	WT_STAT_DSRC_BLOOM_PAGE_EVICT
	bloom filter pages evicted from cache

#define	WT_STAT_DSRC_BLOOM_PAGE_READ
	bloom filter pages read into cache

#define	WT_STAT_DSRC_BLOOM_SIZE
	total size of bloom filters

#define	WT_STAT_DSRC_BTREE_COLUMN_DELETED
	column-store variable-size deleted values

#define	WT_STAT_DSRC_BTREE_COLUMN_FIX
	column-store fixed-size leaf pages

#define	WT_STAT_DSRC_BTREE_COLUMN_INTERNAL
	column-store internal pages

#define	WT_STAT_DSRC_BTREE_COLUMN_VARIABLE
	column-store variable-size leaf pages

#define	WT_STAT_DSRC_BTREE_COMPACT_REWRITE
	tree pages rewritten by compaction

#define	WT_STAT_DSRC_BTREE_ENTRIES
	total LSM, table or file object key/value pairs

#define	WT_STAT_DSRC_BTREE_FIXED_LEN
	fixed-record size

#define	WT_STAT_DSRC_BTREE_MAXINTLITEM
	maximum internal page item size

#define	WT_STAT_DSRC_BTREE_MAXINTLPAGE
	maximum internal page size

#define	WT_STAT_DSRC_BTREE_MAXLEAFITEM
	maximum leaf page item size

#define	WT_STAT_DSRC_BTREE_MAXLEAFPAGE
	maximum leaf page size

#define	WT_STAT_DSRC_BTREE_OVERFLOW
	overflow pages

#define	WT_STAT_DSRC_BTREE_ROW_INTERNAL
	row-store internal pages

#define	WT_STAT_DSRC_BTREE_ROW_LEAF
	row-store leaf pages

#define	WT_STAT_DSRC_CACHE_BYTES_READ
	bytes read into cache

#define	WT_STAT_DSRC_CACHE_BYTES_WRITE
	bytes written from cache

#define	WT_STAT_DSRC_CACHE_EVICTION_CLEAN
	unmodified pages evicted

#define	WT_STAT_DSRC_CACHE_EVICTION_DIRTY
	modified pages evicted

#define	WT_STAT_DSRC_CACHE_EVICTION_FAIL
	data source pages selected for eviction unable to be evicted

#define	WT_STAT_DSRC_CACHE_EVICTION_HAZARD
	eviction unable to acquire hazard pointer

#define	WT_STAT_DSRC_CACHE_EVICTION_INTERNAL
	internal pages evicted

#define	WT_STAT_DSRC_CACHE_OVERFLOW_VALUE
	overflow values cached in memory

#define	WT_STAT_DSRC_CACHE_READ
	pages read into cache

#define	WT_STAT_DSRC_CACHE_READ_OVERFLOW
	overflow pages read into cache

#define	WT_STAT_DSRC_CACHE_WRITE
	pages written from cache

#define	WT_STAT_DSRC_CURSOR_INSERT
	cursor insert calls

#define	WT_STAT_DSRC_CURSOR_INSERT_BULK
	bulk-loaded cursor-insert calls

#define	WT_STAT_DSRC_CURSOR_INSERT_BYTES
	cursor-insert key and value bytes inserted

#define	WT_STAT_DSRC_CURSOR_NEXT
	cursor next calls

#define	WT_STAT_DSRC_CURSOR_PREV
	cursor prev calls

#define	WT_STAT_DSRC_CURSOR_REMOVE
	cursor remove calls

#define	WT_STAT_DSRC_CURSOR_REMOVE_BYTES
	cursor-remove key bytes removed

#define	WT_STAT_DSRC_CURSOR_RESET
	cursor reset calls

#define	WT_STAT_DSRC_CURSOR_SEARCH
	cursor search calls

#define	WT_STAT_DSRC_CURSOR_SEARCH_NEAR
	cursor search near calls

#define	WT_STAT_DSRC_CURSOR_UPDATE
	cursor update calls

#define	WT_STAT_DSRC_CURSOR_UPDATE_BYTES
	cursor-update value bytes updated

#define	WT_STAT_DSRC_LSM_CHUNK_COUNT
	chunks in the LSM tree

#define	WT_STAT_DSRC_LSM_GENERATION_MAX
	highest merge generation in the LSM tree

#define	WT_STAT_DSRC_LSM_LOOKUP_NO_BLOOM
	queries that could have benefited from a Bloom filter that did not exist

#define	WT_STAT_DSRC_REC_DICTIONARY
	reconciliation dictionary matches

#define	WT_STAT_DSRC_REC_OVFL_KEY
	reconciliation overflow keys written

#define	WT_STAT_DSRC_REC_OVFL_VALUE
	reconciliation overflow values written

#define	WT_STAT_DSRC_REC_PAGE_DELETE
	reconciliation pages deleted

#define	WT_STAT_DSRC_REC_PAGE_MERGE
	reconciliation pages merged

#define	WT_STAT_DSRC_REC_SPLIT_INTL
	reconciliation internal pages split

#define	WT_STAT_DSRC_REC_SPLIT_LEAF
	reconciliation leaf pages split

#define	WT_STAT_DSRC_REC_WRITTEN
	reconciliation pages written

#define	WT_STAT_DSRC_TXN_UPDATE_CONFLICT
	update conflicts

#define	WT_STAT_DSRC_TXN_WRITE_CONFLICT
	write generation conflicts

Detailed Description

The functions, handles and methods applications use to access and manage data with WiredTiger.

Class Documentation

struct WT_ITEM

A raw item of data to be managed.

Data items have a pointer to the data and a length (limited to 4GB for items stored in tables).

Examples:: ex_extending.c.

Class Members
const void *	data	The memory reference of the data item. For items returned by a WT_CURSOR, the pointer is only valid until the next operation on that cursor. Applications that need to keep an item across multiple cursor operations must make a copy.
uint32_t	size	The number of bytes in the data item.

Macro Definition Documentation

#define WT_DEADLOCK

Conflict between concurrent operations.

This error is generated when an operation cannot be completed due to a conflict with concurrent operations. The operation may be retried; if a transaction is in progress, it should be rolled back and the operation retried in a new transaction.

#define WT_DUPLICATE_KEY

Attempt to insert an existing key.

This error is generated when the application attempts to insert a record with the same key as an existing record without the 'overwrite' configuration to WT_SESSION::open_cursor.

#define WT_ERROR

Non-specific WiredTiger error.

This error is returned when an error is not covered by a specific error return.

#define WT_INTPACK32_MAXSIZE

The maximum packed size of a 32-bit integer.

The wiredtiger_struct_pack function will pack single integers into at most this many bytes.

#define WT_INTPACK64_MAXSIZE

The maximum packed size of a 64-bit integer.

The wiredtiger_struct_pack function will pack single long integers into at most this many bytes.

#define WT_NOTFOUND

Cursor item not found.

This error indicates a cursor operation did not find a record to return. This includes search and other operations where no record matched the cursor's search key such as WT_CURSOR::update or WT_CURSOR::remove.

Examples:: ex_stat.c.

#define WT_PANIC

WiredTiger library panic.

This error indicates an underlying problem that requires the application exit and restart.

Function Documentation

int wiredtiger_open	(	const char *	home,
		WT_EVENT_HANDLER *	errhandler,
		const char *	config,
		WT_CONNECTION **	connectionp
	)

Open a connection to a database.

ret = wiredtiger_open(home, NULL, "create,cache_size=500M", &conn);

Parameters

home The path to the database home directory. See Database Home Directory for more information.

errhandler An error handler. If NULL, a builtin error handler is installed that writes error messages to stderr

config

Configuration string, see Configuration Strings. Permitted values:

Name	Effect	Values
`buffer_alignment`	in-memory alignment (in bytes) for buffers used for I/O. The default value of -1 indicates that a platform-specific alignment value should be used (512 bytes on Linux systems, zero elsewhere).	an integer between -1 and 1MB; default `-1`.
`cache_size`	maximum heap memory to allocate for the cache. A database should configure either a cache_size or a shared_cache not both.	an integer between 1MB and 10TB; default `100MB`.
`create`	create the database if it does not exist.	a boolean flag; default `false`.
`direct_io`	Use `O_DIRECT` to access files. Options are given as a list, such as `"direct_io=[data]"`.	a list, with values chosen from the following options: `"data"`, `"log"`; default empty.
`error_prefix`	prefix string for error messages.	a string; default empty.
`eviction_dirty_target`	continue evicting until the cache has less dirty pages than this (as a percentage). Dirty pages will only be evicted if the cache is full enough to trigger eviction.	an integer between 10 and 99; default `80`.
`eviction_target`	continue evicting until the cache becomes less full than this (as a percentage). Must be less than `eviction_trigger`.	an integer between 10 and 99; default `80`.
`eviction_trigger`	trigger eviction when the cache becomes this full (as a percentage).	an integer between 10 and 99; default `95`.
`extensions`	list of shared library extensions to load (using dlopen). Optional values are passed as the `config` parameter to WT_CONNECTION::load_extension. Complex paths may require quoting, for example, `extensions=("/path/ext.so"="entry=my_entry")`.	a list of strings; default empty.
`hazard_max`	maximum number of simultaneous hazard pointers per session handle.	an integer greater than or equal to 15; default `1000`.
`logging`	enable logging.	a boolean flag; default `false`.
`lsm_merge`	merge LSM chunks where possible.	a boolean flag; default `true`.
`multiprocess`	permit sharing between processes (will automatically start an RPC server for primary processes and use RPC for secondary processes). Not yet supported in WiredTiger.	a boolean flag; default `false`.
`session_max`	maximum expected number of sessions (including server threads).	an integer greater than or equal to 1; default `50`.
`shared_cache = (`	shared cache configuration options. A database should configure either a cache_size or a shared_cache not both.	a set of related configuration options defined below.
`chunk`	the granularity that a shared cache is redistributed.	an integer between 1MB and 10TB; default `10MB`.
`min`	minimum amount of cache a database in a shared cache can have.	an integer between 10MB and 10TB; default `50MB`.
`name`	name of a cache that is shared between databases.	a string; default empty.
`size`	maximum memory to allocate for the shared cache. Setting this will update the value if one is already set.	an integer between 1MB and 10TB; default `500MB`.
`)`
`sync`	flush files to stable storage when closing or writing checkpoints.	a boolean flag; default `true`.
`transactional`	support transactional semantics.	a boolean flag; default `true`.
`use_environment_priv`	use the `WIREDTIGER_CONFIG` and `WIREDTIGER_HOME` environment variables regardless of whether or not the process is running with special privileges. See Database Home Directory for more information.	a boolean flag; default `false`.
`verbose`	enable messages for various events. Options are given as a list, such as `"verbose=[evictserver,read]"`.	a list, with values chosen from the following options: `"block"`, `"shared_cache"`, `"ckpt"`, `"evict"`, `"evictserver"`, `"fileops"`, `"hazard"`, `"lsm"`, `"mutex"`, `"read"`, `"readserver"`, `"reconcile"`, `"salvage"`, `"verify"`, `"write"`; default empty.

Additionally, if a file named WiredTiger.config appears in the WiredTiger home directory, it is read for configuration values (see WiredTiger.config file for details). Configuration values specified in the config argument to the wiredtiger_open function override configuration values specified in the WiredTiger.config file.

connectionp A pointer to the newly opened connection handle

Returns: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_access.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_file.c, ex_hello.c, ex_pack.c, ex_schema.c, ex_stat.c, and ex_thread.c.

const char* wiredtiger_strerror ( int err )

Return information about an error as a string; wiredtiger_strerror is a superset of the ISO C99/POSIX 1003.1-2001 function strerror.

        const char *key = "non-existent key";
        cursor->set_key(cursor, key);
        if ((ret = cursor->remove(cursor)) != 0) {
                fprintf(stderr,
                    "cursor.remove: %s\n", wiredtiger_strerror(ret));
                return (ret);
        }

Parameters

err	a return value from a WiredTiger, C library or POSIX function

Returns: a string representation of the error

Examples:: ex_access.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_file.c, ex_hello.c, ex_pack.c, ex_schema.c, and ex_thread.c.

int wiredtiger_struct_pack	(	WT_SESSION *	session,
		void *	buffer,
		size_t	size,
		const char *	format,
			...
	)

Pack a structure into a buffer.

See Packing and Unpacking Data for a description of the permitted format strings.

Packing Examples

For example, the string "iSh" will pack a 32-bit integer followed by a NUL-terminated string, followed by a 16-bit integer. The default, big-endian encoding will be used, with no alignment. This could be used in C as follows:

        char buf[100];
        ret = wiredtiger_struct_pack(
            session, buf, sizeof(buf), "iSh", 42, "hello", -3);

Then later, the values can be unpacked as follows:

        int i;
        char *s;
        short h;
        ret = wiredtiger_struct_unpack(
            session, buf, sizeof(buf), "iSh", &i, &s, &h);

Parameters

session	the session handle
buffer	a pointer to a packed byte array
size	the number of valid bytes in the buffer
format	the data format, see Packing and Unpacking Data

Returns: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_pack.c.

int wiredtiger_struct_size	(	WT_SESSION *	session,
		size_t *	sizep,
		const char *	format,
			...
	)

Calculate the size required to pack a structure.

Note that for variable-sized fields including variable-sized strings and integers, the calculated sized merely reflects the expected sizes specified in the format string itself.

size_t size;

ret = wiredtiger_struct_size(session, &size, "iSh", 42, "hello", -3);

Parameters

session	the session handle
sizep	a location where the the number of bytes needed for the matching call to wiredtiger_struct_pack is returned
format	the data format, see Packing and Unpacking Data

Returns: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_pack.c.

int wiredtiger_struct_unpack	(	WT_SESSION *	session,
		const void *	buffer,
		size_t	size,
		const char *	format,
			...
	)

Unpack a structure from a buffer.

Reverse of wiredtiger_struct_pack: gets values out of a packed byte string.

        int i;
        char *s;
        short h;
        ret = wiredtiger_struct_unpack(
            session, buf, sizeof(buf), "iSh", &i, &s, &h);

Parameters

session	the session handle
buffer	a pointer to a packed byte array
size	the number of valid bytes in the buffer
format	the data format, see Packing and Unpacking Data

Returns: zero on success and a non-zero error code on failure. See Error Returns for details.

Examples:: ex_pack.c.

const char* wiredtiger_version	(	int *	majorp,
		int *	minorp,
		int *	patchp
	)

Get version information.

printf("WiredTiger version %s\n", wiredtiger_version(NULL, NULL, NULL));

        int major, minor, patch;
        (void)wiredtiger_version(&major, &minor, &patch);
        printf("WiredTiger version is %d, %d (patch %d)\n",
            major, minor, patch);

Parameters

majorp	a location where the major version number is returned
minorp	a location where the minor version number is returned
patchp	a location where the patch version number is returned

Returns: a string representation of the version

Classes

Macros

Functions

Error returns

Connection statistics

Statistics for data sources

Detailed Description

Class Documentation

Macro Definition Documentation

Function Documentation

Packing Examples