gdbm-version
gdbm_cachesize
gdbm_fast
- ;;gdbm_fastmode obsolete
gdbm_insert
gdbm_newdb
gdbm_reader
(bytevector-length bytes)
(string-length bytes)))
-;; Parameters to gdbm_open for readers, writers, and writers who can
-;; create the database.
-(define gdbm_reader (C-enum "GDBM_READER")) ;A reader.
-(define gdbm_writer (C-enum "GDBM_WRITER")) ;A writer.
-(define gdbm_wrcreat (C-enum "GDBM_WRCREAT")) ;A writer. Create the db if needed.
-(define gdbm_newdb (C-enum "GDBM_NEWDB")) ;A writer. Always create a new db.
-(define gdbm_fast (C-enum "GDBM_FAST")) ;Write fast! => No fsyncs.
+(define gdbm_reader (C-enum "GDBM_READER"))
+(define gdbm_writer (C-enum "GDBM_WRITER"))
+(define gdbm_wrcreat (C-enum "GDBM_WRCREAT"))
+(define gdbm_newdb (C-enum "GDBM_NEWDB"))
+(define gdbm_fast (C-enum "GDBM_FAST"))
+(define gdbm_sync (C-enum "GDBM_SYNC"))
+(define gdbm_nolock (C-enum "GDBM_NOLOCK"))
(define (gdbm-open filename block-size flags mode)
(guarantee integer? block-size 'gdbm-open)
((wrcreat) (C-enum "GDBM_WRCREAT"))
((newdb) (C-enum "GDBM_NEWDB"))
((fast) (C-enum "GDBM_FAST"))
+ ((sync) (C-enum "GDBM_SYNC"))
+ ((nolock) (C-enum "GDBM_NOLOCK"))
(else (error:wrong-type-argument flags "gdbm-open flags" 'gdbm-open))))
(cond ((integer? flags) flags)
((symbol? flags) (flag->number flags))
(remove-open-gdbf-cleanup gdbf))))
unspecific)))
-;; Parameters to gdbm_store for simple insertion or replacement in the
-;; case that the key is already in the database.
-(define gdbm_insert (C-enum "GDBM_INSERT")) ;Never replace old data.
-(define gdbm_replace (C-enum "GDBM_REPLACE")) ;Always replace old data.
+(define gdbm_insert (C-enum "GDBM_INSERT"))
+(define gdbm_replace (C-enum "GDBM_REPLACE"))
(define (gdbm-store gdbf key content flag)
(guarantee-gdbf gdbf 'gdbm-store)
(gdbf-args-get-key args))))
(define (gdbm-nextkey gdbf key)
- ;; Returns #f if key is not (or no longer) in the database. Use
- ;; gdbm-keys to read a complete list despite deletes. Gdbm-keys
- ;; also avoids copying the keys back for gdbm_nextkey.
(guarantee-gdbf gdbf 'gdbm-nextkey)
(guarantee-nonnull-string key 'gdbm-nextkey)
(with-gdbf-locked-open
(guarantee fixnum? errno 'strerror)
(c-peek-cstring (C-call "strerror" (make-alien '(* char)) errno)))
-;; Parameters to gdbm_setopt, specifing the type of operation to perform.
-(define gdbm_cachesize (C-enum "GDBM_CACHESIZE")) ;Set the cache size.
-(define gdbm_syncmode (C-enum "GDBM_SYNCMODE")) ;Toggle fast mode.
+(define gdbm_cachesize (C-enum "GDBM_CACHESIZE"))
+(define gdbm_syncmode (C-enum "GDBM_SYNCMODE"))
(define (gdbm-setopt gdbf opt val)
(guarantee-gdbf gdbf 'gdbm-setopt)
;; helper struct assumes there are no callbacks possible during gdbm
;; operations (via which this procedure could be called multiple
;; times [requiring a malloc per operation]). The per-gdbf lock is
- ;; probably already be poised to deadlock any thread trying it.
+ ;; probably already poised to deadlock any thread trying it.
(args #f read-only #t)
(mutex #f read-only #t)
(filename #f read-only #t))
Functions:
-* List:: The exported bindings.
* Open:: Opening the database.
* Close:: Closing the database.
* Store:: Inserting and replacing records in the database.
operation is in progress. No file locks are used by gdbm or the
Scheme wrapper to ensure exclusive access by a Scheme writer.
-@node List
-@chapter The exported bindings.
-
-The following is a quick list of the procedures provided by the plugin.
+The plugin creates its bindings in the @code{(gdbm)} package. These
+can be imported into @code{(your package)} by adding a
+@code{global-definitions} declaration to your @file{.pkg} file, as
+shown below.
@example
- gdbm-open
- gdbm-close
- gdbm-store
- gdbm-fetch
- gdbm-delete
- gdbm-firstkey
- gdbm-nextkey
- gdbm-reorganize
- gdbm-sync
- gdbm-exists?
- gdbm-setopt
-@end example
+ (global-definitions gdbm/)
-Neither @code{gdbm_errno} nor @code{gdbm_strerror} are exposed because
-the plugin automatically tests and calls them to detect errors and
-convert codes into strings. @code{gdbm_fdesc} is also not exposed,
-treated as an implementation detail the plugin should probably hide,
-used by tricky code that cooperates with multiple file locking
-libraries.
+ (define-package (your package)
+ (parent (your package parent))
+ (import (gdbm)
+ gdbm-open
+ ...))
+@end example
-There is one global variable, @code{gdbm-version}, which is
-initialized from the library's @code{gdbm_version} string.
+For interactive use, enter:
-And several constants:
@example
- gdbm_cachesize
- gdbm_fast
- gdbm_insert
- gdbm_newdb
- gdbm_reader
- gdbm_replace
- gdbm_wrcreat
- gdbm_writer
-@end example
-
-You can load these bindings into your global environment with the
-following expression.
-@smallexample
(load-option 'gdbm)
-@end smallexample
+ (import-gdbm)
+@end example
-And you can include these bindings in your package description
-(@file{.pkg}) file with the following expression.
-@smallexample
- (global-definitions gdbm/)
-@end smallexample
+@deffn Procedure import-gdbm
+Define the ``exported'' names in the current REPL environment for
+interactive use. (The plugin's bindings are not linked to the
+deprecated bindings in the global environment.)
+@end deffn
+The plugin implements the same API as that exported from the
+@code{(runtime gdbm)} package, and is in fact the same code in a new
+wrapper. The plugin is automatically loaded when the deprecated
+@code{gdbm-available?} procedure is called. Until then the other
+deprecated bindings in @code{(runtime gdbm)} (and @code{()}) are
+unassigned. After the plugin is loaded, the bindings can be used as
+before.
+
+The GDBM library's @code{gdbm_errno} and @code{gdbm_strerror}
+variables are not exposed in the API. The plugin automatically tests
+and calls them to detect errors and convert codes into strings. The
+@code{gdbm_fdesc} function is also not exposed, but treated as an
+implementation detail the plugin should probably hide, perhaps only
+used by tricky code cooperating with multiple file locking libraries.
+
+There is one global variable, @code{gdbm-version}.
+
+@deffn Variable gdbm-version
+The value of this variable is initialized from the library's
+@code{gdbm_version} string.
+@end deffn
@node Open
@chapter Opening the database.
If the value is less than 512, the file system blocksize is used, otherwise the
value of @var{block-size} is used.
@item flags
-If @var{flags} is @code{gdbm_reader}, the user wants to just read the
-database and any call to @code{gdbm-store} or @code{gdbm-delete} will fail.
-Many readers can access the database at the same time. If @var{flags} is
-@code{gdbm_writer}, the user wants both read and write access to the database
-and requires exclusive access. If @var{flags} is @code{gdbm_wrcreat}, the
-user wants both read and write access to the database and if the database does
-not exist, create a new one. If @var{flags} is @code{gdbm_newdb}, the
-user want a new database created, regardless of whether one existed, and wants
-read and write access to the new database. The following may also be logically
-or'd into the database flags: @code{gdbm_sync}, which causes all database operations
-to be synchronized to the disk, and @code{gdbm_nolock}, which prevents the library
-from performing any locking on the database file. @code{gdbm_fast} is
-now obsolete, since gdbm defaults to no-sync mode.
+If @var{flags} is @code{gdbm_reader} or the symbol @code{reader}, the
+user wants to just read the database and any call to @code{gdbm-store}
+or @code{gdbm-delete} will fail. Many readers can access the database
+at the same time. If @var{flags} is @code{gdbm_writer} or the symbol
+@code{writer}, the user wants both read and write access to the
+database and requires exclusive access. If @var{flags} is
+@code{gdbm_wrcreat} or the symbol @code{wrcreat}, the user wants both
+read and write access to the database and if the database does not
+exist, create a new one. If @var{flags} is @code{gdbm_newdb} or the
+symbol @code{newdb}, the user want a new database created, regardless
+of whether one existed, and wants read and write access to the new
+database. The following may also be logically or'd into the database
+flags: @code{gdbm_fast}, which is the default and included just for
+backward compatibility, @code{gdbm_sync}, which causes all database
+operations to be synchronized to the disk, and @code{gdbm_nolock},
+which prevents the library from performing any locking on the database
+file. The flags can also be a list of symbols containing one of
+@code{reader}, @code{writer}, @code{wrcreat} or @code{newdb} and zero
+or more of @code{fast}, @code{sync} or @code{nolock}. Again
+@code{fast} is accepted but ignored.
@item mode
File mode (see chmod(2) and open(2) if the file is created).
@end table
access that gdbm file.
@end deffn
+@deffn Variable gdbm_reader
+@deffnx Variable gdbm_writer
+@deffnx Variable gdbm_wrcreat
+@deffnx Variable gdbm_newdb
+@deffnx Variable gdbm_fast
+@deffnx Variable gdbm_sync
+@deffnx Variable gdbm_nolock
+The values of these variables are meaningful as the @var{flags}
+argument to the @code{gdbm-open} procedure above.
+@end deffn
@node Close
@chapter Closing the database.
Another non-empty string, the content to be stored in the database file, also
converted to utf-8.
@item flag
-The action to take when @var{key} is already in the database. The value
-of @code{gdbm_replace} indicates that the old content should be replaced
-by @var{content}. The value of @code{gdbm_insert} indicates that
+The action to take when @var{key} is already in the database. The
+value of @code{gdbm_replace}, or the symbol @code{replace}, indicates
+that the old content should be replaced by @var{content}. The value of
+@code{gdbm_insert}, or the symbol @code{insert}, indicates that
@code{#f} should be returned and no action taken if @var{key} already
exists.
@end table
content can be as large as you want.
@end deffn
+@deffn Variable gdbm_replace
+@deffnx Variable gdbm_insert
+The value of these variables are meaningful as the @var{flag} argument
+to the @code{gdbm-store} procedure above.
+@end deffn
@node Fetch
@chapter Searching for records in the database.
@deffn Procedure gdbm-nextkey dbf key
Returns the key to visit after @var{key}, converting its utf-8 bytes
-to a string.
-If there are no more keys, returns @code{#f}.
+to a string. If there are no more keys, returns @code{#f}.
+
+This may not be the best way to iterate over all keys in a database.
+The @code{gdbm-keys} procedure returns a complete list, which is
+unaffected by database deletions made while iterating over it. The
+@code{gdbm-keys} procedure also avoids making a copy of each key to
+pass back to @code{gdbm_nextkey}.
@end deffn
These functions were intended to visit the database in read-only algorithms,
The pointer returned by @code{gdbm-open}.
@item option
The option to be set, the value of @code{gdbm_cachesize} or
-@code{gdbm_syncmode}.
+@code{gdbm_syncmode} (or the symbol @code{cachesize} or
+@code{syncmode}).
@item value
The value to be set, an integer.
@end table
to turn it on, or @code{0} to turn it off.
@end deffn
-The obsolete and experimental options @code{GDBM_FASTMODE},
-@code{GDBM_CENTFREE} and @code{GDBM_COALESCEBLKS} are not supported by
-this plugin.
+@deffn Variable gdbm_cachesize
+@deffnx Variable gdbm_syncmode
+The value of these variables are meaningful as the @var{option} argument
+to the @code{gdbm-setopt} procedure above.
+@end deffn
@bye
projects / mit-scheme.git / commitdiff