Sending and Receiving Messages

Once you have a message queue to operate with, and the permissions are properly established, you can read and write messages to them. This section describes the msgsnd(3) and msgrcv(3) functions.

Sending Messages

Messages are sent using the msgsnd(3) function. Its function synopsis is given as follows:

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>

int msgsnd(int msqid, void *msgp, size_t msgsz, int msgflg);

The first argument msqid is the IPC ID of the message queue to send the message on. The argument msgp points to a message structure to be sent. The size of the message msgsz is the message size, not including the message type value. The msgflg argument is specified as 0 unless the flag IPC_NOWAIT is used.

The IPC_NOWAIT allows the msgsnd(3) function to return immediately with the error EAGAIN if the operation would block. Sending a message can block if the message queue has reached its maximum limit for messages or memory use. Sending can also block when the kernel's message resources are limited.

The msgsnd(3) function returns 0 when successful. When -1 is returned, the error is found in the variable errno.

The format of the message structure is shown in the next synopsis:

struct msgbuf {        /* Message Structure */
    long  mtype;       /* message type */
    char  mtext[1];    /* body of message */
};

The first member of the message structure must be a long member to hold the message type (message priority). The actual message itself is shown starting with member mtext[0].

Computing the msgsz argument requires some care. This size argument does not include the mtype member of the structure passed in argument msgp.

The following example shows a message being sent, which contains a simple pathname member path[256]:

int z;
struct {
    long    mtype;
    char    path[256];
}  msg;
int msz;

msz = sizeof msg - sizeof msg.mtype;
z = msgsnd(msqid,&msg,msz,0);
if ( z == -1 )
    perror("msgsnd(3)");

Notice that the variable msz receives the size of the message without counting the size of the message type mtype.

Receiving Messages

Messages are received with the function msgrcv(3). The synopsis for it is as follows:

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>

int msgrcv(int msqid, void *msgp, size_t msgsz, long msgtyp, int msgflg);

The argument msqid is the IPC ID of the message queue to receive the message from. The pointer argument msgp must point to a receiving buffer large enough to hold the received message. The argument msgsz indicates the maximum size of the received message, not including the size of the mtype member. The msgtyp and msgflg members hold the message type (priority) and option flags for this call, respectively.

The msgflg argument can be composed of the following flags:

• The flag IPC_NOWAIT indicates that the function msgrcv(3) will return the error code ENOMSG if there are no messages to receive. Normally, the program is suspended until a message arrives.

• The flag MSG_EXCEPT, when used with the msgtyp argument greater than zero, causes the first message that differs from msgtyp to be received.

• The flag MSG_NOERROR indicates that the message should be truncated if necessary to fit the receiving buffer. The error E2BIG is returned when this option is used and the message cannot fit into the buffer.

Table 23.1 lists the variations that are possible for the msgtyp argument.

When msgrcv(3) is successful, it returns the number of bytes received (excluding the size of the message type member). Otherwise, -1 is returned and the error code is found in variable errno.

The following example shows how to receive a message.

int z;
struct {
    long    mtype;
    char    path[256];
}  msg;
int msz;
msz = sizeof msg - sizeof msg.mtype;

z = msgrcv(msqid,&msg,msz,0,0);
if ( z == -1 )
    perror("msgrcv(3)");

This example chooses to receive the first available message without regard to priority (argument msgtyp is equal to 0). The value of msz is computed to include the maximum size of the receiving structure, but not to include the size for msg.mtype.