cdb

README

cdb

This is a Go package to read and write cdb ("constant database") files.

The cdb file format is a machine-independent format with the following features:

• Fast lookups: A successful lookup in a large database normally takes just two disk accesses. An unsuccessful lookup takes only one.
• Low overhead: A database uses 2048 bytes, plus 24 bytes per record, plus the space for keys and data.
• No random limits: cdb can handle any database up to 4 gigabytes. There are no other restrictions; records don't even have to fit into memory.

See the original cdb specification and C implementation by D. J. Bernstein at http://cr.yp.to/cdb.html.

Installation

Assuming you have a working Go environment, installation is simply:

go get github.com/jbarham/cdb

The package documentation can be viewed online at https://pkg.go.dev/github.com/jbarham/cdb or on the command line by running go doc github.com/jbarham/cdb.

The included self-test program cdb_test.go illustrates usage of the package.

Utilities

The cdb package includes ports of the programs cdbdump and cdbmake from the original implementation.

Documentation

Overview

Package cdb reads and writes cdb ("constant database") files.

See the original cdb specification and C implementation by D. J. Bernstein at http://cr.yp.to/cdb.html.

Index

• Variables
• func Dump(w io.Writer, r io.Reader) (err error)
• func Make(w io.WriteSeeker, r io.Reader) (err error)
• type Cdb
  • func New(r io.ReaderAt) *Cdb
  • func Open(name string) (*Cdb, error)
  • func (c *Cdb) Close() (err error)
  • func (c *Cdb) Data(key []byte) (data []byte, err error)
  • func (c *Cdb) Find(key []byte) (rdata *io.SectionReader, err error)
  • func (c *Cdb) FindNext(key []byte) (rdata *io.SectionReader, err error)
  • func (c *Cdb) FindStart()

Variables

var BadFormatError = errors.New("bad format")

Functions

func Dump

func Dump(w io.Writer, r io.Reader) (err error)

Dump reads the cdb-formatted data in r and dumps it as a series of formatted records (+klen,dlen:key->data\n) and a final newline to w. The output of Dump is suitable as input to Make. See http://cr.yp.to/cdb/cdbmake.html for details on the record format.

func Make

func Make(w io.WriteSeeker, r io.Reader) (err error)

Make reads cdb-formatted records from r and writes a cdb-format database to w. See the documentation for Dump for details on the input record format.

Types

type Cdb

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

func New

func New(r io.ReaderAt) *Cdb

New creates a new Cdb from the given ReaderAt, which should be a cdb format database.

func Open

func Open(name string) (*Cdb, error)

Open opens the named file read-only and returns a new Cdb object. The file should exist and be a cdb-format database file.

func (*Cdb) Close

func (c *Cdb) Close() (err error)

Close closes the cdb for any further reads.

func (*Cdb) Data

func (c *Cdb) Data(key []byte) (data []byte, err error)

Data returns the first data value for the given key. If no such record exists, it returns EOF.

func (*Cdb) Find

func (c *Cdb) Find(key []byte) (rdata *io.SectionReader, err error)

Find returns the first data value for the given key as a SectionReader. Find is the same as FindStart followed by FindNext.

func (*Cdb) FindNext

func (c *Cdb) FindNext(key []byte) (rdata *io.SectionReader, err error)

FindNext returns the next data value for the given key as a SectionReader. If there are no more records for the given key, it returns EOF. FindNext acts as an iterator: The iteration should be initialized by calling FindStart and all subsequent calls to FindNext should use the same key value.

func (*Cdb) FindStart

func (c *Cdb) FindStart()

FindStart resets the cdb to search for the first record under a new key.