From 031f9ca91ade7fbb9e31c82545401b8a5531e539 Mon Sep 17 00:00:00 2001 From: xsipewe Date: Thu, 20 Oct 2016 11:46:03 +0200 Subject: erl_interface: Editorial changes --- lib/erl_interface/doc/src/ei.xml | 686 +++++++++++++++++++++------------------ 1 file changed, 378 insertions(+), 308 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 7928e4f5d1..6d416028a5 100644 --- a/lib/erl_interface/doc/src/ei.xml +++ b/lib/erl_interface/doc/src/ei.xml @@ -33,328 +33,368 @@ ei.xml ei - routines for handling the erlang binary term format + Routines for handling the Erlang binary term format.

The library contains macros and functions to encode - and decode the erlang binary term format.

-

With , you can convert atoms, lists, numbers and + and decode the Erlang binary term format.

+ +

allows you to convert atoms, lists, numbers, and binaries to and from the binary format. This is useful when writing port programs and drivers. uses a given - buffer, and no dynamic memory (with the exception of - ), and is often quite fast.

-

It also handles C-nodes, C-programs that talks erlang - distribution with erlang nodes (or other C-nodes) using the - erlang distribution format. The difference between and - is that uses the binary format - directly when sending and receiving terms. It is also thread - safe, and using threads, one process can handle multiple + buffer, no dynamic memory (except + ) and is often quite fast.

+ +

also handles C-nodes, C-programs that talks Erlang + distribution with Erlang nodes (or other C-nodes) using the + Erlang distribution format. The difference between + and is that uses + the binary format directly when sending and receiving terms. It is also + thread safe, and using threads, one process can handle multiple C-nodes. The library is built on top of - , but of legacy reasons, it doesn't allow for multiple - C-nodes. In general, is the preferred way of doing - C-nodes.

-

The decode and encode functions use a buffer an index into the + , but of legacy reasons, it does not allow for + multiple C-nodes. In general, is the preferred way + of doing C-nodes.

+ +

The decode and encode functions use a buffer and an index into the buffer, which points at the point where to encode and decode. The index is updated to point right after the term encoded/decoded. No checking is done whether the term fits in the buffer or not. If encoding goes outside the buffer, the - program may crash.

-

All functions takes two parameter, is a pointer to - the buffer where the binary data is / will be, is a - pointer to an index into the buffer. This parameter will be - incremented with the size of the term decoded / encoded. The - data is thus at when an function is - called.

-

The encode functions all assumes that the and - parameters points to a buffer big enough for the - data. To get the size of an encoded term, without encoding it, - pass instead of a buffer pointer. The - parameter will be incremented, but nothing will be encoded. This + program can crash.

+ +

All functions take two parameters:

+ + +

is a pointer to + the buffer where the binary data is or will be.

+ +

is a pointer to an index into the + buffer. This parameter is incremented with the size of the term + decoded/encoded.

+ + + +

The data is thus at when an + function is called.

+ +

All encode functions assume that the and + parameters point to a buffer large enough for + the data. To get the size of an encoded term, without encoding it, + pass instead of a buffer pointer. Parameter + is incremented, but nothing will be encoded. This is the way in to "preflight" term encoding.

-

There are also encode-functions that uses a dynamic buffer. It + +

There are also encode functions that use a dynamic buffer. It is often more convenient to use these to encode data. All encode - functions comes in two versions: those starting with , - uses a dynamic buffer.

-

All functions return if successful, and if - not. (For instance, if a term is not of the expected type, or - the data to decode is not a valid erlang term.)

-

Some of the decode-functions needs a preallocated buffer. This - buffer must be allocated big enough, and for non compound types + functions comes in two versions; those starting with + use a dynamic buffer.

+ +

All functions return if successful, otherwise + (for example, if a term is not of the expected + type, or the data to decode is an invalid Erlang term).

+ +

