getmsg() holt den Inhalt einer Nachricht, die in der Lese-Queue des Stream-Kopfs einer STREAMS-Datei steht, und schreibt den Inhalt in einen vom Benutzer angegebenen Puffer. Die Nachricht enthält entweder einen Datenteil, einen Steuerteil oder beide Teile. Der Daten- und der Steuerteil der Nachricht werden, wie nachstehend beschrieben, in separate Puffer geschrieben. Die Semantik der Teile wird durch das STREAMS-Modul definiert, das die Nachricht generiert hat.
Die Funktion getpmsg() führt das Gleiche aus wie getmsg(), aber sie liefert eine genauere Kontrolle über die Priorität der erhaltenen Meldungen. Außer, wenn es speziell vermerkt wurde, gelten alle Informationen, die getmsg() betreffen, auch für getpmsg().
fildes gibt einen Dateideskriptor an, der auf einen offenen Stream zeigt.
ctlptr und dataptr verweisen je auf eine strbuf-Struktur, die nachstehende Elemente aufweist:
int maxlen; /* Maximum 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. maxlen zeigt die größtmögliche Anzahl Bytes an, die dieser Puffer aufnehmen kann. Bei der Rückgabe enthält len die Byte-Anzahl der tatsächlich empfangenen Daten bzw. Steuerinformationen, oder der Wert ist 0, wenn der Steuer- oder Datenteil eine Nulllänge aufweist, oder der Wert ist -1, wenn die Nachricht keine Daten- oder Steuerinformationen enthält.
Wenn getmsg() aufgerufen wird, sollte flagsp auf eine Ganzzahl verweisen, welche die Art der Nachricht, die der Benutzer erhalten kann, anzeigt. Dieses wird später beschrieben.
ctlptr wird zur Aufnahme des Steuerteils der Nachricht und dataptr zur Aufnahme des Datenteils der Nachricht verwendet. Wenn ctlptr (oder dataptr) NULL ist oder das maxlen-Feld -1 ist, wird der Steuer- (bzw. Daten-)teil der Nachricht nicht verarbeitet und bleibt in der Lese-Queue des Stream-Kopfes. Wenn ctlptr (oder dataptr) nicht NULL ist und es keinen korrespondierenden Steuer- (oder Daten-)teil der Nachricht in der Lese-Queue des Stream-Kopfes gibt, wird len auf -1 gesetzt. Wenn das maxlen-Feld auf 0 gesetzt ist und ein Steuer- (oder Daten-)teil mit einer Nulllänge vorliegt, wird dieser Nulllängenteil aus der Lese-Queue 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 Lese-Queue, und len wird auf 0 gesetzt. Wenn das maxlen-Feld in ctlptr bzw. dataptr kleiner als der Steuer- oder Datenteil der Nachricht ist, werden maxlen Bytes geholt. In diesem Fall wird der Rest der Nachricht in der Lese-Queue des Stream-Kopfes gelassen und ein Rückgabewert von ungleich null geliefert (siehe Returnwert).
Standardmäßig verarbeitet getmsg() die erste Meldung, die in der Lese-Queue zur Verfügung steht. Wenn die Ganzzahl, auf die flagsp zeigt, auf RS_HIPRI gesetzt ist, empfängt der Prozess nur Meldungen hoher Priorität. In diesem Fall verarbeitet getmsg() die nächste Nachricht nur, wenn diese eine Nachricht hoher Priorität ist. Wenn die Ganzzahl, auf die durch flagsp verwiesen wird, 0 ist, bringt getmsg() jede verfügbare Nachricht in der Lese-Queue des Stream-Kopfes. In diesem Fall wird bei Rückkehr die Ganzzahl, auf die durch flagsp verwiesen wird, auf RS_HIPRI gesetzt, wenn eine Nachricht hoher Priorität angetroffen wurde, andernfalls auf 0.
Für getpmsg() gibt es andere Optionen als für getmsg(). flagsp verweist auf eine Bitmaske mit den folgenden Optionen, die sich gegenseitig ausschließen: MSG_HIPRI, MSG_BAND und MSG_ANY. Ebenso wie getmsg() verarbeitet getpmsg() die als nächste zur Verfügung stehende Nachricht in der Lese-Queue des Stream-Kopfes. Wiederum kann der Benutzer wählen, nur Nachrichten hoher Priorität zu erhalten, indem er die Ganzzahl, auf die mit flagsp verwiesen wird, auf MSG_HIPRI setzt und diejenige, auf die bandp verweist, auf 0. In diesem Fall verarbeitet getpmsg() nur dann die nächste Nachricht, wenn es eine Nachricht hoher Priorität ist. In ähnlicher Weise kann der Benutzer eine Nachricht aus einem speziellen Prioritätsbereich aufrufen, indem er die Ganzzahl, auf die durch flagsp verwiesen wird, auf MSG_BAND setzt, und die Ganzzahl, auf die durch bandp verwiesen wird, auf den gewünschten Prioritätsbereich setzt. In diesem Fall verarbeitet getpmsg() nur dann die nächste Nachricht, 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 Nachricht hoher Priorität handelt. Wenn ein Benutzer lediglich die erste Meldung der Queue abrufen möchte, sollte die Ganzzahl, auf welche durch flagsp verwiesen wird, auf MSG_ANY gesetzt sein, und die Ganzzahl, auf welche durch bandp verwiesen wird, sollte auf 0 gesetzt sein. Falls die erhaltene Nachricht eine Nachricht hoher Priorität war, ist bei der Rückkehr die Ganzzahl, auf welche durch flagsp verwiesen wird, auf MSG_HIPRI, und die Ganzzahl, auf welche durch bandp verwiesen wird, auf 0 gesetzt. Bei allen anderen Nachrichten ist die Ganzzahl, auf die flagsp zeigt, auf MSG_BAND gesetzt, und die Ganzzahl, auf die bandp zeigt, ist auf den Prioritätsbereich der Nachricht gesetzt.
Wenn O_NDELAY und O_NONBLOCK nicht gesetzt wurde, blockieren getmsg() und getpmsg(), bis eine Nachricht des mit flagsp angegebenen Typs in der Lese-Queue des Stre-am-Kopfes vorhanden ist. Wenn O_NDELAY oder O_NONBLOCK gesetzt wurde und keine Nachricht des angegebenen Typs in der Lese-Queue vorhanden ist, bleiben getmsg() und getpmsg() erfolglos, und errno wird auf EAGAIN gesetzt.
Wenn auf dem Stream, aus dem die Nachrichten geholt werden sollen, ein Verbindungsabbruch auftritt, arbeiten getmsg() und getpmsg() normal weiter, wie oben beschrieben, bis die Lese-Queue entleert ist. Danach wird 0 in den len-Feldern von ctlptr und dataptr zurückgegeben.
Wird eine Nachricht mit einem getmsg()- bzw. getpmsg()-Aufruf nicht vollständig gelesen, so kann der Rest der Nachricht mit anschließenden getmsg()- bzw. getpmsg()-Auf-rufen geholt werden. Wenn jedoch eine Nachricht hoher Priorität in dem Stream-Kopf der Lese-Queue eingetroffen ist, bearbeitet der nächste getmsg()- bzw. getpmsg()-Aufruf die Nachricht hoher Priorität vorrangig, bevor der Rest der vorher empfangenen Teilnachricht bearbeitet wird.
