xorg-libx11/specs/XKB/ch22.xml

<chapter id='Debugging_Aids'>
<title>Debugging Aids</title>

<para>
The debugging aids are intended for use primarily by Xkb implementors and are
optional in any implementation.
</para>


<para>
There are two bitmasks that may be used to control debugging. One bitmask
controls the output of debugging information, and the other controls behavior.
Both bitmasks are initially all zeros.
</para>


<para>
To change the values of any of the debug controls, use
<function>XkbSetDebuggingFlags</function>.
</para>

<indexterm significance="preferred" zone="XkbSetDebuggingFlags"><primary><function>XkbSetDebuggingFlags</function></primary></indexterm>
<funcsynopsis id="XkbSetDebuggingFlags">
  <funcprototype>
    <funcdef>Bool <function>XkbSetDebuggingFlags</function></funcdef>
<!-- (
<emphasis>display, mask, flags, msg, ctrls_mask, ctrls, ret_flags, ret_ctrls</emphasis>
) -->

    <paramdef>Display *<parameter>display</parameter></paramdef>
    <paramdef>unsigned int <parameter>mask</parameter></paramdef>
    <paramdef>unsigned int <parameter>flags</parameter></paramdef>
    <paramdef>char *<parameter>msg</parameter></paramdef>
    <paramdef>unsigned int <parameter>ctrls_mask</parameter></paramdef>
    <paramdef>unsigned int <parameter>ctrls</parameter></paramdef>
    <paramdef>unsigned int *<parameter>ret_flags</parameter></paramdef>
    <paramdef>unsigned int *<parameter>ret_ctrls</parameter></paramdef>
  </funcprototype>
</funcsynopsis>
<variablelist>
  <varlistentry>
    <term>
      <parameter>display</parameter>
    </term>
    <listitem>
      <para>
        connection to X server
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>mask</parameter>
    </term>
    <listitem>
      <para>
        mask selecting debug output flags to change
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>flags</parameter>
    </term>
    <listitem>
      <para>
        values for debug output flags selected by <parameter>mask</parameter>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>msg</parameter>
    </term>
    <listitem>
      <para>
        message to print right now
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>ctrls_mask</parameter>
    </term>
    <listitem>
      <para>
        mask selecting debug controls to change
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>ctrls</parameter>
    </term>
    <listitem>
      <para>
        values for debug controls selected by <parameter>ctrls_mask</parameter>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>ret_flags</parameter>
    </term>
    <listitem>
      <para>
        resulting state of all debug output flags
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <parameter>ret_ctrls</parameter>
    </term>
    <listitem>
      <para>
        resulting state of all debug controls
      </para>
    </listitem>
  </varlistentry>
</variablelist>

<para>
<function>XkbSetDebuggingFlags</function>
 modifies the debug output flags as specified by
<emphasis>mask</emphasis>
 and
<emphasis>flags</emphasis>,
modifies the debug controls flags as specified by
<emphasis>ctrls_mask</emphasis>
 and
<emphasis>ctrls</emphasis>,
prints the message
<emphasis>msg</emphasis>,
and backfills
<emphasis>ret_flags</emphasis>
 and
<emphasis>ret_ctrls</emphasis>
 with the resulting debug output and debug controls flags.
</para>


<para>
When bits are set in the debug output masks,
<emphasis>mask</emphasis>
 and
<emphasis>flags</emphasis>,
Xkb prints debug information corresponding to each bit at appropriate points
during its processing. The device to which the output is written is
implementation-dependent, but is normally the same device to which X server
error messages are directed; thus the bits that can be set in
<emphasis>mask</emphasis>
 and
<emphasis>flags</emphasis>
 is implementation-specific. To turn on a debug output selection, set the bit
for the output in the
<emphasis>mask</emphasis>
 parameter and set the corresponding bit in the
<emphasis>flags</emphasis>
 parameter. To turn off event selection for an event, set the bit for the
output in the
<emphasis>mask</emphasis>
 parameter and do not set the corresponding bit in the
<emphasis>flags</emphasis>
 parameter.
</para>


<para>
When bits are set in the debug controls masks,
<emphasis>ctrls_mask</emphasis>
 and
<emphasis>ctrls</emphasis>,
Xkb modifies its behavior according to each controls bit.
<emphasis>ctrls_mask</emphasis>
 and
<emphasis>ctrls</emphasis>
 are related in the same way that
<emphasis>mask</emphasis>
 and
<emphasis>flags</emphasis>
 are. The valid controls bits are defined in Table 22.1.
</para>

<table frame='topbot'>
<title>Debug Control Masks</title>
<?dbfo keep-together="always" ?>
<tgroup cols='3' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.5*'/>
<colspec colname='c2' colwidth='1.0*'/>
<colspec colname='c3' colwidth='2.0*'/>
<thead>
<row rowsep='1'>
  <entry>Debug Control Mask</entry>
  <entry>Value</entry>
  <entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
    <entry>XkbDF_DisableLocks</entry>
    <entry>(1 &lt;&lt; 0)</entry>
    <entry>Disable actions that lock modifiers</entry>
  </row>
</tbody>
</tgroup>
</table>

<para>
<function>XkbSetDebuggingFlags</function>
 returns
<emphasis>True</emphasis>
 if successful and
<emphasis>False</emphasis>
 otherwise. The only protocol error it may generate is
<emphasis>BadAlloc</emphasis>,
if for some reason it is unable to allocate storage.
</para>


<para>
<function>XkbSetDebuggingFlags</function>
 is intended for developer use and may be disabled in production X servers. If
it is disabled,
<function>XkbSetDebuggingFlags</function>
 has no effect and does not generate any protocol errors.
</para>


<para>
The message in
<emphasis>msg</emphasis>
 is written immediately. The device to which it is written is implementation
dependent but is normally the same device where X server error messages are
directed.
</para>
</chapter>