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: src/lib/libc/gen/msgsnd.3,v 1.9.2.5 2001/12/14 18:33:51 ru Exp $
  33 .\"
  34 .Dd January 4, 2015
  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 system call 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 2 ) ,
  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 2 ) ,
  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 ENVIRONMENT
 126 The XSI Interprocess Communication family of functions is also available
 127 as an implementation in userspace.
 128 To use it, the
 129 .Xr sysvipcd 8
 130 daemon has to be running.
 131 .Pp
 132 If the
 133 .Ev USR_SYSVIPC
 134 variable is set in a process' environment, the process and its children
 135 will use the userspace implementation.
 136 .Sh ERRORS
 137 .Fn msgsnd
 138 will fail if:
 139 .Bl -tag -width Er
 140 .It Bq Er EINVAL
 141 .Fa msqid
 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 .Fa msgsz
 150 is less than 0, or greater than
 151 .Va msg_qbytes .
 152 .Pp
 153 .Fa mtype
 154 is not greater than 0.
 155 .It Bq Er EACCES
 156 The calling process does not have write access to the message queue.
 157 .It Bq Er EAGAIN
 158 There was no space for this message either on the queue, or in the whole
 159 system, and
 160 .Dv IPC_NOWAIT
 161 was set in
 162 .Fa msgflg .
 163 .It Bq Er EFAULT
 164 .Fa msgp
 165 points to an invalid address.
 166 .It Bq Er EINTR
 167 The system call was interrupted by the delivery of a signal.
 168 .El
 169 .Sh HISTORY
 170 Message queues appeared in the first release of AT&T Unix System V.
 171 .Sh AUTHORS
 172 .An -nosplit
 173 The
 174 .Dx
 175 specific userspace implementation (see
 176 .Sx ENVIRONMENT )
 177 was written by
 178 .An Larisa Grigore .
 179 .Sh BUGS
 180 .Nx Ns ,
 181 .Dx Ns ,
 182 and
 183 .Fx
 184 do not define the
 185 .Er EIDRM
 186 error value, which should be used
 187 in the case of a removed message queue.