-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Berkeley DB binding
--   
--   This package provides a Haskell binding for Berkeley DB, which is a
--   fast, scalable, fully transactional database that runs on a local file
--   system, and functions as a dictionary of arbitrary-sized binary blobs.
--   It is NOT an SQL-based database. It is not free for commercial use.
--   
--   This is a work in progress: The coverage of the Berkeley DB API is not
--   yet complete. Tested with Berkeley DB versions 4.7 and 4.8, but should
--   work with earlier versions.
--   
--   Berkeley DB home page:
--   <a>http://www.oracle.com/database/berkeley-db/index.html</a>
--   
--   Haskell binding tutorial:
--   <a>http://www.haskell.org/haskellwiki/BerkeleyDBXML</a>
--   
--   DARCS repository: <a>http://code.haskell.org/BerkeleyDB/</a>
--   
--   Changes: 0.8: Support db4.7 and db4.8, removed C++ binding. 0.7.2: Fix
--   on db4.7
@package BerkeleyDB
@version 0.8.4


-- | Berkeley DB binding. All IO monad functions can throw DbException.
--   
--   This documentation is not a complete description of the Berkeley DB
--   interface. You will need to refer to Berkeley DB's C or C++ API
--   documentation for the details.
module Database.Berkeley.Db
data DbFlag
DB_CREATE :: DbFlag
DB_DURABLE_UNKNOWN :: DbFlag
DB_FORCE :: DbFlag
DB_MULTIVERSION :: DbFlag
DB_NOMMAP :: DbFlag
DB_RDONLY :: DbFlag
DB_RECOVER :: DbFlag
DB_THREAD :: DbFlag
DB_TRUNCATE :: DbFlag
DB_TXN_NOSYNC :: DbFlag
DB_TXN_NOWAIT :: DbFlag
DB_TXN_NOT_DURABLE :: DbFlag
DB_TXN_WRITE_NOSYNC :: DbFlag
DB_TXN_SYNC :: DbFlag
DB_TXN_WAIT :: DbFlag
DB_IGNORE_LEASE :: DbFlag
DB_AUTO_COMMIT :: DbFlag
DB_READ_COMMITTED :: DbFlag
DB_DEGREE_2 :: DbFlag
DB_READ_UNCOMMITTED :: DbFlag
DB_DIRTY_READ :: DbFlag
DB_TXN_SNAPSHOT :: DbFlag
DB_CXX_NO_EXCEPTIONS :: DbFlag
DB_USE_ENVIRON :: DbFlag
DB_USE_ENVIRON_ROOT :: DbFlag
DB_INIT_CDB :: DbFlag
DB_INIT_LOCK :: DbFlag
DB_INIT_LOG :: DbFlag
DB_INIT_MPOOL :: DbFlag
DB_INIT_REP :: DbFlag
DB_INIT_TXN :: DbFlag
DB_LOCKDOWN :: DbFlag
DB_PRIVATE :: DbFlag
DB_RECOVER_FATAL :: DbFlag
DB_REGISTER :: DbFlag
DB_SYSTEM_MEM :: DbFlag
DB_EXCL :: DbFlag
DB_FCNTL_LOCKING :: DbFlag
DB_NO_AUTO_COMMIT :: DbFlag
DB_RDWRMASTER :: DbFlag
DB_WRITEOPEN :: DbFlag
DB_MULTIPLE :: DbFlag
DB_MULTIPLE_KEY :: DbFlag
DB_RMW :: DbFlag
DB_LOCK_NOWAIT :: DbFlag
DB_AFTER :: DbFlag
DB_APPEND :: DbFlag
DB_BEFORE :: DbFlag
DB_CONSUME :: DbFlag
DB_CONSUME_WAIT :: DbFlag
DB_CURRENT :: DbFlag
DB_FIRST :: DbFlag
DB_GET_BOTH :: DbFlag
DB_GET_BOTHC :: DbFlag
DB_GET_BOTH_RANGE :: DbFlag
DB_GET_RECNO :: DbFlag
DB_JOIN_ITEM :: DbFlag
DB_KEYFIRST :: DbFlag
DB_KEYLAST :: DbFlag
DB_LAST :: DbFlag
DB_NEXT :: DbFlag
DB_NEXT_DUP :: DbFlag
DB_NEXT_NODUP :: DbFlag
DB_NODUPDATA :: DbFlag
DB_NOOVERWRITE :: DbFlag
DB_NOSYNC :: DbFlag
DB_POSITION :: DbFlag
DB_PREV :: DbFlag
DB_PREV_DUP :: DbFlag
DB_PREV_NODUP :: DbFlag
DB_SET :: DbFlag
DB_SET_RANGE :: DbFlag
DB_SET_RECNO :: DbFlag
DB_UPDATE_SECONDARY :: DbFlag
DB_WRITECURSOR :: DbFlag
DB_WRITELOCK :: DbFlag
DB_DUP :: DbFlag
DB_DUPSORT :: DbFlag
data DbError