Some of the decode functions need a pre-allocated buffer. This + buffer must be allocated large enough, and for non-compound types the - function returns the size required (note that for strings an + function returns the size required (notice that for strings an extra byte is needed for the 0 string terminator).

 -
- DATA TYPES +
+ Data Types erlang_char_encoding -

typedef enum { ERLANG_ASCII = 1, ERLANG_LATIN1 = 2, ERLANG_UTF8 = 4 -}erlang_char_encoding; - -

The character encodings used for atoms. ERLANG_ASCII represents 7-bit ASCII. - Latin1 and UTF8 are different extensions of 7-bit ASCII. All 7-bit ASCII characters - are valid Latin1 and UTF8 characters. ASCII and Latin1 both represent each character - by one byte. A UTF8 character can consist of one to four bytes. Note that these - constants are bit-flags and can be combined with bitwise-or.

+}erlang_char_encoding; +

The character encodings used for atoms. ERLANG_ASCII + represents 7-bit ASCII. Latin-1 and UTF-8 are different extensions + of 7-bit ASCII. All 7-bit ASCII characters are valid Latin-1 and + UTF-8 characters. ASCII and Latin-1 both represent each character + by one byte. An UTF-8 character can consist of 1-4 bytes. + Notice that these + constants are bit-flags and can be combined with bitwise OR.
+ 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.

+

Decodes an atom from the binary format. The NULL-terminated + name of the atom is placed at . At most + bytes can be 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).

+

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 (Latin-1 or UTF-8) can + be obtained from *was. The encoding of the resulting string + (7-bit ASCII, Latin-1, or UTF-8) can be obtained from *result. + Both was and result can be NULL. *result + can differ from want if want is a bitwise OR'd + combination like ERLANG_LATIN1|ERLANG_UTF8 or if + *result turns out to be pure 7-bit ASCII + (compatible with both Latin-1 and UTF-8).

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.

+ or if it cannot be represented with encoding want.

+

This function was introduced in Erlang/OTP R16 as part of a first + step to support UTF-8 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.

+

Decodes an integer in the binary format to a GMP + integer. To use this function, the ei + library must 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 +

Decodes a binary from the binary format. Parameter + is set to the actual size of the + binary. Notice that assumes that + there is 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 +

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 +

Decodes a char (8-bit) integer between 0-255 from the binary format. + For historical reasons the returned integer is of + type . Your C code is to consider the returned value to be of type even if - the C compilers and system may define to be + the C compilers and system can 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 +

Decodes a double-precision (64-bit) floating point number from the binary format.

 + intei_decode_ei_term(const char* buf, int* index, ei_term* term) - Decode a term, without prior knowledge of type. - -

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.

+ Decode a term, without previous knowledge of type. + +

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 1 is returned, the + is incremented, and + contains the decoded term.

+

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

 + intei_decode_fun(const char *buf, int *index, erlang_fun *p) voidfree_fun(erlang_fun* f) Decode a fun. -

This function decodes a fun from the binary format. The - parameter should be NULL or point to an +

Decodes a fun from the binary format. Parameter + is to 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.)

+ function that allocates memory. When the + is no longer needed, it is to be freed with + . (This has to do with the arbitrary size + of the environment for a fun.)

 + intei_decode_list_header(const char *buf, int *index, int *arity) Decode a list. -

This function decodes a list header from the binary +

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 + . The elements + follow (the last one is the tail of the list, normally an empty list). + If is , it is an empty + list.

+

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

 + 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().

+

Decodes a long integer from the binary format. + If the code is 64 bits, the function ei_decode_long() is + the same as ei_decode_longlong().

 + 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 +

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

 + intei_decode_map_header(const char *buf, int *index, int *arity) Decode a map. -

This function decodes a map header from the binary +

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: + *arity. Keys and values follow in this order: K1, V1, K2, V2, ..., Kn, Vn. This makes a total of - arity*2 terms. If arity is zero, it's an empty map. + arity*2 terms. If arity is zero, it is an empty map. A correctly encoded map does not have duplicate keys.

 + intei_decode_pid(const char *buf, int *index, erlang_pid *p) Decode a . -

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

+

Decodes a process identifier (pid) from the binary format.

 + intei_decode_port(const char *buf, int *index, erlang_port *p) Decode a port. -

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

+

Decodes a port identifier from the binary format.

 + intei_decode_ref(const char *buf, int *index, erlang_ref *p) Decode a reference. -

