dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, dbm_open, dbm_store - Funktionen zur Verwaltung von dbm-Datenbasen

Definition	int dbm_clearerr(DBM *db); void dbm_close(DBM *db); int dbm_delete(DBM *db, datum key); int dbm_error(DBM *db); datum dbm_fetch(DBM *db, datum key); datum dbm_firstkey(DBM *db); datum dbm_nextkey(DBM *db); DBM *dbm_open(const char *file, int open_flags, mode_t file_mode); int dbm_store(DBM *db, datum key, datum content, int store_mode);
Beschreibung	Diese Funktionen verwalten Paare aus Schlüssel und zugehörigem Inhalt (key/content) von mindestens 1024 Byte in einer Datenbasis. Die Funktionen bearbeiten sehr große Datenbasen (mit einer Milliarde Blöcken) und greifen auf ein mit einem Schlüssel versehenes Objekt in einem oder zwei Zugriff(en) auf das Dateisystem zu. Dieses Paket ersetzt die frühere dbm-Bibliothek, die nur jeweils eine Datenbasis verwalten kann. key und content werden von der Typdefinition (typedef) datum beschrieben. datum gibt eine Zeichenkette von dsize Byte an, auf die dptr zeigt. Sowohl beliebige binäre Daten als auch normale ASCII-Zeichenketten sind zulässig. Die Datenbasis wird in zwei Dateien gespeichert. Bei einer Datei handelt es sich um ein Verzeichnis mit dem Suffix .dir, das eine Bitmaske enthält. Die zweite Datei mit dem Suffix .pag enthält die Daten. dbm_open() öffnet eine Datenbasis. Das Argument file muss den Pfadnamen der Datenbank enthalten. Hierdurch werden die Dateien file .dir und file .pag geöffnet und/oder erstellt, abhängig vom Argument open_flags. Die Bedeutung von open_flags entspricht der von oflag der Funktion open() (siehe "open, open64, openat, openat64 - Datei öffnen"), außer dass bei den Dateien der Datenbank, die WRITE-ONLY geöffnet werden, Schreib- und Lesezugriff erlaubt ist. file_mode hat dieselbe Bedeutung wie das dritte Argument von open(). dbm_open() gibt einen Zeiger auf eine Struktur vom Typ DBM zurück. Dieser Zeiger muss von allen übrigen Funktionen dieser Gruppe als Argument db übergeben werden. dbm_close() schließt eine Datenbasis. dbm_fetch() liest einen Satz aus der Datenbasis. key ist vom Typ datum und muss den Wert des entsprechenden Schlüssels des Satzes, der gelesen werden soll, enthalten. dbm_store() schreibt einen Satz in die Datenbasis. key ist vom Typ datum und muss den Wert des entsprechenden Schlüssels des Satzes, der geschrieben werden soll, enthalten. Unter diesem Schlüssel kann der Satz später wieder gelesen, geändert oder gelöscht werden. content ist ebenfalls vom Typ datum und enthält den Inhalt des Satzes, der geschrieben werden soll. Das Argument store_mode kann entweder DBM_INSERT oder DBM_REPLACE lauten. Bei DBM_INSERT werden nur neue Einträge in die Datenbasis aufgenommen; ein bereits vorhandener Eintrag mit gleichem Schlüssel wird nicht geändert. Bei DBM_REPLACE wird ein bestehender Eintrag ersetzt, wenn er den gleichen Schlüssel hat. Bei DBM_INSERT dagegen wird ein bestehender Eintrag mit gleichem Schlüssel nicht ersetzt. Wenn der angegebene Schlüssel in der Datenbasis nicht gefunden wird, fügt dbm_store() den Satz in die Datenbasis ein, unabhängig davon, ob store_mode auf DBM_INSERT oder DBM_REPLACE gesetzt ist. dbm_delete() löscht einen Satz und den zugehörigen Schlüssel aus der Datenbasis. key ist vom Typ datum und muss den Wert des entsprechenden Schlüssels des Satzes, der gelöscht werden soll, enthalten. dbm_firstkey() gibt den ersten Schlüssel in der Datenbasis zurück. dbm_nextkey() gibt den jeweils nächsten Schlüssel in der Datenbasis zurück. Um mit dbm_nextkey() arbeiten zu können, muss zuvor dbm_firstkey() aufgerufen worden sein. Aufeinander folgende Aufrufe von dbm_nextkey() geben jeweils den nächsten Schlüssel zurück, bis alle Schlüssel der Datenbasis abgearbeitet sind. Die Funktion dbm_error() gibt die Fehlerbedingung der Datenbank zurück. Das Argument db ist ein Zeiger auf eine Datenbankstruktur, die von einem Aufruf von dbm_open() zurückgegeben wurde. Die Funktion dbm_clearerr() löscht die Fehlerbedingung der Datenbank. Das Argument db ist ein Zeiger auf eine Datenbankstruktur, die von einem Aufruf von dbm_open() zurückgegeben wurde. dbm_clearerr() ist nicht threadsicher.
Returnwert	dbm_open(): Zeiger auf eine Struktur vom Typ DBM
		bei Erfolg.
	(DBM *)0	bei Fehler.
	dbm_store():
	0	bei Erfolg.
	1	falls flags den Wert DBM_INSERT hat und die Datenbasis bereits einen Satz mit dem angegebenen Schlüssel enthält.
	dbm_fetch():
	datum content
		bei Erfolg.
	dptr = Nullzeiger
		falls der angegebene Schlüssel nicht in der Datenbasis gefunden wurde oder bei Fehler.
	dbm_delete():
	0	bei Erfolg.
	Negativwert	bei Fehler.
	dbm_firstkey(), dbm_nextkey():
	datum key	bei Erfolg.
	dptr = Nullzeiger
		falls das Ende der Datenbasis erreicht ist oder bei Fehler. Im Fehlerfall wird zusätzlich die Fehleranzeige der Datenbasis gesetzt.
	dbm_error():
	0	wenn die Fehlerbedingung nicht gesetzt ist.
	!= 0	wenn die Fehlerbedingung gesetzt ist.
	dbm_clearerr(): Der Returnwert ist undefiniert.
