From 5f5fb466630db9dc8e17895c90ed74105852e827 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Fri, 21 Oct 2016 15:44:49 +0200 Subject: erl_interface: Remove CDATA tag except for example code --- lib/erl_interface/doc/src/ei.xml | 280 +++++++++++++++++++-------------------- 1 file changed, 140 insertions(+), 140 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 9b01f4af98..ddfb4d88a8 100644 --- a/lib/erl_interface/doc/src/ei.xml +++ b/lib/erl_interface/doc/src/ei.xml @@ -35,24 +35,24 @@ ei Routines for handling the Erlang binary term format. -

The library contains macros and functions to encode +

The library ei contains macros and functions to encode and decode the Erlang binary term format.

-

allows you to convert atoms, lists, numbers, and +

ei 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 + writing port programs and drivers. ei uses a given buffer, no dynamic memory (except - ) and is often quite fast.

+ ei_decode_fun()) and is often quite fast.

-

also handles C-nodes, C-programs that talks Erlang +

ei 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 + Erlang distribution format. The difference between ei + and erl_interface is that ei 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 does not allow for - multiple C-nodes. In general, is the preferred way + C-nodes. The erl_interface library is built on top of + ei, but of legacy reasons, it does not allow for + multiple C-nodes. In general, ei is the preferred way of doing C-nodes.

The decode and encode functions use a buffer and an index into the @@ -65,37 +65,37 @@

All functions take two parameters:

-

is a pointer to +

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

 -

is a pointer to an index into the +

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

+

The data is thus at buf[*index] when an + ei function is called.

-

All encode functions assume that the and - parameters point to a buffer large enough for +

All encode functions assume that the buf and + index 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.

+ pass NULL instead of a buffer pointer. Parameter + index is incremented, but nothing will be encoded. This + is the way in ei to "preflight" term encoding.

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 - use a dynamic buffer.

+ ei_x use a dynamic buffer.

-

