aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_interface/doc
diff options
context:
space:
mode:
authorSverker Eriksson <[email protected]>2019-04-26 19:43:53 +0200
committerSverker Eriksson <[email protected]>2019-04-26 19:43:53 +0200
commit01aa8b82dd0f8229355ffd2bb2bc8e8f496d2df6 (patch)
tree0a3ae48dfe7f442aa138d7c06fbf5444e9f7c8b6 /lib/erl_interface/doc
parent8f6d45ddc8b2b12376c252a30b267a822cad171a (diff)
downloadotp-01aa8b82dd0f8229355ffd2bb2bc8e8f496d2df6.tar.gz
otp-01aa8b82dd0f8229355ffd2bb2bc8e8f496d2df6.tar.bz2
otp-01aa8b82dd0f8229355ffd2bb2bc8e8f496d2df6.zip
erl_interface: Tweak bit string encode/decode API
to support zero copy decoding and bit offset arguments for future unaligned bit strings.
Diffstat (limited to 'lib/erl_interface/doc')
-rw-r--r--lib/erl_interface/doc/src/ei.xml60
1 files changed, 39 insertions, 21 deletions
diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml
index 254ae27cc8..7808bfd94f 100644
--- a/lib/erl_interface/doc/src/ei.xml
+++ b/lib/erl_interface/doc/src/ei.xml
@@ -183,28 +183,36 @@ typedef enum {
</func>
<func>
- <name since="OTP @OTP-15712@"><ret>int</ret><nametext>ei_decode_bitstring(const char *buf, int *index, void *p, size_t plen, size_t *bitsp)</nametext></name>
+ <name since="OTP @OTP-15712@"><ret>int</ret><nametext>ei_decode_bitstring(const char *buf, int *index, const char **pp, unsigned int *bitoffsp, size_t *nbitsp)</nametext></name>
<fsummary>Decode a bitstring.</fsummary>
<desc>
- <p>Decodes a bitstring from the binary format.</p>
+ <p>Decodes a bit string from the binary format.</p>
<taglist>
- <tag><c>p</c></tag>
- <item><p>Either <c>NULL</c> or points to a buffer where the bytes of the
- bitstring will be written.</p>
+ <tag><c>pp</c></tag>
+ <item><p>Either <c>NULL</c> or <c>*pp</c> returns a pointer to
+ the first byte of the bit string. The returned bit string is
+ readable as long as the buffer pointed to by <c>buf</c> is
+ readable and not written to.</p>
</item>
- <tag><c>plen</c></tag>
- <item><p>The max size of the bitstring in <em>bytes</em>, that is the
- size of the buffer if <c>p != NULL</c>.</p>
+ <tag><c>bitoffsp</c></tag>
+ <item><p>Either <c>NULL</c> or <c>*bitoffsp</c> returns the
+ number of unused bits in the first byte pointed to by
+ <c>*pp</c>. The value of <c>*bitoffsp</c> is between 0 and 7.
+ Unused bits in the first byte are the most significant bits.</p>
</item>
- <tag><c>*bitsp</c></tag>
- <item><p>If <c>bitsp</c> is not <c>NULL</c>, set to the actual
- number of <em>bits</em> of the bitstring.</p>
+ <tag><c>nbitsp</c></tag>
+ <item><p>Either <c>NULL</c> or <c>*nbitsp</c> returns the length
+ of the bit string in <em>bits</em>.</p>
</item>
</taglist>
- <p>Returns <c>0</c> if it was a bitstring no longer than <c>plen</c>
- bytes. The actual length of the bitstring will be
- <c>(*bitsp+7)/8</c> bytes. If <c>(*bitsp % 8) > 0</c> only the high
- <c>(*bitsp % 8)</c> bits of the last byte are significant.</p>
+ <p>Returns <c>0</c> if it was a bit string term.</p>
+ <p>The number of <em>bytes</em> pointed to by <c>*pp</c>, which are
+ part of the bit string, is <c>(*bitoffsp + *nbitsp + 7)/8</c>. If
+ <c>(*bitoffsp + *bitsp)%8 > 0</c> then only <c>(*bitoffsp +
+ *bitsp)%8</c> bits of the last byte are used. Unused bits in
+ the last byte are the least significant bits.</p>
+ <p>The values of unused bits in the first and last byte are undefined
+ and cannot be relied on.</p>
<p>Number of bits may be divisible by 8, which means a binary
decodable by <c>ei_decode_binary</c> is also decodable by
<c>ei_decode_bitstring</c>.</p>
@@ -490,14 +498,24 @@ typedef enum {
</func>
<func>
- <name since="OTP @OTP-15712@"><ret>int</ret><nametext>ei_encode_bitstring(char *buf, int *index, const void *p, size_t bits)</nametext></name>
- <name since="OTP @OTP-15712@"><ret>int</ret><nametext>ei_x_encode_bitstring(ei_x_buff* x, const void *p, size_t bits)</nametext></name>
+ <name since="OTP @OTP-15712@"><ret>int</ret>
+ <nametext>ei_encode_bitstring(char *buf, int *index, const char *p, size_t bitoffs, size_t nbits)</nametext></name>
+ <name since="OTP @OTP-15712@"><ret>int</ret>
+ <nametext>ei_x_encode_bitstring(ei_x_buff* x, const char *p, size_t bitoffs, size_t nbits)</nametext></name>
<fsummary>Encode a bitstring.</fsummary>
<desc>
- <p>Encodes a bitstring in the binary format. The data is at
- <c>p</c>. The size of the data is <c>bits</c> bits or
- <c>(bits+7)/8</c> bytes. If <c>(bits%8) > 0</c> only the high
- <c>(bits%8)</c> bits of the last byte are significant.</p>
+ <p>Encodes a bit string in the binary format.</p>
+ <p>The data is at <c>p</c>. The length of the bit string is <c>nbits</c>
+ bits. The first <c>bitoffs</c> bits of the data at <c>p</c> are unused.
+ The first byte which is part of the bit string is
+ <c>p[bitoffs/8]</c>. The <c>bitoffs%8</c> most significant bits of
+ the first byte <c>p[bitoffs/8]</c> are unused.</p>
+ <p>The number of bytes which is part of the bit string is <c>(bitoffs +
+ nbits + 7)/8</c>. If <c>(bitoffs + nbits)%8 > 0</c> then only <c>(bitoffs +
+ nbits)%8</c> bits of the last byte are used. Unused bits in
+ the last byte are the least significant bits.</p>
+ <p>The values of unused bits are disregarded and does not need to be
+ cleared.</p>
</desc>
</func>