-- | User memory too small for return.
DB_BUFFER_SMALL :: DbError

-- | "Null" return from 2ndary callbk.
DB_DONOTINDEX :: DbError

-- | Key/data deleted or never created.
DB_KEYEMPTY :: DbError

-- | The key/data pair already exists.
DB_KEYEXIST :: DbError

-- | Deadlock.
DB_LOCK_DEADLOCK :: DbError

-- | Lock unavailable.
DB_LOCK_NOTGRANTED :: DbError

-- | In-memory log buffer full.
DB_LOG_BUFFER_FULL :: DbError

-- | Server panic return.
DB_NOSERVER :: DbError

-- | Bad home sent to server.
DB_NOSERVER_HOME :: DbError

-- | Bad ID sent to server.
DB_NOSERVER_ID :: DbError

-- | Key/data pair not found (EOF).
DB_NOTFOUND :: DbError

-- | Out-of-date version.
DB_OLD_VERSION :: DbError

-- | Requested page not found.
DB_PAGE_NOTFOUND :: DbError

-- | There are two masters.
DB_REP_DUPMASTER :: DbError

-- | Rolled back a commit.
DB_REP_HANDLE_DEAD :: DbError

-- | Time to hold an election.
DB_REP_HOLDELECTION :: DbError

-- | This msg should be ignored.
DB_REP_IGNORE :: DbError

-- | Cached not written perm written.
DB_REP_ISPERM :: DbError

-- | Unable to join replication group.
DB_REP_JOIN_FAILURE :: DbError

-- | Master lease has expired.
DB_REP_LEASE_EXPIRED :: DbError

-- | API/Replication lockout now.
DB_REP_LOCKOUT :: DbError

-- | New site entered system.
DB_REP_NEWSITE :: DbError

-- | Permanent log record not written.
DB_REP_NOTPERM :: DbError

-- | Site cannot currently be reached.
DB_REP_UNAVAIL :: DbError

-- | Panic return.
DB_RUNRECOVERY :: DbError

-- | Secondary index corrupt.
DB_SECONDARY_BAD :: DbError

-- | Verify failed; bad format.
DB_VERIFY_BAD :: DbError

-- | Environment version mismatch.
DB_VERSION_MISMATCH :: DbError

-- | Haskell binding: Attempted to use a DbEnv handle after it was closed
DB_ACCESSED_DB_ENV_AFTER_CLOSE :: DbError

-- | Haskell binding: Attempted to use a Db handle after it was closed
DB_ACCESSED_DB_AFTER_CLOSE :: DbError

-- | Haskell binding: Attempted to use a DbTxn handle after it was closed
DB_ACCESSED_DB_TXN_AFTER_CLOSE :: DbError

-- | Haskell binding: Attempted to use a DbCursor handle after it was
--   closed
DB_ACCESSED_DB_CURSOR_AFTER_CLOSE :: DbError

-- | An errno value returned by the operating system
SYSTEM_ERROR :: Int -> DbError

-- | An exception indicating an error in a Berkeley DB operation.
data DbException
DbException :: String -> DbError -> DbException
type DbEnv = ForeignPtr DbEnv_struct

-- | Close the Berkeley DB environment.
dbEnv_close :: [DbFlag] -> DbEnv -> IO ()
data DbEnvCreateFlag

