libsm: Changes to 'upstream-unstable'
.gitignore | 73 -
COPYING | 21
INSTALL | 229 ---
Makefile.am | 12
README | 5
configure.ac | 27
doc/.gitignore | 6
doc/Makefile.am | 64
doc/SMlib.xml | 3230 +++++++++++++++++++++++++++++++++++++++++++++++
doc/xsmp.xml | 2274 +++++++++++++++++++++++++++++++++
include/X11/SM/SM.h | 2
include/X11/SM/SMlib.h | 2
include/X11/SM/SMproto.h | 2
src/Makefile.am | 2
src/SMlibint.h | 3
src/sm_auth.c | 3
src/sm_error.c | 3
src/sm_genid.c | 27
src/sm_manager.c | 3
src/sm_misc.c | 2
src/sm_process.c | 3
21 files changed, 5704 insertions(+), 289 deletions(-)
New commits:
commit d2327760a52fdbcd3759211578e3663e00e4a31e
Author: Alan Coopersmith <alan.coopersmith@oracle.com>
Date: Wed Oct 27 22:26:41 2010 -0700
libSM 1.2.0
Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>
diff --git a/configure.ac b/configure.ac
index fd6b045..54aabdb 100644
--- a/configure.ac
+++ b/configure.ac
@@ -3,7 +3,7 @@
AC_PREREQ(2.60)
AC_INIT([libSM],
- 1.1.1,
+ [1.2.0],
[https://bugs.freedesktop.org/enter_bug.cgi?product=xorg],
libSM)
commit 784a330e337af16c1e385d0fbeee1e5369413656
Author: Alan Coopersmith <alan.coopersmith@oracle.com>
Date: Sun Oct 24 20:31:54 2010 -0700
SMlib.xml: Use <simplelist> instead of <synopsis> for lists of mask values
Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>
diff --git a/doc/SMlib.xml b/doc/SMlib.xml
index a82f209..fd84f1a 100644
--- a/doc/SMlib.xml
+++ b/doc/SMlib.xml
@@ -444,12 +444,12 @@ backwards compatibility in future versions of the library.
The following values may be ORed together to obtain a
<parameter>mask</parameter> value:
-<synopsis>
-<constant>SmcSaveYourselfProcMask</constant>
-<constant>SmcDieProcMask</constant>
-<constant>SmcSaveCompleteProcMask</constant>
-<constant>SmcShutdownCancelledProcMask</constant>
-</synopsis>
+ <simplelist type='vert'>
+ <member><constant>SmcSaveYourselfProcMask</constant></member>
+ <member><constant>SmcDieProcMask</constant></member>
+ <member><constant>SmcSaveCompleteProcMask</constant></member>
+ <member><constant>SmcShutdownCancelledProcMask</constant></member>
+ </simplelist>
</para>
<para>
@@ -843,12 +843,12 @@ use <function>SmcModifyCallbacks</function>
When specifying a value for the <parameter>mask</parameter> argument,
the following values may be ORed together:
-<synopsis>
-<constant>SmcSaveYourselfProcMask</constant>
-<constant>SmcDieProcMask</constant>
-<constant>SmcSaveCompleteProcMask</constant>
-<constant>SmcShutdownCancelledProcMask</constant>
-</synopsis>
+ <simplelist type='vert'>
+ <member><constant>SmcSaveYourselfProcMask</constant></member>
+ <member><constant>SmcDieProcMask</constant></member>
+ <member><constant>SmcSaveCompleteProcMask</constant></member>
+ <member><constant>SmcShutdownCancelledProcMask</constant></member>
+ </simplelist>
</para>
</sect1>
@@ -1624,18 +1624,18 @@ of the library.
<para>
The following values may be ORed together to obtain a mask value:
-<synopsis>
-<constant>SmsRegisterClientProcMask</constant>
-<constant>SmsInteractRequestProcMask</constant>
-<constant>SmsInteractDoneProcMask</constant>
-<constant>SmsSaveYourselfRequestProcMask</constant>
-<constant>SmsSaveYourselfP2RequestProcMask</constant>
-<constant>SmsSaveYourselfDoneProcMask</constant>
-<constant>SmsCloseConnectionProcMask</constant>
-<constant>SmsSetPropertiesProcMask</constant>
-<constant>SmsDeletePropertiesProcMask</constant>
-<constant>SmsGetPropertiesProcMask</constant>
-</synopsis>
+ <simplelist type='vert'>
+ <member><constant>SmsRegisterClientProcMask</constant></member>
+ <member><constant>SmsInteractRequestProcMask</constant></member>
+ <member><constant>SmsInteractDoneProcMask</constant></member>
+ <member><constant>SmsSaveYourselfRequestProcMask</constant></member>
+ <member><constant>SmsSaveYourselfP2RequestProcMask</constant></member>
+ <member><constant>SmsSaveYourselfDoneProcMask</constant></member>
+ <member><constant>SmsCloseConnectionProcMask</constant></member>
+ <member><constant>SmsSetPropertiesProcMask</constant></member>
+ <member><constant>SmsDeletePropertiesProcMask</constant></member>
+ <member><constant>SmsGetPropertiesProcMask</constant></member>
+ </simplelist>
</para>
<para>
commit 12af18dd9a731a816e7b074bbecaa5549bfdba31
Author: Alan Coopersmith <alan.coopersmith@oracle.com>
Date: Sun Oct 24 19:57:32 2010 -0700
SMlib.xml: Tag function names, parameters, constant values, etc.
Includes correcting <function> tags on things that aren't functions
as some stylesheets may add () after <function> tagged items so we
shouldn't use them for constants, variables, filenames, etc.
Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>
diff --git a/doc/SMlib.xml b/doc/SMlib.xml
index d49983c..a82f209 100644
--- a/doc/SMlib.xml
+++ b/doc/SMlib.xml
@@ -131,12 +131,12 @@ a <firstterm>client-ID</firstterm> that uniquely identifies them in
the session. The session manager maintains a list of properties for
each client in the session. These properties describe the client's
environment and, most importantly, describe how the client can be
-restarted (via an <function>SmRestartCommand</function>. Clients are
+restarted (via an <property>SmRestartCommand</property>). Clients are
expected to save their state in such a way as to allow multiple
instantiations of themselves to be managed independently. For
example, clients may use their client-ID 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 <function>SmRestartCommand</function>
+client-ID should be saved as part of the <property>SmRestartCommand</property>
so that the client will retain the same ID after it is restarted.
</para>
@@ -224,16 +224,17 @@ standard.
<para>
Applications (both session managers and clients) should include the
-header file <<symbol role='Pn'>X11/SM/SMlib.h</symbol>>. This
-header file defines all of the SMlib data structures and function
-prototypes. <function>SMlib.h</function> includes the header file
-<<symbol role='Pn'>X11/SM/SM.h</symbol>>, which defines all of
-the SMlib constants.
+header file <<filename class='headerfile'>X11/SM/SMlib.h</filename>>.
+This header file defines all of the SMlib data structures and function
+prototypes. <filename class='headerfile'>SMlib.h</filename> includes the
+header file <<filename class='headerfile'>X11/SM/SM.h</filename>>,
+which defines all of the SMlib constants.
</para>
<para>
Because SMlib is dependent on ICE, applications should link against
-SMlib and ICElib by using <function>-lSM</function> <function>-lICE</function>
+SMlib and ICElib by using
+<quote><option>-lSM</option> <option>-lICE</option></quote>.
</para>
</chapter>
@@ -288,8 +289,9 @@ use <function>SmcOpenConnection</function>
<varlistentry>
<term><parameter>context</parameter></term>
<listitem><para>
-A pointer to an opaque object or NULL. Used to determine if an ICE
-connection can be shared (see <link linkend='context_sharing'>below</link>).
+A pointer to an opaque object or <constant>NULL</constant>. Used to determine
+if an ICE connection can be shared
+(see <link linkend='context_sharing'>below</link>).
</para></listitem>
</varlistentry>
<varlistentry>
@@ -302,7 +304,7 @@ The highest major version of the XSMP the application supports.
<term><parameter>xsmp_minor_rev</parameter></term>
<listitem><para>
The highest minor version of the XSMP the application supports (for
-the specified xsmp_major_rev).
+the specified <parameter>xsmp_major_rev</parameter>).
</para></listitem>
</varlistentry>
<varlistentry>
@@ -326,22 +328,23 @@ messages from the session manager.
</varlistentry>
<varlistentry>
<term><parameter>error_length</parameter></term>
- <listitem><para>Length of the error_string_ret argument passed in.</para></listitem>
+ <listitem><para>Length of the <parameter>error_string_ret</parameter> argument passed in.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>error_string_ret</parameter></term>
<listitem><para>
Returns a null-terminated error message, if any.
-The error_string_ret argument points to user supplied memory.
-No more than error_length bytes are used.
+The <parameter>error_string_ret</parameter> argument points to user supplied
+memory. No more than <parameter>error_length</parameter> bytes are used.
</para></listitem>
</varlistentry>
</variablelist>
<para>
-The network_ids_list argument is a null-terminated string containing
-a list of network IDs for the session manager, separated by commas.
-If network_ids_list is NULL, the value of
+The <parameter>network_ids_list</parameter> argument is a
+null-terminated string containing a list of network IDs for the session
+manager, separated by commas. If <parameter>network_ids_list</parameter>
+is <constant>NULL</constant>, the value of
the <envar>SESSION_MANAGER</envar> environment variable will be used.
Each network ID has the following format:
@@ -379,22 +382,24 @@ an attempt will be made using the second network ID, and so on.
<para>
After the connection is established, <function>SmcOpenConnection</function>
registers the client with the session manager. If the client is being
-restarted from a previous session, previous_id should contain a null
-terminated string representing the client ID from the previous
-session. If the client is first joining the session, previous_id
-should be set to NULL. If previous_id is specified but is determined
+restarted from a previous session, <parameter>previous_id</parameter>
+should contain a null terminated string representing the client ID from the
+previous session. If the client is first joining the session,
+<parameter>previous_id</parameter> should be set to <constant>NULL</constant>.
+If <parameter>previous_id</parameter> is specified but is determined
to be invalid by the session manager, SMlib will re-register the
-client with previous_id set to NULL.
+client with <parameter>previous_id</parameter> set to <constant>NULL</constant>.
</para>
<para>
If <function>SmcOpenConnection</function> succeeds, it returns an
opaque connection pointer of type <function>SmcConn</function> and the
-client_id_ret argument contains the client ID to be used for this
-session. The client_id_ret should be freed with a call
-to <function>free</function> when no longer needed. On
-failure, <function>SmcOpenConnection</function> returns NULL, and the
-reason for failure is returned in error_string_ret.
+<parameter>client_id_ret</parameter> argument contains the client ID to be
+used for this session. The <parameter>client_id_ret</parameter> should be
+freed with a call to <function>free</function> when no longer needed. On
+failure, <function>SmcOpenConnection</function> returns
+<constant>NULL</constant>, and the reason for failure is returned in
+<parameter>error_string_ret</parameter>.
</para>
<para>
@@ -406,10 +411,11 @@ connection to be used for session management.
<para id='context_sharing'>
The context argument indicates how willing the client is to share the
-ICE connection with other protocols. If context is NULL, then the
-caller is always willing to share the connection. If context is not
-NULL, then the caller is not willing to use a previously opened ICE
-connection that has a different non-NULL context associated with it.
+ICE connection with other protocols. If context is <constant>NULL</constant>,
+then the caller is always willing to share the connection. If context is not
+<constant>NULL</constant>, then the caller is not willing to use a previously
+opened ICE connection that has a different non-<constant>NULL</constant>
+context associated with it.
</para>
<para>
@@ -435,13 +441,14 @@ backwards compatibility in future versions of the library.
</para>
<para>
-The following values may be ORed together to obtain a mask value:
+The following values may be ORed together to obtain a
+<parameter>mask</parameter> value:
<synopsis>
-<function>SmcSaveYourselfProcMask</function>
-<function>SmcDieProcMask</function>
-<function>SmcSaveCompleteProcMask</function>
-<function>SmcShutdownCancelledProcMask</function>
+<constant>SmcSaveYourselfProcMask</constant>
+<constant>SmcDieProcMask</constant>
+<constant>SmcSaveCompleteProcMask</constant>
+<constant>SmcShutdownCancelledProcMask</constant>
</synopsis>
</para>
@@ -534,11 +541,14 @@ been set, the client calls <function>SmcSaveYourselfDone</function>
</para>
<para>
-If interact_style is <function>SmInteractStyleNone</function> the
-client must not interact with the user while saving state. If
-interact_style is <function>SmInteractStyleErrors</function> the
+If <parameter>interact_style</parameter> is
+<constant>SmInteractStyleNone</constant> the
+client must not interact with the user while saving state.
+If <parameter>interact_style</parameter> is
+<constant>SmInteractStyleErrors</constant> the
client may interact with the user only if an error condition arises.
-If interact_style is <function>SmInteractStyleAny</function> then the
+If <parameter>interact_style</parameter> is
+<constant>SmInteractStyleAny</constant> then the
client may interact with the user for any purpose. Because only one
client can interact with the user at a time, the client must
call <function>SmcInteractRequest</function> and wait for an
@@ -551,13 +561,14 @@ calls <function>SmcSaveYourselfDone</function>
</para>
<para>
-If save_type is <function>SmSaveLocal</function> the client must
-update the properties to reflect its current state. 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. If save_type is <function>SmSaveGlobal</function> the user
-wants the client to commit all of its data to permanent, globally
-accessible storage. If save_type is <function>SmSaveBoth</function>
+If <parameter>save_type</parameter> is <constant>SmSaveLocal</constant> the
+client must update the properties to reflect its current state. 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.
+If <parameter>save_type</parameter> is <constant>SmSaveGlobal</constant>
+the user wants the client to commit all of its data to permanent, globally
+accessible storage.
+If <parameter>save_type</parameter> is <constant>SmSaveBoth</constant>
the client should do both of these (it should first commit the data to
permanent storage before updating its properties).
</para>
@@ -568,30 +579,32 @@ Some examples are as follows:
<itemizedlist mark='bullet'>
<listitem><para>
If a word processor were sent a “Save Yourself” with a
-type of <function>SmSaveLocal</function> it could create a temporary
+type of <constant>SmSaveLocal</constant> 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 SmRestartCommand property with enough
-information to find this temporary file.
+would then update its <property>SmRestartCommand</property> property with
+enough information to find this temporary file.
</para></listitem>
<listitem><para>
If a word processor were sent a “Save Yourself” with a
-type of <function>SmSaveGlobal</function> it would simply save the
+type of <constant>SmSaveGlobal</constant> it would simply save the
currently edited file.
</para></listitem>
<listitem><para>
If a word processor were sent a “Save Yourself” with a
-type of <function>SmSaveBoth</function> it would first save the
+type of <constant>SmSaveBoth</constant> 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. Finally, it would update its SmRestartCommand
-property with enough information to find the temporary file.
+is being edited. Finally, it would update its
+<property>SmRestartCommand</property> property with enough information
+to find the temporary file.
</para></listitem>
</itemizedlist>
</para>
<para>
-The shutdown argument specifies whether the system is being shut down.
+The <parameter>shutdown</parameter> argument specifies whether the
+system is being shut down.
The interaction is different depending on whether or not shutdown is
set. If not shutting down, the client should save its state and wait
for a “Save Complete” message. If shutting down, the
@@ -600,9 +613,10 @@ either a “Die” or a “Shutdown Cancelled.”
</para>
<para>
-The fast argument specifies that the client should save its state as
-quickly as possible. For example, if the session manager knows that
-power is about to fail, it would set fast to <function>True</function>
+The <parameter>fast</parameter> argument specifies that the client
+should save its state as quickly as possible. For example, if the
+session manager knows that power is about to fail, it would
+set <parameter>fast</parameter> to <constant>True</constant>.
</para>
</sect2>
@@ -705,9 +719,10 @@ when the user cancelled the shutdown during an interaction
continue as if the shutdown had never happened. If the client has not
called <function>SmcSaveYourselfDone</function> yet, it can either
abort the save and then call <function>SmcSaveYourselfDone</function>
-with the success argument set to <function>False</function> or it can
+with the success argument set to <constant>False</constant> or it can
continue with the save and then call <function>SmcSaveYourselfDone</function>
-with the success argument set to reflect the outcome of the save.
+with the <parameter>success</parameter> argument set to reflect the outcome
+of the save.
</para>
</sect2>
</sect1>
@@ -743,11 +758,11 @@ use <function>SmcCloseConnection</function>
</variablelist>
<para>
-The reason_msgs argument will most likely be NULL if resignation is
-expected by the client. Otherwise, it contains a list of
-null-terminated Compound Text strings representing the reason for
-termination. The session manager should display these reason messages
-to the user.
+The <parameter>reason_msgs</parameter> argument will most likely be
+<constant>NULL</constant> if resignation is expected by the client.
+Otherwise, it contains a list of null-terminated Compound Text strings
+representing the reason for termination. The session manager should
+display these reason messages to the user.
</para>
<para>
@@ -772,11 +787,11 @@ from the list of active descriptors to call <function>select</function> on
<itemizedlist mark='bullet'>
<listitem><para>
-<function>SmcClosedNow</function> - the ICE connection was closed at
+<constant>SmcClosedNow</constant> - the ICE connection was closed at
this time, the watch procedures were invoked, and the connection was freed.
</para></listitem>
<listitem><para>
-<function>SmcClosedASAP</function> - an IO error had occurred on the
+<constant>SmcClosedASAP</constant> - an IO error had occurred on the
connection, but <function>SmcCloseConnection</function> is being
called within a nested <function>IceProcessMessages</function> The
watch procedures have been invoked at this time, but the connection
@@ -785,7 +800,7 @@ and <function>IceProcessMessages</function> returns a status
of <function>IceProcessMessagesConnectionClosed</function>
</para> </listitem>
<listitem><para>
-<function>SmcConnectionInUse</function> - the connection was not closed at
+<constant>SmcConnectionInUse</constant> - the connection was not closed at
this time, because it is being used by other active protocols.
</para> </listitem>
</itemizedlist>
@@ -825,14 +840,14 @@ use <function>SmcModifyCallbacks</function>
</variablelist>
<para>
-When specifying a value for the mask argument, the following values
-may be ORed together:
+When specifying a value for the <parameter>mask</parameter> argument,
+the following values may be ORed together:
<synopsis>
-<function>SmcSaveYourselfProcMask</function>
-<function>SmcDieProcMask</function>
-<function>SmcSaveCompleteProcMask</function>
-<function>SmcShutdownCancelledProcMask</function>
+<constant>SmcSaveYourselfProcMask</constant>
+<constant>SmcDieProcMask</constant>
+<constant>SmcSaveCompleteProcMask</constant>
+<constant>SmcShutdownCancelledProcMask</constant>
</synopsis>
</para>
</sect1>
@@ -860,7 +875,7 @@ use <function>SmcSetProperties</function>
<listitem><para>The session management connection object.</para></listitem>
</varlistentry>
<varlistentry>
- <term><parameter>num_proprs</parameter></term>
+ <term><parameter>num_props</parameter></term>
<listitem><para>The number of properties.</para></listitem>
</varlistentry>
<varlistentry>
@@ -881,7 +896,7 @@ the session manager as a database for storing application specific state.
<para>
For a description of session management properties and
-the <function>SmProp</function> structure,
+the <structname>SmProp</structname> structure,
see <link linkend='session_management_properties'>section 7,
“Session Management Properties.”</link>
</para>
@@ -906,7 +921,7 @@ use <function>SmcDeleteProperties</function>
<listitem><para>The session management connection object.</para></listitem>
</varlistentry>
<varlistentry>
- <term><parameter>num_proprs</parameter></term>
+ <term><parameter>num_props</parameter></term>
<listitem><para>The number of properties.</para></listitem>
</varlistentry>
<varlistentry>
@@ -997,8 +1012,9 @@ use <function>free</function>
<para>
After receiving a “Save Yourself” message with an
-interact_style of <function>SmInteractStyleErrors</function>
-or <function>SmInteractStyleAny</function> the client may choose to
+<parameter>interact_style</parameter> of
+<constant>SmInteractStyleErrors</constant>
+or <constant>SmInteractStyleAny</constant> the client may choose to
interact with the user. Because only one client can interact with the
user at a time, the client must call <function>SmcInteractRequest</function>
and wait for an “Interact” message from the session manager.
@@ -1043,9 +1059,9 @@ for failure and a positive value for success.
</para>
<para>
-The dialog_type argument specifies
-either <function>SmDialogError</function> indicating that the client
-wants to start an error dialog, or <function>SmDialogNormal</function>
+The <parameter>dialog_type</parameter> argument specifies
+either <constant>SmDialogError</constant> indicating that the client
+wants to start an error dialog, or <constant>SmDialogNormal</constant>
meaning that the client wishes to start a nonerror dialog.
</para>
@@ -1101,15 +1117,16 @@ message), you should call <function>SmcInteractDone</function>
</varlistentry>
<varlistentry>
<term><parameter>cancel_shutdown</parameter></term>
- <listitem><para>If <function>True</function>, indicates that the user requests that the entire shutdown be cancelled.</para></listitem>
+ <listitem><para>If <constant>True</constant>, indicates that the user requests that the entire shutdown be cancelled.</para></listitem>
</varlistentry>
</variablelist>
<para>
-The cancel_shutdown argument may only be <function>True</function> if
-the corresponding “Save Yourself”
-specified <function>True</function> for shutdown
-and <function>SmInteractStyleErrors</function>
-or <function>SmInteractStyleAny</function> for the interact_style.
+The <parameter>cancel_shutdown</parameter> argument may only be
+<constant>True</constant> if the corresponding “Save Yourself”
+specified <constant>True</constant> for shutdown
+and <constant>SmInteractStyleErrors</constant>
+or <constant>SmInteractStyleAny</constant> for
+the <parameter>interact_style</parameter>.
</para>
</sect1>
@@ -1153,7 +1170,7 @@ use <function>SmcRequestSaveYourself</function>
</varlistentry>
<varlistentry>
<term><parameter>fast</parameter></term>
- <listitem><para>If <function>True</function> the client should save its state as quickly as possible.</para></listitem>
+ <listitem><para>If <constant>True</constant> the client should save its state as quickly as possible.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>global</parameter></term>
@@ -1162,14 +1179,16 @@ use <function>SmcRequestSaveYourself</function>
</variablelist>
<para>
-The save_type, shutdown, interact_style, and fast arguments are discussed
-in more detail in <link linkend='the_save_yourself_callback'>section 5.1.1,
+The <parameter>save_type</parameter>, <parameter>shutdown</parameter>,
+<parameter>interact_style</parameter>, and <parameter>fast</parameter>
+arguments are discussed in more detail in
+<link linkend='the_save_yourself_callback'>section 5.1.1,
“The Save Yourself Callback.”</link>
</para>
<para>
-If global is set to <function>True</function> then the resulting
-“Save Yourself” should be sent to all clients in the
+If <parameter>global</parameter> is set to <constant>True</constant> then
+the resulting “Save Yourself” should be sent to all clients in the
session. For example, a vendor of a Uninterruptible Power Supply
(<acronym>UPS</acronym>) might include a Session Management client
that would monitor the status of the UPS and generate a fast shutdown
@@ -1177,7 +1196,7 @@ if the power is about to be lost.
</para>
<para>
-If global is set to <function>False</function> then the “Save
+If global is set to <constant>False</constant> then the “Save
Yourself” should only be sent to the client that requested it.
</para>
</sect1>
@@ -1251,7 +1270,7 @@ message, you should call <function>SmcSaveYourselfDone</function>
</varlistentry>
<varlistentry>
<term><parameter>success</parameter></term>
- <listitem><para>If <function>True</function> the “Save Yourself” operation was completed successfully.</para></listitem>
+ <listitem><para>If <constant>True</constant> the “Save Yourself” operation was completed successfully.</para></listitem>
</varlistentry>
</variablelist>
@@ -1292,7 +1311,7 @@ the session management protocol associated with this session.
<funcsynopsis>
<funcprototype>
- <funcdef>char <function>*SmcVendor</function></funcdef>
+ <funcdef>char *<function>SmcVendor</function></funcdef>
<paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -1305,7 +1324,7 @@ be freed with a call to <function>free</function>
<funcsynopsis>
<funcprototype>
- <funcdef>char <function>*SmcRelease</function></funcdef>
+ <funcdef>char *<function>SmcRelease</function></funcdef>
<paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -1318,7 +1337,7 @@ with a call to <function>free</function>
<funcsynopsis>
<funcprototype>
- <funcdef>char <function>*SmcClientID</function></funcdef>
+ <funcdef>char *<function>SmcClientID</function></funcdef>
<paramdef>SmcConn <parameter>smc_conn</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -1360,7 +1379,7 @@ standard.
If the client receives an unexpected protocol error from the session
manager, an error handler is invoked by SMlib. A default error
handler exists that simply prints the error message
-to <function>stderr</function> and exits if the severity of the error
+to <varname>stderr</varname> and exits if the severity of the error
is fatal. The client can change this error handler by calling
the <function>SmcSetErrorHandler</function> function.
</para>
@@ -1373,7 +1392,8 @@ the <function>SmcSetErrorHandler</function> function.
</funcsynopsis>
<para>
-The error handler. You should pass NULL to restore the default handler.
+The error handler. You should pass <constant>NULL</constant> to
+restore the default handler.
</para>
@@ -1421,7 +1441,10 @@ The <function>SmcErrorHandler</function> has the following type:
</varlistentry>
<varlistentry>
<term><parameter>severity</parameter></term>
- <listitem><para><function>IceCanContinue</function><function>IceFatalToProtocol</function> or <function>IceFatalToConnection</function></para></listitem>
+ <listitem><para><constant>IceCanContinue</constant>,
+ <constant>IceFatalToProtocol</constant>, or
+ <constant>IceFatalToConnection</constant>
+ </para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>values</parameter></term>
@@ -1510,11 +1533,15 @@ time a new client connects to the session manager.
</varlistentry>
<varlistentry>
<term><parameter>error_length</parameter></term>
- <listitem><para>Length of the error_string_ret argument passed in.</para></listitem>
+ <listitem><para>Length of the <parameter>error_string_ret</parameter> argument passed in.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>error_string_ret</parameter></term>
- <listitem><para>Returns a null-terminated error message, if any. The error_string_ret points to user supplied memory. No more than error_length bytes are used.</para></listitem>
+ <listitem><para>
+Returns a null-terminated error message, if any.
+The <parameter>error_string_ret</parameter> points to user supplied memory.
+No more than <parameter>error_length</parameter> bytes are used.
+ </para></listitem>
</varlistentry>
</variablelist>
@@ -1581,32 +1608,33 @@ the different messages that the client might send.
<para>
If a failure occurs, the <function>SmsNewClientProc</function> should
return a zero status as well as allocate and return a failure reason
-string in failure_reason_ret.
+string in <parameter>failure_reason_ret</parameter>.
SMlib will be responsible for freeing this memory.
</para>
<para>
The session manager must register a set of callbacks to respond to
-client events. The mask_ret argument specifies which callbacks are
-set. All of the callbacks specified in this version of SMlib are
-mandatory. The mask_ret argument is necessary in order to maintain
-backwards compatibility in future versions of the library.
+client events. The <parameter>mask_ret</parameter> argument specifies
+which callbacks are set. All of the callbacks specified in this version of
+SMlib are mandatory. The <parameter>mask_ret</parameter> argument is
+necessary in order to maintain backwards compatibility in future versions
+of the library.
</para>
<para>
The following values may be ORed together to obtain a mask value:
<synopsis>
-<function>SmsRegisterClientProcMask</function>
-<function>SmsInteractRequestProcMask</function>
-<function>SmsInteractDoneProcMask</function>
-<function>SmsSaveYourselfRequestProcMask</function>
-<function>SmsSaveYourselfP2RequestProcMask</function>
-<function>SmsSaveYourselfDoneProcMask</function>
-<function>SmsCloseConnectionProcMask</function>
-<function>SmsSetPropertiesProcMask</function>
-<function>SmsDeletePropertiesProcMask</function>
-<function>SmsGetPropertiesProcMask</function>
+<constant>SmsRegisterClientProcMask</constant>
+<constant>SmsInteractRequestProcMask</constant>
+<constant>SmsInteractDoneProcMask</constant>
+<constant>SmsSaveYourselfRequestProcMask</constant>
+<constant>SmsSaveYourselfP2RequestProcMask</constant>
+<constant>SmsSaveYourselfDoneProcMask</constant>
+<constant>SmsCloseConnectionProcMask</constant>
+<constant>SmsSetPropertiesProcMask</constant>
+<constant>SmsDeletePropertiesProcMask</constant>
+<constant>SmsGetPropertiesProcMask</constant>
</synopsis>
</para>
@@ -1710,18 +1738,19 @@ must be registered with the session manager.
</para>
<para>
-If the client is being restarted from a previous session, previous_id
-will contain a null-terminated string representing the client ID from
-the previous session. Call <function>free</function> on the
-previous_id pointer when it is no longer needed. If the client is
-first joining the session, previous_id will be NULL.
+If the client is being restarted from a previous session,
+<parameter>previous_id</parameter> will contain a null-terminated string
+representing the client ID from the previous session.
+Call <function>free</function> on the <parameter>previous_id</parameter>
+pointer when it is no longer needed. If the client is first joining the
+session, <parameter>previous_id</parameter> will be <constant>NULL</constant>.
</para>
<para>
-If previous_id is invalid, the session manager should not register the
-client at this time. This callback should return a status of zero,
-which will cause an error message to be sent to the client. The
-client should re-register with previous_id set to NULL.
+If <parameter>previous_id</parameter> is invalid, the session manager should
+not register the client at this time. This callback should return a status
+of zero, which will cause an error message to be sent to the client. The
+client should re-register with previous_id set to <constant>NULL</constant>.
</para>
<para>
@@ -1767,8 +1796,9 @@ type <function>SmsInteractRequestProc</function>
<para>
When a client receives a “Save Yourself” message with an
-interact_style of <function>SmInteractStyleErrors</function>
-or <function>SmInteractStyleAny</function> the client may choose to
+<parameter>interact_style</parameter> of
+<constant>SmInteractStyleErrors</constant>
+or <constant>SmInteractStyleAny</constant> the client may choose to
interact with the user. Because only one client can interact with the
user at a time, the client must request to interact with the user.
The session manager should keep a queue of all clients wishing to
@@ -1778,9 +1808,9 @@ before continuing with the next client.
</para>
<para>
-The dialog_type argument specifies
-either <function>SmDialogError</function> indicating that the client
-wants to start an error dialog, or <function>SmDialogNormal</function>
+The <parameter>dialog_type</parameter> argument specifies
+either <constant>SmDialogError</constant> indicating that the client
+wants to start an error dialog, or <constant>SmDialogNormal</constant>
meaning that the client wishes to start a nonerror dialog.
</para>
@@ -1827,9 +1857,10 @@ the <function>SmsInteractDoneProc</function> callback will be invoked.
<para>
Note that the shutdown can be cancelled only if the corresponding
-“Save Yourself” specified <function>True</function> for
-shutdown and <function>SmInteractStyleErrors</function>
-or <function>SmInteractStyleAny</function> for the interact_style.
+“Save Yourself” specified <constant>True</constant> for
+shutdown and <constant>SmInteractStyleErrors</constant>
+or <constant>SmInteractStyleAny</constant> for the
+<parameter>interact_style</parameter>.
</para>
</sect2>
@@ -1878,7 +1909,7 @@ type <function>SmsSaveYourselfRequestProc</function>
</varlistentry>
<varlistentry>
<term><parameter>fast</parameter></term>
- <listitem><para>If <function>True</function> the client should save its state as quickly as possible.</para></listitem>
+ <listitem><para>If <constant>True</constant> the client should save its state as quickly as possible.</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>global</parameter></term>
@@ -1888,17 +1919,18 @@ type <function>SmsSaveYourselfRequestProc</function>
<para>
The Save Yourself Request prompts the session manager to initiate a
-checkpoint or shutdown. For information on the save_type, shutdown,
-interact_style, and fast arguments,
-see <link linkend='sending_a_save_yourself_message'>section 6.3,
+checkpoint or shutdown. For information on the
+<parameter>save_type</parameter>, <parameter>shutdown</parameter>,
+<parameter>interact_style</parameter>, and <parameter>fast</parameter>
+arguments, see <link linkend='sending_a_save_yourself_message'>section 6.3,
“Sending a Save Yourself Message.”</link>
</para>
<para>
-If global is set to <function>True</function> then the resulting
-“Save Yourself” should be sent to all applications. If
-global is set to <function>False</function> then the “Save
-Yourself” should only be sent to the client that requested it.
+If <parameter>global</parameter> is set to <constant>True</constant> then the
+resulting “Save Yourself” should be sent to all applications.
+If <parameter>global</parameter> is set to <constant>False</constant> then the
+“Save Yourself” should only be sent to the client that requested it.
</para>
</sect2>
@@ -1906,7 +1938,8 @@ Yourself” should only be sent to the client that requested it.
<title>The Save Yourself Phase 2 Request Callback</title>
<para>
-The Save Yourself Phase 2 Request callback is of type <function>SmsSaveYourselfPhase2RequestProc</function>
+The Save Yourself Phase 2 Request callback is of
+type <function>SmsSaveYourselfPhase2RequestProc</function>
</para>
<funcsynopsis>
@@ -1965,7 +1998,7 @@ the <function>SmsSaveYourselfDoneProc</function> will be invoked.
</varlistentry>
<varlistentry>
<term><parameter>success</parameter></term>
- <listitem><para>If <function>True</function> the Save Yourself operation was completed successfully.</para></listitem>
+ <listitem><para>If <constant>True</constant> the Save Yourself operation was completed successfully.</para></listitem>
</varlistentry>
</variablelist>
@@ -1981,7 +2014,7 @@ the session manager.
<para>
If the client properly terminates (that is, it
-calls <function>SmcCloseConnection</function>
+calls <function>SmcCloseConnection</function>,
the <function>SmsCloseConnectionProc</function> callback is invoked.
</para>
@@ -2015,7 +2048,8 @@ the <function>SmsCloseConnectionProc</function> callback is invoked.
</variablelist>
<para>
-The reason_msgs argument will most likely be NULL and the count
+The <parameter>reason_msgs</parameter> argument will most likely
+be <constant>NULL</constant> and the <parameter>count</parameter>
argument zero (0) if resignation is expected by the user. Otherwise,
it contains a list of null-terminated Compound Text strings
representing the reason for termination. The session manager should
@@ -2069,7 +2103,7 @@ the <function>SmsSetPropertiesProc</function> callback will be invoked.
<para>
The properties are specified as an array of property pointers. For a
description of session management properties and
-the <function>SmProp</function> structure,
+the <structname>SmProp</structname> structure,
see <link linkend='session_management_properties'>section 7,
“Session Management Properties.”</link>
</para>
@@ -2128,7 +2162,7 @@ the <function>SmsDeletePropertiesProc</function> callback will be invoked.
<para>
The properties are specified as an array of strings. For a
description of session management properties and
-the <function>SmProp</function> structure,
+the <structname>SmProp</structname> structure,
see <link linkend='session_management_properties'>section 7,
“Session Management Properties.”</link>
</para>
@@ -2205,15 +2239,19 @@ it's own internal needs.
</para>
<para>
-If a non-NULL previous_id was specified when the client registered
-itself, client_id should be identical to previous_id.
+If a non-<constant>NULL</constant> <parameter>previous_id</parameter> was
+specified when the client registered itself, <parameter>client_id</parameter>
+should be identical to <parameter>previous_id</parameter>.
</para>
<para>
-Otherwise, client_id should be a unique ID freshly generated by the
-session manager. In addition, the session manager should send a
-“Save Yourself” message with type = Local,
-shutdown = False, interact-style = None, and fast = False
+Otherwise, <parameter>client_id</parameter> should be a unique ID freshly
+generated by the session manager. In addition, the session manager should
+send a “Save Yourself” message with
+<parameter>type</parameter> = <constant>Local</constant>,
+<parameter>shutdown</parameter> = <constant>False</constant>,
+<parameter>interact-style</parameter> = <constant>None</constant>,
+and <parameter>fast</parameter> = <constant>False</constant>
immediately after registering the client.
</para>
@@ -2235,7 +2273,7 @@ to generate a globally unique client ID.
<funcsynopsis>
<funcprototype>
- <funcdef>char <function>*SmsGenerateClientID</function></funcdef>
+ <funcdef>char *<function>SmsGenerateClientID</function></funcdef>
<paramdef>SmsConn <parameter>sms_conn</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -2249,7 +2287,7 @@ to generate a globally unique client ID.
<para>
-NULL will be returned if the ID could not be generated.
+<constant>NULL</constant> will be returned if the ID could not be generated.
Otherwise, the return value of the function is the client ID.
It should be freed with a call to <function>free</function> when
no longer needed.
@@ -2294,7 +2332,7 @@ use <function>SmsSaveYourself</function>.
</varlistentry>
<varlistentry>
<term><parameter>fast</parameter></term>
- <listitem><para>If <function>True</function> the client should save its state as quickly as possible.</para></listitem>
+ <listitem><para>If <constant>True</constant> the client should save its state as quickly as possible.</para></listitem>
</varlistentry>
</variablelist>
@@ -2309,11 +2347,14 @@ sends a “Save Yourself Done” message.
</para>
<para>
-If interact_style is <function>SmInteractStyleNone</function> the
-client must not interact with the user while saving state. If
-interact_style is <function>SmInteractStyleErrors</function> the
+If <parameter>interact_style</parameter>
+is <constant>SmInteractStyleNone</constant> the
+client must not interact with the user while saving state.
+If <parameter>interact_style</parameter>
+is <constant>SmInteractStyleErrors</constant> the
client may interact with the user only if an error condition arises.
-If interact_style is <function>SmInteractStyleAny</function> then the
+If <parameter>interact_style</parameter>
+is <constant>SmInteractStyleAny</constant> then the
client may interact with the user for any purpose. The client must
send an “Interact Request” message and wait for an
“Interact” message from the session manager before it can
@@ -2325,20 +2366,22 @@ Done.”
</para>
<para>
-If save_type is <function>SmSaveLocal</function> the client must
-update the properties to reflect its current state. 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. If save_type is <function>SmSaveGlobal</function> the user
-wants the client to commit all of its data to permanent, globally
-accessible storage. If save_type is <function>SmSaveBoth</function>
+If <parameter>save_type</parameter> is <constant>SmSaveLocal</constant>
+the client must update the properties to reflect its current state.
+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.
+If <parameter>save_type</parameter> is <constant>SmSaveGlobal</constant>
+the user wants the client to commit all of its data to permanent, globally
+accessible storage.
+If <parameter>save_type</parameter> is <constant>SmSaveBoth</constant>
the client should do both of these (it should first commit the data to
permanent storage before updating its properties).
</para>
<para>
-The shutdown argument specifies whether the session is being shut
-down. The interaction is different depending on whether or not
+The <parameter>shutdown</parameter> argument specifies whether the session
+is being shut down. The interaction is different depending on whether or not
shutdown is set. If not shutting down, then the client can save and
resume normal operation. If shutting down, the client must save and
then must prevent interaction until it receives either a
@@ -2347,10 +2390,10 @@ anything the user does after the save will be lost.
</para>
<para>
-The fast argument specifies that the client should save its state as
-quickly as possible. For example, if the session manager knows that
-power is about to fail, it should set fast
-to <function>True</function>
+The <parameter>fast</parameter> argument specifies that the client should
+save its state as quickly as possible. For example, if the session manager
+knows that power is about to fail, it should set <parameter>fast</parameter>
+to <constant>True</constant>.
</para>
</sect1>
Reply to: