X Session Management Protocol X.Org Standard X Version 11, Release 6.7

Mike Wexler
Kubota Pacific Computer, Inc.

ABSTRACT

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.

X Window System is a trademark of The Open Group.

Copyright © 1992, 1993, 1994, 2002 The Open Group.

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:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

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.

ii

1. AcknowledgementsFirst I would like to thank the entire ICCCM and Intrinsicsworking groups for the comments and suggestions. I wouldlike to make special thanks to the following people (inalphabetical order), Jordan Brown, Ellis Cohen, DonnaConverse, Vania Joloboff, Stuart Marks, Ralph Mor and BobScheifler.2. Definitions and GoalsThe purpose of the X Session Management Protocol (XSMP) isto provide a uniform mechanism for users to save and restoretheir sessions. A session is a group of clients, each ofwhich has a particular state. The session is controlled bya network service called the session manager. The sessionmanager issues commands to its clients on behalf of theuser. These commands may cause clients to save their stateor to terminate. It is expected that the client will saveits state in such a way that the client can be restarted ata later time and resume its operation as if it had neverbeen terminated. A client’s state might include informationabout the file currently being edited, the current positionof the insertion point within the file, or the start of anuncommitted transaction. The means by which clients arerestarted is unspecified by this protocol.For purposes of this protocol, a client of the sessionmanager is defined as a connection to the session manager.A client is typically, though not necessarily, a processrunning an application program connected to an X WindowSystem display. However, a client may be connected to morethan one X display or not be connected to any X displays atall.This protocol is layered on top of the X Consortium’s ICEprotocol and relies on the ICE protocol to handle connectionmanagement and authentication.3. Overview of the ProtocolClients use XSMP to register themselves with the sessionmanager (SM). When a client starts up, it should connect tothe SM. The client should remain connected for as long asit runs. A client may resign from the session by issuingthe proper protocol messages before disconnecting.Termination of the connection without notice will be takenas an indication that the client died unexpectedly.Clients are expected to save their state in such a way as toallow multiple instantiations of themselves to be managedindependently. A unique value called a client-ID isprovided by the protocol for the purpose of disambiguatingmultiple instantiations of clients. Clients may use thisID, for example, as part of a filename in which to store thestate for a particular instantiation. The client-ID shouldbe saved as part of the command used to restart this client(the RestartCommand) so that the client will retain the sameID after it is restarted. Certain small pieces of statemight also be stored in the RestartCommand. For example,an X11 client might place a ‘−twoWindow’ option in itsRestartCommand to indicate that it should start up in twowindow mode when it is restarted.The client finds the network address of the SM in asystem-dependent way. On POSIX systems an environmentvariable called SESSION_MANAGER will contain a list ofnetwork IDs. Each id will contain the transport namefollowed by a slash and the (transport-specific) address. ATCP/IP address would look like this:tcp/hostname:portnumberwhere the hostname is a fully qualified domain name. A UnixDomain address looks like this:local/hostname:pathA DECnet address would look like this:decnet/nodename::objnameIf multiple network IDs are specified, they should beseparated by commas. RationaleThere was much discussion over whether the XSMPprotocol should use X as the transport protocol orwhether it should use its own independenttransport. It was decided that it would use anindependent protocol for several reasons. First,the Session Manager should be able to manageprograms that do not maintain an X connection.Second, the X protocol is not appropriate to useas a general-purpose transport protocol. Third, asession might span multiple displays.The protocol is connection based, because there isno other way for the SM to determine reliably whenclients terminate.It should be noted that this protocol introducesanother single point of failure into the system.Although it is possible for clients to continuerunning after the SM has exited, this willprobably not be the case in normal practice.Normally the program that starts the SM willconsider the session to be terminated when the SMexits (either normally or abnormally).To get around this would require some sort ofrendezvous server that would also introduce asingle point of failure. In the absence of agenerally available rendezvous server, XSMP iskept simple in the hopes of making simple reliableSMs.Some clients may wish to manage the programs they start.For example, a mail program could start a text editor forediting the text of a mail message. A client that does thisis a session manager itself; it should supply the clients itstarts with the appropriate connection information (i.e.,the SESSION_MANAGER environment variable) that specifies aconnection to itself instead of to the top level sessionmanager.Each client has associated with it a list of properties. Aproperty set by one client is not visible to any otherclient. These properties are used for the client to informthe SM of the client’s current state. When a clientinitially connects to the SM, there are no properties set.4. Data TypesXSMP messages contain several types of data. Both the SMand the client always send messages in their native byteorder. Thus, both sides may need to byte-swap the messagesreceived. The need to do byte-swapping is determined atrun-time by the ICE protocol.If an invalid value is specified for a field of any of theenumerated types, a BadValue error message must be sent bythe receiver of the message to the sender of the message.5. Protocol Setup and Message FormatTo start the XSMP protocol, the client sends the server anICE ProtocolSetup message. All XSMP messages are in thestandard ICE message format. The message’s major opcode isassigned to XSMP by ICE at run-time. The different parties(client and SM) may be assigned different major opcodes forXSMP. Once assigned, all XSMP messages issued by this partywill use the same major opcode. The message’s minor opcodespecifies which protocol message this message contains.6. Client Identification StringA client ID is a string of XPCS characters encoded in ISOLatin 1 (ISO 8859-1). No null characters are allowed inthis string. The client ID string is used in the Register-Client and RegisterClientReply messages.Client IDs consist of the pieces described below. The ID isformed by concatenating the pieces in sequence, withoutseparator characters. All pieces are padded on the leftwith ’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’.• Version. This is currently the character ‘1’.• Address type and address. The address type will be oneof ‘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 digitsThe address is the one of the network addresses of themachine where the session manager (not the client) isrunning. For example, the IP address 198.112.45.11would be encoded as the string "C6702D0B".• Time stamp. A 13-digit decimal number specifying thenumber of milliseconds since 00:00:00 UTC, January 1,1970.• Process-ID type and process-ID. The process-ID typewill be one of‘1’ a POSIX process-ID encoded as a 10-digit decimal number.The process-ID is the process-ID of the session manager,not of a client.• Sequence number. This is a four-digit decimal number.It is incremented every time the session manager createsan ID. After reaching "9999" it wraps to "0000".RationaleOnce a client ID has been assigned to theclient, the client keeps this ID indefinitely.If the client is terminated and restarted, itwill be reassigned the same ID. It isdesirable to be able to pass client IDs aroundfrom 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 persistenceof client IDs, means that client IDs need tobe globally unique. The constructionspecified above will ensure that any client IDcreated by any user, session manager, andmachine will be different from any other.7. ProtocolThe protocol consists of a sequence of messages as describedbelow. Each message type is specified by an ICE minoropcode. A given message type is sent either from a clientto the session manager or from the session manager to aclient; the appropriate direction is listed with eachmessage’s description. For each message type, the set ofvalid responses and possible error messages are listed. TheICE severity is given in parentheses following each errorclass.__│ RegisterClient [Client → SM]previous-ID: ARRAY8Valid Responses: RegisterClientReplyPossible Errors: BadValue (CanContinue)│__ The client must send this message to the SM to register theclient’s existence. If a client is being restarted from aprevious session, the previous-ID field must contain theclient ID from the previous session. For new clients,previous-ID should be of zero length.If previous-ID is not valid, the SM will send a BadValueerror message to the client. At this point the SM revertsto the register state and waits for another RegisterClient.The client should then send a RegisterClient with a nullprevious-ID field.__│ RegisterClientReply [Client ← SM]client-ID: ARRAY8│__ The client-ID specifies a unique identification for thisclient. If the client had specified an ID in theprevious-ID field of the RegisterClient message, client-IDwill be identical to the previously specified ID. Ifprevious-ID was null, client-ID will be a unique ID freshlygenerated by the SM. The client-ID format is specified insection 6.If the client didn’t supply a previous-ID field to theRegisterClient message, the SM must send a SaveYourselfmessage with type = Local, shutdown = False, interact-style= None, and fast = False immediately after theRegisterClientReply. The client should respond to this likeany other SaveYourself message.__│ SaveYourself [Client ← SM]type: SAVE_TYPEshutdown: BOOLinteract-style: INTERACT_STYLEfast: BOOLValid Responses: SetProperties, DeleteProperties,GetProperties, SaveYourselfDone,SaveYourselfPhase2Request, InteractRequest│__ The SM sends this message to a client to ask it to save itsstate. The client writes a state file, if necessary, and,if necessary, uses SetProperties to inform the SM of how torestart it and how to discard the saved state. During thisprocess it can, if allowed by interact-style, requestpermission to interact with the user by sending anInteractRequest message. After the state has been saved, orif it cannot be successfully saved, and the properties areappropriately set, the client sends a SaveYourselfDonemessage. If the client wants to save additional informationafter all the other clients have finished changing their ownstate, the client should send SaveYourselfPhase2Requestinstead of SaveYourselfDone. The client must then freezeinteraction with the user and wait until it receives aSaveComplete, Die, or a ShutdownCancelled message.If interact-style is None, the client must not interact withthe user while saving state. If the interact-style isErrors, the client may interact with the user only if anerror condition arises. If interact-style is Any, then theclient may interact with the user for any purpose. This isdone by sending an InteractRequest message. The SM willsend an Interact message to each client that sent anInteractRequest. The client must postpone all interactionuntil it gets the Interact message. When the client is doneinteracting it should send the SM an InteractDone message.The InteractRequest message can be sent any time after aSaveYourself and before a SaveYourselfDone.Unusual circumstances may dictate multiple interactions.The client may initiate as many InteractRequest − Interact −InteractDone sequences as it needs before it sendsSaveYourselfDone.When a client receives SaveYourself and has not yetresponded SaveYourselfDone to a previous SaveYourself, itmust send a SaveYourselfDone and may then begin respondingas appropriate to the newly received SaveYourself.The type field specifies the type of information that shouldbe saved: Global, Local, or Both. The Local type indicatesthat the application must update the properties to reflectits current state, send a SaveYourselfDone and continue.Specifically it should save enough information to restorethe state as seen by the user of this client. It should notaffect the state as seen by other users. The Global typeindicates that the user wants the client to commit all ofits data to permanent, globally-accessible storage. Bothindicates that the client should do both of these. If Bothis specified, the client should first commit the data topermanent storage before updating its SM properties.ExamplesIf a word processor was sent a SaveYourself with atype of Local, it could create a temporary filethat included the current contents of the file,the location of the cursor, and other aspects ofthe current editing session. It would then updateits RestartCommand property with enoughinformation to find the temporary file, and itsDiscardCommand with enough information to removeit.If a word processor was sent a SaveYourself with atype of Global, it would simply save the currentlyedited file.If a word processor was sent a SaveYourself with atype of Both, it would first save the currentlyedited file. It would then create a temporaryfile with information such as the current positionof the cursor and what file is being edited. Itwould then update its RestartCommand property withenough information to find the temporary file, andits DiscardCommand with enough information toremove it.Once the SM has send SaveYourself to a client, itcan’t send another SaveYourself to that clientuntil the client either responds with aSaveYourselfDone or the SM sends aShutdownCancelled.Advice to ImplementorsIf the client stores local any state in a file orsimilar "external" storage, it must create adistinct copy in response to each SaveYourselfmessage. It must not simply refer to a previouscopy, because the SM may discard that previoussaved state using a DiscardCommand without knowingthat it is needed for the new checkpoint.The shutdown field specifies whether the system is beingshut down. RationaleThe interaction may be different depending onwhether or not shutdown is set.The client must save and then must prevent interaction untilit receives a SaveComplete, Die, or a ShutdownCancelled,because anything the user does after the save will be lost.The fast field specifies whether or not the client shouldsave its state as quickly as possible. For example, if theSM knows that power is about to fail, it should set the fastfield to True.__│ SaveYourselfPhase2 [Client ← SM]Valid Responses: SetProperties, DeleteProperties,GetProperties, SaveYourselfDone, InteractRequest│__ The SM sends this message to a client that has previouslysent a SaveYourselfPhase2Request message. This messageinforms the client that all other clients are in a fixedstate and this client can save state that is associated withother clients. RationaleClients that manager other clients (windowmanagers, workspace managers, etc) need to knowwhen all clients they are managing are idle, sothat the manager can save state related to each ofthe clients without being concerned with thatstate changing.The client writes a state file, if necessary, and, ifnecessary, uses SetProperties to inform the SM of how torestart it and how to discard the saved state. During thisprocess it can request permission to interact with the userby sending an InteractRequest message. This should only bedone if an error occurs that requires user interaction toresolve. After the state has been saved, or if it cannot besuccessfully saved, and the properties are appropriatelyset, the client sends a SaveYourselfDone message.__│ SaveYourselfRequest [Client → SM]type: SAVE_TYPEshutdown: BOOLinteract-style: INTERACT_STYLEfast: BOOLglobal: BOOLValid Responses: SaveYourself│__ An application sends this to the SM to request a checkpoint.When the SM receives this request it may generate aSaveYourself message in response and it may leave the fieldsintact. ExampleA vendor of a UPS (Uninterruptible Power Supply)might include an SM client that would monitor thestatus of the UPS and generate a fast shutdown ifthe power is about to be lost.If global is set to True, then the resulting SaveYourselfshould be sent to all applications. If global is set toFalse, then the resulting SaveYourself should be sent to theapplication that sent the SaveYourselfRequest.__│ InteractRequest [Client → SM]dialog-type: DIALOG_TYPEValid Responses: Interact, ShutdownCancelledPossible Errors: BadState (CanContinue)│__ During a checkpoint or session-save operation, only oneclient at a time might be granted the privilege ofinteracting with the user. The InteractRequest messagecauses the SM to emit an Interact message at some later timeif the shutdown is not cancelled by another client first.The dialog-type field specifies either Errors, indicatingthat the client wants to start an error dialog or Normal,meaning the client wishes to start a non-error dialog.__│ Interact [Client ← SM]Valid Responses: InteractDone│__ This message grants the client the privilege of interactingwith the user. When the client is done interacting with theuser it must send an InteractDone message to the SM unless ashutdown cancel is received.Advice to ImplementorsIf a client receives a ShutdownCancelled afterreceiving an Interact message, but before sendinga InteractDone, the client should abort theinteraction and send a SaveYourselfDone.__│ InteractDone [Client → SM]cancel-shutdown: BOOLValid Responses: ShutdownCancelled│__ This message is used by a client to notify the SM that it isdone interacting.Setting the cancel-shutdown field to True indicates that theuser has requested that the entire shutdown be cancelled.Cancel-shutdown may only be True if the correspondingSaveYourself message specified True for the shutdown fieldand Any or Errors for the interact-style field. Otherwise,cancel-shutdown must be False.__│ SaveYourselfDone [Client → SM]success: BOOLValid Responses: SaveComplete, Die, ShutdownCancelled│__ This message is sent by a client to indicate that all of theproperties representing its state have been updated. Aftersending SaveYourselfDone the client must wait for aSaveComplete, ShutdownCancelled, or Die message beforechanging its state. If the SaveYourself operation wassuccessful, then the client should set the success field toTrue; otherwise the client should set it to False.ExampleIf a client tries to save its state and runs outof disk space, it should return False in thesuccess field of the SaveYourselfDone message.__│ SaveYourselfPhase2Request [Client → SM]Valid Responses: ShutdownCancelled, SaveYourselfPhase2│__ This message is sent by a client to indicate that it needsto be informed when all the other clients are quiescent, soit can continue its state.__│ Die [Client ← SM]Valid Responses: ConnectionClosed│__ When the SM wants a client to die it sends a Die message.Before the client dies it responds by sending aConnectionClosed message and may then close its connectionto the SM at any time.__│ SaveComplete [Client ← SM]Valid Responses:│__ When the SM is done with a checkpoint, it will send each ofthe clients a SaveComplete message. The client is then freeto change its state.__│ ShutdownCancelled [Client ← SM]│__ The shutdown currently in process has been aborted. Theclient can now continue as if the shutdown had neverhappened. If the client has not sent SaveYourselfDone yet,the client can either abort the save and sendSaveYourselfDone with the success field set to False, or itcan continue with the save and send a SaveYourselfDone withthe success field set to reflect the outcome of the save.__│ ConnectionClosed [Client → SM]reason: LISTofARRAY8│__ Specifies that the client has decided to terminate. Itshould be immediately followed by closing the connection.The reason field specifies why the client is resigning fromthe session. It is encoded as an array of Compound Textstrings. If the resignation is expected by the user, therewill typically be zero ARRAY8s here. But if the clientencountered an unexpected fatal error, the error message(which might otherwise be printed on stderr on a POSIXsystem) should be forwarded to the SM here, one ARRAY8 perline of the message. It is the responsibility of the SM todisplay this reason to the user.After sending this message, the client must not send anyadditional XSMP messages to the SM.Advice to ImplementorsIf additional messages are received, they shouldbe discarded. RationaleThe reason for sending the ConnectionClosedmessage before actually closing the connections isthat some transport protocols will not provideimmediate notification of connection closure.__│ SetProperties [Client → SM]properties: LISTofPROPERTY│__ Sets the specified properties to the specified values.Existing properties not specified in the SetPropertiesmessage are unaffected. Some properties have predefinedsemantics. See section 11, "Predefined Properties."The protocol specification recommends that property namesused for properties not defined by the standard should beginwith an underscore. To prevent conflicts amongorganizations, additional prefixes should be chosen (forexample, _KPC_FAST_SAVE_OPTION). The organizationalprefixes should be registered with the X Registry. The XSMPreserves all property names not beginning with an underscorefor future use.__│ DeleteProperties [Client → SM]property-names: LISTofARRAY8│__ Removes the named properties.__│ GetProperties [Client → SM]Valid Responses: GetPropertiesReply│__ Requests that the SM respond with the values of all theproperties for this client.__│ GetPropertiesReply [Client ← SM]values: LISTofPROPERTY│__ This message is sent in reply to a GetProperties message andincludes the values of all the properties.8. ErrorsWhen 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 theXSMP: BadValue and BadState. These are both defined in theICE protocol.Any message received out-of-sequence will generate aBadState error message.9. State DiagramsThese state diagrams are designed to cover all actions ofboth the client and the SM.9.1. Client State Diagramstart:ICE protocol setup complete → registerregister:send RegisterClient → collect-idcollect-id:receive RegisterClientReply → idleshutdown-cancelled:send SaveYourselfDone → idleidle: [Undoes any freeze of interaction with user.]receive Die → diereceive SaveYourself → freeze-interactionsend GetProperties → idlereceive GetPropertiesReply → idlesend SetProperties → idlesend DeleteProperties → idlesend ConnectionClosed → connection-closedsend SaveYourselfRequest → idledie: send ConnectionClosed → connection-closedfreeze-interaction:freeze interaction with user → save-yourselfsave-yourself:receive ShutdownCancelled → shutdown-cancelledsend SetProperties → save-yourselfsend DeleteProperties → save-yourselfsend GetProperties → save-yourselfreceive GetPropertiesReply → save-yourselfsend InteractRequest → interact-requestsend SaveYourselfPhase2Request -> waiting-for-phase2if shutdown mode:send SaveYourselfDone → save-yourself-doneotherwise:send SaveYourselfDone → idlewaiting-for-phase2:receive ShutdownCancelled → shutdown-cancelledreceive SaveYourselfPhase2 → phase2phase2:receive ShutdownCancelled → shutdown-cancelledsend SetProperties → save-yourselfsend DeleteProperties → save-yourselfsend GetProperties → save-yourselfreceive GetPropertiesReply → save-yourselfsend InteractRequest → interact-request (errors only)if shutdown mode:send SaveYourselfDone → save-yourself-doneotherwise:send SaveYourselfDone → idleinteract-request:receive Interact → interactreceive ShutdownCancelled → shutdown-cancelledinteract:send InteractDone → save-yourselfreceive ShutdownCancelled → shutdown-cancelledsave-yourself-done: (changing state is forbidden)receive SaveComplete → idlereceive Die → diereceive ShutdownCancelled → idleconnection-closed:client stops participating in session9.2. Session Manager State Diagramstart:receive ProtocolSetup → protocol-setupprotocol-setup:send ProtocolSetupReply → registerregister:receive RegisterClient → acknowledge-registeracknowledge-register:send RegisterClientReply → idleidle:receive SetProperties → idlereceive DeleteProperties → idlereceive ConnectionClosed → startreceive GetProperties → get-propertiesreceive SaveYourselfRequest → save-yourselfsend SaveYourself → saving-yourselfsave-yourself:send SaveYourself → saving-yourselfget-properties:send GetPropertiesReply → idlesaving-get-properties:send GetPropertiesReply → saving-yourselfsaving-yourself:receive InteractRequest → saving-yourselfsend Interact → saving-yourselfsend ShutdownCancelled -> idlereceive InteractDone → saving-yourselfreceive SetProperties → saving-yourselfreceive DeleteProperties → saving-yourselfreceive GetProperties → saving-get-propertiesreceive SaveYourselfPhase2Request → start-phase2receive SaveYourselfDone → save-yourself-donestart-phase2:If all clients have sent either SaveYourselfPhase2Request or SaveYourselfDone:send SaveYourselfPhase2 → phase2else → saving-yourselfphase2:receive InteractRequest → saving-yourselfsend Interact → saving-yourselfsend ShutdownCancelled -> idlereceive InteractDone → saving-yourselfreceive SetProperties → saving-yourselfreceive DeleteProperties → saving-yourselfreceive GetProperties → saving-get-propertiesreceive SaveYourselfDone → save-yourself-donesave-yourself-done:If all clients are saved:If shutting down:send Die → dieotherwisesend SaveComplete → idleIf some clients are not saved:→ saving-yourselfdie: SM stops accepting connections10. Protocol Encoding10.1. TypesBOOL0 False1 TrueINTERACT_STYLE0 None1 Errors2 AnyDIALOG_TYPE0 Error1 NormalSAVE_TYPE0 Global1 Local2 BothARRAY84 CARD32 lengthn LISTofCARD8 the arrayp p = pad (4 + n, 8)LISTofARRAY84 CARD32 count4 unuseda ARRAY8 first arrayb ARRAY8 second array...q ARRAY8 last arrayPROPERTYa ARRAY8 nameb ARRAY8 type (XPCS encoded in Latin-1, case sensitive)c LISTofARRAY8 valuesLISTofPROPERTY4 CARD32 count4 unuseda PROPERTY first propertyb PROPERTY second property...q PROPERTY last property10.2. MessagesXSMP is a sub-protocol of ICE. The major opcode is assignedat run-time by ICE and is represented here by ‘?’.To start the XSMP protocol, the client sends the server anICE ProtocolSetup message. The protocol-name field shouldbe specified as "XSMP", the major version of the protocol is1, the minor version is 0. These values may change if theprotocol is revised. The minor version number will beincremented if the change is compatible, otherwise the majorversion number will be incremented.In ProtocolReply message sent by the session manager, theXSMP protocol defines the vendor parameter as productidentification of the session manager, and defines therelease parameter as the software release identification ofthe session manager. The session manager should supply thisinformation in the ICE ProtocolReply message.RegisterClient1 ? XSMP1 1 opcode2 unused4 a/8 length of remaining data in 8-byte unitsa ARRAY8 previous-IDRegisterClientReply1 ? XSMP1 2 opcode2 unused4 a/8 length of remaining data in 8-byte unitsa ARRAY8 client-IDSaveYourself1 ? XSMP1 3 opcode2 unused4 1 length of remaining data in 8-byte units1 SAVE_TYPE type1 BOOL shutdown1 INTERACT_STYLE interact-style1 BOOL fast4 unusedSaveYourselfRequest1 ? XSMP1 4 opcode2 unused4 1 length of remaining data in 8-byte units1 SAVE_TYPE type1 BOOL shutdown1 INTERACT_STYLE interact-style1 BOOL fast1 BOOL global3 unusedInteractRequest1 ? XSMP1 5 opcode1 DIALOG_TYPE dialog type1 unused4 0 length of remaining data in 8-byte unitsInteract1 ? XSMP1 6 opcode2 unused4 0 length of remaining data in 8-byte unitsInteractDone1 ? XSMP1 7 opcode1 BOOL cancel-shutdown1 unused4 0 length of remaining data in 8-byte unitsSaveYourselfDone1 ? XSMP1 8 opcode1 BOOL success1 unused4 0 length of remaining data in 8-byte unitsDie1 ? XSMP1 9 opcode2 unused4 0 length of remaining data in 8-byte unitsShutdownCancelled1 ? XSMP1 10 opcode2 unused4 0 length of remaining data in 8-byte unitsConnectionClosed1 ? XSMP1 11 opcode2 unused4 a/8 length of remaining data in 8-byte unitsa LISTofARRAY8 reasonSetProperties1 ? XSMP1 12 opcode2 unused4 a/8 length of remaining data in 8-byte unitsa LISTofPROPERTY propertiesDeleteProperties1 ? XSMP1 13 opcode2 unused4 a/8 length of remaining data in 8-byte unitsa LISTofARRAY8 propertiesGetProperties1 ? XSMP1 14 opcode2 unused4 0 length of remaining data in 8-byte unitsGetPropertiesReply1 ? XSMP1 15 opcode2 unused4 a/8 length of remaining data in 8-byte unitsa LISTofPROPERTY propertiesSaveYourselfPhase2Request1 ? XSMP1 16 opcode2 unused4 0 length of remaining data in 8-byte unitsSaveYourselfPhase21 ? XSMP1 17 opcode2 unused4 0 length of remaining data in 8-byte unitsSaveComplete1 ? XSMP1 18 opcode2 unused4 0 length of remaining data in 8-byte units11. Predefined PropertiesAll property values are stored in a LISTofARRAY8. If thetype of the property is CARD8, the value is stored as aLISTofARRAY8 with one ARRAY8 that is one byte long. Thatsingle byte contains the CARD8. If the type of the propertyis ARRAY8, the value is stored in the first element of asingle element LISTofARRAY8.The required properties must be set each time a clientconnects with the SM. The properties must be set after theclient sends RegisterClient and before the client sendsSaveYourselfDone. Otherwise, the behavior of the sessionmanager is not defined.Clients may set, get, and delete nonstandard properties.The lifetime of stored properties does not extend intosubsequent sessions.* Required if any state is stored in an external repository(e.g., state file).CloneCommandThis is like the RestartCommand except it restarts a copyof the application. The only difference is that theapplication doesn’t supply its client id at registertime. On POSIX systems the type should be aLISTofARRAY8.CurrentDirectoryOn POSIX-based systems specifies the value of the currentdirectory that needs to be set up prior to starting theprogram and should be of type ARRAY8.DiscardCommandThe discard command contains a command that whendelivered to the host that the client is running on(determined from the connection), will cause it todiscard any information about the current state. If thiscommand is not specified, the SM will assume that all ofthe client’s state is encoded in the RestartCommand. OnPOSIX systems the type should be LISTofARRAY8.EnvironmentOn POSIX based systems, this will be of type LISTofARRAY8where the ARRAY8s alternate between environment variablename and environment variable value.ProcessIDThis specifies an OS-specific identifier for the process.On POSIX systems this should of type ARRAY8 and containthe return value of getpid() turned into a Latin-1(decimal) string.ProgramThe name of the program that is running. On POSIXsystems this should be the first parameter passed toexecve and should be of type ARRAY8.RestartCommandThe restart command contains a command that whendelivered to the host that the client is running on(determined from the connection), will cause the clientto restart in its current state. On POSIX-based systemsthis is of type LISTofARRAY8 and each of the elements inthe array represents an element in the argv array. Thisrestart command should ensure that the client restartswith the specified client-ID.ResignCommandA client that sets the RestartStyleHint to RestartAnywayuses this property to specify a command that undoes theeffect of the client and removes any saved state.ExampleA user runs xmodmap. xmodmap registers withthe SM, sets RestartStyleHint to RestartAnyway,and then terminates. In order to allow the SM(at the user’s request) to undo this, xmodmapwould register a ResignCommand that undoes theeffects of the xmodmap.RestartStyleHintIf the RestartStyleHint property is present, it willcontain the style of restarting the client prefers. Ifthis flag isn’t specified, RestartIfRunning is assumed.The possible values are as follows:The RestartIfRunning style is used in the usual case.The client should be restarted in the next session if itis connected to the session manager at the end of thecurrent session.The RestartAnyway style is used to tell the SM that theapplication should be restarted in the next session evenif it exits before the current session is terminated. Itshould be noted that this is only a hint and the SM willfollow the policies specified by its users in determiningwhat applications to restart.RationaleThis can be specified by a client whichsupports (as MS-Windows clients do) a means forthe user to indicate while exiting thatrestarting is desired. It can also be used forclients that spawn other clients and then goaway, but which want to be restarted.A client that uses RestartAnyway should also set theResignCommand and ShutdownCommand properties to commandsthat undo the state of the client after it exits.The RestartImmediately style is like RestartAnyway, butin addition, the client is meant to run continuously. Ifthe client exits, the SM should try to restart it in thecurrent session. Advice to ImplementorsIt would be wise to sanity-check the frequencywhich which RestartImmediately clients arerestarted, to avoid a sick client beingrestarted continuously.The RestartNever style specifies that the client does notwish to be restarted in the next session.Advice To ImplementorsThis should be used rarely, if at all. It willcause the client to be silently left out ofsessions when they are restarted and willprobably be confusing to users.ShutdownCommandThis command is executed at shutdown time to clean upafter a client that is no longer running but retained itsstate by setting RestartStyleHint to RestartAnyway. Thecommand must not remove any saved state as the client isstill part of the session.ExampleA client is run at start up time that turns ona camera. This client then exits. At sessionshutdown, the user wants the camera turned off.This client would set the RestartStyleHint toRestartAnyway and would register a Shutdown-Command that would turn off the camera.UserIDSpecifies the user’s ID. On POSIX-based systems thiswill contain the the user’s name (the pw_name field ofstruct passwd). 1

X Session Management Protocol X11, Release 6.4