diff options
Diffstat (limited to 'lib/erl_interface/doc/src/ei.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/ei.xml | 60 |
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> |