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 .\" $FreeBSD$
  32 .\"
  33 .\"/
  34 .Dd July 9, 2009
  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 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.
  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 ENOMSG .
 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 ERRORS
 174 The
 175 .Fn msgrcv
 176 function
 177 will fail if:
 178 .Bl -tag -width Er
 179 .It Bq Er EINVAL
 180 The
 181 .Fa msqid
 182 argument
 183 is not a valid message queue identifier.
 184 .Pp
 185 The message queue was removed while
 186 .Fn msgrcv
 187 was waiting for a message of the requested type to become available on it.
 188 .Pp
 189 The
 190 .Fa msgsz
 191 argument
 192 is less than 0.
 193 .It Bq Er E2BIG
 194 A matching message was received, but its size was greater than
 195 .Fa msgsz
 196 and the
 197 .Dv MSG_NOERROR
 198 flag was not set in
 199 .Fa msgflg .
 200 .It Bq Er EACCES
 201 The calling process does not have read access to the message queue.
 202 .It Bq Er EFAULT
 203 The
 204 .Fa msgp
 205 argument
 206 points to an invalid address.
 207 .It Bq Er EINTR
 208 The system call was interrupted by the delivery of a signal.
 209 .It Bq Er ENOMSG
 210 There is no message of the requested type available on the message queue,
 211 and
 212 .Dv IPC_NOWAIT
 213 is set in
 214 .Fa msgflg .
 215 .El
 216 .Sh SEE ALSO
 217 .Xr msgctl 2 ,
 218 .Xr msgget 2 ,
 219 .Xr msgsnd 2
 220 .Sh HISTORY
 221 Message queues appeared in the first release of
 222 .At V .