Chapter Contents

Previous

Next
msgrcv

msgrcv



Receive a Message from a Message Queue

Portability: UNIX compatible


SYNOPSIS
DESCRIPTION
RETURN VALUE
USAGE NOTES
EXAMPLE 1
EXAMPLE 2
RELATED FUNCTIONS


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.  [cautionend]

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.  [cautionend]

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:

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 (|):


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.