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