« back to all changes in this revision
Viewing changes to gdbm.3
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Ronald Blaschke
- Date: 2008-11-09 15:55:44 UTC
- Revision ID: ron@rblasch.org-20081109155544-ig1o30ikmghvvhzs
Initial import of GNU dbm 1.8.0.
- files added:
added
removed
gdbm.3
1
.ds ve 1.8
2
.TH GDBM 3 5/19/99
3
.SH NAME
4
GDBM - The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR
5
compatability. (Version \*(ve.)
6
.SH SYNOPSIS
7
.B #include <gdbm.h>
8
.PP
9
.SM
10
.B extern gdbm_error
11
.br
12
.B gdbm_errno
13
.PP
14
.B extern char
15
.br
16
.B *gdbm_version
17
.PP
18
.B GDBM_FILE
19
.br
20
.B gdbm_open (name, block_size, read_write, mode, fatal_func)
21
.br
22
.B char * name;
23
.br
24
.B int block_size, read_write, mode;
25
.br
26
.B void (*fatal_func) ();
27
.PP
28
.B void
29
.br
30
.B gdbm_close (dbf)
31
.br
32
.B GDBM_FILE dbf;
33
.PP
34
.B int
35
.br
36
.B gdbm_store (dbf, key, content, flag)
37
.br
38
.B GDBM_FILE dbf;
39
.br
40
.B datum key, content;
41
.br
42
.B int flag;
43
.PP
44
.B datum
45
.br
46
.B gdbm_fetch (dbf, key)
47
.br
48
.B GDBM_FILE dbf;
49
.br
50
.B datum key;
51
.PP
52
.B int
53
.br
54
.B gdbm_delete (dbf, key)
55
.br
56
.B GDBM_FILE dbf;
57
.br
58
.B datum key;
59
.PP
60
.B datum
61
.br
62
.B gdbm_firstkey (dbf)
63
.br
64
.B GDBM_FILE dbf;
65
.PP
66
.B datum
67
.br
68
.B gdbm_nextkey (dbf, key)
69
.br
70
.B GDBM_FILE dbf;
71
.br
72
.B datum key;
73
.PP
74
.B int
75
.br
76
.B gdbm_reorganize (dbf)
77
.br
78
.B GDBM_FILE dbf;
79
.PP
80
.B void
81
.br
82
.B gdbm_sync (dbf)
83
.br
84
.B GDBM_FILE dbf;
85
.PP
86
.B int
87
.br
88
.B gdbm_exists (dbf, key)
89
.br
90
.B GDBM_FILE dbf;
91
.br
92
.B datum key;
93
.PP
94
.B char *
95
.br
96
.B gdbm_strerror (errno)
97
.br
98
.B gdbm_error errno;
99
.PP
100
.B int
101
.br
102
.B gdbm_setopt (dbf, option, value, size)
103
.br
104
.B GDBM_FILE dbf;
105
.br
106
.B int option;
107
.br
108
.B int *value;
109
.br
110
.B int size;
111
.PP
112
.B int
113
.br
114
.B gdbm_fdesc (dbf)
115
.br
116
.B GDBM_FILE dbf;
117
.PP
118
.PP
119
.B DBM Compatability routines:
120
.PP
121
.B #include <dbm.h>
122
.PP
123
.SM
124
.B int
125
.br
126
.B dbminit (name)
127
.br
128
.B char *name;
129
.PP
130
.B int
131
.br
132
.B store (key, content)
133
.br
134
.B datum key, content;
135
.PP
136
.B datum
137
.br
138
.B fetch (key)
139
.br
140
.B datum key;
141
.PP
142
.B int
143
.br
144
.B delete (key)
145
.br
146
.B datum key;
147
.PP
148
.B datum
149
.br
150
.B firstkey ()
151
.PP
152
.B datum
153
.br
154
.B nextkey (key)
155
.br
156
.B datum key;
157
.PP
158
.B int
159
.br
160
.B dbmclose ()
161
.PP
162
.PP
163
.B NDBM Compatability routines:
164
.PP
165
.B #include <ndbm.h>
166
.PP
167
.SM
168
.B DBM
169
.br
170
.B *dbm_open (name, flags, mode)
171
.br
172
.B char *name;
173
.br
174
.B int flags, mode;
175
.PP
176
.B void
177
.br
178
.B dbm_close (file)
179
.br
180
.B DBM *file;
181
.PP
182
.B datum
183
.br
184
.B dbm_fetch (file, key)
185
.br
186
.B DBM *file;
187
.br
188
.B datum key;
189
.PP
190
.B int
191
.br
192
.B dbm_store (file, key, content, flags)
193
.br
194
.B DBM *file;
195
.br
196
.B datum key, content;
197
.br
198
.B int flags;
199
.PP
200
.B int
201
.br
202
.B dbm_delete (file, key)
203
.br
204
.B DBM *file;
205
.br
206
.B datum key;
207
.PP
208
.B datum
209
.br
210
.B dbm_firstkey (file)
211
.br
212
.B DBM *file;
213
.PP
214
.B datum
215
.br
216
.B dbm_nextkey (file)
217
.br
218
.B DBM *file;
219
.PP
220
.B int
221
.br
222
.B dbm_error (file)
223
.br
224
.B DBM *file;
225
.PP
226
.B int
227
.br
228
.B dbm_clearerr (file)
229
.br
230
.B DBM *file;
231
.PP
232
.B int
233
.br
234
.B dbm_pagfno (file)
235
.br
236
.B DBM *file;
237
.PP
238
.B int
239
.br
240
.B dbm_dirfno (file)
241
.br
242
.B DBM *file;
243
.PP
244
.B int
245
.br
246
.B dbm_rdonly (file)
247
.br
248
.B DBM *file;
249
250
251
.SH DESCRIPTION
252
GNU dbm is a library of routines that manages data files that contain
253
key/data pairs. The access provided is that of storing,
254
retrieval, and deletion by key and a non-sorted traversal of all
255
keys. A process is allowed to use multiple data files at the
256
same time.
257
258
A process that opens a gdbm file is designated as a "reader" or a
259
"writer". Only one writer may open a gdbm file and many readers may
260
open the file. Readers and writers can not open the gdbm file at the
261
same time. The procedure for opening a gdbm file is:
262
263
GDBM_FILE dbf;
264
265
dbf = gdbm_open ( name, block_size, read_write, mode, fatal_func )
266
267
\fIName\fR is the name of the file (the complete name,
268
gdbm does not append any characters to this name). \fIBlock_size\fR is
269
the size of a single transfer from disk to memory. This parameter is
270
ignored unless the file is a new file. The minimum size is 512. If
271
it is less than 512, dbm will use the stat block size for the file system.
272
\fIRead_write\fR can have one of the following values:
273
.br
274
.B GDBM_READER
275
reader
276
.br
277
.B GDBM_WRITER
278
writer
279
.br
280
.B GDBM_WRCREAT
281
writer - if database does not exist create new one
282
.br
283
.B GDBM_NEWDB
284
writer - create new database regardless if one exists
285
.br
286
For the last three (writers of the database) the following may be added
287
added to \fIread_write\fR by bitwise or:
288
.B GDBM_SYNC,
289
which causes all database operations to be synchronized to the disk, and
290
.B GDBM_NOLOCK,
291
which prevents the library from performing any locking on the database file.
292
The option
293
.B GDBM_FAST
294
is now obsolete, since gdbm defaults to no-sync mode.
295
.br
296
\fIMode\fR is the file mode (see \fBchmod(2)\fR and \fBopen(2)\fR) if the
297
file is created. \fI(*Fatal_func) ()\fR is a function for dbm to call
298
if it detects a fatal error. The only parameter of this function is a string.
299
If the value of 0 is provided, gdbm will use a default function.
300
301
The return value \fIdbf\fR is the pointer needed by all other routines to
302
access that gdbm file. If the return is the NULL pointer, \fBgdbm_open\fR
303
was not successful. The errors can be found in \fIgdbm_errno\fR for gdbm
304
errors and in \fIerrno\fR for system errors. (For error codes, see
305
gdbmerrno.h.)
306
307
In all of the following calls, the parameter \fIdbf\fR refers to the pointer
308
returned from \fBgdbm_open\fR.
309
310
It is important that every file opened is also closed. This is needed to
311
update the reader/writer count on the file. This is done by:
312
313
gdbm_close (dbf);
314
315
316
The database is used by 3 primary routines. The first stores data in the
317
database.
318
319
ret = gdbm_store ( dbf, key, content, flag )
320
321
\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the
322
key data. \fIContent\fR is the data to be associated with the \fIkey\fR.
323
\fIFlag\fR can have one of the following values:
324
.br
325
.B GDBM_INSERT
326
insert only, generate an error if key exists
327
.br
328
.B GDBM_REPLACE
329
replace contents if key exists.
330
331
If a reader calls \fBgdbm_store\fR, the return value will be -1.
332
If called with GDBM_INSERT and \fIkey\fR is in the database, the return
333
value will be 1. Otherwise, the return value is 0.
334
335
\fINOTICE: If you store data for a key that is already in the data base,
336
gdbm replaces the old data with the new data if called with GDBM_REPLACE.
337
You do not get two data items for the same key and you do not get an
338
error from gdbm_store.
339
340
NOTICE: The size in gdbm is not restricted like dbm or ndbm. Your data
341
can be as large as you want.\fR
342
343
344
To search for some data:
345
346
content = gdbm_fetch ( dbf, key )
347
348
\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is
349
the key data.
350
351
352
If the \fIdptr\fR element of the return value is NULL, no data was
353
found. Otherwise the return value is a pointer to the found data.
354
The storage space for the \fIdptr\fR element is allocated using
355
\fBmalloc(3C)\fR. \fBGdbm\fI does not automatically free this data.
356
It is the programmer's responsibility to free this storage when it is
357
no longer needed.\fR
358
359
360
To search for some data, without retrieving it:
361
362
ret = gdbm_exists ( dbf, key )
363
364
\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is
365
the key data to search for.
366
367
If the \fIkey\fR is found within the database, the return value \fIret\fR
368
will be true. If nothing appropiate is found, \fIret\fR will be false.
369
This routine is useful for checking for the existance of a record,
370
without performing the memory allocation done by \fBgdbm_fetch\fR.
371
372
373
To remove some data from the database:
374
375
ret = gdbm_delete ( dbf, key )
376
377
\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the
378
key data.
379
380
The return value is -1 if the item is not present or the requester is a reader.
381
The return value is 0 if there was a successful delete.
382
383
384
The next two routines allow for accessing all items in the database. This
385
access is not key sequential, but it is guaranteed to visit every key in
386
the database once. (The order has to do with the hash values.)
387
388
key = gdbm_firstkey ( dbf )
389
390
nextkey = gdbm_nextkey ( dbf, key )
391
392
\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the
393
key data.
394
395
The return values are both of type \fBdatum\fR. If the \fIdptr\fR
396
element of the return value is NULL, there is no first key or next key.
397
Again notice that \fIdptr\fR points to data allocated by \fBmalloc(3C)\fR
398
and \fBgdbm\fR will not free it for you.
399
400
These functions were intended to visit the database in read-only algorithms,
401
for instance, to validate the database or similar operations.
402
403
File `visiting' is based on a `hash table'. \fIgdbm_delete\fR re-arranges the
404
hash table to make sure that any collisions in the table do not leave some item
405
`un-findable'. The original key order is NOT guaranteed to remain unchanged in
406
ALL instances. It is possible that some key will not be visited if a loop like
407
the following is executed:
408
409
key = gdbm_firstkey ( dbf );
410
while ( key.dptr ) {
411
nextkey = gdbm_nextkey ( dbf, key );
412
if ( some condition ) {
413
gdbm_delete ( dbf, key );
414
free ( key.dptr );
415
}
416
key = nextkey;
417
}
418
419
420
The following routine should be used very infrequently.
421
422
ret = gdbm_reorganize ( dbf )
423
424
If you have had a lot of deletions and would like to shrink the space
425
used by the \fBgdbm\fR file, this routine will reorganize the database.
426
\fBGdbm\fR will not shorten the length of a \fBgdbm\fR file except by
427
using this reorganization. (Deleted file space will be reused.)
428
429
430
Unless your database was opened with the GDBM_SYNC flag, gdbm does not
431
wait for writes to be flushed to the disk before continuing.
432
The following routine can be used to guarantee that the database is
433
physically written to the disk file.
434
435
gdbm_sync ( dbf )
436
437
It will not return until the disk file state is syncronized with the
438
in-memory state of the database.
439
440
441
To convert a \fBgdbm\fR error code into English text, use this routine:
442
443
ret = gdbm_strerror ( errno )
444
445
Where \fIerrno\fR is of type \fIgdbm_error\fR, usually the global
446
variable \fIgdbm_errno\fR. The appropiate phrase is returned.
447
448
449
\fBGdbm\fR now supports the ability to set certain options on an
450
already open database.
451
452
ret = gdbm_setopt ( dbf, option, value, size )
453
454
Where \fIdbf\fR is the return value from a previous call to \fBgdbm_open\fR,
455
and \fIoption\fR specifies which option to set. The valid options are
456
currently:
457
458
\fBGDBM_CACHESIZE\fR - Set the size of the internal bucket
459
cache. This option may only be set once on each \fIGDBM_FILE\fR
460
descriptor, and is set automatically to 100 upon the first
461
access to the database.
462
463
\fBGDBM_FASTMODE\fR - Set \fBfast mode\fR to either on or off. This
464
allows \fBfast mode\fR to be toggled on an already open and
465
active database. \fIvalue\fR (see below) should be set to either
466
TRUE or FALSE. \fIThis option is now obsolete.\fR
467
468
\fBGDBM_SYNCMODE\fR - Turn on or off file system synchronization operations.
469
This setting defaults to off; \fIvalue\fR (see below) should be set to either
470
TRUE or FALSE.
471
472
\fBGDBM_CENTFREE\fR - Set \fBcentral free block pool\fR to either on or off.
473
The default is off, which is how previous versions of \fBGdbm\fR
474
handled free blocks. If set, this option causes all subsequent free
475
blocks to be placed in the \fBglobal\fR pool, allowing (in thoery)
476
more file space to be reused more quickly. \fIvalue\fR (see below) should
477
be set to either TRUE or FALSE.
478
\fINOTICE: This feature is still under study.\fR
479
480
\fBGDBM_COALESCEBLKS\fR - Set \fBfree block merging\fR to either on or off.
481
The default is off, which is how previous versions of \fBGdbm\fR
482
handled free blocks. If set, this option causes adjacent free blocks
483
to be merged. This can become a CPU expensive process with time, though,
484
especially if used in conjunction with \fBGDBM_CENTFREE\fR. \fIvalue\fR
485
(see below) should be set to either TRUE or FALSE.
486
\fINOTICE: This feature is still under study.\fR
487
488
\fIvalue\fR is the value to set \fIoption\fR to, specified as an integer
489
pointer. \fIsize\fR is the size of the data pointed to by \fIvalue\fR.
490
The return value will be -1 upon failure, or 0 upon success. The global
491
variable \fIgdbm_errno\fR will be set upon failure.
492
493
For instance, to set a database to use a cache of 10, after opening it
494
with \fBgdbm_open\fR, but prior to accessing it in any way, the following
495
code could be used:
496
497
int value = 10;
498
499
ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));
500
501
502
If the database was opened with the \fBGDBM_NOLOCK\fR flag, the user may
503
wish to perform their own file locking on the database file in order to
504
prevent multiple writers operating on the same file simultaneously.
505
506
In order to support this, the \fIgdbm_fdesc\fR routine is provided.
507
508
ret = gdbm_fdesc ( dbf )
509
510
Where \fIdbf\fR is the return value from a previous call to \fBgdbm_open\fR.
511
The return value will be the file descriptor of the database.
512
513
The following two external variables may be useful:
514
515
\fIgdbm_errno\fR is the variable that contains more information about
516
gdbm errors. (gdbm.h has the definitions of the error values and
517
defines gdbm_errno as an external variable.)
518
.br
519
\fIgdbm_version\fR is the string containing the version information.
520
521
522
There are a few more things of interest. First, \fBgdbm\fR files are
523
not "sparse". You can copy them with the UNIX \fBcp(1)\fR command and
524
they will not expand in the copying process. Also, there is a
525
compatibility mode for use with programs that already use UNIX
526
\fBdbm\fR. In this compatibility mode, no \fRgdbm\fR file pointer is
527
required by the programmer, and only one file may be opened at a time.
528
All users in compatibility mode are assumed to be writers. If the
529
\fBgdbm\fR file is a read only, it will fail as a writer, but will
530
also try to open it as a reader. All returned pointers in datum
531
structures point to data that \fBgdbm\fR WILL free. They should be
532
treated as static pointers (as standard UNIX \fBdbm\fR does).
533
534
535
.SH LINKING
536
This library is accessed by specifying \fI-lgdbm\fR as the last
537
parameter to the compile line, e.g.:
538
.sp
539
gcc -o prog prog.c -lgdbm
540
541
542
.SH BUGS
543
544
.SH "SEE ALSO"
545
dbm, ndbm
546
547
.SH AUTHOR
548
by Philip A. Nelson and Jason Downs.
549
Copyright (C) 1990 - 1999 Free Software Foundation, Inc.
550
551
GDBM is free software; you can redistribute it and/or modify
552
it under the terms of the GNU General Public License as published by
553
the Free Software Foundation; either version 1, or (at your option)
554
any later version.
555
556
GDBM is distributed in the hope that it will be useful,
557
but WITHOUT ANY WARRANTY; without even the implied warranty of
558
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
559
GNU General Public License for more details.
560
561
You should have received a copy of the GNU General Public License
562
along with GDBM; see the file COPYING. If not, write to
563
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
564
565
You may contact the original author by:
566
.br
567
e-mail: phil@cs.wwu.edu
568
.br
569
us-mail: Philip A. Nelson
570
.br
571
Computer Science Department
572
.br
573
Western Washington University
574
.br
575
Bellingham, WA 98226
576
577
You may contact the current maintainer by:
578
.br
579
e-mail: downsj@downsj.com
580
Loggerhead is a web-based interface for Breezy
Version: 2.0.1