ndbm(3C) ndbm(3C)
NAME
ndbm: dbmclearerr, dbmclose, dbmdelete, dbmerror, dbmfetch,
dbmfirstkey, dbmnextkey, dbmopen, dbmstore - Datenbasisfunktionen
SYNTAX
#include <ndbm.h>
int dbmclearerr(DBM *db);
void dbmclose(DBM *db);
int dbmdelete(DBM *db, datum key);
int dbmerror(DBM *db);
datum dbmfetch(DBM *db, datum key);
datum dbmfirstkey(DBM *db);
datum dbmnextkey(DBM *db);
DBM *dbmopen(const char *file, int openflags, modet filemode);
int dbmstore(DBM *db, datum key, datum content, int storemode);
BESCHREIBUNG
Diese Funktionen erstellen eine Datenbasis, greifen auf sie zu und
ändern sie.
Die Angabe datum besteht aus mindestens zwei Komponenten, dptr und
dsize. Die Komponente dptr zeigt auf ein Objekt mit einer Länge von
dsize Byte. In dem Objekt, auf das dptr zeigt, können beliebige Binär-
daten sowie Zeichenketten gespeichert werden.
Die Datenbasis wird in zwei Dateien gespeichert. Bei einer Datei han-
delt es sich um ein Verzeichnis mit dem Suffix .dir, die eine Bitmaske
der Schlüssel enthält. Die zweite Datei mit dem Suffix .pag enthält
alle Daten.
Die Funktion dbmopen() öffnet eine Datenbasis. Das Argument file die-
ser Funktion gibt den Pfadnamen der Datenbasis an. Diese Funktion öff-
net zwei Dateien, file.dir und file.pag. Das Argument openflags hat
dieselbe Bedeutung wie das Argument flags von open(), nur daß hierbei
eine nur für den Schreibzugriff geöffnete Datenbasis die Dateien für
den Lese- und Schreibzugriff öffnet, und das Verhalten des Flags
OAPPEND unbestimmt ist. Das Argument filemode hat die gleiche Wir-
kung wie das dritte Argument von open().
Die Funktion dbmclose() schließt eine Datenbasis. Bei dem Argument db
muß es sich um einen Zeiger auf eine dbm-Struktur handeln, die bei
einem Aufruf von dbmopen() zurückgegeben wurde.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
ndbm(3C) ndbm(3C)
Die Funktion dbmfetch() liest einen Eintrag aus einer Datenbasis. Das
Argument db ist ein Zeiger auf eine Datenbasisstruktur, die bei einem
Aufruf von dbmopen() zurückgegeben wurde. Bei dem Argument key han-
delt es sich um eine Angabe datum, die vom Anwendungsprogramm
ursprünglich auf den Wert des Schlüssels gesetzt wurde, der dem
Schlüssel des Eintrags entspricht, den das Programm abruft.
Die Funktion dbmstore() schreibt einen Eintrag in eine Datenbasis. db
ist ein Zeiger auf eine bei einem Aufruf von dbmopen() zurückgegebene
Datenbasisstruktur. Bei dem Argument key handelt es sich um eine
Angabe datum, die vom Anwendungsprogramm ursprünglich auf den Wert des
Schlüssels gesetzt wurde, der den vom Programm geschriebenen Eintrag
(für nachfolgende Lese-, Schreib- oder Löschoperationen) kennzeichnet.
Das Argument content ist eine Angabe datum, die vom Anwendungsprogramm
ursprünglich auf den Wert des vom Programm geschriebenen Eintrags
gesetzt wurde. Das Argument storemode steuert, ob dbmstore() einen
bereits vorhandenen Eintrag ersetzt, dessen Schlüssel dem vom Argument
key angegebenen Schlüssel entspricht. Das Anwendungsprogramm muß
storemode auf DBMINSERT oder DBMREPLACE setzen. Wenn die Datenbasis
einen Eintrag enthält, der dem Argument key entspricht, und storemode
auf DBMREPLACE gesetzt ist, wird der bereits vorhandene Eintrag durch
den neuen Eintrag ersetzt. Wenn die Datenbasis einen Eintrag enthält,
der dem Argument key entspricht, und storemode auf DBMINSERT gesetzt
ist, wird der bereits vorhandene Eintrag nicht durch den neuen Eintrag
ersetzt. Wenn die Datenbasis keinen Eintrag enthält, der dem Argument
key entspricht, und storemode entweder auf DBMINSERT oder auf
DBMREPLACE gesetzt ist, wird der neue Eintrag in die Datenbasis ein-
gefügt.
Die Funktion dbmdelete() löscht einen Eintrag und seinen zugehörigen
Schlüssel aus der Datenbasis. Das Argument db ist ein Zeiger auf eine
bei einem Aufruf von dbmopen() zurückgegebene Datenbasisstruktur. Das
Argument key ist eine Angabe datum, die vom Anwendungsprogramm
ursprünglich auf den Wert des Schlüssels gesetzt wurde, der den vom
Programm gelöschten Eintrag kennzeichnet.
Die Funktion dbmfirstkey() gibt den ersten Schlüssel in der Datenba-
sis zurück. Das Argument db ist ein Zeiger auf eine bei einem Aufruf
von dbmopen() zurückgegebene Datenbasisstruktur.
Die Funktion dbmnextkey() gibt den nächsten Schlüssel in der Datenba-
sis zurück. Das Argument db ist ein Zeiger auf die bei einem Aufruf
von dbmopen() zurückgegebene Datenbasisstruktur. Die Funktion
dbmfirstkey() muß vor dem Aufruf von dbmnextkey() aufgerufen werden.
Nachfolgende Aufrufe von dbmnextkey() geben so lange den nächsten
Schlüssel zurück, bis alle Schlüssel in der Datenbasis zurückgegeben
wurden.
Die Funktion dbmerror() gibt eine Fehlerbedingung der Datenbasis
zurück. Das Argument db ist ein Zeiger auf eine bei einem Aufruf von
dbmopen() zurückgegebene Datenbasisstruktur.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
ndbm(3C) ndbm(3C)
Die Funktion dbmclearerr() löscht die Fehlerbedingung der Datenbasis.
Das Argument db ist ein Zeiger auf eine bei einem Aufruf von
dbmopen() zurückgegebene Datenbasisstruktur.
Diese Datenbasisfunktionen unterstützen Paare aus Schlüssel und zuge-
hörigem Inhalt (key/content) mit mindestens 1024 Bytes.
RÜCKGABEWERT
Die Funktionen dbmstore() und dbmdelete() geben bei erfolgreicher
Ausführung den Wert 0, bei einem Fehler einen negativen Wert zurück.
Wird die Funktion dbmstore() mit einem Wert DBMINSERT für flags auf-
gerufen und stellt die Funktion einen Eintrag mit dem gleichen Schlüs-
sel fest, wird der Wert 1 zurückgegeben.
Ist die Fehlerbedingung nicht gesetzt, gibt die Funktion dbmerror()
den Wert 0 zurück. Ist die Fehlerbedingung gesetzt, gibt dbmerror()
einen Wert ungleich 0 zurück.
Der Return-Wert von dbmclearerr() ist nicht spezifiziert.
Die Funktionen dbmfirstkey() und dbmnextkey() geben einen Schlüssel
datum zurück. Ist das Ende einer Datenbasis erreicht, ist die Kompo-
nente dptr des Schlüssels ein Nullzeiger. Wird ein Fehler festge-
stellt, ist die Komponente dptr des Schlüssels ein Nullzeiger, und die
Fehlerbedingung der Datenbasis wird gesetzt.
Die Funktion dbmfetch() gibt einen Inhalt datum zurück. Wenn kein
Eintrag in der Datenbasis dem Schlüssel entspricht oder eine Fehlerbe-
dingung in der Datenbasis festgestellt wurde, ist die Komponente dptr
des Inhalts ein Nullzeiger.
Die Funktion dbmopen() gibt einen Zeiger auf eine Datenbasisstruktur
zurück. Wird während der Operation ein Fehler festgestellt, gibt
dbmopen() einen Wert (DBM *)0 zurück.
FEHLER
Es sind keine Fehler definiert.
ANWENDUNGSZWECK
Der folgende Code geht die Datenbasis durch:
for(key = dbmfirstkey(db); key.dptr != NULL; key = dbmnextkey(db))
Die in dieser Bibliothek enthaltenen dbm-Funktionen sind nicht mit
den Funktionen eines allgemeinen Datenbasisverwaltungssystems zu ver-
wechseln. Diese Funktionen stellen weder mehrere Suchschlüssel pro
Eintrag zur Verfügung noch bieten sie Sicherheitsmaßnahmen für den
Mehrbenutzerzugriff (d. h. Einträge oder Dateien werden nicht
gesperrt). Zudem stellen sie die zahlreichen anderen nützlichen Daten-
basisfunktionen leistungsfähigerer Datenbasisverwaltungssysteme nicht
bereit. Die Erstellung und Aktualisierung von Datenbasen mit Hilfe
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
ndbm(3C) ndbm(3C)
dieser Funktionen nimmt aufgrund von Datenkopien bei Hash-Kollisionen
relativ viel Zeit in Anspruch. Diese Funktionen sind für Anwendungen
geeignet, bei denen eine rasche Suche nach relativ statischen Daten
erforderlich ist, die von einem einzigen Schlüssel indexiert werden
sollen.
Die von diesen Funktionen zurückgegebenen dptr-Zeiger zeigen mögli-
cherweise auf den statischen Speicher, der von nachfolgenden Aufrufen
geändert werden kann.
dbmdelete() stellt den Dateibereich zwar nicht physisch wieder her,
macht ihn aber zur weiteren Verwendung verfügbar.
Nach dem Aufrufen von dbmstore() oder dbmdelete() während die
Schlüssel von dbmfirstkey() und dbmnextkey() durchgegangen werden,
sollte die Anwendung die Datenbasis durch Aufrufen von dbmfirstkey()
vor dem erneuten Aufrufen von dbmnextkey() zurücksetzen.
SIEHE AUCH
open(2), ndbm(5).
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98