ndbm

README

ndbm

State of the art structured storage for 1986.

ndbm is a Go wrapper around the POSIX NDBM database interface. NDBM is built into Mac OS X and FreeBSD, and is available as a compatibility mode of the GDBM library on Linux.

API documentation is available on GoDoc.

Why?

I wrote the first version of this library on a Mac on a cruise ship, where I needed a persistent key-value store, but had no Internet connection, just OS X system libraries, man pages, and Go documentation.

Linux notes

Most Linux distros don't package an NDBM implementation. Debian/Ubuntu users should install libgdbm3 and libgdbm-dev before building.

To make this package go gettable, I've targeted the quirky GDBM 1.8, which is the version available on Ubuntu 12-15 and Debian 7-8, instead of attempting build-time library detection, which would allow using the current and more NDBM-compatible GDBM 1.11.

If you are using a recent GDBM that provides ndbm.h, you will probably need to delete gdbm_compat.h and gdbm_compat_linux.c and the #ifdef __linux checks.

Background

POSIX standard for NDBM:

• http://pubs.opengroup.org/onlinepubs/9699919799/functions/dbm_open.html
• http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ndbm.h.html

Mac OS X NDBM:

• https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man3/dbm_open.3.html (Note that this is a BSD man page, and the datum struct described is wrong for OS X.)
• http://www.opensource.apple.com/source/Libc/Libc-997.90.3/include/ndbm.h

FreeBSD NDBM:

• https://www.freebsd.org/cgi/man.cgi?query=dbm&apropos=0&sektion=3&manpath=FreeBSD+10.0-RELEASE&format=html
• https://github.com/freebsd/freebsd/blob/master/lib/libc/db/hash/ndbm.c
• https://github.com/freebsd/freebsd/blob/master/include/ndbm.h

GDBM:

• http://www.gnu.org.ua/software/gdbm/manual/html_node/ndbm.html

Documentation

Overview

State of the art structured storage for 1986.

ndbm is a Go wrapper around the POSIX NDBM database interface. NDBM is built into Mac OS X and FreeBSD, and is available as a compatibility mode of the GDBM library on Linux.

Index

• Variables
• type Error
  • func (err Error) Error() string
• type Item
• type KeyAlreadyExists
  • func (err KeyAlreadyExists) Error() string
• type KeyNotFound
  • func (err KeyNotFound) Error() string
• type NDBM
  • func Open(path string, flags, mode int) (*NDBM, error)
  • func OpenWithDefaults(path string) (*NDBM, error)
  • func (ndbm *NDBM) Close()
  • func (ndbm *NDBM) Delete(key []byte) error
  • func (ndbm *NDBM) Fetch(key []byte) ([]byte, error)
  • func (ndbm *NDBM) Insert(key, value []byte) error
  • func (ndbm *NDBM) Items() []Item
  • func (ndbm *NDBM) ItemsCallback(callback func(key, value []byte) error) error
  • func (ndbm *NDBM) Keys() [][]byte
  • func (ndbm *NDBM) KeysCallback(callback func([]byte) error) error
  • func (ndbm *NDBM) Len() int
  • func (ndbm *NDBM) LockExclusive() error
  • func (ndbm *NDBM) LockShared() error
  • func (ndbm *NDBM) Replace(key, value []byte) error
  • func (ndbm *NDBM) Unlock() error
  • func (ndbm *NDBM) Update(items []Item) error
  • func (ndbm *NDBM) Values() [][]byte
  • func (ndbm *NDBM) ValuesCallback(callback func([]byte) error) error

Variables

var ErrAlreadyLocked = fmt.Errorf("Database is already locked")

ErrAlreadyLocked is returned if another process already has a lock.

Types

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error is returned on unexpected NDBM or libc errors.

func (Error) Error

func (err Error) Error() string

type Item

type Item struct {
	Key   []byte
	Value []byte
}

Item is a database entry.

type KeyAlreadyExists

type KeyAlreadyExists struct {
	Key []byte
}

KeyAlreadyExists is returned when trying to insert a key that already exists.

func (KeyAlreadyExists) Error

func (err KeyAlreadyExists) Error() string

type KeyNotFound

type KeyNotFound struct {
	Key []byte
}

KeyNotFound is returned when trying to fetch or delete a key that doesn't exist.

func (KeyNotFound) Error

func (err KeyNotFound) Error() string

type NDBM

type NDBM struct {
	// contains filtered or unexported fields
}

NDBM or compatible database. NDBM is not required by POSIX to be threadsafe, so this library isn't either.

func Open

func Open(path string, flags, mode int) (*NDBM, error)

Open lets you specify how the database is opened, for example, if you want read-only mode.

func OpenWithDefaults

func OpenWithDefaults(path string) (*NDBM, error)

OpenWithDefaults opens an NDBM database in read-write mode and will create it if it doesn't exist with permissions ug=rw,o=.

func (*NDBM) Close

func (ndbm *NDBM) Close()

Close closes the NDBM database.

func (*NDBM) Delete

func (ndbm *NDBM) Delete(key []byte) error

Delete deletes an entry from the database. Returns KeyNotFound if the key can't be found.

func (*NDBM) Fetch

func (ndbm *NDBM) Fetch(key []byte) ([]byte, error)

Fetch retrieves an entry value by key. Returns KeyNotFound if the key can't be found.

func (*NDBM) Insert

func (ndbm *NDBM) Insert(key, value []byte) error

Insert inserts a new entry into the database. Returns KeyAlreadyExists if the key already exists.

func (*NDBM) Items

func (ndbm *NDBM) Items() []Item

Items returns every entry in the database.

func (*NDBM) ItemsCallback

func (ndbm *NDBM) ItemsCallback(callback func(key, value []byte) error) error

ItemsCallback executes a callback function for every entry in the database. The callback should take a key and value and return an error if there is a problem.

func (*NDBM) Keys

func (ndbm *NDBM) Keys() [][]byte

Keys lists every key in the database.

func (*NDBM) KeysCallback

func (ndbm *NDBM) KeysCallback(callback func([]byte) error) error

KeysCallback executes a callback function for every key in the database. The callback should take a key and return an error if there is a problem.

func (*NDBM) Len

func (ndbm *NDBM) Len() int

Len returns the number of entries in the database.

func (*NDBM) LockExclusive

func (ndbm *NDBM) LockExclusive() error

LockExclusive locks the database for a single process.

func (*NDBM) LockShared

func (ndbm *NDBM) LockShared() error

LockShared locks the database for multiple processes. For example, multiple readers can share a read-only database.

func (*NDBM) Replace

func (ndbm *NDBM) Replace(key, value []byte) error

Replace inserts a new entry or overwrites an existing entry.

func (*NDBM) Unlock

func (ndbm *NDBM) Unlock() error

Unlock unlocks the database.

func (*NDBM) Update

func (ndbm *NDBM) Update(items []Item) error

Update takes a list of entries and upserts them into the database.

func (*NDBM) Values

func (ndbm *NDBM) Values() [][]byte

Values returns every value in the database.

func (*NDBM) ValuesCallback

func (ndbm *NDBM) ValuesCallback(callback func([]byte) error) error

ValuesCallback executes a callback function for every value in the database. The callback should take a value and return an error if there is a problem.