From 9f5b69e8def226f1d1ce9262477d5bbd1cbc1fe7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Mon, 17 Oct 2016 15:07:55 +0200 Subject: erl_interface: Refactor documentation --- lib/erl_interface/doc/src/ei.xml | 869 ++++++++++++++++++++------------------- 1 file changed, 435 insertions(+), 434 deletions(-) (limited to 'lib/erl_interface/doc/src/ei.xml') diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml index 1177954eb9..7928e4f5d1 100644 --- a/lib/erl_interface/doc/src/ei.xml +++ b/lib/erl_interface/doc/src/ei.xml @@ -11,7 +11,7 @@ Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software @@ -30,7 +30,7 @@ 2000-11-27 PA1 - ei.sgml + ei.xml ei routines for handling the erlang binary term format @@ -106,149 +106,265 @@ typedef enum { + + intei_decode_atom(const char *buf, int *index, char *p) + Decode an atom. + +

This function decodes an atom from the binary format. The + null terminated name of the atom is placed at . There can be at most + bytes placed in the buffer.

+ + + + intei_decode_atom_as(const char *buf, int *index, char *p, int plen, erlang_char_encoding want, erlang_char_encoding* was, erlang_char_encoding* result) + Decode an atom. + +

This function decodes an atom from the binary format. The + null terminated name of the atom is placed in buffer at p of length + plen bytes.

+

The wanted string encoding is specified by + want. The original encoding used in the + binary format (latin1 or utf8) can be obtained from *was. The actual encoding of the resulting string + (7-bit ascii, latin1 or utf8) can be obtained from *result. Both was and result can be NULL. + + *result may differ from want if want is a bitwise-or'd combination like + ERLANG_LATIN1|ERLANG_UTF8 or if *result turn out to be pure 7-bit ascii + (compatible with both latin1 and utf8).

+

This function fails if the atom is too long for the buffer + or if it can not be represented with encoding want.

+

This function was introduced in R16 release of Erlang/OTP as part of a first step + to support UTF8 atoms.

+ + + + intei_decode_bignum(const char *buf, int *index, mpz_t obj) + Decode a GMP arbitrary precision integer. + +

This function decodes an integer in the binary format to a GMP integer. + To use this function the ei library needs to be configured and compiled + to use the GMP library.

+ + + + intei_decode_binary(const char *buf, int *index, void *p, long *len) + Decode a binary. + +

This function decodes a binary from the binary format. The + parameter is set to the actual size of the + binary. Note that assumes that there + are enough room for the binary. The size required can be + fetched by .

+ + + + intei_decode_boolean(const char *buf, int *index, int *p) + Decode a boolean. + +

This function decodes a boolean value from the binary + format. A boolean is actually an atom, decodes 1 + and decodes 0.

+ + + + intei_decode_char(const char *buf, int *index, char *p) + Decode an 8-bit integer between 0-255. + +

This function decodes a char (8-bit) integer between 0-255 + from the binary format. + Note that for historical reasons the returned integer is of + type . Your C code should consider the + returned value to be of type even if + the C compilers and system may define to be + signed.

+ + + + intei_decode_double(const char *buf, int *index, double *p) + Decode a double. + +

This function decodes an double-precision (64 bit) floating + point number from the binary format.

+ + - voidei_set_compat_rel(release_number) - Set the ei library in compatibility mode - - unsigned release_number; - + intei_decode_ei_term(const char* buf, int* index, ei_term* term) + Decode a term, without prior knowledge of type. - -

By default, the library is only guaranteed - to be compatible with other Erlang/OTP components from the same - release as the library itself. For example, from - the OTP R10 release is not compatible with an Erlang emulator - from the OTP R9 release by default.

-

A call to sets the - library in compatibility mode of release - . Valid range of - is [7, current release]. This makes it possible to - communicate with Erlang/OTP components from earlier releases.

- -

If this function is called, it may only be called once - and must be called before any other functions in the - library is called.

- - -

You may run into trouble if this feature is used - carelessly. Always make sure that all communicating - components are either from the same Erlang/OTP release, or - from release X and release Y where all components - from release Y are in compatibility mode of release X.

- +

This function decodes any term, or at least tries to. If the + term pointed at by in fits in the + union, it is decoded, and the appropriate field + in value]]> is set, and is + incremented by the term size.

