unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



msgrcv(2)							    msgrcv(2)



NAME
  msgrcv -  Receives a message from a message queue

SYNOPSIS

  #include <&lt;sys/msg.h>&gt;

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

  Application developers may want to specify #include statements for
  <&lt;sys/types.h>&gt;	and <&lt;sys/ipc.h>&gt;	before the one for <&lt;sys/msg.h>&gt; if programs
  are being developed for multiple platforms. The additional #include state-
  ments	are not	required on Tru64 UNIX systems or by ISO or X/Open standards,
  but may be required on other vendors'	systems	that conform to	these stan-
  dards.

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  msgrcv():  XSH5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  msqid	    Specifies the ID of	the message queue from which to	receive	the
	    message.

  msgp	    Specifies a	pointer	to the msgbuf structure	that is	to receive
	    the	message.  See the NOTES	section	for more information.

  msgsz	    Specifies the maximum number of bytes allowed for the received
	    data.  The msgsz parameter is only used to specify the size	of
	    the	msgbuf.mtext field.  It	cannot include the msgbuf.mtype	field
	    or else the	msgbuf buffer is overwritten.

  msgtyp    Specifies the message type to read from the	queue.

  msgflg    Specifies the action to be taken by	the kernel if there are	no
	    msgtyp messages on the queue.

DESCRIPTION

  The msgrcv() function	receives a message from	the queue associated with the
  msqid	parameter.  The	function returns the number of bytes in	the received
  message.

  The msgp parameter points to a user-defined msgbuf structure.	 This struc-
  ture receives	the message read from the queue.


  The msgsz parameter specifies	the maximum size allowed for the received
  data.	 If the	message	is longer than msgsz, the following occurs, depending
  upon the setting of the MSG_NOERROR flag:

    +  If MSG_NOERROR is not set, the kernel returns an	[E2BIG]	error to the
       calling process and leaves the message on the queue.

    +  If MSG_NOERROR is set, the kernel truncates the message to msgsz	and
       discards	the truncated portion without notifying	the calling process.

  The msgtyp parameter specifies the message type that the process expects to
  receive.  Possible values and	their results are as follows:

  0 (zero)  The	process	receives the message at	the head of the	queue.

  Greater than 0 (zero)
	    The	process	receives the first message of the requested
	    positive-integer type.

  Less than 0 (zero)
	    The	process	receives the first message of the lowest type on the
	    queue.  To qualify as the lowest type, the negative-integer	type
	    must be less than or equal to the absolute value of	msgtyp.

  The msgflg parameter specifies the action that the kernel should take	if
  the queue does not contain a message of the requested	type.  Either of two
  kernel actions can be	specified, as follows:

    +  If IPC_NOWAIT is	set, the function returns immediately with a return
       value of	-1 and sets errno to [ENOMSG].

    +  If IPC_NOWAIT is	not set, the kernel suspends the calling process.

       The process remains suspended until one of the following	occurs:

	 -- A message of the requested type appears on the queue.  In this
	    case, the kernel wakes the process to receive the message.

	 -- The	specified message queue	ID is removed from the system.	In
	    this case, the kernel sets errno to	[EIDRM]	and returns -1 to the
	    calling process.

	 -- The	process	catches	a signal.  In this case, the process does not
	    receive the	message	and, instead, resumes execution	as directed
	    by the sigaction() call.

NOTES

  The parameter	msgp points to a user-specified	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.	 For example:
       struct msgbuf {
	       long int	mtype;
	       char mtext[];
       }

  The mytpe field is set to the	message	type supplied by the sender.

  The mtext field is set to the	message	text.  Unless MSG_NOERROR is set, the
  message size will be less than or equal to the msgsz specified on the	call
  to msgrcv().

RETURN VALUES

  Upon successful completion, the msgrcv() function returns a value equal to
  the number of	bytes actually stored in mtext.	 Also, the kernel updates the
  msqid_ds structure associated	with the message queue ID as follows:

    +  Decrements msg_qnum by 1.

    +  Sets msg_lrpid equal to the process ID of the calling process.

    +  Sets msg_rtime equal to the current time.

    +  [Tru64 UNIX]  Decrements	msg_cbytes by the message text size.

  When the msgrcv() function fails, it returns a value of -1 and sets errno
  to indicate the error.

ERRORS

  The msgrcv() function	sets errno to the specified values for the following
  conditions:

  [E2BIG]   The	number of bytes	to be received in mtext	is greater than	msgsz
	    and	the MSG_NOERROR	flag is	not set.

  [EACCES]  The	calling	process	does not have permission for the operation.

  [EFAULT]  Indicates that the requested address is in some way	invalid, for
	    example, out of bounds.

  [EIDRM]   The	message	queue identified by the	msqid parameter	has been
	    removed from the system.

  [EINTR]   The	operation was interrupted by a signal.

  [EINVAL]  The	msqid parameter	is not a valid message queue ID.

  [ENOMSG]  The	queue does not contain a message of the	requested type and
	    the	IPC_NOWAIT flag	is set.

RELATED	INFORMATION

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

  Data Structures: msqid_ds(4)

  Standards: standards(5)