Bug 93382

Created attachment 120520 [details] [review]
spec: Clarify the marshaling format in a few minor ways

This is an attempt to make that section a little clearer. I don’t think
any factual inaccuracies have been fixed (because I couldn’t find any).

Comment on attachment 120520 [details] [review]
spec: Clarify the marshaling format in a few minor ways

Review of attachment 120520 [details] [review]:
-----------------------------------------------------------------

::: doc/dbus-specification.xml
@@ +1006,5 @@
>          which is not considered to be part of the text. The alignment
>          of the string-like type is the same as the alignment of
> +        <varname>n</varname>. Any alignment padding is placed after the
> +        trailing nul byte, rather than between <varname>n</varname> and the
> +        string text.

Any alignment padding for the string itself would come immediately before the length /n/, as described in the next paragraph.

Any alignment padding that comes after the trailing nul would be the alignment padding of *the next thing in the message* (varying from no padding at all for a byte or signature, up to 0-7 bytes for a (u)int64, double or struct) so it isn't really anything to do with the string.

Both of these are a consequences of the general rule (which might not be explicitly stated in as many words, but perhaps should be) that immediately before any value of type T, you zero-pad to T's alignment.

So I think it would be more accurate to say something like this:

The alignment of the string-like type is the same as the alignment of /n/: any padding required for /n/ appears immediately before /n/ itself. There is never any alignment padding between /n/ and the string text, or between the string text and the trailing nul. The alignment padding for the next value in the message (if there is one) starts after the trailing nul.

For example, if the current position is a multiple of 8 bytes from the beginning of a little-endian message, strings "foo", "+" and "bar" would be serialized in sequence as follows:

                                         # no padding required, we are already at a multiple of 4
0x03 0x00 0x00 0x00                      # length of "foo" = 3
                    0x66 0x6f 0x6f       # "foo"
                                   0x00  # trailing nul

                                         # no padding required, we are already at a multiple of 4
0x01 0x00 0x00 0x00                      # length of "+" = 1
                    0x2b                 # "+"
                         0x00            # trailing nul

                               0x00 0x00 # 2 bytes of padding to reach next multiple of 4
0x03 0x00 0x00 0x00                      # length of "bar" = 1
                    0x62 0x61 0x72       # "bar"
                                    0x00 # trailing nul

Created attachment 120606 [details] [review]
spec: Clarify the marshaling format in a few minor ways

This is an attempt to make that section a little clearer. I don’t think
any factual inaccuracies have been fixed (because I couldn’t find any).

Including some wording and an example by Simon McVittie
<smcv@debian.org>.

Looks good, will apply soon.

Please change "review-" to "review?" in the "status whiteboard" when you believe you have fixed all negative review points and would like a patch re-reviewed. I normally assume that bugs still marked "review-" are waiting for a response from the patch submitter.

Fixed in git for 1.11.4 (spec 0.28), thanks.