From 95ee49d90c28b15a3c3be54a233368fc69f3531a Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Fri, 16 Aug 2013 21:55:27 -0700 Subject: Add comments about sizes of dynamically allocated arrays Many arrays have sz_* or size_* fields to list the number of entries allocated, and num_* fields to record the number of entries used. Others use num_* for the number allocated, or size based on max_key_code. And a few are just plain trying to mess with your head. (I'm looking at you XkbNamesRec & XkbKeyTypeRec.) It sure would have been nice if all the XKB authors could have picked a single convention and stuck to it, but we're 20 years too late for that now, so just document it so I can stop reverse engineering from the code every time I need to see if we got a bounds check right or not. Signed-off-by: Alan Coopersmith --- XKBgeom.h | 5 +++++ XKBstr.h | 21 +++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/XKBgeom.h b/XKBgeom.h index f603852..cef78fa 100644 --- a/XKBgeom.h +++ b/XKBgeom.h @@ -95,6 +95,11 @@ typedef struct _XkbBounds { #define XkbBoundsWidth(b) (((b)->x2)-((b)->x1)) #define XkbBoundsHeight(b) (((b)->y2)-((b)->y1)) +/* + * In the following structs, this pattern is used for dynamically sized arrays: + * foo is an array for which sz_foo entries are allocated & num_foo are used + */ + typedef struct _XkbOutline { unsigned short num_points; unsigned short sz_points; diff --git a/XKBstr.h b/XKBstr.h index 25c0cec..1146908 100644 --- a/XKBstr.h +++ b/XKBstr.h @@ -92,9 +92,12 @@ typedef struct _XkbKeyType { XkbModsRec mods; unsigned char num_levels; unsigned char map_count; + /* map is an array of map_count XkbKTMapEntryRec structs */ XkbKTMapEntryPtr map; + /* preserve is an array of map_count XkbModsRec structs */ XkbModsPtr preserve; Atom name; + /* level_names is an array of num_levels Atoms */ Atom * level_names; } XkbKeyTypeRec, *XkbKeyTypePtr; @@ -298,10 +301,14 @@ typedef struct _XkbControls { #define XkbAX_NeedFeedback(c,w) (XkbAX_AnyFeedback(c)&&XkbAX_NeedOption(c,w)) typedef struct _XkbServerMapRec { + /* acts is an array of XkbActions structs, with size_acts entries + allocated, and num_acts entries used. */ unsigned short num_acts; unsigned short size_acts; XkbAction *acts; + /* behaviors, key_acts, explicit, & vmodmap are all arrays with + (xkb->max_key_code + 1) entries allocated for each. */ XkbBehavior *behaviors; unsigned short *key_acts; #if defined(__cplusplus) || defined(c_plusplus) @@ -328,15 +335,20 @@ typedef struct _XkbSymMapRec { } XkbSymMapRec, *XkbSymMapPtr; typedef struct _XkbClientMapRec { + /* types is an array of XkbKeyTypeRec structs, with size_types entries + allocated, and num_types entries used. */ unsigned char size_types; unsigned char num_types; XkbKeyTypePtr types; + /* syms is an array of size_syms KeySyms, in which num_syms are used */ unsigned short size_syms; unsigned short num_syms; KeySym *syms; + /* key_sym_map is an array of (max_key_code + 1) XkbSymMapRec structs */ XkbSymMapPtr key_sym_map; + /* modmap is an array of (max_key_code + 1) unsigned chars */ unsigned char *modmap; } XkbClientMapRec, *XkbClientMapPtr; @@ -364,6 +376,8 @@ typedef struct _XkbSymInterpretRec { } XkbSymInterpretRec,*XkbSymInterpretPtr; typedef struct _XkbCompatMapRec { + /* sym_interpret is an array of XkbSymInterpretRec structs, + in which size_si are allocated & num_si are used. */ XkbSymInterpretPtr sym_interpret; XkbModsRec groups[XkbNumKbdGroups]; unsigned short num_si; @@ -413,11 +427,15 @@ typedef struct _XkbNamesRec { Atom vmods[XkbNumVirtualMods]; Atom indicators[XkbNumIndicators]; Atom groups[XkbNumKbdGroups]; + /* keys is an array of (xkb->max_key_code + 1) XkbKeyNameRec entries */ XkbKeyNamePtr keys; + /* key_aliases is an array of num_key_aliases XkbKeyAliasRec entries */ XkbKeyAliasPtr key_aliases; + /* radio_groups is an array of num_rg Atoms */ Atom *radio_groups; Atom phys_symbols; + /* num_keys seems to be unused in libX11 */ unsigned char num_keys; unsigned char num_key_aliases; unsigned short num_rg; @@ -592,6 +610,7 @@ typedef struct _XkbDeviceInfo { unsigned short supported; unsigned short unsupported; + /* btn_acts is an array of num_btn XkbAction entries */ unsigned short num_btns; XkbAction * btn_acts; @@ -599,6 +618,8 @@ typedef struct _XkbDeviceInfo { unsigned short num_leds; unsigned short dflt_kbd_fb; unsigned short dflt_led_fb; + /* leds is an array of XkbDeviceLedInfoRec in which + sz_leds entries are allocated and num_leds entries are used */ XkbDeviceLedInfoPtr leds; } XkbDeviceInfoRec,*XkbDeviceInfoPtr; -- cgit v1.2.3