1 files changed, 82 insertions, 0 deletions
diff --git a/debian/manpages/tdb_firstkey.3 b/debian/manpages/tdb_firstkey.3
new file mode 100644
index 0000000..ca902a4
--- /dev/null
+++ b/debian/manpages/tdb_firstkey.3
@@ -0,0 +1,82 @@
+.TH TDB_FIRSTKEY 3 "Aug 16, 2000" "Samba" "Linux Programmer's Manual"
+.SH NAME
+tdb_firstkey - return the key of the first record in a tdb database
+tdb_nextkey - return the key of next record in the tdb database
+.SH SYNOPSIS
+.nf
+.B #include <tdb.h>
+.sp
+.BI "TDB_DATA tdb_firstkey(TDB_CONTEXT *" tdb ");"
+.BI "TDB_DATA tdb_nextkey(TDB_CONTEXT *" tdb ", TDB_DATA " prev_key ");"
+.sp
+.SH DESCRIPTION
+.I tdb_firstkey 
+fetches the key of the first entry in the 
+.I tdb 
+database.
+.I tdb_nextkey
+fetches the key of the entry immediately after 
+.I prev_key
+in the database.
+.sp 
+The TDB_DATA structure returned by both these functions is defined as:
+.PP
+.RS
+.nf
+typedef struct {
+	char *dptr;
+	size_t dsize;
+} TDB_DATA;
+.fi
+.RE
+.PP
+.sp
+The order in which this traverses the database is its own internal
+hash order. Do not expect the keys to be in any recognizably sorted
+order.
+.sp
+These functions are reliable even if other writers are accessing the
+database (or you are replacing or deleting elements as you traverse),
+except in the case of nested
+.I tdb_firstkey
+or
+.I tdb_nextkey
+calls.  For example, the following outer traversal may fail to
+traverse all the elements, or may even traverse elements twice if
+other processes are manipulating the database:
+.PP
+.RS
+.nf
+	TDB_DATA i, j;
+
+	for (i = tdb_firstkey(tdb); i.dptr; i = tdb_nextkey(tdb, i)) {
+		for (j = tdb_firstkey(tdb); j.dptr; j = tdb_nextkey(tdb, j)) {
+		...
+		}
+	}
+.fi
+.RE
+.PP
+If such behaviour is desired, use
+.I tdb_traverse
+instead.
+.sp
+.SH "RETURN VALUE"
+If the call succeeds, then a TDB_DATA structure is returned with the
+.I dptr 
+structure filled in. If the call fails or you have reached the end of
+the database then
+.I dptr 
+will be set to NULL.
+.sp
+.B NOTE:
+The caller is responsible for freeing the data pointed to by
+.I dptr
+.
+.SH AUTHORS
+Software: Andrew Tridgell <tridge@linuxcare.com> and 
+Luke Kenneth Casson Leighton
+Man page: Ben Woodard <ben@valinux.com>
+.SH "SEE ALSO"
+.BR gdbm (3),
+.BR tdb(3)