<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 <emphasis>
XkbSetDebuggingFlags</emphasis>
.
</para>

<informaltable frame='none'>
<?dbfo keep-together="always" ?>
<tgroup cols='1' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
<tbody>
  <row>
    <entry role='functiondecl'>
Bool <emphasis>
XkbSetDebuggingFlags</emphasis>
(<emphasis>
display, mask, flags, msg, ctrls_mask, ctrls, ret_flags, ret_ctrls</emphasis>
)
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
Display * <emphasis>
            display</emphasis>
;            /* connection to X server */
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
unsigned int <emphasis>
            mask</emphasis>
;            /* mask selecting debug output flags to change */
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
unsigned int <emphasis>
            flags</emphasis>
;            /* values for debug output flags selected by <emphasis>
mask</emphasis>
 */
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
char * <emphasis>
            msg</emphasis>
;            /* message to print right now */
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
unsigned int            <emphasis>
ctrls_mask</emphasis>
;            /* mask selecting debug controls to change */
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
unsigned int            <emphasis>
ctrls</emphasis>
;            /* values for debug controls selected by <emphasis>
ctrls_mask</emphasis>
 */
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
unsigned int * <emphasis>
            ret_flags</emphasis>
;            /* resulting state of all debug output flags */
    </entry>
  </row>
  <row>
    <entry role='functionargdecl'>
unsigned int *            <emphasis>
ret_ctrls</emphasis>
;            /* resulting state of all debug controls */
    </entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>
<emphasis>
XkbSetDebuggingFlags</emphasis>
 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>
<emphasis>
XkbSetDebuggingFlags</emphasis>
 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>
<emphasis>
XkbSetDebuggingFlags</emphasis>
 is intended for developer use and may be disabled in production X servers. If
it is disabled, <emphasis>
XkbSetDebuggingFlags</emphasis>
 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>