MQ_SEND(3P) - phpMan

MQ_SEND(3P)                POSIX Programmer's Manual               MQ_SEND(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
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 indi-
       cated 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 wait-
       ing 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_time-
       out  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 time-
       out shall be based on the system clock as returned by the time()  func-
       tion.
       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(3P)