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.

Statistics for connection handles
Statistics in WiredTiger are accessed through cursors with `"statistics:"` URIs. Individual statistics can be queried through the cursor using the following keys.
#define	WT_STAT_txn_ancient
	ancient transactions

#define	WT_STAT_block_read
	blocks read from a file

#define	WT_STAT_block_write
	blocks written to a file

#define	WT_STAT_cache_bytes_inuse
	cache: bytes currently held in the cache

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

#define	WT_STAT_cache_evict_internal
	cache: internal pages evicted

#define	WT_STAT_cache_bytes_max
	cache: maximum bytes configured

#define	WT_STAT_cache_evict_modified
	cache: modified pages evicted

#define	WT_STAT_cache_pages_inuse
	cache: pages currently held in the cache

#define	WT_STAT_cache_evict_hazard
	cache: pages selected for eviction not evicted because of a hazard reference

#define	WT_STAT_cache_evict_unmodified
	cache: unmodified pages evicted

#define	WT_STAT_checkpoint
	checkpoints

#define	WT_STAT_cond_wait
	condition wait calls

#define	WT_STAT_file_open
	files currently open

#define	WT_STAT_rwlock_rdlock
	rwlock readlock calls

#define	WT_STAT_rwlock_wrlock
	rwlock writelock calls

#define	WT_STAT_memalloc
	total memory allocations

#define	WT_STAT_memfree
	total memory frees

#define	WT_STAT_total_read_io
	total read I/Os

#define	WT_STAT_total_write_io
	total write I/Os

#define	WT_STAT_txn_begin
	transactions

#define	WT_STAT_txn_commit
	transactions committed

#define	WT_STAT_txn_rollback
	transactions rolled-back

Statistics for file objects

#define	WT_STAT_file_bulk_loaded
	bulk-loaded entries

#define	WT_STAT_file_col_deleted
	column-store deleted values

#define	WT_STAT_file_col_fix_pages
	column-store fixed-size leaf pages

#define	WT_STAT_file_col_int_pages
	column-store internal pages

#define	WT_STAT_file_col_var_pages
	column-store variable-size leaf pages

#define	WT_STAT_cursor_inserts
	cursor-inserts

#define	WT_STAT_cursor_read
	cursor-read

#define	WT_STAT_cursor_read_near
	cursor-read-near

#define	WT_STAT_cursor_read_next
	cursor-read-next

#define	WT_STAT_cursor_read_prev
	cursor-read-prev

#define	WT_STAT_cursor_removes
	cursor-removes

#define	WT_STAT_cursor_resets
	cursor-resets

#define	WT_STAT_cursor_updates
	cursor-updates

#define	WT_STAT_alloc
	file: block allocations

#define	WT_STAT_extend
	file: block allocations required file extension

#define	WT_STAT_free
	file: block frees

#define	WT_STAT_overflow_read
	file: overflow pages read from the file

#define	WT_STAT_page_read
	file: pages read from the file

#define	WT_STAT_page_write
	file: pages written to the file

#define	WT_STAT_file_size
	file: size

#define	WT_STAT_file_fixed_len
	fixed-record size

#define	WT_STAT_file_magic
	magic number

#define	WT_STAT_file_major
	major version number

#define	WT_STAT_file_maxintlitem
	maximum internal page item size

#define	WT_STAT_file_maxintlpage
	maximum internal page size

#define	WT_STAT_file_maxleafitem
	maximum leaf page item size

#define	WT_STAT_file_maxleafpage
	maximum leaf page size

#define	WT_STAT_file_minor
	minor version number

#define	WT_STAT_file_overflow
	overflow pages

#define	WT_STAT_file_allocsize
	page size allocation unit

#define	WT_STAT_rec_page_merge
	reconcile: deleted or temporary pages merged

#define	WT_STAT_rec_dictionary
	reconcile: dictionary match

#define	WT_STAT_rec_split_intl
	reconcile: internal pages split

#define	WT_STAT_rec_split_leaf
	reconcile: leaf pages split

#define	WT_STAT_rec_ovfl_key
	reconcile: overflow key

#define	WT_STAT_rec_ovfl_value
	reconcile: overflow value

#define	WT_STAT_rec_page_delete
	reconcile: pages deleted

#define	WT_STAT_rec_written
	reconcile: pages written

#define	WT_STAT_rec_hazard
	reconcile: unable to acquire hazard reference

#define	WT_STAT_file_row_int_pages
	row-store internal pages

#define	WT_STAT_file_row_leaf_pages
	row-store leaf pages

#define	WT_STAT_file_entries
	total entries

#define	WT_STAT_update_conflict
	update conflicts

#define	WT_STAT_file_write_conflicts
	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 should 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 generated for cases that are not covered by specific error returns.

#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.

Function Documentation

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

Open a connection to a database.

        WT_CONNECTION *conn;
        const char *home = "WT_TEST";
        ret = wiredtiger_open(home, NULL, "create,transactional", &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. By default, a platform-specific alignment value is 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.	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_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 extensions to load. Optional values are passed as the `config` parameter to WT_CONNECTION::load_extension. Complex paths may need quoting, for example, `extensions=("/path/to/ext.so"="entry=my_entry")`.	a list of strings; default empty.
`hazard_max`	number of simultaneous hazard references per session handle.	an integer greater than or equal to 15; default `30`.
`logging`	enable logging.	a boolean flag; default `false`.
`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`.
`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"`, `"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 = "some 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

Statistics for connection handles

Statistics for file objects

Detailed Description

Class Documentation

Macro Definition Documentation

Function Documentation

Packing Examples