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.16 2001/10/01 16:08:51 ru 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 .Fa msgtyp
  73 is greater than 0. The first message of type
  74 .Fa msgtyp
  75 will be received.
  76 .It
  77 .Fa msgtyp
  78 is equal to 0. The first message on the queue will be received.
  79 .It
  80 .Fa msgtyp
  81 is less than 0. The first message of the lowest message type that is
  82 less than or equal to the absolute value of
  83 .Fa msgtyp
  84 will be received.
  85 .El
  86 .Pp
  87 .Fa msgsz
  88 specifies the maximum length of the requested message.
  89 If the received
  90 message has a length greater than
  91 .Fa msgsz
  92 it will be silently truncated if the
  93 .Dv MSG_NOERROR
  94 flag is set in
  95 .Fa msgflg ,
  96 otherwise an error will be returned.
  97 .Pp
  98 If no matching message is present on the message queue specified by
  99 .Fa msqid ,
 100 the behavior of
 101 .Fn msgrcv
 102 depends on whether the
 103 .Dv IPC_NOWAIT
 104 flag is set in
 105 .Fa msgflg
 106 or not.
 107 If
 108 .Dv IPC_NOWAIT
 109 is set,
 110 .Fn msgrcv
 111 will immediately return a value of -1, and set
 112 .Va errno
 113 to
 114 .Er EAGAIN .
 115 If
 116 .Dv IPC_NOWAIT
 117 is not set, the calling process will be blocked
 118 until:
 119 .Bl -bullet
 120 .It
 121 A message of the requested type becomes available on the message queue.
 122 .It
 123 The message queue is removed, in which case -1 will be returned, and
 124 .Va errno
 125 set to
 126 .Er EINVAL .
 127 .It
 128 A signal is received and caught. -1 is returned, and
 129 .Va errno
 130 set to
 131 .Er EINTR .
 132 .El
 133 .Pp
 134 If a message is successfully received, the data structure associated with
 135 .Fa msqid
 136 is updated as follows:
 137 .Bl -bullet
 138 .It
 139 .Va msg_cbytes
 140 is decremented by the size of the message.
 141 .It
 142 .Va msg_lrpid
 143 is set to the pid of the caller.
 144 .It
 145 .Va msg_lrtime
 146 is set to the current time.
 147 .It
 148 .Va msg_qnum
 149 is decremented by 1.
 150 .El
 151 .Sh RETURN VALUES
 152 Upon successful completion,
 153 .Fn msgrcv
 154 returns the number of bytes received into the
 155 .Va mtext
 156 field of the structure pointed to by
 157 .Fa msgp .
 158 Otherwise, -1 is returned, and
 159 .Va errno
 160 set to indicate the error.
 161 .Sh ERRORS
 162 .Fn msgrcv
 163 will fail if:
 164 .Bl -tag -width Er
 165 .It Bq Er EINVAL
 166 .Fa msqid
 167 is not a valid message queue identifier.
 168 .Pp
 169 The message queue was removed while
 170 .Fn msgrcv
 171 was waiting for a message of the requested type to become available on it.
 172 .Pp
 173 .Fa msgsz
 174 is less than 0.
 175 .It Bq Er E2BIG
 176 A matching message was received, but its size was greater than
 177 .Fa msgsz
 178 and the
 179 .Dv MSG_NOERROR
 180 flag was not set in
 181 .Fa msgflg .
 182 .It Bq Er EACCES
 183 The calling process does not have read access to the message queue.
 184 .It Bq Er EFAULT
 185 .Fa msgp
 186 points to an invalid address.
 187 .It Bq Er EINTR
 188 The system call was interrupted by the delivery of a signal.
 189 .It Bq Er EAGAIN
 190 There is no message of the requested type available on the message queue,
 191 and
 192 .Dv IPC_NOWAIT
 193 is set in
 194 .Fa msgflg .
 195 .El
 196 .Sh SEE ALSO
 197 .Xr msgctl 3 ,
 198 .Xr msgget 3 ,
 199 .Xr msgsnd 3
 200 .Sh HISTORY
 201 Message queues appeared in the first release of
 202 .At V .