mesgrcv

The mesgrcv function reads the message from the message queue specified by Qkey (morig) into a buffer pointed to by msgp of size msgsz bytes as shown in the following example. The mesgrcv function creates the message queue if necessary.

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
#include "mesg.h"
#include "spp.h"

int mesgrcv (morig,msgp,msgsz,msgtyp,msgflg,msgrtime)
int morig;
char *msgp; /* message buffer */
int msgtyp; /* type of message to read */
int msgsz; /* size of message buffer */
int msgflag; /* control flag */
long *msgrtime; /* message receive time */

Since the size of the message varies and is unknown before reading, the message must be read into a buffer that is large enough to accommodate the largest message to be received by the DIP. This assures that all known messages are received properly without being truncated or discarded altogether.

The mesgrcv function also allows a DIP to read messages of a particular type (msgtyp). The type of message is defined in the field mtype in the header mbhdr. To read the first message on the queue regardless of its mtype, invoke mesgrcv with the msgtyp argument set to 0 (zero).

The mesgrcv function can be used in two places in a DIP. At initialization, it can be used to clear the message queue. Later, it can be used to read requests as they are received. See Sample DIP for an example.

The msgflag field represents a set of flags that control how mesgrcv reads the messages. By default, mesgrcv waits indefinitely for a message of a specified type to arrive if none are presently on the queue. Many DIPs and voice system processes prefer this because they are message-driven. However, the msgflag field allows you specify that you do not want mesgrcv to wait for a message to arrive. Currently, the flags are:

• IPC_NOWAIT – If on, mesgrcv returns immediately even if no message has arrived. If off (not specified, or 0), mesgrcv sleeps until a message arrives.
• MSG_NOERROR – If on, mesgrcv truncates the received message to msgsz bytes if necessary.
• IPC_GTIME – If on, mesgrcv returns the time (in seconds) when the message was read. The msgrtime field must point to a long if IPC_GTIME is specified; otherwise, set it to NULL.

The msgflag field is formed by bit applying the Boolean "OR" operation (where the operator is |) to turn on all flags. For example, to not wait for a message and obtain the time the message was read (if any are available), pass the following:

IPC_GTIME | IPC_NOWAIT.

IPC_GTIME and MSG_NOERROR is defined in mesg.h and IPC_NOWAIT is defined in ipc.h. If no flags are to be turned on, set msgflag to zero (0).

The mesgrcv function returns the number of bytes read upon successful completion. Otherwise, a negative value is returned.

© 2006 Avaya Inc. All Rights Reserved.