Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
msgrcv(2)			 System	Calls			     msgrcv(2)

       msgrcv -	message	receive	operation

       #include	<sys/msg.h>

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

       The msgrcv() function reads a message from the  queue  associated  with
       the  message  queue  identifier specified by msqid and places it	in the
       user-defined buffer pointed to by msgp.

       The msgp	argument points	to a user-defined  buffer  that	 must  contain
       first  a	 field of type long int	that will specify the type of the mes-
       sage, and then a	data portion that will hold the	data bytes of the mes-
       sage.  The structure below is an	example	of what	this user-defined buf-
       fer might look like:

       struct mymsg {
	       long int	   mtype;     /* message type */
	       char	   mtext[1];  /* message text */

       The mtype member	is the received	message's type	as  specified  by  the
       sending process.

       The mtext member	is the text of the message.

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

       The msgtyp argument specifies the type of message requested as follows:

	 o  If msgtyp is 0, the	first message on the queue is received.

	 o  If	msgtyp	is greater than	0, the first message of	type msgtyp is

	 o  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 re-

       The msgflg argument specifies which of the following actions is	to  be
       taken if	a message of the desired type is not on	the queue:

	 o  If	(msgflg&IPC_NOWAIT)  is	non-zero, the calling process will re-
	    turn immediately with a return  value  of  -1  and	errno  set  to

	 o  If (msgflg&IPC_NOWAIT) is 0, the calling process will suspend exe-
	    cution until one of	the following occurs:

	      o	 A message of the desired type is placed on the	queue.

		 The message queue identifier msqid is removed from the	system
		 (see  msgctl(2)); when	this occurs, errno is set equal	to EI-
		 DRM and -1 is returned.

	      o	 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 in the manner prescribed in	sigac-

       Upon  successful	 completion,  the following actions are	taken with re-
       spect to	the data structure associated with msqid (see intro(2)):

	 o  msg_qnum is	decremented by 1.

	 o  msg_lrpid is set equal to the process ID of	the calling process.

	 o  msg_rtime is set equal to the current time.

       Upon successful completion, msgrcv() returns a value equal to the  num-
       ber  of	bytes  actually	placed into the	buffer mtext. Otherwise, -1 is
       returned, no message is received, and errno is set to indicate the  er-

       The msgrcv() function will fail if:

       E2BIG	       The  value  of  mtext  is  greater  than	msgsz and (ms-
		       gflg&MSG_NOERROR) is 0.

       EACCES	       Operation permission is denied to the calling  process.
		       See intro(2).

       EIDRM	       The  message queue identifier msqid is removed from the

       EINTR	       The msgrcv() function was interrupted by	a signal.

       EINVAL	       The msqid argument is not a valid message queue identi-

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

       The msgrcv() function may fail if:

	EFAULT	       The msgp	argument points	to an illegal address.

       The value passed	as the msgp argument should be converted to type  void

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |

       intro(2), msgctl(2), msgget(2), msgsnd(2), sigaction(2),	attributes(5),

SunOS 5.10			  19 May 1999			     msgrcv(2)


Want to link to this manual page? Use this URL:

home | help