gdbm_open() -- GDBM Function (libgdbm)

Open a GDBM data base
#include <gdbm.h>
GDBM_FILE gdbm_open(database, block_size, read_write, mode, bailout)
char *database;
int block_size, read_write, mode;
void (*bailout)();

Function  gdbm_open()  opens a  GDBM  data base.   It  takes the  following
parameters:

database
     This gives  the complete name  of the data  base.  Please note  that a
     data base  actually consists of  two files: one,  called database.dir,
     holds  the hashed  index; the  other,  called database.pag,  holds the
     data.  The  GDBM routines manage the manipulation  of these files; you
     need not  worry about  them yourself.  (For  more details on  how GDBM
     works, see the Lexicon entry for libgdbm.)

block_size
     This  gives  the  size of  a  single  transfer  from  disk to  memory.
     gdbm_open()  ignores this  parameter is unless  database is  new.  The
     minimum size is 512.  If you set block_size to less than 512, the GDBM
     routines use a block size of BSIZE. (This constant gives the size of a
     block under COHERENT; it is set in header file <sys/buf.h>.

read_write
     This parameter  indicates whether you  are opening the  data base into
     read mode  or write mode.   If a process  opens database only  to read
     records within it, it is  called a ``reader''.  If, however, a process
     can also  add records  to database, remove  record from it,  or modify
     records within it, it is  called a ``writer''.  database can be opened
     by multiple  readers simultaneously, or by a  single writer; it cannot
     be opened  by multiple  writers simultaneously, or  by a reader  and a
     writer simultaneously.   This rule prevents a  writer from modifying a
     data base while it is being read, and so confusing the readers; and to
     prevent multiple writers from ``clobbering'' each other's changes.

     read_write can be one of the following values:

     GDBM_READER
          The process opening database is a reader.
     GDBM_WRITER
          The process opening database is a writer.
     GDBM_WRCREAT
          The  process  opening database  is  a writer;  if  the data  base
          database does not exist, create it.
     GDBM_NEWDB
          The process  opening database is  a writer; create  database as a
          new data base, regardless of whether it already exists.
     GDBM_FAST
          If  this  constant is  OR'd  onto  GDBM_WRITER, GDBM_WRCREAT,  or
          GDBM_NEWDB, the  GDBM routines write the  data base without disk-
          file  syncronization.   This speeds  writing  to  the data  base;
          however, if the writer  dies unexpectedly, some data may be lost.
          To flush buffered data to disk, call function gdbm_sync().

mode This is a bitwise OR of the modes into which database is created.  For
     a list of  the flags that can be incorporated  into this argument, see
     the  Lexicon entry  stat.h. gdbm_open()  ignores this  argument unless
     read_write is set to GDBM_WRCREAT or GDBM_NEWDB.

bailout
     This  points to  the function  that gdbm_open()  calls should  a fatal
     error occur.  This function must take only one argument, a string that
     holds an error message.  If you set bailout to NULL, the GDBM routines
     use a default function.

If  all goes  well,  gdbm_open() returns  a  pointer to  a  record of  type
GDBM_FILE. All other GDBM functions need this record to manipulate the data
base in  database. If  an error occurs,  gdbm_open() returns NULL  and sets
global  variable   gdbm_errno  and   errno  to  appropriate   values.   For
information on  interpreting the contents  of errno, see  the Lexicon entry
for errno.h;  for information on  interpreting the contents  of gdbm_errno,
see the entry for gdbmerrno.h.

See Also


Notes

For  a statement  of copyright  and  permissions on  this routine,  see the
Lexicon entry for libgdbm.

© 2012 by Stephen A. Ness