0;The Berkeley DB Package: DB 2.5.9 Change LogI ¨ 2

Berkeley DB 2.5.9 Change Log

2

Interface Additions in Berkeley DB 2.5.9:


    

  1. BA new flag is available in this release for the Berkeley DB cursorGkey/data retrieval interface: DB_NEXT_DUP. This flag causes theADBcursor->c_get routine to return the next duplicate in a list ofDduplicates, and DB_NOTFOUND if there are no additional duplicates toreturn.

  2. BA new flag is available in this release for the Berkeley DB cursorHkey/data retrieval interfaces: DB_GET_BOTH. This flag causes theJDB->get and DBcursor->c_get routines to return success only if bothAthe specified key and data items match the entry in the database.

  3. DA new flag is available in this release for the Berkeley DB key/dataFretrieval interfaces: DB_RMW. This flag causes the DB->get andJDBcursor->c_get routines to acquire write locks instead of read locks whenFdoing the retrieval. Setting this flag may decrease the likelihood ofFdeadlock during a read-modify-write cycle by immediately acquiring theGwrite lock during the read part of the cycle, so that another thread of;control acquiring a read lock for the same item, in its own5read-modify-write cycle, will not result in deadlock.

  4. FA new flag is available in this release: DB_DUPSORT. This flagGcauses duplicate records to be maintained in sorted order. By default,Hthe sort order is the same default lexical sort used by the Btree accessDmethod. A new field, in the DB_INFO structure passed to the db_openGroutine, is available in this release as well: db_compare. ThisGfield is a sort function that is optionally used to sort duplicate dataHitems. It is intended to allow applications to maintain duplicates in anon-standard sort order.

  5. DA new interface is available in this release, DB->join. ThisHinterface takes a set of Berkeley DB cursors as arguments, and returns aJspecialized Berkeley DB cursor whose get function performs a database join0on the records referenced by the set of cursors.

  6. JA new field is available in this release, set in the Berkeley DB structureFreturned by db_open, DB->byteswapped. This field is set if theJunderlying database was not in the native host byte order, and can be usedJby the application to determine if its stored data will require host-ordercleanups before use.

  7. CThe dbmclose() interface has been added to the Berkeley DB dbm/ndbmCcompatibility interface, for application compatibility with the Sun3Microsystems Solaris and other dbm/ndbm interfaces.
0

Interface Changes in Berkeley DB 2.5.9:


    

  1. JPrevious Berkeley DB releases have been inconsistent with respect to which@DBT structure flags may be specified to which Berkeley DBEinterfaces. For example, calling DB->put with the DB_DBT_MALLOC flagIspecified makes no sense, and DB has been inconsistent historically as to7whether this was treated as an error or simply ignored.

    HAs of this release, inappropriate flags in the DBT structure will simplyGbe ignored. This is intended to make it easy to, for example, retrieveDa key/data pair and then use the data DBT as the key DBT for another=database without having to reinitialize the flags in the DBT.

    FPrevious Berkeley DB releases also required that threaded applicationsFalways set the DB_DBT_MALLOC or DB_DBT_USERMEM flags in DBT structures?when retrieving key/data items. As of this release, specifyingJDB_DBT_MALLOC or DB_DBT_USERMEM is only required when using the non-cursorCDB interfaces (e.g., DB->get). When using cursor interfaces (e.g.,DDBcursor->c_get), the flags are not required, as memory in which theGkey/data items are returned is allocated and maintained on a per-cursorbasis.

  2. DBerkeley DB log files are now named log.XXXXXXXXXX instead ofHlog.XXXXX, in order to ensure that applications do not run out oflog file name space.

    IThis change is transparent to applications, but may NOT be transparent to"local shell scripts and utilities.

  3. IPrevious Berkeley DB releases returned statistics for the Btree databasesHthat were only valid for the lifetime of the handle with which they wereGrequested, i.e., these statistics as returned for a particular BerkeleyIDB handle would only reflect database operations done by that Berkeley DB*handle and any cursors associated with it.

    BThe following statistics have been removed from the returned Btree>statistical information: bt_freed, bt_pfxsaved,:bt_split, bt_rootsplit, bt_fastsplit,Gbt_added, bt_deleted, bt_get, bt_cache_hit,Abt_cache_miss. If any of these are sufficiently useful toHapplication writers that they should be put back into the system, please let us know.

    /This change is NOT transparent to applications.

  4. EPrevious Berkeley DB releases did not support embedded white space inCBerkeley DB environment configuration strings. As of this release,Cconfiguration NAME/VALUE strings are still separated by one or moreEwhitespace characters (which are discarded), but the VALUE string mayDcontain embedded whitespace characters and is terminated by trailingEwhitespace characters and a newline character, both of which are alsoGdiscarded. In addition, empty lines and lines whose first character is=a whitespace or hash (#) character, in the Berkeley DB"configuration, file are discarded.

    ;This change is potentially NOT transparent to applications.

  5. GThe DB_REGION_INIT flag to the db_value_set interface has been enhancedEto write a byte to each page in the region. This allows applicationsGto use DB_REGION_INIT to ensure that there is sufficient disk space forthe backing region file.
*

Berkeley DB Environment failures:

r

Documentation Changes:

D
    

  1. iEThe Berkeley DB documentation has been completely reworked. It is noeFlonger available in flat text, UNIX roff or PostScript formats, but isAnow only available in HTML format. To use the Berkeley DB Ddocumentation, point your browser to the Berkeley DB distribution orEinstallation directory db-2.5.9/docs/index.html. This releasetHalso includes the beginnings of the Berkeley DB Reference Guide, as wellas the manual pages.
a(

B+tree Access Method Bug Fixes:


    

  1. hJCursor delete operations were not necessarily being undone after deadlock,&potentially leading to incorrect data.

  2. uADeleted, off-page duplicate items could be recovered incorrectly,e&potentially leading to incorrect data.

  3. d@Log records could be written outside of a transaction under someJcircumstances, potentially corrupting the log so that recovery would fail.

  4. uFCompletely emptying large trees could cause corruption of the database)root page during the final reverse split.

  5. gIFailure during page split could leave cursors referencing incorrect data.a

  6. tHRetrieving records based on logical record number could return incorrect?data if logically adjacent records had previously been deleted.e

  7. D@The Btree access method is more aggressive in this release aboutIdiscarding locks within transactions that are not needed for correctness.aHThis change significantly decreases the probability of deadlock for some applications.s
a&

Hash Access Method Bug Fixes:


    

  1. eFStoring duplicate data items using the DB_CURRENT flag could result inincorrect data.f

  2. BDCursors and their locks did not always return unchanged on operationfailure.

  3. fFEntering a sufficient number of duplicate data items into the databaseIcould result in incorrect cursor positioning and/or a corrupted database.B
e'

Recno Access Method Bug Fixes:

b
    

  1. eGThe logical record number returned from DB_APPEND calls was stored intoc9library memory instead of into the user-specified memory.a

  2. uJThe memory in which the backing source file name was stored could be freed=multiple times, potentially leading to application core dump.f
a)

