Chapter Contents

Previous

Next

msgrcv

Portability:

UNIX compatible

SYNOPSIS

#include <sys/msg.h>
int msgrcv(int id, void *msg, size_t size, 
           long msgtype,int flags);

DESCRIPTION

The msgrcv function is used to receive a message from an UNIX System Services message queue. The msgtype argument allows the caller to select the type of message to be received.

Note:   See the msgget function description in section msgget for general information about UNIX System Services message queues.  

The id argument to msgrcv specifies the id of the message queue from which messages will be received. This argument is an id, such as the id returned by msgget , not a message queue key, which might be passed as an argument to msgget .

The msg argument should be a pointer to a message buffer into which the received message should be stored. The message buffer should have the following layout:

struct {
   long mtype;     /* message type */
   char mtext[n];  /* message text */
};

where n is an integer constant large enough for the message text.

Note:   You must declare an appropriate type for the messages you receive yourself, as no such type is defined by sys/msg.h . Also the meaning of mtype is not fixed by the message queue protocol, but can be used by the application to establish message types or priorities in any natural way.  

The size argument to msgrcv should be the maximum number of bytes of message text to be received. size should not include the size of the mtype field. If the size of the message text to be received is larger than the size argument, the result depends upon the options specified by the flags argument.

The msgtype argument specifies which message, if any, is received. The argument is interpreted as follows:

• If msgtype is 0 , the first message on the queue is received.

• If msgtype is greater than 0 , the first message whose mtype field is equal to msgtype is received.

• If msgtype is less than zero, a message whose mtype field is less than or equal to -msgtype is received. If there is more than one such message, the first one of minimal mtype value is received.

The flags argument specifies zero or more option flags specifying processing options. The argument should be specified as 0 for no flags, or as one or more of the following symbolic constants, combined using the or operator (|):

• IPC_NOWAIT - Specifies that the caller does not wish to wait if there is no appropriate message on the queue. In this case, msgrcv fails, and errno is set to ENOMSG . If IPC_NOWAIT is not set and there is no appropriate message, the caller will wait until an appropriate message is sent, the message queue is destroyed, or a signal is received.

• MSG_NOERROR - Specifies that receiving a message whose text is larger than the size argument is not to be considered an error. In this case, the message text will be truncated and no indication of the truncation is returned. If MSG_NOERROR is not specified and the message to be received is larger than the size argument, the msgrcv call fails, and errno is set to E2BIG .

RETURN VALUE

If successful, msgrcv returns the number of bytes of message text stored (not including the mtype field). If it fails, msgrcv returns -1 .

USAGE NOTES

The msgrcv function can only be used with MVS 5.2.2 or a later release.

EXAMPLE 1

Refer to msgget for an example.

EXAMPLE 2

Refer to msgctl for an example that establishes an IPC Server using Message Queues.

RELATED FUNCTIONS

msgctl , msgget , msgsnd , msgxrcv

Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.