diff options
Diffstat (limited to 'libX11/specs/XKB/ch22.xml')
| -rw-r--r-- | libX11/specs/XKB/ch22.xml | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/libX11/specs/XKB/ch22.xml b/libX11/specs/XKB/ch22.xml new file mode 100644 index 000000000..ba16bffbc --- /dev/null +++ b/libX11/specs/XKB/ch22.xml @@ -0,0 +1,216 @@ +<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> |