getmsg(2) getmsg(2)
NAME
getmsg, getpmsg - Meldung aus einem Stream abrufen
SYNTAX
#include <stropts.h>
int getmsg(int fd, struct strbuf *ctlptr, struct strbuf *dataptr,
int *flagsp);
int getpmsg(int fd, struct strbuf *ctlptr, struct strbuf *dataptr,
int *bandp, int *flagsp);
BESCHREIBUNG
getmsg() holt den Inhalt einer Meldung, die in der Lesewarteschlange
des Stream-Kopfs einer STREAMS-Datei steht, und schreibt den Inhalt in
einen vom Benutzer angegebenen Puffer. Die Meldung muß entweder einen
Datenteil, einen Steuerteil oder beide Teile enthalten. Der Daten- und
der Steuerteil der Meldung werden, wie nachstehend beschrieben, in
separate Puffer geschrieben. Die Semantik jedes Teils wird durch das
STREAMS-Modul definiert, das die Meldung generiert hat.
Die Funktion getpmsg() führt das gleiche aus wie getmsg(), aber sie
liefert eine genauere Kontrolle über die Priorität der erhaltenen Mel-
dungen. Außer, wenn es speziell vermerkt wurde, gelten alle Informa-
tionen, die getmsg() betreffen, auch für getpmsg().
fd gibt einen Dateideskriptor an, der auf einen offenen Stream zeigt.
ctlptr und dataptr verweisen je auf eine strbuf-Struktur, die nachste-
hende Komponenten aufweist:
int maxlen; /* Maximale Puffergröße */
int len; /* Länge der Daten */
char *buf; /* Zeiger auf den Puffer */
buf weist auf einen Puffer, in den die Daten bzw. Steuerinformationen
geschrieben werden sollen, und maxlen zeigt die größtmögliche Anzahl
Bytes an, die dieser Puffer aufnehmen kann. Bei der Rückgabe enthält
len die Byteanzahl der tatsächlich empfangenen Daten bzw. Steuerinfor-
mationen, oder der Wert ist 0, wenn der Steuer- oder Datenteil eine
Nullänge aufweist, oder der Wert ist -1, wenn die Meldung keine Daten-
oder Steuerinformationen enthält. flagsp sollte auf eine Ganzzahl ver-
weisen, welche die Art der Meldung, die der Benutzer erhalten kann,
anzeigt. Dieses wird später beschrieben.
ctlptr wird zur Aufnahme des Steuerteils der Meldung und dataptr zur
Aufnahme des Datenteils der Meldung verwendet. Wenn ctlptr (oder
dataptr) NULL ist oder das maxlen-Feld -1 ist, wird der Steuer- (bzw.
Daten-)teil der Meldung nicht verarbeitet und bleibt in der Lesewarte-
schlange des Stream-Kopfes. Wenn ctlptr (oder dataptr) nicht NULL ist
und es keinen korrespondierenden Steuer- (oder Daten-)teil der Meldung
in der Lesewarteschlange des Stream-Kopfes gibt, wird len auf -1
gesetzt. Wenn das maxlen-Feld auf 0 gesetzt ist und ein Steuer- (oder
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
getmsg(2) getmsg(2)
Daten-)teil mit einer Nullänge vorliegt, wird dieser Nullängenteil aus
der Lesewarteschlange entfernt und len auf 0 gesetzt. Wenn das
maxlen-Feld auf 0 gesetzt ist und mehr als 0 Byte Steuer- (oder
Daten-)informationen vorhanden sind, bleiben diese Informationen in
der Lesewarteschlange, und len wird auf 0 gesetzt. Wenn das maxlen-
Feld in ctlptr bzw. dataptr kleiner als der Steuer- oder Datenteil der
Meldung ist, werden maxlen Bytes abgerufen. In diesem Fall wird der
Rest der Meldung in der Lesewarteschlange des Stream-Kopfes gelassen
und ein Return-Wert ungleich Null geliefert, wie nachstehend im
Abschnitt ERGEBNIS beschrieben.
Standardmäßig verarbeitet getmsg() die erste Meldung, die in der Lese-
warteschlange zur Verfügung steht. Der Benutzer kann sich jedoch durch
Setzen der Ganzzahl, auf die flagsp zeigt, auf RSHIPRI, dazu ent-
scheiden, nur Meldungen hoher Priorität zu empfangen. In diesem Fall
verarbeitet getmsg() die nächste Meldung nur, wenn diese eine Meldung
hoher Priorität ist. Wenn die Ganzzahl, auf die durch flagsp verwiesen
wird, 0 ist, ruft getmsg() jede verfügbare Meldung in der Lesewarte-
schlange des Stream-Kopfes ab. In diesem Fall wird bei Rückkehr die
Ganzzahl, auf die durch flagsp verwiesen wird, auf RSHIPRI gesetzt,
wenn eine Meldung hoher Priorität angetroffen wurde, anderenfalls auf
0.
Für getpmsg() sind die Optionen unterschiedlich. flagsp verweist auf
eine Bitmaske mit den folgenden Optionen, die sich gegenseitig aus-
schließen: MSGHIPRI, MSGBAND und MSGANY. Ebenso wie getmsg() verar-
beitet getpmsg() die als nächste zur Verfügung stehende Meldung in der
Lesewarteschlange des Stream-Kopfes. Der Benutzer erhält nur Meldungen
hoher Priorität, indem er die Ganzzahlen, auf die mit flagsp=MSGHIPRI
und bandp=0 verwiesen wird, auf 0 setzt. In diesem Fall verarbeitet
getpmsg() nur dann die nächste Meldung, wenn es eine Meldung hoher
Priorität ist. In ähnlicher Weise kann der Benutzer eine Meldung aus
einem speziellen Prioritätsbereich aufrufen, indem er die Ganzzahl,
auf die durch flagsp verwiesen wird, auf MSGBAND setzt, und die Ganz-
zahl, auf die durch bandp verwiesen wird, auf den gewünschten Priori-
tätsbereich setzt. In diesem Fall verarbeitet getpmsg() nur dann die
nächste Meldung, wenn sie sich in einem Prioritätsbereich befindet,
welcher gleich oder größer als die Ganzzahl ist, auf welche durch
bandp verwiesen wird, oder wenn es sich um eine Meldung hoher Priori-
tät handelt. Wenn ein Benutzer lediglich die erste Meldung in der War-
teschlange abrufen möchte, sollte die Ganzzahl, auf welche durch
flagsp verwiesen wird, auf MSGANY gesetzt sein, und die Ganzzahl, auf
welche durch bandp verwiesen wird, sollte auf 0 gesetzt sein. Bei
Rückkehr wird, in dem Fall, daß die erhaltene Meldung eine Meldung
hoher Priorität war, die Ganzzahl, auf welche durch flagsp verwiesen
wird, auf MSGHIPRI, und die Ganzzahl, auf welche durch bandp verwie-
sen wird, auf 0 gesetzt. Anderenfalls wird die Ganzzahl, auf welche
durch flagsp verwiesen wird, auf MSGBAND gesetzt, und die Ganzzahl,
auf die durch bandp verwiesen wird, wird auf den Prioritätsbereich der
Meldung gesetzt.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
getmsg(2) getmsg(2)
Wenn ONDELAY und ONONBLOCK nicht gesetzt wurden, blockiert getmsg(),
bis eine Meldung des mit flagsp angegebenen Typs in der Lesewarte-
schlange des Stream-Kopfes vorhanden ist. Wenn ONDELAY oder
ONONBLOCK gesetzt wurde und keine Meldung des angegebenen Typs in der
Lesewarteschlange vorhanden ist, bleibt getmsg() erfolglos und setzt
errno auf EAGAIN.
Wenn auf dem Stream, aus dem die Meldungen geholt werden sollen, ein
Verbindungsabbruch auftritt, arbeitet getmsg() normal weiter, wie oben
beschrieben, bis die Lesewarteschlange entleert ist. Danach gibt es 0
in den len-Feldern von ctlptr und dataptr zurück.
FEHLER
Die folgenden Beschreibungen der Fehlercodes sind funktionsspezifisch.
Eine allgemeingültige Beschreibung finden Sie in introprm2(2) bzw. in
errno(5).
getmsg() oder getpmsg() sind erfolglos, wenn einer oder mehrere der
nachstehenden Punkte zutreffen:
EAGAIN ONDELAY oder ONONBLOCK ist gesetzt, und es stehen keine
Meldungen zur Verfügung.
EBADF fd ist kein zum Lesen offener, gültiger Dateideskriptor.
EBADMSG Die zu lesende Meldung in der Warteschlange ist für getmsg()
oder getpmsg() nicht gültig, oder am STREAM-Kopf wartet ein
Dateideskriptor.
EFAULT ctlptr, dataptr, bandp oder flagsp weisen auf eine Stelle
außerhalb des zugewiesenen Adreßraums.
EINTR Ein Signal wurde während des Systemaufrufs getmsg() abgefan-
gen.
EINVAL Ein ungültiger Wert wurde in flagsp angegeben, oder der
durch fd angegebene Stream ist mit einem Multiplexer verbun-
den.
ENOSTR Ein Stream ist keinem fd zugeordnet.
getmsg() kann auch dann erfolglos sein, wenn vor dem Aufruf von
getmsg() eine STREAMS-Fehlermeldung am Stream-Kopf empfangen wurde.
Der zurückgegebene Fehler ist der Wert, der in der STREAMS-Fehlermel-
dung enthalten ist.
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98
getmsg(2) getmsg(2)
ERGEBNIS
Nach erfolgreicher Beendigung wird ein nicht negativer Wert zurückge-
geben. Der Wert 0 zeigt an, daß eine vollständige Meldung erfolgreich
gelesen wurde. Der Return-Wert MORECTL zeigt an, daß weitere Steuerin-
formationen auf einen Abruf warten. Der Rückgabewert MOREDATA zeigt
an, daß weitere Daten auf den Abruf warten. Der Rückgabewert
MORECTL | MOREDATA zeigt an, daß noch beide Arten übrig sind. Der Rest
der Meldung wird mit anschließenden getmsg()-Aufrufen abgerufen. Wenn
jedoch eine Meldung hoher Priorität in dem Stream-Kopf der Lesewarte-
schlange eingetroffen ist, wird der nächste getmsg()-Aufruf die Mel-
dung hoher Priorität vorrangig bearbeiten, bevor der Rest der vorher
empfangenen Teilmeldung bearbeitet wird.
SIEHE AUCH
poll(2), putmsg(2), read(2), write(2), stropts(5).
"Leitfaden für Programmierer: STREAMS".
Seite 4 Reliant UNIX 5.44 Gedruckt 11/98