summaryrefslogtreecommitdiff
path: root/lib/ntdb/doc
diff options
context:
space:
mode:
authorRusty Russell <rusty@rustcorp.com.au>2012-06-22 09:44:41 +0930
committerRusty Russell <rusty@rustcorp.com.au>2012-06-22 07:35:17 +0200
commit01ec4a72de56ade54bbbc92e0a408771390c5c12 (patch)
tree1ee7082cac28cee704ebc0eb6e76d372baa31405 /lib/ntdb/doc
parentbd5c061932d9aaf2e66cd56a39743c9ff34c3a88 (diff)
downloadsamba-01ec4a72de56ade54bbbc92e0a408771390c5c12.tar.gz
samba-01ec4a72de56ade54bbbc92e0a408771390c5c12.tar.bz2
samba-01ec4a72de56ade54bbbc92e0a408771390c5c12.zip
ntdb: make database read-only during ntdb_parse() callback.
Since we have a readlock, any write will grab a write lock: if it happens to be on the same bucket, we'll fail. For that reason, enforce read-only so every write operation fails (even for NTDB_NOLOCK or NTDB_INTERNAL dbs), and document it! Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
Diffstat (limited to 'lib/ntdb/doc')
-rw-r--r--lib/ntdb/doc/TDB_porting.txt91
1 files changed, 74 insertions, 17 deletions
diff --git a/lib/ntdb/doc/TDB_porting.txt b/lib/ntdb/doc/TDB_porting.txt
index 8b0ca2fec8..5daf94b74b 100644
--- a/lib/ntdb/doc/TDB_porting.txt
+++ b/lib/ntdb/doc/TDB_porting.txt
@@ -170,23 +170,6 @@ Interface differences between TDB and NTDB.
O_CREAT|O_RDWR, 0600, &hashsize);
}
-- ntdb does locking on read-only databases (ie. O_RDONLY passed to ntdb_open).
- tdb did not: use the NTDB_NOLOCK flag if you want to suppress locking.
-
- Example:
- #include <tdb.h>
- #include <ntdb.h>
-
- struct tdb_context *tdb_example(void)
- {
- return tdb_open("example.tdb", 0, TDB_DEFAULT, O_RDONLY, 0);
- }
-
- struct ntdb_context *ntdb_example(void)
- {
- return ntdb_open("example.ntdb", NTDB_NOLOCK, O_RDONLY, NULL);
- }
-
- ntdb's log function is simpler than tdb's log function. The string
is already formatted, is not terminated by a '\n', and it takes an
enum ntdb_log_level not a tdb_debug_level, and which has only three
@@ -304,6 +287,80 @@ Interface differences between TDB and NTDB.
}
}
+- ntdb's ntdb_parse_record() takes a type-checked callback data
+ pointer, not a void * (though a void * pointer still works). The
+ callback function is allowed to do read operations on the database,
+ or write operations if you first call ntdb_lockall(). TDB's
+ tdb_parse_record() did not allow any database access within the
+ callback, could crash if you tried.
+
+ Example:
+ #include <tdb.h>
+ #include <ntdb.h>
+
+ static int tdb_parser(TDB_DATA key, TDB_DATA data, void *private_data)
+ {
+ TDB_DATA *expect = private_data;
+
+ return data.dsize == expect->dsize
+ && !memcmp(data.dptr, expect->dptr, data.dsize);
+ }
+
+ void tdb_example(struct tdb_context *tdb, TDB_DATA key, NTDB_DATA d)
+ {
+ switch (tdb_parse_record(tdb, key, tdb_parser, &d)) {
+ case -1:
+ printf("parse failed: %s\n", tdb_errorstr(tdb));
+ break;
+ case 0:
+ printf("data was different!\n");
+ break;
+ case 1:
+ printf("data was same!\n");
+ break;
+ }
+ }
+
+ static int ntdb_parser(TDB_DATA key, TDB_DATA data, TDB_DATA *expect)
+ {
+ return ntdb_deq(data, *expect);
+ }
+
+ void ntdb_example(struct ntdb_context *ntdb, NTDB_DATA key, NTDB_DATA d)
+ {
+ enum NTDB_ERROR e;
+
+ e = tdb_parse_record(tdb, key, tdb_parser, &d);
+ switch (e) {
+ case 0:
+ printf("data was different!\n");
+ break;
+ case 1:
+ printf("data was same!\n");
+ break;
+ default:
+ printf("parse failed: %s\n", ntdb_errorstr(e));
+ break;
+ }
+ }
+
+- ntdb does locking on read-only databases (ie. O_RDONLY passed to ntdb_open).
+ tdb did not: use the NTDB_NOLOCK flag if you want to suppress locking.
+
+ Example:
+ #include <tdb.h>
+ #include <ntdb.h>
+
+ struct tdb_context *tdb_example(void)
+ {
+ return tdb_open("example.tdb", 0, TDB_DEFAULT, O_RDONLY, 0);
+ }
+
+ struct ntdb_context *ntdb_example(void)
+ {
+ return ntdb_open("example.ntdb", NTDB_NOLOCK, O_RDONLY, NULL);
+ }
+
- Failure inside a transaction (such as a lock function failing) does
not implicitly cancel the transaction; you still need to call
ntdb_transaction_cancel().