doc: explain when to use FT_STRINGZ, and document FT_STRINGZPAD.

FT_STRINGZ should be used *ONLY* if the string is *ALWAYS* supposed to
have a null terminator, either because the length isn't otherwise
specified, so that it can only be determined by finding the terminating
null character, or because a character count *and* a NULL terminator are
both used (yes, there appear to be some cases where that's true).

FT_STRINGZPAD is null-padded rather than null-terminated; this is
typically used for fixed-length fields that contain a string value that
might be shorter than the fixed length.

Change-Id: Ifdf421ca666482583a4dfc76167eae6dc473f48a
Reviewed-on: https://code.wireshark.org/review/38137
Reviewed-by: Guy Harris <gharris@sonic.net>
This commit is contained in:
Guy Harris 2020-08-12 02:02:56 -07:00
parent 9eddbdafa9
commit efd7cb38e6
1 changed files with 13 additions and 0 deletions

View File

@ -903,6 +903,19 @@ The type of value this field holds. The current field types are:
However if the length given in the call
is -1, then the length used is that
returned by calling tvb_strsize().
This should only be used if the string,
in the packet, is always terminated with
a NULL character, either because the length
isn't otherwise specified or because a
character count *and* a NULL terminator are
both used.
FT_STRINGZPAD A NULL-padded string of characters.
The length is given in the proto_tree_add_item()
call, but may be larger than the length of
the string, with extra bytes being NULL padding.
This is typically used for fixed-length fields
that contain a string value that might be shorter
than the fixed length.
FT_UINT_STRING A counted string of characters, consisting
of a count (represented as an integral value,
of width given in the proto_tree_add_item()