diff options
| -rw-r--r-- | doc/xsmp.xml | 168 |
1 files changed, 86 insertions, 82 deletions
diff --git a/doc/xsmp.xml b/doc/xsmp.xml index 6584be1..c2d41d8 100644 --- a/doc/xsmp.xml +++ b/doc/xsmp.xml @@ -68,7 +68,7 @@ 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. +top of the X.Org <acronym>ICE</acronym> protocol. </para> </abstract> @@ -78,8 +78,8 @@ top of the X.Org ICE protocol. <title>Acknowledgments</title> <para> -First I would like to thank the entire ICCCM and Intrinsics working -groups for the comments and suggestions. I would like to make special +First I would like to thank the entire <acronym>ICCCM</acronym> 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. @@ -90,12 +90,12 @@ and Bob Scheifler. <title>Definitions and Goals</title> <para> -The purpose of the X Session Management Protocol (XSMP) is to provide -a uniform mechanism for users to save and restore their sessions. -A <emphasis remap='I'>session</emphasis> is a group of clients, each +The purpose of the X Session Management Protocol (<acronym>XSMP</acronym>) is +to provide a uniform mechanism for users to save and restore their sessions. +A <firstterm>session</firstterm> is a group of clients, each of which has a particular state. The session is controlled by a -network service called the <emphasis remap='I'>session -manager</emphasis>. The session manager issues commands to its +network service called the <firstterm>session manager</firstterm>. +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 @@ -108,7 +108,7 @@ protocol. </para> <para> -For purposes of this protocol, a <emphasis remap='I'>client</emphasis> +For purposes of this protocol, a <firstterm>client</firstterm> 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 @@ -117,8 +117,8 @@ display or not be connected to any X displays at all. </para> <para> -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. +This protocol is layered on top of the X Consortium's <acronym>ICE</acronym> protocol and +relies on the <acronym>ICE</acronym> protocol to handle connection management and authentication. </para> </chapter> @@ -138,13 +138,13 @@ taken as an indication that the client died unexpectedly. <para> 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 <emphasis remap='I'>client-ID</emphasis> is +unique value called a <firstterm>client-ID</firstterm> 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 <emphasis remap='I'>RestartCommand</emphasis>) so that the client +(the <property>RestartCommand</property>) 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 @@ -154,22 +154,23 @@ restarted. <para> The client finds the network address of the SM in a system-dependent -way. On POSIX systems an environment variable called SESSION_MANAGER +way. On <acronym>POSIX</acronym> systems an environment +variable called <envar>SESSION_MANAGER</envar> 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: -<literallayout remap='DS'> -<emphasis remap='C'>tcp/</emphasis><emphasis remap='I'>hostname</emphasis><emphasis remap='C'>:</emphasis><emphasis remap='I'>portnumber</emphasis> -</literallayout> + <informalexample><para> + <literal>tcp/</literal><replaceable>hostname</replaceable><literal>:</literal><replaceable>portnumber</replaceable> + </para></informalexample> where the hostname is a fully qualified domain name. A Unix Domain address looks like this: -<literallayout remap='DS'> -<emphasis remap='C'>local/</emphasis><emphasis remap='I'>hostname</emphasis><emphasis remap='C'>:</emphasis><emphasis remap='I'>path</emphasis> -</literallayout> + <informalexample><para> + <literal>local/</literal><replaceable>hostname</replaceable><literal>:</literal><replaceable>path</replaceable> + </para></informalexample> A DECnet address would look like this: -<literallayout remap='DS'> -<emphasis remap='C'>decnet/</emphasis><emphasis remap='I'>nodename</emphasis><emphasis remap='C'>::</emphasis><emphasis remap='I'>objname</emphasis> -</literallayout> + <informalexample><para> + <literal>decnet/</literal><replaceable>nodename</replaceable><literal>::</literal><replaceable>objname</replaceable> + </para></informalexample> </para> <para> @@ -214,8 +215,8 @@ 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 +information (i.e., the <envar>SESSION_MANAGER</envar> environment variable) +that specifies a connection to itself instead of to the top level session manager. </para> @@ -235,7 +236,7 @@ no properties set. 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. +byte-swapping is determined at run-time by the <acronym>ICE</acronym> protocol. </para> <para> @@ -257,7 +258,7 @@ the receiver of the message to the sender of the message. <tbody> <row> <entry align='left'>BOOL</entry> - <entry align='left'><para><function>False</function> or <function>True</function></para></entry> + <entry align='left'><para><constant>False</constant> or <constant>True</constant></para></entry> </row> <row> <entry align='left'>INTERACT_STYLE</entry> @@ -310,9 +311,9 @@ the receiver of the message to the sender of the message. <para> To start the XSMP protocol, the client sends the server an -ICE <function>ProtocolSetup</function> 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 +<acronym>ICE</acronym> <function>ProtocolSetup</function> message. All XSMP messages are +in the standard <acronym>ICE</acronym> message format. The message's major opcode is +assigned to XSMP by <acronym>ICE</acronym> 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 @@ -332,20 +333,24 @@ and <function>Register­ClientReply</function> messages. <para> 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'. +All pieces are padded on the left with '<literal>0</literal>' +characters so as to fill the specified length. Decimal numbers are +encoded using the characters '<literal>0</literal>' through +'<literal>9</literal>', and hexadecimal numbers using the characters +'<literal>0</literal>' through '<literal>9</literal>' and +'<literal>A</literal>' through '<literal>F</literal>'. </para> <itemizedlist mark='bullet'> - <listitem><para>Version. This is currently the character '1'.</para></listitem> + <listitem><para> +Version. This is currently the character '<literal>1</literal>'. + </para></listitem> <listitem> <para>Address type and address. The address type will be one of <literallayout remap='DS'> - '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 + '<literal>1</literal>' a 4-byte IPv4 address encoded as 8 hexadecimal digits + '<literal>2</literal>' a 6-byte DECNET address encoded as 12 hexadecimal digits + '<literal>6</literal>' a 16-byte IPv6 address encoded as 32 hexadecimal digits </literallayout> </para> @@ -353,7 +358,7 @@ characters '0' through '9' and 'A' through 'F'. 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". +"<literal>QC6702D0B</literal>". </para> </listitem> <listitem><para> @@ -364,7 +369,7 @@ address 198.112.45.11 would be encoded as the string <para> Process-ID type and process-ID. The process-ID type will be one of <literallayout remap='DS'> -'1' a POSIX process-ID encoded as a 10-digit decimal number. + '<literal>1</literal>' a <acronym>POSIX</acronym> process-ID encoded as a 10-digit decimal number. </literallayout> </para> <para> @@ -398,12 +403,12 @@ any user, session manager, and machine will be different from any other. <title>Protocol</title> <para> The protocol consists of a sequence of messages as described below. -Each message type is specified by an ICE minor opcode. A given +Each message type is specified by an <acronym>ICE</acronym> 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. +<acronym>ICE</acronym> severity is given in parentheses following each error class. </para> <para><function>RegisterClient</function> [Client → SM]</para> @@ -604,7 +609,7 @@ user does after the save will be lost. <para> 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 <function>True</function> +is about to fail, it should set the fast field to <constant>True</constant> </para> <para><function>SaveYourselfPhase2</function> [Client → SM]</para> @@ -660,15 +665,16 @@ message in response and it may leave the fields intact. </para> <note remap='NT'> <para> -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. +A vendor of a <acronym>UPS</acronym> (Uninterruptible Power Supply) +might include an SM client that would monitor the status of +the <acronym>UPS</acronym> and generate a fast shutdown if the power +is about to be lost. </para></note> <para> -If global is set to <function>True</function> then the +If global is set to <constant>True</constant> then the resulting <function>SaveYourself</function> should be sent to all -applications. If global is set to <function>False</function> then the +applications. If global is set to <constant>False</constant> then the resulting <function>SaveYourself</function> should be sent to the application that sent the <function>Save­Yourself­Request</function> </para> @@ -723,14 +729,14 @@ This message is used by a client to notify the SM that it is done interacting. </para> <para> -Setting the cancel-shutdown field to <function>True</function> +Setting the cancel-shutdown field to <constant>True</constant> indicates that the user has requested that the entire shutdown be -cancelled. Cancel-shutdown may only be <function>True</function> if +cancelled. Cancel-shutdown may only be <constant>True</constant> if the corresponding <function>SaveYourself</function> message -specified <function>True</function> for the shutdown field +specified <constant>True</constant> for the shutdown field and <function>Any</function> or <function>Errors</function> for the interact-style field. Otherwise, cancel-shutdown must -be <function>False</function> +be <constant>False</constant> </para> <para><function>SaveYourselfDone</function> [Client → SM]</para> @@ -750,14 +756,14 @@ sending <function>SaveYourselfDone</function> the client must wait for a <function>SaveComplete</function> <function>ShutdownCancelled</function> or <function>Die</function> message before changing its state. If the <function>SaveYourself</function> operation was successful, then -the client should set the success field to <function>True</function> -otherwise the client should set it to <function>False</function> +the client should set the success field to <constant>True</constant> +otherwise the client should set it to <constant>False</constant> </para> <note remap='NT'> <para> If a client tries to save its state and runs out of disk space, it -should return <function>False</function> in the success field of +should return <constant>False</constant> in the success field of the <function>SaveYourselfDone</function> message. </para> </note> @@ -802,7 +808,7 @@ 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 <function>SaveYourselfDone</function> yet, the client can either abort the save and send <function>SaveYourselfDone</function> -with the success field set to <function>False</function> or it can +with the success field set to <constant>False</constant> or it can continue with the save and send a <function>SaveYourselfDone</function> with the success field set to reflect the outcome of the save. </para> @@ -822,7 +828,7 @@ 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 +on a <acronym>POSIX</acronym> 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. </para> @@ -892,10 +898,10 @@ message and includes the values of all the properties. <para> When the receiver of a message detects an error condition, the -receiver sends an ICE error message to the sender. There are only two +receiver sends an <acronym>ICE</acronym> error message to the sender. There are only two types of errors that are used by the XSMP: <function>BadValue</function> and <function>BadState</function> -These are both defined in the ICE protocol. +These are both defined in the <acronym>ICE</acronym> protocol. </para> <para> @@ -917,7 +923,7 @@ client and the SM. <!-- <literallayout remap='DS'> --> <literallayout> <emphasis remap='I'>start:</emphasis> - ICE protocol setup complete → <emphasis remap='C'>register</emphasis></literallayout> + <acronym>ICE</acronym> protocol setup complete → <emphasis remap='C'>register</emphasis></literallayout> <literallayout> <emphasis remap='I'>register:</emphasis> @@ -1379,18 +1385,19 @@ client and the SM. <sect1 id='messages'> <title>Messages</title> <para> -XSMP is a sub-protocol of ICE. The major opcode is assigned at -run-time by ICE and is represented here by '?'. +XSMP is a sub-protocol of <acronym>ICE</acronym>. The major opcode is +assigned at run-time by <acronym>ICE</acronym> and is represented here +by '<literal>?</literal>'. </para> <para> To start the XSMP protocol, the client sends the server an -ICE <function>ProtocolSetup</function> message. The protocol-name -field should be specified as "XSMP", 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. +<acronym>ICE</acronym> <function>ProtocolSetup</function> message. +The protocol-name field should be specified as "<literal>XSMP</literal>", +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. </para> <para> @@ -1399,7 +1406,7 @@ 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 <function>ProtocolReply</function> message. +<acronym>ICE</acronym> <function>ProtocolReply</function> message. </para> <informaltable pgwide='0' frame='all'> @@ -2284,14 +2291,14 @@ of stored properties does not extend into subsequent sessions. <listitem> <para> This is like the <function>RestartCommand</function> 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 +application doesn't supply its client id at register time. On <acronym>POSIX</acronym> systems the type should be a LISTofARRAY8. </para></listitem> </varlistentry> <varlistentry> <term>CurrentDirectory</term> <listitem><para> -On POSIX-based systems specifies the value of the current directory that +On <acronym>POSIX</acronym>-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. </para></listitem> </varlistentry> @@ -2303,13 +2310,13 @@ 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 <function>Restart­Command</function> On -POSIX systems the type should be LISTofARRAY8. +<acronym>POSIX</acronym> systems the type should be LISTofARRAY8. </para></listitem> </varlistentry> <varlistentry> <term>Environment</term> <listitem><para> -On POSIX based systems, this will be of type LISTofARRAY8 where the +On <acronym>POSIX</acronym> based systems, this will be of type LISTofARRAY8 where the ARRAY8s alternate between environment variable name and environment variable value. </para></listitem> @@ -2317,7 +2324,7 @@ variable value. <varlistentry> <term>ProcessID</term> <listitem><para> -This specifies an OS-specific identifier for the process. On POSIX +This specifies an OS-specific identifier for the process. On <acronym>POSIX</acronym> systems this should of type ARRAY8 and contain the return value of getpid() turned into a Latin-1 (decimal) string. </para></listitem> @@ -2325,7 +2332,7 @@ getpid() turned into a Latin-1 (decimal) string. <varlistentry> <term>Program</term> <listitem><para> -The name of the program that is running. On POSIX systems this should +The name of the program that is running. On <acronym>POSIX</acronym> systems this should be the first parameter passed to execve and should be of type ARRAY8. </para></listitem> </varlistentry> @@ -2334,7 +2341,7 @@ be the first parameter passed to execve and should be of type ARRAY8. <listitem><para> 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 +cause the client to restart in its current state. On <acronym>POSIX</acronym>-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 @@ -2379,10 +2386,6 @@ possible values are as follows: <entry align='left'>Name</entry> <entry align='right'>Value</entry> </row> - <row> - <entry align='left'>.TH</entry> - <entry align='right'></entry> - </row> </thead> <tbody> <row> @@ -2480,8 +2483,9 @@ to <function>Restart­Anyway</function> and would register a <varlistentry> <term>UserID</term> <listitem><para> -Specifies the user's ID. On POSIX-based systems this will contain the -the user's name (the pw_name field of struct passwd). +Specifies the user's ID. On <acronym>POSIX</acronym>-based systems +this will contain the the user's name (the <structfield>pw_name</structfield> +field of <structname>struct passwd</structname>). </para></listitem> </varlistentry> </variablelist> |