putmsg, putpmsg - Nachricht auf eine STREAMS-Datei senden

Definition	#include <stropts.h> int putmsg(int fildes, const struct strbuf *ctlptr, const struct strbuf *dataptr, int flags); int putpmsg(int fildes, const struct strbuf *ctlptr, const struct strbuf *dataptr, int band, int flags);
Beschreibung	putmsg() erstellt aus den angegebenen Puffern eine Nachricht und sendet diese an eine STREAMS-Datei. Die Nachricht kann entweder einen Datenteil, einen Steuerteil oder beides enthalten. Die zu sendenden Daten- und Steuerteile werden voneinander unterschieden, indem sie in verschiedene Puffer geschrieben werden (siehe unten). Die Semantik der Teile ist durch das STREAMS-Modul definiert, das die Nachricht empfängt. Die Funktion putpmsg() hat dieselbe Funktionalität wie putmsg(), aber sie gibt dem Benutzer die Möglichkeit, Nachrichten mit verschiedenen Prioritäten zu senden. Alle hier für putmsg() beschriebenen Informationen gelten auch für putpmsg(), Ausnahmen werden explizit gekennzeichnet. fildes ist ein 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 in die Nachricht aufzunehmenden Steuerteil beschreibt (falls vorhanden). Das Feld buf in der strbuf-Struktur weist auf den Puffer, in dem die Steuerinformationen stehen, und das Feld len gibt die Anzahl der zu sendenden Bytes an. Das Feld maxlen wird in putmsg() nicht verwendet (siehe getmsg()). Auf gleiche Weise beschreibt dataptr den Datenteil, der in die Nachricht aufgenommen werden soll. flags gibt an, was für ein Nachrichtentyp gesendet werden soll (siehe unten). Zum Senden des Datenteils einer Nachricht muss dataptr ungleich dem Nullzeiger sein, und das Feld len von dataptr muss einen Wert ≥ 0 enthalten. Zum Senden des Steuerteils einer Nachricht müssen die entsprechenden Werte für ctlptr gesetzt sein. Ein Daten-(Steuer-)Teil wird nicht gesendet, wenn entweder dataptr (ctlptr) der Nullzeiger ist oder das entsprechende len-Feld auf -1 gesetzt ist. Wird bei putmsg() ein Steuerteil angegeben, und ist flags auf RS_HIPRI gesetzt, wird eine Nachricht mit hoher Priorität geschickt. Ist kein Steuerteil angegeben und flags auf RS_HIPRI gesetzt, schlägt putmsg() fehl und setzt errno auf EINVAL. Wenn flags auf 0 gesetzt ist, wird eine normale Nachricht geschickt ( Priorität=0). Ist weder ein Steuer- noch ein Datenteil angegeben und ist flags auf 0 gesetzt, wird keine Nachricht gesendet und der Wert 0 zurückgegeben. Der STREAMS-Kopf garantiert, dass der Steuerteil einer von putmsg() erzeugten Nachricht mindestens 64 Bytes lang ist. Für putpmsg() werden andere Flags verwendet: flags ist eine Bitmaske, die entweder MS-G_HIPRI oder MSG_BAND oder 0 enthält (die Werte schließen sich gegenseitig aus). Wenn flags auf 0 gesetzt ist, schlägt putpmsg() fehl und setzt errno auf EINVAL. Wenn ein Steuerteil angegeben ist und flags auf MSG_HIPRI und band auf 0 gesetzt sind, wird eine Nachricht mit hoher Priorität gesendet. Wenn flags auf MSG_HIPRI gesetzt ist, und entweder kein Steuerteil angegeben ist oder band != 0 ist, scheitert putpmsg() und setzt errno auf EINVAL. Wenn flags auf MSG_BAND gesetzt ist, wird eine Nachricht in der durch band angegebenen Prioritätsklasse gesendet. Wenn kein Steuer- und kein Datenteil angegeben und flags auf MSG_BAND gesetzt ist, wird keine Nachricht gesendet und 0 zurückgegeben. Normalerweise blockiert putmsg(), wenn die Schreib-Warteschlange des Streams auf Grund von internen Kontrollfluss-Bedingungen voll ist. Bei Nachrichten mit hoher Priorität blockiert putmsg() in diesem Falle jedoch nicht. Bei anderen Nachrichten blockiert putmsg() nicht bei voller Schreib-Warteschlange, wenn O_NDELAY oder O_NONBLOCK gesetzt ist. Statt dessen schlägt der Aufruf fehl, und errno wird auf EAGAIN gesetzt. putmsg() oder putpmsg() blockieren unabhängig von der Priorität und O_NDELAY oder O_NONBLOCK auch dann, wenn sie auf die Verfügbarkeit von Nachrichtenblöcken im Stream warten. Eine Teilnachricht wird nicht gesendet.
Returnwert	0	bei Erfolg.
	-1	bei Fehler. errno wird gesetzt, um den Fehler anzuzeigen.
