brian 99/03/03 12:39:34
Modified: src/support dbmmanage.1 Log: Scratching an itch... documenting the difference between different DBM files in an attempt to stave off some support questions. Revision Changes Path 1.6 +48 -1 apache-1.3/src/support/dbmmanage.1 Index: dbmmanage.1 =================================================================== RCS file: /home/cvs/apache-1.3/src/support/dbmmanage.1,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- dbmmanage.1 1999/01/01 19:05:33 1.5 +++ dbmmanage.1 1999/03/03 20:39:33 1.6 @@ -86,7 +86,8 @@ found at http://www.apache.org/. .SH OPTIONS .IP \fB\fIfilename\fP -The filename of the DBM format file. Usually without the extension .pag or .dir. +The filename of the DBM format file. Usually without the +extension .db, .pag, or .dir. .IP \fB\fIcommand\fP This selects the operation to perform: .TP 12 @@ -118,6 +119,52 @@ Just displays the complete contents of the DBM file. .IP \fB\fIusername\fP The user for which the update operation is performed. +.PD +.SH BUGS +.PP +One should be aware that there are a number of different DBM file +formats in existance, and with all likelihood, libraries for more than +one format may exist on your system. The three primary examples are +NDBM, the GNU project's GDBM, and Berkeley DB 2. Unfortunately, all +these libraries use different file formats, and you must make sure +that the file format used by +.I filename +is the same format that +.B dbmmanage +expects to see. +.B dbmmanage +currently has no way of determining what type of DBM file it is +looking at. If used against the wrong format, +.dbmmanage +will simply return nothing, or may create a different DBM file with a +different name, or at worst, it may corrupt the DBM file if you were +attempting to write to it. +.PP +.B dbmmanage +has a list of DBM format preferences, defined by the +.B @AnyDBM::ISA +array near the beginning of the program. Since we prefer the Berkeley +DB 2 file format, the order in which +.B dbmmanage +will look for system libraries is Berkeley DB 2, then NDBM, and then +GDBM. The first library found will be the library +.B dbmmanage +will attempt to use for all DBM file transactions. This ordering is +slightly different than the standard +.B @AnyDBM::ISA +ordering in perl, as well as the ordering used by the simple dbmopen() +call in Perl, so if you use any other utilities to manage your DBM +files, they must also follow this preference ordering. Similar care +must be taken if using programs in other languages, like C, to +access these files. +.PP +Apache's +.B mod_auth_db.c +module corresponds to Berkeley DB 2 library, while +.B mod_auth_dbm.c +corresponds to the NDBM library. Also, one can usually use the +.B file +program supplied with most Unix systems to see what format a DBM file is in. .PD .SH SEE ALSO .BR httpd(8)
