242 lines
6.3 KiB
XML
242 lines
6.3 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
|
|
<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>
|
|
<!-- (
|
|
<parameter>display, mask, flags, msg, ctrls_mask, ctrls, ret_flags, ret_ctrls</parameter>
|
|
) -->
|
|
|
|
<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
|
|
<parameter>mask</parameter>
|
|
and
|
|
<parameter>flags</parameter>,
|
|
modifies the debug controls flags as specified by
|
|
<parameter>ctrls_mask</parameter>
|
|
and
|
|
<parameter>ctrls</parameter>,
|
|
prints the message
|
|
<parameter>msg</parameter>,
|
|
and backfills
|
|
<parameter>ret_flags</parameter>
|
|
and
|
|
<parameter>ret_ctrls</parameter>
|
|
with the resulting debug output and debug controls flags.
|
|
</para>
|
|
|
|
|
|
<para>
|
|
When bits are set in the debug output masks,
|
|
<parameter>mask</parameter>
|
|
and
|
|
<parameter>flags</parameter>,
|
|
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
|
|
<parameter>mask</parameter>
|
|
and
|
|
<parameter>flags</parameter>
|
|
is implementation-specific. To turn on a debug output selection, set the bit
|
|
for the output in the
|
|
<parameter>mask</parameter>
|
|
parameter and set the corresponding bit in the
|
|
<parameter>flags</parameter>
|
|
parameter. To turn off event selection for an event, set the bit for the
|
|
output in the
|
|
<parameter>mask</parameter>
|
|
parameter and do not set the corresponding bit in the
|
|
<parameter>flags</parameter>
|
|
parameter.
|
|
</para>
|
|
|
|
|
|
<para>
|
|
When bits are set in the debug controls masks,
|
|
<parameter>ctrls_mask</parameter>
|
|
and
|
|
<parameter>ctrls</parameter>,
|
|
Xkb modifies its behavior according to each controls bit.
|
|
<parameter>ctrls_mask</parameter>
|
|
and
|
|
<parameter>ctrls</parameter>
|
|
are related in the same way that
|
|
<parameter>mask</parameter>
|
|
and
|
|
<parameter>flags</parameter>
|
|
are. The valid controls bits are defined in
|
|
<link linkend="table22.1">Table 22.1</link>.
|
|
</para>
|
|
|
|
<table id='table22.1' 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><symbol>XkbDF_DisableLocks</symbol></entry>
|
|
<entry>(1 << 0)</entry>
|
|
<entry>Disable actions that lock modifiers</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>
|
|
<function>XkbSetDebuggingFlags</function>
|
|
returns
|
|
<symbol>True</symbol>
|
|
if successful and
|
|
<symbol>False</symbol>
|
|
otherwise. The only protocol error it may generate is
|
|
<errorname>BadAlloc</errorname>,
|
|
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
|
|
<parameter>msg</parameter>
|
|
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>
|