lib/libc/sys/msgsnd.2

   1 .\"     $NetBSD: msgsnd.2,v 1.20 2013/07/24 11:54:04 skrll 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 July 24, 2013
  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 of length
  73 .Fa msgsz ,
  74 with size up to the system limit
  75 .Dv MSGMAX .
  76 .Pp
  77 If the number of bytes already on the message queue plus
  78 .Fa msgsz
  79 is greater than the maximum number of bytes in the message queue
  80 .Pf ( Va msg_qbytes ,
  81 see
  82 .Xr msgctl 2 ) ,
  83 or if the number of messages on all queues system-wide is already equal to
  84 the system limit,
  85 .Fa msgflg
  86 determines the action of
  87 .Fn msgsnd .
  88 If
  89 .Fa msgflg
  90 has
  91 .Dv IPC_NOWAIT
  92 mask set in it, the call will return immediately.
  93 If
  94 .Fa msgflg
  95 does not have
  96 .Dv IPC_NOWAIT
  97 set in it, the call will block until:
  98 .Bl -bullet -offset indent
  99 .It
 100 The condition which caused the call to block no longer exists.
 101 The message was sent.
 102 .It
 103 The message queue is removed, in which case \-1 will be returned and
 104 .Va errno
 105 set to
 106 .Er EINVAL .
 107 .It
 108 The caller catches a signal.
 109 The call returns with
 110 .Va errno
 111 set to
 112 .Er EINTR .
 113 .El
 114 .Pp
 115 After a successful call, the data structure associated with the message
 116 queue is updated in the following way:
 117 .Bl -bullet -offset indent
 118 .It
 119 .Va msg_qnum
 120 is incremented by 1.
 121 .It
 122 .Va msg_lspid
 123 is set to the pid of the calling process.
 124 .It
 125 .Va msg_stime
 126 is set to the current time.
 127 .El
 128 .Sh RETURN VALUES
 129 Upon successful completion, 0 is returned.
 130 Otherwise, \-1 is returned and
 131 .Va errno
 132 is set to indicate the error.
 133 .Sh ERRORS
 134 .Fn msgsnd
 135 will fail if:
 136 .Bl -tag -width Er
 137 .It Bq Er EACCES
 138 The calling process does not have write access to the message queue.
 139 .It Bq Er EAGAIN
 140 There was no space for this message either on the queue or in the whole
 141 system, and
 142 .Dv IPC_NOWAIT
 143 was set in
 144 .Fa msgflg .
 145 .It Bq Er EFAULT
 146 .Fa msgp
 147 points to an invalid address.
 148 .It Bq Er EINTR
 149 The system call was interrupted by the delivery of a signal.
 150 .It Bq Er EINVAL
 151 The
 152 .Fa msqid
 153 argument is not a valid message queue identifier,
 154 or the value of
 155 .Fa mtype
 156 is less than 1.
 157 .Pp
 158 The message queue was removed while
 159 .Fn msgsnd
 160 was waiting for a resource to become available in order to deliver the
 161 message.
 162 .Pp
 163 The
 164 .Fa msgsz
 165 argument is greater than
 166 .Va msg_qbytes
 167 or
 168 .Dv SSIZE_MAX .
 169 .El
 170 .Sh SEE ALSO
 171 .Xr msgctl 2 ,
 172 .Xr msgget 2 ,
 173 .Xr msgrcv 2
 174 .Sh STANDARDS
 175 The
 176 .Nm
 177 system call conforms to
 178 .St -xsh5
 179 and
 180 .St -p1003.1-2001 .
 181 .Sh HISTORY
 182 Message queues appeared in the first release of
 183 .At V .