msgrcv()

read message from queue 

Function


SYNOPSIS

#include <sys/msg.h>

int msgrcv(int msqid, void *msgp, int msgsz, long msgtyp, int msgflg);


DESCRIPTION

The msgrcv() function reads a message from the queue associated with the message queue identifier that msqid specifies and places it in the user-defined structure that msgp points to. When successfully completed, the following actions are taken with respect to the data structure associated with msqid:

The argument msgp must point to a user-defined buffer that must contain first a field of type long int that specifies the type of the message, and then a data portion that holds the data bytes of the message. The following structure is an example of how a user-defined buffer might be declared:

struct mymsg {
	long int mtype;
	char mtext[1];
}

The structure member mtype is the received message's type as specified by the sending process, and the structure member mtext is the text of the message.

The argument msgsz is the size in bytes of mtext. The received message is truncated to msgsz bytes if it is larger than msgsz and (msgflg & MSG_NOERROR) is non-zero. The truncated part of the message is lost, and no indication of the truncation is given to the calling process.


PARAMETERS

msqid 

Is a unique positive integer, created by a msgget() call, that identifies a message queue.

msgp 

Points to a user-defined buffer.

msgsz 

Specifies the size, in bytes, of mtext.

msgtyp 

Specifies the type of message requested as follows:

  • If msgtyp is 0, the first message on the queue is received.
  • If msgtyp is greater than 0, the first message of type msgtyp is received.
  • If msgtyp is less than 0, the first message of the lowest type that is less than or equal to the absolute value of msgtyp is received.
msgflg 

Specifies the action to be taken if a message of the desired type is not in the queue. The possible actions are:

  • If (msgflg & IPC_NOWAIT) is non-zero, the calling process returns immediately with a return value of -1 and sets errno to ENOMSG.
  • If (msgflg & IPC_NOWAIT) is zero, the calling process suspends execution until one of the following occurs:
  • A message of the desired type is placed on the queue.
  • msqid is removed from the system. When this occurs, errno is set to EIDRM, and a value of -1 is returned.
  • The calling process receives a signal that is to be caught. In this case, a message is not received and the calling process resumes execution as appropriate for the signal.


RETURN VALUES

If successful, msgrcv() returns the number of bytes actually placed into mtext. On failure, msgrcv() returns a value of -1, receives no message, and sets errno to one of the following values:

E2BIG 

The length of mtext is greater than msgsz and (msgflg & MSG_NOERROR) is zero.

EACCES 

Operation permission is denied to the calling process.

EFAULT 

msgp is an invalid pointer.

EIDRM 

msqid was removed.

EINTR 

A signal interrupted the call.

EINVAL 

msgsz is less than 0.

msqid is not a valid message queue identifier.

ENOMSG 

The queue does not contain a message of the desired type and (msgtyp & IPC_NOWAIT) is non-zero.


CONFORMANCE

Unix 98.


MULTITHREAD SAFETY LEVEL

MT-Safe.


PORTING ISSUES

None.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
msgctl(), msgget(), msgsnd()


PTC MKS Toolkit 10.3 Documentation Build 39.