putmsg(2) putmsg(2)
NAME
putmsg, putpmsg - Nachricht auf einen Stream senden
SYNTAX
#include <stropts.h>
int putmsg(int fd, const struct strbuf *ctlptr,
const struct strbuf *dataptr, int flags);
int putpmsg(int fd, const struct strbuf *ctlptr,
const struct strbuf *dataptr, int band, int flags);
BESCHREIBUNG
putmsg() erstellt aus dem vom Benutzer angegebenen Puffer eine Nach-
richt und sendet diese an eine STREAMS-Datei. Die Nachricht kann ent-
weder einen Datenteil, einen Steuerteil oder auch beide Teile enthal-
ten. Die zu sendenden Daten- und Steuerteile werden voneinander unter-
schieden, indem sie in verschiedene Puffer geschrieben werden. Die
Semantik jedes Teils ist durch das STREAMS-Modul definiert, das die
Nachricht empfängt.
Die Funktion putpmsg() macht dasselbe wie putmsg(), aber sie gibt dem
Benutzer die Möglichkeit, Nachrichten in verschiedenen Prioritäts-
folgen zu senden. Außer wenn es explizit angegeben wird, gelten alle
Informationen für putmsg() auch für putpmsg().
fd kennzeichnet einen Dateideskriptor, der auf einen offenen Stream
verweist. ctlptr und dataptr weisen jeweils auf eine strbuf-Struktur,
die folgende Elemente enthält:
int maxlen; /* nicht verwendet */
int len; /* Länge der Daten */
void *buf; /* Zeiger auf Puffer für Daten */
ctlptr weist auf die Struktur, die den Steuerteil beschreibt, der in
die Nachricht aufgenommen werden soll. Das Feld buf in der strbuf-
Struktur weist auf den Puffer, in dem die Steuerinformationen stehen,
und das Feld len weist auf die Anzahl der zu sendenden Bytes. Das Feld
maxlen wird in putmsg() nicht verwendet [siehe getmsg(2)]. Auf gleiche
Weise gibt dataptr die Daten an, die in die Nachricht aufgenommen wer-
den sollen. flags gibt an, was für ein Nachrichtentyp gesendet werden
soll.
Zum Senden des Datenteils einer Nachricht muß dataptr ungleich NULL
sein, und das Feld len von dataptr muß einen Wert von 0 oder größer
aufweisen. Zum Senden des Steuerteils einer Nachricht müssen die ent-
sprechenden Werte für ctlptr gesetzt sein. Ein Daten-(Steuer-)Teil
wird nicht gesendet, wenn entweder dataptr (ctlptr) gleich NULL ist
oder das Feld len von dataptr (ctlptr) auf -1 gesetzt ist.
Seite 1 Reliant UNIX 5.44 Gedruckt 11/98
putmsg(2) putmsg(2)
Wird bei putmsg() ein Steuerteil angegeben, und ist flags auf RSHIPRI
gesetzt, wird eine Nachricht mit hoher Priorität geschickt. Ist kein
Steuerteil angegeben und flags auf RSHIPRI gesetzt, ist putmsg()
erfolglos und setzt errno auf EINVAL. Wenn flags auf 0 gesetzt ist,
wird eine normale (keine Priorität) Nachricht geschickt. Sind kein
Steuerteil und kein Datenteil angegeben und ist flags auf 0 gesetzt,
wird keine Nachricht gesendet, und 0 wird zurückgegeben.
Für putpmsg() sind die Optionen anders: flags ist eine Bitmaske, mit
den sich gegenseitig ausschließenden Optionen MSGHIPRI und MSGBAND.
Wenn flags auf 0 gesetzt ist, scheitert putpmsg() und setzt errno auf
EINVAL. Wenn ein Steuerteil angegeben ist und flags auf MSGHIPRI und
band auf 0 gesetzt sind, wird eine Nachricht mit hoher Priorität
gesendet. Wenn flags auf MSGHIPRI gesetzt ist, und entweder kein
Steuerteil angegeben ist oder band auf einen Wert ungleich Null
gesetzt ist, scheitert putpmsg() und setzt errno auf EINVAL. Wenn
flags auf MSGBAND gesetzt ist, wird eine Nachricht in der durch band
angegebenen Prioritätsklasse gesendet. Wenn kein Steuer- und kein
Datenteil angegeben und flags auf MSGBAND gesetzt ist, wird keine
Nachricht gesendet und 0 zurückgegeben.
Normalerweise blockiert putmsg(), wenn die Schreibwarteschlange des
Streams aufgrund von internen Kontrollflußbedingungen voll ist. Bei
Nachrichten mit hoher Priorität blockiert putmsg() bei dieser Bedin-
gung nicht. Bei anderen Nachrichten blockiert putmsg() nicht, wenn die
Schreibwarteschlange voll und ONDELAY oder ONONBLOCK gesetzt ist.
Statt dessen bleibt der Aufruf erfolglos, und errno wird auf EAGAIN
gesetzt.
putmsg() oder putpmsg() blockieren auch, wenn sie auf die Verfügbar-
keit von von Nachrichtenblöcken im Stream warten, unabhängig von der
Priorität und ONDELAY oder ONONBLOCK. Eine Teilnachricht wird nicht
gesendet.
FEHLER
Die folgenden Beschreibungen der Fehlercodes sind funktionsspezifisch.
Eine allgemeingültige Beschreibung finden Sie in introprm2(2) bzw. in
errno(5).
putmsg() ist erfolglos, wenn einer oder mehrere der nachstehenden
Punkte zutreffen:
EAGAIN Eine Nachricht ohne Priorität wurde angegeben, der Anzeiger
ONDELAY oder ONONBLOCK ist gesetzt, und die Schreibwar-
teschlange des Streams ist aufgrund von internen Kontroll-
flußbedingungen blockiert.
EBADF fd ist kein gültiger zum Schreiben offener Dateideskriptor.
EFAULT ctlptr oder dataptr weisen über den zugewiesenen Adreßraum
hinaus.
Seite 2 Reliant UNIX 5.44 Gedruckt 11/98
putmsg(2) putmsg(2)
EINTR Ein Signal wurde während des Systemaufrufs putmsg() abgefan-
gen.
EINVAL Ein undefinierter Wert wurde in flags angegeben, oder flags
ist auf RSHIPRI gesetzt, und kein Steuerteil wurde bereit-
gestellt.
EINVAL Der Stream, auf den fd zeigt, ist über einen Multiplexer
angeschlossen.
EINVAL Bei putpmsg(): flags ist auf MSGHIPRI gesetzt, und band ist
ungleich Null.
ENOSR Für die zu erstellende Nachricht konnte wegen zu geringem
STREAMS-Speicherplatz kein Puffer zugewiesen werden.
ENOSTR Zu fd gehört kein Stream.
ENXIO Ein Hangup wurde streamabwärts für den angegebenen Stream
generiert, oder das andere Ende der Pipe ist geschlossen.
ERANGE Die Größe des Datenteils der Nachricht liegt nicht in dem
Bereich, der durch die maximale und minimale Paketgröße des
obersten Stream-Moduls angegeben wurde. Dieser Wert wird
auch zurückgegeben, wenn der Steuerteil der Nachricht größer
als die maximale konfigurierte Größe des Steuerteils einer
Nachricht ist, oder wenn der Datenteil einer Nachricht grö-
ßer als die maximal konfigurierte Größe des Datenteils einer
Nachricht ist.
putmsg() ist auch erfolglos, wenn eine STREAMS-Fehlermeldung den
Stream-Kopf vor dem Aufruf von putmsg() erreicht hat. Bei dem zurück-
gegebenen Fehler handelt es sich um den Wert, der in der STREAMS-
Fehlermeldung enthalten ist.
ERGEBNIS
Nach erfolgreicher Beendigung wird 0 zurückgegeben. Andernfalls wird
-1 zurückgegeben, und errno wird zur Anzeige des Fehlers gesetzt.
HINWEISE
Wenn zwei Prozesse eine FIFO-Datei eröffnen, wobei der eine mit
putmsg() eine Nachricht hoher Priorität schreibt und der andere mit
getmsg() eine Nachricht hoher Priorität liest, können Nachrichten ver-
lorengehen. Dieser Verlust kann vermieden werden, wenn der Sendeprozeß
durch sleep zwischen den einzelnen putmsg()-Aufrufen verlangsamt wird.
SIEHE AUCH
getmsg(2), poll(2), putmsg(2), read(2), write(2), stropts(5).
"Leitfaden für Programmierer: STREAMS".
Seite 3 Reliant UNIX 5.44 Gedruckt 11/98