msgrcv

Reads a message from a message queue.

Syntax

   #include <sys/types.h>

   #include <sys/ipc.h>

   #include <sys/msg.h>



   int msgrcv (int msqid, void *msgp, int msgsz, 

              long msgtyp, int msgflg);

Parameters

msqid

Passes message queue identifier returned by a call to msgget().

msgp

Passes a pointer to a buffer whose structure is similar to the msgbuf example template located in <msg.h>, for example:

struct example_msgbuf {



   long   mtype;                  /* message type          */

   char   mtext[your_buffer_size];  /* message text          */



   };

where your_buffer_size is an integer specifying the size of the buffer. The mtype field stores the received message's type as specified by the process that sent the message. The mtext field stores the text of the message. The size of mtext is specified by the msgsz argument.

msgsz

Passes the size, in bytes, of mtext. Valid values are from 0 to a system-defined limit.

msgtyp

Passes a value specifying the type of message requested. Following are valid values and their meanings:

0: Read the first message on the queue.
>0: Read the first message on the queue whose type equals msgtyp.
<0: Read a message from the queue whose type is the lowest type of all messages in that queue that is less than or equal to the absolute value of msgtyp.

msgflg

Passes a value defining what action to take if either a message specified by msgtyp is not found on the message queue or the message is too large to fit in the buffer. Flags are:

IPC_NOWAIT: The calling process is not suspended. Control returns immediately with errno set to ENOMSG.
MSG_NOERROR: If the message to receive is larger than msgsz, the message is truncated to msgsz bytes. No error indication is given.

If msgflg does not specify IPC_NOWAIT, the calling process suspends execution until a message satisfying the msgtyp specifications is placed on the queue. When this occurs, control returns to msgrcv(). If MSG_NOERROR is not set, and the selected message is larger than the buffer pointed to by msgp, msgrcv() returns an error and sets errno to E2BIG.

Return Values

>=0: Success. The number of bytes actually placed into the mtext field of the data structure pointed to by msgp is returned.
-1: An error occurred, and errno is set to indicate the error condition.

Description

The msgrcv() function reads a message from the message queue specified by msqid and places it in the buffer pointed to by msgp.

If the MSG_NOERROR option is set in msgflg, the received message is truncated to msgsz bytes if it is larger than msgsz. The truncated part of the message is lost and no indication of the truncation is given.

If the calling process is suspended waiting for a message, the following conditions will cause msgrcv() to return an error and set errno to indicate the error condition.

The message queue specified by msqid is removed from the system
The calling process receives a signal that is to be caught.

If msgrcv() is successful, the following fields of the data structure associated with msqid are updated to the indicated values:

msg_qnum: Decremented by 1
msg_lrpid: PID of the calling process
msg_rtime: Current time

Implementation Considerations

If a process suspended during execution of msgrcv() receives a signal, control returns to the user with errno set to EINTR. Disabled signals are ignored.

Errors

If an error occurs, errno is set to one of the following values.

`E2BIG`	CAUSE	`msgsz` is less than the size of the message and `msgflg` does not specify `MSG_NOERROR`.
	ACTION	Increase the `msgsz` parameter and associated buffer space, or specify the `MSG_NOERROR` option to allow truncation of the received message.
`EACCES`	CAUSE	The calling process does not have permission.
	ACTION	Ensure that the calling process has read access for the message queue.
`EFAULT`	CAUSE	The system detected a NULL or bad address in attempting to use the `msgp` argument.
	ACTION	Check to see if the pointer is correctly initialized.
`EIDRM`	CAUSE	The message queue specified by `msqid` was removed while the process was suspended in `msgrcv()`.
	ACTION	None.
`EINTR`	CAUSE	A process waited in `msgrcv()` was interrupted by a signal.
	ACTION	Application dependent.
`EINVAL`	CAUSE	`msqid` is not a valid message queue identifier, or `msgsz` is less than 0 or greater than the system-defined limit.
	ACTION	Check the `msqid` to make sure it is valid and the message queue has not been removed from the system. Verify that a positive `msgsz` was specified that does not exceed the currently configured limit.
`ENOMSG`	CAUSE	The specified message queue does not contain a message of the type specified in `mtype` and `msgflg` specifies `IPC_NOWAIT`.
	ACTION	None. Application dependent. The receive operation can be retried.
`ESYSERR`	CAUSE	An operating system error occurred that does not map directly to any of the above errors.
	ACTION	Examine the MPE/iX process error stack for the type of system error.

msgrcv

Technical documentation

» Table of Contents

» Index