contrib/apr-util/include/apr_dbm.h

   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
  27 extern "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  */
  42 typedef struct apr_dbm_t apr_dbm_t;
  43
  44 /**
  45  * Structure for referencing the datum record within a dbm
  46  */
  47 typedef 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
  89 APU_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  */
 111 APU_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  */
 119 APU_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  */
 127 APU_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  */
 135 APU_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  */
 144 APU_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  */
 151 APU_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  */
 158 APU_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  */
 165 APU_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  */
 172 APU_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  */
 183 APU_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  */
 199 APU_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  */
 217 APU_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 */