msgrcv() — Message receive operation
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4 |
both |
Format
#define _XOPEN_SOURCE
#include <sys/msg.h>
int msgrcv(int msgid, void *msgp, size_t msgsz, long int msgtyp, int msgflg);
#define _XOPEN_SOURCE 500
#include <sys/msg.h>
ssize_t msgrcv(int msgid, void *msgp, size_t msgsz, long int msgtyp, int msgflg);
General description
The msgrcv() function reads a message from the queue associated with the message queue identifier specified by msgid and places it in the user-defined buffer pointed to by msgp.
struct message
{
long int mtype; Message type
int mtext[n]; Message text
}
The structure member, mtype, is the received message's type as specified by the sending process. The structure member, mtext, is the text of the message.
The argument msgsz specifies the size in bytes of mtext, The received message is truncated to msgsz bytes if it is larger than msgsz and the MSG_NOERROR flag was specified in the argument msgflg. The truncated portion of the message is lost and no indication of the truncation is given to the calling process.
- If msgtyp is equal to zero, the first message on the queue is received.
- If msgtyp is greater than 0, the first message of type, msgtyp, is received.
- If msgtyp is less than 0, the first message of the lowest type that is less than or equal to the absolute value of msgtyp is received.
- If the IPC_NOWAIT flag is on in msgflg, the calling process will return immediately with a return value of -1 and errno set to ENOMSG.
- If the IPC_NOWAIT flag is off in msgflg the
calling process will suspend execution until one of the following
occurs:
- A message of the desired type is placed on the queue.
- The message queue identifier, msgid, is removed from the system; when this occurs, errno is set to EIDRM and a value of -1 is returned.
- The calling process receives a signal that is to be caught; in this case a message is not received and the calling process resumes execution. A value of -1 is returned and errno is set to EINTR.
- msg_qnum is decremented by 1.
- msg_lrpid is set equal to the process ID of the calling process.
- msg_rtime is set equal to the current time.
Returned value
If successful, msgrcv() returns a value equal to the number of bytes actually placed into the mtext field of the user-defined buffer pointed to by msgp. A value of zero indicates that only the mtype field was received from the message queue.
- Error Code
- Description
- E2BIG
- The value of mtext is greater than msgsz and the flag MSG_NOERROR was not specified.
- EACCES
- The calling process does not have read permission to the message queue associated with the message queue identifier msgid or the message queue was built with IPC_RCVTYPEPID and the Message_Type was other than the invoker's process ID (JRTypeNotPID).
- EIDRM
- The message queue identifier, msgid, has been removed from the system while the caller of msgrcv() was waiting.
- EINTR
- The function msgrcv() was interrupted by a signal before a message could be received.
- EINVAL
- The value of argument msgid is not a valid message queue identifier or the value of msgsz is less than zero.
- ENOMSG
- The flag IPC_NOWAIT was specified and the message queue does not contain a message of the desired type.