lib/libc/sys/msgsnd.2

   1 .\"     $NetBSD: msgsnd.2,v 1.18 2010/04/30 04:06:20 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 1995 Frank van der Linden
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"      This product includes software developed for the NetBSD Project
  17 .\"      by Frank van der Linden
  18 .\" 4. The name of the author may not be used to endorse or promote products
  19 .\"    derived from this software without specific prior written permission
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .Dd April 30, 2010
  33 .Dt MSGSND 2
  34 .Os
  35 .Sh NAME
  36 .Nm msgsnd
  37 .Nd send a message to a message queue
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/msg.h
  42 .Ft int
  43 .Fn msgsnd "int msqid" "const void *msgp" "size_t msgsz" "int msgflg"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn msgsnd
  47 function sends a message from the message queue specified in
  48 .Fa msqid .
  49 The
  50 .Fa msgp
  51 argument is a pointer to a user-defined structure containing the message.
  52 This structure must contain a first field of type
  53 .Vt long
  54 that will indicate the user-defined type of the message.
  55 The remaining fields will contain the contents of the message.
  56 The following is an example of what this user-defined
  57 structure might look like:
  58 .Bd -literal -offset indent
  59 struct mymsg {
  60     long mtype;    /* message type */
  61     char mtext[1]; /* body of message */
  62 };
  63 .Ed
  64 .Pp
  65 The
  66 .Va mtype
  67 field is an integer greater than 0 that can
  68 be used for selecting messages (see
  69 .Xr msgrcv 2 ) .
  70 The
  71 .Va mtext
  72 field is an array of bytes, with size up to the system limit
  73 .Dv MSGMAX .
  74 .Pp
  75 If the number of bytes already on the message queue plus
  76 .Fa msgsz
  77 is greater than the maximum number of bytes in the message queue
  78 .Pf ( Va msg_qbytes ,
  79 see
  80 .Xr msgctl 2 ) ,
  81 or if the number of messages on all queues system-wide is already equal to
  82 the system limit,
  83 .Fa msgflg
  84 determines the action of
  85 .Fn msgsnd .
  86 If
  87 .Fa msgflg
  88 has
  89 .Dv IPC_NOWAIT
  90 mask set in it, the call will return immediately.
  91 If
  92 .Fa msgflg
  93 does not have
  94 .Dv IPC_NOWAIT
  95 set in it, the call will block until:
  96 .Bl -bullet -offset indent
  97 .It
  98 The condition which caused the call to block no longer exists.
  99 The message was sent.
 100 .It
 101 The message queue is removed, in which case \-1 will be returned and
 102 .Va errno
 103 set to
 104 .Er EINVAL .
 105 .It
 106 The caller catches a signal.
 107 The call returns with
 108 .Va errno
 109 set to
 110 .Er EINTR .
 111 .El
 112 .Pp
 113 After a successful call, the data structure associated with the message
 114 queue is updated in the following way:
 115 .Bl -bullet -offset indent
 116 .It
 117 .Va msg_qnum
 118 is incremented by 1.
 119 .It
 120 .Va msg_lspid
 121 is set to the pid of the calling process.
 122 .It
 123 .Va msg_stime
 124 is set to the current time.
 125 .El
 126 .Sh RETURN VALUES
 127 Upon successful completion, 0 is returned.
 128 Otherwise, \-1 is returned and
 129 .Va errno
 130 is set to indicate the error.
 131 .Sh ERRORS
 132 .Fn msgsnd
 133 will fail if:
 134 .Bl -tag -width Er
 135 .It Bq Er EACCES
 136 The calling process does not have write access to the message queue.
 137 .It Bq Er EAGAIN
 138 There was no space for this message either on the queue or in the whole
 139 system, and
 140 .Dv IPC_NOWAIT
 141 was set in
 142 .Fa msgflg .
 143 .It Bq Er EFAULT
 144 .Fa msgp
 145 points to an invalid address.
 146 .It Bq Er EINTR
 147 The system call was interrupted by the delivery of a signal.
 148 .It Bq Er EINVAL
 149 The
 150 .Fa msqid
 151 argument is not a valid message queue identifier,
 152 or the value of
 153 .Fa mtype
 154 is less than 1.
 155 .Pp
 156 The message queue was removed while
 157 .Fn msgsnd
 158 was waiting for a resource to become available in order to deliver the
 159 message.
 160 .Pp
 161 The
 162 .Fa msgsz
 163 argument is greater than
 164 .Va msg_qbytes
 165 or
 166 .Dv SSIZE_MAX .
 167 .El
 168 .Sh SEE ALSO
 169 .Xr msgctl 2 ,
 170 .Xr msgget 2 ,
 171 .Xr msgrcv 2
 172 .Sh STANDARDS
 173 The
 174 .Nm
 175 system call conforms to
 176 .St -xsh5
 177 and
 178 .St -p1003.1-2001 .
 179 .Sh HISTORY
 180 Message queues appeared in the first release of
 181 .At V .