Chapter Contents

Previous

Next

msgxrcv

Portability:

SAS/C extension

SYNOPSIS

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

DESCRIPTION

The msgxrcv 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. Unlike msgrcv , msgxrcv stores information about the time the message was sent and the process which sent the message.

Note:   See the msgget function description in section msgget for general information about UNIX System Services message queues.  
The id argument to msgxrcv 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 {
   /* the time the message was sent */
   time_t mtime;

   /* the effective uid of the sender */
   uid_t muid;

   /* the effective gid of the sender */
   gid_t mgid;

   /* the process id of the sender */
   pid_t mpid;

   /* message type */
   long mtype;

   /* message text */
   char mtext[n];
};

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 msgxrcv should be the maximum number of bytes of message text to be received. size should not include the size of any of the fields preceding mtext in the structure. 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 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, msgxrcv 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 msgxrcv call fails, and errno is set to E2BIG .

RETURN VALUE

If successful, msgxrcv returns the number of bytes of message text stored (not including the header fields). If it fails, msgxrcv returns -1 .

USAGE NOTES

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

PORTABILITY

msgxrcv is an UNIX System Services extension to UNIX message queue processing, and is not portable.

EXAMPLE 1

Refer to msgget for an example that establishes an IPC Client using XMessage Queues.

EXAMPLE 2

Refer to msgctl for an example that establishes an IPC Server using Message Queues. Also, it uses UNIX System Service's extended Message structure.

RELATED FUNCTIONS

msgctl , msgget , msgrcv , msgsnd

Chapter Contents

Previous

Next

Top of Page

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