Message Queue Functions

Message queues provide a form of message passing in which any process (given that it has the necessary permissions) can read a message from or write a message to any IPC message queue on the system. There are no requirements that a process be waiting to receive a message from a queue before another process sends one, or that a message exist on the queue before a process requests to receive one.

Every message on a queue has the following attributes:

• Message type
• Message length (length of data part of message)
• Message data (if length is greater than 0)

A thread gets a message queue identifier by calling the msgget() function. Depending on the key and msgflg parameters passed in, either a new message queue is created or an existing message queue is accessed. When a new message queue is created, a data structure is also created to contain information about the message queue. This structure is defined in the <sys/msg.h> header file as follows:

typedef struct msqid_ds {
    struct ipc_perm   msg_perm;    /* Operation permission struct */
    msgqnum_t         msg_qnum;    /* # msgs currently on queue   */
    msglen_t          msg_qbytes;  /* Max # bytes allowed on queue*/
    pid_t             msg_lspid;   /* Process ID of last msgsnd() */
    pid_t             msg_lrpid;   /* Process ID of last msgrcv() */
    time_t            msg_stime;   /* Time of last msgsnd()       */
    time_t            msg_rtime;   /* Time of last msgrcv()       */
    time_t            msg_ctime;   /* Time of last change         */
} msqid_ds_t;

A thread puts a message on a message queue by calling the msgsnd() function. The following parameters are passed in:

• Message queue ID
• Pointer to a buffer containing the message type and message data
• Length of the message
• Flag that specifies whether or not the thread is willing to wait to send the message.

A thread gets a message from a message queue by calling the msgrcv() function. The following parameters are passed in:

• Message queue ID
• Pointer to a buffer in which to receive the message
• Length of the buffer
• Type of message
• Flag that specifies whether or not the thread is willing to wait and whether or not the thread is willing to truncate a message to receive it

A thread removes a message queue ID by calling the msgctl() function. The thread also can use the msgctl() function to change the data structure values associated with the message queue ID or to retrieve the data structure values associated with the message queue ID. The following parameters are passed in:

• Message queue ID
• Command the thread wants to perform (remove ID, set data structure values, receive data structure values)
• Pointer to a buffer from which to set data structure values or in which to receive data structure values

Message Queue Differences and Restrictions

IBM^® i message queues differ from the message queue definition in the Single UNIX^® Specification in the following ways:

• The maximum message size is 65535 bytes.
• The maximum number of bytes on a message queue is 16 777 216.
• The maximum number of message queues that can be created (system-wide) is 2 147 483 646.

The message queue functions are:

• msgctl() (Perform Message Control Operations) provides message control operations as specified by cmd on the message queue specified by msqid.
• msgget() (Get Message Queue) returns the message queue identifier associated with the parameter key.
• msgrcv() (Receive Message Operation) reads a message from the queue associated with the message queue identifier specified by msqid and places it in the user-defined buffer pointed to by msgp.
• msgsnd() (Send Message Operation) is used to send a message to the queue associated with the message queue identifier specified by msqid.

See also IPC Key Generation Functions for additional message queue functions.

[ Back to top | UNIX-Type APIs | APIs by category ]