1 /* Copyright (c) 2011 The LevelDB Authors. All rights reserved.
2 Use of this source code is governed by a BSD-style license that can be
3 found in the LICENSE file. See the AUTHORS file for names of contributors.
5 C bindings for leveldb. May be useful as a stable ABI that can be
6 used by programs that keep leveldb in a shared library, or for
10 . getters for the option types
11 . custom comparators that implement key shortening
12 . capturing post-write-snapshot
13 . custom iter, db, env, cache implementations using just the C bindings
17 (1) We expose just opaque struct pointers and functions to clients.
18 This allows us to change internal representations without having to
21 (2) For simplicity, there is no equivalent to the Slice type. Instead,
22 the caller has to pass the pointer and length as separate
25 (3) Errors are represented by a null-terminated c string. NULL
26 means no error. All operations that can raise an error are passed
27 a "char** errptr" as the last argument. One of the following must
30 *errptr points to a malloc()ed null-terminated error message
31 (On Windows, *errptr must have been malloc()-ed by this library.)
32 On success, a leveldb routine leaves *errptr unchanged.
33 On failure, leveldb frees the old value of *errptr and
34 set *errptr to a malloc()ed error message.
36 (4) Bools have the type unsigned char (0 == false; rest == true)
38 (5) All of the pointer arguments must be non-NULL.
41 #ifndef STORAGE_LEVELDB_INCLUDE_C_H_
42 #define STORAGE_LEVELDB_INCLUDE_C_H_
54 typedef struct leveldb_t leveldb_t;
55 typedef struct leveldb_cache_t leveldb_cache_t;
56 typedef struct leveldb_comparator_t leveldb_comparator_t;
57 typedef struct leveldb_env_t leveldb_env_t;
58 typedef struct leveldb_filelock_t leveldb_filelock_t;
59 typedef struct leveldb_filterpolicy_t leveldb_filterpolicy_t;
60 typedef struct leveldb_iterator_t leveldb_iterator_t;
61 typedef struct leveldb_logger_t leveldb_logger_t;
62 typedef struct leveldb_options_t leveldb_options_t;
63 typedef struct leveldb_randomfile_t leveldb_randomfile_t;
64 typedef struct leveldb_readoptions_t leveldb_readoptions_t;
65 typedef struct leveldb_seqfile_t leveldb_seqfile_t;
66 typedef struct leveldb_snapshot_t leveldb_snapshot_t;
67 typedef struct leveldb_writablefile_t leveldb_writablefile_t;
68 typedef struct leveldb_writebatch_t leveldb_writebatch_t;
69 typedef struct leveldb_writeoptions_t leveldb_writeoptions_t;
73 extern leveldb_t* leveldb_open(
74 const leveldb_options_t* options,
78 extern void leveldb_close(leveldb_t* db);
80 extern void leveldb_put(
82 const leveldb_writeoptions_t* options,
83 const char* key, size_t keylen,
84 const char* val, size_t vallen,
87 extern void leveldb_delete(
89 const leveldb_writeoptions_t* options,
90 const char* key, size_t keylen,
93 extern void leveldb_write(
95 const leveldb_writeoptions_t* options,
96 leveldb_writebatch_t* batch,
99 /* Returns NULL if not found. A malloc()ed array otherwise.
100 Stores the length of the array in *vallen. */
101 extern char* leveldb_get(
103 const leveldb_readoptions_t* options,
104 const char* key, size_t keylen,
108 extern leveldb_iterator_t* leveldb_create_iterator(
110 const leveldb_readoptions_t* options);
112 extern const leveldb_snapshot_t* leveldb_create_snapshot(
115 extern void leveldb_release_snapshot(
117 const leveldb_snapshot_t* snapshot);
119 /* Returns NULL if property name is unknown.
120 Else returns a pointer to a malloc()-ed null-terminated value. */
121 extern char* leveldb_property_value(
123 const char* propname);
125 extern void leveldb_approximate_sizes(
128 const char* const* range_start_key, const size_t* range_start_key_len,
129 const char* const* range_limit_key, const size_t* range_limit_key_len,
132 extern void leveldb_compact_range(
134 const char* start_key, size_t start_key_len,
135 const char* limit_key, size_t limit_key_len);
137 /* Management operations */
139 extern void leveldb_destroy_db(
140 const leveldb_options_t* options,
144 extern void leveldb_repair_db(
145 const leveldb_options_t* options,
151 extern void leveldb_iter_destroy(leveldb_iterator_t*);
152 extern unsigned char leveldb_iter_valid(const leveldb_iterator_t*);
153 extern void leveldb_iter_seek_to_first(leveldb_iterator_t*);
154 extern void leveldb_iter_seek_to_last(leveldb_iterator_t*);
155 extern void leveldb_iter_seek(leveldb_iterator_t*, const char* k, size_t klen);
156 extern void leveldb_iter_next(leveldb_iterator_t*);
157 extern void leveldb_iter_prev(leveldb_iterator_t*);
158 extern const char* leveldb_iter_key(const leveldb_iterator_t*, size_t* klen);
159 extern const char* leveldb_iter_value(const leveldb_iterator_t*, size_t* vlen);
160 extern void leveldb_iter_get_error(const leveldb_iterator_t*, char** errptr);
164 extern leveldb_writebatch_t* leveldb_writebatch_create();
165 extern void leveldb_writebatch_destroy(leveldb_writebatch_t*);
166 extern void leveldb_writebatch_clear(leveldb_writebatch_t*);
167 extern void leveldb_writebatch_put(
168 leveldb_writebatch_t*,
169 const char* key, size_t klen,
170 const char* val, size_t vlen);
171 extern void leveldb_writebatch_delete(
172 leveldb_writebatch_t*,
173 const char* key, size_t klen);
174 extern void leveldb_writebatch_iterate(
175 leveldb_writebatch_t*,
177 void (*put)(void*, const char* k, size_t klen, const char* v, size_t vlen),
178 void (*deleted)(void*, const char* k, size_t klen));
182 extern leveldb_options_t* leveldb_options_create();
183 extern void leveldb_options_destroy(leveldb_options_t*);
184 extern void leveldb_options_set_comparator(
186 leveldb_comparator_t*);
187 extern void leveldb_options_set_filter_policy(
189 leveldb_filterpolicy_t*);
190 extern void leveldb_options_set_create_if_missing(
191 leveldb_options_t*, unsigned char);
192 extern void leveldb_options_set_error_if_exists(
193 leveldb_options_t*, unsigned char);
194 extern void leveldb_options_set_paranoid_checks(
195 leveldb_options_t*, unsigned char);
196 extern void leveldb_options_set_env(leveldb_options_t*, leveldb_env_t*);
197 extern void leveldb_options_set_info_log(leveldb_options_t*, leveldb_logger_t*);
198 extern void leveldb_options_set_write_buffer_size(leveldb_options_t*, size_t);
199 extern void leveldb_options_set_max_open_files(leveldb_options_t*, int);
200 extern void leveldb_options_set_cache(leveldb_options_t*, leveldb_cache_t*);
201 extern void leveldb_options_set_block_size(leveldb_options_t*, size_t);
202 extern void leveldb_options_set_block_restart_interval(leveldb_options_t*, int);
205 leveldb_no_compression = 0,
206 leveldb_snappy_compression = 1
208 extern void leveldb_options_set_compression(leveldb_options_t*, int);
212 extern leveldb_comparator_t* leveldb_comparator_create(
214 void (*destructor)(void*),
217 const char* a, size_t alen,
218 const char* b, size_t blen),
219 const char* (*name)(void*));
220 extern void leveldb_comparator_destroy(leveldb_comparator_t*);
224 extern leveldb_filterpolicy_t* leveldb_filterpolicy_create(
226 void (*destructor)(void*),
227 char* (*create_filter)(
229 const char* const* key_array, const size_t* key_length_array,
231 size_t* filter_length),
232 unsigned char (*key_may_match)(
234 const char* key, size_t length,
235 const char* filter, size_t filter_length),
236 const char* (*name)(void*));
237 extern void leveldb_filterpolicy_destroy(leveldb_filterpolicy_t*);
239 extern leveldb_filterpolicy_t* leveldb_filterpolicy_create_bloom(
244 extern leveldb_readoptions_t* leveldb_readoptions_create();
245 extern void leveldb_readoptions_destroy(leveldb_readoptions_t*);
246 extern void leveldb_readoptions_set_verify_checksums(
247 leveldb_readoptions_t*,
249 extern void leveldb_readoptions_set_fill_cache(
250 leveldb_readoptions_t*, unsigned char);
251 extern void leveldb_readoptions_set_snapshot(
252 leveldb_readoptions_t*,
253 const leveldb_snapshot_t*);
257 extern leveldb_writeoptions_t* leveldb_writeoptions_create();
258 extern void leveldb_writeoptions_destroy(leveldb_writeoptions_t*);
259 extern void leveldb_writeoptions_set_sync(
260 leveldb_writeoptions_t*, unsigned char);
264 extern leveldb_cache_t* leveldb_cache_create_lru(size_t capacity);
265 extern void leveldb_cache_destroy(leveldb_cache_t* cache);
269 extern leveldb_env_t* leveldb_create_default_env();
270 extern void leveldb_env_destroy(leveldb_env_t*);
275 REQUIRES: ptr was malloc()-ed and returned by one of the routines
276 in this file. Note that in certain cases (typically on Windows), you
277 may need to call this routine instead of free(ptr) to dispose of
278 malloc()-ed memory returned by this library. */
279 extern void leveldb_free(void* ptr);
281 /* Return the major version number for this release. */
282 extern int leveldb_major_version();
284 /* Return the minor version number for this release. */
285 extern int leveldb_minor_version();
288 } /* end extern "C" */
291 #endif /* STORAGE_LEVELDB_INCLUDE_C_H_ */