usr/src/man/man3c/mq_send.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\" Copyright (c) 2014, Ryan Zezeski.
  47 .\"
  48 .TH MQ_SEND 3C "Oct 23, 2014"
  49 .SH NAME
  50 mq_send, mq_timedsend, mq_reltimedsend_np \- send a message to a message queue
  51 .SH SYNOPSIS
  52 .LP
  53 .nf
  54 #include <mqueue.h>
  55
  56 \fBint\fR \fBmq_send\fR(\fBmqd_t\fR \fImqdes\fR, \fBconst char *\fR\fImsg_ptr\fR, \fBsize_t\fR \fImsg_len\fR,
  57      \fBunsigned\fR \fImsg_prio\fR);
  58 .fi
  59
  60 .LP
  61 .nf
  62 #include <mqueue.h>
  63 #include <time.h>
  64
  65 \fBint\fR \fBmq_timedsend\fR(\fBmqd_t\fR \fImqdes\fR, \fBconst char *\fR\fImsg_ptr\fR,
  66      \fBsize_t\fR \fImsg_len\fR, \fBunsigned\fR \fImsg_prio\fR,
  67      \fBconst struct timespec *restrict\fR \fIabs_timeout\fR);
  68 .fi
  69
  70 .LP
  71 .nf
  72 \fBint\fR \fBmq_reltimedsend_np\fR(\fBmqd_t\fR \fImqdes\fR, \fBconst char *\fR\fImsg_ptr\fR,
  73      \fBsize_t\fR \fImsg_len\fR, \fBunsigned\fR \fImsg_prio\fR,
  74      \fBconst struct timespec *restrict\fR \fIrel_timeout\fR);
  75 .fi
  76
  77 .SH DESCRIPTION
  78 .LP
  79 The \fBmq_send()\fR function adds the message pointed to by the argument
  80 \fImsg_ptr\fR to the message queue specified by \fImqdes\fR. The \fImsg_len\fR
  81 argument specifies the length of the message in bytes pointed to by
  82 \fImsg_ptr\fR. The value of \fImsg_len\fR is less than or equal to the
  83 \fImq_msgsize\fR attribute of the message queue, or \fBmq_send()\fR fails.
  84 .sp
  85 .LP
  86 If the specified message queue is not full, \fBmq_send()\fR behaves as
  87 if the message is inserted into the message queue at the position
  88 indicated by the \fImsg_prio\fR argument. A message with a larger
  89 numeric value of \fImsg_prio\fR is inserted before messages with lower
  90 values of \fImsg_prio\fR.  A message will be inserted after other
  91 messages in the queue, if any, with equal \fImsg_prio\fR. The value of
  92 \fImsg_prio\fR must range from zero to \fBMQ_PRIO_MAX - 1\fR.
  93 .sp
  94 .LP
  95 If the specified message queue is full and \fBO_NONBLOCK\fR is not set in the
  96 message queue description associated with \fImqdes\fR (see \fBmq_open\fR(3C)
  97 and \fBmq_setattr\fR(3C)), \fBmq_send()\fR blocks until space becomes available
  98 to enqueue the message, or until \fBmq_send()\fR is interrupted by a signal. If
  99 more than one thread is waiting to send when space becomes available in the
 100 message queue, then the thread of the highest priority which has been waiting
 101 the longest is unblocked to send its message. Otherwise, it is unspecified
 102 which waiting thread is unblocked. If the specified message queue is full and
 103 \fBO_NONBLOCK\fR is set in the message queue description associated with
 104 \fImqdes\fR, the message is not queued and \fBmq_send()\fR returns an error.
 105 .sp
 106 .LP
 107 The \fBmq_timedsend()\fR function adds a message to the message queue specified
 108 by \fImqdes\fR in the manner defined for the \fBmq_send()\fR function. However,
 109 if the specified message queue is full and \fBO_NONBLOCK\fR is not set in the
 110 message queue description associated with \fImqdes\fR, the wait for sufficient
 111 room in the queue is terminated when the specified timeout expires. If
 112 \fBO_NONBLOCK\fR is set in the message queue description, this function is
 113 equivalent to \fBmq_send()\fR.
 114 .sp
 115 .LP
 116 The \fBmq_reltimedsend_np()\fR function is identical to the
 117 \fBmq_timedsend()\fR function, except that the timeout is specified as a
 118 relative time interval.
 119 .sp
 120 .LP
 121 For \fBmq_timedsend()\fR, the timeout expires when the absolute time specified
 122 by \fIabs_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR clock
 123 (that is, when the value of that clock equals or exceeds \fIabs_timeout\fR), or
 124 if the absolute time specified by \fIabs_timeout\fR has already been passed at
 125 the time of the call.
 126 .sp
 127 .LP
 128 For \fBmq_reltimedsend_np()\fR, the timeout expires when the time interval
 129 specified by \fIrel_timeout\fR passes, as measured by the \fBCLOCK_REALTIME\fR
 130 clock, or if the time interval specified by \fIrel_timeout\fR is negative at
 131 the time of the call.
 132 .sp
 133 .LP
 134 The resolution of the timeout is the resolution of the \fBCLOCK_REALTIME\fR
 135 clock. The \fBtimespec\fR argument is defined in the <\fBtime.h\fR> header.
 136 .sp
 137 .LP
 138 Under no circumstance does the operation fail with a timeout if there is
 139 sufficient room in the queue to add the message immediately. The validity of
 140 the timeout parameter need not be checked when there is sufficient room in the
 141 queue.
 142 .SH RETURN VALUES
 143 .LP
 144 Upon successful completion, \fBmq_send()\fR, \fBmq_timedsend()\fR, and
 145 \fBmq_reltimedsend_np()\fR return \fB0\fR. Otherwise, no message is enqueued,
 146 the functions return \fB\(mi1\fR, and \fBerrno\fR is set to indicate the error.
 147 .SH ERRORS
 148 .LP
 149 The \fBmq_send()\fR, \fBmq_timedsend()\fR, and \fBmq_reltimedsend_np()\fR
 150 functions will fail if:
 151 .sp
 152 .ne 2
 153 .na
 154 \fB\fBEAGAIN\fR \fR
 155 .ad
 156 .RS 13n
 157 The  \fBO_NONBLOCK\fR flag is set in the message queue description associated
 158 with \fImqdes\fR, and the specified message queue is full.
 159 .RE
 160
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fBEBADF\fR \fR
 165 .ad
 166 .RS 13n
 167 The \fImqdes\fR argument is not a valid message queue descriptor open for
 168 writing.
 169 .RE
 170
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBEINTR\fR \fR
 175 .ad
 176 .RS 13n
 177 A signal interrupted the function call.
 178 .RE
 179
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fBEINVAL\fR\fR
 184 .ad
 185 .RS 13n
 186 The value of \fImsg_prio\fR was outside the valid range.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBEINVAL\fR\fR
 193 .ad
 194 .RS 13n
 195 The process or thread would have blocked, and the timeout parameter specified a
 196 nanoseconds field value less than zero or greater than or equal to 1,000
 197 million.
 198 .RE
 199
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fBEMSGSIZE\fR \fR
 204 .ad
 205 .RS 13n
 206 The specified message length, \fImsg_len\fR, exceeds the message size attribute
 207 of the message queue.
 208 .RE
 209
 210 .sp
 211 .ne 2
 212 .na
 213 \fB\fBETIMEDOUT\fR\fR
 214 .ad
 215 .RS 13n
 216 The \fBO_NONBLOCK\fR flag was not set when the message queue was opened, but
 217 the timeout expired before the message could be added to the queue.
 218 .RE
 219
 220 .SH ATTRIBUTES
 221 .LP
 222 See \fBattributes\fR(5) for descriptions of the following attributes:
 223 .sp
 224
 225 .sp
 226 .TS
 227 box;
 228 l | l
 229 l | l .
 230 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 231 _
 232 Interface Stability     Committed
 233 _
 234 MT-Level        MT-Safe
 235 _
 236 Standard        See below.
 237 .TE
 238
 239 .sp
 240 .LP
 241 For \fBmq_send()\fR and \fBmq_timedsend()\fR, see \fBstandards\fR(5).
 242 .SH SEE ALSO
 243 .LP
 244 \fBsysconf\fR(3C), \fBmqueue.h\fR(3HEAD), \fBmq_open\fR(3C),
 245 \fBmq_receive\fR(3C), \fBmq_setattr\fR(3C), \fBattributes\fR(5),
 246 \fBstandards\fR(5)