lib/libcr/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 .\"
  34 .Dd November 24, 1997
  35 .Dt MSGSND 3
  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" "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 .Fa msgp
  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 3 ) ,
  65 .Va mtext
  66 is an array of bytes, with a size up to that of the system limit
  67 .Pf ( Dv MSGMAX ) .
  68 .Pp
  69 If the number of bytes already on the message queue plus
  70 .Fa msgsz
  71 is bigger than the maximum number of bytes on the message queue
  72 .Pf ( Va msg_qbytes ,
  73 see
  74 .Xr msgctl 3 ) ,
  75 or the number of messages on all queues system-wide is already equal to
  76 the system limit,
  77 .Fa msgflg
  78 determines the action of
  79 .Fn msgsnd .
  80 If
  81 .Fa msgflg
  82 has
  83 .Dv IPC_NOWAIT
  84 mask set in it, the call will return immediately.
  85 If
  86 .Fa msgflg
  87 does not have
  88 .Dv IPC_NOWAIT
  89 set in it, the call will block until:
  90 .Bl -bullet
  91 .It
  92 The condition which caused the call to block does no longer exist.
  93 The message will be sent.
  94 .It
  95 The message queue is removed, in which case -1 will be returned, and
  96 .Va errno
  97 is set to
  98 .Er EINVAL .
  99 .It
 100 The caller catches a signal.
 101 The call returns with
 102 .Va errno
 103 set to
 104 .Er EINTR .
 105 .El
 106 .Pp
 107 After a successful call, the data structure associated with the message
 108 queue is updated in the following way:
 109 .Bl -bullet
 110 .It
 111 .Va msg_cbytes
 112 is incremented by the size of the message.
 113 .It
 114 .Va msg_qnum
 115 is incremented by 1.
 116 .It
 117 .Va msg_lspid
 118 is set to the pid of the calling process.
 119 .It
 120 .Va msg_stime
 121 is set to the current time.
 122 .El
 123 .Sh RETURN VALUES
 124 .Rv -std msgsnd
 125 .Sh ERRORS
 126 .Fn msgsnd
 127 will fail if:
 128 .Bl -tag -width Er
 129 .It Bq Er EINVAL
 130 .Fa msqid
 131 is not a valid message queue identifier
 132 .Pp
 133 The message queue was removed while
 134 .Fn msgsnd
 135 was waiting for a resource to become available in order to deliver the
 136 message.
 137 .Pp
 138 .Fa msgsz
 139 is less than 0, or greater than
 140 .Va msg_qbytes .
 141 .Pp
 142 .Fa mtype
 143 is not greater than 0.
 144 .It Bq Er EACCES
 145 The calling process does not have write access to the message queue.
 146 .It Bq Er EAGAIN
 147 There was no space for this message either on the queue, or in the whole
 148 system, and
 149 .Dv IPC_NOWAIT
 150 was set in
 151 .Fa msgflg .
 152 .It Bq Er EFAULT
 153 .Fa msgp
 154 points to an invalid address.
 155 .It Bq Er EINTR
 156 The system call was interrupted by the delivery of a signal.
 157 .El
 158 .Sh BUGS
 159 .Nx
 160 and
 161 .Fx
 162 do not define the
 163 .Er EIDRM
 164 error value, which should be used
 165 in the case of a removed message queue.
 166 .Sh HISTORY
 167 Message queues appeared in the first release of AT&T Unix System V.