Fehler	putmsg() und putpmsg() schlagen fehl, wenn gilt:
	EAGAIN	Eine Nachricht ohne Priorität wurde angegeben, das Flag O_NDELAY oder O_NONBLOCK ist gesetzt, und die Schreib-Warteschlange des STREAM ist auf Grund von internen Kontrollfluss-Bedingungen voll oder für die zu erzeugende Nachricht konnten keine Puffer zugewiesen werden.
	EBADF	fildes ist kein gültiger, zum Schreiben offener Dateideskriptor.
	EINTR	Ein Signal wurde während des Systemaufrufs putmsg() abgefangen.
	EFAULT	ctlptr oder dataptr weisen über den zugewiesenen Adressraum hinaus.
	EINVAL	Ein undefinierter Wert wurde in flags angegeben, oder flags ist auf RS_HIPRI oder MSG_HIPRI gesetzt, und es wurde kein Steuerteil bereitgestellt oder der durch fildes referenzierte STREAM oder Multiplexer ist streamabwärts über einen Multiplexer angeschlossen. nur für putpmsg(): flags ist auf MSG_HIPRI gesetzt und es gilt band != 0.
	ENOSR	Für die zu erstellende Nachricht konnte wegen zu geringem STREAMS-Speicherplatz kein Puffer zugewiesen werden.
	ENOSTR	Zu fildes gehört kein STREAM.
	ENXIO	Ein Hangup wurde streamabwärts für den angegebenen Stream generiert.
	EPIPE oder EIO
		fildes referenziert eine STREAM-basierte Pipe und das andere Ende der Pipe ist geschlossen. Für den rufenden Prozess wird das Signal SIGPIPE erzeugt.
	ERANGE	Der Datenteil der Nachricht hat eine Größe, die nicht in dem Bereich liegt, der durch die maximale und minimale Paketgröße des obersten Stream-Moduls vorgegeben wurde. ERANGE wird auch zurückgegeben, wenn der Steuerteil der Nachricht größer ist als die konfigurierte maximale Größe des Steuerteils einer Nachricht, oder wenn der Datenteil einer Nachricht größer ist als die konfigurierte maximale Größe des Datenteils einer Nachricht.
	putmsg() und putpmsg() schlagen ebenfalls fehl, wenn eine asynchrone STREAMS-Fehlermeldung den Stream-Kopf vor dem Aufruf von putmsg() bzw. putpmsg() erreicht hat. In diesem Fall bezieht sich errno auf den Fehler, der in der STREAMS-Fehlermeldung enthalten ist.
Hinweis	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 verlorengehen. Dieser Verlust kann vermieden werden, wenn der Sendeprozess durch sleep zwischen den einzelnen putmsg() verlangsamt wird.
Siehe auch	auch getmsg(), poll(), read(), write(), stropts.h.