lib/librt/mq_send.2

   1 .\"     $NetBSD: mq_send.3,v 1.1 2009/01/05 21:19:49 rmind Exp $
   2 .\"
   3 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   4 .\"
   5 .Dd August 19, 2009
   6 .Dt MQ_SEND 2
   7 .Os
   8 .Sh NAME
   9 .Nm mq_send , mq_timedsend
  10 .Nd send a message to a message queue (REALTIME)
  11 .Sh LIBRARY
  12 .Lb librt
  13 .Sh SYNOPSIS
  14 .In mqueue.h
  15 .Ft int
  16 .Fo mq_send
  17 .Fa "mqd_t mqdes"
  18 .Fa "const char *msg_ptr"
  19 .Fa "size_t msg_len"
  20 .Fa "unsigned msg_prio"
  21 .Fc
  22 .In mqueue.h
  23 .In time.h
  24 .Ft int
  25 .Fo mq_timedsend
  26 .Fa "mqd_t mqdes"
  27 .Fa "const char *msg_ptr"
  28 .Fa "size_t msg_len"
  29 .Fa "unsigned msg_prio"
  30 .Fa "const struct timespec *abs_timeout"
  31 .Fc
  32 .Sh DESCRIPTION
  33 The
  34 .Fn mq_send
  35 function will add the message pointed to by the argument
  36 .Fa msg_ptr
  37 to the message queue specified by
  38 .Fa mqdes .
  39 The
  40 .Fa msg_len
  41 argument specifies the length of the message, in bytes, pointed to by
  42 .Fa msg_ptr .
  43 The value of
  44 .Fa msg_len
  45 will be less than or equal to the
  46 .Fa mq_msgsize
  47 attribute of the message queue, or
  48 .Fn mq_send
  49 will fail.
  50 .Pp
  51 If the specified message queue is not full,
  52 .Fn mq_send
  53 behaves as if the message is inserted into the message queue at the
  54 position indicated by the
  55 .Fa msg_prio
  56 argument.
  57 A message with a larger numeric value of
  58 .Fa msg_prio
  59 will be inserted before messages with lower values of
  60 .Fa msg_prio .
  61 A message will be inserted after other messages in the queue,
  62 if any, with equal
  63 .Fa msg_prio .
  64 The value of
  65 .Fa msg_prio
  66 will be less than
  67 .Brq Dv MQ_PRIO_MAX .
  68 .Pp
  69 If the specified message queue is full and
  70 .Dv O_NONBLOCK
  71 is not set in the message queue description associated with
  72 .Fa mqdes ,
  73 .Fn mq_send
  74 blocks until space becomes available to enqueue the message, or until
  75 .Fn mq_send
  76 is interrupted by a signal.
  77 If more than one thread is waiting to send when space becomes available
  78 in the message queue, then the thread of the highest priority that has
  79 been waiting the longest will be unblocked to send its message.
  80 If the specified message queue is full and
  81 .Dv O_NONBLOCK
  82 is set in the message queue description associated with
  83 .Fa mqdes ,
  84 the message will not be queued and
  85 .Fn mq_send
  86 will return an error.
  87 .Pp
  88 The
  89 .Fn mq_timedsend
  90 function will add a message to the message queue specified by
  91 .Fa mqdes
  92 in the manner defined for the
  93 .Fn mq_send
  94 function.
  95 However, if the specified message queue is full and
  96 .Dv O_NONBLOCK
  97 is not set in the message queue description associated with
  98 .Fa mqdes ,
  99 the wait for sufficient room in the queue will be terminated
 100 when the specified timeout expires.
 101 If
 102 .Dv O_NONBLOCK
 103 is set in the message queue description, this function will be equivalent to
 104 .Fn mq_send .
 105 .Pp
 106 The timeout will expire when the absolute time specified by
 107 .Fa abs_timeout
 108 passes, as measured by the clock on which timeouts are based (that is,
 109 when the value of that clock equals or exceeds
 110 .Fa abs_timeout ) ,
 111 or if the absolute time specified by
 112 .Fa abs_timeout
 113 has already been passed at the time of the call.
 114 .Pp
 115 The resolution of the timeout is based on the CLOCK_REALTIME clock.
 116 The
 117 .Fa timespec
 118 argument is defined in the
 119 .Aq time.h
 120 header.
 121 .Pp
 122 Under no circumstance will the operation fail with a timeout if there is
 123 sufficient room in the queue to add the message immediately.
 124 The validity of the
 125 .Fa abs_timeout
 126 parameter need not be checked when there is sufficient room in the queue.
 127 .Sh RETURN VALUES
 128 Upon successful completion, the
 129 .Fn mq_send
 130 and
 131 .Fn mq_timedsend
 132 functions return a value of zero.
 133 Otherwise, no message will be enqueued,
 134 the functions will return \-1, and the global variable
 135 .Va errno
 136 will be set to indicate the error.
 137 .Sh ERRORS
 138 The
 139 .Fn mq_send
 140 and
 141 .Fn mq_timedsend
 142 functions fail if:
 143 .Bl -tag -width Er
 144 .It Bq Er EAGAIN
 145 The
 146 .Dv O_NONBLOCK
 147 flag is set in the message queue description associated with
 148 .Fa mqdes ,
 149 and the specified message queue is full.
 150 .It Bq Er EBADF
 151 The
 152 .Fa mqdes
 153 argument is not a valid message queue descriptor open for writing.
 154 .It Bq Er EINTR
 155 A signal interrupted the call to
 156 .Fn mq_send
 157 or
 158 .Fn mq_timedsend .
 159 .It Bq Er EINVAL
 160 The value of
 161 .Fa msg_prio
 162 was outside the valid range, or
 163 the process or thread would have blocked, and the
 164 .Fa abs_timeout
 165 parameter specified a nanoseconds field value less than zero
 166 or greater than or equal to 1000 million.
 167 .It Bq Er EMSGSIZE
 168 The specified message length,
 169 .Fa msg_len ,
 170 exceeds the message size attribute of the message queue.
 171 .It Bq Er ETIMEDOUT
 172 The
 173 .Dv O_NONBLOCK
 174 flag was not set when the message queue was opened,
 175 but the timeout expired before the message could be added to the queue.
 176 .El
 177 .Sh SEE ALSO
 178 .Xr mq_close 2 ,
 179 .Xr mq_getattr 2 ,
 180 .Xr mq_notify 2 ,
 181 .Xr mq_open 2 ,
 182 .Xr mq_receive 2 ,
 183 .Xr mq_setattr 2 ,
 184 .Xr mq_unlink 2
 185 .Sh STANDARDS
 186 These functions are expected to conform to the
 187 .St -p1003.1-2001
 188 standard.
 189 .Sh HISTORY
 190 The
 191 .Fn mq_send
 192 and
 193 .Fn mq_timedsend
 194 functions first appeared in
 195 .Dx 2.5 .
 196 .Sh COPYRIGHT
 197 Portions of this text are reprinted and reproduced in electronic form
 198 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 199 -- Portable Operating System Interface (POSIX), The Open Group Base
 200 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 201 Electrical and Electronics Engineers, Inc and The Open Group.
 202 In the
 203 event of any discrepancy between this version and the original IEEE and
 204 The Open Group Standard, the original IEEE and The Open Group Standard
 205 is the referee document.
 206 The original Standard can be obtained online at
 207 http://www.opengroup.org/unix/online.html .