+

The function returns 1 on successful decoding, -1 on error, + and 0 if the term seems alright, but does not fit in the + structure. If it returns 1, the + will be incremented, and the contains the + decoded term.

+

The structure will contain the arity for a tuple + or list, size for a binary, string or atom. It will contains + a term if it's any of the following: integer, float, atom, + pid, port or ref.

 - intei_encode_version(char *buf, int *index) - intei_x_encode_version(ei_x_buff* x) - Encode version + intei_decode_fun(const char *buf, int *index, erlang_fun *p) + voidfree_fun(erlang_fun* f) + Decode a fun. -

Encodes a version magic number for the binary format. Must - be the first token in a binary term.

+

This function decodes a fun from the binary format. The + parameter should be NULL or point to an + structure. This is the only decode + function that allocates memory; when the + is no longer needed, it should be freed with + . (This has to do with the arbitrary size of + the environment for a fun.)

 - intei_encode_long(char *buf, int *index, long p) - intei_x_encode_long(ei_x_buff* x, long p) - Encode integer + intei_decode_list_header(const char *buf, int *index, int *arity) + Decode a list. -

Encodes a long integer in the binary format. - Note that if the code is 64 bits the function ei_encode_long() is - exactly the same as ei_encode_longlong().

+

This function decodes a list header from the binary + format. The number of elements is returned in + . The elements follows (the last + one is the tail of the list, normally an empty list.) If + is , it's an empty list.

+

Note that lists are encoded as strings, if they consist + entirely of integers in the range 0..255. This function will + not decode such strings, use + instead.

 - intei_encode_ulong(char *buf, int *index, unsigned long p) - intei_x_encode_ulong(ei_x_buff* x, unsigned long p) - Encode unsigned integer + intei_decode_long(const char *buf, int *index, long *p) + Decode integer. -

Encodes an unsigned long integer in the binary format. - Note that if the code is 64 bits the function ei_encode_ulong() is - exactly the same as ei_encode_ulonglong().

+

This function decodes a long integer from the binary format. + Note that if the code is 64 bits the function ei_decode_long() is + exactly the same as ei_decode_longlong().

 - intei_encode_longlong(char *buf, int *index, long long p) - intei_x_encode_longlong(ei_x_buff* x, long long p) - Encode integer + intei_decode_longlong(const char *buf, int *index, long long *p) + Decode integer. -

Encodes a GCC or Visual C++ (64 bit) - integer in the binary format. Note that this function is missing - in the VxWorks port.

+

This function decodes a GCC or Visual C++ + (64 bit) integer from the binary format. Note that this + function is missing in the VxWorks port.

 - intei_encode_ulonglong(char *buf, int *index, unsigned long long p) - intei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p) - Encode unsigned integer + intei_decode_map_header(const char *buf, int *index, int *arity) + Decode a map. -

Encodes a GCC or Visual C++ (64 bit) integer in the binary format. Note that - this function is missing in the VxWorks port.

+

This function decodes a map header from the binary + format. The number of key-value pairs is returned in + *arity. Keys and values follow in the following order: + K1, V1, K2, V2, ..., Kn, Vn. This makes a total of + arity*2 terms. If arity is zero, it's an empty map. + A correctly encoded map does not have duplicate keys.

 - intei_encode_bignum(char *buf, int *index, mpz_t obj) - intei_x_encode_bignum(ei_x_buff *x, mpz_t obj) - Encode an arbitrary precision integer + intei_decode_pid(const char *buf, int *index, erlang_pid *p) + Decode a . -

Encodes a GMP integer to binary format. - To use this function the ei library needs to be configured and compiled - to use the GMP library.

+

