mqueue

This interface allows processes to share data by sending and receiving messages.

Here is an example of how to create a new message queue and put a message in the new queue:

#include <mqueue.h>
#include <stdio.h>

void create_queue_and_send_msg(){
     mqd_t mdes;
     struct mq_attr attr;
     char msg[32];

     attr.mq_maxmsg = 4;
     attr.mq_msgsize = 32;

     mdes = mq_open("/path/to/queue", O_CREAT|O_EXCL|O_RDWR, 0666, &attr);
     if ( mdes == (mqd_t)-1 ){
          perror("failed to create queue");
          return;
     }

     //now send a message in the queue
     strcpy(msg, "this is the message");
     if ( mq_send(mdes, msg, strlen(msg), 0) < 0 ){
          perror("failed to send message");
     }

}

Another process can read the message in the queue my using the following code:

#include <mqueue.h>
#include <stdio.h>

void read_msg(){
     mqd_t mdes;
     char msg[32];
     unsigned msg_prio;

     mdes = mq_open("/path/to/queue", O_RDWR);
     if ( mdes == (mqd_t)-1 ){
          perror("failed to create queue");
          return;
     }

     //now send a message in the queue
     if ( mq_receive(mdes, msg, strlen(msg), &msg_prio) < 0 ){
          perror("failed to send message");
     }

     printf("received: %s\n", msg);

}

Prototypes

  • public intmq_getattr(mqd_t mqdes,structmq_attr* mqstat)
  • public intmq_setattr(mqd_t mqdes,const structmq_attr* mqstat,structmq_attr* omqstat)
  • public mqd_tmq_open(const char * name,int oflag,...)
  • public intmq_close(mqd_t mqdes)
  • public intmq_unlink(const char * name)
  • public voidmq_discard(mqd_t mqdes)
  • public voidmq_flush(mqd_t mqdes)
  • public intmq_notify(mqd_t mqdes,const struct sigevent * notification)
  • public ssize_tmq_receive(mqd_t mqdes,char * msg_ptr,size_t msg_len,unsigned * msg_prio)
  • public ssize_tmq_timedreceive(mqd_t mqdes,char * msg_ptr,size_t msg_len,unsigned * msg_prio,const struct timespec * abs_timeout)
  • public intmq_send(mqd_t mqdes,const char * msg_ptr,size_t msg_len,unsigned msg_prio)
  • public intmq_timedsend(mqd_t mqdes,const char * msg_ptr,size_t msg_len,unsigned msg_prio,const struct timespec * abs_timeout)
  • public ssize_tmq_tryreceive(mqd_t mqdes,char * msg_ptr,size_t msg_len,unsigned * msg_prio)
  • public intmq_trysend(mqd_t mqdes,const char * msg_ptr,size_t msg_len,unsigned msg_prio)

Details

public intmq_getattr(mqd_t mqdes,structmq_attr* mqstat)

This function gets the message queue attributes and stores them at mqstat.

Returns

Zero on success or -1 with errno (see Errno) set to:

  • EBADF: mqdes is not a valid message queue descriptor

public intmq_setattr(mqd_t mqdes,const structmq_attr* mqstat,structmq_attr* omqstat)

This function is not supported.

Returns

Zero on success or -1 with errno (see Errno) set to:

  • ENOTSUP

public mqd_tmq_open(const char * name,int oflag,...)

This function opens or creates a new message queue.

Parameters

  • name The name of the message queue

  • oflag The flags to use when opening (O_CREAT, O_EXCL, O_RDWR, O_RDONLY)

  • mode The access mode settings for the queue

  • attr The message queue attributes

If using O_CREAT, the following prototype is used:

mqd_t mq_open(const char * name, int oflag, mode_t mode, const struct mq_attr * attr);

Returns

Zero on success or -1 with errno (see Errno) set to:

  • ENAMETOOLONG: name length is greater than NAME_MAX

  • EEXIST: O_CREAT and O_EXCL are set in oflag but the queue already exists

  • ENOENT: O_CREAT is not set in oflag and the queue does not exist

  • ENOMEM: not enough memory for the queue

  • EACCES: permission to create name queue is denied

  • EINVAL: O_CREAT is set and attr is not null but mq_maxmsg or mq_msgsize is less than or equal to zero


