Import BSDDB 4.7.25 (as of svn r89086)

docs_src/db/db_set_bt_compare.so

@@ -0,0 +1,70 @@
+m4_comment([$Id: db_set_bt_compare.so,v 10.50 2006/10/26 20:59:24 bostic Exp $])
+
+define(M4PAGELOCAL, dbh_set_bt_compare)
+include(m4/m4.seealso)
+
+m4_pf_header(m4_ref(dbh_set_bt_compare),
+ifelse(M4API, C_API, [dnl
+int
+DB-__GT__set_bt_compare(DB *db,
+    int (*bt_compare_fcn)(DB *db, const DBT *dbt1, const DBT *dbt2));
+])
+ifelse(M4API, CXX_API, [dnl
+extern "C" {
+    typedef int (*bt_compare_fcn_type)(DB *db, const DBT *dbt1, const DBT *dbt2);
+};
+int
+Db::set_bt_compare(bt_compare_fcn_type bt_compare_fcn);
+]))
+
+m4_p([dnl
+Set the Btree key comparison function.  The comparison function is
+called whenever it is necessary to compare a key specified by the
+application with a key currently stored in the tree.])
+
+m4_p([dnl
+If no comparison function is specified, the keys are compared lexically,
+with shorter keys collating before longer keys.])
+
+m4_scope_dbh(dbh_set_bt_compare)
+
+m4_when_dbopen(dbh_set_bt_compare, corrupt)
+
+m4_return(dbh_set_bt_compare, std)
+
+m4_parambegin
+m4_param(bt_compare_fcn, [dnl
+The m4_arg(bt_compare_fcn) function is the application-specified Btree
+comparison function.  The comparison function takes three parameters:
+m4_tagbegin
+m4_tag(m4_arg(db), [dnl
+The m4_arg(db) parameter is the enclosing database handle.])
+m4_tag(m4_arg(dbt1), [dnl
+The m4_arg(dbt1) parameter is the m4_ref(Dbt) representing the
+application supplied key.])
+m4_tag(m4_arg(dbt2), [dnl
+The m4_arg(dbt2) parameter is the m4_ref(Dbt) representing the
+current tree's key.])
+m4_tagend])
+
+m4_p([dnl
+The m4_arg(bt_compare_fcn) function must return an integer value less
+than, equal to, or greater than zero if the first key parameter is
+considered to be respectively less than, equal to, or greater than the
+second key parameter.  In addition, the comparison function must cause
+the keys in the database to be m4_italic(well-ordered).  The comparison
+function must correctly handle any key values used by the application
+(possibly including zero-length keys).  In addition, when Btree key
+prefix comparison is being performed (see m4_ref(dbh_set_bt_prefix) for
+more information), the comparison routine may be passed a prefix of any
+database key.  The m4_arg(data) and m4_arg(size) fields of the
+m4_ref(Dbt) are the only fields that may be used for the purposes of
+this comparison, and no particular alignment of the memory to which by
+the m4_arg(data) field refers may be assumed.])
+m4_paramend
+
+m4_err(dbh_set_bt_compare,
+einval, [the method was called after m4_ref(dbh_open) was called])
+
+m4_seealso(Db)
+m4_page_footer