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 in order to handle error messages, information messages and progress. More...
Defines
#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 (void buffer, size_t size, const char format,...)
	Pack a structure into a buffer.
size_t	wiredtiger_struct_size (const char *format,...)
	Calculate the size required to pack a structure.
int	wiredtiger_struct_unpack (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 to itself as possible error values. In addition, C99/POSIX error codes such as `ENOMEM`, `EINVAL` and `ENOTSUP` may also be returned, 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_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_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
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_freelist_bytes
	number of bytes in the freelist
#define	WT_STAT_file_freelist_entries
	number of entries in the freelist
#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_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

Detailed Description

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

Define 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 WiredTiger 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`.
`home_environment`	use the `WIREDTIGER_HOME` environment variable for naming unless the process is running with special privileges. See WiredTiger Home Directory for more information.	a boolean flag; default `false`.
`home_environment_priv`	use the `WIREDTIGER_HOME` environment variable for naming regardless of whether or not the process is running with special privileges. See WiredTiger Home Directory for more information.	a boolean flag; default `false`.
`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`.
`transactional`	support transactional semantics.	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"`, `"evict"`, `"evictserver"`, `"fileops"`, `"hazard"`, `"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 Home Directory Configuration 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_all.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_hello.c, ex_pack.c, ex_schema.c, ex_stat.c, ex_thread.c, and ex_transaction.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_all.c, ex_call_center.c, ex_config.c, ex_cursor.c, ex_extending.c, ex_hello.c, ex_pack.c, ex_schema.c, ex_thread.c, and ex_transaction.c.

int wiredtiger_struct_pack	(	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(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(buf, sizeof (buf), "iSh", &i, &s, &h);

Parameters:

buffer	a pointer to a packed byte array
size	the number of valid bytes in the buffer
format	the data format, see wiredtiger_struct_pack

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

Examples:: ex_all.c, and ex_pack.c.

size_t wiredtiger_struct_size	(	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;
        size = wiredtiger_struct_size("iSh", 42, "hello", -3);
        assert(size < 100);

Parameters:

format the data format, see wiredtiger_struct_pack

Returns:: the number of bytes needed for the matching call to wiredtiger_struct_pack

Examples:: ex_all.c, and ex_pack.c.

int wiredtiger_struct_unpack	(	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(buf, sizeof (buf), "iSh", &i, &s, &h);

Parameters:

buffer	a pointer to a packed byte array
size	the number of valid bytes in the buffer
format	the data format, see wiredtiger_struct_pack

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

Examples:: ex_all.c, and 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

Examples:: ex_all.c.

Classes

Defines

Functions

Error returns

Statistics for connection handles

Statistics for file objects

Detailed Description

Define Documentation

Function Documentation

Packing Examples