Chapter Contents |
Previous |
Next |
msgrcv |
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.
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:
msgtype
is
0
, the first message
on the queue is received.
msgtype
is greater than
0
, the
first message whose
mtype
field is equal to
msgtype
is received.
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.