NAME
msgrcv —
receive a message from a
message queue
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/msg.h>
ssize_t
msgrcv(
int
msqid,
void *msgp,
size_t msgsz,
long msgtyp,
int msgflg);
DESCRIPTION
The
msgrcv() function receives a message from the message
queue specified in
msqid, and places it into the
user-defined structure pointed to by
msgp. This
structure must contain a first field of type
long that will
indicate the user-defined type of the message. The remaining fields will
contain the contents of the message. The following is an example of what this
user-defined structure might look like:
struct mymsg {
long mtype; /* message type */
char mtext[1]; /* body of message */
};
mtype is an integer greater than 0 that can be used to
select messages.
mtext is an array of bytes, with size
up to the system limit
MSGMAX
.
The value of
msgtyp has one of the following meanings:
- msgtyp is greater than 0. The
first message of type msgtyp will be received.
- msgtyp is equal to 0. The first
message on the queue will be received.
- msgtyp is less than 0. The first
message of the lowest message type that is less than or equal to the
absolute value of msgtyp will be received.
The argument
msgsz specifies the size in bytes of
mtext. If the received message has a length greater than
msgsz it will be silently truncated if the
MSG_NOERROR
flag is set in
msgflg, otherwise an error will be returned.
If no matching message is present on the message queue specified by
msqid, the behaviour of
msgrcv()
depends on whether the
IPC_NOWAIT
flag is set in
msgflg or not. If
IPC_NOWAIT
is
set, then
msgrcv() will immediately return a value of -1 and
set
errno to
EAGAIN
. If
IPC_NOWAIT
is not set, the calling process will block
until:
- A message of the requested type becomes available on the
message queue.
- The message queue is removed, in which case -1 will be
returned and errno set to
EIDRM
.
- A signal is received and caught. -1 is returned and
errno is set to
EINTR
.
If a message is successfully received, the data structure associated with
msqid is updated as follows:
- msg_lrpid is set to the pid of the
caller.
- msg_lrtime is set to the current
time.
- msg_qnum is decremented by 1.
RETURN VALUES
Upon successful completion,
msgrcv() returns the number of
bytes received and placed into the
mtext field of the
structure pointed to by
msgp. Otherwise, -1 is returned,
and
errno set to indicate the error.
ERRORS
msgrcv() will fail if:
-
-
- [
E2BIG
]
- A matching message was received, but its size was greater
than msgsz and the
MSG_NOERROR
flag was not set in
msgflg.
-
-
- [
EACCES
]
- The calling process does not have read access to the
message queue.
-
-
- [
EAGAIN
]
- There is no message of the requested type available on the
message queue, and
IPC_NOWAIT
is set in
msgflg.
-
-
- [
EFAULT
]
- msgp points to an invalid
address.
-
-
- [
EIDRM
]
- The message queue identifier msqid is
removed from the system.
-
-
- [
EINTR
]
- The system call was interrupted by the delivery of a
signal.
-
-
- [
EINVAL
]
- msqid is not a valid message queue
identifier
The message queue was removed while msgrcv() was waiting
for a message of the requested type to become available in it.
msgsz is greater than
SSIZE_MAX
.
-
-
- [
ENOMSG
]
- The queue does not contain a message of the desired type
and
IPC_NOWAIT
is set.
SEE ALSO
msgctl(2),
msgget(2),
msgsnd(2)
STANDARDS
The
msgrcv system call conforms to
X/Open
System Interfaces and Headers Issue 5 (“XSH5”).
HISTORY
Message queues appeared in the first release of
AT&T
System V UNIX.