.TH gdbm_firstkey() "" "" "GDBM Function (libgdbm)"
.PC "Return the first record from a GDBM data base"
.B "#include <gdbm.h>"
\fBdatum gdbm_firstkey(\fIdatabase\^\fB)\fR
\fBGDBM_FILE \fIdatabase\^\fB;\fR
.PP
Function
.B gdbm_firstkey()
returns the first record from the data base to which
.I database
points.
.I database
must have been returned by a call to
.BR gdbm_open() .
.PP
.B gdbm_firstkey()
returns the first record within
.IR database .
Note that that the first record is dictated by the algorithm
that the GDBM routines use to hash the keys within the data base, and so
may not be what you expect.
If
.I database
is empty,
.B gdbm_firstkey()
returns a record whose field
.B dptr
is set to NULL.
.PP
.B gdbm_firstkey()
calls
.B malloc()
to allocate the memory to hold the data it retrieves from
.IR database .
It is your responsibility to free this memory; to do so, call
.B free()
and pass it field
.B dptr
in the record that
.B gdbm_firstkey()
returns.
.SH "See Also"
.XR "gdbm.h," gdbm.h
.XR "gdbm_nextkey()," gdbm_next
.XR "gdbm_open()," gdbm_open
.XR "libgdbm" libgdbm
.SH Notes
For a statement of copyright and permissions on this routine, see the
Lexicon entry for
.BR libgdbm .
