msgrcv() — Message receive operation

Non-Single UNIX Specification, Version 2

#define _XOPEN_SOURCE
#include <sys/msg.h>

int msgrcv(int msgid, void *msgp, size_t msgsz, long int msgtyp, int msgflg);

Single UNIX Specification, Version 2

#define _XOPEN_SOURCE 500
#include <sys/msg.h>

ssize_t msgrcv(int msgid, void *msgp, size_t msgsz, long int msgtyp, int msgflg);

The argument msgp points to a user-defined buffer that must contain first a field of type long int that will specify the type of the message, and then a data portion that will hold the data bytes of the message. The structure below is an example of what this user-defined buffer should look like:

struct message
{
     long int   mtype;    Message type
     int        mtext[n]; Message text
}

The argument msgtyp specifies the type of message requested, as follows:

• 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.

The argument msgflg specifies the action to be taken if a message of the desired type is not on the queue. These are as follows:

• 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.

If successful, the following actions are taken with respect to the data structure, msgiq_ds, associated with msgid:

1. msg_qnum is decremented by 1.
2. msg_lrpid is set equal to the process ID of the calling process.
3. msg_rtime is set equal to the current time.

If unsuccessful, msgrcv() returns -1 and sets errno to one of the following values:

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.