Import BSDDB 4.7.25 (as of svn r89086)

docs_src/db/db_set_dup_compare.so

@@ -0,0 +1,83 @@
+m4_comment([$Id: db_set_dup_compare.so,v 10.50 2004/08/13 03:38:56 bostic Exp $])
+
+define(M4PAGELOCAL, dbh_set_dup_compare)
+include(m4/m4.seealso)
+
+m4_pf_header(m4_ref(dbh_set_dup_compare),
+ifelse(M4API, C_API, [dnl
+int
+DB-__GT__set_dup_compare(DB *db,
+    int (*dup_compare_fcn)(DB *, const DBT *, const DBT *));
+])
+ifelse(M4API, CXX_API, [dnl
+extern "C" {
+    typedef int (*dup_compare_fcn_type)(DB *, const DBT *, const DBT *);
+};
+int
+Db::set_dup_compare(dup_compare_fcn_type dup_compare_fcn);
+]))
+
+define(__compareDuplicates_param, [dnl
+ifelse([$1], internal, [dnl
+The m4_arg(dup_compare_fcn) function is the application-specified
+duplicate data item comparison function.  The function takes three
+arguments:
+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 a m4_ref(Dbt) representing the application
+supplied data item.])
+m4_tag(m4_arg(dbt2), [dnl
+The m4_arg(dbt2) parameter is a m4_ref(Dbt) representing the current
+tree's data item.])
+m4_tagend],[dnl
+m4_parambegin
+m4_param(db, [dnl
+The m4_arg(db) parameter is the enclosing database handle.])
+m4_param(dbt1, [dnl
+The m4_arg(dbt1) parameter is a m4_ref(Dbt) representing the application
+supplied data item.])
+m4_param(dbt2, [dnl
+The m4_arg(dbt2) parameter is a m4_ref(Dbt) representing the current
+tree's data item.])
+m4_paramend])])
+
+define(__compareDuplicates_return, [dnl
+The m4_arg(dup_compare_fcn) function must return an integer value less
+than, equal to, or greater than zero if the first data item parameter
+is considered to be respectively less than, equal to, or greater than
+the second data item parameter.  In addition, the comparison function
+must cause the data items in the set to be m4_italic(well-ordered).  The
+comparison function must correctly handle any data item values used by
+the application (possibly including zero-length data items).  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 the m4_arg(data) field
+refers may be assumed.])
+
+m4_p([dnl
+Set the duplicate data item comparison function.  The comparison
+function is called whenever it is necessary to compare a data item
+specified by the application with a data item currently stored in the
+database.  Calling m4_ref(dbh_set_dup_compare) implies calling
+m4_ref(dbh_set_flags) with the m4_ref(DB_DUPSORT) flag.])
+
+m4_p([dnl
+If no comparison function is specified, the data items are compared
+lexically, with shorter data items collating before longer data items.])
+
+m4_when_dbopen(dbh_set_dup_compare, corrupt)
+
+m4_return(dbh_set_dup_compare, std)
+
+m4_parambegin
+m4_param(dup_compare_fcn, [dnl
+__compareDuplicates_param(internal)
+m4_p([__compareDuplicates_return])])
+m4_paramend
+
+m4_err(dbh_set_dup_compare, einval)
+
+m4_seealso(Db)
+m4_page_footer