msgrcv()

NAME

msgrcv() - read message from a message queue

SYNOPSIS

#include <sys/msg.h>


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

DESCRIPTION

The msgrcv(2) function retrieves a message from the queue associated with the identifier msqid. The message is stored in a user-defined structure indicated by msgp (see msgsnd(2)) and is of the size specified by msgsz.

The type of message to be received is specified by the argument msgtyp. The msgrcv(2) function searches through the queue for messages of that type; if msgtyp is 0, the function returns the first message in the queue. If msgtyp is <0, the function returns the first message whose type is less than or equal to the absolute value of msgtyp.

The msgflg describes what is to be done if there is no message of the appropriate type in the queue:

(msgflg&IPC_NOWAIT) != 0

The calling process does not wait for a message but returns immediately; the function returns a value of -1 and sets errno to [ENOMSG].

(msgflg&IPC_NOWAIT) = 0

The calling process suspends execution until:

• A message of the right type appears in the queue.
• The message queue is removed from the system; the function returns -1 and sets errno to [EIDRM].
• The calling process catches a signal.

Once the function has received a message, the function changes the data structure associated with msqid in these ways:

• msg_qnum is reduced by 1.
• msg_lrpid is set to the process ID of the calling process.
• msg_rtime is set to the current time.

RETURN VALUE

On success, the msgrcv(2) function returns the number of bytes placed into the data buffer of the msgp structure. On failure it returns -1 and sets errno to indicate the error.

ERRORS

[E2BIG]

The message text is larger than msgsz and the MSG_NOERROR flag has not been set (that is, (msgflg is zero).

[EACCES]

The calling process does not have permission to perform that operation.

[EIDRM]

The message queue identifier msqid has been removed from the system.

[EINTR]

The function was interrupted by a signal.

[EINVAL]

The msqid is not a valid message queue identifier or msgsz is less than 0.

[ENOMSG]

There is no message of the desired type in the queue and the IPC_NOWAIT bit is set (that is, (msgflg is non-zero).

SEE ALSO

msgctl(2)

msgget(2)

msgsnd(2)