Chapter 25 | The dbm library: access to NDBM databases

The `dbm` library provides access to NDBM databases under Unix. NDBM databases maintain key/data associations, where both the key and the data are arbitrary strings. They support fairly large databases (several gigabytes) and can retrieve a keyed item in one or two file system accesses. Refer to the Unix manual pages for more information.
Unix:

> Programs that use the `dbm` library must be linked as follows:

>             ocamlc other options dbm.cma other files
>             ocamlopt other options dbm.cmxa other files

> For interactive use of the `dbm` library, do:

>             ocamlmktop -o mytop dbm.cma
>             ./mytop

Windows:

> This library is not available.

25.1 | Module `Dbm`: interface to the NDBM database

    type t

> The type of file descriptors opened on NDBM databases.

    type open_flag =
       Dbm_rdonly | Dbm_wronly | Dbm_rdwr | Dbm_create

> Flags for opening a database (see `opendbm`).

    exception Dbm_error of string

> Raised by the following functions when an error is encountered.

    val opendbm : string -> mode:open_flag list -> perm:int -> t

> Open a descriptor on an NDBM database. The first argument is the name of the database (without the `.dir` and `.pag` suffixes). The second argument is a list of flags: `Dbm_rdonly` opens the database for reading only, `Dbm_wronly` for writing only, `Dbm_rdwr` for reading and writing; `Dbm_create` causes the database to be created if it does not already exist. The third argument is the permissions to give to the database files, if the database is created.

    val close : t -> unit

> Close the given descriptor.

    val find : t -> string -> string

> `find db key` returns the data associated with the given `key` in the database opened for the descriptor `db`. Raise `Not_found` if the `key` has no associated data.

    val add : t -> key:string -> data:string -> unit

> `add db key data` inserts the pair (`key`, `data`) in the database `db`. If the database already contains data associated with `key`, raise `Dbm_error "Entry already exists"`.

    val replace : t -> key:string -> data:string -> unit

> `replace db key data` inserts the pair (`key`, `data`) in the database `db`. If the database already contains data associated with `key`, that data is discarded and silently replaced by the new `data`.

    val remove : t -> string -> unit

> `remove db key data` removes the data associated with `key` in `db`. If `key` has no associated data, raise `Dbm_error "dbm_delete"`.

    val firstkey : t -> string
    val nextkey : t -> string

> Enumerate all keys in the given database, in an unspecified order. `firstkey db` returns the first key, and repeated calls to `nextkey db` return the remaining keys. `Not_found` is raised when all keys have been enumerated.

    val iter : f:(key:string -> data:string -> 'a) -> t -> unit

> `iter f db` applies `f` to each (`key`, `data`) pair in the database `db`. `f` receives `key` as first argument and `data` as second argument.