usr/src/man/man2/msgsnd.2

   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 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  44 .\" Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
  45 .\"
  46 .TH MSGSND 2 "Feb 11, 2003"
  47 .SH NAME
  48 msgsnd \- message send operation
  49 .SH SYNOPSIS
  50 .LP
  51 .nf
  52 #include <sys/msg.h>
  53
  54 \fBint\fR \fBmsgsnd\fR(\fBint\fR \fImsqid\fR, \fBconst void *\fR\fImsgp\fR, \fBsize_t\fR \fImsgsz\fR, \fBint\fR \fImsgflg\fR);
  55 .fi
  56
  57 .SH DESCRIPTION
  58 .sp
  59 .LP
  60 The \fBmsgsnd()\fR function is used to send a message to the queue associated
  61 with the message queue identifier specified by \fImsqid\fR.
  62 .sp
  63 .LP
  64 The \fImsgp\fR argument points to a user-defined buffer that must contain first
  65 a field of type \fBlong int\fR that will specify the type of the message, and
  66 then a data portion that will hold the data bytes of the message. The structure
  67 below is an example of what this user-defined buffer might look like:
  68 .sp
  69 .in +2
  70 .nf
  71 struct  mymsg {
  72         long  mtype;     /* message type */
  73         char  mtext[1];  /* message text */
  74 }
  75 .fi
  76 .in -2
  77
  78 .sp
  79 .LP
  80 The \fBmtype\fR member is a non-zero positive type \fBlong int\fR that can be
  81 used by the receiving process for message selection.
  82 .sp
  83 .LP
  84 The \fBmtext\fR member is any text of length \fImsgsz\fR bytes. The \fImsgsz\fR
  85 argument can range from 0 to a system-imposed maximum.
  86 .sp
  87 .LP
  88 The \fImsgflg\fR argument specifies the action to be taken if one or more of
  89 the following are true:
  90 .RS +4
  91 .TP
  92 .ie t \(bu
  93 .el o
  94 The number of bytes already on the queue is equal to \fBmsg_qbytes\fR. See
  95 \fBIntro\fR(2).
  96 .RE
  97 .RS +4
  98 .TP
  99 .ie t \(bu
 100 .el o
 101 The total number of messages on the queue would exceed the maximum allowed by
 102 the system. See NOTES.
 103 .RE
 104 .sp
 105 .LP
 106 These actions are as follows:
 107 .RS +4
 108 .TP
 109 .ie t \(bu
 110 .el o
 111 If (\fImsgflg\fR\fB&IPC_NOWAIT\fR) is non-zero, the message will not be sent
 112 and the calling process will return immediately.
 113 .RE
 114 .RS +4
 115 .TP
 116 .ie t \(bu
 117 .el o
 118 If (\fImsgflg\fR\fB&IPC_NOWAIT\fR) is 0, the calling process will suspend
 119 execution until one of the following occurs:
 120 .RS +4
 121 .TP
 122 .ie t \(bu
 123 .el o
 124 The condition responsible for the suspension no longer exists, in which case
 125 the message is sent.
 126 .RE
 127 .RS +4
 128 .TP
 129 .ie t \(bu
 130 .el o
 131 The message queue identifier \fImsqid\fR is removed from the system (see
 132 \fBmsgctl\fR(2)); when this occurs, \fBerrno\fR is set equal to \fBEIDRM\fR and
 133 \fB\(mi1\fR is returned.
 134 .RE
 135 .RS +4
 136 .TP
 137 .ie t \(bu
 138 .el o
 139 The calling process receives a signal that is to be caught; in this case the
 140 message is not sent and the calling process resumes execution in the manner
 141 prescribed in \fBsigaction\fR(2).
 142 .RE
 143 .RE
 144 .sp
 145 .LP
 146 Upon successful completion, the following actions are taken with respect to the
 147 data structure associated with \fImsqid\fR (see \fBIntro\fR(2)):
 148 .RS +4
 149 .TP
 150 .ie t \(bu
 151 .el o
 152 \fBmsg_qnum\fR is incremented by 1.
 153 .RE
 154 .RS +4
 155 .TP
 156 .ie t \(bu
 157 .el o
 158 \fBmsg_lspid\fR is set equal to the process \fBID\fR of the calling process.
 159 .RE
 160 .RS +4
 161 .TP
 162 .ie t \(bu
 163 .el o
 164 \fBmsg_stime\fR is set equal to the current time.
 165 .RE
 166 .SH RETURN VALUES
 167 .sp
 168 .LP
 169 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
 170 returned, no message is sent, and \fBerrno\fR is set to indicate the error.
 171 .SH ERRORS
 172 .sp
 173 .LP
 174 The \fBmsgsnd()\fR function will fail if:
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBEACCES\fR\fR
 179 .ad
 180 .RS 10n
 181 Operation permission is denied to the calling process. See \fBIntro\fR(2).
 182 .RE
 183
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBEAGAIN\fR\fR
 188 .ad
 189 .RS 10n
 190 The message cannot be sent for one of the reasons cited above and
 191 (\fImsgflg\fR\fB&IPC_NOWAIT\fR) is non-zero.
 192 .RE
 193
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fBEIDRM\fR\fR
 198 .ad
 199 .RS 10n
 200 The message queue identifier \fImsgid\fR is removed from the system.
 201 .RE
 202
 203 .sp
 204 .ne 2
 205 .na
 206 \fB\fBEINTR\fR\fR
 207 .ad
 208 .RS 10n
 209 The \fBmsgsnd()\fR function was interrupted by a signal.
 210 .RE
 211
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fBEINVAL\fR\fR
 216 .ad
 217 .RS 10n
 218 The value of \fImsqid\fR is not a valid message queue identifier, or the value
 219 of \fBmtype\fR is less than 1.
 220 .sp
 221 The value of \fImsgsz\fR is less than 0 or greater than the system-imposed
 222 limit.
 223 .RE
 224
 225 .sp
 226 .LP
 227 The \fBmsgsnd()\fR function may fail if:
 228 .sp
 229 .ne 2
 230 .na
 231 \fB \fBEFAULT\fR\fR
 232 .ad
 233 .RS 11n
 234 The \fImsgp\fR argument points to an illegal address.
 235 .RE
 236
 237 .SH USAGE
 238 .sp
 239 .LP
 240 The value passed as the \fImsgp\fR argument should be converted to type \fBvoid
 241 *\fR.
 242 .SH ATTRIBUTES
 243 .sp
 244 .LP
 245 See \fBattributes\fR(5) for descriptions of the following attributes:
 246 .sp
 247
 248 .sp
 249 .TS
 250 box;
 251 c | c
 252 l | l .
 253 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 254 _
 255 Interface Stability     Standard
 256 .TE
 257
 258 .SH SEE ALSO
 259 .sp
 260 .LP
 261 \fBrctladm\fR(1M), \fBIntro\fR(2), \fBmsgctl\fR(2), \fBmsgget\fR(2),
 262 \fBmsgrcv\fR(2), \fBsetrctl\fR(2), \fBsigaction\fR(2), \fBattributes\fR(5),
 263 \fBstandards\fR(5)
 264 .SH NOTES
 265 .sp
 266 .LP
 267 The maximum number of messages allowed on a message queue is the minimum
 268 enforced value of the \fBprocess.max-msg-messages\fR resource control of the
 269 creating process at the time \fBmsgget\fR(2) was used to allocate the queue.
 270 .sp
 271 .LP
 272  See \fBrctladm\fR(1M) and \fBsetrctl\fR(2) for information about using
 273 resource controls.