ypclnt(3N) ypclnt(3N)
NAME
ypclnt: ypgetdefaultdomain, ypbind, ypunbind, ypmatch, ypfirst,
ypnext, ypall, yporder, ypmaster, yperrstring, ypproterr - NIS-
Client-Schnittstellen
SYNTAX
#include <rpcsvc/ypclnt.h>
#include <rpcsvc/ypprot.h>
BESCHREIBUNG
Dieses Funktionspaket bietet eine Schnittstelle zum Netz-Informations-
dienst NIS an. Das Paket wird mit der Standardbibliothek
/usr/lib/libnsl.so gebunden. Ein Überblick der NIS-Dienste ist unter
ypfiles(4) und ypserv(1M) zu finden, wo auch die Definition von map
und domain und eine Beschreibung von verschiedenen Servern, Dateien
und Kommandos von NIS zu finden ist.
Alle Namen der Eingabeparameter beginnen mit in. Ausgabeparameter
beginnen mit out. Ausgabeparameter vom Typ char ** sollten Adressen
von nicht initialisierten Zeigern sein. Speicher wird durch das NIS-
Client-Paket mittels malloc() angelegt und kann freigegeben werden,
wenn er nicht mehr benötigt wird. Für jedes outkey und outval werden
am Ende zwei zusätzliche Bytes reserviert, die jeweils ein NEWLINE und
NULL enthalten. Diese zwei Bytes werden jedoch nicht in outkeylen oder
outvallen angezeigt. Die Zeichenketten indomain und inmap dürfen nicht
NULL sein und müssen mit NULL enden. Zeichenkettenparameter, die noch
einen Zählparameter besitzen, dürfen nicht NULL sein, können jedoch
auf NULL-Zeichenketten verweisen, wobei der Zählparameter dies
anzeigt. Strings mit einem Zähler müssen nicht mit NULL enden.
Alle Funktionen des Typs int aus diesem Paket liefern im Erfolgsfall 0
zurück, ansonsten einen Fehlercode (YPERRxxxx). Fehlercodes werden
unten bei DIAGNOSE beschrieben.
Routinen
int ypbind(char *indomain);
Um den NIS-Dienst zu verwenden, muß der Client-Prozeß mit einem
NIS-Server, der die entsprechende Domäne bedient, mittels
ypbind() gebunden werden. Das Binden muß jedoch nicht explizit
von der Anwendung durchgeführt werden.
ypunbind(char *indomain);
Jede Bindung legt einen Socket-Deskriptor des Client-Prozesses
an. Jede gebundene Domäne nimmt einen Socket-Deskriptor in
Anspruch. Mehrere Anfragen für dieselbe Domäne nehmen jedoch nur
einen Deskriptor in Anspruch. Prozessen, die ihre Socket-
Deskriptoren beim Zugriff auf mehrere Domänen explizit verwalten,
steht ypunbind() an der Client-Schnittstelle zur Verfügung. Der
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
ypclnt(3N) ypclnt(3N)
Aufruf von ypunbind() löst die Bindung der Domäne auf (unbound)
und gibt für diesen Prozeß und den Knoten alle Betriebsmittel
frei, die zur Verbindung verwendet wurden.
Wenn für eine Bindung ein RPC-Fehler auftritt, wird die Bindung
dieser Domäne automatisch aufgelöst. In diesem Fall wird die
ypclnt()-Funktion solange wiederholt, bis die Operation erfolg-
reich ist, vorausgesetzt, ypbind läuft und entweder
- der Client-Prozeß keinen Server an die Domäne binden kann oder
- RPC-Aufträge an den Server fehlschlagen.
Wenn ein anderer als ein RPC-Fehler auftritt, oder wenn ypbind
nicht läuft, oder wenn ein gebundener ypserv-Prozeß eine Antwort
zurückliefert (Erfolg oder Mißerfolg), übergibt die ypclnt-Ebene
die Kontrolle wieder an den Benutzer zusammen mit den Ergebnissen
und dem entsprechenden Rückgabecode.
int ypgetdefaultdomain(char **outdomain);
Die NIS-Informationsfunktionen erwarten zumindest einen Mapnamen
und einen Domänennamen. Es wird vorausgesetzt, daß der Client-
Prozeß den Namen der entsprechenden Map kennt. Client-Prozesse
können die Standarddomäne des Knotens durch den Aufruf von
ypgetdefaultdomain() ermitteln, und den zurückgelieferten
Domänennamen outdomain als den Eingabe-Domänenparameter indomain
für weitere NIS-Funktionen verwenden.
int ypmatch(char *indomain, char *inmap, char *inkey,
int inkeylen, char **outval, int *outvallen);
ypmatch() liefert den entsprechenden Wert zu dem übergebenen
Schlüssel zurück. Dieser Schlüssel muß genau stimmen, da keine
Mustersuche (pattern matching) durchgeführt wird.
int ypfirst(char *indomain, char *inmap, char **outkey,
int *outkeylen, char **outval, int *outvallen);
ypfirst() liefert das erste Schlüssel/Wertepaar der angegebenen
Map in der angegebenen Domäne zurück.
int ypnext(char *indomain, char *inmap, char *inkey,
int inkeylen, char **outkey, int outkeylen,
char **outval, int *outvallen);
ypnext() liefert das nächste Schlüssel/Wertepaar einer angegebe-
nen Map zurück. Der Parameter inkey sollte der Ausgabeparameter
outkey des ersten ypfirst()-Aufrufs sein (um das zweite Paar zu
bekommen) oder der zurückgelieferte Wert des nten Aufrufs von
ypnext() (um das nte + 1 Paar zu bekommen).
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
ypclnt(3N) ypclnt(3N)
Das sequentielle Lesen der Einträge ist charakteristisch für die
NIS-Maps. Es gibt keine Sortier-Reihenfolge der Schlüssel/Werte-
paare. Die einzige Garantie bezüglich der Reihenfolge, ist die
folgende: Wenn die Funktion ypfirst() für eine bestimmte Map
aufgerufen wird und die Funktion ypnext() wiederholt auf dersel-
ben Map desselben Servers aufgerufen wird, bis der Fehler
YPERRNOMORE zurückgegeben wurde, wird jeder Eintrag der Datenba-
sis genau einmal inspiziert. Weiterhin gilt, wenn die Operationen
in der gleichen Reihenfolge auf der gleichen Map des gleichen
Servers mehrfach aufgerufen wurde, werden die Einträge immer in
derselben Reihenfolge inspiziert.
Unter starker Last des Servers oder bei Serverfehlern ist es mög-
lich, daß die Bindung aufgelöst und daraufhin (eventuell auf
einem anderen Server) wieder eingerichtet wird, während der
Client noch läuft. Es kann vorkommen, daß Einträge vom Client
doppelt oder überhaupt nicht erfaßt werden. Diese Methode verhin-
dert zumindest, daß der Client während der Aufzählung der Ele-
mente Fehlermeldungen erhält. Der nächste Abschnitt erläutert
eine bessere Methode, alle Einträge einer Map zu erhalten.
int ypall(char *indomain, char *inmap,
struct ypallcallback *incallback);
ypall() bietet eine Lösung, um eine Map vom Server zum Client in
einem einzigen auftrag mittels TCP (statt mittels UDP, wie das
bei anderen Funktionen dieses Pakets der Fall ist) zu übertragen.
Die ganze Transaktion wird als ein einziger RPC-Auftrag durchge-
führt und beantwortet. ypall() identifiziert die Map in der
üblichen Art und ruft eine Funktion auf, die alle Einträge inner-
halb der Map verarbeitet. Der Aufruf von ypall() kehrt erst
zurück, wenn die Transaktion vollständig durchgeführt wurde
(erfolgreich oder nicht), oder wenn die Funktion foreach keine
weiteren Schlüssel/Wertepaare mehr verarbeiten will.
Der dritte Parameter von ypall() ist die Struktur
struct ypallcallback *incallback {
int (*foreach)();
char *data;
};
Die Funktion foreach wird in folgender Form aufgerufen:
foreach(instatus, inkey, inkeylen, inval, invallen, indata);
int instatus;
char *inkey;
int inkeylen;
char *inval;
int invallen;
char *indata;
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
ypclnt(3N) ypclnt(3N)
Der Parameter instatus enthält einen der in <rpcsvc/ypprot.h>
definierten Rückgabewerte - entweder YPTRUE oder einen Fehler-
code. Die Funktion ypproterr() unten beschreibt eine Umsetzung
eines Protokollfehlercodes eines NIS-Diensts in einen ypclnt-
Fehlercode.
Der Speicher, auf den durch die Parameter inkey und inval verwie-
sen wird, ist privat für die Funktion ypall() und wird jedesmal
bei Erhalt eines neuen Schlüssel/Wertepaares überschrieben. Es
liegt in der Verantwortlichkeit der Funktion foreach, den Inhalt
dieses Speichers zu sichern bzw. zu verarbeiten, sie hat jedoch
keinen Einfluß darauf, was mit diesem Speicher später geschieht.
Schlüssel- und Wertobjekte, die foreach gegeben werden, haben
genau dieselbe Form, wie in der Map des Servers - wenn sie nicht
mit NEWLINE oder NULL in der Map abgeschlossen sind, werden sie
es hier auch nicht sein.
Der Parameter indata ist der Inhalt des Elements
incallback->data, das an ypall() übergeben wurde. Das Element
data der callback-Struktur kann dazu verwendet werden, Zustand-
sinformation der Funktion foreach und des Hauptprogramms gemein-
sam zu benutzen. Die Verwendung ist optional und kein Teil des
NIS-Client-Pakets überprüft den Inhalt des Elements - setzen Sie
den entsprechenden Typ des Elements (cast).
Die Funktion foreach liefert boolesche Werte zurück. Sie sollte
Null zurückliefern, um anzuzeigen, daß sie nochmals aufgerufen
werden soll, um weitere Schlüssel/Wertepaare zu verarbeiten.
Ansonsten sollte sie einen Wert ungleich Null zurückliefern, um
das Erhalten weiterer Schlüssel/Wertepaare zu stoppen. Wenn
foreach einen Wert ungleich Null zurückliefert, wird sie nicht
noch einmal aufgerufen. Der Wert von ypall() ist dann 0.
int yporder(char *indomain, char *inmap, int *outorder);
yporder() liefert den Modifikationsstempel (order number) für
eine Map zurück.
int ypmaster(char *indomain, char *inmap, char **outname);
ypmaster() liefert den Namen des Netzverwaltungsrechners für die
gegebene Domäne Map zurück.
char *yperrstring(int incode);
yperrstring() liefert einen Zeiger auf eine Fehlernachricht,
zurück. Die Nachricht wird mit NULL abgeschlossen, enthält jedoch
keinen Punkt oder ein NEWLINE-Zeichen.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
ypclnt(3N) ypclnt(3N)
int ypproterr(unsigned int incode);
ypproterr() erwartet einen NIS-Protokollfehlercode als Eingabe
und liefert einen ypclnt-Fehlercode zurück, der danach als Ein-
gabe für yperrstring() dienen kann.
DIAGNOSE
Alle Integer-Funktionen liefern den Wert 0 zurück, wenn die angefor-
derte Operation erfolgreich war. Im Fehlerfall wird einer der folgen-
den Fehler zurückgegeben:
1 Argumente der Funktion sind falsch
2 RPC-Fehler - Bindung der Domäne wurde aufgelöst
3 Bindung an Server in dieser Domäne nicht möglich
4 Diese Map existiert nicht in der Domäne des Servers
5 Dieser Schlüssel existiert nicht in der Map
6 Interner Fehler bei NIS-Server oder Client
7 Fehler bei Reservierung von Betriebsmitteln
8 Keine weiteren Einträge in Map-Datenbank
9 Kommunikation mit rpcbind nicht möglich
10 Kommunikation mit ypbind nicht möglich
11 Kommunikation mit ypserv nicht möglich
12 Lokaler Domänenname nicht gesetzt
13 NIS-Datenbasis ist fehlerhaft
14 NIS-Version nicht korrekt
15 Zugriffsverletzung
16 Datenbasis wird gerade bearbeitet
DATEIEN
/usr/lib/libnsl.so
SIEHE AUCH
ypserv(1M), malloc(3C), ypupdate(3N), malloc(3X), ypfiles(4).
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98