217 lines
5.2 KiB
XML
217 lines
5.2 KiB
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 <emphasis>
|
|
XkbSetDebuggingFlags</emphasis>
|
|
.
|
|
</para>
|
|
|
|
<informaltable frame='none'>
|
|
<tgroup cols='1'>
|
|
<colspec colsep='0'/>
|
|
<tbody>
|
|
<row rowsep='0'>
|
|
<entry role='functiondecl'>
|
|
Bool <emphasis>
|
|
XkbSetDebuggingFlags</emphasis>
|
|
(<emphasis>
|
|
display, mask, flags, msg, ctrls_mask, ctrls, ret_flags, ret_ctrls</emphasis>
|
|
)
|
|
</entry>
|
|
</row>
|
|
<row rowsep='0'>
|
|
<entry role='functionargdecl'>
|
|
Display * <emphasis>
|
|
display</emphasis>
|
|
; /* connection to X server */
|
|
</entry>
|
|
</row>
|
|
<row rowsep='0'>
|
|
<entry role='functionargdecl'>
|
|
unsigned int <emphasis>
|
|
mask</emphasis>
|
|
; /* mask selecting debug output flags to change */
|
|
</entry>
|
|
</row>
|
|
<row rowsep='0'>
|
|
<entry role='functionargdecl'>
|
|
unsigned int <emphasis>
|
|
flags</emphasis>
|
|
; /* values for debug output flags selected by <emphasis>
|
|
mask</emphasis>
|
|
*/
|
|
</entry>
|
|
</row>
|
|
<row rowsep='0'>
|
|
<entry role='functionargdecl'>
|
|
char * <emphasis>
|
|
msg</emphasis>
|
|
; /* message to print right now */
|
|
</entry>
|
|
</row>
|
|
<row rowsep='0'>
|
|
<entry role='functionargdecl'>
|
|
unsigned int <emphasis>
|
|
ctrls_mask</emphasis>
|
|
; /* mask selecting debug controls to change */
|
|
</entry>
|
|
</row>
|
|
<row rowsep='0'>
|
|
<entry role='functionargdecl'>
|
|
unsigned int <emphasis>
|
|
ctrls</emphasis>
|
|
; /* values for debug controls selected by <emphasis>
|
|
ctrls_mask</emphasis>
|
|
*/
|
|
</entry>
|
|
</row>
|
|
<row rowsep='0'>
|
|
<entry role='functionargdecl'>
|
|
unsigned int * <emphasis>
|
|
ret_flags</emphasis>
|
|
; /* resulting state of all debug output flags */
|
|
</entry>
|
|
</row>
|
|
<row rowsep='0'>
|
|
<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='none'>
|
|
<title>Debug Control Masks</title>
|
|
<tgroup cols='3'>
|
|
<colspec colsep='0'/>
|
|
<colspec colsep='0'/>
|
|
<colspec colsep='0'/>
|
|
<thead>
|
|
<row rowsep='0'>
|
|
<entry>Debug Control Mask</entry>
|
|
<entry>Value</entry>
|
|
<entry>Meaning</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row rowsep='0'>
|
|
<entry>XkbDF_DisableLocks</entry>
|
|
<entry>(1 << 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>
|