Move session management protocol docs from xorg-docs here too

Since we don't have a smproto package, but ship the protocol headers
in this module, might as well keep the protocol docs with the headers

Signed-off-by: Alan Coopersmith <alan.coopersmith@sun.com>

1 files changed, 1623 insertions, 0 deletions

diff --git a/doc/xsmp.ms b/doc/xsmp.ms
new file mode 100644
index 0000000..7ab2cf6
--- /dev/null
+++ b/doc/xsmp.ms
@@ -0,0 +1,1623 @@
+.\" Use tbl, -ms, and macros.t
+.\" $Xorg: xsmp.ms,v 1.3 2000/08/17 19:42:19 cpqbld Exp $
+.EH ''''
+.OH ''''
+.EF ''''
+.OF ''''
+.ps 10
+.nr PS 10
+\&
+.TL
+\s+2\fBX Session Management Protocol\fP\s-2
+.sp
+X.Org Standard
+.sp
+X Version 11, Release 7
+.sp
+\*(xV
+.AU
+Mike Wexler
+.AI
+Kubota Pacific Computer, Inc.
+.AB
+.LP
+This document specifies a protocol that facilitates the management of groups
+of client applications by a session manager.  The session manager can cause
+clients to save their state, to shut down, and to be restarted into a
+previously saved state.  This protocol is layered on top of the X.Org
+ICE protocol.
+.AE
+.LP
+.bp
+\&
+.sp 8
+.LP
+.DS C
+X Window System is a trademark of The Open Group.
+.sp
+Copyright \(co 1992, 1993, 1994, 2002 The Open Group.
+.DE
+.sp 3
+.LP
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the ``Software''), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+.LP
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+.LP
+THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+.af PN i
+.EF ''\\\\n(PN''
+.OF ''\\\\n(PN''
+.bp 1
+.af PN 1
+.EH '\fBX Session Management Protocol\fP''\fB\*(xV\fP'
+.OH '\fBX Session Management Protocol\fP''\fB\*(xV\fP'
+.EF ''\fB\\\\n(PN\fP''
+.OF ''\fB\\\\n(PN\fP''
+.nH 1 "Acknowledgements"
+.LP
+First I would like to thank the entire ICCCM and Intrinsics working groups for
+the comments and suggestions. I would like to make special thanks to the 
+following people (in alphabetical order), Jordan Brown, Ellis Cohen, Donna 
+Converse, Vania Joloboff, Stuart Marks, Ralph Mor and Bob Scheifler.
+.nH 1 "Definitions and Goals"
+.LP
+The purpose of the X Session Management Protocol (XSMP) is to provide a
+uniform mechanism for users to save and restore their sessions.  A
+\fIsession\fP is a group of clients, each of which has a particular state.
+The session is controlled by a network service called the \fIsession
+manager\fP\^.  The session manager issues commands to its clients on behalf
+of the user.  These commands may cause clients to save their state or to
+terminate.  It is expected that the client will save its state in such a
+way that the client can be restarted at a later time and resume its
+operation as if it had never been terminated.  A client's state might
+include information about the file currently being edited, the current
+position of the insertion point within the file, or the start of an 
+uncommitted transaction.
+The means by which clients are
+restarted is unspecified by this protocol.
+.LP
+For purposes of this protocol, a \fIclient\fP of the session manager is
+defined as a connection to the session manager.  A client is typically,
+though not necessarily, a process running an application program connected
+to an X Window System display.  However, a client may be connected to more
+than one X display or not be connected to any X displays at all.
+.LP
+This protocol is layered on top of the X Consortium's ICE protocol and relies on
+the ICE protocol to handle connection management and authentication.
+.LP
+.nH 1 "Overview of the Protocol"
+.LP
+Clients use XSMP to register themselves with the session manager (SM).  When
+a client starts up, it should connect to the SM.  The client should remain
+connected for as long as it runs.  A client may resign from the session by
+issuing the proper protocol messages before disconnecting.  Termination of
+the connection without notice will be taken as an indication that the client
+died unexpectedly.
+.LP
+Clients are expected to save their state in such a way as to allow multiple
+instantiations of themselves to be managed independently.  A unique value
+called a \fIclient-ID\fP is provided by the protocol for the purpose of
+disambiguating multiple instantiations of clients.  Clients may use this ID,
+for example, as part of a filename in which to store the state for a
+particular instantiation.  The client-ID should be saved as part of the
+command used to restart this client (the \fIRestartCommand\fP\^) so that the
+client will retain the same ID after it is restarted.  Certain small pieces
+of state might also be stored in the RestartCommand.   For example, an X11 client
+might place a `\-twoWindow' option in its RestartCommand to indicate that it
+should start up in two window mode when it is restarted.
+.LP
+The client finds the network address of the SM in a system-dependent way.
+On POSIX systems an environment variable called SESSION_MANAGER will contain
+a list of network IDs.  Each id will contain the transport name followed by a 
+slash and the (transport-specific)
+address.  A TCP/IP address would look like this:
+.ID
+	\fCtcp/\fP\fIhostname\fP\^\fC:\fP\^\fIportnumber\fP
+.DE
+where the hostname is a fully qualified domain name.
+A Unix Domain address looks like this:
+.ID
+	\fClocal/\fP\fIhostname\fP\^\fC:\fP\^\fIpath\fP
+.DE
+A DECnet address would look like this:
+.ID
+	\fCdecnet/\fP\fInodename\fP\^\fC::\fP\^\fIobjname\fP
+.DE
+If multiple network IDs are specified, they should be separated by commas.
+.NT Rationale
+There was much discussion over whether the XSMP protocol should use X as
+the transport protocol or whether it should use its own independent
+transport.  It was decided that it would use an independent protocol for
+several reasons.  First, the Session Manager should be able to 
+manage programs that
+do not maintain an X connection.  Second, the X protocol is not appropriate to
+use as a general-purpose transport protocol.  Third, a session might
+span multiple displays.
+.LP
+The protocol is connection based, because there is no other way for the SM
+to determine reliably when clients terminate.
+.LP
+It should be noted that this protocol introduces another single point of 
+failure into the system.  Although it is possible for clients to continue 
+running after the SM has exited, this will probably not be the case in 
+normal practice.  Normally the program that starts the SM will consider the
+session to be terminated when the SM exits (either normally or abnormally).
+.LP
+To get around this would require some sort of 
+rendezvous server that would also introduce a single point of failure.  In the
+absence of a generally available rendezvous server, XSMP is kept simple in
+the hopes of making simple reliable SMs.
+.NE
+.LP
+Some clients may wish to manage the programs they start.  For example, a
+mail program could start a text editor for editing the text of a mail
+message.  A client that does this is a session manager itself;
+it should supply the clients it starts with the appropriate connection
+information (i.e., the SESSION_MANAGER environment variable) that specifies
+a connection to itself instead of to the top level session manager.
+.LP
+Each client has associated with it a list of properties.
+A property set by one client is not visible to any other client.
+These properties are used for the client to inform the SM of the client's
+current state.
+When a client initially connects to the SM, there are no properties set.
+.nH 1 "Data Types"
+.LP
+XSMP messages contain several types of data.  Both the SM and the client
+always send messages in their native byte order.  Thus, both sides may need
+to byte-swap the messages received.  The need to do byte-swapping is
+determined at run-time by the ICE protocol. 
+.LP
+If an invalid value is specified for a field of any of the enumerated types, a
+.PN BadValue
+error message must be sent by the receiver of the message to the sender of the
+message.
+.br
+.ne 6
+.TS H
+l lw(4.5i).
+_
+.sp 6p
+.B
+Type Name	Description
+.R
+.sp 6p
+_
+.sp 6p
+.TH
+BOOL	T{
+.PN False
+or
+.PN True
+T}
+INTERACT_STYLE	T{
+.PN None ,
+.PN Errors ,
+or
+.PN Any
+T}
+DIALOG_TYPE	T{
+.PN Error
+or
+.PN Normal
+T}
+SAVE_TYPE	T{
+.PN Global ,
+.PN Local ,
+or
+.PN Both
+T}
+CARD8	a one-byte unsigned integer
+CARD16	a two-byte unsigned integer
+CARD32	a four-byte unsigned integer
+ARRAY8	a sequence of CARD8s
+LISTofARRAY8	a sequence of ARRAY8s
+PROPERTY	a property name (an ARRAY8), a type name, and a value of that type
+LISTofPROPERTY	T{
+a counted collection of \%PROPERTYs.
+T}		
+.sp 6p
+_
+.TE
+.nH 1 "Protocol Setup and Message Format"
+.LP
+To start the XSMP protocol, the client sends the server an ICE
+.PN ProtocolSetup
+message.
+All XSMP messages are in the standard ICE message format.  The message's major
+opcode is assigned to XSMP by ICE at run-time.  The different parties
+(client and SM) may be assigned different major opcodes for XSMP.  Once
+assigned, all XSMP messages issued by this party will use the same major
+opcode.  The message's minor opcode specifies which protocol message this
+message contains. 
+.nH 1 "Client Identification String"
+.LP
+A client ID is a string of XPCS characters encoded in ISO Latin 1 (ISO
+8859-1).  No null characters are allowed in this string.  The client ID
+string is used in the
+.PN Register\%Client
+and
+.PN Register\%ClientReply
+messages.
+.LP
+Client IDs consist of the pieces described below.  The ID is
+formed by concatenating the pieces in sequence, without
+separator characters.  All pieces are padded on the left 
+with '0' characters
+so as to fill the specified length.
+Decimal numbers are
+encoded using the characters `0' through `9', and
+hexadecimal numbers using the characters `0' through `9'
+and `A' through `F'.
+.IP \(bu 4
+Version.  This is currently the character `1'.
+.IP \(bu 4
+Address type and address.  The address type will be one of
+.DS
+.ta 0.5i
+`1'	a 4-byte IPv4 address encoded as 8 hexadecimal digits
+`2'	a 6-byte DECNET address encoded as 12 hexadecimal digits
+`6'	a 16-byte IPv6 address encoded as 32 hexadecimal digits
+.DE
+.IP
+The address is the one of the network addresses of the machine where the
+session manager (not the client) is running.  For example, the IP address
+198.112.45.11 would be encoded as the string \*QC6702D0B\*U.
+.IP \(bu 4
+Time stamp.  A 13-digit decimal number specifying the number of
+milliseconds since 00:00:00 UTC, January 1, 1970.
+.IP \(bu 4
+Process-ID type and process-ID.  The process-ID type will be one of
+.DS
+.ta 0.5i
+`1'	a POSIX process-ID encoded as a 10-digit decimal number.
+.DE
+.IP
+The process-ID is the process-ID of the session manager, not of a client.
+.IP \(bu 4
+Sequence number.  This is a four-digit decimal number.  It is incremented
+every time the session manager creates an ID.  After reaching \*Q9999\*U it
+wraps to \*Q0000\*U.
+.NT "Rationale"
+Once a client ID has been assigned to the client, the client keeps
+this ID indefinitely.  If the client is terminated and restarted, it
+will be reassigned the same ID.  It is desirable to be able to pass
+client IDs around from machine to machine, from user to user, and
+from session manager to session manager, while retaining the
+identity of the client.  This, combined with the indefinite
+persistence of client IDs, means that client IDs need to be globally
+unique.  The construction specified above will ensure that any
+client ID created by any user, session manager, and machine will be
+different from any other.
+.NE
+.nH 1 "Protocol"
+.LP
+The protocol consists of a sequence of messages as described below.  Each
+message type is specified by an ICE minor opcode.  A given message type is
+sent either from a client to the session manager or from the session manager
+to a client; the appropriate direction is listed with each message's
+description.  For each message type, the set of 
+valid responses and possible error
+messages are listed.  The ICE severity is given in parentheses following
+each error class.
+.LP
+.sM
+.PN RegisterClient
+[Client \(-> SM]
+.RS
+.LP
+\fIprevious-ID\fP\^: ARRAY8
+.LP
+Valid Responses: 
+.PN RegisterClientReply
+.LP
+Possible Errors:
+.PN BadValue
+.Pn ( CanContinue )
+.RE
+.eM
+.LP
+The client must send this message to the SM to register the client's existence.
+If a client is being restarted from a previous
+session, the previous-ID field must contain the client ID from the
+previous session.
+For new clients, previous-ID should be of zero length.
+.LP
+If previous-ID is not valid, the SM will send a
+.PN BadValue
+error message to the client.
+At this point the SM reverts to the register state and waits for another
+.PN RegisterClient .
+The client should then send a
+.PN RegisterClient
+with a null previous-ID field.
+.LP
+.sM
+.PN RegisterClientReply
+[Client \(<- SM]
+.RS
+.LP
+\fIclient-ID\fP\^: ARRAY8
+.RE
+.eM
+.LP
+The client-ID specifies a unique identification for this client.
+If the client had specified an ID in the previous-ID field of the
+.PN RegisterClient
+message, client-ID will be identical to the previously specified ID.  If
+previous-ID was null, client-ID will be a unique ID freshly generated by the
+SM.  The client-ID format is specified in section 6.
+.LP
+If the client didn't supply a previous-ID field to the
+.PN Register\%Client
+message, the SM must send a
+.PN SaveYourself
+message with type = Local, shutdown = False, interact-style = None,
+and fast = False immediately after the
+.PN RegisterClientReply .
+The client should respond to this like any other
+.PN Save\%Yourself
+message.
+.LP
+.sM
+.PN SaveYourself
+[Client \(<- SM]
+.RS
+.LP
+\fItype\fP\^: SAVE_TYPE
+.br
+\fIshutdown\fP\^: BOOL
+.br
+\fIinteract-style\fP\^: INTERACT_STYLE
+.br
+\fIfast\fP\^: BOOL
+.LP
+Valid Responses:
+.PN SetProperties ,
+.PN DeleteProperties ,
+.PN GetProperties ,
+.PN SaveYourselfDone ,
+.PN SaveYourselfPhase2Request ,
+.PN InteractRequest
+.RE
+.eM
+.LP
+The SM sends this message to a client to ask it to save
+its state.  The client writes a state file, if necessary,
+and, if necessary, uses 
+.PN SetProperties
+to inform the SM of
+how to restart it and how to discard the saved state.  During
+this process it can, if allowed by interact-style, request
+permission to interact with the user by sending an
+.PN InteractRequest
+message.
+After the state has been saved, or
+if it cannot be successfully saved, and the properties
+are appropriately set, the client sends a 
+.PN SaveYourselfDone
+message. 
+If the client wants to save additional information after all the
+other clients have finished changing their own state, the client
+should send
+.PN SaveYourselfPhase2Request
+instead of 
+.PN SaveYourselfDone .
+The client must then
+freeze interaction with the user and wait until it
+receives a 
+.PN SaveComplete ,
+.PN Die ,
+or a 
+.PN ShutdownCancelled
+message.
+.LP
+If interact-style is
+.PN None ,
+the client must not interact with the
+user while saving state.  If the interact-style is 
+.PN Errors ,
+the client
+may interact with the user only if an error condition arises.  If
+interact-style is 
+.PN Any ,
+then the client may interact with the user for
+any purpose.
+This is done by sending an
+.PN Interact\%Request
+message.  The SM will send an
+.PN Interact
+message to
+each client that sent an
+.PN Interact\%Request .  
+The client must postpone all
+interaction until it gets the
+.PN Interact
+message.  When the client is done
+interacting it should send the SM an
+.PN Interact\%Done
+message.  The 
+.PN Interact\%Request
+message can be sent any time after a
+.PN Save\%Yourself
+and before a 
+.PN Save\%Yourself\%Done .
+.LP
+Unusual circumstances may dictate multiple interactions.
+The client may initiate as many
+.PN Interact\%Request
+\-
+.PN Interact
+\-
+.PN InteractDone
+sequences as it needs before it sends
+.PN SaveYourselfDone .
+.LP
+When a client receives
+.PN Save\%Yourself
+and has not yet responded
+.PN Save\%Yourself\%Done
+to a previous
+.PN Save\%Yourself ,
+it must send a
+.PN Save\%Yourself\%Done
+and may then begin responding as appropriate
+to the newly received 
+.PN Save\%Yourself .
+.LP
+The type field specifies the type of information that should be saved:
+.PN Global ,
+.PN Local ,
+or
+.PN Both .
+The 
+.PN Local
+type indicates that the application must update the
+properties to reflect its current state, send a
+.PN Save\%Yourself\%Done
+and continue.  Specifically it should save enough information to restore
+the state as seen by the user of this client.  It should not affect the
+state as seen by other users.
+The
+.PN Global
+type indicates that the user wants the client to 
+commit all of its data to permanent, globally-accessible
+storage.
+.PN Both
+indicates that the client should do both of these.  If
+.PN Both
+is specified, the client should first commit the data to permanent storage
+before updating its SM properties.
+.NT Examples
+If a word processor was sent a 
+.PN SaveYourself
+with a type of 
+.PN Local ,
+it could create a temporary file that included the
+current contents of the file, the location of the cursor, and
+other aspects of the current editing session.
+It would then update its
+.PN Restart\%Command
+property with enough information to find the temporary file, 
+and its 
+.PN Discard\%Command 
+with enough information to remove it.
+.LP
+If a word processor was sent a 
+.PN SaveYourself
+with a type of
+.PN Global ,
+it would simply save the currently edited file.
+.LP
+If a word processor was sent a 
+.PN SaveYourself
+with a type of
+.PN Both ,
+it would first save the currently edited file.  It would then create a
+temporary file with information such as the current position of the cursor
+and what file is being edited.
+It would then update its
+.PN Restart\%Command
+property with enough information to find the temporary file, 
+and its 
+.PN Discard\%Command 
+with enough information to remove it.
+.LP
+Once the SM has send 
+.PN SaveYourself
+to a client, it can't send another 
+.PN SaveYourself 
+to that client until the client either
+responds with a 
+.PN SaveYourselfDone
+or the SM sends a 
+.PN ShutdownCancelled .
+.NE
+.NT "Advice to Implementors"
+If the client stores local any state in a file or similar
+\*Qexternal\*U storage, it must create a distinct
+copy in response to each 
+.PN SaveYourself 
+message.
+It \fImust not\fP simply refer to a previous copy, because
+the SM may discard that previous saved state using a 
+.PN DiscardCommand
+without knowing that it is needed for the new checkpoint.
+.NE
+.LP
+The shutdown field specifies whether the system is being shut down.
+.NT Rationale
+The interaction
+may be different depending on whether or not shutdown is set.
+.NE
+The client must save and then must prevent interaction
+until it receives a
+.PN SaveComplete ,
+.PN Die ,
+or a
+.PN Shutdown\%Cancelled ,
+because anything the user does after the save will be lost.
+.LP
+The fast field specifies whether or not the client should save its state as quickly as
+possible.  For example, if the SM knows that power is about to fail, it
+should set the fast field to
+.PN True .
+.LP
+.sM
+.PN SaveYourselfPhase2
+[Client \(<- SM]
+.RS
+.LP
+.LP
+Valid Responses:
+.PN SetProperties ,
+.PN DeleteProperties ,
+.PN GetProperties ,
+.PN SaveYourselfDone ,
+.PN InteractRequest
+.RE
+.eM
+.LP
+The SM sends this message to a client that has previously sent a
+.PN SaveYourselfPhase2Request
+message.
+This message informs the client that all other clients are in a fixed
+state and this client can save state that is associated with other clients.
+.NT "Rationale"
+Clients that manager other clients (window managers, workspace managers, etc)
+need to know when all clients they are managing are idle, so that the manager
+can save state related to each of the clients without being concerned with
+that state changing.
+.NE
+The client writes a state file, if necessary, and, if necessary, uses 
+.PN SetProperties
+to inform the SM of
+how to restart it and how to discard the saved state.  During
+this process it can request
+permission to interact with the user by sending an
+.PN InteractRequest
+message.
+This should only be done if an error occurs that requires user interaction
+to resolve.
+After the state has been saved, or
+if it cannot be successfully saved, and the properties
+are appropriately set, the client sends a 
+.PN SaveYourselfDone
+message. 
+.LP
+.LP
+.sM
+.PN SaveYourselfRequest
+[Client \(-> SM]
+.RS
+.LP
+\fItype\fP\^: SAVE_TYPE
+.br
+\fIshutdown\fP\^: BOOL
+.br
+\fIinteract-style\fP\^: INTERACT_STYLE
+.br
+\fIfast\fP\^: BOOL
+.br
+\fIglobal\fP\^: BOOL
+.LP
+Valid Responses:
+.PN SaveYourself
+.RE
+.eM
+.LP
+An application sends this to the SM to request a checkpoint.
+When the SM receives this request it may generate a 
+.PN SaveYourself
+message in response and it may leave the fields intact.
+.NT Example
+A vendor of a UPS (Uninterruptible Power Supply) might include an
+SM client that would monitor the status of the UPS and generate
+a fast shutdown if the power is about to be lost.
+.NE
+.LP
+If global is set to 
+.PN True ,
+then the resulting 
+.PN SaveYourself 
+should be
+sent to all applications.  If global is set to 
+.PN False ,
+then the resulting
+.PN SaveYourself 
+should be sent to the application that sent the 
+.PN Save\%Yourself\%Request .
+.LP
+.sM
+.PN InteractRequest
+[Client \(-> SM]
+.RS
+.LP
+\fIdialog-type\fP\^: DIALOG_TYPE
+.LP
+Valid Responses:
+.PN Interact ,
+.PN ShutdownCancelled
+.LP
+Possible Errors:
+.PN BadState
+.Pn ( CanContinue )
+.RE
+.eM
+.LP
+During a checkpoint or session-save operation,
+only one client at a time might be granted the privilege of interacting with
+the user.  The
+.PN InteractRequest
+message causes the SM to emit an
+.PN Interact
+message at some later time if the shutdown is not cancelled
+by another client first.
+.LP
+The dialog-type field specifies either
+.PN Errors ,
+indicating that the 
+client wants to start an error dialog or
+.PN Normal ,
+meaning the client 
+wishes to start a non-error dialog.
+.LP
+.sM
+.PN Interact
+[Client \(<- SM]
+.RS
+.LP
+Valid Responses:
+.PN InteractDone
+.LP
+.RE
+.eM
+.LP
+This message grants the client the privilege of interacting with the
+user.  When the client is done interacting with the user it must
+send an 
+.PN InteractDone
+message to the SM unless a shutdown cancel is received.
+.NT "Advice to Implementors"
+If a client receives a ShutdownCancelled after receiving an
+.PN Interact
+message, but before sending a 
+.PN InteractDone ,
+the client should abort the interaction and send a 
+.PN SaveYourselfDone .
+.NE
+.LP
+.sM
+.PN InteractDone
+[Client \(-> SM]
+.RS
+.LP
+\fIcancel-shutdown\fP\^: BOOL
+.br
+.LP
+Valid Responses:
+.PN ShutdownCancelled
+.LP
+.RE
+.eM
+.LP
+This message is used by a client to notify the SM that it is done interacting.
+.LP
+Setting the cancel-shutdown field to 
+.PN True
+indicates that
+the user has requested that the entire shutdown be cancelled.
+Cancel-shutdown may only be
+.PN True
+if the corresponding
+.PN SaveYourself
+message specified
+.PN True
+for the shutdown field and
+.PN Any
+or
+.PN Errors
+for the interact-style field.  Otherwise, cancel-shutdown must be
+.PN False .
+.LP
+.sM
+.PN SaveYourselfDone
+[Client \(-> SM]
+.RS
+.LP
+\fIsuccess\fP\^: BOOL
+.LP
+Valid Responses: 
+.PN SaveComplete ,
+.PN Die ,
+.PN ShutdownCancelled
+.LP
+.RE
+.eM
+.LP
+This message is sent by a client to indicate that all of the properties
+representing its state have been updated.
+After sending 
+.PN SaveYourselfDone 
+the client must
+wait for a 
+.PN SaveComplete ,
+.PN ShutdownCancelled ,
+or 
+.PN Die 
+message before changing its state.
+If the 
+.PN SaveYourself
+operation was successful, then the client
+should set the success field to
+.PN True ;
+otherwise the client should set
+it to
+.PN False .
+.NT Example
+If a client tries to save its state and runs out of disk space,
+it should return 
+.PN False
+in the success
+field of the 
+.PN SaveYourselfDone
+message.
+.NE
+.LP
+.sM
+.PN SaveYourselfPhase2Request
+[Client \(-> SM]
+.RS
+.LP
+Valid Responses: 
+.PN ShutdownCancelled ,
+.PN SaveYourselfPhase2
+.LP
+.RE
+.eM
+.LP
+This message is sent by a client to indicate that it needs to be informed
+when all the other clients are quiescent, so it can continue its state.
+.LP
+.sM
+.PN Die
+[Client \(<- SM]
+.RS
+.LP
+Valid Responses:
+.PN ConnectionClosed
+.RE
+.eM
+.LP
+When the SM wants a client to die it sends a
+.PN Die
+message.  Before the client dies it responds
+by sending a 
+.PN ConnectionClosed
+message and may then close
+its connection to the SM at any time.
+.LP
+.sM
+.PN SaveComplete
+[Client \(<- SM]
+.RS
+.LP
+Valid Responses:
+.RE
+.eM
+.LP
+When the SM is done with a checkpoint, it will send each of the clients a
+.PN SaveComplete
+message.  
+The client is then free to change its state.
+.LP
+.sM
+.PN ShutdownCancelled
+[Client \(<- SM]
+.RS
+.RE
+.eM
+.LP
+The shutdown currently in process has been aborted.  The client can now
+continue as if the shutdown had never happened.
+If the client has not sent
+.PN SaveYourselfDone
+yet, the client can either
+abort the save and send 
+.PN SaveYourselfDone
+with the success field
+set to
+.PN False ,
+or it can continue with the save and send a
+.PN SaveYourselfDone
+with the success field set to reflect the outcome
+of the save.
+.LP
+.sM
+.PN ConnectionClosed
+[Client \(-> SM]
+.RS
+.LP
+\fIreason\fP\^: LISTofARRAY8
+.RE
+.eM
+.LP
+Specifies that the client has decided to terminate.
+It should be immediately followed by closing the connection.
+.LP
+The reason field specifies why the client is resigning from the session.  It
+is encoded as an array of Compound Text strings.  If the resignation is
+expected by the user, there will typically be zero ARRAY8s here.  But if the
+client encountered an unexpected fatal error, the error message (which might
+otherwise be printed on stderr on a POSIX system) should be forwarded to the
+SM here, one ARRAY8 per line of the message.  It is the responsibility of
+the SM to display this reason to the user.
+.LP
+After sending this message, the client must not send any additional XSMP
+messages to the SM.
+.NT "Advice to Implementors"
+If additional messages are received, they should be discarded.
+.NE
+.NT Rationale
+The reason for sending the
+.PN ConnectionClosed
+message before
+actually closing the connections is that some transport protocols will
+not provide immediate notification of connection closure.
+.NE
+.LP
+.sM
+.PN SetProperties
+[Client \(-> SM]
+.RS
+.LP
+\fIproperties\fP: LISTofPROPERTY
+.RE
+.eM
+.LP
+Sets the specified properties to the specified values.
+Existing properties not specified in the 
+.PN Set\%Properties
+message are unaffected.
+Some properties have predefined semantics.
+See section 11, \*QPredefined Properties.\*U
+.LP
+The protocol specification recommends that property names used 
+for properties not defined by the standard should begin with an underscore.
+To prevent conflicts among organizations, 
+additional prefixes should be chosen 
+(for example,  _KPC_FAST_SAVE_OPTION).
+The organizational prefixes should be registered with the X Registry.
+The XSMP reserves all property names not beginning with an underscore for 
+future use.
+.LP
+.sM
+.PN DeleteProperties
+[Client \(-> SM]
+.RS
+.LP
+.br
+\fIproperty-names\fP: LISTofARRAY8
+.RE
+.eM
+.LP
+Removes the named properties.
+.LP
+.sM
+.PN GetProperties
+[Client \(-> SM]
+.RS
+.LP
+Valid Responses:
+.PN GetPropertiesReply
+.RE
+.eM
+.LP
+Requests that the SM respond with the
+values of all the properties for this client.
+.LP
+.sM
+.PN GetPropertiesReply
+[Client \(<- SM]
+.RS
+.LP
+\fIvalues\fP\^: LISTofPROPERTY
+.RE
+.eM
+.LP
+This message is sent in reply to a
+.PN GetProperties
+message and includes
+the values of all the properties.
+.nH 1 "Errors"
+.LP
+When the receiver of a message detects an error condition, 
+the receiver sends
+an ICE error message to the sender.
+There are only two types of errors that are used by the XSMP:
+.PN BadValue 
+and
+.PN BadState .
+These are both defined in the ICE protocol.
+.LP
+Any message received out-of-sequence
+will generate a
+.PN BadState
+error message.
+.nH 1 "State Diagrams"
+.LP
+These state diagrams are designed to cover all actions of both
+the client and the SM. 
+.nH 2 "Client State Diagram"
+.LP
+.nf
+.DS L 0
+\fIstart:\fP
+	ICE protocol setup complete \(-> \fCregister\fP
+.DE
+.sp
+.DS L 0
+\fIregister:\fP
+	send \fBRegisterClient\fP \(-> \fCcollect-id\fP
+.DE
+.sp
+.DS L 0
+\fIcollect-id:\fP
+	receive \fBRegisterClientReply\fP \(-> \fCidle\fP
+.DE
+.sp
+.DS L 0
+\fIshutdown-cancelled:\fP
+	send \fBSaveYourselfDone\fP \(-> \fCidle\fP
+.DE
+.sp
+.DS L 0
+\fIidle:\fP [Undoes any freeze of interaction with user.] 
+	receive \fBDie\fP \(-> \fCdie\fP
+	receive \fBSaveYourself\fP \(-> \fCfreeze-interaction\fP
+	send \fBGetProperties\fP \(-> \fCidle\fP
+	receive \fBGetPropertiesReply\fP \(-> \fCidle\fP
+	send \fBSetProperties\fP \(-> \fCidle\fP
+	send \fBDeleteProperties\fP \(-> \fCidle\fP
+	send \fBConnectionClosed\fP \(-> \fCconnection-closed\fP
+	send \fBSaveYourselfRequest\fP \(-> \fCidle\fP
+.DE
+.sp
+.DS L 0
+\fIdie:\fP
+	send \fBConnectionClosed\fP \(-> \fCconnection-closed\fP
+.DE
+.sp
+.DS L 0
+\fIfreeze-interaction:\fP
+	freeze interaction with user \(-> \fCsave-yourself\fP
+.DE
+.sp
+.DS L 0
+\fIsave-yourself:\fP
+	receive \fBShutdownCancelled\fP \(-> \fCshutdown-cancelled\fP
+	send \fBSetProperties\fP \(-> \fCsave-yourself\fP
+	send \fBDeleteProperties\fP \(-> \fCsave-yourself\fP
+	send \fBGetProperties\fP \(-> \fCsave-yourself\fP
+	receive \fBGetPropertiesReply\fP \(-> \fCsave-yourself\fP
+	send \fBInteractRequest\fP \(-> \fCinteract-request\fP
+	send \fBSaveYourselfPhase2Request\fP -> waiting-for-phase2
+	if shutdown mode:
+		send \fBSaveYourselfDone\fP \(-> \fCsave-yourself-done\fP
+	otherwise:
+		send \fBSaveYourselfDone\fP \(-> \fCidle\fP
+.DE
+.sp
+.DS L 0
+\fIwaiting-for-phase2:\fP
+	receive \fBShutdownCancelled\fP \(-> \fCshutdown-cancelled\fP
+	receive \fBSaveYourselfPhase2\fP \(-> \fCphase2\fP
+.DE
+.sp
+.DS L 0
+\fIphase2:\fP
+	receive \fBShutdownCancelled\fP \(-> \fCshutdown-cancelled\fP
+	send \fBSetProperties\fP \(-> \fCsave-yourself\fP
+	send \fBDeleteProperties\fP \(-> \fCsave-yourself\fP
+	send \fBGetProperties\fP \(-> \fCsave-yourself\fP
+	receive \fBGetPropertiesReply\fP \(-> \fCsave-yourself\fP
+	send \fBInteractRequest\fP \(-> \fCinteract-request\fP (errors only)
+	if shutdown mode:
+		send \fBSaveYourselfDone\fP \(-> \fCsave-yourself-done\fP
+	otherwise:
+		send \fBSaveYourselfDone\fP \(-> \fCidle\fP
+.DE
+.sp
+.DS L 0
+\fIinteract-request:\fP
+	receive \fBInteract\fP \(-> \fCinteract\fP
+	receive \fBShutdownCancelled\fP \(-> \fCshutdown-cancelled\fP
+.DE
+.sp
+.DS L 0
+\fIinteract:\fP
+	send \fBInteractDone\fP \(-> \fCsave-yourself\fP
+	receive \fBShutdownCancelled\fP \(-> \fCshutdown-cancelled\fP
+.DE
+.sp
+.DS L 0
+\fIsave-yourself-done:\fP (changing state is forbidden)
+	receive \fBSaveComplete\fP \(-> \fCidle\fP
+	receive \fBDie\fP \(-> \fCdie\fP
+	receive \fBShutdownCancelled\fP \(-> \fCidle\fP
+.DE
+.sp
+.DS L 0
+\fIconnection-closed:\fP
+	client stops participating in session
+.DE
+.ne 1i
+.nH 2 "Session Manager State Diagram"
+.LP
+.nf
+.DS L 0
+\fIstart:\fP
+	receive \fBProtocolSetup\fP \(-> \fCprotocol-setup\fP
+.DE
+.sp
+.DS L 0
+\fIprotocol-setup:\fP
+	send \fBProtocolSetupReply\fP \(-> \fCregister\fP
+.DE
+.sp
+.DS L 0
+\fIregister:\fP
+	receive \fBRegisterClient\fP \(-> \fCacknowledge-register\fP
+.DE
+.sp
+.DS L 0
+\fIacknowledge-register:\fP
+	send \fBRegisterClientReply\fP \(-> \fCidle\fP
+.DE
+.sp
+.DS L 0
+\fIidle:\fP
+	receive \fBSetProperties\fP \(-> \fCidle\fP
+	receive \fBDeleteProperties\fP \(-> \fCidle\fP
+	receive \fBConnectionClosed\fP \(-> \fCstart\fP
+	receive \fBGetProperties\fP \(-> \fCget-properties\fP
+	receive \fBSaveYourselfRequest\fP \(-> \fCsave-yourself\fP
+	send \fBSaveYourself\fP \(-> \fCsaving-yourself\fP
+.DE
+.sp
+.DS L 0
+\fIsave-yourself:\fP
+	send \fBSaveYourself\fP \(-> \fCsaving-yourself\fP
+.DE
+.sp
+.DS L 0
+\fIget-properties:\fP
+	send \fBGetPropertiesReply\fP \(-> \fCidle\fP
+.DE
+.sp
+.DS L 0
+\fIsaving-get-properties:\fP
+	send \fBGetPropertiesReply\fP \(-> \fCsaving-yourself\fP
+.DE
+.sp
+.DS L 0
+\fIsaving-yourself:\fP
+	receive \fBInteractRequest\fP \(-> \fCsaving-yourself\fP
+	send \fBInteract\fP \(-> \fCsaving-yourself\fP
+	send \fBShutdownCancelled\fP -> \fCidle\fP
+	receive \fBInteractDone\fP \(-> \fCsaving-yourself\fP
+	receive \fBSetProperties\fP \(-> \fCsaving-yourself\fP
+ 	receive \fBDeleteProperties\fP \(-> \fCsaving-yourself\fP
+	receive \fBGetProperties\fP \(-> \fCsaving-get-properties\fP
+	receive \fBSaveYourselfPhase2Request\fP \(-> \fCstart-phase2\fP
+	receive \fBSaveYourselfDone\fP \(-> \fCsave-yourself-done\fP
+.DE
+.sp
+.DS L 0
+\fIstart-phase2:\fP	
+	If all clients have sent either \fBSaveYourselfPhase2Request\fP or \fBSaveYourselfDone\fP:
+		send \fBSaveYourselfPhase2\fP \(-> \fCphase2\fP
+	else
+		\(-> \fCsaving-yourself\fP
+.DE
+.sp
+.DS L 0
+\fIphase2:\fP
+	receive \fBInteractRequest\fP \(-> \fCsaving-yourself\fP
+	send \fBInteract\fP \(-> \fCsaving-yourself\fP
+	send \fBShutdownCancelled\fP -> \fCidle\fP
+	receive \fBInteractDone\fP \(-> \fCsaving-yourself\fP
+	receive \fBSetProperties\fP \(-> \fCsaving-yourself\fP
+ 	receive \fBDeleteProperties\fP \(-> \fCsaving-yourself\fP
+	receive \fBGetProperties\fP \(-> \fCsaving-get-properties\fP
+	receive \fBSaveYourselfDone\fP \(-> \fCsave-yourself-done\fP
+.DE
+.sp
+.DS L 0
+\fIsave-yourself-done:\fP
+	If all clients are saved:
+		If shutting down:
+			send \fBDie\fP \(-> \fCdie\fP
+		otherwise
+			send \fBSaveComplete\fP \(-> \fCidle\fP
+.sp
+	If some clients are not saved:
+	\(-> \fCsaving-yourself\fP
+.DE
+.sp
+.DS L 0
+\fIdie:\fP
+	SM stops accepting connections
+.DE
+.nH 1 "Protocol Encoding"
+.nH 2 "Types"
+.LP
+.nf
+.ta .2i .5i 2.0i
+BOOL
+	0	False
+	1	True
+.sp
+INTERACT_STYLE
+	0	None
+	1	Errors
+	2	Any
+.sp
+DIALOG_TYPE
+	0	Error
+	1	Normal
+.sp
+SAVE_TYPE
+	0	Global
+	1 	Local
+	2 	Both
+.sp
+.ne .75i
+ARRAY8
+	4	CARD32	length
+	n	LISTofCARD8	the array
+	p		p = pad (4 + n, 8)
+.sp
+LISTofARRAY8
+	4	CARD32	count
+	4		unused
+	a	ARRAY8	first array
+	b	ARRAY8	second array
+	\&.
+	\&.
+	\&.
+	q	ARRAY8	last array
+.sp
+PROPERTY
+	a	ARRAY8	name
+	b	ARRAY8	type (XPCS encoded in Latin-1, case sensitive)
+	c	LISTofARRAY8	values
+.sp
+LISTofPROPERTY
+	4       CARD32	count
+	4       	unused
+	a       PROPERTY	first property
+	b       PROPERTY	second property
+	\&.
+	\&.
+	\&.
+	q	PROPERTY	last property
+.nH 2 "Messages"
+.LP
+XSMP is a sub-protocol of ICE.  The major opcode is assigned at run-time
+by ICE and is represented here by `?'.
+.LP
+To start the XSMP protocol, the client sends the server an ICE
+.PN ProtocolSetup
+message.  
+The protocol-name field should be specified as \*QXSMP\*U, the major
+version of the protocol is 1, the minor version is 0.
+These values may change if the protocol is revised.  The minor version
+number will be incremented if the change is compatible, otherwise the major
+version number will be incremented.
+.LP
+In 
+.PN ProtocolReply
+message sent by the session manager,
+the XSMP protocol defines the vendor parameter as product identification
+of the session manager, and defines the release parameter as
+the software release identification of the session manager. 
+The session manager should supply this information in the
+ICE 
+.PN ProtocolReply
+message.
+.LP
+.nf
+.ta .2i .5i 2.0i 
+.ne 3
+.PN RegisterClient
+	1	?	XSMP
+	1	1	opcode
+	2		unused
+	4	a/8	length of remaining data in 8-byte units
+	a	ARRAY8	previous-ID
+.ne 6
+.sp
+.PN RegisterClientReply
+	1	?	XSMP
+	1	2	opcode
+	2		unused
+	4	a/8	length of remaining data in 8-byte units
+	a	ARRAY8	client-ID
+.ne 4
+.sp
+.PN SaveYourself
+	1	?	XSMP
+	1	3	opcode
+	2		unused
+	4	1	length of remaining data in 8-byte units
+	1	SAVE_TYPE	type
+	1	BOOL	shutdown
+	1	INTERACT_STYLE	interact-style
+	1	BOOL	fast
+	4		unused
+.ne 4
+.sp
+.PN SaveYourselfRequest
+	1	?	XSMP
+	1	4	opcode
+	2		unused
+	4	1	length of remaining data in 8-byte units
+	1	SAVE_TYPE	type
+	1	BOOL	shutdown
+	1	INTERACT_STYLE	interact-style
+	1	BOOL	fast
+	1	BOOL	global
+	3		unused
+.ne 4
+.sp
+.PN InteractRequest
+	1	?	XSMP
+	1	5	opcode
+	1	DIALOG_TYPE	dialog type
+	1		unused
+	4	0	length of remaining data in 8-byte units
+.ne 4
+.sp
+.PN Interact
+	1	?	XSMP
+	1	6	opcode
+	2		unused
+	4	0	length of remaining data in 8-byte units
+.ne 4
+.sp
+.PN InteractDone
+	1	?	XSMP
+	1	7	opcode
+	1	BOOL	cancel-shutdown
+	1		unused
+	4	0	length of remaining data in 8-byte units
+.ne 6
+.sp
+.PN SaveYourselfDone
+	1	?	XSMP
+	1	8	opcode
+	1	BOOL	success
+	1		unused
+	4	0	length of remaining data in 8-byte units
+.ne 4
+.sp
+.PN Die
+	1	?	XSMP
+	1	9	opcode
+	2		unused
+	4	0	length of remaining data in 8-byte units
+.ne 4
+.sp
+.PN ShutdownCancelled
+	1	?	XSMP
+	1	10	opcode
+	2		unused
+	4	0	length of remaining data in 8-byte units
+.ne 4
+.sp
+.PN ConnectionClosed
+	1	?	XSMP
+	1	11	opcode
+	2		unused
+	4	a/8	length of remaining data in 8-byte units
+	a	LISTofARRAY8	reason
+.ne 4
+.sp
+.PN SetProperties
+	1	?	XSMP
+	1	12	opcode
+	2		unused
+	4	a/8	length of remaining data in 8-byte units
+	a	LISTofPROPERTY	properties
+.ne 4
+.sp
+.PN DeleteProperties
+	1	?	XSMP
+	1	13	opcode
+	2		unused
+	4	a/8	length of remaining data in 8-byte units
+	a	LISTofARRAY8	properties
+.ne 4
+.sp
+.PN GetProperties
+	1	?	XSMP
+	1	14	opcode
+	2		unused
+	4	0	length of remaining data in 8-byte units
+.ne 4
+.sp
+.PN GetPropertiesReply
+	1	?	XSMP
+	1	15	opcode
+	2		unused
+	4	a/8	length of remaining data in 8-byte units
+	a	LISTofPROPERTY	properties
+.ne 4
+.sp
+.PN SaveYourselfPhase2Request
+	1	?	XSMP
+	1	16	opcode
+	2		unused
+	4	0	length of remaining data in 8-byte units
+.ne 4
+.sp
+.PN SaveYourselfPhase2
+	1	?	XSMP
+	1	17	opcode
+	2		unused
+	4	0	length of remaining data in 8-byte units
+
+.sp
+.PN SaveComplete
+	1	?	XSMP
+	1	18	opcode
+	2		unused
+	4	0	length of remaining data in 8-byte units
+
+.nH 1 "Predefined Properties"
+.LP
+All property values are stored in a LISTofARRAY8.  If the type of the
+property is CARD8, the value is stored as a LISTofARRAY8 with one ARRAY8
+that is one byte long.  That single byte contains the CARD8.  If the type of
+the property is ARRAY8, the value is stored in the first element of a single
+element LISTofARRAY8.
+.LP
+The required properties must be set each time a client
+connects with the SM.  The properties must be set after
+the client sends
+.PN RegisterClient
+and before the client sends
+.PN SaveYourselfDone .
+Otherwise, the behavior of
+the session manager is not defined.
+.LP
+Clients may set, get, and delete nonstandard properties.
+The lifetime of stored properties does not extend into 
+subsequent sessions.
+.br
+.ne 6
+.TS H
+l l l c .
+_
+.sp 6p
+.B
+Name	Type	Posix Type	Required?
+.R
+.sp 6p
+_
+.sp 6p
+.TH
+CloneCommand	OS-specific	LISTofARRAY8	Yes
+CurrentDirectory	OS-specific	ARRAY8	No
+DiscardCommand	OS-specific	LISTofARRAY8	No*
+Environment	OS-specific	LISTofARRAY8	No
+ProcessID	OS-specific	ARRAY8	No
+Program	OS-specific	ARRAY8	Yes
+RestartCommand	OS-specific	LISTofARRAY8	Yes
+ResignCommand	OS-specific	LISTofARRAY8	No
+RestartStyleHint	CARD8	CARD8	No
+ShutdownCommand	OS-specific	LISTofARRAY8	No
+UserID	ARRAY8	ARRAY8	Yes
+.sp 6p
+_
+.TE
+.LP
+* Required if any state is stored in an external repository (e.g., state file).
+.IP CloneCommand 3
+This is like the 
+.PN RestartCommand 
+except it restarts a copy of the
+application.  The only difference is that the application doesn't
+supply its client id at register time.  On POSIX systems the type
+should be a LISTofARRAY8.
+.IP CurrentDirectory 3
+On POSIX-based systems specifies the value of the current directory that
+needs to be set up prior to starting the program and should be of type
+ARRAY8.
+.IP DiscardCommand 3
+The discard command contains a command that when delivered to the host that 
+the client is running on (determined from the connection), will
+cause it to discard any information about the current state.  If this command
+is not specified, the SM will assume that all of the client's state is encoded
+in the 
+.PN Restart\%Command .
+On POSIX systems the type should be LISTofARRAY8.
+.IP Environment 3
+On POSIX based systems, this will be of type LISTofARRAY8 where
+the ARRAY8s alternate between environment variable name and environment
+variable value.  
+.IP ProcessID 3
+This specifies an OS-specific identifier for the process.  On POSIX
+systems this should of type ARRAY8 and contain the return value 
+of getpid() turned into a Latin-1 (decimal) string.
+.IP Program 3
+The name of the program that is running.  On POSIX systems this 
+should be the
+first parameter passed to execve and should be of type ARRAY8.
+.IP RestartCommand 3
+The restart command contains a command that when delivered to the
+host that the client is running on (determined from the connection),
+will cause the client to restart in
+its current state.  On POSIX-based systems this is of type LISTofARRAY8
+and each of the elements in the array represents an element in
+the argv array.
+This restart command should ensure that the client restarts with the specified
+client-ID.
+.IP ResignCommand 3
+A client that sets the
+.PN RestartStyleHint
+to
+.PN RestartAnyway
+uses this property to specify a command 
+that undoes the effect of the client and removes
+any saved state.
+.NT Example
+A user runs xmodmap.  xmodmap registers with the SM, sets 
+.PN Restart\%Style\%Hint
+to 
+.PN Restart\%Anyway ,
+and then terminates.  In order to allow the SM (at the
+user's request) to undo this, xmodmap would register a
+.PN Resign\%Command
+that undoes the effects of the xmodmap.
+.NE
+.IP RestartStyleHint 3
+.RS
+.LP
+If the RestartStyleHint property is present, it will contain the 
+style of restarting the client prefers.  If this flag isn't specified,
+.PN RestartIfRunning
+is assumed.
+The possible values are as follows:
+.br
+.ne 6
+.TS H
+l n.
+_
+.sp 6p
+.B
+Name	Value
+.R
+.sp 6p
+_
+.sp 6p
+.TH
+RestartIfRunning	0
+RestartAnyway	1
+RestartImmediately	2
+RestartNever	3
+.sp 6p
+_
+.TE
+.LP
+The
+.PN RestartIfRunning
+style is used in the usual case.  The client should
+be restarted in the next session if it is connected to the 
+session manager at the end of the current session.
+.LP
+The
+.PN RestartAnyway
+style is used to tell the SM that the application
+should be restarted in the next session even if it exits before the 
+current session is terminated.
+It should be noted that this is only a hint and the SM
+will follow the policies specified by its users in determining what applications
+to restart.
+.LP
+.NT Rationale
+This can be specified by a client which supports (as MS-Windows clients
+do) a means for the user to indicate while exiting that
+restarting is desired.  It can also be used for clients that
+spawn other clients and then go away, but which want to be
+restarted.
+.NE
+.LP
+A client that uses
+.PN RestartAnyway
+should also set the
+.PN ResignCommand
+and
+.PN ShutdownCommand
+properties to commands that undo the state of the client
+after it exits.
+.LP
+The
+.PN RestartImmediately
+style is like
+.PN RestartAnyway ,
+but in addition, the
+client is meant to run continuously.  If the client exits, the
+SM should try to restart it in the current session.
+.NT "Advice to Implementors"
+It would be wise to sanity-check the frequency which which
+.PN RestartImmediately
+clients are restarted, to avoid a sick
+client being restarted continuously.
+.NE
+The
+.PN RestartNever
+style specifies that the client 
+does not wish to be restarted in the next session.
+.NT "Advice To Implementors"
+This should be used rarely, if at all.  It will cause the client
+to be silently left out of sessions when they are restarted and
+will probably be confusing to users.
+.NE
+.RE
+.IP ShutdownCommand
+This command is executed at shutdown time to clean up after a client that
+is no longer running but retained its state by setting
+.PN RestartStyleHint
+to 
+.PN RestartAnyway .
+The command must not remove any saved state as the client is still part of
+the session.
+.NT Example
+A client is run at start up time that turns on a camera.  This client then
+exits.  At session shutdown, the user wants the camera turned off.  This client
+would set the 
+.PN Restart\%Style\%Hint
+to 
+.PN Restart\%Anyway
+and would register a 
+.PN Shutdown\%Command
+that would turn off the camera.
+.NE
+.IP UserID 3
+Specifies the user's ID.  On POSIX-based systems this
+will contain the the user's name (the pw_name field of struct passwd).
+.\" Finish up.
+.YZ 3