lib/ntdb/doc/TDB_porting.txt

   1 Interface differences between TDB and NTDB.
   2
   3 - ntdb shares 'struct TDB_DATA' with tdb, but TDB defines the TDB_DATA
   4   typedef, whereas ntdb defines NTDB_DATA (ie. both are compatible).
   5   If you include both ntdb.h and tdb.h, #include tdb.h first,
   6   otherwise you'll get a compile error when tdb.h re-defined struct
   7   TDB_DATA.
   8
   9   Example:
  10         #include <tdb.h>
  11         #include <ntdb.h>
  12
  13 - ntdb functions return NTDB_SUCCESS (ie 0) on success, and a negative
  14   error on failure, whereas tdb functions returned 0 on success, and
  15   -1 on failure.  tdb then used tdb_error() to determine the error;
  16   this API is nasty if we ever want to support threads, so is not supported.
  17
  18   Example:
  19         #include <tdb.h>
  20         #include <ntdb.h>
  21
  22         void tdb_example(struct tdb_context *tdb, TDB_DATA key, TDB_DATA d)
  23         {
  24                 if (tdb_store(tdb, key, d) == -1) {
  25                         printf("store failed: %s\n", tdb_errorstr(tdb));
  26                 }
  27         }
  28
  29         void ntdb_example(struct ntdb_context *ntdb, NTDB_DATA key, NTDB_DATA d)
  30         {
  31                 enum NTDB_ERROR e;
  32
  33                 e = ntdb_store(ntdb, key, d);
  34                 if (e) {
  35                         printf("store failed: %s\n", ntdb_errorstr(e));
  36                 }
  37         }
  38
  39 - ntdb's ntdb_fetch() returns an error, tdb's returned the data directly
  40   (or tdb_null, and you were supposed to check tdb_error() to find out why).
  41
  42   Example:
  43         #include <tdb.h>
  44         #include <ntdb.h>
  45
  46         void tdb_example(struct tdb_context *tdb, TDB_DATA key)
  47         {
  48                 TDB_DATA data;
  49
  50                 data = tdb_fetch(tdb, key);
  51                 if (!data.dptr) {
  52                         printf("fetch failed: %s\n", tdb_errorstr(tdb));
  53                 }
  54         }
  55
  56         void ntdb_example(struct ntdb_context *ntdb, NTDB_DATA key)
  57         {
  58                 NTDB_DATA data;
  59                 enum NTDB_ERROR e;
  60
  61                 e = ntdb_fetch(ntdb, key, &data);
  62                 if (e) {
  63                         printf("fetch failed: %s\n", ntdb_errorstr(e));
  64                 }
  65         }
  66
  67 - ntdb's ntdb_nextkey() frees the old key's dptr, in tdb you needed to do
  68   this manually.
  69
  70   Example:
  71         #include <tdb.h>
  72         #include <ntdb.h>
  73
  74         void tdb_example(struct tdb_context *tdb)
  75         {
  76                 TDB_DATA key, next, data;
  77
  78                 for (key = tdb_firstkey(tdb); key.dptr; key = next) {
  79                         printf("Got key!\n");
  80                         next = tdb_nextkey(tdb, key);
  81                         free(key.dptr);
  82                 }
  83         }
  84
  85
  86         void ntdb_example(struct ntdb_context *ntdb)
  87         {
  88                 NTDB_DATA k, data;
  89                 enum NTDB_ERROR e;
  90
  91                 for (e = ntdb_firstkey(ntdb,&k); !e; e = ntdb_nextkey(ntdb,&k))
  92                         printf("Got key!\n");
  93         }
  94
  95 - Unlike tdb_open/tdb_open_ex, ntdb_open does not allow NULL names,
  96   even for NTDB_INTERNAL dbs, and thus ntdb_name() never returns NULL.
  97
  98   Example:
  99         #include <tdb.h>
 100         #include <ntdb.h>
 101
 102         struct tdb_context *tdb_example(void)
 103         {
 104                 return tdb_open(NULL, 0, TDB_INTERNAL, O_RDWR, 0);
 105         }
 106
 107         struct ntdb_context *ntdb_example(void)
 108         {
 109                 return ntdb_open("example", NTDB_INTERNAL, O_RDWR, 0);
 110         }
 111
 112 - ntdb uses a linked list of attribute structures to implement logging and
 113   alternate hashes.  tdb used tdb_open_ex, which was not extensible.
 114
 115   Example:
 116         #include <tdb.h>
 117         #include <ntdb.h>
 118
 119         /* Custom hash function */
 120         static unsigned int my_tdb_hash_func(TDB_DATA *key)
 121         {
 122                 return key->dsize;
 123         }
 124
 125         struct tdb_context *tdb_example(void)
 126         {
 127                 return tdb_open_ex("example.tdb", 0, TDB_DEFAULT,
 128                                    O_CREAT|O_RDWR, 0600, NULL, my_hash_func);
 129         }
 130
 131         /* Custom hash function */
 132         static unsigned int my_ntdb_hash_func(const void *key, size_t len,
 133                                               uint32_t seed, void *data)
 134         {
 135                 return len;
 136         }
 137
 138         struct ntdb_context *ntdb_example(void)
 139         {
 140                 union ntdb_attribute hash;
 141
 142                 hash.base.attr = NTDB_ATTRIBUTE_HASH;
 143                 hash.base.next = NULL;
 144                 hash.hash.fn = my_ntdb_hash_func;
 145                 return ntdb_open("example.ntdb", NTDB_DEFAULT,
 146                                    O_CREAT|O_RDWR, 0600, &hash);
 147         }
 148
 149 - tdb's tdb_open/tdb_open_ex took an explicit hash size, defaulting to
 150   131.  ntdb's uses an attribute for this, defaulting to 8192.
 151
 152   Example:
 153         #include <tdb.h>
 154         #include <ntdb.h>
 155
 156         struct tdb_context *tdb_example(void)
 157         {
 158                 return tdb_open("example.tdb", 10007, TDB_DEFAULT,
 159                                 O_CREAT|O_RDWR, 0600);
 160         }
 161
 162         struct ntdb_context *ntdb_example(void)
 163         {
 164                 union ntdb_attribute hashsize;
 165
 166                 hashsize.base.attr = NTDB_ATTRIBUTE_HASHSIZE;
 167                 hashsize.base.next = NULL;
 168                 hashsize.hashsize.size = 16384;
 169                 return ntdb_open("example.ntdb", NTDB_DEFAULT,
 170                                    O_CREAT|O_RDWR, 0600, &hashsize);
 171         }
 172
 173 - ntdb's log function is simpler than tdb's log function.  The string
 174   is already formatted, is not terminated by a '\n', and it takes an
 175   enum ntdb_log_level not a tdb_debug_level, and which has only three
 176   values: NTDB_LOG_ERROR, NTDB_LOG_USE_ERROR and NTDB_LOG_WARNING.
 177
 178         #include <tdb.h>
 179         #include <ntdb.h>
 180
 181         static void tdb_log(struct tdb_context *tdb,
 182                             enum tdb_debug_level level, const char *fmt, ...)
 183         {
 184                 va_list ap;
 185                 const char *name;
 186
 187                 switch (level) {
 188                 case TDB_DEBUG_FATAL:
 189                         fprintf(stderr, "FATAL: ");
 190                         break;
 191                 case TDB_DEBUG_ERROR:
 192                         fprintf(stderr, "ERROR: ");
 193                         break;
 194                 case TDB_DEBUG_WARNING:
 195                         fprintf(stderr, "WARNING: ");
 196                         break;
 197                 case TDB_DEBUG_TRACE:
 198                         /* Don't print out tracing. */
 199                         return;
 200                 }
 201
 202                 name = tdb_name(tdb);
 203                 if (!name) {
 204                         name = "unnamed";
 205                 }
 206
 207                 fprintf(stderr, "tdb(%s):", name);
 208
 209                 va_start(ap, fmt);
 210                 vfprintf(stderr, fmt, ap);
 211                 va_end(ap);
 212         }
 213
 214         struct tdb_context *tdb_example(void)
 215         {
 216                 struct tdb_logging_context lctx;
 217
 218                 lctx.log_fn = tdb_log;
 219                 return tdb_open_ex("example.tdb", 0, TDB_DEFAULT,
 220                                    O_CREAT|O_RDWR, 0600, &lctx, NULL);
 221         }
 222
 223         static void ntdb_log(struct ntdb_context *ntdb,
 224                              enum ntdb_log_level level,
 225                              enum NTDB_ERROR ecode,
 226                              const char *message,
 227                              void *data)
 228         {
 229                 switch (level) {
 230                 case NTDB_LOG_ERROR:
 231                         fprintf(stderr, "ERROR: ");
 232                         break;
 233                 case NTDB_LOG_USE_ERROR:
 234                         /* We made a mistake, so abort. */
 235                         abort();
 236                         break;
 237                 case NTDB_LOG_WARNING:
 238                         fprintf(stderr, "WARNING: ");
 239                         break;
 240                 }
 241
 242                 fprintf(stderr, "ntdb(%s):%s:%s\n",
 243                         ntdb_name(ntdb), ntdb_errorstr(ecode), message);
 244         }
 245
 246         struct ntdb_context *ntdb_example(void)
 247         {
 248                 union ntdb_attribute log;
 249
 250                 log.base.attr = NTDB_ATTRIBUTE_LOG;
 251                 log.base.next = NULL;
 252                 log.log.fn = ntdb_log;
 253                 return ntdb_open("example.ntdb", NTDB_DEFAULT,
 254                                  O_CREAT|O_RDWR, 0600, &log);
 255         }
 256
 257 - ntdb provides ntdb_deq() for comparing two NTDB_DATA, and ntdb_mkdata() for
 258   creating an NTDB_DATA.
 259
 260         #include <tdb.h>
 261         #include <ntdb.h>
 262
 263         void tdb_example(struct tdb_context *tdb)
 264         {
 265                 TDB_DATA data, key;
 266
 267                 key.dsize = strlen("hello");
 268                 key.dptr = "hello";
 269                 data = tdb_fetch(tdb, key);
 270                 if (data.dsize == key.dsize
 271                     && !memcmp(data.dptr, key.dptr, key.dsize))
 272                         printf("key is same as data\n");
 273                 }
 274                 free(data.dptr);
 275         }
 276
 277         void ntdb_example(struct ntdb_context *ntdb)
 278         {
 279                 NTDB_DATA data, key;
 280
 281                 key = ntdb_mkdata("hello", strlen("hello"));
 282                 if (ntdb_fetch(ntdb, key, &data) == NTDB_SUCCESS) {
 283                         if (ntdb_deq(key, data)) {
 284                                 printf("key is same as data\n");
 285                         }
 286                         free(data.dptr);
 287                 }
 288         }
 289
 290 - ntdb's ntdb_parse_record() takes a type-checked callback data
 291   pointer, not a void * (though a void * pointer still works).  The
 292   callback function is allowed to do read operations on the database,
 293   or write operations if you first call ntdb_lockall().  TDB's
 294   tdb_parse_record() did not allow any database access within the
 295   callback, could crash if you tried.
 296
 297   Example:
 298         #include <tdb.h>
 299         #include <ntdb.h>
 300
 301         static int tdb_parser(TDB_DATA key, TDB_DATA data, void *private_data)
 302         {
 303                 TDB_DATA *expect = private_data;
 304
 305                 return data.dsize == expect->dsize
 306                         && !memcmp(data.dptr, expect->dptr, data.dsize);
 307         }
 308
 309         void tdb_example(struct tdb_context *tdb, TDB_DATA key, NTDB_DATA d)
 310         {
 311                 switch (tdb_parse_record(tdb, key, tdb_parser, &d)) {
 312                 case -1:
 313                         printf("parse failed: %s\n", tdb_errorstr(tdb));
 314                         break;
 315                 case 0:
 316                         printf("data was different!\n");
 317                         break;
 318                 case 1:
 319                         printf("data was same!\n");
 320                         break;
 321                 }
 322         }
 323
 324         static int ntdb_parser(TDB_DATA key, TDB_DATA data, TDB_DATA *expect)
 325         {
 326                 return ntdb_deq(data, *expect);
 327         }
 328
 329         void ntdb_example(struct ntdb_context *ntdb, NTDB_DATA key, NTDB_DATA d)
 330         {
 331                 enum NTDB_ERROR e;
 332
 333                 e = tdb_parse_record(tdb, key, tdb_parser, &d);
 334                 switch (e) {
 335                 case 0:
 336                         printf("data was different!\n");
 337                         break;
 338                 case 1:
 339                         printf("data was same!\n");
 340                         break;
 341                 default:
 342                         printf("parse failed: %s\n", ntdb_errorstr(e));
 343                         break;
 344                 }
 345         }
 346
 347 - ntdb does locking on read-only databases (ie. O_RDONLY passed to ntdb_open).
 348   tdb did not: use the NTDB_NOLOCK flag if you want to suppress locking.
 349
 350   Example:
 351         #include <tdb.h>
 352         #include <ntdb.h>
 353
 354         struct tdb_context *tdb_example(void)
 355         {
 356                 return tdb_open("example.tdb", 0, TDB_DEFAULT, O_RDONLY, 0);
 357         }
 358
 359         struct ntdb_context *ntdb_example(void)
 360         {
 361                 return ntdb_open("example.ntdb", NTDB_NOLOCK, O_RDONLY, NULL);
 362         }
 363
 364 - Failure inside a transaction (such as a lock function failing) does
 365   not implicitly cancel the transaction; you still need to call
 366   ntdb_transaction_cancel().
 367
 368         #include <tdb.h>
 369         #include <ntdb.h>
 370
 371         void tdb_example(struct tdb_context *tdb, TDB_DATA key, TDB_DATA d)
 372         {
 373                 if (tdb_transaction_start(tdb) == -1) {
 374                         printf("transaction failed: %s\n", tdb_errorstr(tdb));
 375                         return;
 376                 }
 377
 378                 if (tdb_store(tdb, key, d) == -1) {
 379                         printf("store failed: %s\n", tdb_errorstr(tdb));
 380                         return;
 381                 }
 382                 if (tdb_transaction_commit(tdb) == -1) {
 383                         printf("commit failed: %s\n", tdb_errorstr(tdb));
 384                 }
 385         }
 386
 387         void ntdb_example(struct ntdb_context *ntdb, NTDB_DATA key, NTDB_DATA d)
 388         {
 389                 enum NTDB_ERROR e;
 390
 391                 e = ntdb_transaction_start(ntdb);
 392                 if (e) {
 393                         printf("transaction failed: %s\n", ntdb_errorstr(e));
 394                         return;
 395                 }
 396
 397                 e = ntdb_store(ntdb, key, d);
 398                 if (e) {
 399                         printf("store failed: %s\n", ntdb_errorstr(e));
 400                         ntdb_transaction_cancel(ntdb);
 401                 }
 402
 403                 e = ntdb_transaction_commit(ntdb);
 404                 if (e) {
 405                         printf("commit failed: %s\n", ntdb_errorstr(e));
 406                 }
 407         }
 408
 409 - There is no NTDB_CLEAR_IF_FIRST flag; it has severe scalability and
 410   API problems.  If necessary, you can emulate this by using the open
 411   hook and placing a 1-byte lock at offset 4.  If your program forks
 412   and exits, you will need to place this lock again in the child before
 413   the parent exits.
 414
 415   Example:
 416
 417         #include <tdb.h>
 418         #include <ntdb.h>
 419
 420         struct tdb_context *tdb_example(void)
 421         {
 422                 return tdb_open("example.tdb", 0, TDB_CLEAR_IF_FIRST,
 423                                    O_CREAT|O_RDWR, 0600);
 424         }
 425
 426         static enum NTDB_ERROR clear_if_first(int fd, void *unused)
 427         {
 428                 /* We hold a lock offset 4 always, so we can tell if
 429                  * anyone else is. */
 430                 struct flock fl;
 431
 432                 fl.l_type = F_WRLCK;
 433                 fl.l_whence = SEEK_SET;
 434                 fl.l_start = 4; /* ACTIVE_LOCK */
 435                 fl.l_len = 1;
 436
 437                 if (fcntl(fd, F_SETLK, &fl) == 0) {
 438                         /* We must be first ones to open it!  Clear it. */
 439                         if (ftruncate(fd, 0) != 0) {
 440                                 return NTDB_ERR_IO;
 441                         }
 442                 }
 443                 fl.l_type = F_RDLCK;
 444                 if (fcntl(fd, F_SETLKW, &fl) != 0) {
 445                         return NTDB_ERR_IO;
 446                 }
 447                 return NTDB_SUCCESS;
 448         }
 449
 450         struct ntdb_context *ntdb_example(void)
 451         {
 452                 union ntdb_attribute open_attr;
 453
 454                 open_attr.openhook.base.attr = NTDB_ATTRIBUTE_OPENHOOK;
 455                 open_attr.openhook.base.next = NULL;
 456                 open_attr.openhook.fn = clear_if_first;
 457
 458                 return ntdb_open("example.ntdb", NTDB_DEFAULT,
 459                                  O_CREAT|O_RDWR, 0600, &open_attr);
 460         }
 461
 462 - ntdb traversals are not reliable if the database is changed during
 463   the traversal, ie your traversal may not cover all elements, or may
 464   cover elements multiple times.  As a special exception, deleting the
 465   current record within ntdb_traverse() is reliable.
 466
 467 - There is no ntdb_traverse_read, since ntdb_traverse does not hold
 468   a lock across the entire traversal anyway.  If you want to make sure
 469   that your traversal function does not write to the database, you can
 470   set and clear the NTDB_RDONLY flag around the traversal.
 471
 472 - ntdb does not need tdb_reopen() or tdb_reopen_all().  If you call
 473   fork() after during certain operations the child should close the
 474   ntdb, or complete the operations before continuing to use the tdb:
 475
 476         ntdb_transaction_start(): child must ntdb_transaction_cancel()
 477         ntdb_lockall(): child must call ntdb_unlockall()
 478         ntdb_lockall_read(): child must call ntdb_unlockall_read()
 479         ntdb_chainlock(): child must call ntdb_chainunlock()
 480         ntdb_parse() callback: child must return from ntdb_parse()
 481
 482 - ntdb will not open a non-ntdb file, even if O_CREAT is specified.  tdb
 483   will overwrite an unknown file in that case.