NAME

       mq_send, mq_timedsend - send a message to a message queue (REALTIME)

SYNOPSIS

       #include <mqueue.h>

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

       #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  shall  add  the message pointed to by the argument msg_ptr to the message queue
       specified by mqdes. The msg_len argument specifies the length of the message, in  bytes,  pointed  to  by
       msg_ptr.  The  value  of  msg_len  shall be less than or equal to the mq_msgsize attribute of the message
       queue, or mq_send() shall fail.

       If the specified message queue is not full, mq_send() shall behave as if the message is inserted into the
       message queue at the position indicated by the msg_prio argument. A message with a larger  numeric  value
       of  msg_prio shall be inserted before messages with lower values of msg_prio. A message shall be inserted
       after other messages in the queue, if any, with equal msg_prio. The value of msg_prio shall 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, mq_send() shall 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, then the thread of the
       highest priority that has been waiting the longest shall be 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  shall  not  be  queued  and
       mq_send() shall return an error.

       The  mq_timedsend()  function  shall  add a message to the message queue specified by mqdes in the manner
       defined for the mq_send() function. However, if the specified message queue is full and O_NONBLOCK is not
       set in the message queue description associated with mqdes, the wait for sufficient  room  in  the  queue
       shall  be  terminated  when  the  specified  timeout  expires.  If O_NONBLOCK is set in the message queue
       description, this function shall be equivalent to mq_send().

       The timeout shall expire 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
       the absolute time specified by abs_timeout has already been passed at the time of the call.

       If  the Timers option is supported, the timeout shall be based on the CLOCK_REALTIME clock; if the Timers
       option is not supported, the timeout shall be based on  the  system  clock  as  returned  by  the  time()
       function.

       The  resolution  of  the  timeout shall be the resolution of the clock on which it is based. The timespec
       argument is defined in the <time.h> header.

       Under no circumstance shall the operation fail with a timeout if there is sufficient room in the queue to
       add the message immediately. The validity of the abs_timeout parameter need not be checked when there  is
       sufficient room in the queue.

RETURN VALUE

       Upon  successful  completion, the mq_send()    and mq_timedsend() functions shall return a value of zero.
       Otherwise, no message shall be enqueued, the functions shall  return  -1,  and  errno  shall  be  set  to
       indicate the error.

ERRORS

       The mq_send()    and mq_timedsend() functions shall fail if:

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

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

       EINTR  A signal interrupted the call to mq_send()    or mq_timedsend().

       EINVAL The value of msg_prio was outside the valid range.

       EINVAL The process or thread would have blocked, and the abs_timeout parameter  specified  a  nanoseconds
              field value less than zero or greater than or equal to 1000 million.

       EMSGSIZE
              The specified message length, 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.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The value of the symbol {MQ_PRIO_MAX} limits the number of priority levels supported by the  application.
       Message priorities range from 0 to {MQ_PRIO_MAX}-1.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       mq_open()  ,  mq_receive()  ,  mq_setattr() , mq_timedreceive() , time() , the Base Definitions volume of
       IEEE Std 1003.1-2001, <mqueue.h>, <time.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
       Inc  and  The  Open Group. In the event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                                   2003                                            MQ_SEND(P)