rpc_clnt_calls(3N) rpc_clnt_calls(3N)
NAME
rpcclntcalls: clntcall, clntfreeres, clntgeterr, clntperrno,
clntperror, clntsperrno, clntsperror, rpcbroadcast, rpccall -
Clientseitige Bibliotheksroutinen für RPC-Aufrufe
BESCHREIBUNG
RPC-Routinen erlauben C-Programmen, Prozeduraufrufe auf anderen
Maschinen über ein Netzwerk durchzuführen. Zuerst ruft der Client eine
Prozedur auf, um ein Datenpaket an den Server zu senden. Dieser ruft
bei Empfang eine Verteilerfunktion auf, um den angeforderten Dienst
durchzuführen, und sendet danach eine Antwort zurück.
Die Routinen clntcall, rpccall und rpcbroadcast behandeln den Pro-
zeduraufruf auf der Client-Seite. Die restlichen Routinen dienen zur
Fehlerbehandlung, die im Falle eines Fehlers durchzuführen ist.
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 in rpc(3N) beschrieben.
#include <rpc/rpc.h>
enum clntstat
clntcall(CLIENT *clnt, const ulong procnum, const xdrproct inproc,
caddrt in, const xdrproct outproc, caddrt out,
const struct timeval tout);
Dies ist ein Funktionsmakro, das die ferne Prozedur procnum
zusammen mit dem Client-Handle clnt aufruft. Das Handle erhält
man durch eine Client-Generierungsroutine von RPC, wie die Rou-
tine clntcreate [siehe rpcclntcreate(3N)]. Der Parameter in
ist die Adresse der Prozedurargumente und out die Adresse, wo die
Ergebnisse abzulegen sind. inproc wird für die Kodierung der Pro-
zedurparameter verwendet und outproc für die Dekodierung der Pro-
zedurergebnisse. tout ist die erlaubte Zeit, in der die Ergeb-
nisse vom Server zurückgeliefert werden müssen.
Falls der ferne Aufruf erfolgreich ist, wird der Status in
RPCSUCCESS zurückgeliefert. Andernfalls wird ein entsprechender
Status zurückgegeben.
int clntfreeres(CLIENT *clnt, const xdrproct outproc, caddrt out);
Dies ist ein Funktionsmakro, das alle Daten freigibt, die durch
das RPC/XDR-System bei der Dekodierung der Ergebnisse eines RPC-
Aufrufs, allokiert wurden. Der Parameter out ist die Adresse der
Ergebnisse und outproc ist die XDR-Routine für die Ergebnisse.
Die Routine liefert 1 zurück, wenn die Ergebnisse erfolgreich
freigegeben wurden, andernfalls wird 0 zurückgegeben.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
rpc_clnt_calls(3N) rpc_clnt_calls(3N)
void
clntgeterr(const CLIENT *clnt, struct rpcerr *errp);
Dieses Funktionsmakro kopiert die Fehlerbeschreibung aus dem
Client-Handle in die Struktur, die sich an der Adresse errp
befindet.
void
clntperrno(const enum clntstat stat);
Gibt eine Meldung auf die Standard-Fehlerausgabe aus, entspre-
chend der Fehlerbedingung, die durch stat angezeigt wird. An das
Ende der Nachricht wird ein Zeilenendezeichen gehängt. Dieser
Aufruf wird normalerweise verwendet, nachdem ein Prozeduraufruf
fehlgeschlagen ist, wie z. B. rpccall.
void
clntperror(const CLIENT *clnt, const char *s);
Gibt eine Meldung auf die Standard-Fehlerausgabe, die anzeigt,
warum der RPC-Aufruf fehlgeschlagen ist. clnt ist das Handle, um
den Aufruf durchzuführen. Vor die Nachricht wird die Zeichenkette
s und ein Doppelpunkt gesetzt. An das Ende der Nachricht wird ein
Zeilenendezeichen angehängt. Dieser Aufruf wird normalerweise
verwendet, nachdem ein Prozeduraufruf fehlgeschlagen ist, wie
z. B. clntcall.
char *
clntsperrno(const enum clntstat stat);
Dieser Aufruf erwartet dieselben Argumente wie clntperrno. Aber
anstatt die Fehlerursache auf die Standard-Fehlerausgabe zu
geben, wird ein Zeiger auf die Zeichenkette zurückgegeben, die
die Meldung enthält.
clntsperrno wird normalerweise als Ersatz für clntperrno ver-
wendet, wenn das Programm keine Standard-Fehlerausgabe besitzt
(ein Programm, das z. B. als Server abläuft, besitzt sehr wahr-
scheinlich keine), oder falls der Programmierer nicht will, daß
die Meldung mit printf [siehe printf(3S)] ausgegeben wird, oder
falls ein Format für die Meldung verwendet werden soll, das sich
von dem Format von clntperrno unterscheidet. Hinweis: Im Gegen-
satz zu clntsperror und clntspcreaterror [siehe
rpcclntcreate(3N)] liefert clntsperrno keinen Zeiger auf sta-
tische Daten zurück, so daß das Ergebnis nicht bei jedem Aufruf
überschrieben wird.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
rpc_clnt_calls(3N) rpc_clnt_calls(3N)
char *
clntsperror(const CLIENT *clnt, const char *s);
Entspricht clntperror, bis auf den Unterschied, daß statt der
Ausgabe der Meldung auf die Standard-Fehlerausgabe, ein String
zurückgegeben wird (wie bei clntsperrno). clntsperror hängt
jedoch kein Zeilenendezeichen an das Ende der Nachricht.
Warnung:
Es wird ein Zeiger auf statische Daten zurückgegeben, die bei
jedem Aufruf überschrieben werden.
enum clntstat
rpcbroadcast(const ulong prognum, const ulong versnum,
const ulong procnum, const xdrproct inproc, caddrt in,
const xdrproct outproc, caddrt out,
const resultproct eachresult, const char *nettype);
Entspricht rpccall, bis auf den Unterschied, daß die Aufrufmel-
dung über einen verbindungslosen Transport gesendet wird, der
durch nettype bestimmt ist. Wenn nettype NULL ist, wird standard-
mäßig netpath genommen. Jedesmal wenn diese Routine eine Antwort
empfängt, ruft sie die Funktion eachresult auf, die folgenderma-
ßen aussieht:
boolt
eachresult(const caddrt out, const struct netbuf *addr,
struct netconfig *netconf);
out entspricht dem Parameter out, der an rpcbroadcast übergeben
wird, bis auf den Unterschied, daß die Ausgabe der fernen Proze-
dur dort verschlüsselt ist. addr zeigt auf die Adresse der
Maschine, die die Ergebnisse gesendet hat. netconf ist die
netconfig-Struktur des Transports, über den der ferne Server
geantwortet hat. Wenn eachresult 0 zurückgibt, wartet
rpcbroadcast auf weitere Antworten. Andernfalls kehrt
rpcbroadcast zurück.
Warnung:
Broadcast-Nachrichten dürfen die maximale Übertragungsgröße des
Transports nicht überschreiten. Für Ethernet ist dieser Wert 1500
Bytes.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
rpc_clnt_calls(3N) rpc_clnt_calls(3N)
enum clntstat
rpccall(const char *host, const ulong prognum,
const ulong versnum, const ulong procnum,
const xdrproct inproc, const xdrproct outproc,
const char *in, char *out, const char *nettype);
Ruft die ferne Prozedur, die prognum, versnum und procnum ent-
spricht, auf der Maschine host auf. Der Parameter in ist die
Adresse der Argumente für die Prozedur, und out ist die Adresse,
wo die Ergebnisse abzulegen sind. inproc wird für die Kodierung
der Prozedurparameter verwendet und outproc für die Dekodierung
der Prozedurergebnisse. nettype kann jeden der in rpc(3N) aufge-
listeten Werte annehmen. Wenn nettype NULL ist, wird standardmä-
ßig netpath genommen.
Die Routine liefert im Erfolgsfall 0 zurück, und im Fehlerfall
den Wert enum clntstat, der auf den Typ Integer angepaßt ist
(cast). Um Fehlerkodes in Meldungen umzuwandeln, müssen Sie die
Routine clntperrno verwenden.
Warnung:
rpccall benutzt den ersten verfügbaren Transport, auf dem es
eine Verbindung aufbauen kann, wobei der Transport zur Klasse
nettype gehört. Bei der Verwendung dieser Routine haben sie keine
Kontrollmöglichkeit über Zeitlimits oder über Identifikationsin-
formationen. Es gibt ebenfalls keine Möglichkeit, das Client-
Handle zu löschen.
SIEHE AUCH
rpc(3N), rpcclntauth(3N), rpcclntcreate(3N), printf(3S).
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98