dbm-close

Generic Function, dbi.ndbm package

Arguments: ndbm

dbm-close closes an ndbm database that had been opened with dbm-open.
It is okey to call dbm-close again on a database that has already been closed.

See ndbm.html for information on the NDBM facility.

dbm-delete

Generic Function, dbi.ndbm package

Arguments: ndbm key &key external-format if-does-not-exist

dbm-delete removes a key from the database specified by ndbm (which should be a value returned by dbm-open). key can be a string or a usb8 array. If key is a string, it will be internally converted to a usb8 array according to the external-format keyword argument (or, if not supplied, the default determined by dbm-open will be used).
If the key does not exist in the database, and:

• if-does-not-exist is :error, then an error is signaled.
• if-does-not-exist is nil (the default), then nil is returned

If the key did exist, it is removed and t is returned.

See ndbm.html for information on the NDBM facility.

dbm-fetch

Generic Function, dbi.ndbm package

Arguments: ndbm key &key external-format if-does-not-exist return

dbm-fetch retrieves content from the database specified by ndbm (which should be a value returned by dbm-open). key is used to locate the data. If key is a string, it will be internally converted to a usb8 array according to the external-format keyword argument (or, if not supplied, the default determined by dbm-open will be used). If the key does not exist in the database and:

• if-does-not-exist is nil (the default), then dbm-fetch returns nil.

• if-does-not-exist is :error, then dbm-fetch signals an error.

If the key is found, then dbm-fetch returns the corresponding data. If the return keyword argument is :string, then the data will be converted to a string according to the external-format keyword argument (or the default determined by dbm-open). If return is :usb8, the the data will be returned as a usb8 array. If return is not specified, then the data will be returned in whatever format was specified as the default to dbm-open.

See ndbm.html for information on the NDBM facility.

dbm-firstkey

Generic Function, dbi.ndbm package

Arguments: ndbm &key return external-format

dbm-firstkey starts a database traversal process and returns the first key found by that process. ndbm should be a database returned by dbm-open. This generic function is used in combination with dbm-nextkey to traverse a database.

Keys are not stored in any interesting order. If return is supplied (the value can be :string or :usb8), it determines the return data type, otherwise the default as determined by dbm-open is used. If the return type is :string, then external-format is used to convert the data to a string. If external-format is not supplied, then again the default as determined by dbm-open is used.

Note: If you call dbm-store or dbm-delete while traversing a database using dbm-firstkey/dbm-nextkey, you should restart the traversal by calling dbm-firstkey again.

See ndbm.html for information on the NDBM facility.

dbm-nextkey

Generic Function, dbi.ndbm package

Arguments: ndbm &key if-exists external-format return

dbm-nextkey returns the next key from the database ndbm. dbm-firstkey should have already been called on ndbm. The keyword arguments are the same as dbm-firstkey.

Note: If you call dbm-store or dbm-delete while traversing a database using dbm-firstkey/dbm-nextkey, you should restart the traversal by calling dbm-firstkey again.

See ndbm.html for information on the NDBM facility.

dbm-open

Function, dbi.ndbm package

Arguments: filename &key if-exists if-does-not-exist default-return external-format mode store-null-terminators

dbm-open opens or creates an ndbm database. filename specifies the base filename for the database (notes on this below).

The keyword arguments are:

• if-exists: the value may be :append (the default), :overwrite, or :supersede. :append and :overwrite are synonymous and indicate that an existing database should be opened. :supersede means that any existing database should be erased and a fresh database should be created.
• if-does-not-exist: the value may be :error (the default) or :create. :error means that an error will be generated if the database does not exist. :create means that a fresh database will be created if one does not exist.
• default-return: this argument specifies the default data type to return from dbm-fetch. Internally, NDBM databases simply work with byte arrays. However, it is often convenient to work with strings. If default-return is :string (the default), then database data will be converted to strings before being returned from dbm-fetch (unless the return type is specified in the call to dbm-fetch). If default-return is :usb8, then dbm-fetch will return usb8 vectors (that is, (unsigned-byte 8) vectors) unless the return type is specified in the call to dbm-fetch.
• external-format: this argument specifies the default external format to use when storing/retrieving strings from the database. If not supplied, then (locale-external-format *locale*) will be used. (See locale-external-format and *locale*.)
• mode: this argument is defined by the open(2) system call documentation on each system. No value need be specified, as the default value is generally suitable.
• store-null-terminators: if this argument is true (the default), then when strings are used as keys or data, their null terminating bytes are included in the data stored in the database.

This function returns an ndbm object.

Note about the filename

Your operating system's implementation of NDBM may augment the supplied filename and open/create additional files to support the database. For example, many implementations take the base filename and make two files: filename.dir and file.pag. Always use just the base filename when calling dbm-open.

See ndbm.html for information on the NDBM facility.

dbm-store

Generic Function, dbi.ndbm package

Arguments: ndbm key content &key if-exists external-format

dbm-store stores a key/content pair into the database specified by ndbm (which was returned by a call to dbm-open). key can be a string or a usb8 vector. If key is a string, it will be internally converted to a usb8 array according to the external-format keyword argument (or, if not supplied, the default determined by dbm-open will be used). Likewise for content, if it is a string. If the key to be stored already exists, and:

• if-exists is nil, then dbm-store will return nil and the operation will not be performed.
• if-exists is :error, then an error will be generated.
• if-exists is :replace (the default), then the existing key will be replaced.

dbm-store returns t if a key was added or replaced.

See ndbm.html for information on the NDBM facility.

with-dbm-iterator

Macro, dbi.ndbm package

Arguments: (ndbm keyvar &key external-format return) &body body

This macro executes body in a loop with keyvar bound to successive keys found while traversing the database ndbm with dbm-firstkey/dbm-nextkey. See dbm-firstkey for information about the external-format and return keyword arguments.

Evaluating (return) allows you to break from the loop early.

Do not call dbm-store or dbm-delete while within with-dbm-iterator.

See ndbm.html for information on the NDBM facility.

with-open-dbm

Macro, dbi.ndbm package

Arguments: (dbsym &rest args) &body body

The body of this macro will execute with dbsym bound to an ndbm database opened via a call to dbm-open with arguments specified by args. When the body has finished (either normally or exceptionally), the database will be closed.

See ndbm.html for information on the NDBM facility.

Copyright (c) 2023, Franz Inc. Lafayette, CA., USA. All rights reserved.