Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | DB_File - Perl5 access to Berkeley DB |
4 | |
5 | =head1 SYNOPSIS |
6 | |
7 | use DB_File ; |
8 | |
9 | [$X =] tie %hash, DB_File, $filename [, $flags, $mode, $DB_HASH] ; |
10 | [$X =] tie %hash, DB_File, $filename, $flags, $mode, $DB_BTREE ; |
11 | [$X =] tie @array, DB_File, $filename, $flags, $mode, $DB_RECNO ; |
12 | |
13 | $status = $X->del($key [, $flags]) ; |
14 | $status = $X->put($key, $value [, $flags]) ; |
15 | $status = $X->get($key, $value [, $flags]) ; |
16 | $status = $X->seq($key, $value [, $flags]) ; |
17 | $status = $X->sync([$flags]) ; |
18 | $status = $X->fd ; |
19 | |
20 | untie %hash ; |
21 | untie @array ; |
22 | |
23 | =head1 DESCRIPTION |
24 | |
25 | B<DB_File> is a module which allows Perl programs to make use of |
26 | the facilities provided by Berkeley DB. If you intend to use this |
27 | module you should really have a copy of the Berkeley DB manual |
28 | page at hand. The interface defined here |
29 | mirrors the Berkeley DB interface closely. |
30 | |
31 | Berkeley DB is a C library which provides a consistent interface to a number of |
32 | database formats. |
33 | B<DB_File> provides an interface to all three of the database types currently |
34 | supported by Berkeley DB. |
35 | |
36 | The file types are: |
37 | |
38 | =over 5 |
39 | |
40 | =item DB_HASH |
41 | |
42 | This database type allows arbitrary key/data pairs to be stored in data files. |
43 | This is equivalent to the functionality provided by |
44 | other hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. |
45 | Remember though, the files created using DB_HASH are |
46 | not compatible with any of the other packages mentioned. |
47 | |
48 | A default hashing algorithm, which will be adequate for most applications, |
49 | is built into Berkeley DB. |
50 | If you do need to use your own hashing algorithm it is possible to write your |
51 | own in Perl and have B<DB_File> use it instead. |
52 | |
53 | =item DB_BTREE |
54 | |
55 | The btree format allows arbitrary key/data pairs to be stored in a sorted, |
56 | balanced binary tree. |
57 | |
58 | As with the DB_HASH format, it is possible to provide a user defined Perl routine |
59 | to perform the comparison of keys. By default, though, the keys are stored |
60 | in lexical order. |
61 | |
62 | =item DB_RECNO |
63 | |
64 | DB_RECNO allows both fixed-length and variable-length flat text files to be |
65 | manipulated using |
66 | the same key/value pair interface as in DB_HASH and DB_BTREE. |
67 | In this case the key will consist of a record (line) number. |
68 | |
69 | =back |
70 | |
71 | =head2 How does DB_File interface to Berkeley DB? |
72 | |
73 | B<DB_File> allows access to Berkeley DB files using the tie() mechanism |
74 | in Perl 5 (for full details, see L<perlfunc/tie()>). |
75 | This facility allows B<DB_File> to access Berkeley DB files using |
76 | either an associative array (for DB_HASH & DB_BTREE file types) or an |
77 | ordinary array (for the DB_RECNO file type). |
78 | |
79 | In addition to the tie() interface, it is also possible to use most of the |
80 | functions provided in the Berkeley DB API. |
81 | |
82 | =head2 Differences with Berkeley DB |
83 | |
84 | Berkeley DB uses the function dbopen() to open or create a |
85 | database. Below is the C prototype for dbopen(). |
86 | |
87 | DB* |
88 | dbopen (const char * file, int flags, int mode, |
89 | DBTYPE type, const void * openinfo) |
90 | |
91 | The parameter C<type> is an enumeration which specifies which of the 3 |
92 | interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used. |
93 | Depending on which of these is actually chosen, the final parameter, |
94 | I<openinfo> points to a data structure which allows tailoring of the |
95 | specific interface method. |
96 | |
97 | This interface is handled |
98 | slightly differently in B<DB_File>. Here is an equivalent call using |
99 | B<DB_File>. |
100 | |
101 | tie %array, DB_File, $filename, $flags, $mode, $DB_HASH ; |
102 | |
103 | The C<filename>, C<flags> and C<mode> parameters are the direct equivalent |
104 | of their dbopen() counterparts. The final parameter $DB_HASH |
105 | performs the function of both the C<type> and C<openinfo> |
106 | parameters in dbopen(). |
107 | |
108 | In the example above $DB_HASH is actually a reference to a hash object. |
109 | B<DB_File> has three of these pre-defined references. |
110 | Apart from $DB_HASH, there is also $DB_BTREE and $DB_RECNO. |
111 | |
112 | The keys allowed in each of these pre-defined references is limited to the names |
113 | used in the equivalent C structure. |
114 | So, for example, the $DB_HASH reference will only allow keys called C<bsize>, |
115 | C<cachesize>, C<ffactor>, C<hash>, C<lorder> and C<nelem>. |
116 | |
117 | To change one of these elements, just assign to it like this |
118 | |
119 | $DB_HASH{cachesize} = 10000 ; |
120 | |
121 | |
122 | =head2 RECNO |
123 | |
124 | |
125 | In order to make RECNO more compatible with Perl the array offset for all |
126 | RECNO arrays begins at 0 rather than 1 as in Berkeley DB. |
127 | |
128 | |
129 | =head2 In Memory Databases |
130 | |
131 | Berkeley DB allows the creation of in-memory databases by using NULL (that is, a |
132 | C<(char *)0 in C) in |
133 | place of the filename. |
134 | B<DB_File> uses C<undef> instead of NULL to provide this functionality. |
135 | |
136 | |
137 | =head2 Using the Berkeley DB Interface Directly |
138 | |
139 | As well as accessing Berkeley DB using a tied hash or array, it is also |
140 | possible to make direct use of most of the functions defined in the Berkeley DB |
141 | documentation. |
142 | |
143 | |
144 | To do this you need to remember the return value from the tie. |
145 | |
146 | $db = tie %hash, DB_File, "filename" |
147 | |
148 | Once you have done that, you can access the Berkeley DB API functions directly. |
149 | |
150 | $db->put($key, $value, R_NOOVERWRITE) ; |
151 | |
152 | All the functions defined in L<dbx(3X)> are available except |
153 | for close() and dbopen() itself. |
154 | The B<DB_File> interface to these functions have been implemented to mirror |
155 | the the way Berkeley DB works. In particular note that all the functions return |
156 | only a status value. Whenever a Berkeley DB function returns data via one of |
157 | its parameters, the B<DB_File> equivalent does exactly the same. |
158 | |
159 | All the constants defined in L<dbopen> are also available. |
160 | |
161 | Below is a list of the functions available. |
162 | |
163 | =over 5 |
164 | |
165 | =item get |
166 | |
167 | Same as in C<recno> except that the flags parameter is optional. |
168 | Remember the value |
169 | associated with the key you request is returned in the $value parameter. |
170 | |
171 | =item put |
172 | |
173 | As usual the flags parameter is optional. |
174 | |
175 | If you use either the R_IAFTER or |
176 | R_IBEFORE flags, the key parameter will have the record number of the inserted |
177 | key/value pair set. |
178 | |
179 | =item del |
180 | |
181 | The flags parameter is optional. |
182 | |
183 | =item fd |
184 | |
185 | As in I<recno>. |
186 | |
187 | =item seq |
188 | |
189 | The flags parameter is optional. |
190 | |
191 | Both the key and value parameters will be set. |
192 | |
193 | =item sync |
194 | |
195 | The flags parameter is optional. |
196 | |
197 | =back |
198 | |
199 | =head1 EXAMPLES |
200 | |
201 | It is always a lot easier to understand something when you see a real example. |
202 | So here are a few. |
203 | |
204 | =head2 Using HASH |
205 | |
206 | use DB_File ; |
207 | use Fcntl ; |
208 | |
209 | tie %h, DB_File, "hashed", O_RDWR|O_CREAT, 0640, $DB_HASH ; |
210 | |
211 | # Add a key/value pair to the file |
212 | $h{"apple"} = "orange" ; |
213 | |
214 | # Check for existence of a key |
215 | print "Exists\n" if $h{"banana"} ; |
216 | |
217 | # Delete |
218 | delete $h{"apple"} ; |
219 | |
220 | untie %h ; |
221 | |
222 | =head2 Using BTREE |
223 | |
224 | Here is sample of code which used BTREE. Just to make life more interesting |
225 | the default comparision function will not be used. Instead a Perl sub, C<Compare()>, |
226 | will be used to do a case insensitive comparison. |
227 | |
228 | use DB_File ; |
229 | use Fcntl ; |
230 | |
231 | sub Compare |
232 | { |
233 | my ($key1, $key2) = @_ ; |
234 | |
235 | "\L$key1" cmp "\L$key2" ; |
236 | } |
237 | |
238 | $DB_BTREE->{compare} = 'Compare' ; |
239 | |
240 | tie %h, DB_File, "tree", O_RDWR|O_CREAT, 0640, $DB_BTREE ; |
241 | |
242 | # Add a key/value pair to the file |
243 | $h{'Wall'} = 'Larry' ; |
244 | $h{'Smith'} = 'John' ; |
245 | $h{'mouse'} = 'mickey' ; |
246 | $h{'duck'} = 'donald' ; |
247 | |
248 | # Delete |
249 | delete $h{"duck"} ; |
250 | |
251 | # Cycle through the keys printing them in order. |
252 | # Note it is not necessary to sort the keys as |
253 | # the btree will have kept them in order automatically. |
254 | foreach (keys %h) |
255 | { print "$_\n" } |
256 | |
257 | untie %h ; |
258 | |
259 | Here is the output from the code above. |
260 | |
261 | mouse |
262 | Smith |
263 | Wall |
264 | |
265 | |
266 | =head2 Using RECNO |
267 | |
268 | use DB_File ; |
269 | use Fcntl ; |
270 | |
271 | $DB_RECNO->{psize} = 3000 ; |
272 | |
273 | tie @h, DB_File, "text", O_RDWR|O_CREAT, 0640, $DB_RECNO ; |
274 | |
275 | # Add a key/value pair to the file |
276 | $h[0] = "orange" ; |
277 | |
278 | # Check for existence of a key |
279 | print "Exists\n" if $h[1] ; |
280 | |
281 | untie @h ; |
282 | |
283 | |
284 | |
285 | =head1 WARNINGS |
286 | |
287 | If you happen find any other functions defined in the source for this module |
288 | that have not been mentioned in this document -- beware. |
289 | I may drop them at a moments notice. |
290 | |
291 | If you cannot find any, then either you didn't look very hard or the moment has |
292 | passed and I have dropped them. |
293 | |
294 | =head1 BUGS |
295 | |
296 | Some older versions of Berkeley DB had problems with fixed length records |
297 | using the RECNO file format. The newest version at the time of writing |
298 | was 1.85 - this seems to have fixed the problems with RECNO. |
299 | |
300 | I am sure there are bugs in the code. If you do find any, or can suggest any |
301 | enhancements, I would welcome your comments. |
302 | |
303 | =head1 AVAILABILITY |
304 | |
305 | Berkeley DB is available via the hold C<ftp.cs.berkeley.edu> in the |
306 | directory C</ucb/4bsd/db.tar.gz>. It is I<not> under the GPL. |
307 | |
308 | =head1 SEE ALSO |
309 | |
310 | L<perl(1)>, L<dbopen(3)>, L<hash(3)>, L<recno(3)>, L<btree(3)> |
311 | |
312 | Berkeley DB is available from F<ftp.cs.berkeley.edu> in the directory F</ucb/4bsd>. |
313 | |
314 | =head1 AUTHOR |
315 | |
316 | The DB_File interface was written by |
317 | Paul Marquess <pmarquess@bfsec.bt.co.uk>. |
318 | Questions about the DB system itself may be addressed to |
319 | Keith Bostic <bostic@cs.berkeley.edu>. |