dbm_store man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

ndbm(3C)		 Standard C Library Functions		      ndbm(3C)

NAME
       ndbm,   dbm_clearerr,   dbm_close,  dbm_delete,	dbm_error,  dbm_fetch,
       dbm_firstkey, dbm_nextkey, dbm_open, dbm_store - database functions

SYNOPSIS
       #include <ndbm.h>

       int dbm_clearerr(DBM *db);

       void dbm_close(DBM *db);

       int dbm_delete(DBM *db, datum key);

       int dbm_error(DBM *db);

       datum dbm_fetch(DBM *db, datum key);

       datum dbm_firstkey(DBM *db);

       datum dbm_nextkey(DBM *db);

       DBM *dbm_open(const char *file, int open_flags, mode_t file_mode);

       int dbm_store(DBM *db, datum key, datum content, int store_mode);

DESCRIPTION
       These functions create, access and modify  a  database.	They  maintain
       key/content  pairs in a database. The functions will handle large data‐
       bases (up to a billion blocks) and will access a keyed item in  one  or
       two  file  system  accesses.  This  package  replaces  the  earlier dbm
       library, which managed only a single database.

       keys and contents are described by the datum typedef. A datum  consists
       of  at  least two members, dptr and dsize. The dptr member points to an
       object that is dsize bytes in length.  Arbitrary binary data,  as  well
       as  ASCII  character strings, may be stored in the object pointed to by
       dptr.

       The database is stored in two files. One file is a directory containing
       a bit map of keys and has .dir as its suffix.  The second file contains
       all data and has .pag as its suffix.

       The dbm_open() function opens a database.  The  file  argument  to  the
       function is the pathname of the database.  The function opens two files
       named file.dir and file.pag. The open_flags argument has the same mean‐
       ing  as the flags argument of open(2) except that a database opened for
       write-only access opens the files  for  read  and  write	 access.   The
       file_mode  argument  has	 the  same  meaning  as	 the third argument of
       open(2).

       The dbm_close() function closes a database.  The argument db must be  a
       pointer	to  a  dbm  structure  that  has  been returned from a call to
       dbm_open().

       The dbm_fetch() function reads a record from a database.	 The  argument
       db  is  a pointer to a database structure that has been returned from a
       call to dbm_open(). The argument key is a datum that has been  initial‐
       ized  by	 the  application program to the value of the key that matches
       the key of the record the program is fetching.

       The dbm_store() function writes a record to a database.	 The  argument
       db  is  a pointer to a database structure that has been returned from a
       call to dbm_open(). The argument key is a datum that has been  initial‐
       ized by the application program to the value of the key that identifies
       (for subsequent reading, writing or deleting) the record the program is
       writing.	 The  argument content is a datum that has been initialized by
       the application program to the value of the record the program is writ‐
       ing.  The argument store_mode controls whether dbm_store() replaces any
       pre-existing record that has the same key that is specified by the  key
       argument.   The	application  program  must  set	 store_mode  to either
       DBM_INSERT or DBM_REPLACE.  If the  database  contains  a  record  that
       matches	the  key  argument and store_mode is DBM_REPLACE, the existing
       record is replaced with the new record.	If  the	 database  contains  a
       record  that matches the key argument and store_mode is DBM_INSERT, the
       existing record is not replaced with the new record.  If	 the  database
       does  not contain a record that matches the key argument and store_mode
       is either DBM_INSERT or DBM_REPLACE, the new record is inserted in  the
       database.

       The  dbm_delete()  function deletes a record and its key from the data‐
       base.  The argument db is a pointer to a database  structure  that  has
       been  returned  from  a call to dbm_open(). The argument key is a datum
       that has been initialized by the application program to	the  value  of
       the key that identifies the record the program is deleting.

       The dbm_firstkey() function returns the first key in the database.  The
       argument db is a pointer to a database structure that has been returned
       from a call to dbm_open().

       The  dbm_nextkey()  function returns the next key in the database.  The
       argument db is a pointer to a database structure that has been returned
       from  a	call to dbm_open(). The dbm_firstkey() function must be called
       before calling dbm_nextkey(). Subsequent calls to dbm_nextkey()	return
       the next key until all of the keys in the database have been returned.

       The  dbm_error()	 function returns the error condition of the database.
       The argument db is a pointer to a  database  structure  that  has  been
       returned from a call to dbm_open().

       The dbm_clearerr() function clears the error condition of the database.
       The argument db is a pointer to a  database  structure  that  has  been
       returned from a call to dbm_open().

       These  database	functions  support  key/content pairs of at least 1024
       bytes.

