mq_send(), mq_timedsend

send a message to a message queue 

Realtime Function

SYNOPSIS

#include <mqueue.h>

#include <time.h>

int mq_timedsend(mqd_t mqdes, const char *msg_ptr, size_t msg_len, unsigned msg_prio, const struct timespec *abs_timeout);

DESCRIPTION

The mq_send() function adds the message pointed to by the msg_ptr argument to the message queue specified by mqdes. The msg_len argument specifies the length, in bytes, of this message. mq_send() fails if the value of msg_len is greater than the mq_msgsize attribute of the message queue.

When the specified message queue is not full, mq_send() uses the msg_prio argument to determine where to place the message in the queue. mq_send() inserts a new message with a larger numeric value of msg_prio before messages with lower values of msg_prio. It inserts a new message after other messages in the queue with equal msg_prio. The maximum value for msg_prio is {MQ_PRIO_MAX}.

If the message queue specified by mqdes is not full and the queue has the O_NONBLOCK flag set in its message queue description, mq_send() blocks block until space becomes available to enqueue the message, or until a signal interrupts mq_send(). If multiple threads are waiting to send when space becomes available in the message queue, the Windows WaitForSingle() function determines which thread is unblocked to send its message. If the specified message queue is full and the O_NONBLOCK is set its message queue description>, the message is not queued and mq_send() returns an error.

The mq_timedsend() function is identical to the mq_send() function except that if the specified message queue is full and the O_NONBLOCK flag is not set in the message queue description, the wait for sufficient room in the queue ends when the specified timeout expires.

The timeout expires when the absolute time specified by abs_timeout passes, as measured by the clock on which timeouts are based (that is, when the value of that clock equals or exceeds abs_timeout), or if abs_timeout has already been passed when mq_send() is called. The timeout is based on the system clock as returned by the time() function.

The resolution of the timeout is the resolution of the clock on which it is based. The <time.h> header defines timespec data type.

This operation never fails with a timeout if there is insufficient room to add the message to the queue immediately. When there is sufficient room in the queue to add the message, the validity of the abs_timeout argument is not checked.

PARAMETERS

abs_timeout 

Specifies the maximum wait for sufficient room to become available to add the message to the specified message queue.

mqdes 

Specifies the message queue descriptor associated with the message queue to which the message is to be added.

msg_len 

Specifies the length, in bytes, of the message to be added to the message queue.

msg_prio 

Specifies the priority of the message to be added to the message queue.

msg_ptr 

Points to the message to be added to the message queue.

RETURN VALUES

On success, the mq_send() and mq_timedsend() functions return 0. On failure, no message is added to the queue and these functions return -1 and set errno to one of the following:

EAGAIN 

The O_NONBLOCK flag is set in the message queue description associated with mqdes, and the specified message queue is full.

EBADF 

mqdes is not a valid message queue descriptor open for writing.

EINTR 

A signal interrupted the mq_send() mq_timedsend() call.

EINVAL 

The value of msg_prio was outside the valid range.

EINVAL 

The process or thread would have blocked, and the abs_timeout argument specified an invalid value.

EMSGSIZE 

The value of msg_len exceeds the message size attribute of the message queue.

ETIMEDOUT 

The O_NONBLOCK flag was not set when the message queue was opened, but the timeout expired before the message could be added to the queue.

CONFORMANCE

UNIX 03.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

On the NuTCRACKER Platform, the Windows WaitForSingle() function determines which thread is selected when multiple threads are waiting for room to become available in the message queue.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
mq_open(), mq_receive(), mq_setattr(), mq_timedreceive(), time()

PTC MKS Toolkit 10.4 Documentation Build 39.