1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17#ifndef APR_DBM_H 18#define APR_DBM_H 19 20#include "apu.h" 21#include "apr.h" 22#include "apr_errno.h" 23#include "apr_pools.h" 24#include "apr_file_info.h" 25 26#ifdef __cplusplus 27extern "C" { 28#endif 29 30/** 31 * @file apr_dbm.h 32 * @brief APR-UTIL DBM library 33 */ 34/** 35 * @defgroup APR_Util_DBM DBM routines 36 * @ingroup APR_Util 37 * @{ 38 */ 39/** 40 * Structure for referencing a dbm 41 */ 42typedef struct apr_dbm_t apr_dbm_t; 43 44/** 45 * Structure for referencing the datum record within a dbm 46 */ 47typedef struct 48{ 49 /** pointer to the 'data' to retrieve/store in the DBM */ 50 char *dptr; 51 /** size of the 'data' to retrieve/store in the DBM */ 52 apr_size_t dsize; 53} apr_datum_t; 54 55/* modes to open the DB */ 56#define APR_DBM_READONLY 1 /**< open for read-only access */ 57#define APR_DBM_READWRITE 2 /**< open for read-write access */ 58#define APR_DBM_RWCREATE 3 /**< open for r/w, create if needed */ 59#define APR_DBM_RWTRUNC 4 /**< open for r/w, truncating an existing 60 DB if present */ 61/** 62 * Open a dbm file by file name and type of DBM 63 * @param dbm The newly opened database 64 * @param type The type of the DBM (not all may be available at run time) 65 * <pre> 66 * db for Berkeley DB files 67 * gdbm for GDBM files 68 * ndbm for NDBM files 69 * sdbm for SDBM files (always available) 70 * default for the default DBM type 71 * </pre> 72 * @param name The dbm file name to open 73 * @param mode The flag value 74 * <PRE> 75 * APR_DBM_READONLY open for read-only access 76 * APR_DBM_READWRITE open for read-write access 77 * APR_DBM_RWCREATE open for r/w, create if needed 78 * APR_DBM_RWTRUNC open for r/w, truncate if already there 79 * </PRE> 80 * @param perm Permissions to apply to if created 81 * @param cntxt The pool to use when creating the dbm 82 * @remark The dbm name may not be a true file name, as many dbm packages 83 * append suffixes for seperate data and index files. 84 * @bug In apr-util 0.9 and 1.x, the type arg was case insensitive. This 85 * was highly inefficient, and as of 2.x the dbm name must be provided in 86 * the correct case (lower case for all bundled providers) 87 */ 88 89APU_DECLARE(apr_status_t) apr_dbm_open_ex(apr_dbm_t **dbm, const char* type, 90 const char *name, 91 apr_int32_t mode, apr_fileperms_t perm, 92 apr_pool_t *cntxt); 93 94 95/** 96 * Open a dbm file by file name 97 * @param dbm The newly opened database 98 * @param name The dbm file name to open 99 * @param mode The flag value 100 * <PRE> 101 * APR_DBM_READONLY open for read-only access 102 * APR_DBM_READWRITE open for read-write access 103 * APR_DBM_RWCREATE open for r/w, create if needed 104 * APR_DBM_RWTRUNC open for r/w, truncate if already there 105 * </PRE> 106 * @param perm Permissions to apply to if created 107 * @param cntxt The pool to use when creating the dbm 108 * @remark The dbm name may not be a true file name, as many dbm packages 109 * append suffixes for seperate data and index files. 110 */ 111APU_DECLARE(apr_status_t) apr_dbm_open(apr_dbm_t **dbm, const char *name, 112 apr_int32_t mode, apr_fileperms_t perm, 113 apr_pool_t *cntxt); 114 115/** 116 * Close a dbm file previously opened by apr_dbm_open 117 * @param dbm The database to close 118 */ 119APU_DECLARE(void) apr_dbm_close(apr_dbm_t *dbm); 120 121/** 122 * Fetch a dbm record value by key 123 * @param dbm The database 124 * @param key The key datum to find this record 125 * @param pvalue The value datum retrieved for this record 126 */ 127APU_DECLARE(apr_status_t) apr_dbm_fetch(apr_dbm_t *dbm, apr_datum_t key, 128 apr_datum_t *pvalue); 129/** 130 * Store a dbm record value by key 131 * @param dbm The database 132 * @param key The key datum to store this record by 133 * @param value The value datum to store in this record 134 */ 135APU_DECLARE(apr_status_t) apr_dbm_store(apr_dbm_t *dbm, apr_datum_t key, 136 apr_datum_t value); 137 138/** 139 * Delete a dbm record value by key 140 * @param dbm The database 141 * @param key The key datum of the record to delete 142 * @remark It is not an error to delete a non-existent record. 143 */ 144APU_DECLARE(apr_status_t) apr_dbm_delete(apr_dbm_t *dbm, apr_datum_t key); 145 146/** 147 * Search for a key within the dbm 148 * @param dbm The database 149 * @param key The datum describing a key to test 150 */ 151APU_DECLARE(int) apr_dbm_exists(apr_dbm_t *dbm, apr_datum_t key); 152 153/** 154 * Retrieve the first record key from a dbm 155 * @param dbm The database 156 * @param pkey The key datum of the first record 157 */ 158APU_DECLARE(apr_status_t) apr_dbm_firstkey(apr_dbm_t *dbm, apr_datum_t *pkey); 159 160/** 161 * Retrieve the next record key from a dbm 162 * @param dbm The database 163 * @param pkey The key datum of the next record 164 */ 165APU_DECLARE(apr_status_t) apr_dbm_nextkey(apr_dbm_t *dbm, apr_datum_t *pkey); 166 167/** 168 * Proactively toss any memory associated with the apr_datum_t. 169 * @param dbm The database 170 * @param data The datum to free. 171 */ 172APU_DECLARE(void) apr_dbm_freedatum(apr_dbm_t *dbm, apr_datum_t data); 173 174/** 175 * Report more information when an apr_dbm function fails. 176 * @param dbm The database 177 * @param errcode A DBM-specific value for the error (for logging). If this 178 * isn't needed, it may be NULL. 179 * @param errbuf Location to store the error text 180 * @param errbufsize The size of the provided buffer 181 * @return The errbuf parameter, for convenience. 182 */ 183APU_DECLARE(char *) apr_dbm_geterror(apr_dbm_t *dbm, int *errcode, 184 char *errbuf, apr_size_t errbufsize); 185/** 186 * If the specified file/path were passed to apr_dbm_open(), return the 187 * actual file/path names which would be (created and) used. At most, two 188 * files may be used; used2 may be NULL if only one file is used. 189 * @param pool The pool for allocating used1 and used2. 190 * @param type The type of DBM you require info on @see apr_dbm_open_ex 191 * @param pathname The path name to generate used-names from. 192 * @param used1 The first pathname used by the apr_dbm implementation. 193 * @param used2 The second pathname used by apr_dbm. If only one file is 194 * used by the specific implementation, this will be set to NULL. 195 * @return An error if the specified type is invalid. 196 * @remark The dbm file(s) don't need to exist. This function only manipulates 197 * the pathnames. 198 */ 199APU_DECLARE(apr_status_t) apr_dbm_get_usednames_ex(apr_pool_t *pool, 200 const char *type, 201 const char *pathname, 202 const char **used1, 203 const char **used2); 204 205/** 206 * If the specified file/path were passed to apr_dbm_open(), return the 207 * actual file/path names which would be (created and) used. At most, two 208 * files may be used; used2 may be NULL if only one file is used. 209 * @param pool The pool for allocating used1 and used2. 210 * @param pathname The path name to generate used-names from. 211 * @param used1 The first pathname used by the apr_dbm implementation. 212 * @param used2 The second pathname used by apr_dbm. If only one file is 213 * used by the specific implementation, this will be set to NULL. 214 * @remark The dbm file(s) don't need to exist. This function only manipulates 215 * the pathnames. 216 */ 217APU_DECLARE(void) apr_dbm_get_usednames(apr_pool_t *pool, 218 const char *pathname, 219 const char **used1, 220 const char **used2); 221 222/** @} */ 223#ifdef __cplusplus 224} 225#endif 226 227#endif /* !APR_DBM_H */ 228