-- | Create a Berkeley DB environment handle.
dbEnv_create :: [DbEnvCreateFlag] -> IO DbEnv
dbEnv_set_data_dir :: DbEnv -> FilePath -> IO ()
dbEnv_set_lg_dir :: DbEnv -> FilePath -> IO ()
dbEnv_get_cache_size :: DbEnv -> IO (Int, Int, Int)
dbEnv_get_lk_max_lockers :: DbEnv -> IO Int
dbEnv_get_lk_max_locks :: DbEnv -> IO Int
dbEnv_get_lk_max_objects :: DbEnv -> IO Int
dbEnv_get_tx_max :: DbEnv -> IO Int
type DbLock = ForeignPtr DbLock_struct
data DbLocker
data DbLockMode
DB_LOCK_READ :: DbLockMode
DB_LOCK_WRITE :: DbLockMode
DB_LOCK_IWRITE :: DbLockMode
DB_LOCK_IREAD :: DbLockMode
DB_LOCK_IWR :: DbLockMode

-- | Acquire a DbLock. <a>dbTxn_id</a> converts a DbTxn to a DbLocker.
dbEnv_lock_get :: [DbFlag] -> DbLockMode -> ByteString -> DbEnv -> DbLocker -> IO DbLock

-- | Release a DbLock acquired by dbEnv_lock_get.
dbEnv_lock_put :: DbLock -> IO ()

-- | Wrap dbEnv_lock_get / dbEnv_lock_put around the specified computation.
--   <a>dbTxn_id</a> converts a DbTxn to a DbLocker.
dbEnv_withLock :: [DbFlag] -> DbLockMode -> ByteString -> DbEnv -> DbLocker -> IO a -> IO a

-- | Open the Berkeley DB environment, which must be done before
--   <a>db_open</a>.
dbEnv_open :: [DbFlag] -> Int -> DbEnv -> FilePath -> IO ()
dbEnv_set_cache_size :: DbEnv -> Int -> Int -> Int -> IO ()
data DbLockFlag
DB_LOCK_NORUN :: DbLockFlag
DB_LOCK_DEFAULT :: DbLockFlag
DB_LOCK_EXPIRE :: DbLockFlag
DB_LOCK_MAXLOCKS :: DbLockFlag
DB_LOCK_MAXWRITE :: DbLockFlag
DB_LOCK_MINLOCKS :: DbLockFlag
DB_LOCK_MINWRITE :: DbLockFlag
DB_LOCK_OLDEST :: DbLockFlag
DB_LOCK_RANDOM :: DbLockFlag
DB_LOCK_YOUNGEST :: DbLockFlag

-- | Start the Berkeley DB lock detector.
dbEnv_set_lk_detect :: DbEnv -> DbLockFlag -> IO ()
dbEnv_set_lk_max_lockers :: DbEnv -> Int -> IO ()
dbEnv_set_lk_max_locks :: DbEnv -> Int -> IO ()
dbEnv_set_lk_max_objects :: DbEnv -> Int -> IO ()
dbEnv_set_tx_max :: DbEnv -> Int -> IO ()

-- | Checkpoint the transaction subsystem.
dbEnv_txn_checkpoint :: [DbFlag] -> DbEnv -> Word -> Word -> IO ()
dbEnv_set_flags :: DbEnv -> [DbFlag] -> Bool -> IO ()

-- | An exception-safe helper that runs an action inside a transaction. It
--   will commit on completion, or abort if an exception is thrown.
dbEnv_withTxn :: [DbFlag] -> [DbFlag] -> DbEnv -> Maybe DbTxn -> (DbTxn -> IO a) -> IO a

-- | Create a new transaction. You are recommended to use
--   <a>dbEnv_withTxn</a> instead of this function.
dbEnv_txn_begin :: [DbFlag] -> DbEnv -> Maybe DbTxn -> IO DbTxn
type DbTxn = ForeignPtr DbTxn_struct

-- | Abort a transaction, rolling back any writes that were made. You are
--   recommended to use <a>dbEnv_withTxn</a> instead of this function.
dbTxn_abort :: DbTxn -> IO ()

-- | Commit a transaction. You are recommended to use <a>dbEnv_withTxn</a>
--   instead of this function.
dbTxn_commit :: [DbFlag] -> DbTxn -> IO ()

-- | Get the locker ID for a transaction, which can be used with
--   <a>dbEnv_withLock</a>.
dbTxn_id :: DbTxn -> IO DbLocker
type Db = ForeignPtr Db_struct

-- | Create a database handle.
db_create :: [DbFlag] -> DbEnv -> IO Db
db_del :: [DbFlag] -> Db -> Maybe DbTxn -> ByteString -> IO ()

