wrowe 00/12/08 09:18:08
Modified: include apr_dbm.h
src/dbm apr_dbm.c
Log:
Document and address several problems with apr_dbm - including;
make apr_dbm_open args sane in respect to both apr and dbm
note absurdity of apr_dbm_freedatum in a pool-managed implementation
note obscurity of apr_dbm_geterror in relation to apr
Revision Changes Path
1.4 +79 -11 apr-util/include/apr_dbm.h
Index: apr_dbm.h
===================================================================
RCS file: /home/cvs/apr-util/include/apr_dbm.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- apr_dbm.h 2000/12/06 08:01:09 1.3
+++ apr_dbm.h 2000/12/08 17:18:06 1.4
@@ -63,8 +63,20 @@
extern "C" {
#endif
+/**
+ * @package APR-UTIL DBM library
+ */
+
+/**
+ * Structure for referencing a dbm
+ * @defvar apr_dbm_t
+ */
typedef struct apr_dbm_t apr_dbm_t;
+/**
+ * Structure for referencing the datum record within a dbm
+ * @defvar apr_datum_t
+ */
typedef struct
{
char *dptr;
@@ -75,21 +87,77 @@
#define APR_DBM_READONLY 1 /* open for read-only access */
#define APR_DBM_READWRITE 2 /* open for read-write access */
#define APR_DBM_RWCREATE 3 /* open for r/w, create if needed */
-
-apr_status_t apr_dbm_open(const char *pathname, apr_pool_t *pool, int mode,
- apr_dbm_t **pdb);
+/**
+ * Open a dbm file by file name
+ * @param dbm The newly opened database
+ * @param name The dbm file name to open
+ * @param mode The flag value
+ * <PRE>
+ * APR_DBM_READONLY open for read-only access
+ * APR_DBM_READWRITE open for read-write access
+ * APR_DBM_RWCREATE open for r/w, create if needed
+ * </PRE>
+ * @param cntxt The pool to use when creating the dbm
+ * @tip The dbm name may not be a true file name, as many dbm packages
+ * append suffixes for seperate data and index files.
+ */
+apr_status_t apr_dbm_open(apr_dbm_t **dbm, const char *name, int mode,
+ apr_pool_t *cntxt);
+/**
+ * Close a dbm file previously opened by apr_dbm_open
+ * @param dbm The database to close
+ */
void apr_dbm_close(apr_dbm_t *db);
-apr_status_t apr_dbm_fetch(apr_dbm_t *db, apr_datum_t key,
+/**
+ * Fetch a dbm record value by key
+ * @param dbm The database
+ * @param key The key datum to find this record
+ * @param value The value datum retrieved for this record
+ */
+apr_status_t apr_dbm_fetch(apr_dbm_t *dbm, apr_datum_t key,
apr_datum_t *pvalue);
-apr_status_t apr_dbm_store(apr_dbm_t *db, apr_datum_t key, apr_datum_t
value);
-apr_status_t apr_dbm_delete(apr_dbm_t *db, apr_datum_t key);
-int apr_dbm_exists(apr_dbm_t *db, apr_datum_t key);
-apr_status_t apr_dbm_firstkey(apr_dbm_t *db, apr_datum_t *pkey);
-apr_status_t apr_dbm_nextkey(apr_dbm_t *db, apr_datum_t *pkey);
-void apr_dbm_freedatum(apr_dbm_t *db, apr_datum_t data);
+/**
+ * Store a dbm record value by key
+ * @param dbm The database
+ * @param key The key datum to store this record by
+ * @param value The value datum to store in this record
+ */
+apr_status_t apr_dbm_store(apr_dbm_t *dbm, apr_datum_t key, apr_datum_t
value);
+/**
+ * Delete a dbm record value by key
+ * @param dbm The database
+ * @param key The key datum of the record to delete
+ */
+apr_status_t apr_dbm_delete(apr_dbm_t *dbm, apr_datum_t key);
+/**
+ * Search for a key within the dbm
+ * @param dbm The database
+ * @param key The datum describing a key to test
+ */
+int apr_dbm_exists(apr_dbm_t *dbm, apr_datum_t key);
+/**
+ * Retrieve the first record key from a dbm
+ * @param dbm The database
+ * @param key The key datum of the first record
+ */
+apr_status_t apr_dbm_firstkey(apr_dbm_t *dbm, apr_datum_t *pkey);
+/**
+ * Retrieve the next record key from a dbm
+ * @param dbm The database
+ * @param key The key datum of the next record
+ */
+apr_status_t apr_dbm_nextkey(apr_dbm_t *dbm, apr_datum_t *pkey);
+
+/* XXX: This is bogus. If this is a pool-managed dbm wrapper, we
+ * don't free datum. If it isn't why pass pools?
+ */
+void apr_dbm_freedatum(apr_dbm_t *dbm, apr_datum_t data);
-void apr_dbm_geterror(apr_dbm_t *db, int *errcode, const char **errmsg);
+/* XXX: Need to change errcode to be handled canonically, and modify
+ * the prototype to follow apr_dso_error etc.
+ */
+void apr_dbm_geterror(apr_dbm_t *dbm, int *errcode, const char **errmsg);
#ifdef __cplusplus
}
1.9 +9 -2 apr-util/src/dbm/apr_dbm.c
Index: apr_dbm.c
===================================================================
RCS file: /home/cvs/apr-util/src/dbm/apr_dbm.c,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- apr_dbm.c 2000/12/08 00:36:16 1.8
+++ apr_dbm.c 2000/12/08 17:18:08 1.9
@@ -161,8 +161,8 @@
return rv;
}
-apr_status_t apr_dbm_open(const char *pathname, apr_pool_t *pool, int mode,
- apr_dbm_t **pdb)
+apr_status_t apr_dbm_open(apr_dbm_t **pdb, const char *pathname, int mode,
+ apr_pool_t *pool)
{
real_file_t file;
int dbmode;
@@ -286,11 +286,18 @@
return set_error(db);
}
+/* XXX: This is wrong - we must call freedatum after moving the
+ * datum contents into the pool before we return, the user can't
+ * concern themselves with free in a pool-managed application.
+ */
void apr_dbm_freedatum(apr_dbm_t *db, apr_datum_t data)
{
APR_DBM_FREEDATUM(db, data);
}
+/* XXX: This is wrong... need to return a canonical errcode as part
+ * of this package, and follow the apr_dso_error prototype.
+ */
void apr_dbm_geterror(apr_dbm_t *db, int *errcode, const char **errmsg)
{
*errcode = db->errcode;
