Man Linux: Main Page and Category List

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 .