1 files changed, 97 insertions, 0 deletions
diff --git a/src/docs/cursor-ops.dox b/src/docs/cursor-ops.dox
new file mode 100644
index 00000000000..cd77621d43d
--- /dev/null
+++ b/src/docs/cursor-ops.dox
@@ -0,0 +1,97 @@
+/*! @page cursor_ops Cursor operations
+
+Common operations in WiredTiger are performed using WT_CURSOR handles.
+A cursor includes:
+
+- a position within a data source
+- getter/setters for key and value fields
+- encoding of fields to store in the data source
+- methods to navigate within and iterate through the data
+
+@section cursor_opening Opening a cursor
+
+Cursors are created using the WT_SESSION::open_cursor method.  The
+following are examples from the example program @ex_ref{ex_cursor.c}:
+
+@snippet ex_cursor.c open cursor #1
+@snippet ex_cursor.c open cursor #2
+
+In addition to traditional data sources, cursors in WiredTiger are used
+to access projections and even created data sources such as the run-time
+statistics:
+
+@snippet ex_cursor.c open cursor #3
+
+See @ref cursors for more information on available cursor types.
+
+@section cursor_position Positioning a cursor
+
+Cursors may be positioned at the beginning of the data source, the end of
+the data source, at an exact key within the data source, and near a key
+within the data source.  
+
+To invalidate the position of a cursor so that subsequent iterations start
+from the beginning or end of the data source, use the WT_CURSOR::reset method:
+
+@snippet ex_cursor.c cursor reset
+
+To move a cursor forward or backward in the data source, use the cursor
+WT_CURSOR::next and WT_CURSOR::prev methods:
+
+@snippet ex_cursor.c cursor next
+@snippet ex_cursor.c cursor prev
+
+If the WT_CURSOR::next and WT_CURSOR::prev methods are called on cursors
+without a position in the data source, they are positioned at the beginning
+or end of the data source, respectively.
+
+To position a cursor at a specific location in the data source, use the
+WT_CURSOR::search method:
+
+@snippet ex_cursor.c cursor search
+
+To position a cursor at or near a location in the data source, use the
+WT_CURSOR::search_near method:
+
+@snippet ex_cursor.c cursor search near
+
+@section cursor_writes Inserting and updating
+
+To insert new data, and optionally update existing data, using a cursor,
+use the WT_CURSOR::insert method:
+
+@snippet ex_cursor.c cursor insert
+
+By default, when inserting into a row-store, the WT_CURSOR::insert method
+returns an error if the key already exists in the store, otherwise it
+inserts a new key/value pair.  If the <code>overwrite</code> configuration
+string is specified to the WT_SESSION::open_cursor method, any previously
+existing key/value pair is updated to the new value rather than returning
+an error.
+
+By default, when updating an underlying column-store, the WT_CURSOR::insert
+method ignores the application's key value, instead, it allocates an unused
+record number in the store and returns that record number in the
+application's key.  If the <code>overwrite</code> configuration string is
+specified to the WT_SESSION::open_cursor method, the application's key
+value will be used to specify the record number being inserted or updated.
+
+To update existing data using a cursor, use the WT_CURSOR::update method:
+
+@snippet ex_cursor.c cursor update
+
+In all cases, calling WT_CURSOR::update where the key does not already
+exist in the store will return an error.
+
+To remove existing data using a cursor, use the WT_CURSOR::remove method:
+
+@snippet ex_cursor.c cursor remove
+
+@section cursor_error Cursor position after error
+
+After any cursor handle method failure, the cursor's position is
+undetermined.  Applications that cannot re-position the cursor after
+failure must duplicate the cursor before calling a cursor method that will
+attempt to re-position the cursor.  @notyet{cursor duplication}
+
+ */