Version 1.1.5
WiredTiger API

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.

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.

The maximum packed size of a 32-bit integer.

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

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:
homeThe path to the database home directory. See WiredTiger Home Directory for more information.
errhandlerAn error handler. If NULL, a builtin error handler is installed that writes error messages to stderr
configConfiguration string, see Configuration Strings. Permitted values:
NameEffectValues
buffer_alignmentin-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_sizemaximum heap memory to allocate for the cache.an integer between 1MB and 10TB; default 100MB.
createcreate the database if it does not exist.a boolean flag; default false.
direct_ioUse 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_prefixprefix string for error messages.a string; default empty.
eviction_targetcontinue 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_triggertrigger eviction when the cache becomes this full (as a percentage).an integer between 10 and 99; default 95.
extensionslist 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_maxnumber of simultaneous hazard references per session handle.an integer greater than or equal to 15; default 30.
home_environmentuse 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_privuse 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.
loggingenable logging.a boolean flag; default false.
multiprocesspermit 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_maxmaximum expected number of sessions (including server threads).an integer greater than or equal to 1; default 50.
transactionalsupport transactional semantics.a boolean flag; default false.
verboseenable 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.
connectionpA 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:
erra 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:
buffera pointer to a packed byte array
sizethe number of valid bytes in the buffer
formatthe 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:
formatthe 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:
buffera pointer to a packed byte array
sizethe number of valid bytes in the buffer
formatthe 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:
majorpa location where the major version number is returned
minorpa location where the minor version number is returned
patchpa location where the patch version number is returned
Returns:
a string representation of the version
Examples:
ex_all.c.