lib/libc/sys/msgrcv.2

   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 .\"
  32 .\" $FreeBSD: src/lib/libc/gen/msgrcv.3,v 1.8.2.7 2003/03/15 15:11:05 trhodes Exp $
  33 .\"
  34 .Dd January 4, 2014
  35 .Dt MSGRCV 2
  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 system call 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.
  76 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.
  84 The first message on the queue will be received.
  85 .It
  86 The
  87 .Fa msgtyp
  88 argument
  89 is less than 0.
  90 The first message of the lowest message type that is
  91 less than or equal to the absolute value of
  92 .Fa msgtyp
  93 will be received.
  94 .El
  95 .Pp
  96 The
  97 .Fa msgsz
  98 argument
  99 specifies the maximum length of the requested message.
 100 If the received
 101 message has a length greater than
 102 .Fa msgsz
 103 it will be silently truncated if the
 104 .Dv MSG_NOERROR
 105 flag is set in
 106 .Fa msgflg ,
 107 otherwise an error will be returned.
 108 .Pp
 109 If no matching message is present on the message queue specified by
 110 .Fa msqid ,
 111 the behavior of
 112 .Fn msgrcv
 113 depends on whether the
 114 .Dv IPC_NOWAIT
 115 flag is set in
 116 .Fa msgflg
 117 or not.
 118 If
 119 .Dv IPC_NOWAIT
 120 is set,
 121 .Fn msgrcv
 122 will immediately return a value of -1, and set
 123 .Va errno
 124 to
 125 .Er EAGAIN .
 126 If
 127 .Dv IPC_NOWAIT
 128 is not set, the calling process will be blocked
 129 until:
 130 .Bl -bullet
 131 .It
 132 A message of the requested type becomes available on the message queue.
 133 .It
 134 The message queue is removed, in which case -1 will be returned, and
 135 .Va errno
 136 set to
 137 .Er EINVAL .
 138 .It
 139 A signal is received and caught.
 140 -1 is returned, and
 141 .Va errno
 142 set to
 143 .Er EINTR .
 144 .El
 145 .Pp
 146 If a message is successfully received, the data structure associated with
 147 .Fa msqid
 148 is updated as follows:
 149 .Bl -bullet
 150 .It
 151 .Va msg_cbytes
 152 is decremented by the size of the message.
 153 .It
 154 .Va msg_lrpid
 155 is set to the pid of the caller.
 156 .It
 157 .Va msg_lrtime
 158 is set to the current time.
 159 .It
 160 .Va msg_qnum
 161 is decremented by 1.
 162 .El
 163 .Sh RETURN VALUES
 164 Upon successful completion,
 165 .Fn msgrcv
 166 returns the number of bytes received into the
 167 .Va mtext
 168 field of the structure pointed to by
 169 .Fa msgp .
 170 Otherwise, -1 is returned, and
 171 .Va errno
 172 set to indicate the error.
 173 .Sh ENVIRONMENT
 174 The XSI Interprocess Communication family of functions is also available
 175 as an implementation in userspace.
 176 To use it, the
 177 .Xr sysvipcd 8
 178 daemon has to be running.
 179 .Pp
 180 If the
 181 .Ev USR_SYSVIPC
 182 variable is set in a process' environment, the process and its children
 183 will use the userspace implementation.
 184 .Sh ERRORS
 185 The
 186 .Fn msgrcv
 187 system call will fail if:
 188 .Bl -tag -width Er
 189 .It Bq Er EINVAL
 190 The
 191 .Fa msqid
 192 argument
 193 is not a valid message queue identifier.
 194 .Pp
 195 The message queue was removed while
 196 .Fn msgrcv
 197 was waiting for a message of the requested type to become available on it.
 198 .Pp
 199 The
 200 .Fa msgsz
 201 argument
 202 is less than 0.
 203 .It Bq Er E2BIG
 204 A matching message was received, but its size was greater than
 205 .Fa msgsz
 206 and the
 207 .Dv MSG_NOERROR
 208 flag was not set in
 209 .Fa msgflg .
 210 .It Bq Er EACCES
 211 The calling process does not have read access to the message queue.
 212 .It Bq Er EFAULT
 213 The
 214 .Fa msgp
 215 argument
 216 points to an invalid address.
 217 .It Bq Er EINTR
 218 The system call was interrupted by the delivery of a signal.
 219 .It Bq Er EAGAIN
 220 There is no message of the requested type available on the message queue,
 221 and
 222 .Dv IPC_NOWAIT
 223 is set in
 224 .Fa msgflg .
 225 .El
 226 .Sh SEE ALSO
 227 .Xr msgctl 2 ,
 228 .Xr msgget 2 ,
 229 .Xr msgsnd 2
 230 .Sh HISTORY
 231 Message queues appeared in the first release of
 232 .At V .
 233 .Sh AUTHORS
 234 .An -nosplit
 235 The
 236 .Dx
 237 specific userspace implementation (see
 238 .Sx ENVIRONMENT )
 239 was written by
 240 .An Larisa Grigore .
 241 .Sh BUGS
 242 .Nx ,
 243 .Dx ,
 244 and
 245 .Fx
 246 do not define the
 247 .Er EIDRM
 248 error value, which should be used in
 249 the case of a removed message queue, nor the
 250 .Er ENOMSG
 251 value, which
 252 should be used when no suitable message is available and
 253 .Dv IPC_NOWAIT
 254 is set.