lib/libc/gen/msgrcv.3

   1 .\"     $NetBSD: msgrcv.2,v 1.1 1995/10/16 23:49:20 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 .\" $FreeBSD: src/lib/libc/gen/msgrcv.3,v 1.8.2.7 2003/03/15 15:11:05 trhodes Exp $
  32 .\" $DragonFly: src/lib/libc/gen/msgrcv.3,v 1.4 2006/02/17 19:35:06 swildner Exp $
  33 .\"
  34 .\"/
  35 .Dd November 24, 1997
  36 .Dt MSGRCV 3
  37 .Os
  38 .Sh NAME
  39 .Nm msgrcv
  40 .Nd receive a message from 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 msgrcv "int msqid" "void *msgp" "size_t msgsz" "long msgtyp" "int msgflg"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn msgrcv
  52 function receives a message from the message queue specified in
  53 .Fa msqid ,
  54 and places it into the structure pointed to by
  55 .Fa msgp .
  56 This structure should 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,
  64 .Va mtext
  65 is an array of bytes, with a size up to that of the system limit
  66 .Pf ( Dv MSGMAX ) .
  67 .Pp
  68 The value of
  69 .Fa msgtyp
  70 has one of the following meanings:
  71 .Bl -bullet
  72 .It
  73 The
  74 .Fa msgtyp
  75 argument
  76 is greater than 0. The first message of type
  77 .Fa msgtyp
  78 will be received.
  79 .It
  80 The
  81 .Fa msgtyp
  82 argument
  83 is equal to 0. The first message on the queue will be received.
  84 .It
  85 The
  86 .Fa msgtyp
  87 argument
  88 is less than 0. The first message of the lowest message type that is
  89 less than or equal to the absolute value of
  90 .Fa msgtyp
  91 will be received.
  92 .El
  93 .Pp
  94 The
  95 .Fa msgsz
  96 argument
  97 specifies the maximum length of the requested message.
  98 If the received
  99 message has a length greater than
 100 .Fa msgsz
 101 it will be silently truncated if the
 102 .Dv MSG_NOERROR
 103 flag is set in
 104 .Fa msgflg ,
 105 otherwise an error will be returned.
 106 .Pp
 107 If no matching message is present on the message queue specified by
 108 .Fa msqid ,
 109 the behavior of
 110 .Fn msgrcv
 111 depends on whether the
 112 .Dv IPC_NOWAIT
 113 flag is set in
 114 .Fa msgflg
 115 or not.
 116 If
 117 .Dv IPC_NOWAIT
 118 is set,
 119 .Fn msgrcv
 120 will immediately return a value of -1, and set
 121 .Va errno
 122 to
 123 .Er EAGAIN .
 124 If
 125 .Dv IPC_NOWAIT
 126 is not set, the calling process will be blocked
 127 until:
 128 .Bl -bullet
 129 .It
 130 A message of the requested type becomes available on the message queue.
 131 .It
 132 The message queue is removed, in which case -1 will be returned, and
 133 .Va errno
 134 set to
 135 .Er EINVAL .
 136 .It
 137 A signal is received and caught. -1 is returned, and
 138 .Va errno
 139 set to
 140 .Er EINTR .
 141 .El
 142 .Pp
 143 If a message is successfully received, the data structure associated with
 144 .Fa msqid
 145 is updated as follows:
 146 .Bl -bullet
 147 .It
 148 .Va msg_cbytes
 149 is decremented by the size of the message.
 150 .It
 151 .Va msg_lrpid
 152 is set to the pid of the caller.
 153 .It
 154 .Va msg_lrtime
 155 is set to the current time.
 156 .It
 157 .Va msg_qnum
 158 is decremented by 1.
 159 .El
 160 .Sh RETURN VALUES
 161 Upon successful completion,
 162 .Fn msgrcv
 163 returns the number of bytes received into the
 164 .Va mtext
 165 field of the structure pointed to by
 166 .Fa msgp .
 167 Otherwise, -1 is returned, and
 168 .Va errno
 169 set to indicate the error.
 170 .Sh ERRORS
 171 The
 172 .Fn msgrcv
 173 function
 174 will fail if:
 175 .Bl -tag -width Er
 176 .It Bq Er EINVAL
 177 The
 178 .Fa msqid
 179 argument
 180 is not a valid message queue identifier.
 181 .Pp
 182 The message queue was removed while
 183 .Fn msgrcv
 184 was waiting for a message of the requested type to become available on it.
 185 .Pp
 186 The
 187 .Fa msgsz
 188 argument
 189 is less than 0.
 190 .It Bq Er E2BIG
 191 A matching message was received, but its size was greater than
 192 .Fa msgsz
 193 and the
 194 .Dv MSG_NOERROR
 195 flag was not set in
 196 .Fa msgflg .
 197 .It Bq Er EACCES
 198 The calling process does not have read access to the message queue.
 199 .It Bq Er EFAULT
 200 The
 201 .Fa msgp
 202 argument
 203 points to an invalid address.
 204 .It Bq Er EINTR
 205 The system call was interrupted by the delivery of a signal.
 206 .It Bq Er EAGAIN
 207 There is no message of the requested type available on the message queue,
 208 and
 209 .Dv IPC_NOWAIT
 210 is set in
 211 .Fa msgflg .
 212 .El
 213 .Sh SEE ALSO
 214 .Xr msgctl 3 ,
 215 .Xr msgget 3 ,
 216 .Xr msgsnd 3
 217 .Sh HISTORY
 218 Message queues appeared in the first release of
 219 .At V .
 220 .Sh BUGS
 221 .Tn Nx Ns ,
 222 .Dx Ns ,
 223 and
 224 .Fx
 225 do not define the
 226 .Er EIDRM
 227 error value, which should be used in
 228 the case of a removed message queue, nor the
 229 .Er ENOMSG
 230 value, which
 231 should be used when no suitable message is available and
 232 .Dv IPC_NOWAIT
 233 is set.