Decodes a pid, process identifier, from the binary format.

 - intei_encode_double(char *buf, int *index, double p) - intei_x_encode_double(ei_x_buff* x, double p) - Encode a double float + intei_decode_port(const char *buf, int *index, erlang_port *p) + Decode a port. -

Encodes a double-precision (64 bit) floating point number in - the binary format.

-

- The function returns if the floating point number is not finite. -

+

This function decodes a port identifier from the binary + format.

 - intei_encode_boolean(char *buf, int *index, int p) - intei_x_encode_boolean(ei_x_buff* x, int p) - Encode a boolean + intei_decode_ref(const char *buf, int *index, erlang_ref *p) + Decode a reference. -

Encodes a boolean value, as the atom if p is not - zero or if p is zero.

+

This function decodes a reference from the binary format.

 - intei_encode_char(char *buf, int *index, char p) - intei_x_encode_char(ei_x_buff* x, char p) - Encode an 8-bit integer between 0-255 + intei_decode_string(const char *buf, int *index, char *p) + Decode a string. -

Encodes a char (8-bit) as an integer between 0-255 in the binary format. - Note that for historical reasons the integer argument is of - type . Your C code should consider the - given argument to be of type even if - the C compilers and system may define to be - signed.

+

This function decodes a string from the binary format. A + string in erlang is a list of integers between 0 and + 255. Note that since the string is just a list, sometimes + lists are encoded as strings by , + even if it was not intended.

+

The string is copied to , and enough space must be + allocated. The returned string is null terminated so you + need to add an extra byte to the memory requirement.

 - intei_encode_string(char *buf, int *index, const char *p) - intei_encode_string_len(char *buf, int *index, const char *p, int len) - intei_x_encode_string(ei_x_buff* x, const char *p) - intei_x_encode_string_len(ei_x_buff* x, const char* s, int len) - Encode a string + intei_decode_term(const char *buf, int *index, void *t) + Decode a . -

Encodes a string in the binary format. (A string in erlang - is a list, but is encoded as a character array in the binary - format.) The string should be zero-terminated, except for - the function.

+

