git.ozlabs.org Git - ccan/blob - ccan/ntdb/man/ntdb.3.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   3 <refentry>
   4   <refmeta>
   5     <refentrytitle>ntdb</refentrytitle>
   6     <manvolnum>3</manvolnum>
   7     <refmiscinfo class="source">Samba</refmiscinfo>
   8     <refmiscinfo class="manual">System Administration tools</refmiscinfo>
   9     <refmiscinfo class="version">4.1</refmiscinfo>
  10   </refmeta>
  11   <refnamediv>
  12     <refname>ntdb</refname>
  13 <refpurpose>A not-so trivial keyword/data database system</refpurpose>
  14   </refnamediv>
  15   <refsynopsisdiv>
  16 <synopsis>#include &lt;ntdb.h&gt;</synopsis>
  17   </refsynopsisdiv>
  18   <refsect1><title>DESCRIPTION</title>
  19     <para>
  20       If you have previously used the tdb library from Samba, much of
  21       this will seem familiar, but there are some API changes which a
  22       compiler will warn you about if you simply replace 'tdb' with
  23       'ntdb' in your code!  The on-disk format for ntdb is
  24       incompatible with tdb.
  25     </para>
  26     <para>
  27       tdb's API was based on gdbm, and ntdb continues this tradition,
  28       with enhancements.  A differences guide is available in the text
  29       file <filename>lib/ntdb/doc/TDB_porting.txt</filename> in the
  30       SAMBA source tree.
  31     </para>
  32   </refsect1>
  33   <refsect1><title>NTDB API OVERVIEW</title>
  34     <para>
  35       The complete API is documented in the ntdb.h header, which is
  36       kept up-to-date and recommended reading.
  37     </para>
  38     <para>
  39       Normal usage is to call ntdb_open() to create or open an ntdb
  40       file.  ntdb_store() is used to add records, ntdb_fetch() is used
  41       to fetch them.  Traversals are supported via callback
  42       (ntdb_traverse()) or iteration (ntdb_firstkey() and
  43       ntdb_nextkey()).  Transactions are supported for batching
  44       updates or reads atomically, using ntdb_transaction_start() and
  45       ntdb_transaction_commit().
  46     </para>
  47     <refsect2><title>Use With Talloc</title>
  48       <para>
  49         ntdb_open() takes an optional linked list of attributes:
  50         in particular you can specify an alternate allocator (such as
  51         talloc):
  52       </para>
  53       <programlisting>
  54 #include &lt;talloc.h&gt;
  55 #include &lt;ntdb.h&gt;
  56
  57 static void *my_alloc(const void *owner, size_t len, void *priv)
  58 {
  59     return talloc_size(owner, len);
  60 }
  61
  62 static void *my_expand(void *old, size_t newlen, void *priv)
  63 {
  64     return talloc_realloc_size(NULL, old, newlen);
  65 }
  66
  67 static void my_free(void *old, void *priv)
  68 {
  69     talloc_free(old);
  70 }
  71
  72 /* This opens an ntdb file as a talloc object with given parent. */
  73 struct ntdb_context *ntdb_open_talloc(const void *parent,
  74                                       const char *filename)
  75 {
  76      struct ntdb_context *ntdb;
  77      union ntdb_attribute alloc;
  78
  79      alloc.base.attr = NTDB_ATTRIBUTE_ALLOCATOR;
  80      alloc.base.next = NULL;
  81      alloc.alloc.alloc = my_alloc;
  82      alloc.alloc.expand = my_expand;
  83      alloc.alloc.free = my_free;
  84
  85      ntdb = ntdb_open(filename, NTDB_DEFAULT, O_RDWR|O_CREAT, 0600,
  86                       &amp;alloc);
  87      if (ntdb) {
  88          talloc_steal(parent, ntdb);
  89          talloc_set_name(ntdb, "%s", filename);
  90      }
  91      return ntdb;
  92 }
  93 </programlisting>
  94     </refsect2>
  95   </refsect1>
  96   <refsect1><title>SEE ALSO</title>
  97     <para>
  98       <ulink url="http://tdb.samba.org/"/>
  99     </para>
 100   </refsect1>
 101
 102   <refsect1><title>AUTHOR</title>
 103     <para> The original tdb software was created by Andrew Tridgell, and
 104     is now developed by the
 105       Samba Team as an Open Source project similar to the way the
 106       Linux kernel is developed.  ntdb was derived from tdb, but mostly
 107       rewritten by Rusty Russell.
 108     </para>
 109   </refsect1>
 110
 111   <refsect1><title>COPYRIGHT/LICENSE</title>
 112     <para>
 113       Copyright (C) Rusty Russell 2013, IBM Corporation
 114     </para>
 115     <para>
 116       This program is free software; you can redistribute it and/or modify
 117       it under the terms of the GNU Lesser General Public License as
 118       published by the Free Software Foundation; either version 3 of the
 119       License, or (at your option) any later version.
 120     </para>
 121     <para>
 122       This program is distributed in the hope that it will be useful, but
 123       WITHOUT ANY WARRANTY; without even the implied warranty of
 124       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 125       General Public License for more details.
 126     </para>
 127     <para>
 128       You should have received a copy of the GNU General Public License
 129       along with this program; if not, see http://www.gnu.org/licenses/.
 130     </para>
 131   </refsect1>
 132 </refentry>