mq_send Subroutine

Purpose

Sends a message to a message queue.

Library

Standard C Library (libc.a)

Syntax

#include <mqueue.h>

int mq_send (mqdes, msg_ptr, msg_len, msg_prio)
mqd_t mqdes;
const char *msg_ptr;
size_t msg_len;
unsigned *msg_prio;

Description

The mq_send subroutine adds the message pointed to by the msg_ptr parameter to the message queue specified by the mqdes parameter. The msg_len parameter specifies the length of the message, in bytes, pointed to by msg_ptr. The value of msg_len is less than or equal to the mq_msgsize attribute of the message queue, or the mq_send subroutine will fail.

If the specified message queue is not full, the mq_send subroutine behaves as if the message is inserted into the message queue at the position indicated by the msg_prio parameter. A message with a larger numeric value of msg_prio will be inserted before messages with lower values of msg_prio. A message will be inserted after other messages in the queue with equal msg_prio. The value of msg_prio will be less than MQ_PRIO_MAX.

If the specified message queue is full and O_NONBLOCK is not set in the message queue description associated with mqdes, the mq_send subroutine will block until space becomes available to enqueue the message, or until mq_send is interrupted by a signal. If more than one thread is waiting to send when space becomes available in the message queue and the Priority Scheduling option is supported, the thread of the highest priority that has been waiting the longest is unblocked to send its message. Otherwise, it is unspecified which waiting thread is unblocked. If the specified message queue is full and O_NONBLOCK is set in the message queue description associated with mqdes, the message is not queued and the mq_send subroutine returns an error.

Parameters

Item Description
mqdes Specifies the message queue descriptor.
msg_ptr Points to the message to be added.
msg_len Specifies the length of the message, in bytes.
msg_prio Specifies the position of the message in the message queue.

Return Values

Upon successful completion, the mq_send subroutine returns a zero. Otherwise, no message is enqueued, the subroutine returns -1, and errno is set to indicate the error.

Error Codes

The mq_send subroutine fails if:
Item Description
EAGAIN The O_NONBLOCK flag is set in the message queue description associated with the mqdes parameter, and the specified message queue is full (maximum number of messages in the queue or maximum number of bytes in the queue is reached).
EBADF The mqdes parameter is not a valid message queue descriptor open for writing.
EFAULT Invalid used address.
EIDRM The specified message queue was removed during the required operation.
EINTR A signal interrupted the call to the mq_send subroutine.
EINVAL The value of the msg_prio parameter was outside the valid range.
EINVAL The msg_ptr parameter is null.
EMSGSIZE The specified message length, msg_len, exceeds the message size attribute of the message queue.
ENOMEM Insufficient memory for the required operation.
ENOTSUP This function is not supported with processes that have been checkpoint-restart'ed.