head	1.1;
branch	1.1.1;
access;
symbols
	netbsd-11-0-RC7:1.1.1.3
	libX11-1-8-13:1.1.1.3
	netbsd-11-0-RC6:1.1.1.3
	netbsd-11-0-RC5:1.1.1.3
	netbsd-11-0-RC4:1.1.1.3
	netbsd-11-0-RC3:1.1.1.3
	netbsd-11-0-RC2:1.1.1.3
	netbsd-11-0-RC1:1.1.1.3
	netbsd-11:1.1.1.3.0.8
	netbsd-11-base:1.1.1.3
	libX11-1-8-12:1.1.1.3
	netbsd-10-1-RELEASE:1.1.1.3
	libX11-1-8-10:1.1.1.3
	libX11-1-8-9:1.1.1.3
	netbsd-8-3-RELEASE:1.1.1.3
	netbsd-9-4-RELEASE:1.1.1.3
	netbsd-10-0-RELEASE:1.1.1.3
	netbsd-10-0-RC6:1.1.1.3
	netbsd-10-0-RC5:1.1.1.3
	netbsd-10-0-RC4:1.1.1.3
	netbsd-10-0-RC3:1.1.1.3
	netbsd-10-0-RC2:1.1.1.3
	netbsd-10-0-RC1:1.1.1.3
	libX11-1-8-7:1.1.1.3
	libX11-1-8-6:1.1.1.3
	libX11-1-8-4:1.1.1.3
	libX11-1-8-3:1.1.1.3
	netbsd-10:1.1.1.3.0.6
	netbsd-10-base:1.1.1.3
	libX11-1-8-2:1.1.1.3
	netbsd-9-3-RELEASE:1.1.1.3
	libX11-1-8-1:1.1.1.3
	libX11-1-7-2:1.1.1.3
	libX11-1-7-1:1.1.1.3
	netbsd-9-2-RELEASE:1.1.1.3
	libX11-1-7-0:1.1.1.3
	netbsd-9-1-RELEASE:1.1.1.3
	libX11-1-6-12:1.1.1.3
	libX11-1-6-10:1.1.1.3
	netbsd-8-2-RELEASE:1.1.1.3
	libX11-1-6-9:1.1.1.3
	netbsd-9-0-RELEASE:1.1.1.3
	netbsd-9-0-RC2:1.1.1.3
	netbsd-9-0-RC1:1.1.1.3
	netbsd-9:1.1.1.3.0.4
	netbsd-9-base:1.1.1.3
	libX11-1-6-8:1.1.1.3
	netbsd-8-1-RELEASE:1.1.1.3
	netbsd-8-1-RC1:1.1.1.3
	libX11-1-6-7:1.1.1.3
	netbsd-7-2-RELEASE:1.1.1.2
	libX11-1-6-6:1.1.1.3
	netbsd-8-0-RELEASE:1.1.1.3
	netbsd-8-0-RC2:1.1.1.3
	netbsd-8-0-RC1:1.1.1.3
	netbsd-7-1-2-RELEASE:1.1.1.2
	netbsd-7-1-1-RELEASE:1.1.1.2
	netbsd-8:1.1.1.3.0.2
	netbsd-8-base:1.1.1.3
	netbsd-7-1:1.1.1.2.0.8
	netbsd-7-1-RELEASE:1.1.1.2
	libX11-1-6-5:1.1.1.3
	netbsd-7-1-RC2:1.1.1.2
	netbsd-7-1-RC1:1.1.1.2
	netbsd-7-0-2-RELEASE:1.1.1.2
	libX11-1-6-4:1.1.1.3
	netbsd-7-0-1-RELEASE:1.1.1.2
	netbsd-7-0:1.1.1.2.0.6
	netbsd-7-0-RELEASE:1.1.1.2
	netbsd-7-0-RC3:1.1.1.2
	netbsd-7-0-RC2:1.1.1.2
	libX11-1-6-3:1.1.1.3
	netbsd-7-0-RC1:1.1.1.2
	netbsd-6-0-6-RELEASE:1.1.1.1
	netbsd-6-1-5-RELEASE:1.1.1.1
	netbsd-7:1.1.1.2.0.4
	netbsd-7-base:1.1.1.2
	netbsd-6-1-4-RELEASE:1.1.1.1
	netbsd-6-0-5-RELEASE:1.1.1.1
	riastradh-xf86-video-intel-2-7-1-pre-2-21-15:1.1.1.2
	libX11-1-6-2:1.1.1.2
	riastradh-drm2:1.1.1.2.0.2
	riastradh-drm2-base:1.1.1.2
	netbsd-6-1-3-RELEASE:1.1.1.1
	netbsd-6-0-4-RELEASE:1.1.1.1
	netbsd-6-1-2-RELEASE:1.1.1.1
	netbsd-6-0-3-RELEASE:1.1.1.1
	netbsd-6-1-1-RELEASE:1.1.1.1
	libX11-1-6-0:1.1.1.2
	libX11-1-5-99-902:1.1.1.2
	netbsd-6-1:1.1.1.1.0.6
	netbsd-6-0-2-RELEASE:1.1.1.1
	netbsd-6-1-RELEASE:1.1.1.1
	netbsd-6-1-RC4:1.1.1.1
	netbsd-6-1-RC3:1.1.1.1
	netbsd-6-1-RC2:1.1.1.1
	netbsd-6-1-RC1:1.1.1.1
	netbsd-6-0-1-RELEASE:1.1.1.1
	netbsd-6-0:1.1.1.1.0.4
	netbsd-6-0-RELEASE:1.1.1.1
	netbsd-6-0-RC2:1.1.1.1
	netbsd-6-0-RC1:1.1.1.1
	netbsd-6:1.1.1.1.0.2
	netbsd-6-base:1.1.1.1
	libX11-1-4-4:1.1.1.1
	libX11-1-4-3:1.1.1.1
	libX11-1-4-1:1.1.1.1
	xorg:1.1.1;
