Quit(4)

Quit(4)		 DEVICES AND NETWORK INTERFACES		  Quit(4)

NAME
     Quit request - terminate an operation or an entire	tool

SYNOPSIS
     Quit(in boolean silent,
	  in boolean force
	  [in messageID	operation2Quit]);

DESCRIPTION
     The Quit request terminates an operation or an entire  tool.
     Without  the  optional operation2Quit argument, this request
     asks the handling procid to quit.	If the request	succeeds,
     one  or  more  ToolTalk procids should call tt_close(3), and
     zero or more processes should exit.

     With the optional operation2Quit argument,	this request asks
     the  handler  to  terminate the indicated request.	 (Whether
     the terminated request must therefore be failed  depends  on
     its semantics.  Often, termination	can be considered to mean
     that the requested	operation has been  carried  out  to  the
     requester's satisfaction.)

     The Quit request should be	failed (and the	status	code  set
     appropriately)  when  the	termination  is	not performed-for
     example, because the silent argument was false and	the  user
     canceled the quit.

     The silent	argument affects user  notification  of	 termina-
     tion.   If	 silent	 is  True,  the	handler	is not allowed to
     block on user input before	terminating itself (or the  indi-
     cated  operation).	 If it is False, however, the handler may
     seek such input.

     The force argument	is a Boolean value indicating whether the
     handler should terminate itself (or the indicated operation)
     even if circumstances are	such  that  the	 tool  ordinarily
     would not perform the termination.

     For example, a tool might have a policy of	not quitting with
     unsaved  changes  unless the user has been	asked whether the
     changes should be saved.  When force is true,  such  a  tool
     should  terminate even when doing so would	lose changes that
     the user has not been asked by the	tool about saving.

     The operation2Quit	argument is the	request	 that  should  be
     terminated.   For	a  request  to be terminable, the handler
     must have sent a Status notice back to the	 requester  (thus
     identifying itself	to the requester).

ERRORS
     The ToolTalk service may return one of the	following  errors
     in	processing the Quit request:

Unix System LaboratorLast change: 13 May 1994			1

Quit(4)		 DEVICES AND NETWORK INTERFACES		  Quit(4)

	TT_DESKTOP_ECANCELED
	      The user overrode	the Quit request.

	TT_DESKTOP_ENOMSG
	      The operation2Quit argument does not refer  to  any
	      message currently	known by the handler.

APPLICATION USAGE
     The ttdt_session_join(3), and ttdt_message_accept(3),  func-
     tions  can	 be  used  to register for, and	help process, the
     Quit request.

     In	the successful case, ``zero or more'' procids  are  cited
     because  a	 single	process	can instantiate	multiple indepen-
     dent procids, and a single	procid can conceivably be  imple-
     mented by a set of	cooperating processes.

EXAMPLES
     The Quit request can be sent as in	the following example:

	  Tt_message msg = tttk_message_create(0, TT_REQUEST, TT_SESSION,
		      the_recipient_procid, TTDT_QUIT,
		      my_callback);
	  tt_message_iarg_add(msg, TT_IN, Tttk_boolean,	0);
	  tt_message_iarg_add(msg, TT_IN, Tttk_boolean,	0);
	  tt_message_send(msg);

WARNINGS
     Quit can also be sent as a	multicast notice, as an	edict  to
     all  tools	in the scope of	the message.  The consequences of
     doing so can be severe and	unexpected.

SEE ALSO
     tt_close(3), tt_message_iarg_add(3), tt_message_send(3),
     ttdt_message_accept(3), ttdt_session_join(3).

Unix System LaboratorLast change: 13 May 1994			2