This function decodes a reference from the binary format.

+

Decodes a reference from the binary format.

 + 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 +

Decodes a string from the binary format. A + string in Erlang is a list of integers between 0 and + 255. Notice that as 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.

+

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

 + intei_decode_term(const char *buf, int *index, void *t) Decode a . -

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 +

Decodes a term from the binary format. The term + is return in as a , so + is actually an (see + erl_eterm). + The term is later to be deallocated.

+

Notice 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.

+

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.

+

Decodes a tuple header, the number of elements + is returned in . The tuple elements follow + 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().

+

Decodes an unsigned long integer from the binary format. + If the code is 64 bits, the function ei_decode_ulong() is + 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.

+

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

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

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

Decodes the version magic number for the + Erlang binary term format. It must be the first token in a binary term.

 @@ -366,12 +406,14 @@ typedef enum { intei_x_encode_atom_len(ei_x_buff* x, const char *p, int len) 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 - are encoded. The name should be zero-terminated, except for +

Encodes an atom in the binary format. Parameter + is the name of the atom in Latin-1 encoding. Only up to + MAXATOMLEN-1 bytes + are encoded. The name is to be zero-terminated, except for the function.

 + intei_encode_atom_as(char *buf, int *index, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc) intei_encode_atom_len_as(char *buf, int *index, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc) @@ -380,30 +422,35 @@ typedef enum { Encode an atom.

Encodes an atom in the binary format with character encoding - to_enc (latin1 or utf8). - The p parameter is the name of the atom with character encoding - from_enc (ascii, latin1 or utf8). - The name must either be zero-terminated or a function variant with a len - parameter must be used. If to_enc is set to the bitwise-or'd combination - (ERLANG_LATIN1|ERLANG_UTF8), utf8 encoding is only used if the atom string - can not be represented in latin1 encoding.

-

The encoding will fail if p is not a valid string in encoding from_enc, - if the string is too long or if it can not be represented with character encoding to_enc.

-

These functions were introduced in R16 release of Erlang/OTP as part of a first step - to support UTF8 atoms. Atoms encoded with ERLANG_UTF8 - can not be decoded by earlier releases than R16.

+ to_enc + (Latin-1 or UTF-8). Parameter p is the name of the atom with + character encoding + from_enc + (ASCII, Latin-1, or UTF-8). The name must either be zero-terminated or + a function variant with a len parameter must be used. + If to_enc is set to the bitwise OR'd combination + (ERLANG_LATIN1|ERLANG_UTF8), UTF-8 encoding is only used if the + atom string cannot be represented in Latin-1 encoding.

+

The encoding fails if p is an invalid string in encoding + from_enc, if the string is too long, or if it cannot be + represented with character encoding to_enc.

+

These functions were introduced in Erlang/OTP R16 as part of a first + step to support UTF-8 atoms. Atoms encoded with ERLANG_UTF8 + cannot 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.

+ To use this function, the ei library must 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) @@ -413,72 +460,78 @@ typedef enum { , of bytes length.

 + intei_encode_boolean(char *buf, int *index, int p) intei_x_encode_boolean(ei_x_buff* x, int p) Encode a boolean. -

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

+

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

 + 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 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 +

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

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

Encodes a double-precision (64 bit) floating point number in +

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

-

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

+

Returns if the floating point + number is not finite.

 + intei_encode_empty_list(char* buf, int* index) intei_x_encode_empty_list(ei_x_buff* x) Encode an empty list (). -

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

+

Encodes an empty list. It is often used at the tail of a list.

 + 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. -

Encodes a fun in the binary format. The parameter +

Encodes a fun in the binary format. Parameter points to an structure. The is not freed automatically, the - should be called if the fun is not needed + is to 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. -

This function encodes a list header, with a specified +

Encodes a list header, with a specified arity. The next terms are the elements (actually its cons cells) and the tail of the list. Lists and tuples are encoded recursively, so that a - list may contain another list or tuple.

-

E.g. to encode the list :

+ list can contain another list or tuple.

+

For example, to encode the list + :

 ei_encode_list_header(buf, &i, 3);
 ei_encode_atom(buf, &i, "c");
@@ -486,14 +539,13 @@ ei_encode_atom(buf, &i, "d");
 ei_encode_list_header(buf, &i, 1);
 ei_encode_atom(buf, &i, "e");
 ei_encode_atom(buf, &i, "f");
-ei_encode_empty_list(buf, &i);
-
+ei_encode_empty_list(buf, &i);

It may seem that there is no way to create a list without knowing the number of elements in advance. But indeed - there is a way. Note that the list can be - written as . Using this, a list can - be written as conses.

+ there is a way. Notice that the list + can be written as . + Using this, a list can be written as conses.

To encode a list, without knowing the arity in advance:

@@ -501,83 +553,89 @@ while (something()) {
     ei_x_encode_list_header(&x, 1);
     ei_x_encode_ulong(&x, i); /* just an example */
 }
-ei_x_encode_empty_list(&x);
-
+ei_x_encode_empty_list(&x); + intei_encode_long(char *buf, int *index, long p) intei_x_encode_long(ei_x_buff* x, long p) Encode integer.

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().

+ If the code is 64 bits, the function ei_encode_long() is + 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.

+

Encodes a GCC or Visual C++ + (64-bit) integer in the binary format. + 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. -

This function encodes a map header, with a specified arity. The next +

Encodes a map header, with a specified arity. The next arity*2 terms encoded will be the keys and values of the map encoded in the following order: K1, V1, K2, V2, ..., Kn, Vn.

-

E.g. to encode the map #{a => "Apple", b => "Banana"}:

+

For example, to encode the map #{a => "Apple", b => + "Banana"}:

 ei_x_encode_map_header(&x, 2);
 ei_x_encode_atom(&x, "a");
 ei_x_encode_string(&x, "Apple");
 ei_x_encode_atom(&x, "b");
-ei_x_encode_string(&x, "Banana");
-
-

A correctly encoded map can not have duplicate keys.

+ei_x_encode_string(&x, "Banana"); +

A correctly encoded map cannot have duplicate keys.

 + 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. -

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

+

Encodes an Erlang process identifier (pid) in the binary + format. Parameter points to an + structure (which should have been + obtained earlier with ).

 + 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. + Encode a port. -

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

+

Encodes an Erlang port in the binary format. Parameter + points to a + structure (which should have been obtained earlier with + ).

 + 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. + Encode a ref. -

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

+

Encodes an Erlang reference in the binary format. Parameter + points to a + structure (which should have been obtained earlier with + ).

 + intei_encode_string(char *buf, int *index, const char *p) intei_encode_string_len(char *buf, int *index, const char *p, int len) @@ -585,21 +643,22 @@ ei_x_encode_string(&x, "Banana"); intei_x_encode_string_len(ei_x_buff* x, const char* s, int len) Encode a string. -

Encodes a string in the binary format. (A string in erlang +

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 + format.) The string is to be zero-terminated, except for the function.

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

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

+

Encodes an , as obtained from + . Parameter is + actually an pointer. This function + does not free the .

 @@ -607,51 +666,54 @@ ei_x_encode_string(&x, "Banana"); 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 +

Encodes an Erlang trace token in the binary format. + Parameter points to a structure (which should have been - obtained earlier with .

+ 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. -

This function encodes a tuple header, with a specified +

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 :

+ recursively, so that a tuple can contain another tuple or list.

+

For example, 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);
-
+ei_encode_tuple_header(buf, &i, 0); + intei_encode_ulong(char *buf, int *index, unsigned long p) intei_x_encode_ulong(ei_x_buff* x, unsigned long p) Encode unsigned 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().

+ If the code is 64 bits, the function ei_encode_ulong() is + the same as ei_encode_ulonglong().

 + 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. -

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

+

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

 + intei_encode_version(char *buf, int *index) intei_x_encode_version(ei_x_buff* x) @@ -661,43 +723,47 @@ ei_encode_tuple_header(buf, &i, 0); be the first token in a binary term.

 + 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 +

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.

+ 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. -

This function prints a term, in clear text, to the file - given by , or the buffer pointed to by . It - tries to resemble the term printing in the erlang shell.

-

In , the parameter should +

Prints a term, in clear text, to the file + specified by , or the buffer pointed to by + . It + tries to resemble the term printing in the Erlang shell.

+

In , parameter + is to point to a dynamically (malloc) allocated string of - bytes or a NULL pointer. The string may be - reallocated (and may be updated) by this function - if the result is more than characters. The - string returned is zero-terminated.

-

The return value is the number of characters written to the - file or string, or -1 if doesn't contain a - valid term. Unfortunately, I/O errors on is not - checked.

-

The argument is updated, i.e. this function can - be viewed as en decode function that decodes a term into a - human readable format.

+ bytes or a NULL pointer. The string + can be reallocated (and can be updated) by this + function if the result is more than + characters. The string returned is zero-terminated.

+

The return value is the number of characters written to the file + or string, or -1 if does not + contain a valid term. + Unfortunately, I/O errors on is not checked.

+

Argument is updated, that is, this function + can be viewed as a decode function that decodes a term into a + human-readable format.

 + voidei_set_compat_rel(release_number) Set the ei library in compatibility mode. @@ -708,54 +774,58 @@ ei_encode_tuple_header(buf, &i, 0);

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 + release as the library itself. For example, + from + Erlang/OTP R10 is not compatible with an Erlang emulator + from Erlang/OTP R9 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.

+

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

 -

You may run into trouble if this feature is used - carelessly. Always make sure that all communicating +

You can run into trouble if this feature is used + carelessly. Always ensure 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. + Skip a term. -

This function skips a term in the given buffer, it +

Skips a term in the specified buffer; 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.

+ Erlang term.

is the buffer.

-

is updated to point right after the term in 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 + terms: skip them and copy the binary term data to some buffer.

 -

The function returns on success and on - failure.

+

Returns on success, otherwise + .

 + 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. + Append a buffer at the end. -

These functions appends data at the end of the buffer .

+

Appends data at the end of buffer .

 @@ -764,69 +834,69 @@ ei_encode_tuple_header(buf, &i, 0); intei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... ) Format a term from a format string and parameters. -

Format a term, given as a string, to a buffer. This - functions works like a sprintf for erlang terms. The +

Formats a term, given as a string, to a buffer. + Works like a sprintf for Erlang terms. contains a format string, with arguments like , to insert terms from variables. The following formats are supported (with the C types given):

- 

-~a - an atom, char*
-~c - a character, char
-~s - a string, char*
-~i - an integer, int
-~l - a long integer, long int
-~u - a unsigned long integer, unsigned long int
-~f - a float, float
-~d - a double float, double float
-~p - an Erlang PID, erlang_pid*
-
-

For instance, to encode a tuple with some stuff:

+~a An atom, char* +~c A character, char +~s A string, char* +~i An integer, int +~l A long integer, long int +~u A unsigned long integer, unsigned long int +~f A float, float +~d A double float, double float +~p An Erlang pid, erlang_pid* +

For example, to encode a tuple with some stuff:

 ei_x_format("{~a,~i,~d}", "numbers", 12, 3.14159)
-encodes the tuple {numbers,12,3.14159}
-
-

The formats into a buffer, without - the initial version byte.

+encodes the tuple {numbers,12,3.14159} +

formats into a buffer, + without the initial version byte.

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

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

+

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. -

This function allocates a new buffer. The - fields of the structure pointed to by parameter is - filled in, and a default buffer is allocated. The - also puts an initial version - byte, that is used in the binary format. (So that - won't be needed.)

+

Allocates a new buffer. The + fields of the structure pointed to by parameter + is filled in, and a default buffer is allocated. + also puts an initial + version byte, which is used in the binary format (so that + will not be needed.)

 - +
Debug Information -

Some tips on what to check when the emulator doesn't seem to - receive the terms that you send.

+

Some tips on what to check when the emulator does not seem to + receive the terms that you send:

+ - be careful with the version header, use - when appropriate - turn on distribution tracing on the erlang node - check the result codes from ei_decode_-calls + Be careful with the version header, use + when appropriate. + Turn on distribution tracing on the Erlang node. + Check the result codes from ei_decode_-calls.
See Also -

erl_interface(3)

+

erl_eterm

-- cgit v1.2.3