rpc_clnt_create(3N) rpc_clnt_create(3N)
NAME
rpcclntcreate: clntcontrol, clntcreate, clntdestroy,
clntdgcreate, clntpcreateerror, clntrawcreate,
clntspcreateerror, clnttlicreate, clnttpcreate, clntvccreate -
Routinen für die Erzeugung und Manipulation von CLIENT-Handles
BESCHREIBUNG
RPC-Bibliotheksroutinen ermöglichen C-Programmen, Prozeduraufrufe auf
anderen Maschinen über ein Netzwerk durchzuführen. Zuerst wird ein
Client-Handle erzeugt. Danach ruft der Client eine Prozedur auf, um
ein Datenpaket zum Server zu senden. Bei Empfang des Pakets ruft der
Server eine Verteilerfunktion auf, um den angeforderten Dienst durch-
zuführen, und sendet eine Antwort zurück.
Wenn Sie eine der rpc-Funktionen verwenden, müssen Sie bei der Über-
setzung die Bibliothek libnsl dazubinden (cc -lnsl).
Routinen
Die Definition der Datenstruktur CLIENT ist unter rpc(3N) beschrieben.
#include <rpc/rpc.h>
boolt
clntcontrol(CLIENT *clnt, const uint req, char *info);
Ein Funktionsmakro, der verwendet wird, um Informationen über ein
Client-Handle zu lesen oder zu ändern. req zeigt den Typ der Ope-
ration an und info ist ein Zeiger auf die Information. Für ver-
bindungslosen und verbindungsorientierten Transport sind die mög-
lichen Werte von req und deren Argumenttypen die folgenden:
CLSETTIMEOUT struct timeval setze Zeitlimit für RPCs
CLGETTIMEOUT struct timeval hole Zeitlimit für RPCs
Hinweis: Wenn Sie das Zeitlimit mittels clntcontrol setzen, wird
der Zeitlimit-Parameter für clntcall bei allen späteren Aufrufen
ignoriert.
CLGETFD int hole Dateideskriptor des Handle
CLGETSVCADDR struct netbuf hole Server-Adresse
CLSETFDCLOSE int schließe Datei, wenn Client-Handle
gelöscht wird [siehe clntdestroy]
CLSETFDNCLOSE int schließe Datei nicht, wenn
Client-Handle gelöscht wird
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
rpc_clnt_create(3N) rpc_clnt_create(3N)
Folgende Operationen sind nur für verbindungslosen Transport gül-
tig:
CLSETRETRYTIMEOUT struct timeval setze Zeitlimit für
Sendewiederholung
CLGETRETRYTIMEOUT struct timeval hole Zeitlimit für
Sendewiederholung
Das Zeitlimit für Sendewiederholung ist die Zeit, die der Client
auf die Antwort des Servers wartet, bevor die Anfrage nochmals
gesendet wird.
clntcontrol liefert bei erfolgreicher Durchführung 1 und bei
Fehler 0 zurück.
CLIENT *
clntcreate(const char *host, const ulong prognum,
const ulong versnum, const char *nettype);
Dies ist eine generische Erzeugungsroutine für Handles von
Clients des RPC-Dienstes und der Programmnummer prognum und der
Versionsnummer versnum. host gibt den Namen des fernen Hosts an,
auf dem sich der Server befindet. nettype gibt die Klasse des zu
verwendenden Transportprotokolls an. Die Transporte werden in der
Reihenfolge von links nach rechts in der Variablen NETPATH und
von oben nach unten in der netconfig-Datei ausprobiert.
clntcreate probiert alle Transporte der Klasse nettype durch,
die in der Variable NETPATH oder der in netconfig-Datenbank zur
Verfügung stehen, und wählt den ersten Transport aus, der zum
Erfolg führt. Es sind Standardzeitlimits gesetzt, die jedoch mit-
tels clntcontrol verändert werden können.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
rpc_clnt_create(3N) rpc_clnt_create(3N)
void
clntdestroy(CLIENT *clnt);
Ein Funktionsmakro, der das RPC-Client-Handle löscht. Dies
schließt normalerweise auch das Löschen privater Datenstrukturen
mit ein (einschließlich clnt selbst). Die Benutzung von clnt ist
nach dem Aufruf von clntdestroy nicht mehr erlaubt. Falls die
entsprechende Datei von der RPC-Bibliothek geöffnet oder
CLSETFDCLOSE mittels clntcontrol gesetzt wurde, wird die Datei
geschlossen.
CLIENT *
clntdgcreate(const int fd, const struct netbuf *svcaddr,
const ulong prognum, const ulong versnum,
const uint sendsz, const uint recvsz);
Diese Routine erzeugt ein RPC-Client-Handle für das ferne Pro-
gramm prognum der Version versnum. Der Client benutzt dabei einen
verbindungslosen Transport. Das ferne Programm ist unter der
Adresse svcaddr zu finden. Der Parameter fd ist ein Dateideskrip-
tor für die Gerätedatei des Transportes (z. B. /dev/udp). Die
Routine wird die Aufrufsnachricht alle 15 Sekunden wiederholen.
Das Zeitlimit für Sendewiederholungen verdoppelt sich bei jeder
Wiederholung. Die Routine wiederholt den Aufruf, bis ein Zeitli-
mit erreicht wird. Dieses Zeitlimit für den gesamten RPC wird
durch clntcall festgelegt [siehe clntcall unter
rpcclntcalls(3N)]. Die Routine liefert im Fehlerfall NULL
zurück. Das Zeitlimit-Intervall für die Aufrufwiederholung und
das Zeitlimit für den gesamten RPC können mittels clntcontrol
verändert werden. Der Benutzer kann die Größe des Sende- und Emp-
fangspuffers mit den Parametern sendsz und recvsz festlegen. Bei
Angabe von 0 werden geeignete Standardwerte verwendet.
void
clntpcreateerror(const char *s);
Wird für die Ausgabe einer Meldung auf die Standardausgabe ver-
wendet, die anzeigt, warum ein RPC-Client-Handle nicht erzeugt
werden konnte. Vor die Meldung wird der String s und ein Doppel-
punkt gesetzt, und hinter die Meldung ein Zeilenendezeichen.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
rpc_clnt_create(3N) rpc_clnt_create(3N)
CLIENT *
clntrawcreate(const ulong prognum, const ulong versnum);
Diese Routine erzeugt ein RPC-Client-Handle für Pseudo-RPC. prog-
num und versnum sind die Programm- bzw. Versionsnummer des RPC-
Dienstes. Der Transport, der für die Übergabe von Nachrichten an
den Dienst verwendet wird, ist kein "echter" Transport, sondern
ein Puffer innerhalb des Prozeßadreßraums. Daher sollte sich der
entsprechende Server in demselben Adreßraum befinden [siehe
svcrawcreate unter rpcclntcalls(3N)]. Dies ermöglicht eine
Simulation von RPC-Diensten, ohne den Kern mit einzubeziehen.
clntrawcreate liefert im Fehlerfall NULL zurück. Sie sollte
erst nach Aufrufen von svcrawcreate aufgerufen werden.
char *
clntspcreateerror(const char *s);
Entspricht clntpcreateerror, bis auf den Unterschied, daß statt
auf die Standardausgabe zu schreiben, ein String zurückgegeben
wird. Es wird in diesem Fall auch kein Zeilenendezeichen an das
Ende der Meldung gehängt.
Warnung: Es wird ein Zeiger auf einen statischen Datenbereich
zurückgegeben, der somit bei jedem Aufruf überschrieben wird.
CLIENT *
clnttlicreate(const int fd, const struct netconfig *netconf,
const struct netbuf *svcaddr, const ulong prognum,
const ulong versnum, const uint sendsz,
const uint recvsz);
Diese Routine erzeugt ein Handle für Clients des RPC-Dienstes mit
der Programmnummer prognum der Versionsnummer versnum. Das ferne
Programm befindet sich an der Adresse svcaddr. Wenn svcaddr NULL
ist, und der Transport verbindungsorientiert ist, wird angenom-
men, daß für den Dateideskriptor eine Verbindung besteht. Für
verbindungslose Transporte wird der Fehler RPCUNKNOWNADDR
gesetzt, wenn svcaddr NULL ist. fd ist ein Dateideskriptor einer
Datei, der geöffnet und an eine Adresse gebunden sein kann. Falls
er den Wert RPCANYFD hat, wird eine Datei auf dem Transport
geöffnet, der durch netconf spezifiziert ist. Falls netconf NULL
ist, wird der Fehlerwert RPCUNKNOWNPROTO gesetzt. Falls fd nicht
gebunden ist, wird versucht, den Dateideskriptor zu binden.
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98
rpc_clnt_create(3N) rpc_clnt_create(3N)
Der Benutzer kann die Größe der Puffer durch die Parameter sendsz
und recvsz festlegen. Bei Angabe von 0 werden geeignete Standard-
werte gewählt. Abhängig vom Transporttyp (verbindungsorientiert
oder verbindungslos) ruft clnttlicreate die entsprechenden
Client-Erzeugungsroutinen auf. Diese Routine liefert im Fehler-
fall NULL zurück. Die Routine clntpcreaterror kann dazu verwen-
det werden, die Ursache des Fehlers auszugeben. Der ferne Dienst
rpcbind [siehe rpcbind(1M)] wird für die Bestimmung der Adresse
des fernen Dienstes nicht in Anspruch genommen.
CLIENT *
clnttpcreate(const char *host, const ulong prognum,
const ulong versnum, const struct netconfig *netconf);
clnttpcreate erzeugt ein Client-Handle für den in netconf spe-
zifizierten Transport. Es werden Standardoptionen gesetzt, die
mittels eines clntcontrol-Aufrufs geändert werden können. Für
die Ermittlung der Adresse des fernen Dienstes wird der ferne
Dienst rpcbind auf dem Host host in Anspruch genommen. Falls ein
Fehler auftritt, liefert die Routine NULL zurück. Die Routine
clntpcreaterror kann dazu verwendet werden, die Ursache eines
Fehlers auszugeben.
CLIENT *
clntvccreate(const int fd, const struct netbuf *svcaddr,
const ulong prognum, const ulong versnum,
const uint sendsz, const uint recvsz);
Diese Routine erzeugt ein RPC-Client-Handle für den RPC-Dienst
mit der Programmnummer prognum und der Versionsnummer versnum.
Der Client verwendet einen verbindungsorientierten Transport. Das
ferne Programm befindet sich an der Adresse svcaddr. Der Parame-
ter fd ist ein Dateideskriptor einer geöffneten Datei und an eine
Adresse gebunden. Der Benutzer kann die Größe des Sende- und Emp-
fangspuffers durch die Parameter sendsz und recvsz angeben. Bei
Angabe des Wertes 0 werden geeignete Standardwerte genommen. Die
Routine liefert im Fehlerfall NULL zurück.
Die Adresse svcaddr sollte nicht NULL sein, sondern sollte auf
die aktuelle Adresse des fernen Programms zeigen. clntvccreate
nimmt für diesen Dienst nicht den fernen Dienst rpcbind in
Anspruch.
SIEHE AUCH
rpcbind(1M), rpc(3N), rpcclntauth(3N), rpcclntcalls(3N).
Seite 5 Reliant UNIX 5.44 Gedruckt 11/98