tt_message_receive(3)

tt_message_receive(3)  C LIBRARY FUNCTIONS  tt_message_receive(3)

NAME
     tt_message_receive	- receive a message

SYNOPSIS
     #include <Tt/tt_c.h>

     Tt_message	tt_message_receive(void);

DESCRIPTION
     The tt_message_receive() function returns a handle	 for  the
     next  message queued to be	delivered to the process and also
     runs any message or  pattern  callbacks  applicable  to  the
     queued message.

     If	the return value of tt_message_status(3) for this message
     is	 TT_WRN_START_MESSAGE,	the  ToolTalk service started the
     process to	deliver	the  queued  message;  the  process  must
     reply   to	  this	 message.    If	  the	return	value  of
     tt_message_receive() is zero, no message is available.

RETURN VALUE
     Upon successful completion, the  tt_message_receive()  func-
     tion  returns the handle for the message object.  The appli-
     cation can	use tt_ptr_error(3) to extract one of the follow-
     ing Tt_status values from the returned handle:

	TT_OK	The operation completed	successfully.

	TT_ERR_NOMP
		The ttsession(1) process is not	running	 and  the
		ToolTalk service cannot	restart	it.

APPLICATION USAGE
     A zero value can occur if	a  message  or	pattern	 callback
     processes the message.  It	can also occur if the interval is
     too long between the time the file	descriptor became  active
     and  the  tt_message_receive() call was made.  In the latter
     case, the ToolTalk	service	will time out and offer	the  mes-
     sage to another process.

     The application should  use  tt_free(3)  to  free	any  data
     stored in the address returned by the ToolTalk API.

SEE ALSO
     Tttt_c(5),	tt_ptr_error(3), tt_free(3).

Unix System LaboratorLast change: 11 May 1994			1