Date: Thu, 1 Mar 2001 14:37:44 +0900
   Posted: Thu, 01 Mar 2001 14:37:43 +0900
   From: matz / zetabits.com (Yukihiro Matsumoto)
   Reply-To: ruby-talk / ruby-lang.org

   In message "[ruby-talk:11815] problems with DBM module"
       on 01/03/01, Eric Sven Ristad <ristad / mnemonic.com> writes:

   |1. DBM module is inconsistent with Ruby design

   might be.  let me consider this.

My claim is incorrect.  The problem is not in the design of the DBM
module, but in the documentation.  There are really two different
types of modes and the documentation does not distinguish them.

1. The access permissions on a file 
   C type "mode_t mode", an octal number (eg., octal 0666 = symbolic a+rw)
2. How the file is opened and what operations are allowed
   eg., read-only, read-write, append, etc.

This confusion is compounded because the C language prototype
     dbm_open(const char *file, int flags, mode_t mode)
takes both kinds of mode arguments whereas the Ruby language method
     DBM.open(dbname[, mode])
only takes one mode argument (the access permissions) and the reader
is left to guess which kind of mode it is.

The cleanest easy solution may be to rename the first type of "mode"
to be "access", as in "File.chmod(access, path, file)" and
"DBM.open(dbname[, access])".  Then the Ruby documentation would
explain that arguments named "access" are octal integers that control
the access permissions on the file, while arguments named "mode" are
character strings (eg., "r+") that control the file operations.

Eric