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