lib/libc/gen/msgsnd.3

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