Integrate gbm (gnu-dbm) into Solaris [PSARC/2008/645 FastTrack timeout 10/28/2008] update
Martina Tomisova
Martina.Tomisova at sun.com
Mon Nov 3 04:13:07 PST 2008
Hi,
I'm sorry I've forgotten to update the man page. I'm going to send it as
fast as possible.
Enjoy the day,
Martina
On 11/03/08 11:04, Martina Tomisova wrote:
> Hi all,
>
> there is a new proposal (I hope the last version). I've decided to
> remove the compatibility libraries and put the gdbm.h file into the
> /usr/include/ directly.
>
>
>
> Proposal:
>
> Integrate gbm (gnu-dbm) into Solaris.
>
> Detail:
>
> A set of database routines that use extensible hashing. It works
> like ndbm, however it adds support for arbitrary length data in
> the database, as previously (at dbm or ndbm) all data had had a
> fixed maximum length.
>
> It does not contain the compatibility library which behaves
> exactly like dbm or ndbm library.
>
> The current version of gdbm is 1.8.3 at the time of this case.
>
>
> Release Binding:
>
> Micro
>
>
> Exported Interfaces:
>
> SUNWgnu-dbm Committed Package name
>
> /usr/lib/libgdbm.so Uncommitted Symbolic link to
> libgdbm.so.3.0.0
>
> /usr/lib/libgdbm.so.3 Uncommitted Symbolic link to
> libgdbm.so.3.0.0
>
> /usr/lib/libgdbm.so.3.0.0 Uncommitted Shared object
> library API's
>
> /usr/include/gdbm.h Uncommitted Header file
>
>
> References:
>
> [1] http://www.gnu.org/software/gdbm/
> Leader(s) of gdbm project: Jason Downs <downsj at downsj.com>
> [2] 6744694 - Integrate gdbm into Solaris.
> [3] gdbm.3 - man page (attached)
>
>
> 6. Resources and Schedule
> 6.4. Steering Committee requested information
> 6.4.1. Consolidation C-team Name:
> SFW
> 6.5. ARC review type: FastTrack
> 6.6. ARC Exposure: open
>
>
>
>
> Introduction to Library Functions GDBM(3)
>
> NAME
> GDBM - The GNU database manager. Includes dbm and ndbm com-
> patability. (Version 1.8.3.)
>
> SYNOPSIS
> #include <gdbm/gdbm.h>
>
> extern gdbm_error
> gdbm_errno
>
> extern char
> *gdbm_version
>
> GDBM_FILE
> gdbm_open (name, block_size, read_write, mode, fatal_func)
> char * name;
> int block_size, read_write, mode;
> void (*fatal_func) ();
>
> void
> gdbm_close (dbf)
> GDBM_FILE dbf;
>
> int
> gdbm_store (dbf, key, content, flag)
> GDBM_FILE dbf;
> datum key, content;
> int flag;
>
> datum
> gdbm_fetch (dbf, key)
> GDBM_FILE dbf;
> datum key;
>
> int
> gdbm_delete (dbf, key)
> GDBM_FILE dbf;
> datum key;
>
> datum
> gdbm_firstkey (dbf)
> GDBM_FILE dbf;
>
> datum
> gdbm_nextkey (dbf, key)
> GDBM_FILE dbf;
> datum key;
>
> int
> gdbm_reorganize (dbf)
> GDBM_FILE dbf;
>
> SunOS 5.10 Last change: 10/15/2002 1
>
> Introduction to Library Functions GDBM(3)
>
> void
> gdbm_sync (dbf)
> GDBM_FILE dbf;
>
> int
> gdbm_exists (dbf, key)
> GDBM_FILE dbf;
> datum key;
>
> char *
> gdbm_strerror (errno)
> gdbm_error errno;
>
> int
> gdbm_setopt (dbf, option, value, size)
> GDBM_FILE dbf;
> int option;
> int *value;
> int size;
>
> int
> gdbm_fdesc (dbf)
> GDBM_FILE dbf;
>
> DBM Compatability routines:
>
> #include <gdbm/dbm.h>
>
> int
> dbminit (name)
> char *name;
>
> int
> store (key, content)
> datum key, content;
>
> datum
> fetch (key)
> datum key;
>
> int
> delete (key)
> datum key;
>
> datum
> firstkey ()
>
> datum
> nextkey (key)
> datum key;
>
> SunOS 5.10 Last change: 10/15/2002 2
>
> Introduction to Library Functions GDBM(3)
>
> int
> dbmclose ()
>
> NDBM Compatability routines:
>
> #include <gdbm/ndbm.h>
>
> DBM
> *dbm_open (name, flags, mode)
> char *name;
> int flags, mode;
>
> void
> dbm_close (file)
> DBM *file;
>
> datum
> dbm_fetch (file, key)
> DBM *file;
> datum key;
>
> int
> dbm_store (file, key, content, flags)
> DBM *file;
> datum key, content;
> int flags;
>
> int
> dbm_delete (file, key)
> DBM *file;
> datum key;
>
> datum
> dbm_firstkey (file)
> DBM *file;
>
> datum
> dbm_nextkey (file)
> DBM *file;
>
> int
> dbm_error (file)
> DBM *file;
>
> int
> dbm_clearerr (file)
> DBM *file;
>
> int
> dbm_pagfno (file)
> DBM *file;
>
> SunOS 5.10 Last change: 10/15/2002 3
>
> Introduction to Library Functions GDBM(3)
>
> int
> dbm_dirfno (file)
> DBM *file;
>
> int
> dbm_rdonly (file)
> DBM *file;
>
> DESCRIPTION
> GNU dbm is a library of routines that manages data files
> that contain key/data pairs. The access provided is that of
> storing, retrieval, and deletion by key and a non-sorted
> traversal of all keys. A process is allowed to use multiple
> data files at the same time.
>
> A process that opens a gdbm file is designated as a "reader"
> or a "writer". Only one writer may open a gdbm file and
> many readers may open the file. Readers and writers can not
> open the gdbm file at the same time. The procedure for open-
> ing a gdbm file is:
>
> GDBM_FILE dbf;
>
> dbf = gdbm_open ( name, block_size, read_write, mode,
> fatal_func )
>
> Name is the name of the file (the complete name, gdbm does
> not append any characters to this name). Block_size is the
> size of a single transfer from disk to memory. This parame-
> ter is ignored unless the file is a new file. The minimum
> size is 512. If it is less than 512, dbm will use the stat
> block size for the file system. Read_write can have one of
> the following values:
> GDBM_READER reader
> GDBM_WRITER writer
> GDBM_WRCREAT writer - if database does not exist create new
> one
> GDBM_NEWDB writer - create new database regardless if one
> exists
> For the last three (writers of the database) the following
> may be added added to read_write by bitwise or: GDBM_SYNC,
> which causes all database operations to be synchronized to
> the disk, and GDBM_NOLOCK, which prevents the library from
> performing any locking on the database file. The option
> GDBM_FAST is now obsolete, since gdbm defaults to no-sync
> mode.
> Mode is the file mode (see chmod(2) and open(2)) if the file
> is created. (*Fatal_func) () is a function for dbm to call
> if it detects a fatal error. The only parameter of this
> function is a string. If the value of 0 is provided, gdbm
>
> SunOS 5.10 Last change: 10/15/2002 4
>
> Introduction to Library Functions GDBM(3)
>
> will use a default function.
>
> The return value dbf is the pointer needed by all other rou-
> tines to access that gdbm file. If the return is the NULL
> pointer, gdbm_open was not successful. The errors can be
> found in gdbm_errno for gdbm errors and in errno for system
> errors. (For error codes, see gdbmerrno.h.)
>
> In all of the following calls, the parameter dbf refers to
> the pointer returned from gdbm_open.
>
> It is important that every file opened is also closed. This
> is needed to update the reader/writer count on the file.
> This is done by:
> gdbm_close (dbf);
>
> The database is used by 3 primary routines. The first
> stores data in the database.
>
> ret = gdbm_store ( dbf, key, content, flag )
>
> Dbf is the pointer returned by gdbm_open. Key is the key
> data. Content is the data to be associated with the key.
> Flag can have one of the following values:
> GDBM_INSERT insert only, generate an error if key exists
> GDBM_REPLACE replace contents if key exists.
>
> If a reader calls gdbm_store, the return value will be -1.
> If called with GDBM_INSERT and key is in the database, the
> return value will be 1. Otherwise, the return value is 0.
>
> NOTICE: If you store data for a key that is already in the
> data base, gdbm replaces the old data with the new data if
> called with GDBM_REPLACE. You do not get two data items for
> the same key and you do not get an error from gdbm_store.
>
> NOTICE: The size in gdbm is not restricted like dbm or ndbm.
> Your data can be as large as you want.
>
> To search for some data:
>
> content = gdbm_fetch ( dbf, key )
>
> Dbf is the pointer returned by gdbm_open. Key is the key
> data.
>
> If the dptr element of the return value is NULL, no data was
> found. Otherwise the return value is a pointer to the found
>
> SunOS 5.10 Last change: 10/15/2002 5
>
> Introduction to Library Functions GDBM(3)
>
> data. The storage space for the dptr element is allocated
> using malloc(3C). Gdbm does not automatically free this
> data. It is the programmer's responsibility to free this
> storage when it is no longer needed.
>
> To search for some data, without retrieving it:
>
> ret = gdbm_exists ( dbf, key )
>
> Dbf is the pointer returned by gdbm_open. Key is the key
> data to search for.
>
> If the key is found within the database, the return value
> ret will be true. If nothing appropiate is found, ret will
> be false. This routine is useful for checking for the exis-
> tance of a record, without performing the memory allocation
> done by gdbm_fetch.
>
> To remove some data from the database:
>
> ret = gdbm_delete ( dbf, key )
>
> Dbf is the pointer returned by gdbm_open. Key is the key
> data.
>
> The return value is -1 if the item is not present or the
> requester is a reader. The return value is 0 if there was a
> successful delete.
>
> The next two routines allow for accessing all items in the
> database. This access is not key sequential, but it is
> guaranteed to visit every key in the database once. (The
> order has to do with the hash values.)
>
> key = gdbm_firstkey ( dbf )
>
> nextkey = gdbm_nextkey ( dbf, key )
>
> Dbf is the pointer returned by gdbm_open. Key is the key
> data.
>
> The return values are both of type datum. If the dptr ele-
> ment of the return value is NULL, there is no first key or
> next key. Again notice that dptr points to data allocated
> by malloc(3C) and gdbm will not free it for you.
>
> These functions were intended to visit the database in
> read-only algorithms, for instance, to validate the database
> or similar operations.
>
> SunOS 5.10 Last change: 10/15/2002 6
>
> Introduction to Library Functions GDBM(3)
>
> File `visiting' is based on a `hash table'. gdbm_delete
> re-arranges the hash table to make sure that any collisions
> in the table do not leave some item `un-findable'. The ori-
> ginal key order is NOT guaranteed to remain unchanged in ALL
> instances. It is possible that some key will not be visited
> if a loop like the following is executed:
>
> key = gdbm_firstkey ( dbf );
> while ( key.dptr ) {
> nextkey = gdbm_nextkey ( dbf, key );
> if ( some condition ) {
> gdbm_delete ( dbf, key );
> free ( key.dptr );
> }
> key = nextkey;
> }
>
> The following routine should be used very infrequently.
>
> ret = gdbm_reorganize ( dbf )
>
> If you have had a lot of deletions and would like to shrink
> the space used by the gdbm file, this routine will reorgan-
> ize the database. Gdbm will not shorten the length of a
> gdbm file except by using this reorganization. (Deleted
> file space will be reused.)
>
> Unless your database was opened with the GDBM_SYNC flag,
> gdbm does not wait for writes to be flushed to the disk
> before continuing. The following routine can be used to
> guarantee that the database is physically written to the
> disk file.
>
> gdbm_sync ( dbf )
>
> It will not return until the disk file state is syncronized
> with the in-memory state of the database.
>
> To convert a gdbm error code into English text, use this
> routine:
>
> ret = gdbm_strerror ( errno )
>
> Where errno is of type gdbm_error, usually the global vari-
> able gdbm_errno. The appropiate phrase is returned.
>
> Gdbm now supports the ability to set certain options on an
> already open database.
>
> SunOS 5.10 Last change: 10/15/2002 7
>
> Introduction to Library Functions GDBM(3)
>
> ret = gdbm_setopt ( dbf, option, value, size )
>
> Where dbf is the return value from a previous call to
> gdbm_open, and option specifies which option to set. The
> valid options are currently:
>
> GDBM_CACHESIZE - Set the size of the internal bucket
> cache. This option may only be set once on each GDBM_FILE
> descriptor, and is set automatically to 100 upon the first
> access to the database.
>
> GDBM_FASTMODE - Set fast mode to either on or off. This
> allows fast mode to be toggled on an already open and
> active database. value (see below) should be set to either
> TRUE or FALSE. This option is now obsolete.
>
> GDBM_SYNCMODE - Turn on or off file system synchronization
> operations.
> This setting defaults to off; value (see below) should be
> set to either
> TRUE or FALSE.
>
> GDBM_CENTFREE - Set central free block pool to either on
> or off.
> The default is off, which is how previous versions of Gdbm
> handled free blocks. If set, this option causes all subse-
> quent free
> blocks to be placed in the global pool, allowing (in
> thoery)
> more file space to be reused more quickly. value (see
> below) should
> be set to either TRUE or FALSE.
> NOTICE: This feature is still under study.
>
> GDBM_COALESCEBLKS - Set free block merging to either on or
> off.
> The default is off, which is how previous versions of Gdbm
> handled free blocks. If set, this option causes adjacent
> free blocks
> to be merged. This can become a CPU expensive process with
> time, though,
> especially if used in conjunction with GDBM_CENTFREE.
> value
> (see below) should be set to either TRUE or FALSE.
> NOTICE: This feature is still under study.
>
> value is the value to set option to, specified as an integer
> pointer. size is the size of the data pointed to by value.
> The return value will be -1 upon failure, or 0 upon success.
> The global variable gdbm_errno will be set upon failure.
>
> For instance, to set a database to use a cache of 10, after
>
> SunOS 5.10 Last change: 10/15/2002 8
>
> Introduction to Library Functions GDBM(3)
>
> opening it with gdbm_open, but prior to accessing it in any
> way, the following code could be used:
>
> int value = 10;
>
> ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value,
> sizeof(int));
>
> If the database was opened with the GDBM_NOLOCK flag, the
> user may wish to perform their own file locking on the data-
> base file in order to prevent multiple writers operating on
> the same file simultaneously.
>
> In order to support this, the gdbm_fdesc routine is pro-
> vided.
>
> ret = gdbm_fdesc ( dbf )
>
> Where dbf is the return value from a previous call to
> gdbm_open. The return value will be the file descriptor of
> the database.
>
> The following two external variables may be useful:
>
> gdbm_errno is the variable that contains more information
> about gdbm errors. (gdbm.h has the definitions of the error
> values and defines gdbm_errno as an external variable.)
> gdbm_version is the string containing the version informa-
> tion.
>
> There are a few more things of interest. First, gdbm files
> are not "sparse". You can copy them with the UNIX cp(1)
> command and they will not expand in the copying process.
> Also, there is a compatibility mode for use with programs
> that already use UNIX dbm. In this compatibility mode, no
> gdbm file pointer is required by the programmer, and only
> one file may be opened at a time. All users in compatibil-
> ity mode are assumed to be writers. If the gdbm file is a
> read only, it will fail as a writer, but will also try to
> open it as a reader. All returned pointers in datum struc-
> tures point to data that gdbm WILL free. They should be
> treated as static pointers (as standard UNIX dbm does).
>
> LINKING
> This library is accessed by specifying -lgdbm as the last
> parameter to the compile line, e.g.:
>
> gcc -o prog prog.c -lgdbm
>
> SunOS 5.10 Last change: 10/15/2002 9
>
> Introduction to Library Functions GDBM(3)
>
> If you wish to use the dbm or ndbm compatibility routines,
> you must link in the gdbm_compat library as well. For exam-
> ple:
>
> gcc -o prog proc.c -lgdbm -lgdbm_compat
>
> BUGS
> SEE ALSO
> dbm, ndbm
>
> AUTHOR
> by Philip A. Nelson and Jason Downs. Copyright (C) 1990 -
> 1999 Free Software Foundation, Inc.
>
> GDBM is free software; you can redistribute it and/or modify
> it under the terms of the GNU General Public License as pub-
> lished by the Free Software Foundation; either version 1, or
> (at your option) any later version.
>
> GDBM is distributed in the hope that it will be useful, but
> WITHOUT ANY WARRANTY; without even the implied warranty of
> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
> the GNU General Public License for more details.
>
> You should have received a copy of the GNU General Public
> License along with GDBM; see the file COPYING. If not,
> write to the Free Software Foundation, 675 Mass Ave, Cam-
> bridge, MA 02139, USA.
>
> You may contact the original author by:
> e-mail: phil at cs.wwu.edu
> us-mail: Philip A. Nelson
> Computer Science Department
> Western Washington University
> Bellingham, WA 98226
>
> You may contact the current maintainer by:
> e-mail: downsj at downsj.com
>
> ATTRIBUTES
> See attributes(5) for descriptions of the following attri-
> butes:
>
> SunOS 5.10 Last change: 10/15/2002 10
>
> Introduction to Library Functions GDBM(3)
>
> _______________________________________
> | ATTRIBUTE TYPE | ATTRIBUTE VALUE|
> |____________________|_________________|
> | Availability | SUNWgnu-dbm |
> |____________________|_________________|
> | Interface Stability| Uncommitted |
> |____________________|_________________|
>
> NOTES
> Source for gdbm is available on http://opensolaris.org.
>
> SunOS 5.10 Last change: 10/15/2002 11
>
>
>
More information about the opensolaris-arc
mailing list