Hinweise	Der folgende Code geht die gesamte Datenbasis durch: for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) Die dbm_ Funktionen, die in dieser Bibliothek zur Verfügung gestellt werden, können keinesfalls mit den Funktionen eines allgemeinen Datenbankverwaltungssystems verglichen werden. Sie ermöglichen keine mehrfachen Suchschlüsselworte pro Eintrag, sie bieten keinen Schutz gegen Mehrfach-Zugriff (d.h. sie sperren keine Sätze oder Dateien) und sie stellen auch nicht die Vielzahl anderer Datenbankfunktionen bereit, die in leistungsstarken Datenbankverwaltungssystemen angeboten werden. Erstellen und Aktualisieren von Datenbasen mit diesen Funktionen geschieht auf Grund der Datenkopien nach Hash-Kollisionen relativ langsam. Die dbm_ Funktionen sind nützlich für Anwendungen, die ohne viel Aufwand relativ statische Informationen verwalten wollen, die über einen einzigen Schlüssel indiziert werden. Die dptr-Zeiger, die von diesen Funktionen zurückgegeben werden, zeigen auf statischen Speicher, der durch nachfolgende Aufrufe geändert werden kann. dbm_delete() stellt den Dateibereich zwar nicht physisch wieder her, macht ihn aber zur weiteren Verwendung verfügbar. Wird die Datenbasis durch Aufrufe von dbm_store() oder dbm_delete() verändert, während die Datenbasis sequenziell mit den Funktionen dbm_firstkey() und dbm_nextkey() durchgegangen wurde, so empfiehlt es sich, mit einem Aufruf von dbm_firstkey() auf den Anfang der Datenbasis zurückzusetzen.
Siehe auch	open(), ndbm.h.