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