General Access Method Bug Fixes:

s
    

  1. oGIncorrectly treated setting the database cachesize in the presence of a FBerkeley DB environment to be an error, even if the environment didn't+not initialize a shared memory buffer pool.T

  2. /FUsing the DBcursor->c_get interface with the DB_KEYFIRST or DB_KEYLAST7flags to insert a new key into the database would fail. 

  3. nHIn previous Berkeley DB releases each cursor operation (when not part ofIa transaction) potentially used a different locker ID, making it possibletHfor cursor operations to lock against themselves. In the 2.5.9 release,Gthe cursor locker ID is maintained for the life of the cursor, instead.e

  4. sGThe optional user-specified transaction recovery function was not beinggBcalled during Berkeley DB recovery, and when using the db_printlogutility.

  5. oJPages of duplicate data items were incorrectly split and logged/recovered,+potentially leading to database corruption.e

  6. iEDuring recovery, deleted database files could cause recovery to fail. 
r&

C++ API Changes and Bug Fixes


    

  1. sFA DbEnv::version method has been added to allow access to major, minor*and patch numbers for the current version.

  2. iEThe DbEnv class has been cleaned up so that inappropriate get and set methods have been removed:

    n

    v

    fBThese methods are unneeded because the constructor with arguments,=or the appinit() method, can be used to set this information.n

    o

    f

    nIThese get methods accessed information that was never set by Berkeley DB.y

  3. eHRemaining DbEnv::set_* methods may throw an exception if they are calledEafter the environment has been initialized (either via appinit or theoconstructor with arguments).

  4. lDThe DbInfo class has been reworked so that inappropriate get methodsChave been removed. These get methods accessed information that wassnever set by Berkeley DB.d

    d

    

    tCMethods to get and set underlying lock identifiers in a DbLock have Dbeen removed, as lock identifiers should be completely opaque to the application.

o'

