subversion/libsvn_fs_base/bdb/dbt.h

   1 /* dbt.h --- interface to DBT-frobbing functions
   2  *
   3  * ====================================================================
   4  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
   5  *
   6  * This software is licensed as described in the file COPYING, which
   7  * you should have received as part of this distribution.  The terms
   8  * are also available at http://subversion.tigris.org/license-1.html.
   9  * If newer versions of this license are posted there, you may use a
  10  * newer version instead, at your option.
  11  *
  12  * This software consists of voluntary contributions made by many
  13  * individuals.  For exact contribution history, see the revision
  14  * history and logs, available at http://subversion.tigris.org/.
  15  * ====================================================================
  16  */
  17
  18 #ifndef SVN_LIBSVN_FS_DBT_H
  19 #define SVN_LIBSVN_FS_DBT_H
  20
  21 #include <apr_pools.h>
  22
  23 #define APU_WANT_DB
  24 #include <apu_want.h>
  25
  26 #include "svn_fs.h"
  27 #include "../util/skel.h"
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif /* __cplusplus */
  32
  33 \f
  34 /* Set all fields of DBT to zero.  Return DBT.  */
  35 DBT *svn_fs_base__clear_dbt(DBT *dbt);
  36
  37
  38 /* Set DBT to retrieve no data.  This is useful when you're just
  39    probing the table to see if an entry exists, or to find a key, but
  40    don't care what the value is.  Return DBT.  */
  41 DBT *svn_fs_base__nodata_dbt(DBT *dbt);
  42
  43
  44 /* Set DBT to refer to the SIZE bytes at DATA.  Return DBT.  */
  45 DBT *svn_fs_base__set_dbt(DBT *dbt, const void *data, u_int32_t size);
  46
  47
  48 /* Prepare DBT to hold data returned from Berkeley DB.  Return DBT.
  49
  50    Clear all its fields to zero, but set the DB_DBT_MALLOC flag,
  51    requesting that Berkeley DB place the returned data in a freshly
  52    malloc'd block.  If the database operation succeeds, the caller
  53    then owns the data block, and is responsible for making sure it
  54    gets freed.
  55
  56    You can use this with svn_fs_base__track_dbt:
  57
  58        svn_fs_base__result_dbt (&foo);
  59        ... some Berkeley DB operation that puts data in foo ...
  60        svn_fs_base__track_dbt (&foo, pool);
  61
  62    This arrangement is:
  63    - thread-safe --- the returned data is allocated via malloc, and
  64      won't be overwritten if some other thread performs an operation
  65      on the same table.  See the explanation of ``Retrieved key/data
  66      permanence'' in the section of the Berkeley DB manual on the DBT
  67      type.
  68    - pool-friendly --- the data returned by Berkeley DB is now guaranteed
  69      to be freed when POOL is cleared.  */
  70 DBT *svn_fs_base__result_dbt(DBT *dbt);
  71
  72 /* Arrange for POOL to `track' DBT's data: when POOL is cleared,
  73    DBT->data will be freed, using `free'.  If DBT->data is zero,
  74    do nothing.
  75
  76    This is meant for use with svn_fs_base__result_dbt; see the explanation
  77    there.  */
  78 DBT *svn_fs_base__track_dbt(DBT *dbt, apr_pool_t *pool);
  79
  80
  81 /* Prepare DBT for use as a key into a RECNO table.  This call makes
  82    DBT refer to the db_recno_t pointed to by RECNO as its buffer; the
  83    record number you assign to *RECNO will be the table key.  */
  84 DBT *svn_fs_base__recno_dbt(DBT *dbt, db_recno_t *recno);
  85
  86
  87 /* Compare two DBT values in byte-by-byte lexicographic order.  */
  88 int svn_fs_base__compare_dbt(const DBT *a, const DBT *b);
  89
  90
  91 /* Set DBT to the unparsed form of ID; allocate memory from POOL.
  92    Return DBT.  */
  93 DBT *svn_fs_base__id_to_dbt(DBT *dbt, const svn_fs_id_t *id,
  94                             apr_pool_t *pool);
  95
  96
  97 /* Set DBT to the unparsed form of SKEL; allocate memory from POOL.
  98    Return DBT.  */
  99 DBT *svn_fs_base__skel_to_dbt(DBT *dbt, skel_t *skel, apr_pool_t *pool);
 100
 101
 102 /* Set DBT to the text of the null-terminated string STR.  DBT will
 103    refer to STR's storage.  Return DBT.  */
 104 DBT *svn_fs_base__str_to_dbt(DBT *dbt, const char *str);
 105
 106
 107 #ifdef __cplusplus
 108 }
 109 #endif /* __cplusplus */
 110
 111 #endif /* SVN_LIBSVN_FS_DBT_H */