locks; strict;
comment	@# @;


1.1
date	2011.02.23.07.55.46;	author mrg;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	2011.02.23.07.55.46;	author mrg;	state Exp;
branches;
next	1.1.1.2;

1.1.1.2
date	2013.05.30.23.04.38;	author mrg;	state Exp;
branches;
next	1.1.1.3;
commitid	IUyYawfUjfmA1IRw;

1.1.1.3
date	2015.07.19.08.08.35;	author mrg;	state Exp;
branches;
next	;
commitid	u9SvqCeNOT4JZRty;


desc
@@


1.1
log
@Initial revision
@
text
@<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 &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>
@


1.1.1.1
log
@initial import of libX11-1.4.1:
- remove support for building without XCB
- many man page updates
- many random bug fixes
- several new nls aliases (need to enable these yet.)
@
text
@@


1.1.1.2
log
@initial import of libX11-1.5.99.902
@
text
@d1 1
a1 1
<chapter id='Debugging_Aids'>
d24 2
a25 3
<?dbfo keep-together="always" ?>
<tgroup cols='1' align='left' colsep='0' rowsep='0'>
<colspec colname='c1' colwidth='1.0*'/>
d27 1
a27 1
  <row>
d36 1
a36 1
  <row>
d43 1
a43 1
  <row>
d50 1
a50 1
  <row>
d59 1
a59 1
  <row>
d66 1
a66 1
  <row>
d73 1
a73 1
  <row>
d82 1
a82 1
  <row>
d89 1
a89 1
  <row>
d163 1
a163 1
<table frame='topbot'>
d165 4
a168 5
<?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*'/>
d170 1
a170 1
<row rowsep='1'>
d177 1
a177 1
<row>
@


1.1.1.3
log
@initial import of libX11-1.6.3
@
text
@a0 3
<?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">
d18 3
a20 2
To change the values of any of the debug controls, use
<function>XkbSetDebuggingFlags</function>.
d23 105
a127 127
<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
d130 15
a144 15
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.
d149 13
a161 14
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>.
d164 1
a164 1
<table id='table22.1' frame='topbot'>
d180 1
a180 1
    <entry><symbol>XkbDF_DisableLocks</symbol></entry>
d189 9
a197 8
<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.
d202 6
a207 5
<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.
d212 3
a214 3
The message in
<parameter>msg</parameter>
is written immediately. The device to which it is written is implementation
@