lib/libc/sys/msgsnd.2

   1 .\"     $NetBSD: msgsnd.2,v 1.1 1995/10/16 23:49:24 jtc 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 9, 2009
  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/types.h
  42 .In sys/ipc.h
  43 .In sys/msg.h
  44 .Ft int
  45 .Fn msgsnd "int msqid" "const void *msgp" "size_t msgsz" "int msgflg"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn msgsnd
  49 function sends a message to the message queue specified in
  50 .Fa msqid .
  51 The
  52 .Fa msgp
  53 argument
  54 points to a structure containing the message.
  55 This structure should
  56 consist of the following members:
  57 .Bd -literal
  58     long mtype;    /* message type */
  59     char mtext[1]; /* body of message */
  60 .Ed
  61 .Pp
  62 .Va mtype
  63 is an integer greater than 0 that can be used for selecting messages (see
  64 .Xr msgrcv 2 ) ,
  65 .Va mtext
  66 is an array of
  67 .Fa msgsz
  68 bytes.
  69 The argument
  70 .Fa msgsz
  71 can range from 0 to a system-imposed maximum,
  72 .Dv MSGMAX .
  73 .Pp
  74 If the number of bytes already on the message queue plus
  75 .Fa msgsz
  76 is bigger than the maximum number of bytes on the message queue
  77 .Pf ( Va msg_qbytes ,
  78 see
  79 .Xr msgctl 2 ) ,
  80 or the number of messages on all queues system-wide is already equal to
  81 the system limit,
  82 .Fa msgflg
  83 determines the action of
  84 .Fn msgsnd .
  85 If
  86 .Fa msgflg
  87 has
  88 .Dv IPC_NOWAIT
  89 mask set in it, the call will return immediately.
  90 If
  91 .Fa msgflg
  92 does not have
  93 .Dv IPC_NOWAIT
  94 set in it, the call will block until:
  95 .Bl -bullet
  96 .It
  97 The condition which caused the call to block does no longer exist.
  98 The message will be sent.
  99 .It
 100 The message queue is removed, in which case -1 will be returned, and
 101 .Va errno
 102 is set to
 103 .Er EINVAL .
 104 .It
 105 The caller catches a signal.
 106 The call returns with
 107 .Va errno
 108 set to
 109 .Er EINTR .
 110 .El
 111 .Pp
 112 After a successful call, the data structure associated with the message
 113 queue is updated in the following way:
 114 .Bl -bullet
 115 .It
 116 .Va msg_cbytes
 117 is incremented by the size of the message.
 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 .Rv -std msgsnd
 130 .Sh ERRORS
 131 The
 132 .Fn msgsnd
 133 function
 134 will fail if:
 135 .Bl -tag -width Er
 136 .It Bq Er EINVAL
 137 The
 138 .Fa msqid
 139 argument
 140 is not a valid message queue identifier.
 141 .Pp
 142 The message queue was removed while
 143 .Fn msgsnd
 144 was waiting for a resource to become available in order to deliver the
 145 message.
 146 .Pp
 147 The
 148 .Fa msgsz
 149 argument
 150 is greater than
 151 .Va msg_qbytes .
 152 .Pp
 153 The
 154 .Fa mtype
 155 argument
 156 is not greater than 0.
 157 .It Bq Er EACCES
 158 The calling process does not have write access to the message queue.
 159 .It Bq Er EAGAIN
 160 There was no space for this message either on the queue, or in the whole
 161 system, and
 162 .Dv IPC_NOWAIT
 163 was set in
 164 .Fa msgflg .
 165 .It Bq Er EFAULT
 166 The
 167 .Fa msgp
 168 argument
 169 points to an invalid address.
 170 .It Bq Er EINTR
 171 The system call was interrupted by the delivery of a signal.
 172 .El
 173 .Sh HISTORY
 174 Message queues appeared in the first release of AT&T Unix System V.
 175 .Sh BUGS
 176 .Nx
 177 and
 178 .Fx
 179 do not define the
 180 .Er EIDRM
 181 error value, which should be used
 182 in the case of a removed message queue.