d9ed135f206976c44d073ef8b5e8ffd753d08cd9
[samba.git] / source / lib / ldb / man / ldb.3.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <refentry id="ldb.3">
4
5 <refmeta>
6         <refentrytitle>ldb</refentrytitle>
7         <manvolnum>3</manvolnum>
8 </refmeta>
9
10 <refnamediv>
11         <refname>ldb</refname>
12         <refclass>The Samba Project</refclass>
13         <refpurpose>A light-weight database library</refpurpose>
14 </refnamediv>
15
16 <refsynopsisdiv>
17         <synopsis>#include &lt;ldb.h&gt;</synopsis>
18 </refsynopsisdiv>
19
20 <refsect1>
21         <title>description</title>
22
23         <para>
24 ldb is a light weight embedded database library and API. With a
25 programming interface that is very similar to LDAP, ldb can store its
26 data either in a tdb(3) database or in a real LDAP database.
27         </para>
28
29         <para>
30 When used with the tdb backend ldb does not require any database
31 daemon. Instead, ldb function calls are processed immediately by the
32 ldb library, which does IO directly on the database, while allowing
33 multiple readers/writers using operating system byte range locks. This
34 leads to an API with very low overheads, often resulting in speeds of
35 more than 10x what can be achieved with a more traditional LDAP
36 architecture.
37         </para>
38
39         <para>
40 It a taxonomy of databases ldb would sit half way between key/value
41 pair databases (such as berkley db or tdb) and a full LDAP
42 database. With a structured attribute oriented API like LDAP and good
43 indexing capabilities, ldb can be used for quite sophisticated
44 applications that need a light weight database, without the
45 administrative overhead of a full LDAP installation.
46         </para>
47
48         <para>
49 Included with ldb are a number of useful command line tools for
50 manipulating a ldb database. These tools are similar in style to the
51 equivalent ldap command line tools.
52         </para>
53
54         <para>
55 In its default mode of operation with a tdb backend, ldb can also be
56 seen as a "schema-less LDAP". By default ldb does not require a
57 schema, which greatly reduces the complexity of getting started with
58 ldb databases. As the complexity of you application grows you can take
59 advantage of some of the optional schema-like attributes that ldb
60 offers, or you can migrate to using the full LDAP api while keeping
61 your exiting ldb code.
62         </para>
63
64         <para>
65 If you are new to ldb, then I suggest starting with the manual pages
66 for ldbsearch(1) and ldbedit(1), and experimenting with a local
67 database. Then I suggest you look at the ldb_connect(3) and
68 ldb_search(3) manual pages.
69         </para>
70 </refsect1>
71
72 <refsect1>
73         <title>TOOLS</title>
74
75         <itemizedlist>
76                 <listitem><para>
77                         <application>ldbsearch(1)</application>
78                           - command line ldb search utility
79                 </para></listitem>
80
81                 <listitem><para>
82                         <application>ldbedit(1)</application>
83                          - edit all or part of a ldb database using your favourite editor
84                 </para></listitem>
85
86                 <listitem><para>
87                         <application>ldbadd(1)</application>
88                          - add records to a ldb database using LDIF formatted input
89                 </para></listitem>
90
91                 <listitem><para>
92                         <application>ldbdel(1)</application>
93                          - delete records from a ldb database
94                 </para></listitem>
95
96                 <listitem><para>
97                         <application>ldbmodify(1)</application>
98                          - modify records in a ldb database using LDIF formatted input
99                 </para></listitem>
100         </itemizedlist>
101 </refsect1>
102
103 <refsect1>
104         <title>FUNCTIONS</title>
105
106         <itemizedlist>
107                 <listitem><para>
108                         <function>ldb_connect(3)</function>
109                          - connect to a ldb backend
110                 </para></listitem>
111
112                 <listitem><para>
113                         <function>ldb_search(3)</function>
114                          - perform a database search
115                 </para></listitem>
116
117                 <listitem><para>
118                         <function>ldb_add(3)</function>
119                          - add a record to the database
120                 </para></listitem>
121
122                 <listitem><para>
123                         <function>ldb_delete(3)</function>
124                          - delete a record from the database
125                 </para></listitem>
126
127                 <listitem><para>
128                         <function>ldb_modify(3)</function>
129                          - modify a record in the database
130                 </para></listitem>
131
132                 <listitem><para>
133                         <function>ldb_errstring(3)</function>
134                          - retrieve extended error information from the last operation
135                 </para></listitem>
136
137                 <listitem><para>
138                         <function>ldb_ldif_write(3)</function>
139                          - write a LDIF formatted message
140                 </para></listitem>
141
142                 <listitem><para>
143                         <function>ldb_ldif_write_file(3)</function>
144                          - write a LDIF formatted message to a file
145                 </para></listitem>
146
147                 <listitem><para>
148                         <function>ldb_ldif_read(3)</function>
149                          - read a LDIF formatted message
150                 </para></listitem>
151
152                 <listitem><para>
153                         <function>ldb_ldif_read_free(3)</function>
154                          - free the result of a ldb_ldif_read()
155                 </para></listitem>
156
157                 <listitem><para>
158                         <function>ldb_ldif_read_file(3)</function>
159                          - read a LDIF message from a file
160                 </para></listitem>
161
162                 <listitem><para>
163                         <function>ldb_ldif_read_string(3)</function>
164                          - read a LDIF message from a string
165                 </para></listitem>
166
167                 <listitem><para>
168                         <function>ldb_msg_find_element(3)</function>
169                          - find an element in a ldb_message
170                 </para></listitem>
171
172                 <listitem><para>
173                         <function>ldb_val_equal_exact(3)</function>
174                          - compare two ldb_val structures
175                 </para></listitem>
176
177                 <listitem><para>
178                         <function>ldb_msg_find_val(3)</function>
179                          - find an element by value
180                 </para></listitem>
181
182                 <listitem><para>
183                         <function>ldb_msg_add_empty(3)</function>
184                          - add an empty message element to a ldb_message
185                 </para></listitem>
186
187
188                 <listitem><para>
189                         <function>ldb_msg_add(3)</function>
190                          - add a non-empty message element to a ldb_message
191                 </para></listitem>
192
193
194                 <listitem><para>
195                         <function>ldb_msg_element_compare(3)</function>
196                          - compare two ldb_message_element structures
197                 </para></listitem>
198
199
200                 <listitem><para>
201                         <function>ldb_msg_find_int(3)</function>
202                          - return an integer value from a ldb_message
203                 </para></listitem>
204
205
206                 <listitem><para>
207                         <function>ldb_msg_find_uint(3)</function>
208                          - return an unsigned integer value from a ldb_message
209                 </para></listitem>
210
211
212                 <listitem><para>
213                         <function>ldb_msg_find_double(3)</function>
214                          - return a double value from a ldb_message
215                 </para></listitem>
216
217
218                 <listitem><para>
219                         <function>ldb_msg_find_string(3)</function>
220                          - return a string value from a ldb_message
221                 </para></listitem>
222
223
224                 <listitem><para>
225                         <function>ldb_set_alloc(3)</function>
226                          - set the memory allocation function to be used by ldb
227                 </para></listitem>
228
229
230                 <listitem><para>
231                         <function>ldb_set_debug(3)</function>
232                          - set a debug handler to be used by ldb
233                 </para></listitem>
234
235
236                 <listitem><para>
237                         <function>ldb_set_debug_stderr(3)</function>
238                          - set a debug handler for stderr output
239                 </para></listitem>
240         </itemizedlist>
241 </refsect1>
242
243 <refsect1>
244         <title>description</title>
245
246         <para>
247                 ldb was written by 
248                  <ulink url="http://samba.org/~tridge/">Andrew Tridgell</ulink>.
249         </para>
250
251         <para>
252 If you wish to report a problem or make a suggestion then please see
253 the <ulink url="http://ldb.samba.org/"/> web site for
254 current contact and maintainer information.
255         </para>
256
257         <para>
258 ldb is released under the GNU Lesser General Public License version 2
259 or later. Please see the file COPYING for license details.
260         </para>
261 </refsect1>
262 </refentry>