lgdbm   -   This is a Lua interface for gdbm, the GNU database manager.


 local G = require "gdbm"
 local d = assert(G.open("/tmp/test.gdbm", "c"))
 d:insert("JAN", "January")
 d:insert("FEB", "February")
 if d:exists("JAN") then print("JAN exists :-)") end
 d:replace("JAN", "Janeiro")
 print("JAN is now", d:fetch("JAN"))
 d:close()  -- don't forget to do this!


This is a gdbm interface for Lua 5.2.
gdbm is the GNU database manager, a replacement of the UNIX dbm library, available at www.gnu.org/software/gdbm/
If you're running Linux, you probably already have gdbm installed.

The code is in the public domain.


close, delete, exists, export, fetch, firstkey, import,
insert, nextkey, open, reorganize, replace, sync

db = G.open( filename, mode )

Returns a userdata representing the open database. The filename is the name of the file (the complete name; gdbm does not append any characters to this name).

The mode is a string, which must start with one of the following:
  r   GDBM_READER - reader
  w   GDBM_WRITER - writer
  c   GDBM_WRCREAT - if database does not exist create new one
  n   GDBM_NEWDB - create a new, empty, database
and the optional remaining characters can be any of the following:
For the meanings of these parameters see man gdbm.
Be aware that n will delete any database which might already exist under that filename.

db:close()   or   G.close( db )
It is important that every database opened is also closed (this is needed to update the reader/writer count on the file).
db:delete( key )   or   G.delete( db, key )
Deletes the key from the database, and returns nil if it wasn't there.
db:exists( key )
Returns true or false
db:export( outputfile )
Test for the existence of this routine before you try to use it ! It's not very portable; it only exists if the variable GDBM_VERSION_MAJOR was defined.
db:fetch( key )
Returns the value of the given key, or nil if it doesn't exist.
Returns the first key (in key order) in the database. This is used in conjunction with nextkey(key) to traverse the whole database.
db:import( inputdb [,replace] )
Test for the existence of this routine before you try to use it ! It's not very portable; it only exists if the variable GDBM_VERSION_MAJOR was defined.
replace is boolean.
db:insert( key, data )
Insert only; returns nil if the key exists already.
db:nextkey( key )
Returns the next key after the given key argument, or nil if it was the last. Starting from firstkey(), this will traverse the whole database (in key order).
This routine should be used very infrequently. If you have had a lot of deletions and would like to shrink the space used by the gdbm file, this routine will reorganize the database. Gdbm will not shorten the length of a database except by using this reorganization.
db:replace( key, data )
Replaces the contents, if the key exists, and returns nil otherwise.
Physically writes the current state of the database out to the disk file. It will not return until the disk file state is synchronized with the in-memory state of the database.


The following code from test.lua, by the module author Luiz Henrique de Figueiredo, creates table proxies for gdbm databases, and two "for" generators: "keys" and "entries", for convenient traversal of databases.

local gdbm = require "gdbm"
local M = {
  __index = function (t,k) return t.gdbm:fetch(k) end,
  __newindex = function (t,k,v)
    if v~=nil then t.gdbm:replace(k,v) else t.gdbm:delete(k) end
function gdbm.proxy(t)
  return setmetatable({gdbm=t}, M)
local function keys(d,k)
  if k==nil then return d:firstkey() else return d:nextkey(k) end
function gdbm.keys(d)
 return keys,d
local function entries(d,k)
  local v
  if k==nil then k=d:firstkey() else k=d:nextkey(k) end
  if k==nil then v=nil else v=d:fetch(k) end
  return k,v
function gdbm.entries(d)
  return entries,d

local t = d:proxy()
t.JUL = "July"  -- proxy insert
t.JAN =  nil    -- proxy delete

if d.export and d.import then  -- check first!
  F="test.flat" -- testing export and import
  print("export  ",d:export(F))
  print("import store",d:import(F))
  print("import replace",d:import(F,true))



This module is available as a LuaRock in luarocks.org/modules/luarocks/lgdbm so you should be able to install it with the command:

 $ su
 # luarocks install lgdbm

If this results in an error message such as:
  Error: Could not find expected file libgdbm.a, or libgdbm.so,
  or libgdbm.so.* for GDBM -- you may have to install GDBM in your
  system and/or pass GDBM_DIR or GDBM_LIBDIR to the luarocks command.
  Example: luarocks install lgdbm GDBM_DIR=/usr/local
then you need to find the appropriate directory with:
  find /usr/lib -name 'libgdbm.*' -print
and then invoke:
  luarocks install lgdbm GDBM_LIBDIR=/usr/lib/i386-linux-gnu/
(or wherever) accordingly.

For detailed installation instructions, see also: www.tecgraf.puc-rio.br/~lhf/ftp/lua/install.html


The Lua module is by Luiz Henrique de Figueiredo
Comments, suggestions, and bug reports to lhf@tecgraf.puc-rio.br

This manual page was put together by Peter Billam
See:   www.pjb.com.au,   www.pjb.com.au/comp/contact.html


 man gdbm