msgxrcv (Subroutine)

Zweck

Empfängt eine erweiterte Nachricht.

Bibliothek

Standard-C-Bibliothek (libc.a)

Syntax

#include <sys/msg.h>

int msgxrcv (MessageQueueID, MessagePointer, MessageSize, MessageType, MessageFlag) int MessageQueueID, MessageFlag; size_t MessageSize; struct msgxbuf * MessagePointer; long MessageType;

Beschreibung

Das Unterprogramm msgxrcv liest eine Nachricht aus der durch den Parameter MessageQueueID angegebenen Warteschlange und speichert sie in dem erweiterten Nachrichtenempfangspuffer, auf den der Parameter MessagePointer zeigt. Der aktuelle Prozess muss Leseberechtigung haben, um diese Operation ausführen zu können. Die Struktur msgxbuf ist in der Datei sys/msg.h definiert.

Hinweis: Die Routine kann einen Kernspeicherauszug erstellen, anstatt EFAULT zurückzugeben, wenn ein ungültiger Zeiger übergeben wird, wenn eine 64-Bit-Anwendung eine 32-Bit-Kernelschnittstelle aufruft.

Für die Nachrichtenwarteschlange gelten folgende Grenzwerte:

Die maximale Nachrichtengröße beträgt 4 Megabyte.
Die maximale Anzahl Nachrichten pro Warteschlange beträgt 8192.
Die maximale Anzahl von Nachrichtenwarteschlangen-IDs ist 131072.
Die maximale Anzahl von Bytes in einer Warteschlange beträgt 4 Megabyte.

Hinweis Bei einem 64-Bit-Prozess ist das Feld mtype 64 Bit lang. Aus Gründen der Kompatibilität mit 32-Bit-Prozessen muss das Feld mtype jedoch einen 32-Bit-Wert mit Vorzeichen enthalten, der auf 64 Bit erweitert ist. Die höchstwertigen 32 Bit werden nicht in die Nachrichtenwarteschlange eingereiht. Bei einem 64-Bit-Prozess wird das Feld mtype erneut auf 64 Bit erweitert.

Parameter

Element	Beschreibung
MessageQueueID	Gibt die ID der Nachrichtenwarteschlange an.
MessagePointer	Gibt einen Zeiger auf einen erweiterten Nachrichtenempfangspuffer an, in dem eine Nachricht gespeichert wird
MessageSize	Gibt die Größe des`mtext`Feld in Byte. Die empfangene Nachricht wird auf die mit dem Parameter MessageSize angegebene Größe abgeschnitten, wenn sie größer als der Parameter MessageSize ist und der Wert für MSG_NOERROR auf 'true' gesetzt ist. Der abgeschnittene Teil der Nachricht geht verloren und dem aufrufenden Prozess wird kein Hinweis auf das Abschneiden gegeben. Wenn die Nachricht länger als die durch den Parameter MessageSize angegebene Anzahl Byte ist und der Wert MSG_NOERROR nicht festgelegt ist, ist die Subroutine msgxrcv nicht erfolgreich und setzt die globale Variable errno auf den Fehlercode E2BIG .
MessageType	Gibt den Typ der angeforderten Nachricht wie folgt an: Wenn der Parameter MessageType gleich 0 ist, wird die erste Nachricht in der Warteschlange empfangen. Wenn der Parameter MessageType größer als 0 ist, wird die erste Nachricht des mit dem Parameter MessageType angegebenen Typs empfangen. Wenn der Parameter MessageType kleiner als 0 ist, wird die erste Nachricht des niedrigsten Typs, die kleiner-gleich dem absoluten Wert des Parameters MessageType ist, empfangen.
MessageFlag	Gibt den Wert 0 oder einen Wert an, der durch logisches ODER mit einem oder mehreren der folgenden Werte erstellt wurde: MSG_NOERROR Schneidet die Nachricht ab, wenn sie länger als die mit dem Parameter MessageSize angegebene Anzahl Byte ist. IPC_NOWAIT Gibt die Aktion an, die ausgeführt werden soll, wenn sich eine Nachricht des gewünschten Typs nicht in der Warteschlange befindet: Wenn der Wert IPC_NOWAIT gesetzt ist, gibt der aufrufende Prozess den Wert -1 zurück und setzt die globale Variable errno auf den Fehlercode ENOMSG. Wenn der Wert IPC_NOWAIT nicht festgelegt ist, setzt der aufrufende Prozess die Ausführung aus, bis einer der folgenden Fälle eintritt: Eine Nachricht des gewünschten Typs wird in die Warteschlange gestellt. Die durch den Parameter MessageQueueID angegebene Kennung der Nachrichtenwarteschlange wird aus dem System entfernt. In diesem Fall wird die globale Variable errno auf den EIDRM-Fehlercode gesetzt, und es wird der Wert -1 zurückgegeben. Der aufrufende Prozess empfängt ein Signal, das abgefangen werden soll. In diesem Fall wird keine Nachricht empfangen und der aufrufende Prozess wird in der in der Subroutine sigaction vorgeschriebenen Weise fortgesetzt.

Rückgabewerte

Nach erfolgreichem Abschluss gibt die Subroutine msgxrcv einen Wert zurück, der der Anzahl der tatsächlich in dermtextund die folgenden Aktionen werden in Bezug auf die mit dem Parameter MessageQueueID verbundene Datenstruktur durchgeführt:

Dermsg_qnumwird um 1 verringert.
Dermsg_lrpidFeld wird auf die Prozess-ID des aufrufenden Prozesses gesetzt.
Dermsg_rtimeFeld wird auf die aktuelle Uhrzeit gesetzt.

Wenn das Unterprogramm msgxrcv nicht erfolgreich ist, wird ein Wert von -1 zurückgegeben und die globale Variable errno gesetzt, um den Fehler anzuzeigen.

Fehlercodes

Die Subroutine msgxrcv ist nicht erfolgreich, wenn eine der folgenden Bedingungen zutrifft:

Element	Beschreibung
EINVAL	Der Parameter MessageQueueID ist kein gültiger Bezeichner für die Nachrichtenwarteschlange.
EACCES	Dem aufrufenden Prozess wird die Berechtigung für die angegebene Operation verweigert.
EINVAL	Der Parameter MessageSize ist kleiner als 0.
E2BIG	Der`mtext`ist größer als der Wert des Parameters MessageSize und der Wert MSG_NOERROR ist nicht festgelegt.
ENOMSG	Die Warteschlange enthält keine Nachricht des gewünschten Typs und der Wert IPC_NOWAIT wird festgelegt.
EFAULT	Der Parameter MessagePointer verweist außerhalb des Prozessadressraums.
EINTR	Die Subroutine msgxrcv wurde durch ein Signal unterbrochen.
EIDRM	Die durch den Parameter MessageQueueID angegebene Kennung der Nachrichtenwarteschlange wird aus dem System entfernt.