This function decodes a term from the binary format. The + term is return in as a , so + is actually an (see + . The term should later be + deallocated.

+

Note that this function is located in the erl_interface + library.

+ + + + intei_decode_trace(const char *buf, int *index, erlang_trace *p) + Decode a trace token. + +

Decodes an erlang trace token from the binary format.

+ + + + intei_decode_tuple_header(const char *buf, int *index, int *arity) + Decode a tuple. + +

This function decodes a tuple header, the number of elements + is returned in . The tuple elements follows in order in + the buffer.

+ + + + intei_decode_ulong(const char *buf, int *index, unsigned long *p) + Decode unsigned integer. + +

This function decodes an unsigned long integer from + the binary format. + Note that if the code is 64 bits the function ei_decode_ulong() is + exactly the same as ei_decode_ulonglong().

+ + + + intei_decode_ulonglong(const char *buf, int *index, unsigned long long *p) + Decode unsigned integer. + +

This function decodes a GCC or Visual C++ + (64 bit) integer from the binary format. + Note that this function is missing in the VxWorks port.

+ + + + intei_decode_version(const char *buf, int *index, int *version) + Encode an empty list (). + +

This function decodes the version magic number for the + erlang binary term format. It must be the first token in a + binary term.

 + intei_encode_atom(char *buf, int *index, const char *p) intei_encode_atom_len(char *buf, int *index, const char *p, int len) intei_x_encode_atom(ei_x_buff* x, const char *p) intei_x_encode_atom_len(ei_x_buff* x, const char *p, int len) - Encode an atom + Encode an atom.

Encodes an atom in the binary format. The parameter is the name of the atom in latin1 encoding. Only upto MAXATOMLEN-1 bytes @@ -261,7 +377,7 @@ typedef enum { intei_encode_atom_len_as(char *buf, int *index, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc) intei_x_encode_atom_as(ei_x_buff* x, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc) intei_x_encode_atom_len_as(ei_x_buff* x, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc) - Encode an atom + Encode an atom.

Encodes an atom in the binary format with character encoding to_enc (latin1 or utf8). @@ -278,106 +394,84 @@ typedef enum { can not be decoded by earlier releases than R16.

 + + intei_encode_bignum(char *buf, int *index, mpz_t obj) + intei_x_encode_bignum(ei_x_buff *x, mpz_t obj) + Encode an arbitrary precision integer. + +

Encodes a GMP integer to binary format. + To use this function the ei library needs to be configured and compiled + to use the GMP library.

+ + intei_encode_binary(char *buf, int *index, const void *p, long len) intei_x_encode_binary(ei_x_buff* x, const void *p, long len) - Encode a binary + Encode a binary.

Encodes a binary in the binary format. The data is at , of bytes length.

 - intei_encode_pid(char *buf, int *index, const erlang_pid *p) - intei_x_encode_pid(ei_x_buff* x, const erlang_pid *p) - Encode a pid + intei_encode_boolean(char *buf, int *index, int p) + intei_x_encode_boolean(ei_x_buff* x, int p) + Encode a boolean. -

Encodes an erlang process identifier, pid, in the binary - format. The parameter points to an - structure (which should have been obtained - earlier with ).

+

Encodes a boolean value, as the atom if p is not + zero or if p is zero.

 - intei_encode_fun(char *buf, int *index, const erlang_fun *p) - intei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun) - Encode a fun + intei_encode_char(char *buf, int *index, char p) + intei_x_encode_char(ei_x_buff* x, char p) + Encode an 8-bit integer between 0-255. -

Encodes a fun in the binary format. The parameter - points to an structure. The - is not freed automatically, the - should be called if the fun is not needed - after encoding.

+

Encodes a char (8-bit) as an integer between 0-255 in the binary format. + Note that for historical reasons the integer argument is of + type . Your C code should consider the + given argument to be of type even if + the C compilers and system may define to be + signed.

 - intei_encode_port(char *buf, int *index, const erlang_port *p) - intei_x_encode_port(ei_x_buff* x, const erlang_port *p) - Encodes a port + intei_encode_double(char *buf, int *index, double p) + intei_x_encode_double(ei_x_buff* x, double p) + Encode a double float. -

Encodes an erlang port in the binary format. The - parameter points to a structure (which - should have been obtained earlier with - .

+

Encodes a double-precision (64 bit) floating point number in + the binary format.

+

+ The function returns if the floating point number is not finite. +

- intei_encode_ref(char *buf, int *index, const erlang_ref *p) - intei_x_encode_ref(ei_x_buff* x, const erlang_ref *p) - Encodes a ref + intei_encode_empty_list(char* buf, int* index) + intei_x_encode_empty_list(ei_x_buff* x) + Encode an empty list (). -

Encodes an erlang reference in the binary format. The - parameter points to a structure - (which should have been obtained earlier with - .

+

This function encodes an empty list. It's often used at the + tail of a list.

 - intei_encode_term(char *buf, int *index, void *t) - intei_x_encode_term(ei_x_buff* x, void *t) - Encode an term - -

This function encodes an , as obtained from - . The parameter is actually an - pointer. This function doesn't free the - .

- - - - intei_encode_trace(char *buf, int *index, const erlang_trace *p) - intei_x_encode_trace(ei_x_buff* x, const erlang_trace *p) - Encode a trace token - -

This function encodes an erlang trace token in the binary - format. The parameter points to a - structure (which should have been - obtained earlier with .

- - - - intei_encode_tuple_header(char *buf, int *index, int arity) - intei_x_encode_tuple_header(ei_x_buff* x, int arity) - Encode a tuple + intei_encode_fun(char *buf, int *index, const erlang_fun *p) + intei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun) + Encode a fun. -

This function encodes a tuple header, with a specified - arity. The next terms encoded will be the - elements of the tuple. Tuples and lists are encoded - recursively, so that a tuple may contain another tuple or - list.

-

E.g. to encode the tuple :

- 
-ei_encode_tuple_header(buf, &i, 2);
-ei_encode_atom(buf, &i, "a");
-ei_encode_tuple_header(buf, &i, 2);
-ei_encode_atom(buf, &i, "b");
-ei_encode_tuple_header(buf, &i, 0);
-
+

Encodes a fun in the binary format. The parameter + points to an structure. The + is not freed automatically, the + should be called if the fun is not needed + after encoding.

 intei_encode_list_header(char *buf, int *index, int arity) intei_x_encode_list_header(ei_x_buff* x, int arity) - Encode a list + Encode a list.

This function encodes a list header, with a specified arity. The next terms are the elements @@ -412,18 +506,29 @@ ei_x_encode_empty_list(&x); - intei_encode_empty_list(char* buf, int* index) - intei_x_encode_empty_list(ei_x_buff* x) - Encode an empty list () + intei_encode_long(char *buf, int *index, long p) + intei_x_encode_long(ei_x_buff* x, long p) + Encode integer. -

This function encodes an empty list. It's often used at the - tail of a list.

+

Encodes a long integer in the binary format. + Note that if the code is 64 bits the function ei_encode_long() is + exactly the same as ei_encode_longlong().

+ + + + intei_encode_longlong(char *buf, int *index, long long p) + intei_x_encode_longlong(ei_x_buff* x, long long p) + Encode integer. + +

Encodes a GCC or Visual C++ (64 bit) + integer in the binary format. Note that this function is missing + in the VxWorks port.

 intei_encode_map_header(char *buf, int *index, int arity) intei_x_encode_map_header(ei_x_buff* x, int arity) - Encode a map + Encode a map.

This function encodes a map header, with a specified arity. The next arity*2 terms encoded will be the keys and values of the map @@ -441,275 +546,139 @@ ei_x_encode_string(&x, "Banana"); - intei_get_type(const char *buf, const int *index, int *type, int *size) - Fetch the type and size of an encoded term - -

This function returns the type in and size in - of the encoded term. - For strings and atoms, size - is the number of characters not including the - terminating 0. For binaries, is the number of - bytes. For lists and tuples, is the arity of the - object. For other types, is 0. In all cases, - is left unchanged.

- - - - intei_decode_version(const char *buf, int *index, int *version) - Encode an empty list () - -

This function decodes the version magic number for the - erlang binary term format. It must be the first token in a - binary term.

- - - - intei_decode_long(const char *buf, int *index, long *p) - Decode integer - -

This function decodes a long integer from the binary format. - Note that if the code is 64 bits the function ei_decode_long() is - exactly the same as ei_decode_longlong().

- - - - intei_decode_ulong(const char *buf, int *index, unsigned long *p) - Decode unsigned integer - -

This function decodes an unsigned long integer from - the binary format. - Note that if the code is 64 bits the function ei_decode_ulong() is - exactly the same as ei_decode_ulonglong().

- - - - intei_decode_longlong(const char *buf, int *index, long long *p) - Decode integer - -

This function decodes a GCC or Visual C++ - (64 bit) integer from the binary format. Note that this - function is missing in the VxWorks port.

- - - - intei_decode_ulonglong(const char *buf, int *index, unsigned long long *p) - Decode unsigned integer - -

This function decodes a GCC or Visual C++ - (64 bit) integer from the binary format. - Note that this function is missing in the VxWorks port.

- - - - intei_decode_bignum(const char *buf, int *index, mpz_t obj) - Decode a GMP arbitrary precision integer - -

This function decodes an integer in the binary format to a GMP integer. - To use this function the ei library needs to be configured and compiled - to use the GMP library.

- - - - intei_decode_double(const char *buf, int *index, double *p) - Decode a double - -

This function decodes an double-precision (64 bit) floating - point number from the binary format.

- - - - intei_decode_boolean(const char *buf, int *index, int *p) - Decode a boolean - -

This function decodes a boolean value from the binary - format. A boolean is actually an atom, decodes 1 - and decodes 0.

- - - - intei_decode_char(const char *buf, int *index, char *p) - Decode an 8-bit integer between 0-255 - -

This function decodes a char (8-bit) integer between 0-255 - from the binary format. - Note that for historical reasons the returned integer is of - type . Your C code should consider the - returned value to be of type even if - the C compilers and system may define to be - signed.

- - - - intei_decode_string(const char *buf, int *index, char *p) - Decode a string - -

This function decodes a string from the binary format. A - string in erlang is a list of integers between 0 and - 255. Note that since the string is just a list, sometimes - lists are encoded as strings by , - even if it was not intended.

-

The string is copied to , and enough space must be - allocated. The returned string is null terminated so you - need to add an extra byte to the memory requirement.

- - - - intei_decode_atom(const char *buf, int *index, char *p) - Decode an atom - -

This function decodes an atom from the binary format. The - null terminated name of the atom is placed at . There can be at most - bytes placed in the buffer.

- - - - intei_decode_atom_as(const char *buf, int *index, char *p, int plen, erlang_char_encoding want, erlang_char_encoding* was, erlang_char_encoding* result) - Decode an atom - -

This function decodes an atom from the binary format. The - null terminated name of the atom is placed in buffer at p of length - plen bytes.

-

The wanted string encoding is specified by - want. The original encoding used in the - binary format (latin1 or utf8) can be obtained from *was. The actual encoding of the resulting string - (7-bit ascii, latin1 or utf8) can be obtained from *result. Both was and result can be NULL. - - *result may differ from want if want is a bitwise-or'd combination like - ERLANG_LATIN1|ERLANG_UTF8 or if *result turn out to be pure 7-bit ascii - (compatible with both latin1 and utf8).

-

This function fails if the atom is too long for the buffer - or if it can not be represented with encoding want.

-

This function was introduced in R16 release of Erlang/OTP as part of a first step - to support UTF8 atoms.

- - - - intei_decode_binary(const char *buf, int *index, void *p, long *len) - Decode a binary + intei_encode_pid(char *buf, int *index, const erlang_pid *p) + intei_x_encode_pid(ei_x_buff* x, const erlang_pid *p) + Encode a pid. -

This function decodes a binary from the binary format. The - parameter is set to the actual size of the - binary. Note that assumes that there - are enough room for the binary. The size required can be - fetched by .

+

Encodes an erlang process identifier, pid, in the binary + format. The parameter points to an + structure (which should have been obtained + earlier with ).

 - intei_decode_fun(const char *buf, int *index, erlang_fun *p) - voidfree_fun(erlang_fun* f) - Decode a fun + intei_encode_port(char *buf, int *index, const erlang_port *p) + intei_x_encode_port(ei_x_buff* x, const erlang_port *p) + Encodes a port. -

This function decodes a fun from the binary format. The - parameter should be NULL or point to an - structure. This is the only decode - function that allocates memory; when the - is no longer needed, it should be freed with - . (This has to do with the arbitrary size of - the environment for a fun.)

+

Encodes an erlang port in the binary format. The + parameter points to a structure (which + should have been obtained earlier with + .

 - intei_decode_pid(const char *buf, int *index, erlang_pid *p) - Decode a + intei_encode_ref(char *buf, int *index, const erlang_ref *p) + intei_x_encode_ref(ei_x_buff* x, const erlang_ref *p) + Encodes a ref. -

Decodes a pid, process identifier, from the binary format.

+

Encodes an erlang reference in the binary format. The + parameter points to a structure + (which should have been obtained earlier with + .

 - intei_decode_port(const char *buf, int *index, erlang_port *p) - Decode a port + intei_encode_string(char *buf, int *index, const char *p) + intei_encode_string_len(char *buf, int *index, const char *p, int len) + intei_x_encode_string(ei_x_buff* x, const char *p) + intei_x_encode_string_len(ei_x_buff* x, const char* s, int len) + Encode a string. -

This function decodes a port identifier from the binary - format.

+

Encodes a string in the binary format. (A string in erlang + is a list, but is encoded as a character array in the binary + format.) The string should be zero-terminated, except for + the function.

 - intei_decode_ref(const char *buf, int *index, erlang_ref *p) - Decode a reference + intei_encode_term(char *buf, int *index, void *t) + intei_x_encode_term(ei_x_buff* x, void *t) + Encode an term. -

This function decodes a reference from the binary format.

+

This function encodes an , as obtained from + . The parameter is actually an + pointer. This function doesn't free the + .

 - intei_decode_trace(const char *buf, int *index, erlang_trace *p) - Decode a trace token + intei_encode_trace(char *buf, int *index, const erlang_trace *p) + intei_x_encode_trace(ei_x_buff* x, const erlang_trace *p) + Encode a trace token. -

Decodes an erlang trace token from the binary format.

+

This function encodes an erlang trace token in the binary + format. The parameter points to a + structure (which should have been + obtained earlier with .

 - intei_decode_tuple_header(const char *buf, int *index, int *arity) - Decode a tuple + intei_encode_tuple_header(char *buf, int *index, int arity) + intei_x_encode_tuple_header(ei_x_buff* x, int arity) + Encode a tuple. -

This function decodes a tuple header, the number of elements - is returned in . The tuple elements follows in order in - the buffer.

+

This function encodes a tuple header, with a specified + arity. The next terms encoded will be the + elements of the tuple. Tuples and lists are encoded + recursively, so that a tuple may contain another tuple or + list.

+

E.g. to encode the tuple :

+ 
+ei_encode_tuple_header(buf, &i, 2);
+ei_encode_atom(buf, &i, "a");
+ei_encode_tuple_header(buf, &i, 2);
+ei_encode_atom(buf, &i, "b");
+ei_encode_tuple_header(buf, &i, 0);
+
- intei_decode_list_header(const char *buf, int *index, int *arity) - Decode a list + intei_encode_ulong(char *buf, int *index, unsigned long p) + intei_x_encode_ulong(ei_x_buff* x, unsigned long p) + Encode unsigned integer. -

This function decodes a list header from the binary - format. The number of elements is returned in - . The elements follows (the last - one is the tail of the list, normally an empty list.) If - is , it's an empty list.

-

Note that lists are encoded as strings, if they consist - entirely of integers in the range 0..255. This function will - not decode such strings, use - instead.

+

Encodes an unsigned long integer in the binary format. + Note that if the code is 64 bits the function ei_encode_ulong() is + exactly the same as ei_encode_ulonglong().

 - intei_decode_map_header(const char *buf, int *index, int *arity) - Decode a map + intei_encode_ulonglong(char *buf, int *index, unsigned long long p) + intei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p) + Encode unsigned integer. -

This function decodes a map header from the binary - format. The number of key-value pairs is returned in - *arity. Keys and values follow in the following order: - K1, V1, K2, V2, ..., Kn, Vn. This makes a total of - arity*2 terms. If arity is zero, it's an empty map. - A correctly encoded map does not have duplicate keys.

+

Encodes a GCC or Visual C++ (64 bit) integer in the binary format. Note that + this function is missing in the VxWorks port.

 - intei_decode_ei_term(const char* buf, int* index, ei_term* term) - Decode a term, without prior knowledge of type + intei_encode_version(char *buf, int *index) + intei_x_encode_version(ei_x_buff* x) + Encode version. -

This function decodes any term, or at least tries to. If the - term pointed at by in fits in the - union, it is decoded, and the appropriate field - in value]]> is set, and is - incremented by the term size.

-

The function returns 1 on successful decoding, -1 on error, - and 0 if the term seems alright, but does not fit in the - structure. If it returns 1, the - will be incremented, and the contains the - decoded term.

-

The structure will contain the arity for a tuple - or list, size for a binary, string or atom. It will contains - a term if it's any of the following: integer, float, atom, - pid, port or ref.

+

Encodes a version magic number for the binary format. Must + be the first token in a binary term.

 - intei_decode_term(const char *buf, int *index, void *t) - Decode a + intei_get_type(const char *buf, const int *index, int *type, int *size) + Fetch the type and size of an encoded term. -

This function decodes a term from the binary format. The - term is return in as a , so - is actually an (see - . The term should later be - deallocated.

-

Note that this function is located in the erl_interface - library.

+

This function returns the type in and size in + of the encoded term. + For strings and atoms, size + is the number of characters not including the + terminating 0. For binaries, is the number of + bytes. For lists and tuples, is the arity of the + object. For other types, is 0. In all cases, + is left unchanged.

 intei_print_term(FILE* fp, const char* buf, int* index) intei_s_print_term(char** s, const char* buf, int* index) - Print a term in clear text + Print a term in clear text.

This function prints a term, in clear text, to the file given by , or the buffer pointed to by . It @@ -729,6 +698,67 @@ ei_x_encode_string(&x, "Banana"); human readable format.

 + + voidei_set_compat_rel(release_number) + Set the ei library in compatibility mode. + + unsigned release_number; + + + +

By default, the library is only guaranteed + to be compatible with other Erlang/OTP components from the same + release as the library itself. For example, from + the OTP R10 release is not compatible with an Erlang emulator + from the OTP R9 release by default.

+

A call to sets the + library in compatibility mode of release + . Valid range of + is [7, current release]. This makes it possible to + communicate with Erlang/OTP components from earlier releases.

+ +

If this function is called, it may only be called once + and must be called before any other functions in the + library is called.

+ + +

You may run into trouble if this feature is used + carelessly. Always make sure that all communicating + components are either from the same Erlang/OTP release, or + from release X and release Y where all components + from release Y are in compatibility mode of release X.

+ + + + + intei_skip_term(const char* buf, int* index) + skip a term. + +

This function skips a term in the given buffer, it + recursively skips elements of lists and tuples, so that a + full term is skipped. This is a way to get the size of an + erlang term.

+

is the buffer.

+

is updated to point right after the term in the + buffer.

+ +

This can be useful when you want to hold arbitrary + terms: just skip them and copy the binary term data to some + buffer.

+ +

The function returns on success and on + failure.

+ + + + intei_x_append(ei_x_buff* x, const ei_x_buff* x2) + intei_x_append_buf(ei_x_buff* x, const char* buf, int len) + Appends a buffer at the end. + +

These functions appends data at the end of the buffer .

+ + + intei_x_format(ei_x_buff* x, const char* fmt, ...) intei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... ) @@ -760,10 +790,18 @@ encodes the tuple {numbers,12,3.14159} the initial version byte.

 + + intei_x_free(ei_x_buff* x) + Frees a buffer. + +

This function frees an buffer. The memory + used by the buffer is returned to the OS.

+ + intei_x_new(ei_x_buff* x) intei_x_new_with_version(ei_x_buff* x) - Allocate a new buffer + Allocate a new buffer.

This function allocates a new buffer. The fields of the structure pointed to by parameter is @@ -773,43 +811,7 @@ encodes the tuple {numbers,12,3.14159} won't be needed.)

 - - intei_x_free(ei_x_buff* x) - Frees a buffer - -

This function frees an buffer. The memory - used by the buffer is returned to the OS.

- - - - intei_x_append(ei_x_buff* x, const ei_x_buff* x2) - intei_x_append_buf(ei_x_buff* x, const char* buf, int len) - Appends a buffer at the end - -

These functions appends data at the end of the buffer .

- - - - intei_skip_term(const char* buf, int* index) - skip a term - -

This function skips a term in the given buffer, it - recursively skips elements of lists and tuples, so that a - full term is skipped. This is a way to get the size of an - erlang term.

-

is the buffer.

-

is updated to point right after the term in the - buffer.

- -

This can be useful when you want to hold arbitrary - terms: just skip them and copy the binary term data to some - buffer.

- -

The function returns on success and on - failure.

- - - +
Debug Information @@ -828,4 +830,3 @@ encodes the tuple {numbers,12,3.14159}

erl_interface(3)

- -- cgit v1.2.3