RETURN VALUES
       The dbm_store() and dbm_delete() functions return 0 when	 they  succeed
       and a negative value when they fail.

       The  dbm_store()	 function returns 1 if it is called with a flags value
       of DBM_INSERT and the function finds an existing record with  the  same
       key.

       The  dbm_error()	 function  returns 0 if the error condition is not set
       and returns a non-zero value if the error condition is set.

       The return value of dbm_clearerr() is unspecified .

       The dbm_firstkey() and dbm_nextkey() functions return a key datum. When
       the  end	 of  the  database is reached, the dptr member of the key is a
       null pointer.  If an error is detected, the dptr member of the key is a
       null pointer and the error condition of the database is set.

       The  dbm_fetch()	 function returns a content datum. If no record in the
       database matches the key or if an error condition has been detected  in
       the database, the dptr member of the content is a null pointer.

       The  dbm_open() function returns a pointer to a database structure.  If
       an error is detected during the operation, dbm_open()  returns  a  (DBM
       *)0.

ERRORS
       No errors are defined.

USAGE
       The following code can be used to traverse the database:

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

       The  dbm_  functions provided in this library should not be confused in
       any way with those of a	general-purpose	 database  management  system.
       These functions do not provide for multiple search keys per entry, they
       do not protect against multi-user access (in other words	 they  do  not
       lock  records  or files), and they do not provide the many other useful
       database functions that are found in more  robust  database  management
       systems.	  Creating and updating databases by use of these functions is
       relatively slow because of data copies that occur upon hash collisions.
       These  functions	 are  useful for applications requiring fast lookup of
       relatively static information that is to be indexed by a single key.

       The dptr pointers returned by these functions  may  point  into	static
       storage that may be changed by subsequent calls.

       The  dbm_delete()  function  does  not  physically  reclaim file space,
       although it does make it available for reuse.

       After calling dbm_store() or dbm_delete() during	 a  pass  through  the
       keys  by dbm_firstkey() and dbm_nextkey(), the application should reset
       the database by calling dbm_firstkey() before  again  calling  dbm_nex‐
       tkey().

EXAMPLES
       Example 1 Using the Database Functions

       The  following  example	stores and retrieves a phone number, using the
       name as the key.	 Note that this example does not include error	check‐
       ing.

	 #include <ndbm.h>
	 #include <stdio.h>
	 #include <fcntl.h>
	 #define NAME	   "Bill"
	 #define PHONE_NO	   "123-4567"
	 #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, 0660);
	      (void) dbm_store(db, name, put_phone_no, DBM_INSERT);
	      /* Retrieve the record */
	      get_phone_no = dbm_fetch(db, name);
	      (void) printf("Name: %s, Phone Number: %s\n", name.dptr,
	      get_phone_no.dptr);
	      /* Close the database */
	      dbm_close(db);
	      return (0);
	 }

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Committed			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │Unsafe			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Standard		     │See standards(5).		   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       ar(1),  cat(1),	cp(1),	tar(1),	 open(2), netconfig(4), attributes(5),
       standards(5)

NOTES
       The .pag file will contain holes so  that  its  apparent	 size  may  be
       larger  than  its  actual content. Older versions of the UNIX operating
       system may create real file blocks for these holes when touched.	 These
       files  cannot be copied by normal means ( cp(1), cat(1), tar(1), ar(1))
       without filling in the holes.

       The sum of the sizes of a key/content pair must not exceed the internal
       block  size (currently 1024 bytes). Moreover all key/content pairs that
       hash together must fit on a single block. dbm_store()  will  return  an
       error in the event that a disk block fills with inseparable data.

       The order of keys presented by dbm_firstkey() and dbm_nextkey() depends
       on a hashing function.

       There are no interlocks and no reliable cache flushing; thus concurrent
       updating and reading is risky.

       The database files (file.dir and file.pag) are binary and are architec‐
       ture-specific (for example, they	 depend	 on  the  architecture's  byte
       order.)	These files are not guaranteed to be portable across architec‐
       tures.

SunOS 5.11			  17 Sep 2001			      ndbm(3C)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net