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. 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 ENVIRONMENT
 170 The XSI Interprocess Communication family of functions is also available
 171 as an implementation in userspace.
 172 To use it, the
 173 .Xr sysvipcd 8
 174 daemon has to be running.
 175 .Pp
 176 If the
 177 .Ev USR_SYSVIPC
 178 variable is set in a process' environment, the process and its children
 179 will use the userspace implementation.
 180 .Sh ERRORS
 181 The
 182 .Fn msgrcv
 183 system call will fail if:
 184 .Bl -tag -width Er
 185 .It Bq Er EINVAL
 186 The
 187 .Fa msqid
 188 argument
 189 is not a valid message queue identifier.
 190 .Pp
 191 The message queue was removed while
 192 .Fn msgrcv
 193 was waiting for a message of the requested type to become available on it.
 194 .Pp
 195 The
 196 .Fa msgsz
 197 argument
 198 is less than 0.
 199 .It Bq Er E2BIG
 200 A matching message was received, but its size was greater than
 201 .Fa msgsz
 202 and the
 203 .Dv MSG_NOERROR
 204 flag was not set in
 205 .Fa msgflg .
 206 .It Bq Er EACCES
 207 The calling process does not have read access to the message queue.
 208 .It Bq Er EFAULT
 209 The
 210 .Fa msgp
 211 argument
 212 points to an invalid address.
 213 .It Bq Er EINTR
 214 The system call was interrupted by the delivery of a signal.
 215 .It Bq Er EAGAIN
 216 There is no message of the requested type available on the message queue,
 217 and
 218 .Dv IPC_NOWAIT
 219 is set in
 220 .Fa msgflg .
 221 .El
 222 .Sh SEE ALSO
 223 .Xr msgctl 2 ,
 224 .Xr msgget 2 ,
 225 .Xr msgsnd 2
 226 .Sh HISTORY
 227 Message queues appeared in the first release of
 228 .At V .
 229 .Sh AUTHORS
 230 .An -nosplit
 231 The
 232 .Dx
 233 specific userspace implementation (see
 234 .Sx ENVIRONMENT )
 235 was written by
 236 .An Larisa Grigore .
 237 .Sh BUGS
 238 .Nx ,
 239 .Dx ,
 240 and
 241 .Fx
 242 do not define the
 243 .Er EIDRM
 244 error value, which should be used in
 245 the case of a removed message queue, nor the
 246 .Er ENOMSG
 247 value, which
 248 should be used when no suitable message is available and
 249 .Dv IPC_NOWAIT
 250 is set.