All functions return if successful, otherwise - (for example, if a term is not of the expected +

All functions return 0 if successful, otherwise + -1 (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 + the ei_get_type() function returns the size required (notice that for strings an extra byte is needed for the NULL-terminator).

 @@ -128,8 +128,8 @@ typedef enum { Decode an atom.

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.

+ name of the atom is placed at p. At most + MAXATOMLEN bytes can be placed in the buffer.

 @@ -162,7 +162,7 @@ typedef enum { Decode a GMP arbitrary precision integer.

Decodes an integer in the binary format to a GMP - integer. To use this function, the ei + mpz_t integer. To use this function, the ei library must be configured and compiled to use the GMP library.

 @@ -172,10 +172,10 @@ typedef enum { Decode a binary.

Decodes a binary from the binary format. Parameter - is set to the actual size of the - binary. Notice that assumes that + len is set to the actual size of the + binary. Notice that ei_decode_binary() assumes that there is enough room for the binary. The size required can be - fetched by .

+ fetched by ei_get_type().

 @@ -184,8 +184,8 @@ typedef enum { Decode a boolean.

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

+ A boolean is actually an atom, true decodes 1 + and false decodes 0.

 @@ -195,9 +195,9 @@ typedef enum {

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 can define to be + type char. Your C code is to consider the + returned value to be of type unsigned char even if + the C compilers and system can define char to be signed.

 @@ -216,16 +216,16 @@ typedef enum { 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.

+ pointed at by *index in buf fits + in the term union, it is decoded, and the + appropriate field in term->value is set, and + *index 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 + term structure. If 1 is returned, the + index is incremented, and term contains the decoded term.

-

The structure contains the arity for a tuple +

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

@@ -238,11 +238,11 @@ typedef enum { Decode a fun.

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 + p is to be NULL or point to an + erlang_fun structure. This is the only decode + function that allocates memory. When the erlang_fun is no longer needed, it is to be freed with - . (This has to do with the arbitrary size + free_fun. (This has to do with the arbitrary size of the environment for a fun.)

 @@ -253,13 +253,13 @@ typedef enum {

Decodes a list header from the binary format. The number of elements is returned in - . The elements + arity. The arity+1 elements follow (the last one is the tail of the list, normally an empty list). - If is , it is an empty + If arity is 0, 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 + not decode such strings, use ei_decode_string() instead.

 @@ -278,8 +278,8 @@ typedef enum { intei_decode_longlong(const char *buf, int *index, long long *p) Decode integer. -

Decodes a GCC or Visual C++ - +

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

 @@ -300,7 +300,7 @@ typedef enum { intei_decode_pid(const char *buf, int *index, erlang_pid *p) - Decode a . + Decode a pid.

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

 @@ -329,9 +329,9 @@ typedef enum {

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 , + lists are encoded as strings by term_to_binary/1, even if it was not intended.

-

The string is copied to , and enough space must +

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

 @@ -339,11 +339,11 @@ typedef enum { intei_decode_term(const char *buf, int *index, void *t) - Decode a . + Decode a ETERM.

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

Notice that this function is located in the Erl_Interface @@ -364,7 +364,7 @@ typedef enum { Decode a tuple.

Decodes a tuple header, the number of elements - is returned in . The tuple elements follow + is returned in arity. The tuple elements follow in order in the buffer.

 @@ -383,15 +383,15 @@ typedef enum { intei_decode_ulonglong(const char *buf, int *index, unsigned long long *p) Decode unsigned integer. -

Decodes a GCC or Visual C++ - (64-bit) integer from the binary +

Decodes a GCC unsigned long long or Visual C++ + unsigned __int64 (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) - Decode an empty list (). + Decode an empty list (nil).

Decodes the version magic number for the Erlang binary term format. It must be the first token in a @@ -406,11 +406,11 @@ 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. Parameter +

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

+ the ei_x_encode_atom_len() function.

 @@ -445,7 +445,7 @@ typedef enum { intei_x_encode_bignum(ei_x_buff *x, mpz_t obj) Encode an arbitrary precision integer. -

Encodes a GMP integer to binary format. +

Encodes a GMP mpz_t integer to binary format. To use this function, the ei library must be configured and compiled to use the GMP library.

 @@ -457,7 +457,7 @@ typedef enum { Encode a binary.

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

+ p, of len bytes length.

 @@ -466,8 +466,8 @@ typedef enum { 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 +

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

 @@ -479,9 +479,9 @@ typedef enum {

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 + type char. Your C code is to consider the specified + argument to be of type unsigned char even if + the C compilers and system may define char to be signed.

 @@ -493,7 +493,7 @@ typedef enum {

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

-

Returns if the floating point +

Returns -1 if the floating point number is not finite.

 @@ -501,7 +501,7 @@ typedef enum { intei_encode_empty_list(char* buf, int* index) intei_x_encode_empty_list(ei_x_buff* x) - Encode an empty list (). + Encode an empty list (nil).

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

 @@ -512,10 +512,10 @@ typedef enum { intei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun) Encode a fun. -

Encodes a fun in the binary format. Parameter - points to an structure. The - is not freed automatically, the - is to be called if the fun is not needed +

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

 @@ -526,12 +526,12 @@ typedef enum { Encode a list.

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

For example, to encode the list - :

+ [c, d, [e | f]]:

 ei_encode_list_header(buf, &i, 3);
 ei_encode_atom(buf, &i, "c");
@@ -543,8 +543,8 @@ 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. Notice that the list - can be written as . + there is a way. Notice that the list [a, b, c] + can be written as [a | [b | [c]]]. Using this, a list can be written as conses.

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

@@ -573,8 +573,8 @@ ei_x_encode_empty_list(&x); 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. +

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

 @@ -606,9 +606,9 @@ ei_x_encode_string(&x, "Banana"); Encode a pid.

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

+ format. Parameter p points to an + erlang_pid structure (which should have been + obtained earlier with ei_decode_pid()).

 @@ -618,9 +618,9 @@ ei_x_encode_string(&x, "Banana"); Encode a port.

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

+ ei_decode_port()).

 @@ -630,9 +630,9 @@ ei_x_encode_string(&x, "Banana"); Encode a ref.

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

+ ei_decode_ref()).

 @@ -646,19 +646,19 @@ ei_x_encode_string(&x, "Banana");

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 is to be NULL-terminated, except for - the function.

+ the ei_x_encode_string_len() 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 erl_interface term. -

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

+

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

 @@ -667,9 +667,9 @@ ei_x_encode_string(&x, "Banana"); Encode a trace token.

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

+ Parameter p points to a + erlang_trace structure (which should have been + obtained earlier with ei_decode_trace()).

 @@ -679,10 +679,10 @@ ei_x_encode_string(&x, "Banana"); Encode a tuple.

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

-

For example, to encode the tuple :

+

For example, to encode the tuple {a, {b, {}}}:

 ei_encode_tuple_header(buf, &i, 2);
 ei_encode_atom(buf, &i, "a");
@@ -708,8 +708,8 @@ ei_encode_tuple_header(buf, &i, 0);
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 +

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

 @@ -728,13 +728,13 @@ ei_encode_tuple_header(buf, &i, 0); intei_get_type(const char *buf, const int *index, int *type, int *size) Fetch the type and size of an encoded term. -

Returns the type in and size in - of the encoded term. For strings and atoms, +

Returns the type in type and size in + size of the encoded term. For strings and atoms, size is the number of characters not including the - terminating NULL. 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.

+ terminating NULL. For binaries, size is the number of + bytes. For lists and tuples, size is the arity of + the object. For other types, size is 0. In all + cases, index is left unchanged.

 @@ -744,21 +744,21 @@ ei_encode_tuple_header(buf, &i, 0); Print a term in clear text.

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

-

In , parameter - is to +

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

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

-

Argument is updated, that is, this function + Unfortunately, I/O errors on fp is not checked.

+

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

 @@ -772,22 +772,22 @@ ei_encode_tuple_header(buf, &i, 0); -

By default, the library is only guaranteed +

By default, the ei library is only guaranteed to be compatible with other Erlang/OTP components from the same - release as the library itself. For example, - from + release as the ei library itself. For example, + ei 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 - +

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

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

+ ei library are called.

You can run into trouble if this feature is used @@ -807,16 +807,16 @@ ei_encode_tuple_header(buf, &i, 0); 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 +

buf is the buffer.

+

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

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

 -

Returns on success, otherwise - .

+

Returns 0 on success, otherwise + -1.

 @@ -825,7 +825,7 @@ ei_encode_tuple_header(buf, &i, 0); intei_x_append_buf(ei_x_buff* x, const char* buf, int len) Append a buffer at the end. -

Appends data at the end of buffer .

+

Appends data at the end of buffer x.

 @@ -836,8 +836,8 @@ ei_encode_tuple_header(buf, &i, 0);

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 + fmt contains a format string, with arguments like + ~d, to insert terms from variables. The following formats are supported (with the C types given):

 ~a  An atom, char*
@@ -853,7 +853,7 @@ ei_encode_tuple_header(buf, &i, 0);
 ei_x_format("{~a,~i,~d}", "numbers", 12, 3.14159)
 encodes the tuple {numbers,12,3.14159}
-

formats into a buffer, +

ei_x_format_wo_ver() formats into a buffer, without the initial version byte.

 @@ -862,7 +862,7 @@ encodes the tuple {numbers,12,3.14159} intei_x_free(ei_x_buff* x) Free a buffer. -

Frees an buffer. +

Frees an ei_x_buff buffer. The memory used by the buffer is returned to the OS.

 @@ -872,12 +872,12 @@ encodes the tuple {numbers,12,3.14159} intei_x_new_with_version(ei_x_buff* x) Allocate a new buffer. -

Allocates a new buffer. The - fields of the structure pointed to by parameter +

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

+ ei_x_encode_version() will not be needed.)

 @@ -889,7 +889,7 @@ encodes the tuple {numbers,12,3.14159} Be careful with the version header, use - when appropriate. + ei_x_new_with_version() when appropriate. Turn on distribution tracing on the Erlang node. Check the result codes from ei_decode_-calls. -- cgit v1.2.3