CS245A Winter 98

What's ndbm?

The library ndbm is a collection of routines that manages data files that contain key/data pairs. The library provides storing, retrieval, and deletion of data by key, as well as non-sorted traversal of all keys.

A Sample Application

This application creates a database, adds a record to it and then retrieves it. The function and data structures used are explained in the next section. Note that this application lacks error management.

 
     #include <ndbm.h>     
     #include <stdio.h> 
     #include <fcntl.h> 
   
     #define NAME       "Arturo Crespo" 
     #define PHONE_NO   "723-9273" 
     #define DB_NAME    "phones" 

   
     main()   
     {
          DBM *db;
          datum name = {NAME, sizeof (NAME)};
          datum put_phone_no = {PHONE_NO, sizeof (PHONE_NO)};
          datum get_phone_no;
   
          // Open the database and store the record
          db = dbm_open(DB_NAME, O_RDWR | O_CREAT, 0600);
          dbm_store(db, name, put_phone_no, DBM_INSERT);
   
          // Retrieve the record
          get_phone_no = dbm_fetch(db, name);
          printf("Name: %s, Phone Number: %s0, name.dptr, get_phone_no.dptr);

          // Close the database
          dbm_close(db);
          return (0);
     }





 

Keys and contents in the database are described by the datum typedef:

 
     typedef struct {
        char *dptr;
        int dsize;
     } datum;



    
 

DBM *dbmopen(char* fileName, int flags, int mode)

Before the data base fileName can be accessed, it must be opened or created with this function. The parameters flag and mode are the same as in the open() function and specify in which state the file will be opened ( ORDONLY, OWRONLY, ORDWR, OAPPEND, OCREAT ) and the mode (usually 0600, meaning read and write privileges for the owner only). The function returns a handle for the database.

void dbmclose(DBM* db)

The database with handle db is closed using this function.

datum dbmfetch(DBM* db, datum key)

Retrieves from the database db the data associated with key . Note that key must be of type datum.

int dbmstore(DBM* db, datum key, datum content, int flags)

Stores in the database db the pair key / content . The flags parameter specified what to do with duplicate keys. If flags is DBMINSERT and you try to insert a duplicate key, dbmstore() will return an error and will not change the existing entry. On the other hand, If the flags is set to DBMREPLACE , ndbm will replace the existing entry.

int dbmdelete(DBM* db, datum key)

A key and its associated contents is deleted with this function.

datum dbmfirstkey(DBM* db) and datum dbmnextkey(DBM* db)

A linear pass through all keys in a data base can be made by use of dbmfirstkey() and dbmnextkey() . dbmfirstkey() will return the first key in the data base. dbmnextkey() will return the next key in the data base. The order in which keys are returned is not defined. This code segment will traverse the data base:

for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))

Error Handling

All functions that return an int indicate errors with negative values. A zero return indicates no error. Routines that return a datum indicate errors with a NULL dptr.

Compiling with the library

This library is part of the default libraries in the Elaines, so you do not need any extra parameters when compiling with gcc.

More Information

For more information look at the man pages of ndbm and dbm.