Apache Portable Runtime
Main Page
Related Pages
Modules
Namespaces
Data Structures
Files
File List
Globals
All
Data Structures
Namespaces
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
usr
include
apr-1
apr_dbm.h
Go to the documentation of this file.
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 */
Generated by
1.8.3.1