-- | Look the key up in the database, and return Just the stored value, or
--   Nothing if it was not found.
db_get :: [DbFlag] -> Db -> Maybe DbTxn -> ByteString -> IO (Maybe ByteString)
data DbType
DB_BTREE :: DbType
DB_HASH :: DbType
DB_RECNO :: DbType
DB_QUEUE :: DbType
DB_UNKNOWN :: DbType

-- | Open a database.
db_open :: [DbFlag] -> DbType -> Int -> Db -> Maybe DbTxn -> FilePath -> Maybe String -> IO ()
db_close :: [DbFlag] -> Db -> IO ()
db_set_flags :: [DbFlag] -> Db -> IO ()

-- | Store the specified value into the database under the specified key.
db_put :: [DbFlag] -> Db -> Maybe DbTxn -> ByteString -> ByteString -> IO ()
db_set_pagesize :: Db -> Int -> IO ()

-- | An exception-safe helper that creates a cursor, passes it to an
--   action, and cleans up afterwards.
db_withCursor :: [DbFlag] -> Db -> Maybe DbTxn -> (DbCursor -> IO a) -> IO a

-- | Open a DbCursor. You are recommended to use <a>db_withCursor</a>
--   instead of this function.
db_cursor :: [DbFlag] -> Db -> Maybe DbTxn -> IO DbCursor
type DbCursor = ForeignPtr DbCursor_struct

-- | Close a DBCursor. You are recommended to use <a>db_withCursor</a>
--   instead of this function.
dbCursor_close :: DbCursor -> IO ()

-- | Count the number of duplicates at the cursor position.
dbCursor_count :: [DbFlag] -> DbCursor -> IO Int

-- | Delete the record at the cursor position.
dbCursor_del :: [DbFlag] -> DbCursor -> IO ()

-- | An exception-safe helper that duplicates a cursor using
--   <a>dbCursor_dup</a>, passes it to an action, and cleans up afterwards.
dbCursor_withCursor :: [DbFlag] -> DbCursor -> (DbCursor -> IO a) -> IO a

-- | Create a duplicate of the specified cursor.
dbCursor_dup :: [DbFlag] -> DbCursor -> IO DbCursor

-- | Fetch the record pointed at by the cursor (modified by the flags - see
--   the Berkeley DB documentation), and return Just the (key, value) pair
--   at the cursor position, or Nothing if no record was found.
dbCursor_get :: [DbFlag] -> DbCursor -> IO (Maybe (ByteString, ByteString))

-- | Move the cursor to the specified key/data pair of the database, and
--   return the datum associated with the given key, or Nothing if it
--   wasn't matched. (This is DBC-&gt;get with the DB_SET flag. The DB_SET
--   flag is implied.)
dbCursor_set :: [DbFlag] -> DbCursor -> ByteString -> IO (Maybe ByteString)

-- | stores key/data pairs into the database in the context of the cursor.
dbCursor_put :: [DbFlag] -> DbCursor -> ByteString -> ByteString -> IO ()
data DbLogFlag
DB_LOG_DIRECT :: DbLogFlag
DB_LOG_DSYNC :: DbLogFlag
DB_LOG_AUTO_REMOVE :: DbLogFlag
DB_LOG_IN_MEMORY :: DbLogFlag
DB_LOG_ZERO :: DbLogFlag
dbEnv_log_set_config :: DbEnv -> [DbLogFlag] -> Bool -> IO ()
dbEnv_get_lg_regionmax :: DbEnv -> IO Int
dbEnv_set_lg_regionmax :: DbEnv -> Int -> IO ()

-- | Needed for BerkeleyDBXML: Binary representation of a DbFlag
dbToNum :: DbFlag -> Word32

-- | Needed for BerkeleyDBXML: Convert an error code to a DbError
dbErrFromNum :: Int -> DbError

-- | Needed for BerkeleyDBXML: C pointer type for a DbEnv
data DbEnv_struct

-- | Needed for BerkeleyDBXML: C pointer type for a DbTxn
data DbTxn_struct
data DbEnv_native

-- | Convert the Haskell handle into a native handle of type DB_ENV* which
--   can be passed to C.
dbEnv_toNative :: DbEnv -> (Ptr DbEnv_native -> IO a) -> IO a
instance Typeable DbException
instance Eq DbError
instance Show DbError
instance Eq DbException
instance Show DbException
instance Exception DbException