Java API Changes and Bug Fixes


    

  1. c:The DB_SET_RANGE flag did not correctly return data items.

  2. nIDb.stat() is now declared to return an Object. The object returned is ofDCtype DbBtreeStat if the file was created using Db.DB_BTREE. In the 7future, this will return other types, e.g., DbHashStat.d

    eLThe DbBtreeStat, DbLockStat, DbMpoolFStat, DbMpoolStat and DbTxnStat classesJhave been changed to allow direct access to their data members. DbLogStatis a new class. 

  3. tCThe DbEnv class has been reworked and all inappropriate get and setamethods have been removed:

    g

    P

    wIThese methods are unneeded because the constructor with arguments, or the 6appinit() method, can be used to set this information.

    h

    R

    oBThese get methods used to access information that was never set by Berkeley DB.

    sGThe DbEnv.get_java_version_string method has been removed, and the JavapDpart of Berkeley DB no longer maintains its own version information.

  4. wHRemaining DbEnv.set_* methods may throw a DbException if they are calledEafter the environment has been initialized (either via appinit or thenconstructor with arguments).

  5. DThe DbInfo class has been reworked so that inappropriate get methodsEhave been removed. These get methods used to access information thatawas never set by Berkeley DB. 

    r

    

  6. CMethods to get and set underlying lock identifiers in a DbLock have Dbeen removed, as lock identifiers should be completely opaque to the application.

  7. e@The DbRunRecoveryException class has been added as a subclass ofCDbException. A DbRunRecoveryException object will be thrown when asFfatal error occurs in Berkeley DB, requiring recovery to be performed.
o7

Shared Memory Buffer Pool Subsystem Bug Fixes:

n
    

  1. yJIt was possible for threads opening and closing databases in a fairly full?buffer cache to free memory that was still in use, resulting ineapplication failure.

  2. EIf the memp_trickle() interface was unable to find a single buffer torGflush in the entire buffer list, it would return with the shared memorycregion mutex locked.

  3. ,BOpening underlying files of certain sizes in the buffer pool wouldincorrectly fail.r
.%

Locking Subsystem Bug Fixes:

n
    

  1. aGIf the a locker being forced to wait does not currently hold any locks,e'the deadlock detector is no longer run.y
%

Logging Subsystem Bug Fixes:


    

  1. HIf the first log get call after database recovery used the DB_NEXT flag,it would fail.

  2. nCIf databases were opened multiple times without intervening closes,erecovery could fail.

  3. t:A memory leak in the log_archive interface has been fixed.


Additional Bug Fixes:


    

  1. iHWindows/NT: using shared anonymous memory did not work correctly betweenprocesses sharing the database.g

  2. nEUtilities: Signal handling and Berkeley DB region exit was incorrect./JAmong other issues, the db_load utility could exit holding a region mutex.

  3. aGDbm/Ndbm: System error values were not always being correctly returned.p
u4

System Porting and Build Procedure Changes:


    

  1. .=A alpha-release port to VMS has been added to the Berkeley DBe<distribution. The port has not yet run the Berkeley DB test'suite, but there are no known problems.l

  2. eIBerkeley DB now uses the pstat_getdynamic(2) interface on Hewlett-Packardn<HP/UX systems to detect the presence of multiple processors.

  3. eAFor performance reasons, the Berkeley DB release now uses the SunhDMicrosystems Solaris pread(2) and pwrite(2) UNIX interfaces, if theyare available.

  4. oDBerkeley DB now compiles with the -D_THREAD_SAFE C preprocessor flagDand loads with the libc_r.a C library by default on FreeBSD systems.

  5. eHFor portability reasons, shared memory segments allocated using the UNIXIshmget(2) function are now allocated as IPC_PRIVATE. (Apparently, markingiDthem as IPC_PRIVATE does not affect that they are available to other processes.)o

  6. eBThe standard UNIX install for the Berkeley DB library now installsABerkeley DB into its own hierarchy instead of into separate localo4directories. By default, the install locations are:

    l  I u *  e.  y*  m+ ,# re
    LocationContents
    /usr/local/BerkeleyDB/binbinaries
    /usr/local/BerkeleyDB/includeinclude files
    /usr/local/BerkeleyDB/liblibraries
    /usr/local/BerkeleyDB/docsHTML documentation
    

  7. rIFor portability reasons, the standard UNIX Berkeley DB library archive isAbuilt with the -cr options in this release, instead of the:&-cq options as done previously.

  8. aIThe standard UNIX Berkeley DB configuration will now automatically detectn-and use gcc if no compiler named cc is found.t

  9. e@When the C pre-processor DIAGNOSTIC value is #defined, memory is:overwritten with a 0xdb pattern instead of a 0xff pattern.
a$

Additional Changes: db_dump


    

  1. :DThe db_dump utility has a new option, -N. This option allowsDdb_dump to be run without acquiring any shared region mutexes. This*option is intended for debugging use only.

  2. HThe db_dump utility now allows a Berkeley DB environment directory to beCspecified (the -h option) at the same time as the "debugging&output" option (the -d option).

  3. >FThe db_dump utility now uses the shared memory buffer pool region if aIBerkeley DB environment directory is specified, which allows users to seetIthe current state of the database instead of only the database state thatt!has already been flushed to disk.e
nibÿÿv::get_tx_max
cDbEnv::get_tx_recover
iDbEnv::get_verbose
f

nIThese get methods accessed information that was never set by Berkeley DB.y

  • eHRemaining DbEnv::set_* methods may throw an exception if they are calledEafter the environment has been initialized (either via appinit or theoconstructor with arguments).

  • lDThe DbInfo class has been reworked so that inappropriate g