public intmq_close(mqd_t mqdes)

This function closes the message queue.

Returns

Zero on success or -1 with errno (see Errno) set to:

  • EBADF: mqdes is not a valid descriptor

public intmq_unlink(const char * name)

This function deletes a message queue if no other processes have it open. If another process has the queue open, the queue will be deleted when said process closes the queue using mq_close().

Returns

Zero on success or -1 with errno (see Errno) set to:

  • ENAMETOOLONG: length of name exceeds NAME_MAX

  • EACCES: write permission to name is denied

  • ENOENT: the queue does not exist

  • EIO: I/O error while deleting the queue


public voidmq_discard(mqd_t mqdes)


public voidmq_flush(mqd_t mqdes)


public intmq_notify(mqd_t mqdes,const struct sigevent * notification)

This function is not supported.

Returns

Zero on success or -1 with errno (see Errno) set to:

  • ENOTSUP: feature is not supported

public ssize_tmq_receive(mqd_t mqdes,char * msg_ptr,size_t msg_len,unsigned * msg_prio)

This function removes a message from the queue and stores the message at msg_ptr.

Returns

Zero on success or -1 with errno (see Errno) set to:

  • EAGAIN: no message on the queue and O_NONBLOCK is set in the descriptor flags

  • EIO: I/O error while accessing the queue

  • EMSGSIZE: msg_len is less than the message size of the queue

  • EBADF: mqdes is not a valid message queue descriptor


public ssize_tmq_timedreceive(mqd_t mqdes,char * msg_ptr,size_t msg_len,unsigned * msg_prio,const struct timespec * abs_timeout)

This function removes a message from the queue and stores the message at msg_ptr. If no messages are available, the thread is blocked until either a messsage is available or the value of CLOCK_REALTIME is less then abs_timeout.

If O_NONBLOCK is set in mqdes, the function returns immediately whether a message is ready or not.

Returns

Zero on success or -1 with errno (see Errno) set to:

  • EAGAIN: no message on the queue and O_NONBLOCK is set in the descriptor flags

  • EIO: I/O error while accessing the queue

  • ETIMEDOUT: abs_timeout was exceeded by CLOCK_REALTIME

  • EMSGSIZE: msg_len is less than the message size of the queue

  • EBADF: mqdes is not a valid message queue descriptor


public intmq_send(mqd_t mqdes,const char * msg_ptr,size_t msg_len,unsigned msg_prio)

This function sends a message pointed to by msg_ptr. If there is no room in the queue (and O_NONBLOCK is not set in mqdes), the thread is blocked until a message is removed from the queue.

If O_NONBLOCK is set in mqdes, the function returns immediately whether a message is sent or not.

Returns

Zero on success or -1 with errno (see Errno) set to:

  • EAGAIN: no room on the queue and O_NONBLOCK is set in the descriptor flags

  • EIO: I/O error while accessing the queue

  • EBADF: mqdes is not a valid message queue descriptor


public intmq_timedsend(mqd_t mqdes,const char * msg_ptr,size_t msg_len,unsigned msg_prio,const struct timespec * abs_timeout)

This function sends a message pointed to by msg_ptr. If there is no room in the queue (and O_NONBLOCK is not set in mqdes), the thread is blocked until a message is removed from the queue or until the value of CLOCK_REALTIME exceeds abs_timeout.

If O_NONBLOCK is set in mqdes, the function returns immediately whether a message is sent or not.

Returns

Zero on success or -1 with errno (see Errno) set to:

  • EAGAIN: no message on the queue and O_NONBLOCK is set in the descriptor flags

  • EIO: I/O error while accessing the queue

  • ETIMEDOUT: abs_timeout was exceeded by CLOCK_REALTIME

  • EBADF: mqdes is not a valid message queue descriptor


public ssize_tmq_tryreceive(mqd_t mqdes,char * msg_ptr,size_t msg_len,unsigned * msg_prio)


public intmq_trysend(mqd_t mqdes,const char * msg_ptr,size_t msg_len,unsigned msg_prio)