Apache Portable Runtime Utility Library
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Modules | Data Structures | Macros | Typedefs | Functions
DBM routines
APR Utility Functions

Modules

 SDBM library

Data Structures

struct  apr_datum_t

Macros

#define APR_DBM_READONLY   1
#define APR_DBM_READWRITE   2
#define APR_DBM_RWCREATE   3
#define APR_DBM_RWTRUNC   4

Typedefs

typedef struct apr_dbm_t apr_dbm_t

Functions

apr_status_t apr_dbm_open_ex (apr_dbm_t **dbm, const char *type, const char *name, apr_int32_t mode, apr_fileperms_t perm, apr_pool_t *cntxt)
apr_status_t apr_dbm_open (apr_dbm_t **dbm, const char *name, apr_int32_t mode, apr_fileperms_t perm, apr_pool_t *cntxt)
void apr_dbm_close (apr_dbm_t *dbm)
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 *dbm, apr_datum_t key, apr_datum_t value)
apr_status_t apr_dbm_delete (apr_dbm_t *dbm, apr_datum_t key)
int apr_dbm_exists (apr_dbm_t *dbm, apr_datum_t key)
apr_status_t apr_dbm_firstkey (apr_dbm_t *dbm, apr_datum_t *pkey)
apr_status_t apr_dbm_nextkey (apr_dbm_t *dbm, apr_datum_t *pkey)
void apr_dbm_freedatum (apr_dbm_t *dbm, apr_datum_t data)
char * apr_dbm_geterror (apr_dbm_t *dbm, int *errcode, char *errbuf, apr_size_t errbufsize)
apr_status_t apr_dbm_get_usednames_ex (apr_pool_t *pool, const char *type, const char *pathname, const char **used1, const char **used2)
void apr_dbm_get_usednames (apr_pool_t *pool, const char *pathname, const char **used1, const char **used2)

Detailed Description

Macro Definition Documentation

#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

#define APR_DBM_RWTRUNC   4

open for r/w, truncating an existing DB if present

Typedef Documentation

typedef struct apr_dbm_t apr_dbm_t

Structure for referencing a dbm

Function Documentation

void apr_dbm_close ( apr_dbm_t dbm)

Close a dbm file previously opened by apr_dbm_open

Parameters
dbmThe database to close
apr_status_t apr_dbm_delete ( apr_dbm_t dbm,
apr_datum_t  key 
)

Delete a dbm record value by key

Parameters
dbmThe database
keyThe key datum of the record to delete
Remarks
It is not an error to delete a non-existent record.
int apr_dbm_exists ( apr_dbm_t dbm,
apr_datum_t  key 
)

Search for a key within the dbm

Parameters
dbmThe database
keyThe datum describing a key to test
apr_status_t apr_dbm_fetch ( apr_dbm_t dbm,
apr_datum_t  key,
apr_datum_t pvalue 
)

Fetch a dbm record value by key

Parameters
dbmThe database
keyThe key datum to find this record
pvalueThe value datum retrieved for this record
apr_status_t apr_dbm_firstkey ( apr_dbm_t dbm,
apr_datum_t pkey 
)

Retrieve the first record key from a dbm

Parameters
dbmThe database
pkeyThe key datum of the first record
void apr_dbm_freedatum ( apr_dbm_t dbm,
apr_datum_t  data 
)

Proactively toss any memory associated with the apr_datum_t.

Parameters
dbmThe database
dataThe datum to free.
void apr_dbm_get_usednames ( apr_pool_t *  pool,
const char *  pathname,
const char **  used1,
const char **  used2 
)

If the specified file/path were passed to apr_dbm_open(), return the actual file/path names which would be (created and) used. At most, two files may be used; used2 may be NULL if only one file is used.

Parameters
poolThe pool for allocating used1 and used2.
pathnameThe path name to generate used-names from.
used1The first pathname used by the apr_dbm implementation.
used2The second pathname used by apr_dbm. If only one file is used by the specific implementation, this will be set to NULL.
Remarks
The dbm file(s) don't need to exist. This function only manipulates the pathnames.
apr_status_t apr_dbm_get_usednames_ex ( apr_pool_t *  pool,
const char *  type,
const char *  pathname,
const char **  used1,
const char **  used2 
)

If the specified file/path were passed to apr_dbm_open(), return the actual file/path names which would be (created and) used. At most, two files may be used; used2 may be NULL if only one file is used.

Parameters
poolThe pool for allocating used1 and used2.
typeThe type of DBM you require info on
See Also
apr_dbm_open_ex
Parameters
pathnameThe path name to generate used-names from.
used1The first pathname used by the apr_dbm implementation.
used2The second pathname used by apr_dbm. If only one file is used by the specific implementation, this will be set to NULL.
Returns
An error if the specified type is invalid.
Remarks
The dbm file(s) don't need to exist. This function only manipulates the pathnames.
char* apr_dbm_geterror ( apr_dbm_t dbm,
int *  errcode,
char *  errbuf,
apr_size_t  errbufsize 
)

Report more information when an apr_dbm function fails.

Parameters
dbmThe database
errcodeA DBM-specific value for the error (for logging). If this isn't needed, it may be NULL.
errbufLocation to store the error text
errbufsizeThe size of the provided buffer
Returns
The errbuf parameter, for convenience.
apr_status_t apr_dbm_nextkey ( apr_dbm_t dbm,
apr_datum_t pkey 
)

Retrieve the next record key from a dbm

Parameters
dbmThe database
pkeyThe key datum of the next record
apr_status_t apr_dbm_open ( apr_dbm_t **  dbm,
const char *  name,
apr_int32_t  mode,
apr_fileperms_t  perm,
apr_pool_t *  cntxt 
)

Open a dbm file by file name

Parameters
dbmThe newly opened database
nameThe dbm file name to open
modeThe flag value
          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
          APR_DBM_RWTRUNC    open for r/w, truncate if already there
permPermissions to apply to if created
cntxtThe pool to use when creating the dbm
Remarks
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_ex ( apr_dbm_t **  dbm,
const char *  type,
const char *  name,
apr_int32_t  mode,
apr_fileperms_t  perm,
apr_pool_t *  cntxt 
)

Open a dbm file by file name and type of DBM

Parameters
dbmThe newly opened database
typeThe type of the DBM (not all may be available at run time)
 db   for Berkeley DB files
 gdbm for GDBM files
 ndbm for NDBM files
 sdbm for SDBM files (always available)
 default for the default DBM type
 
nameThe dbm file name to open
modeThe flag value
          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
          APR_DBM_RWTRUNC    open for r/w, truncate if already there
permPermissions to apply to if created
cntxtThe pool to use when creating the dbm
Remarks
The dbm name may not be a true file name, as many dbm packages append suffixes for seperate data and index files.
Bug:
In apr-util 0.9 and 1.x, the type arg was case insensitive. This was highly inefficient, and as of 2.x the dbm name must be provided in the correct case (lower case for all bundled providers)
apr_status_t apr_dbm_store ( apr_dbm_t dbm,
apr_datum_t  key,
apr_datum_t  value 
)

Store a dbm record value by key

Parameters
dbmThe database
keyThe key datum to store this record by
valueThe value datum to store in this record