NAME

msgrcv -  Receives a message from a message queue

SYNOPSIS

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h> int msgrcv(
int msqid,
struct msgbuf ∗msgp,
size_t msgsz,
long msgtyp,
int msgflg);

PARAMETERS

msqidSpecifies the ID of the message queue from which to receive the message. 

msgpSpecifies a pointer to the msgbuf structure that is to receive the message.  See NOTES. 

msgszSpecifies the maximum number of bytes allowed for the received data. 

msgtypSpecifies the message type to read from the queue. 

msgflgSpecifies the action to be taken by the kernel if there are no msgtyp messages on the queue. 

DESCRIPTION

The msgrcv() function receives a message from the queue associated with the msqid parameter.  It returns the number of bytes in the received message. 

The msgp parameter points to a user-defined msgbuf structure.  The structure will receive the message read from the queue. 

The msgsz parameter specifies the maximum size allowed for the received data.  If the message is longer than msgsz, the kernel will take one of the following actions, depending on whether the MSG_NOERROR flag is set:

       •If MSG_NOERROR is not set, the kernel returns an [E2BIG] error to the calling process and leaves the message on the queue. 

       •If MSG_NOERROR is set, the kernel truncates the message to msgsz and discards the truncated portion without notifying the calling process. 

The msgtyp parameter specifies the message type that the process wants to receive.  Possible values and their results are as follows:

0The process receives the message at the head of the queue. 

>0The process receives the first message of the requested positive-integer type. 

<0The process receives the first message of the lowest type on the queue.  To qualify as the lowest type, the negative-integer type must be less than or equal to the absolute value of msgtyp. 

The msgflg parameter specifies the action that the kernel should take if the queue does not contain a message of the requested type.  Either of two kernel actions can be specified, as follows:

       •If IPC_NOWAIT is set, the kernel returns immediately with a return value of -1 and errno set to [ENOMSG]. 

       •If IPC_NOWAIT is not set, the kernel suspends the calling process. 

The process remains suspended until one of the following occurs:

       —
A message of the requested type appears on the queue.  In this case, the kernel wakes the process to receive the message.

       —
The specified message queue ID is removed from the system.  In this case, the kernel sets errno to [EIDRM] and returns -1 to the calling process. 

       —
The process catches a signal.  In this case, the process does not receive the message and, instead, resumes execution as directed by the signal() call. 

NOTES

The user-specified msgbuf structure, used to store received messages, is defined as follows:

struct msgbuf {
mtyp_t mtype;
char mtext[];
}

The mytpe field is set to the message type supplied by the sender. 

The mtext field is set to the message text.  Unless MSG_NOERROR is set, the message size will be less than or equal to the msgsz specified on the call to msgrcv(). 

RETURN VALUES

Upon successful completion, the msgrcv() function returns a value equal to the number of bytes actually stored in mtext.  Also, the kernel updates the msqid_ds structure associated with the message queue ID as follows:

       •Decrements msg_qnum by 1. 

       •Sets msg_lrpid equal to the process ID of the calling process. 

       •Sets msg_rtime equal to the current time. 

       •Decrements msg_cbytes by the message text size. 

When the msgrcv() function fails, a value of -1 is returned and errno is set to indicate the error. 

ERRORS

If the msgrcv() function fails, errno may be set to one of the following values:

[EINVAL]The msqid parameter is not a valid message queue ID, or the msgsz parameter is less than 0 (zero). 

[EACCES]The calling process does not have permission for the operation. 

[EIDRM]The msgid parameter has been removed from the system. 

[E2BIG]The number of bytes to be received in mtext is greater than msgsz and the MSG_NOERROR flag is not set. 

[ENOMSG]The queue does not contain a message of the requested type and the IPC_NOWAIT flag is set. 

[EINTR]The operation was interrupted by a signal. 

RELATED INFORMATION

Functions: msgctl(2), msgget(2), msgsnd(2), sigaction(2)

Data Structures: msqid_ds(4)