SYSTEM CALL: msgsnd()

Once we have the queue identifier, we can begin performing operations on it. To deliver a message to a queue, you use the msgsnd system call:

  SYSTEM CALL: msgsnd();                                                          

  PROTOTYPE: int msgsnd ( int msqid, struct msgbuf *msgp, int msgsz, int msgflg );
    RETURNS: 0 on success
             -1 on error: errno = EAGAIN (queue is full, and IPC_NOWAIT was asserted)
                                  EACCES (permission denied, no write permission)
                                  EFAULT (msgp address isn't accessable - invalid)
                                  EIDRM  (The message queue has been removed)
                                  EINTR  (Received a signal while waiting to write)
                                  EINVAL (Invalid message queue identifier, nonpositive
                                          message type, or invalid message size) 
                                  ENOMEM (Not enough memory to copy message buffer)
  NOTES:

The first argument to msgsnd is our queue identifier, returned by a previous call to msgget. The second argument, msgp, is a pointer to our redeclared and loaded message buffer. The msgsz argument contains the size of the message in bytes, excluding the length of the message type (4 byte long).

The msgflg argument can be set to 0 (ignored), or:

IPC_NOWAIT

If the message queue is full, then the message is not written to the queue, and control is returned to the calling process. If not specified, then the calling process will suspend (block) until the message can be written.

Let's create another wrapper function for sending messages:

int send_message( int qid, struct mymsgbuf *qbuf )
{
        int     result, length;

        /* The length is essentially the size of the structure minus sizeof(mtype) */
        length = sizeof(struct mymsgbuf) - sizeof(long);        

        if((result = msgsnd( qid, qbuf, length, 0)) == -1)
        {
                return(-1);
        }
        
        return(result);
}

This small function attempts to send the message residing at the passed address (qbuf) to the message queue designated by the passed queue identifier (qid). Here is a sample code snippet utilizing the two wrapper functions we have developed so far:

#include <stdio.h>
#include <stdlib.h>
#include <linux/ipc.h>
#include <linux/msg.h>

main()
{
        int    qid;
        key_t  msgkey;
        struct mymsgbuf {
                long    mtype;          /* Message type */
                int     request;        /* Work request number */
                double  salary;         /* Employee's salary */
        } msg;

        /* Generate our IPC key value */
        msgkey = ftok(".", 'm');

        /* Open/create the queue */
        if(( qid = open_queue( msgkey)) == -1) {
                perror("open_queue");
                exit(1);
        }

        /* Load up the message with arbitrary test data */
        msg.mtype   = 1;        /* Message type must be a positive number! */   
        msg.request = 1;        /* Data element #1 */
        msg.salary  = 1000.00;  /* Data element #2 (my yearly salary!) */
        
        /* Bombs away! */
        if((send_message( qid, &msg )) == -1) {
                perror("send_message");
                exit(1);
        }
}

After creating/opening our message queue, we proceed to load up the message buffer with test data (note the lack of character data to illustrate our point about sending binary information). A quick call to send_message merrily distributes our message out to the message queue.

Now that we have a message on our queue, try the ipcs command to view the status of your queue. Now let's turn the discussion to actually retrieving the message from the queue. To do this, you use the msgrcv() system call:

  SYSTEM CALL: msgrcv();                                                          
  PROTOTYPE: int msgrcv ( int msqid, struct msgbuf *msgp, int msgsz, long mtype, int msgflg );
    RETURNS: Number of bytes copied into message buffer
             -1 on error: errno = E2BIG  (Message length is greater than msgsz, no MSG_NOERROR)
                                  EACCES (No read permission)
                                  EFAULT (Address pointed to by msgp is invalid)
                                  EIDRM  (Queue was removed during retrieval)
                                  EINTR  (Interrupted by arriving signal)
                                  EINVAL (msgqid invalid, or msgsz less than 0)
                                  ENOMSG (IPC_NOWAIT asserted, and no message exists
                                          in the queue to satisfy the request) 
  NOTES:

Obviously, the first argument is used to specify the queue to be used during the message retrieval process (should have been returned by an earlier call to msgget). The second argument (msgp) represents the address of a message buffer variable to store the retrieved message at. The third argument (msgsz) represents the size of the message buffer structure, excluding the length of the mtype member. Once again, this can easily be calculated as:

msgsz = sizeof(struct mymsgbuf) - sizeof(long);

The fourth argument (mtype) specifies the type of message to retrieve from the queue. The kernel will search the queue for the oldest message having a matching type, and will return a copy of it in the address pointed to by the msgp argument. One special case exists. If the mtype argument is passed with a value of zero, then the oldest message on the queue is returned, regardless of type.

If IPC_NOWAIT is passed as a flag, and no messages are available, the call returns ENOMSG to the calling process. Otherwise, the calling process blocks until a message arrives in the queue that satisfies the msgrcv() parameters. If the queue is deleted while a client is waiting on a message, EIDRM is returned. EINTR is returned if a signal is caught while the process is in the middle of blocking, and waiting for a message to arrive.

Let's examine a quick wrapper function for retrieving a message from our queue:

int read_message( int qid, long type, struct mymsgbuf *qbuf )
{
        int     result, length;

        /* The length is essentially the size of the structure minus sizeof(mtype) */
        length = sizeof(struct mymsgbuf) - sizeof(long);        

        if((result = msgrcv( qid, qbuf, length, type,  0)) == -1)
        {
                return(-1);
        }
        
        return(result);
}

After successfully retrieving a message from the queue, the message entry within the queue is destroyed.

The MSG_NOERROR bit in the msgflg argument provides some additional capabilities. If the size of the physical message data is greater than msgsz, and MSG_NOERROR is asserted, then the message is truncated, and only msgsz bytes are returned. Normally, the msgrcv() system call returns -1 (E2BIG), and the message will remain on the queue for later retrieval. This behavior can used to create another wrapper function, which will allow us to ``peek'' inside the queue, to see if a message has arrived that satisfies our request:

int peek_message( int qid, long type )
{
        int     result, length;

        if((result = msgrcv( qid, NULL, 0, type,  IPC_NOWAIT)) == -1)
        {
                if(errno == E2BIG)
                        return(TRUE);
        }
        
        return(FALSE);
}

Above, you will notice the lack of a buffer address and a length. In this particular case, we want the call to fail. However, we check for the return of E2BIG which indicates that a message does exist which matches our requested type. The wrapper function returns TRUE on success, FALSE otherwise. Also note the use of the IPC_NOWAIT flag, which prevents the blocking behavior described earlier.