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/book.xml | 11 +- lib/erl_interface/doc/src/ei.xml | 869 ++++++++++++++------------- lib/erl_interface/doc/src/ei_connect.xml | 515 ++++++++-------- lib/erl_interface/doc/src/ei_users_guide.xml | 9 +- lib/erl_interface/doc/src/erl_call.xml | 35 +- lib/erl_interface/doc/src/erl_connect.xml | 373 ++++++------ lib/erl_interface/doc/src/erl_error.xml | 21 +- lib/erl_interface/doc/src/erl_eterm.xml | 169 +++--- lib/erl_interface/doc/src/erl_format.xml | 13 +- lib/erl_interface/doc/src/erl_global.xml | 19 +- lib/erl_interface/doc/src/erl_malloc.xml | 59 +- lib/erl_interface/doc/src/erl_marshal.xml | 35 +- lib/erl_interface/doc/src/ref_man.xml | 5 +- lib/erl_interface/doc/src/registry.xml | 625 ++++++++++--------- 14 files changed, 1373 insertions(+), 1385 deletions(-) (limited to 'lib/erl_interface') diff --git a/lib/erl_interface/doc/src/book.xml b/lib/erl_interface/doc/src/book.xml index c9194d96ff..94bfef7455 100644 --- a/lib/erl_interface/doc/src/book.xml +++ b/lib/erl_interface/doc/src/book.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 @@ -19,19 +19,19 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + - Erlang Interface + Erl_Interface Gordon Beaton 1998-11-30 1.2 - book.sgml + book.xml - Erlang Interface + Erl_Interface @@ -47,4 +47,3 @@ - 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)

- diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index 516357b6a3..8cc08f86cd 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + ei_connect @@ -29,7 +29,7 @@ ? 2001-09-01 A - ei_connect.sgml + ei_connect.xml ei_connect Communicate with distributed erlang @@ -72,11 +72,96 @@ the operations are completed (regardless of the result). To avoid problems, leave the socket options alone. Ei will handle any socket options that need modification.

-

In all other senses, the functions inherit all - the return values and the semantics from the functions without +

In all other senses, the functions inherit all + the return values and the semantics from the functions without the suffix.

+ + struct hostent*ei_gethostbyaddr(const char *addr, int len, int type) + struct hostent*ei_gethostbyaddr_r(const char *addr, int length, int type, struct hostent *hostp, char *buffer, int buflen, int *h_errnop) + struct hostent*ei_gethostbyname(const char *name) + struct hostent*ei_gethostbyname_r(const char *name, struct hostent *hostp, char *buffer, int buflen, int *h_errnop) + Name lookup functions. + +

These are convenience functions for some common name lookup functions.

+ + + + intei_accept(ei_cnode *ec, int listensock, ErlConnect *conp) + Accept a connection from another node. + +

This function is used by a server process to accept a + connection from a client process.

+

is the C-node structure.

+

is an open socket descriptor on which + has previously been called.

+

is a pointer to an struct, + described as follows:

+ +

On success, is filled in with the address and + node name of the connecting client and a file descriptor is + returned. On failure, is returned and + is set to .

+ + + + intei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms) + Accept a connection from another node with optional timeout. + +

ei_accept with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_connect(ei_cnode* ec, char *nodename) + intei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename) + Establishe a connection to an Erlang node. + +

These functions set up a connection to an Erlang node.

+

requires the IP address of the remote + host and the alive name of the remote node + to be specified. provides an alternative + interface, and determines the information from the node name + provided.

+

is the 32-bit IP address of the remote host.

+

is the alivename of the remote node.

+

is the name of the remote node.

+

These functions return an open file descriptor on success, or + a negative value indicating that an error occurred --- in + which case they will set to one of:

+ + + The remote host is unreachable + + No more memory available. + + I/O error. + +

Additionally, values from + (2) and (2) + system calls may be propagated into .

+

Example:

+ + + intei_connect_init(ei_cnode* ec, const char* this_node_name, const char *cookie, short creation) intei_connect_xinit(ei_cnode* ec, const char *thishostname, const char *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr, const char *cookie, short creation) @@ -140,61 +225,58 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { - intei_connect(ei_cnode* ec, char *nodename) - intei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename) - Establishe a connection to an Erlang node + intei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms) + intei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms) + Establish a connection to an Erlang node with optional timeout. -

These functions set up a connection to an Erlang node.

-

requires the IP address of the remote - host and the alive name of the remote node - to be specified. provides an alternative - interface, and determines the information from the node name - provided.

-

is the 32-bit IP address of the remote host.

-

is the alivename of the remote node.

-

is the name of the remote node.

-

These functions return an open file descriptor on success, or - a negative value indicating that an error occurred --- in - which case they will set to one of:

- - - The remote host is unreachable - - No more memory available. - - I/O error. - -

Additionally, values from - (2) and (2) - system calls may be propagated into .

-

Example:

- +

ei_connect and ei_xconnect with an optional timeout argument, + see the description at the beginning of this document.

 - intei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms) - intei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms) - Establish a connection to an Erlang node with optional timeout + intei_get_tracelevel(void) + voidei_set_tracelevel(int level) + Get and set functions for tracing. -

ei_connect and ei_xconnect with an optional timeout argument, +

These functions are used to set tracing on the distribution. The levels are different verbosity levels. A higher level means more information. + See also Debug Information and below.

+

and are not thread safe.

+ + + + intei_publish(ei_cnode *ec, int port) + Publish a node name. + +

These functions are used by a server process to register + with the local name server epmd, thereby allowing + other processes to send messages by using the registered name. + Before calling either of these functions, the process should + have called and on an open socket.

+

is the C-node structure.

+

is the local name to register, and should be the + same as the port number that was previously bound to the socket.

+

is the 32-bit IP address of the local host.

+

To unregister with epmd, simply close the returned + descriptor. Do not use , which is deprecated anyway.

+

On success, the functions return a descriptor connecting the + calling process to epmd. On failure, they return -1 and set + to .

+

Additionally, values from (2) + and (2) system calls may be propagated + into .

+ + + + intei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms) + Publish a node name with optional timeout. + +

ei_publish with an optional timeout argument, see the description at the beginning of this document.

 intei_receive(int fd, unsigned char* bufp, int bufsize) - Receive a message + Receive a message.

This function receives a message consisting of a sequence of bytes in the Erlang external format.

@@ -224,17 +306,44 @@ fd = ei_xconnect(&ec, &addr, ALIVE); - intei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms) - Receive a message with optional timeout + intei_receive_encoded(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen) + Obsolete function for receiving a message. -

ei_receive with an optional timeout argument, +

This function is retained for compatibility with code + generated by the interface compiler and with code following + examples in the same application.

+

In essence the function performs the same operation as + , but instead of using an ei_x_buff, the + function expects a pointer to a character pointer + (), where the character pointer should point to a + memory area allocated by . The argument + should be a pointer to an integer containing the + exact size (in bytes) of the memory area. The function may + reallocate the memory area and will in such cases put the new + size in and update .

+

Furthermore the function returns either ERL_TICK or the + field of the . The actual + length of the message is put in . On error it + will return a value .

+

It is recommended to use ei_xreceive_msg instead when + possible, for the sake of readability. The function will + however be retained in the interface for compatibility and + will not be removed not be removed in future releases + without notice.

+ + + + intei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen, unsigned timeout_ms) + Obsolete function for receiving a message with timeout. + +

ei_receive_encoded with an optional timeout argument, see the description at the beginning of this document.

 intei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x) intei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x) - Receive a message + Receive a message.

These functions receives a message to the buffer in . allows the buffer in @@ -279,90 +388,23 @@ typedef struct { intei_receive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned imeout_ms) intei_xreceive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned timeout_ms) - Receive a message with optional timeout + Receive a message with optional timeout.

ei_receive_msg and ei_xreceive_msg with an optional timeout argument, see the description at the beginning of this document.

 - intei_receive_encoded(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen) - Obsolete function for receiving a message - -

This function is retained for compatibility with code - generated by the interface compiler and with code following - examples in the same application.

-

In essence the function performs the same operation as - , but instead of using an ei_x_buff, the - function expects a pointer to a character pointer - (), where the character pointer should point to a - memory area allocated by . The argument - should be a pointer to an integer containing the - exact size (in bytes) of the memory area. The function may - reallocate the memory area and will in such cases put the new - size in and update .

-

Furthermore the function returns either ERL_TICK or the - field of the . The actual - length of the message is put in . On error it - will return a value .

-

It is recommended to use ei_xreceive_msg instead when - possible, for the sake of readability. The function will - however be retained in the interface for compatibility and - will not be removed not be removed in future releases - without notice.

- - - - intei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen, unsigned timeout_ms) - Obsolete function for receiving a message with timeout - -

ei_receive_encoded with an optional timeout argument, - see the description at the beginning of this document.

- - - - intei_send(int fd, erlang_pid* to, char* buf, int len) - Send a message - -

This function sends an Erlang term to a process.

-

is an open descriptor to an Erlang connection.

-

is the Pid of the intended recipient of the - message.

-

is the buffer containing the term in binary - format.

-

is the length of the message in bytes.

-

The function returns 0 if successful, otherwise -1, in the - latter case it will set to .

- - - - intei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms) - Send a message with optional timeout - -

ei_send with an optional timeout argument, - see the description at the beginning of this document.

- - - - intei_send_encoded(int fd, erlang_pid* to, char* buf, int len) - Obsolete function to send a message - -

Works exactly as ei_send, the alternative name retained for - backward compatibility. The function will not be - removed without notice.

- - - - intei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms) - Obsolete function to send a message with optional timeout + intei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms) + Receive a message with optional timeout. -

ei_send_encoded with an optional timeout argument, +

ei_receive with an optional timeout argument, see the description at the beginning of this document.

 intei_reg_send(ei_cnode* ec, int fd, char* server_name, char* buf, int len) - Send a message to a registered name + Send a message to a registered name.

This function sends an Erlang term to a registered process.

@@ -387,49 +429,17 @@ if (ei_reg_send(&ec, fd, x.buff, x.index) < 0) intei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf, int len, unsigned timeout_ms) - Send a message to a registered name with optional timeout + Send a message to a registered name with optional timeout.

ei_reg_send with an optional timeout argument, see the description at the beginning of this document.

 - - intei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len) - Obsolete function to send a message to a registered name - -

This function is retained for compatibility with code - generated by the interface compiler and with code following - examples in the same application.

-

The function works as with one - exception. Instead of taking the as a first - argument, it takes a second argument, an - which should be the process identifier of the sending process - (in the erlang distribution protocol).

-

A suitable can be constructed from the - structure by the following example code:

- num = fd; - ]]> - - - - intei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len) - Obsolete function to send a message to a registered name with timeout - -

ei_send_reg_encoded with an optional timeout argument, - see the description at the beginning of this document.

- - intei_rpc(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen, ei_x_buff *x) intei_rpc_to(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen) intei_rpc_from(ei_cnode *ec, int fd, int timeout, erlang_msg *msg, ei_x_buff *x) - Remote Procedure Call from C to Erlang + Remote Procedure Call from C to Erlang.

These functions support calling Erlang functions on remote nodes. sends an rpc request to a remote node and @@ -496,95 +506,85 @@ if (ei_decode_version(result.buff, &index) < 0 - intei_publish(ei_cnode *ec, int port) - Publish a node name + erlang_pid *ei_self(ei_cnode *ec) + Retrieve the Pid of the C-node. -

These functions are used by a server process to register - with the local name server epmd, thereby allowing - other processes to send messages by using the registered name. - Before calling either of these functions, the process should - have called and on an open socket.

-

is the C-node structure.

-

is the local name to register, and should be the - same as the port number that was previously bound to the socket.

-

is the 32-bit IP address of the local host.

-

To unregister with epmd, simply close the returned - descriptor. Do not use , which is deprecated anyway.

-

On success, the functions return a descriptor connecting the - calling process to epmd. On failure, they return -1 and set - to .

-

Additionally, values from (2) - and (2) system calls may be propagated - into .

+

This function retrieves the Pid of the C-node. Every C-node + has a (pseudo) pid used in , + and others. This is contained in a field in the + structure. It will be safe for a long time to fetch this + field directly from the structure.

 - intei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms) - Publish a node name with optional timeout + intei_send(int fd, erlang_pid* to, char* buf, int len) + Send a message. -

ei_publish with an optional timeout argument, - see the description at the beginning of this document.

+

This function sends an Erlang term to a process.

+

is an open descriptor to an Erlang connection.

+

is the Pid of the intended recipient of the + message.

+

is the buffer containing the term in binary + format.

+

is the length of the message in bytes.

+

The function returns 0 if successful, otherwise -1, in the + latter case it will set to .

 - intei_accept(ei_cnode *ec, int listensock, ErlConnect *conp) - Accept a connection from another node + intei_send_encoded(int fd, erlang_pid* to, char* buf, int len) + Obsolete function to send a message. -

This function is used by a server process to accept a - connection from a client process.

-

is the C-node structure.

-

is an open socket descriptor on which - has previously been called.

-

is a pointer to an struct, - described as follows:

- -

On success, is filled in with the address and - node name of the connecting client and a file descriptor is - returned. On failure, is returned and - is set to .

+

Works exactly as ei_send, the alternative name retained for + backward compatibility. The function will not be + removed without notice.

 - intei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms) - Accept a connection from another node with optional timeout + intei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms) + Obsolete function to send a message with optional timeout. -

ei_accept with an optional timeout argument, +

ei_send_encoded with an optional timeout argument, see the description at the beginning of this document.

 - intei_unpublish(ei_cnode *ec) - Forcefully unpublish a node name + intei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len) + Obsolete function to send a message to a registered name. -

This function can be called by a process to unregister a - specified node from epmd on the localhost. This is however usually not - allowed, unless epmd was started with the -relaxed_command_check - flag, which it normally isn't.

- -

To unregister a node you have published, you should - close the descriptor that was returned by - .

- - -

This function is deprecated and will be removed in a future - release.

- -

is the node structure of the node to unregister.

-

If the node was successfully unregistered from epmd, the - function returns 0. Otherwise, it returns -1 and sets - is to .

+

This function is retained for compatibility with code + generated by the interface compiler and with code following + examples in the same application.

+

The function works as with one + exception. Instead of taking the as a first + argument, it takes a second argument, an + which should be the process identifier of the sending process + (in the erlang distribution protocol).

+

A suitable can be constructed from the + structure by the following example code:

+ num = fd; + ]]> - intei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms) - Unpublish a node name with optional timeout + intei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len) + Obsolete function to send a message to a registered name with timeout. -

ei_unpublish with an optional timeout argument, +

ei_send_reg_encoded with an optional timeout argument, + see the description at the beginning of this document.

+ + + + intei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms) + Send a message with optional timeout. + +

ei_send with an optional timeout argument, see the description at the beginning of this document.

 @@ -592,7 +592,7 @@ typedef struct { const char *ei_thisnodename(ei_cnode *ec) const char *ei_thishostname(ei_cnode *ec) const char *ei_thisalivename(ei_cnode *ec) - Retrieve some values + Retrieve some values.

These functions can be used to retrieve information about the C Node. These values are initially set with @@ -603,37 +603,37 @@ typedef struct { - erlang_pid *ei_self(ei_cnode *ec) - Retrieve the Pid of the C-node - -

This function retrieves the Pid of the C-node. Every C-node - has a (pseudo) pid used in , - and others. This is contained in a field in the - structure. It will be safe for a long time to fetch this - field directly from the structure.

- - - - struct hostent*ei_gethostbyname(const char *name) - struct hostent*ei_gethostbyaddr(const char *addr, int len, int type) - struct hostent*ei_gethostbyname_r(const char *name, struct hostent *hostp, char *buffer, int buflen, int *h_errnop) - struct hostent*ei_gethostbyaddr_r(const char *addr, int length, int type, struct hostent *hostp, char *buffer, int buflen, int *h_errnop) - Name lookup functions + intei_unpublish(ei_cnode *ec) + Forcefully unpublish a node name. -

These are convenience functions for some common name lookup functions.

+

This function can be called by a process to unregister a + specified node from epmd on the localhost. This is however usually not + allowed, unless epmd was started with the -relaxed_command_check + flag, which it normally isn't.

+ +

To unregister a node you have published, you should + close the descriptor that was returned by + .

+ + +

This function is deprecated and will be removed in a future + release.

+ +

is the node structure of the node to unregister.

+

If the node was successfully unregistered from epmd, the + function returns 0. Otherwise, it returns -1 and sets + is to .

 - intei_get_tracelevel(void) - voidei_set_tracelevel(int level) - Get and set functions for tracing. + intei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms) + Unpublish a node name with optional timeout. -

These functions are used to set tracing on the distribution. The levels are different verbosity levels. A higher level means more information. - See also Debug Information and below.

-

and are not thread safe.

+

ei_unpublish with an optional timeout argument, + see the description at the beginning of this document.

 - +
Debug Information @@ -652,13 +652,12 @@ typedef struct { or by setting the environment variable . The different tracelevels has the following messages:

- 1: Verbose error messages - 2: Above messages and verbose warning messages - 3: Above messages and progress reports for connection handling - 4: Above messages and progress reports for communication - 5: Above messages and progress reports for data conversion + 1: Verbose error messages + 2: Above messages and verbose warning messages + 3: Above messages and progress reports for connection handling + 4: Above messages and progress reports for communication + 5: Above messages and progress reports for data conversion
- diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index 4b9809aee4..4beb4c6c73 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + The El Library User's Guide @@ -77,7 +77,7 @@ Eshell V4.7.4 (abort with ^G) definition in your . The correct value for this path is Vsn, where is the path reported by in the above example, and Vsn is - the version of the Erl_interface application, for example + the version of the Erl_interface application, for example

@@ -147,7 +147,7 @@ i = erl_encode(tuple, buf); ]]>
Building Terms and Patterns -

The previous example can be simplified by using +

The previous example can be simplified by using to create an Erlang term.

- diff --git a/lib/erl_interface/doc/src/erl_call.xml b/lib/erl_interface/doc/src/erl_call.xml index 46015621ac..f8fe409560 100644 --- a/lib/erl_interface/doc/src/erl_call.xml +++ b/lib/erl_interface/doc/src/erl_call.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,14 +30,14 @@ Torbjörn Törnkvist 97-05-16 B - erl_call.sgml + erl_call.xml erl_call - Call/Start a Distributed Erlang Node + Call/start a distributed Erlang node. -

makes it possible to start and/or communicate with - a distributed Erlang node. It is built upon the - library as an example application. Its purpose is to use an Unix shell script to interact with a distributed Erlang node. It performs all +

makes it possible to start and/or communicate with + a distributed Erlang node. It is built upon the + library as an example application. Its purpose is to use an Unix shell script to interact with a distributed Erlang node. It performs all communication with the Erlang rex server, using the standard Erlang RPC facility. It does not require any special software to be run at the Erlang target node.

The main use is to either start a distributed Erlang node @@ -46,17 +46,17 @@ compiled, or to pipe a sequence of Erlang expressions to be evaluated (similar to the Erlang shell).

Options, which cause to be read, can be used with - advantage - as scripts from within (Unix) shell scripts. Another + advantage + as scripts from within (Unix) shell scripts. Another nice use of could be from (http) CGI-bin scripts.

 erl_call <options> - Start/Call Erlang + Start/call Erlang.

Each option flag is described below with its name, type and - meaning.

+ meaning.

-a [Mod [Fun [Args]]]] @@ -85,7 +85,7 @@

(optional): Reads a sequence of Erlang expressions, separated by ',' and ended with a '.', from until - EOF (Control-D). Evaluates the expressions and returns the result from + EOF (Control-D). Evaluates the expressions and returns the result from the last expression. Returns if successful.

 @@ -103,18 +103,18 @@ -n Node -

(one of is required): - Has the same meaning as and can still be used for +

(one of is required): + Has the same meaning as and can still be used for backwards compatibility reasons.

 -name Node

(one of is required): is the name of the node to be - started or communicated with. It is assumed that - is started with , which means that fully - qualified long node names are used. - If the option is given, an Erlang node will (if necessary) + started or communicated with. It is assumed that + is started with , which means that fully + qualified long node names are used. + If the option is given, an Erlang node will (if necessary) be started with .

 @@ -238,4 +238,3 @@ start() -> ]]> - diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml index 0fad98cd17..0799e30905 100644 --- a/lib/erl_interface/doc/src/erl_connect.xml +++ b/lib/erl_interface/doc/src/erl_connect.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + erl_connect @@ -30,7 +30,7 @@ Torbjörn Törnkvist 980703 A - erl_connect.sgml + erl_connect.xml erl_connect Communicate with Distributed Erlang @@ -46,10 +46,99 @@ Erlang function .

+ + interl_accept(listensock, conp) + Accept a connection. + + int listensock; + ErlConnect *conp; + + +

This function is used by a server process to accept a + connection from a client process.

+

is an open socket descriptor on which + has previously been called.

+

is a pointer to an struct, + described as follows:

+ +

On success, is filled in with the address and + node name of the connecting client and a file descriptor is + returned. On failure, is returned and + is set to .

+ + + + interl_close_connection(fd) + Close a connection to an Erlang node. + + int fd; + + +

This function closes an open connection to an Erlang node.

+

is a file descriptor obtained from + or .

+

On success, 0 is returned. If the call fails, a non-zero value + is returned, and the reason for + the error can be obtained with the appropriate platform-dependent + call.

+ + + + interl_connect(node) + interl_xconnect(addr, alive) + Establishe a connection to an Erlang node. + + char *node, *alive; + struct in_addr *addr; + + +

These functions set up a connection to an Erlang node.

+

requires the IP address of the remote + host and the alive name of the remote node + to be specified. provides an alternative + interface, and determines the information from the node name + provided.

+

is the 32-bit IP address of the remote host.

+

is the alivename of the remote node.

+

is the name of the remote node.

+

These functions return an open file descriptor on success, or + a negative value indicating that an error occurred --- in + which case they will set to one of:

+ + + The remote host is unreachable + + No more memory available. + + I/O error. + +

Additionally, values from + (2) and (2) + system calls may be propagated into .

+ + + interl_connect_init(number, cookie, creation) interl_connect_xinit(host, alive, node, addr, cookie, creation) - Initialize communication + Initialize communication. int number; char *cookie; @@ -61,7 +150,7 @@

These functions initialize the module. In particular, they are used to identify the name of the C-node from which they are called. One of these functions must - be called before any of the other functions in the erl_connect + be called before any of the other functions in the erl_connect module are used.

stores for later use information about the node's host name , alive name , node @@ -69,12 +158,12 @@ and creation number . provides an alternative interface which does not require as much information from the caller. Instead, - uses to obtain default values. + uses to obtain default values.

If you use your node will have a short name, i.e., it will not be fully qualified. If you need to use fully qualified (a.k.a. long) names, use - instead. + instead.

is the name of the host on which the node is running.

is the alivename of the node.

@@ -118,71 +207,38 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) - interl_connect(node) - interl_xconnect(addr, alive) - Establishe a connection to an Erlang node + interl_publish(port) + Publish a node name. - char *node, *alive; - struct in_addr *addr; + int port; -

These functions set up a connection to an Erlang node.

-

requires the IP address of the remote - host and the alive name of the remote node - to be specified. provides an alternative - interface, and determines the information from the node name - provided.

-

is the 32-bit IP address of the remote host.

-

is the alivename of the remote node.

-

is the name of the remote node.

-

These functions return an open file descriptor on success, or - a negative value indicating that an error occurred --- in - which case they will set to one of:

+

These functions are used by a server process to register + with the local name server epmd, thereby allowing + other processes to send messages by using the registered name. + Before calling either of these functions, the process should + have called and on an open socket.

+

is the local name to register, and should be the + same as the port number that was previously bound to the socket.

+

To unregister with epmd, simply close the returned + descriptor. +

+

On success, the functions return a descriptor connecting the + calling process to epmd. On failure, they return -1 and set + to:

- - The remote host is unreachable - - No more memory available. - I/O error. + I/O error -

Additionally, values from - (2) and (2) - system calls may be propagated into .

- - - - - interl_close_connection(fd) - Close a connection to an Erlang node - - int fd; - - -

This function closes an open connection to an Erlang node.

-

is a file descriptor obtained from - or .

-

On success, 0 is returned. If the call fails, a non-zero value - is returned, and the reason for - the error can be obtained with the appropriate platform-dependent - call.

+

Additionally, values from (2) + and (2) system calls may be propagated + into . +

interl_receive(fd, bufp, bufsize) - Receive a message + Receive a message. int fd; char *bufp; @@ -216,7 +272,7 @@ erl_xconnect( &addr , ALIVE ); interl_receive_msg(fd, bufp, bufsize, emsg) - Receive and decodes a message + Receive and decodes a message. int fd; unsigned char *bufp; @@ -224,7 +280,7 @@ erl_xconnect( &addr , ALIVE ); ErlMessage *emsg; -

This function receives the message into the specified buffer, +

This function receives the message into the specified buffer, and decodes into the .

is an open descriptor to an Erlang connection.

is a buffer large enough to hold the expected message.

@@ -245,9 +301,9 @@ typedef struct {

The definition of has changed since earlier versions of Erl_Interface.

-

identifies the type of message, one of +

identifies the type of message, one of , , , - and . + and .

If contains this indicates that an ordinary send operation has taken @@ -294,66 +350,9 @@ typedef struct { - - interl_xreceive_msg(fd, bufpp, bufsizep, emsg) - Receive and decodes a message - - int fd; - unsigned char **bufpp; - int *bufsizep; - ErlMessage *emsg; - - -

This function is similar to . The - difference is that expects the buffer to - have been allocated by , and reallocates it if the received - message does not fit into the original buffer. For that reason, - both buffer and buffer length are given as pointers - their values - may change by the call. -

-

On success, the function returns and the - struct will be initialized as described above, or - , in which case no message is returned. On - failure, the function returns and will set - to one of:

- - - Buffer too small. - - No more memory available. - - I/O error. - - - - - interl_send(fd, to, msg) - Send a message - - int fd; - ETERM *to, *msg; - - -

This function sends an Erlang term to a process.

-

is an open descriptor to an Erlang connection.

-

is an Erlang term containing the Pid of the - intended recipient of the message.

-

is the Erlang term to be sent.

-

The function returns 1 if successful, otherwise 0 --- in - which case it will set to one of:

- - - Invalid argument: is not a valid Erlang pid. - - No more memory available. - - I/O error. - - - interl_reg_send(fd, to, msg) - Send a message to a registered name + Send a message to a registered name. int fd; char *to; @@ -377,9 +376,9 @@ typedef struct { ETERM *erl_rpc(fd, mod, fun, args) - interl_rpc_to(fd, mod, fun, args) interl_rpc_from(fd, timeout, emsg) - Remote Procedure Call + interl_rpc_to(fd, mod, fun, args) + Remote Procedure Call. int fd, timeout; char *mod, *fun; @@ -438,68 +437,37 @@ typedef struct { - interl_publish(port) - Publish a node name + interl_send(fd, to, msg) + Send a message. - int port; + int fd; + ETERM *to, *msg; -

These functions are used by a server process to register - with the local name server epmd, thereby allowing - other processes to send messages by using the registered name. - Before calling either of these functions, the process should - have called and on an open socket.

-

is the local name to register, and should be the - same as the port number that was previously bound to the socket.

-

To unregister with epmd, simply close the returned - descriptor. -

-

On success, the functions return a descriptor connecting the - calling process to epmd. On failure, they return -1 and set - to:

+

This function sends an Erlang term to a process.

+

is an open descriptor to an Erlang connection.

+

is an Erlang term containing the Pid of the + intended recipient of the message.

+

is the Erlang term to be sent.

+

The function returns 1 if successful, otherwise 0 --- in + which case it will set to one of:

+ + Invalid argument: is not a valid Erlang pid. + + No more memory available. - I/O error + I/O error. -

Additionally, values from (2) - and (2) system calls may be propagated - into . -

- - - - interl_accept(listensock, conp) - Accept a connection - - int listensock; - ErlConnect *conp; - - -

This function is used by a server process to accept a - connection from a client process.

-

is an open socket descriptor on which - has previously been called.

-

is a pointer to an struct, - described as follows:

- -

On success, is filled in with the address and - node name of the connecting client and a file descriptor is - returned. On failure, is returned and - is set to .

 - const char *erl_thiscookie() - const char *erl_thisnodename() - const char *erl_thishostname() const char *erl_thisalivename() + const char *erl_thiscookie() shorterl_thiscreation() - Retrieve some values + const char *erl_thishostname() + const char *erl_thisnodename() + Retrieve some values.

These functions can be used to retrieve information about the C Node. These values are initially set with @@ -508,22 +476,22 @@ typedef struct { interl_unpublish(alive) - Forcefully unpublish a node name + Forcefully unpublish a node name. char *alive;

This function can be called by a process to unregister a - specified node from epmd on the localhost. This is however usually not - allowed, unless epmd was started with the -relaxed_command_check + specified node from epmd on the localhost. This is however usually not + allowed, unless epmd was started with the -relaxed_command_check flag, which it normally isn't.

To unregister a node you have published, you should instead - close the descriptor that was returned by - .

+ close the descriptor that was returned by + .

-

This function is deprecated and will be removed in a future +

This function is deprecated and will be removed in a future release.

is the name of the node to unregister, i.e., the @@ -534,11 +502,43 @@ typedef struct { - struct hostent*erl_gethostbyname(name) + interl_xreceive_msg(fd, bufpp, bufsizep, emsg) + Receive and decodes a message. + + int fd; + unsigned char **bufpp; + int *bufsizep; + ErlMessage *emsg; + + +

This function is similar to . The + difference is that expects the buffer to + have been allocated by , and reallocates it if the received + message does not fit into the original buffer. For that reason, + both buffer and buffer length are given as pointers - their values + may change by the call. +

+

On success, the function returns and the + struct will be initialized as described above, or + , in which case no message is returned. On + failure, the function returns and will set + to one of:

+ + + Buffer too small. + + No more memory available. + + I/O error. + + + + struct hostent*erl_gethostbyaddr(addr, length, type) - struct hostent*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop) struct hostent*erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop) - Name lookup functions + struct hostent*erl_gethostbyname(name) + struct hostent*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop) + Name lookup functions. const char *name; const char *addr; @@ -567,4 +567,3 @@ typedef struct { - diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml index abe84780e1..5b8d546e12 100644 --- a/lib/erl_interface/doc/src/erl_error.xml +++ b/lib/erl_interface/doc/src/erl_error.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + erl_error @@ -30,13 +30,13 @@ Torbjörn Törnkvist 961014 A - erl_error.sgml + erl_error.xml erl_error Error Print Routines

This module contains some error printing routines taken - from Advanced Programming in the UNIX Environment + from Advanced Programming in the UNIX Environment by W. Richard Stevens.

These functions are all called in the same manner as , i.e. with a string containing format specifiers @@ -46,7 +46,7 @@ voiderl_err_msg(FormatStr, ... ) - Non-fatal error, and not system call error + Non-fatal error, and not system call error. const char *FormatStr; @@ -57,7 +57,7 @@ voiderl_err_quit(FormatStr, ... ) - Fatal error, but not system call error + Fatal error, but not system call error. const char *FormatStr; @@ -70,19 +70,19 @@ voiderl_err_ret(FormatStr, ... ) - Non-fatal system call error + Non-fatal system call error. const char *FormatStr;

Use this function after a failed system call. The message provided by the caller is printed followed by a string - describing the reason for failure.

+ describing the reason for failure.

 voiderl_err_sys(FormatStr, ... ) - Fatal system call error + Fatal system call error. const char *FormatStr; @@ -107,7 +107,7 @@ volatile interl_errno - The variable contains the erl_interface error number. You can change the value if you wish. + The variable contains the erl_interface error number. You can change the value if you wish.

is initially (at program startup) zero and is then set by many erl_interface functions on failure to a @@ -134,4 +134,3 @@ - diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml index 800f8a3207..e5207a271e 100644 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ b/lib/erl_interface/doc/src/erl_eterm.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + erl_eterm @@ -30,7 +30,7 @@ Torbjörn Törnkvist 980703 A - erl_eterm.sgml + erl_eterm.xml erl_eterm Functions for Erlang Term Construction @@ -167,18 +167,18 @@ erl_free_compound(list); ETERM *erl_copy_term(term) - Creates a copy of an Erlang term + Creates a copy of an Erlang term. ETERM *term; -

This function creates and returns a copy of the Erlang term +

This function creates and returns a copy of the Erlang term .

 ETERM *erl_element(position, tuple) - Extracts an element from an Erlang tuple + Extracts an element from an Erlang tuple. int position; ETERM *tuple; @@ -195,38 +195,54 @@ erl_free_compound(list); the arity of .

 + + ETERM *erl_hd(list) + Extracts the first element from a list. + + ETERM *list; + + +

Extracts the first element from a list.

+

is an Erlang term containing a list.

+

The function returns an Erlang term corresponding to the + head element in the list, or a NULL pointer if was + not a list.

+ + voiderl_init(NULL, 0) - Initialization routine + Initialization routine. void *NULL; int 0; -

This function must be called before any of the others in +

This function must be called before any of the others in the library in order to initialize the - library functions. The arguments must be specified as + library functions. The arguments must be specified as .

 - ETERM *erl_hd(list) - Extracts the first element from a list + interl_iolist_length(list) + Return the length of an IO list. ETERM *list; -

Extracts the first element from a list.

-

is an Erlang term containing a list.

-

The function returns an Erlang term corresponding to the - head element in the list, or a NULL pointer if was - not a list.

+

Returns the length of an IO list. +

+

is an Erlang term containing an IO list.

+

The function returns the length of , or -1 if + is not an IO list.

+

Refer to for the definition of + an IO list.

ETERM *erl_iolist_to_binary(term) - Converts an IO list to a binary + Converts an IO list to a binary. ETERM *list; @@ -252,7 +268,7 @@ iohead ::= Binary char *erl_iolist_to_string(list) - Converts an IO list to a zero terminated string + Converts an IO list to a zero terminated string. ETERM *list; @@ -271,25 +287,9 @@ iohead ::= Binary IO list.

- - interl_iolist_length(list) - Return the length of an IO list - - ETERM *list; - - -

Returns the length of an IO list. -

-

is an Erlang term containing an IO list.

-

The function returns the length of , or -1 if - is not an IO list.

-

Refer to for the definition of - an IO list.

- - interl_length(list) - Determines the length of a list + Determines the length of a list. ETERM *list; @@ -303,7 +303,7 @@ iohead ::= Binary ETERM *erl_mk_atom(string) - Creates an atom + Creates an atom. const char *string; @@ -324,7 +324,7 @@ iohead ::= Binary ETERM *erl_mk_binary(bptr, size) - Creates a binary object + Creates a binary object. char *bptr; int size; @@ -336,13 +336,13 @@ iohead ::= Binary

indicates the length of .

The function returns an Erlang binary object.

retrieves a pointer to - the binary data. retrieves the + the binary data. retrieves the size.

ETERM *erl_mk_empty_list() - Creates an empty Erlang list + Creates an empty Erlang list.

This function creates and returns an empty Erlang list. Note that NULL is not used to represent an empty list; @@ -351,7 +351,7 @@ iohead ::= Binary ETERM *erl_mk_estring(string, len) - Creates an Erlang string + Creates an Erlang string. char *string; int len; @@ -367,7 +367,7 @@ iohead ::= Binary ETERM *erl_mk_float(f) - Creates an Erlang float + Creates an Erlang float. double f; @@ -385,7 +385,7 @@ iohead ::= Binary ETERM *erl_mk_int(n) - Creates an Erlang integer + Creates an Erlang integer. int n; @@ -395,13 +395,13 @@ iohead ::= Binary

The function returns an Erlang integer object with the value specified in .

-

can be used to retrieve the value +

can be used to retrieve the value value from an Erlang integer.

 ETERM *erl_mk_list(array, arrsize) - Creates a list from an array + Creates a list from an array. ETERM **array; int arrsize; @@ -417,9 +417,36 @@ iohead ::= Binary .

 + + ETERM *erl_mk_long_ref(node, n1, n2, n3, creation) + Creates an Erlang reference. + + const char *node; + unsigned int n1, n2, n3; + unsigned int creation; + + +

This function creates an Erlang reference, with 82 bits.

+

is the name of the C node.

+

, and can be seen as one big number + which should be chosen uniquely for + each reference + created for a given C node.

+

is an arbitrary number.

+

Note that and are limited in + precision, so only the low 18 and 2 bits of these numbers + are actually used. +

+

The function returns an Erlang reference object.

+

, , + and + to retrieve the values used + to create the reference.

+ + ETERM *erl_mk_pid(node, number, serial, creation) - Creates a process identifier + Creates a process identifier. const char *node; unsigned int number; @@ -443,7 +470,7 @@ iohead ::= Binary ETERM *erl_mk_port(node, number, creation) - Creates a port identifier + Creates a port identifier. const char *node; unsigned int number; @@ -464,7 +491,7 @@ iohead ::= Binary ETERM *erl_mk_ref(node, number, creation) - Creates an old Erlang reference + Creates an old Erlang reference. const char *node; unsigned int number; @@ -487,36 +514,9 @@ iohead ::= Binary to create the reference.

- - ETERM *erl_mk_long_ref(node, n1, n2, n3, creation) - Creates an Erlang reference - - const char *node; - unsigned int n1, n2, n3; - unsigned int creation; - - -

This function creates an Erlang reference, with 82 bits.

-

is the name of the C node.

-

, and can be seen as one big number - which should be chosen uniquely for - each reference - created for a given C node.

-

is an arbitrary number.

-

Note that and are limited in - precision, so only the low 18 and 2 bits of these numbers - are actually used. -

-

The function returns an Erlang reference object.

-

, , - and - to retrieve the values used - to create the reference.

- - ETERM *erl_mk_string(string) - Creates a string + Creates a string. char *string; @@ -529,7 +529,7 @@ iohead ::= Binary ETERM *erl_mk_tuple(array, arrsize) - Creates an Erlang tuple from an array + Creates an Erlang tuple from an array. ETERM **array; int arrsize; @@ -553,7 +553,7 @@ iohead ::= Binary ETERM *erl_mk_uint(n) - Creates an unsigned integer + Creates an unsigned integer. unsigned int n; @@ -570,7 +570,7 @@ iohead ::= Binary ETERM *erl_mk_var(name) - Creates an Erlang variable + Creates an Erlang variable. char *name; @@ -584,7 +584,7 @@ iohead ::= Binary interl_print_term(stream, term) - Prints an Erlang term + Prints an Erlang term. FILE *stream; ETERM *term; @@ -601,7 +601,7 @@ iohead ::= Binary voiderl_set_compat_rel(release_number) - Set the erl_interface library in compatibility mode + Set the erl_interface library in compatibility mode. unsigned release_number; @@ -633,7 +633,7 @@ iohead ::= Binary interl_size(term) - Return the arity of a tuple or binary + Return the arity of a tuple or binary. ETERM *term; @@ -648,7 +648,7 @@ iohead ::= Binary ETERM *erl_tl(list) - Extracts the tail from a list + Extracts the tail from a list. ETERM *list; @@ -662,14 +662,14 @@ iohead ::= Binary ETERM *erl_var_content(term, name) - Extracts the content of a variable + Extracts the content of a variable. ETERM *term; char *name;

This function returns the contents of the specified - variable in an Erlang term. + variable in an Erlang term.

is an Erlang term. In order for this function to succeed, must be an Erlang variable with the @@ -685,4 +685,3 @@ iohead ::= Binary - diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml index 6e3ac4f0c9..ce5163fbc7 100644 --- a/lib/erl_interface/doc/src/erl_format.xml +++ b/lib/erl_interface/doc/src/erl_format.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + erl_format @@ -30,7 +30,7 @@ Torbjörn Törnkvist 961016 A - erl_format.sgml + erl_format.xml erl_format Create and Match Erlang Terms @@ -41,7 +41,7 @@ ETERM *erl_format(FormatStr, ... ) - Creates an Erlang term + Creates an Erlang term. char *FormatStr; @@ -81,7 +81,7 @@ erl_format("[{name,~a},{age,~i},{data,~w}]", erl_format("[{adr,~s,~i}]","E-street",42)); ]]>

This will create an structure corresponding - to the Erlang term: + to the Erlang term:

The function returns an Erlang term, or NULL if does not describe a valid Erlang term.

@@ -89,7 +89,7 @@ erl_format("[{name,~a},{age,~i},{data,~w}]", interl_match(Pattern, Term) - Performs pattern matching + Performs pattern matching. ETERM *Pattern,*Term; @@ -139,4 +139,3 @@ if (erl_match(pattern2, term2)) { - diff --git a/lib/erl_interface/doc/src/erl_global.xml b/lib/erl_interface/doc/src/erl_global.xml index d6bfffc69d..69f303722d 100644 --- a/lib/erl_interface/doc/src/erl_global.xml +++ b/lib/erl_interface/doc/src/erl_global.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + erl_global @@ -30,7 +30,7 @@ Gordon Beaton 980703 A - erl_global.sgml + erl_global.xml erl_global Access globally registered names @@ -39,14 +39,14 @@ up and unregistering names in the Erlang Global module. For more information, see the description of Global in the reference manual.

Note that the functions below perform an RPC using an open file - descriptor provided by the caller. This file descriptor must - not be used for other traffic during the global operation or the + descriptor provided by the caller. This file descriptor must + not be used for other traffic during the global operation or the function may receive unexpected data and fail.

char **erl_global_names(fd,count) - Obtain list of Global names + Obtain list of Global names. int fd; int *count; @@ -76,7 +76,7 @@ interl_global_register(fd,name,pid) - Register a name in Global + Register a name in Global. int fd; const char *name; @@ -98,7 +98,7 @@ interl_global_unregister(fd,name) - Unregister a name in Global + Unregister a name in Global. int fd; const char *name; @@ -115,7 +115,7 @@ ETERM *erl_global_whereis(fd,name,node) - Look up a name in global + Look up a name in global. int fd; const char *name; @@ -139,4 +139,3 @@ - diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml index 799c903b1a..ba1f59a492 100644 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ b/lib/erl_interface/doc/src/erl_malloc.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + erl_malloc @@ -30,7 +30,7 @@ Torbjörn Törnkvist 980703 A - erl_malloc.sgml + erl_malloc.xml erl_malloc Memory Allocation Functions @@ -41,7 +41,7 @@ ETERM *erl_alloc_eterm(etype) - Allocates an ETERM structure + Allocates an ETERM structure. unsigned char etype; @@ -101,9 +101,9 @@ voiderl_eterm_release(void) - Clears the ETERM freelist + Clears the ETERM freelist. -

Clears the +

Clears the freelist, where blocks are placed when they are released by and .

@@ -111,7 +111,7 @@ voiderl_eterm_statistics(allocated, freed) - Reports term allocation statistics + Reports term allocation statistics. long *allocated; long *freed; @@ -126,9 +126,20 @@ .

+ + voiderl_free(ptr) + Frees some memory. + + void *ptr; + + +

This function calls the standard + function.

+ + voiderl_free_array(array, size) - Frees an array of ETERM structures + Frees an array of ETERM structures. ETERM **array; int size; @@ -140,19 +151,9 @@

is the number of terms in the array.

 - - voiderl_free_term(t) - Frees an ETERM structure - - ETERM *t; - - -

Use this function to free an Erlang term.

- - voiderl_free_compound(t) - Frees an array of ETERM structures + Frees an array of ETERM structures. ETERM *t; @@ -175,27 +176,25 @@ - voiderl_malloc(size) - Allocates some memory + voiderl_free_term(t) + Frees an ETERM structure. - long size; + ETERM *t; -

This function calls the standard - function.

+

Use this function to free an Erlang term.

 - voiderl_free(ptr) - Frees some memory + voiderl_malloc(size) + Allocates some memory. - void *ptr; + long size; -

This function calls the standard - function.

+

This function calls the standard + function.

- diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml index 7c56089016..c70bdb53e1 100644 --- a/lib/erl_interface/doc/src/erl_marshal.xml +++ b/lib/erl_interface/doc/src/erl_marshal.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + erl_marshal @@ -30,7 +30,7 @@ Torbjörn Törnkvist 980703 A - erl_marshal.sgml + erl_marshal.xml erl_marshal Encoding and Decoding of Erlang terms @@ -42,7 +42,7 @@ interl_compare_ext(bufp1, bufp2) - Compares encoded byte sequences + Compares encoded byte sequences. unsigned char *bufp1,*bufp2; @@ -56,14 +56,14 @@ term term2.

The function returns 0 if the terms are equal, -1 if term1 - is less than term2, or 1 if term2 is less than term1. + is less than term2, or 1 if term2 is less than term1.

ETERM *erl_decode(bufp) ETERM *erl_decode_buf(bufpp) - Converts a term from Erlang external format + Converts a term from Erlang external format. unsigned char *bufp; unsigned char **bufpp; @@ -79,7 +79,7 @@

is the address of a buffer pointer. The buffer contains one or more consecutively encoded Erlang terms. - Following a successful call to , + Following a successful call to , will be updated so that it points to the next encoded term.

@@ -96,14 +96,14 @@ interl_encode(term, bufp) interl_encode_buf(term, bufpp) - Converts a term into Erlang external format + Converts a term into Erlang external format. ETERM *term; unsigned char *bufp; unsigned char **bufpp; -

and encode +

and encode Erlang terms into external format for storage or transmission. provides a simple mechanism for encoding several terms consecutively in the same @@ -116,13 +116,13 @@

bufpp is a pointer to a pointer to a buffer containing one or more consecutively encoded Erlang terms. - Following a successful call to , + Following a successful call to , bufpp will be updated so that it points to the position for the next encoded term.

These functions returns the number of bytes written to buffer - if successful, otherwise returns 0. + if successful, otherwise returns 0.

Note that no bounds checking is done on the buffer. It is the caller's responsibility to make sure that the buffer is @@ -165,14 +165,14 @@ is an atom.

The total space required will be the result calculated - from the information above, plus 1 additional byte for a + from the information above, plus 1 additional byte for a version identifier.

interl_ext_size(bufp) - Counts elements in encoded term + Counts elements in encoded term. unsigned char *bufp; @@ -183,7 +183,7 @@ unsigned charerl_ext_type(bufp) - Determines type of an encoded byte sequence + Determines type of an encoded byte sequence. unsigned char *bufp; @@ -230,7 +230,7 @@ unsigned char *erl_peek_ext(bufp, pos) - Steps over encoded term + Steps over encoded term. unsigned char *bufp; int pos; @@ -244,7 +244,7 @@ more encoded Erlang terms.

indicates how many terms to step over in the - buffer. + buffer.

The function returns a pointer to a sub-term that can be used in a subsequent call to in order to retrieve @@ -255,7 +255,7 @@ interl_term_len(t) - Determines encoded size of term + Determines encoded size of term. ETERM *t; @@ -270,4 +270,3 @@ - diff --git a/lib/erl_interface/doc/src/ref_man.xml b/lib/erl_interface/doc/src/ref_man.xml index 0cf060829b..e23f00956a 100644 --- a/lib/erl_interface/doc/src/ref_man.xml +++ b/lib/erl_interface/doc/src/ref_man.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + Erl_Interface Command Reference Gordon Beaton @@ -53,4 +53,3 @@ - diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml index 285a2402b8..fd3e29c30f 100644 --- a/lib/erl_interface/doc/src/registry.xml +++ b/lib/erl_interface/doc/src/registry.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + registry @@ -30,10 +30,10 @@ Gordon Beaton 980707 A - registry.sgml + registry.xml registry - Store and backup key-value pairs + Store and backup key-value pairs.

This module provides support for storing key-value pairs in a table known as a registry, backing up registries to @@ -41,52 +41,9 @@ registry from Mnesia.

- - ei_reg *ei_reg_open(size) - Create and open a registry - - int size; - - -

Open (create) a registry. The registry will be - initially empty. Use to close the registry - later. -

-

is the approximate number of objects you intend - to store in the registry. Since the registry uses a hash table - with collision chaining, there is no absolute upper limit on the - number of objects that can be stored in it. However for reasons - of efficiency, it is a good idea to choose a number that is - appropriate for your needs. It is possible to use - to change the size later. Note that the - number you provide will be increased to the nearest larger prime - number. -

-

On success, an empty registry will be returned. On failure, NULL - will be returned.

- - - - intei_reg_resize(reg,newsize) - Resize a registry - - ei_reg *reg; - int newsize; - - -

Change the size of a registry. -

-

is the new size to make the registry. The - number will be increased to the nearest larger prime number. -

-

On success, the registry will be resized, all contents - rehashed, and the function will return 0. On failure, the - registry will be left unchanged and the function will return -1.

- - intei_reg_close(reg) - Close a registry + Close a registry. ei_reg *reg; @@ -101,153 +58,83 @@ - intei_reg_setival(reg,key,i) - Assign an integer object - - ei_reg *reg; - const char *key; - int i; - - -

Create a key-value pair with the specified and integer - value . If an object already existed with the same - , the new value replaces the old one. If the previous - value was a binary or string, it is freed with . -

-

is the registry where the object should be placed. -

-

is the name of the object. -

-

is the integer value to assign. -

-

The function returns 0 on success, or -1 on failure.

- - - - intei_reg_setfval(reg,key,f) - Assign a floating point object - - ei_reg *reg; - const char *key; - double f; - - -

Create a key-value pair with the specified and - floating point value . If an object already existed with - the same , the new value replaces the old one. If the - previous value was a binary or string, it is freed with . -

-

is the registry where the object should be placed. -

-

is the name of the object. -

-

is the floating point value to assign. -

-

The function returns 0 on success, or -1 on failure.

- - - - intei_reg_setsval(reg,key,s) - Assign a string object - - ei_reg *reg; - const char *key; - const char *s; - - -

Create a key-value pair with the specified whose - "value" is the specified string . If an object already - existed with the same , the new value replaces the old - one. If the previous value was a binary or string, it is freed - with . -

-

is the registry where the object should be placed. -

-

is the name of the object. -

-

is the string to assign. The string itself - must have been created through a single call to or - similar function, so that the registry can later delete it if - necessary by calling . -

-

The function returns 0 on success, or -1 on failure.

- - - - intei_reg_setpval(reg,key,p,size) - Assign a binary object + intei_reg_delete(reg,key) + Delete an object from the registry. ei_reg *reg; const char *key; - const void *p; - int size; -

Create a key-value pair with the specified whose - "value" is the binary object pointed to by . If an - object already existed with the same , the new value - replaces the old one. If the previous value was a binary or - string, it is freed with . -

-

is the registry where the object should be placed. +

Delete an object from the registry. The object is not + actually removed from the registry, it is only marked for later + removal so that on subsequent backups to Mnesia, the + corresponding object can be removed from the Mnesia table as + well. If another object is later created with the same key, the + object will be reused.

-

is the name of the object. +

The object will be removed from the registry after a call to + or .

-

is a pointer to the binary object. The object itself - must have been created through a single call to or - similar function, so that the registry can later delete it if - necessary by calling . +

is the registry containing .

-

is the length in bytes of the binary object. +

is the object to remove.

-

The function returns 0 on success, or -1 on failure.

+

If the object was found, the function returns 0 indicating + success. Otherwise the function returns -1.

 - intei_reg_setval(reg,key,flags,v,...) - Assign a value to any object type + intei_reg_dump(fd,reg,mntab,flags) + Back up a registry to Mnesia. + int fd; ei_reg *reg; - const char *key; + const char *mntab; int flags; - v (see below) -

Create a key-value pair with the specified whose - value is specified by . If an object already - existed with the same , the new value replaces the old - one. If the previous value was a binary or string, it is freed - with . +

Dump the contents of a registry to a Mnesia table in an + atomic manner, i.e. either all data will be updated, or none of + it will. If any errors are encountered while backing up + the data, the entire operation is aborted.

-

is the registry where the object should be placed. +

is an open connection to Erlang. + Mnesia 3.0 or later must be running on the Erlang node.

-

is the name of the object. +

is the registry to back up.

-

indicates the type of the object specified by - . Flags must be one of EI_INT, EI_FLT, EI_STR and - EI_BIN, indicating whether is , , - or . If is EI_BIN, then a - fifth argument is required, indicating the size - in bytes of the object pointed to by . +

is the name of the Mnesia table where the backed + up data should be placed. If the table does not exist, it will + be created automatically using configurable defaults. See your + Mnesia documentation for information about configuring this + behaviour.

-

If you wish to store an arbitrary pointer in the registry, - specify a of 0. In this case, the object itself will - not be transferred by an operation, just - the pointer value. +

If is 0, the backup will include only those + objects which have been created, modified or deleted since the + last backup or restore (i.e. an incremental backup). After the + backup, any objects that were marked dirty are now clean, and any + objects that had been marked for deletion are deleted. +

+

Alternatively, setting flags to EI_FORCE will cause a full + backup to be done, and EI_NOPURGE will cause the deleted objects + to be left in the registry afterwards. These can be bitwise ORed + together if both behaviours are desired. If EI_NOPURGE was + specified, you can use to explicitly remove + the deleted items from the registry later.

The function returns 0 on success, or -1 on failure.

 - intei_reg_getival(reg,key) - Get an integer object + doubleei_reg_getfval(reg,key) + Get a floating point object. ei_reg *reg; const char *key;

Get the value associated with in the - registry. The value must be an integer. + registry. The value must be a floating point type.

is the registry where the object will be looked up. @@ -255,23 +142,23 @@

is the name of the object to look up.

On success, the function returns the value associated with . - If the object was not found or it was not an integer - object, -1 is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between -1 and a + If the object was not found or it was not a floating point + object, -1.0 is returned. To avoid problems with in-band error + reporting (i.e. if you cannot distinguish between -1.0 and a valid result) use the more general function instead.

 - doubleei_reg_getfval(reg,key) - Get a floating point object + intei_reg_getival(reg,key) + Get an integer object. ei_reg *reg; const char *key;

Get the value associated with in the - registry. The value must be a floating point type. + registry. The value must be an integer.

is the registry where the object will be looked up. @@ -279,31 +166,36 @@

is the name of the object to look up.

On success, the function returns the value associated with . - If the object was not found or it was not a floating point - object, -1.0 is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between -1.0 and a + If the object was not found or it was not an integer + object, -1 is returned. To avoid problems with in-band error + reporting (i.e. if you cannot distinguish between -1 and a valid result) use the more general function instead.

 - const char *ei_reg_getsval(reg,key) - Get a string object + const void *ei_reg_getpval(reg,key,size) + Get a binary object. ei_reg *reg; const char *key; + int size;

Get the value associated with in the - registry. The value must be a string. + registry. The value must be a binary (pointer) type.

is the registry where the object will be looked up.

is the name of the object to look up.

+

will be initialized to contain the length in + bytes of the object, if it is found. +

On success, the function returns the value associated with - . If the object was not found or it was not a string, + and indicates its length in . + If the object was not found or it was not a binary object, NULL is returned. To avoid problems with in-band error reporting (i.e. if you cannot distinguish between NULL and a valid result) use the more general function @@ -311,28 +203,23 @@ - const void *ei_reg_getpval(reg,key,size) - Get a binary object + const char *ei_reg_getsval(reg,key) + Get a string object. ei_reg *reg; const char *key; - int size;

Get the value associated with in the - registry. The value must be a binary (pointer) type. + registry. The value must be a string.

is the registry where the object will be looked up.

is the name of the object to look up.

-

will be initialized to contain the length in - bytes of the object, if it is found. -

On success, the function returns the value associated with - and indicates its length in . - If the object was not found or it was not a binary object, + . If the object was not found or it was not a string, NULL is returned. To avoid problems with in-band error reporting (i.e. if you cannot distinguish between NULL and a valid result) use the more general function @@ -341,7 +228,7 @@ intei_reg_getval(reg,key,flags,v,...) - Get any object + Get any object. ei_reg *reg; const char *key; @@ -350,7 +237,7 @@

This is a general function for retrieving any kind of - object from the registry. + object from the registry.

is the registry where the object will be looked up. @@ -376,7 +263,7 @@ intei_reg_markdirty(reg,key) - Mark an object as dirty + Mark an object as dirty. ei_reg *reg; const char *key; @@ -390,7 +277,7 @@ registry and modified the contents, then the change will be invisible to the registry and the object will be assumed to be unmodified. This function allows you to make such modifications - and then let the registry know about them. + and then let the registry know about them.

is the registry containing the object.

@@ -400,34 +287,248 @@ - intei_reg_delete(reg,key) - Delete an object from the registry + ei_reg *ei_reg_open(size) + Create and open a registry. - ei_reg *reg; - const char *key; + int size; -

Delete an object from the registry. The object is not - actually removed from the registry, it is only marked for later - removal so that on subsequent backups to Mnesia, the - corresponding object can be removed from the Mnesia table as - well. If another object is later created with the same key, the - object will be reused. -

-

The object will be removed from the registry after a call to - or . -

-

is the registry containing . +

Open (create) a registry. The registry will be + initially empty. Use to close the registry + later.

-

is the object to remove. +

is the approximate number of objects you intend + to store in the registry. Since the registry uses a hash table + with collision chaining, there is no absolute upper limit on the + number of objects that can be stored in it. However for reasons + of efficiency, it is a good idea to choose a number that is + appropriate for your needs. It is possible to use + to change the size later. Note that the + number you provide will be increased to the nearest larger prime + number.

-

If the object was found, the function returns 0 indicating - success. Otherwise the function returns -1.

+

On success, an empty registry will be returned. On failure, NULL + will be returned.

+ + + + intei_reg_purge(reg) + Remove deleted objects. + + ei_reg *reg; + + +

Remove all objects marked for deletion. When objects + are deleted with they are not actually + removed from the registry, only marked for later removal. This + is so that on a subsequent backup to Mnesia, the + objects can also be removed from the Mnesia table. If you are + not backing up to Mnesia then you may wish to remove the objects + manually with this function. +

+

is a registry containing objects marked for + deletion. +

+

The function returns 0 on success, or -1 on failure.

+ + + + intei_reg_resize(reg,newsize) + Resize a registry. + + ei_reg *reg; + int newsize; + + +

Change the size of a registry. +

+

is the new size to make the registry. The + number will be increased to the nearest larger prime number. +

+

On success, the registry will be resized, all contents + rehashed, and the function will return 0. On failure, the + registry will be left unchanged and the function will return -1.

+ + + + intei_reg_restore(fd,reg,mntab) + Restore a registry from Mnesia. + + int fd; + ei_reg *reg; + const char *mntab; + + +

The contents of a Mnesia table are read into the + registry. +

+

is an open connection to Erlang. + Mnesia 3.0 or later must be running on the Erlang node. +

+

is the registry where the data should be placed. +

+

is the name of the Mnesia table to read data + from. +

+

Note that only tables of a certain format can be + restored, i.e. those that have been created and backed up to + with . If the registry was not empty before + the operation, then the contents of the table are added to the + contents of the registry. If the table contains objects with the + same keys as those already in the registry, the registry objects + will be overwritten with the new values. If the registry + contains objects that were not in the table, they will be + unchanged by this operation. +

+

After the restore operation, the entire contents of the + registry is marked as unmodified. Note that this includes any + objects that were modified before the restore and not + overwritten by the restore. +

+

The function returns 0 on success, or -1 on failure.

+ + + + intei_reg_setfval(reg,key,f) + Assign a floating point object. + + ei_reg *reg; + const char *key; + double f; + + +

Create a key-value pair with the specified and + floating point value . If an object already existed with + the same , the new value replaces the old one. If the + previous value was a binary or string, it is freed with . +

+

is the registry where the object should be placed. +

+

is the name of the object. +

+

is the floating point value to assign. +

+

The function returns 0 on success, or -1 on failure.

+ + + + intei_reg_setival(reg,key,i) + Assign an integer object. + + ei_reg *reg; + const char *key; + int i; + + +

Create a key-value pair with the specified and integer + value . If an object already existed with the same + , the new value replaces the old one. If the previous + value was a binary or string, it is freed with . +

+

is the registry where the object should be placed. +

+

is the name of the object. +

+

is the integer value to assign. +

+

The function returns 0 on success, or -1 on failure.

+ + + + intei_reg_setpval(reg,key,p,size) + Assign a binary object. + + ei_reg *reg; + const char *key; + const void *p; + int size; + + +

Create a key-value pair with the specified whose + "value" is the binary object pointed to by . If an + object already existed with the same , the new value + replaces the old one. If the previous value was a binary or + string, it is freed with . +

+

is the registry where the object should be placed. +

+

is the name of the object. +

+

is a pointer to the binary object. The object itself + must have been created through a single call to or + similar function, so that the registry can later delete it if + necessary by calling . +

+

is the length in bytes of the binary object. +

+

The function returns 0 on success, or -1 on failure.

+ + + + intei_reg_setsval(reg,key,s) + Assign a string object. + + ei_reg *reg; + const char *key; + const char *s; + + +

Create a key-value pair with the specified whose + "value" is the specified string . If an object already + existed with the same , the new value replaces the old + one. If the previous value was a binary or string, it is freed + with . +

+

is the registry where the object should be placed. +

+

is the name of the object. +

+

is the string to assign. The string itself + must have been created through a single call to or + similar function, so that the registry can later delete it if + necessary by calling . +

+

The function returns 0 on success, or -1 on failure.

+ + + + intei_reg_setval(reg,key,flags,v,...) + Assign a value to any object type. + + ei_reg *reg; + const char *key; + int flags; + v (see below) + + +

Create a key-value pair with the specified whose + value is specified by . If an object already + existed with the same , the new value replaces the old + one. If the previous value was a binary or string, it is freed + with . +

+

is the registry where the object should be placed. +

+

is the name of the object. +

+

indicates the type of the object specified by + . Flags must be one of EI_INT, EI_FLT, EI_STR and + EI_BIN, indicating whether is , , + or . If is EI_BIN, then a + fifth argument is required, indicating the size + in bytes of the object pointed to by . +

+

If you wish to store an arbitrary pointer in the registry, + specify a of 0. In this case, the object itself will + not be transferred by an operation, just + the pointer value. +

+

The function returns 0 on success, or -1 on failure.

 intei_reg_stat(reg,key,obuf) - Get object information + Get object information. ei_reg *reg; const char *key; @@ -452,7 +553,7 @@ struct ei_reg_stat {

In the object's attributes are stored as the logical OR of its type (one of EI_INT, EI_FLT, EI_BIN and EI_STR), whether it is marked for deletion (EI_DELET) and whether it has - been modified since the last backup to Mnesia (EI_DIRTY). + been modified since the last backup to Mnesia (EI_DIRTY).

The field indicates the size in bytes required to store EI_STR (including the terminating 0) and EI_BIN objects, or 0 @@ -464,7 +565,7 @@ struct ei_reg_stat { intei_reg_tabstat(reg,obuf) - Get registry information + Get registry information. ei_reg *reg; struct ei_reg_tabstat *obuf; @@ -496,7 +597,7 @@ struct ei_reg_tabstat { registry. It includes objects that are deleted but not purged.

indicates the number of unique positions that are - occupied in the registry. + occupied in the registry.

indicates how many elements are sharing positions in the registry. @@ -506,107 +607,5 @@ struct ei_reg_tabstat { returns -1.

 - - intei_reg_dump(fd,reg,mntab,flags) - Back up a registry to Mnesia - - int fd; - ei_reg *reg; - const char *mntab; - int flags; - - -

Dump the contents of a registry to a Mnesia table in an - atomic manner, i.e. either all data will be updated, or none of - it will. If any errors are encountered while backing up - the data, the entire operation is aborted. -

-

is an open connection to Erlang. - Mnesia 3.0 or later must be running on the Erlang node. -

-

is the registry to back up. -

-

is the name of the Mnesia table where the backed - up data should be placed. If the table does not exist, it will - be created automatically using configurable defaults. See your - Mnesia documentation for information about configuring this - behaviour. -

-

If is 0, the backup will include only those - objects which have been created, modified or deleted since the - last backup or restore (i.e. an incremental backup). After the - backup, any objects that were marked dirty are now clean, and any - objects that had been marked for deletion are deleted. -

-

Alternatively, setting flags to EI_FORCE will cause a full - backup to be done, and EI_NOPURGE will cause the deleted objects - to be left in the registry afterwards. These can be bitwise ORed - together if both behaviours are desired. If EI_NOPURGE was - specified, you can use to explicitly remove - the deleted items from the registry later. -

-

The function returns 0 on success, or -1 on failure.

- - - - intei_reg_restore(fd,reg,mntab) - Restore a registry from Mnesia - - int fd; - ei_reg *reg; - const char *mntab; - - -

The contents of a Mnesia table are read into the - registry. -

-

is an open connection to Erlang. - Mnesia 3.0 or later must be running on the Erlang node. -

-

is the registry where the data should be placed. -

-

is the name of the Mnesia table to read data - from. -

-

Note that only tables of a certain format can be - restored, i.e. those that have been created and backed up to - with . If the registry was not empty before - the operation, then the contents of the table are added to the - contents of the registry. If the table contains objects with the - same keys as those already in the registry, the registry objects - will be overwritten with the new values. If the registry - contains objects that were not in the table, they will be - unchanged by this operation. -

-

After the restore operation, the entire contents of the - registry is marked as unmodified. Note that this includes any - objects that were modified before the restore and not - overwritten by the restore. -

-

The function returns 0 on success, or -1 on failure.

- - - - intei_reg_purge(reg) - Remove deleted objects - - ei_reg *reg; - - -

Remove all objects marked for deletion. When objects - are deleted with they are not actually - removed from the registry, only marked for later removal. This - is so that on a subsequent backup to Mnesia, the - objects can also be removed from the Mnesia table. If you are - not backing up to Mnesia then you may wish to remove the objects - manually with this function. -

-

is a registry containing objects marked for - deletion. -

-

The function returns 0 on success, or -1 on failure.

- - - -- cgit v1.2.3 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 ++++++++++++----------- lib/erl_interface/doc/src/ei_connect.xml | 776 +++++++++++++++++---------- lib/erl_interface/doc/src/ei_users_guide.xml | 692 +++++++++++++++--------- lib/erl_interface/doc/src/erl_call.xml | 196 ++++--- lib/erl_interface/doc/src/erl_connect.xml | 546 +++++++++++-------- lib/erl_interface/doc/src/erl_error.xml | 63 ++- lib/erl_interface/doc/src/erl_eterm.xml | 588 +++++++++++--------- lib/erl_interface/doc/src/erl_format.xml | 88 ++- lib/erl_interface/doc/src/erl_global.xml | 122 +++-- lib/erl_interface/doc/src/erl_malloc.xml | 155 +++--- lib/erl_interface/doc/src/erl_marshal.xml | 258 +++++---- lib/erl_interface/doc/src/part.xml | 2 +- lib/erl_interface/doc/src/ref_man.xml | 13 +- lib/erl_interface/doc/src/registry.xml | 680 ++++++++++++----------- 14 files changed, 2774 insertions(+), 2091 deletions(-) (limited to 'lib/erl_interface') 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

diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index 8cc08f86cd..a5a020ffda 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -25,57 +25,66 @@ ei_connect Jakob Cederlund - ? - ? + + 2001-09-01 A ei_connect.xml ei_connect - Communicate with distributed erlang + Communicate with distributed Erlang. -

This module enables C programs to communicate with erlang nodes, - using the erlang distribution over TCP/IP.

-

A C node appears to Erlang as a - hidden node. +

This module enables C-programs to communicate with Erlang nodes, + using the Erlang distribution over TCP/IP.

+ +

A C-node appears to Erlang as a hidden node. That is, Erlang processes that know the name of the - C node are able to communicate with it in a normal manner, but - the node name will not appear in the listing provided by the - Erlang function .

+ C-node can communicate with it in a normal manner, but + the node name is not shown in the listing provided by + erlang:nodes/0 + in ERTS.

+

The environment variable can be used - to indicate which logical cluster a C node belongs to.

+ to indicate which logical cluster a C-node belongs to.
- Timeout functions + Time-Out Functions

Most functions appear in a version with the suffix - appended to the function name. Those function take - an additional argument, a timeout in milliseconds. The - semantics is this; for each communication primitive involved in + appended to the function name. Those functions + take an extra argument, a time-out in milliseconds. The + semantics is this: for each communication primitive involved in the operation, if the primitive does not complete within the time - specified, the function will return an error and - will be set to . With - communication primitive is meant an operation on the socket, like - , , or .

-

Obviously the timeouts are for implementing fault tolerance, - not to keep hard realtime promises. The functions + specified, the function returns an error and + is set to . + With communication primitive is meant an operation on the socket, like + , , + , or .

+ +

Clearly the time-outs are for implementing fault tolerance, + not to keep hard real-time promises. The functions are for detecting non-responsive peers and to avoid blocking on - socket operations.

-

A timeout value of (zero), means that timeouts are - disabled. Calling a -function with the last argument as - is therefore exactly the same thing as calling the - function without the suffix.

-

As with all other ei functions, you are not expected - to put the socket in non blocking mode yourself in the program. Every - use of non blocking mode is embedded inside the timeout + socket operations.

+ +

A time-out value of (zero) means that time-outs are + disabled. Calling a function with the last + argument as is therefore the same thing as calling + the function without the suffix.

+ +

As with all other functions starting with ei_, + you are not expected + to put the socket in non-blocking mode yourself in the program. Every + use of non-blocking mode is embedded inside the time-out functions. The socket will always be back in blocking mode after the operations are completed (regardless of the result). To - avoid problems, leave the socket options alone. Ei will handle + avoid problems, leave the socket options alone. ei handles any socket options that need modification.

+

In all other senses, the functions inherit all the return values and the semantics from the functions without the suffix.

+ struct hostent*ei_gethostbyaddr(const char *addr, int len, int type) @@ -84,69 +93,88 @@ struct hostent*ei_gethostbyname_r(const char *name, struct hostent *hostp, char *buffer, int buflen, int *h_errnop) Name lookup functions. -

These are convenience functions for some common name lookup functions.

+

Convenience functions for some common name lookup functions.

 + intei_accept(ei_cnode *ec, int listensock, ErlConnect *conp) Accept a connection from another node. -

This function is used by a server process to accept a +

Used by a server process to accept a connection from a client process.

-

is the C-node structure.

-

is an open socket descriptor on which - has previously been called.

-

is a pointer to an struct, - described as follows:

- + +

is the C-node structure.

+ + +

is an open socket descriptor on + which has previously been called.

+ + +

is a pointer to an + struct, described as follows:

+ + +

On success, is filled in with the address and node name of the connecting client and a file descriptor is returned. On failure, is returned and is set to .

 + intei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms) - Accept a connection from another node with optional timeout. + Accept a connection from another node with optional + time-out. -

ei_accept with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to + ei_accept with an optional time-out argument, + see the description at the beginning of this manual page.

 + intei_connect(ei_cnode* ec, char *nodename) intei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename) - Establishe a connection to an Erlang node. + Establish a connection to an Erlang node. -

These functions set up a connection to an Erlang node.

-

requires the IP address of the remote - host and the alive name of the remote node - to be specified. provides an alternative - interface, and determines the information from the node name +

Sets up a connection to an Erlang node.

+

requires the IP address of the + remote host and the alive name of the remote node to be + specified. provides an alternative + interface and determines the information from the node name provided.

-

is the 32-bit IP address of the remote host.

-

is the alivename of the remote node.

-

is the name of the remote node.

+ + is the 32-bit IP address of the remote + host. + is the alivename of the remote node. + + is the name of the remote node. +

These functions return an open file descriptor on success, or - a negative value indicating that an error occurred --- in - which case they will set to one of:

+ a negative value indicating that an error occurred. In the latter + case they set to one of the + following:

- The remote host is unreachable + The remote host is unreachable. - No more memory available. + No more memory is available. I/O error. -

Additionally, values from - (2) and (2) +

Also, values from + (2) and + (2) system calls may be propagated into .

-

Example:

+

Example:

 + intei_connect_init(ei_cnode* ec, const char* this_node_name, const char *cookie, short creation) intei_connect_xinit(ei_cnode* ec, const char *thishostname, const char *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr, const char *cookie, short creation) Initialize for a connection. -

These function initializes the structure, to +

Initializes the structure, to identify the node name and cookie of the server. One of them - has to be called before other functions that works on the - type or a file descriptor associated with a - connection to another node are used.

-

is a structure containing information about the - C-node. It is used in other functions for - connecting and receiving data.

-

is the registered name of the process - (the name before '@').

-

is the cookie for the node.

-

identifies a specific instance of a C - node. It can help prevent the node from receiving messages - sent to an earlier process with the same registered name.

-

is the name of the machine we're running - on. If long names are to be used, it should be fully - qualified (i.e. instead of - ).

-

is the registered name of the process.

-

is the full name of the node, - i.e. .

-

if the IP address of the host.

-

A C node acting as a server will be assigned a creation + must be called before other functions that works on the + type or a file descriptor associated with + a connection to another node is used.

+ + +

is a structure containing information about + the C-node. It is used in other functions + for connecting and receiving data.

+ + +

is the registered name of the + process (the name before '@').

+ + +

is the cookie for the node.

+ + +

identifies a specific instance of a + C-node. It can help prevent the node from receiving messages + sent to an earlier process with the same registered name.

+ + +

is the name of the machine we are + running on. If long names are to be used, they are to be fully + qualified (that is, + instead of ).

+ + +

is the registered name of the + process.

+ + +

is the full name of the node, + that is, .

+ + +

if the IP address of the host.

+ + +

A C-node acting as a server is assigned a creation number when it calls .

-

A connection is closed by simply closing the socket. Refer - to system documentation to close the socket gracefully (when - there are outgoing packets before close).

-

This function return a negative value indicating that an error +

A connection is closed by simply closing the socket. + For information about how to close the socket gracefully (when + there are outgoing packets before close), see the relevant system + documentation.

+

These functions return a negative value indicating that an error occurred.

-

Example 1: -

+

Example 1:

-

Example 2: -

+

Example 2:

 + intei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms) intei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms) - Establish a connection to an Erlang node with optional timeout. + Establish a connection to an Erlang node with optional + time-out. -

ei_connect and ei_xconnect with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to + ei_connect and ei_xconnect with an optional time-out + argument, see the description at the beginning of this manual + page.

 + intei_get_tracelevel(void) voidei_set_tracelevel(int level) Get and set functions for tracing. -

These functions are used to set tracing on the distribution. The levels are different verbosity levels. A higher level means more information. - See also Debug Information and below.

-

and are not thread safe.

+

Used to set tracing on the distribution. The levels are different + verbosity levels. A higher level means more information. See also + section + Debug Information.

+

These functions are not thread safe.

 + intei_publish(ei_cnode *ec, int port) Publish a node name. -

These functions are used by a server process to register +

Used by a server process to register with the local name server epmd, thereby allowing other processes to send messages by using the registered name. Before calling either of these functions, the process should - have called and on an open socket.

-

is the C-node structure.

-

is the local name to register, and should be the - same as the port number that was previously bound to the socket.

-

is the 32-bit IP address of the local host.

-

To unregister with epmd, simply close the returned - descriptor. Do not use , which is deprecated anyway.

-

On success, the functions return a descriptor connecting the - calling process to epmd. On failure, they return -1 and set - to .

-

Additionally, values from (2) - and (2) system calls may be propagated + have called and + on an open socket.

+ + +

is the C-node structure.

+ + +

is the local name to register, and is to + be the same as the port number that was previously bound to the + socket.

+ + +

is the 32-bit IP address of the local + host.

+ + +

To unregister with EPMD, simply close the returned descriptor. Do + not use , which is deprecated + anyway.

+

On success, the function returns a descriptor connecting the + calling process to EPMD. On failure, -1 is returned and + is set to .

+

Also, values from + (2) and + (2) system calls may be propagated into .

 + intei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms) - Publish a node name with optional timeout. + Publish a node name with optional time-out. -

ei_publish with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to + ei_publish with an optional time-out argument, + see the description at the beginning of this manual page.

 + intei_receive(int fd, unsigned char* bufp, int bufsize) Receive a message. + -

This function receives a message consisting of a sequence +

Receives a message consisting of a sequence of bytes in the Erlang external format.

-

is an open descriptor to an Erlang connection. It - is obtained from a previous or - .

-

is a buffer large enough to hold the expected - message.

-

indicates the size of .

-

If a tick occurs, i.e., the Erlang node on the + + +

is an open descriptor to an Erlang + connection. It is obtained from a previous + or .

+ + +

is a buffer large enough to hold the + expected message.

+ + +

indicates the size of + .

+ + +

If a tick occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function will return and - no message will be placed in the buffer. Also, - will be set to .

+ is still alive, the function returns and + no message is placed in the buffer. Also, + is set to .

On success, the message is placed in the specified buffer and the function returns the number of bytes actually read. On - failure, the function returns and will set - to one of:

+ failure, the function returns and sets + to one of the following:

Temporary error: Try again. - Buffer too small. + Buffer is too small. I/O error. + intei_receive_encoded(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen) Obsolete function for receiving a message. @@ -312,50 +394,63 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) {

This function is retained for compatibility with code generated by the interface compiler and with code following examples in the same application.

-

In essence the function performs the same operation as - , but instead of using an ei_x_buff, the - function expects a pointer to a character pointer - (), where the character pointer should point to a - memory area allocated by . The argument - should be a pointer to an integer containing the - exact size (in bytes) of the memory area. The function may - reallocate the memory area and will in such cases put the new - size in and update .

-

Furthermore the function returns either ERL_TICK or the - field of the . The actual - length of the message is put in . On error it - will return a value .

-

It is recommended to use ei_xreceive_msg instead when - possible, for the sake of readability. The function will - however be retained in the interface for compatibility and - will not be removed not be removed in future releases - without notice.

+

In essence, the function performs the same operation as + , but instead of using an + ei_x_buff, the function expects a pointer to a character + pointer (), where the character pointer + is to point to a memory area allocated by . + Argument is to be a pointer to an integer + containing the exact size (in bytes) of the memory area. The function + may reallocate the memory area and will in such cases put the new + size in and update + .

+

Returns either ERL_TICK or the + field of the + . The length + of the message is put in . On error + a value is returned.

+

It is recommended to use ei_xreceive_msg instead when + possible, for the sake of readability. However, the function will + be retained in the interface for compatibility and + will not be removed in future releases without prior + notice.

 + intei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen, unsigned timeout_ms) - Obsolete function for receiving a message with timeout. + Obsolete function for receiving a message with time-out. + -

ei_receive_encoded with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to + ei_receive_encoded with an optional time-out argument, + see the description at the beginning of this manual page.

 + intei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x) intei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x) Receive a message. + -

These functions receives a message to the buffer in - . allows the buffer in - to grow, but fails if the - message is bigger than the preallocated buffer in .

-

is an open descriptor to an Erlang connection.

-

is a pointer to an structure - and contains information on the message received.

-

is buffer obtained from .

-

On success, the function returns and the - struct will be initialized. - is defined as follows:

+

Receives a message to the buffer in . + allows the buffer in + to grow, but + fails if the message is larger than the pre-allocated buffer in + .

+ + is an open descriptor to an Erlang + connection. + is a pointer to an + structure + and contains information on the message received. + is buffer obtained from + . + +

On success, the functions return and the + struct is initialized. + is defined as follows:

-

identifies the type of message, and is one of - , , , - and .

-

If is this indicates that an - ordinary send operation has taken place, and to]]> - contains the Pid of the recipient (the C-node). If - is then a registered send - operation took place, and from]]> contains the Pid - of the sender.

-

If is or , then - to]]> and from]]> contain the pids of the - sender and recipient of the link or unlink.

-

If is , then this indicates that - a link has been broken. In this case, to]]> and - from]]> contain the pids of the linked processes.

-

The return value is the same as for , see - above.

+

identifies the type of message, and is + one of the following:

+ + + +

Indicates that an ordinary send operation has occurred. + to]]> contains the pid of the recipient (the + C-node).

+ + + +

A registered send operation occurred. + from]]> contains the pid of the sender.

+ + or + + +

to]]> and + from]]> contain the pids of the + sender and recipient of the link or unlink.

+ + + +

Indicates a broken link. to]]> and + from]]> contain the pids of the linked + processes.

+ + +

The return value is the same as for + ei_receive.

 + intei_receive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned imeout_ms) intei_xreceive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned timeout_ms) - Receive a message with optional timeout. + Receive a message with optional time-out. -

ei_receive_msg and ei_xreceive_msg with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to ei_receive_msg and ei_xreceive_msg + with an optional time-out argument, + see the description at the beginning of this manual page.

 + intei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms) - Receive a message with optional timeout. + Receive a message with optional time-out. -

ei_receive with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to + ei_receive with an optional time-out argument, + see the description at the beginning of this manual page.

 + intei_reg_send(ei_cnode* ec, int fd, char* server_name, char* buf, int len) Send a message to a registered name. -

This function sends an Erlang term to a registered process. -

-

This function sends an Erlang term to a process.

-

is an open descriptor to an Erlang connection.

-

is the registered name of the intended - recipient.

-

is the buffer containing the term in binary - format.

-

is the length of the message in bytes.

-

The function returns 0 if successful, otherwise -1, in the - latter case it will set to .

-

Example, send the atom "ok" to the process "worker":

+

Sends an Erlang term to a registered process.

+ + +

is an open descriptor to an Erlang + connection.

+ + is the registered name of the + intended recipient. + is the buffer containing the term in + binary format. + is the length of the message in bytes. + + +

Returns 0 if successful, otherwise -1. In + the latter case it sets to + .

+

Example:

+

Send the atom "ok" to the process "worker":

 + intei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf, int len, unsigned timeout_ms) - Send a message to a registered name with optional timeout. + Send a message to a registered name with optional time-out + -

ei_reg_send with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to + ei_reg_send with an optional time-out argument, + see the description at the beginning of this manual page.

 + intei_rpc(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen, ei_x_buff *x) intei_rpc_to(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen) intei_rpc_from(ei_cnode *ec, int fd, int timeout, erlang_msg *msg, ei_x_buff *x) Remote Procedure Call from C to Erlang. -

These functions support calling Erlang functions on remote nodes. - sends an rpc request to a remote node and - receives the results of such a call. - combines the functionality of these two functions - by sending an rpc request and waiting for the results. See also - .

-

is the C-node structure previously initiated by a - call to or -

-

is an open descriptor to an Erlang connection.

-

is the maximum time (in ms) to wait for - results. Specify to wait forever. - will wait infinitely for the answer, - i.e. the call will never time out.

-

is the name of the module containing the function - to be run on the remote node.

-

is the name of the function to run.

-

is a pointer to a buffer with an encoded - Erlang list, without a version magic number, containing the - arguments to be passed to the function.

-

is the length of the buffer containing the - encoded Erlang list.

-

structure of type and contains - information on the message received. See - for a description of the format.

-

points to the dynamic buffer that receives the - result. For for this will be the result - without the version magic number. For - the result will return a version magic number and a 2-tuple - .

-

returns the number of bytes in the result - on success and -1 on failure. returns - number of bytes or one of , - and otherwise. When failing, - all three functions set to one of:

+

Supports calling Erlang functions on remote nodes. + sends an RPC request to a remote node + and receives the results of such a + call. combines the functionality of these + two functions by sending an RPC request and waiting for the results. + See also + rpc:call/4 in Kernel.

+ + +

is the C-node structure previously + initiated by a call to or + .

+ + +

is an open descriptor to an Erlang + connection.

+ + +

is the maximum time (in milliseconds) + to wait for results. Specify to + wait forever. + waits infinitely for the answer, + that is, the call will never time out.

+ + +

is the name of the module containing the + function to be run on the remote node.

+ + +

is the name of the function to run.

+ + +

is a pointer to a buffer with an + encoded Erlang list, without a version magic number, containing + the arguments to be passed to the function.

+ + +

is the length of the buffer + containing the encoded Erlang list.

+ + +

is structure of type + and contains information on the + message + received. For a description of the + format, see + ei_receive_msg.

+ + +

points to the dynamic buffer that receives + the result. For this is the result + without the version magic number. For + the result returns a version + magic number and a 2-tuple .

+ + +

returns the number of bytes in the + result on success and -1 on failure. + returns the + number of bytes, otherwise one of , + , + and . When failing, all three + functions set to one of the + following:

I/O error. - Timeout expired. + Time-out expired. Temporary error: Try again. -

Example, check to see if an erlang process is alive:

+

Example:

+

Check to see if an Erlang process is alive:

 + erlang_pid *ei_self(ei_cnode *ec) - Retrieve the Pid of the C-node. + Retrieve the pid of the C-node. -

This function retrieves the Pid of the C-node. Every C-node - has a (pseudo) pid used in , +

Retrieves the pid of the C-node. Every C-node + has a (pseudo) pid used in , + , and others. This is contained in a field in the structure. It will be safe for a long time to fetch this field directly from the structure.

 + intei_send(int fd, erlang_pid* to, char* buf, int len) Send a message. -

This function sends an Erlang term to a process.

-

is an open descriptor to an Erlang connection.

-

is the Pid of the intended recipient of the - message.

-

is the buffer containing the term in binary - format.

-

is the length of the message in bytes.

-

The function returns 0 if successful, otherwise -1, in the - latter case it will set to .

+

Sends an Erlang term to a process.

+ + is an open descriptor to an Erlang + connection. + is the pid of the intended recipient of + the message. + is the buffer containing the term in + binary format. + is the length of the message in bytes. + + +

Returns 0 if successful, otherwise -1. In + the latter case it sets to + .

 + intei_send_encoded(int fd, erlang_pid* to, char* buf, int len) Obsolete function to send a message. -

Works exactly as ei_send, the alternative name retained for +

Works exactly as ei_send, the alternative name is retained for backward compatibility. The function will not be - removed without notice.

+ removed without prior notice.

 + intei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms) - Obsolete function to send a message with optional timeout. + Obsolete function to send a message with optional time-out. + -

ei_send_encoded with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to + ei_send_encoded with an optional time-out argument, + see the description at the beginning of this manual page.

 + intei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len) - Obsolete function to send a message to a registered name. + Obsolete function to send a message to a registered name. +

This function is retained for compatibility with code generated by the interface compiler and with code following examples in the same application.

The function works as with one - exception. Instead of taking the as a first - argument, it takes a second argument, an - which should be the process identifier of the sending process - (in the erlang distribution protocol).

+ exception. Instead of taking as first + argument, it takes a second argument, an + , + which is to be the process identifier of the sending process + (in the Erlang distribution protocol).

A suitable can be constructed from the - structure by the following example code:

+ structure by the following example + code:

num = fd; +ei_cnode ec; +erlang_pid *self; +int fd; /* the connection fd */ +... +self = ei_self(&ec); +self->num = fd; ]]> + intei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len) - Obsolete function to send a message to a registered name with timeout. + Obsolete function to send a message to a registered name with + time-out. -

ei_send_reg_encoded with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to + ei_send_reg_encoded with an optional time-out argument, + see the description at the beginning of this manual page.

 + intei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms) - Send a message with optional timeout. + Send a message with optional time-out. -

ei_send with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to + ei_send with an optional time-out argument, + see the description at the beginning of this manual page.

 + const char *ei_thisnodename(ei_cnode *ec) const char *ei_thishostname(ei_cnode *ec) const char *ei_thisalivename(ei_cnode *ec) Retrieve some values. -

These functions can be used to retrieve information about - the C Node. These values are initially set with - or .

-

They simply fetches the appropriate field from the +

Can be used to retrieve information about + the C-node. These values are initially set with + or + .

+

These function simply fetch the appropriate field from the + structure. Read the field directly will probably be safe for a long time, so these functions are not really needed.

 + intei_unpublish(ei_cnode *ec) Forcefully unpublish a node name. -

This function can be called by a process to unregister a - specified node from epmd on the localhost. This is however usually not - allowed, unless epmd was started with the -relaxed_command_check - flag, which it normally isn't.

- -

To unregister a node you have published, you should +

Can be called by a process to unregister a + specified node from EPMD on the local host. This is, however, usually + not allowed, unless EPMD was started with flag + -relaxed_command_check, which it normally is not.

+

To unregister a node you have published, you should close the descriptor that was returned by .

-

This function is deprecated and will be removed in a future release.

 -

is the node structure of the node to unregister.

-

If the node was successfully unregistered from epmd, the - function returns 0. Otherwise, it returns -1 and sets - is to .

+

is the node structure of the node to + unregister.

+

If the node was successfully unregistered from EPMD, the + function returns 0. Otherwise, -1 is returned and + is set to .

 + intei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms) - Unpublish a node name with optional timeout. + Unpublish a node name with optional time-out. -

ei_unpublish with an optional timeout argument, - see the description at the beginning of this document.

+

Equivalent to + ei_unpublish with an optional time-out argument, + see the description at the beginning of this manual page.

 - +
+ Debug Information

If a connection attempt fails, the following can be checked:

+ - - that the right cookie was used - that epmd is running - the remote Erlang node on the other side is running the - same version of Erlang as the - library. - the environment variable - is set correctly. + . + That the correct cookie was used + That EPMD is running + That the remote Erlang node on the other side is running the + same version of Erlang as the library + That environment variable + is set correctly -

The connection attempt can be traced by setting a tracelevel by either using - or by setting the environment variable . - The different tracelevels has the following messages:

+ +

The connection attempt can be traced by setting a trace level by either + using or by setting environment + variable . + The trace levels have the following messages:

+ 1: Verbose error messages 2: Above messages and verbose warning messages - 3: Above messages and progress reports for connection handling + 3: Above messages and progress reports for connection handling + 4: Above messages and progress reports for communication 5: Above messages and progress reports for data conversion diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index 4beb4c6c73..9499a07467 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.xml @@ -22,7 +22,7 @@ - The El Library User's Guide + Erl_Interface User's Guide Kent Boortz Kent Boortz @@ -32,100 +32,158 @@ ei_users_guide.xml -

The Erl_Interface library contains functions. which help you - integrate programs written in C and Erlang. The functions in - Erl_Interface support the following:

- - manipulation of data represented as Erlang data types - conversion of data between C and Erlang formats - encoding and decoding of Erlang data types for transmission or storage - communication between C nodes and Erlang processes - backup and restore of C node state to and from Mnesia - -

In the following sections, these topics are described:

- - compiling your code for use with Erl_Interface - initializing Erl_Interface - encoding, decoding, and sending Erlang terms - building terms and patterns - pattern matching - connecting to a distributed Erlang node - using EPMD - sending and receiving Erlang messages - remote procedure calls - global names - the registry - + +
+ Introduction +

The Erl_Interface library contains functions that help you + integrate programs written in C and Erlang. The functions in + Erl_Interface support the following:

+ + Manipulation of data represented as Erlang data types + Conversion of data between C and Erlang formats + Encoding and decoding of Erlang data types for transmission or + storage + Communication between C nodes and Erlang processes + Backup and restore of C node state to and from + Mnesia + + +

By default, the Erl_Interface libraries are only guaranteed + to be compatible with other Erlang/OTP components from the same + release as the libraries themselves. For information about how to + communicate with Erlang/OTP components from earlier releases, see + function + ei:ei_set_compat_rel and + + erl_eterm:erl_set_compat_rel.

+ + +
+ Scope +

In the following sections, these topics are described:

+ + Compiling your code for use with Erl_Interface + Initializing Erl_Interface + Encoding, decoding, and sending Erlang terms + Building terms and patterns + Pattern matching + Connecting to a distributed Erlang node + Using the Erlang Port Mapper Daemon (EPMD) + Sending and receiving Erlang messages + Remote procedure calls + Using global names + Using the registry + +
+ +
+ Prerequisites +

It is assumed that the reader is familiar with the Erlang programming + language.

+
+
Compiling and Linking Your Code -

In order to use any of the Erl_Interface functions, include the +

To use any of the Erl_Interface functions, include the following lines in your code:

+ -

Determine where the top directory of your OTP installation is. You - can find this out by starting Erlang and entering the following + +

Determine where the top directory of your OTP installation is. + To find this, start Erlang and enter the following command at the Eshell prompt:

+ code:root_dir(). /usr/local/otp ]]> -

To compile your code, make sure that your C compiler knows where - to find by specifying an appropriate - argument on the command line, or by adding it to the - definition in your . The correct value for this path is - Vsn, where is the path - reported by in the above example, and Vsn is - the version of the Erl_interface application, for example -

+ +

To compile your code, ensure that your C compiler knows where + to find by specifying an appropriate + argument on the command line, or add it to + the definition in your + . The correct value for this path is + Vsn, + where:

+ + + +

is the path reported by + in the example above.

+ + +

Vsn is the version of the Erl_Interface application, + for example, .

+ + + +

Compiling the code:

+ -

When linking, you will need to specify the path to - and with - , and you will need to specify the - name of the libraries with . You can do - this on the command line or by adding the flags to the - definition in your .

+ +

When linking:

+ + + Specify the path to and + with + . + Specify the name of the libraries with + . + + +

Do this on the command line or add the flags to the + definition in your + .

+ +

Linking the code:

+ -

Also, on some systems it may be necessary to link with some - additional libraries (e.g. and on - Solaris, or on Windows) in order to use the - communication facilities of Erl_Interface.

-

If you are using Erl_Interface functions in a threaded + +

On some systems it can be necessary to link with some more + libraries (for example, and + on Solaris, or + on Windows) to use the + communication facilities of Erl_Interface.

+ +

If you use the Erl_Interface functions in a threaded application based on POSIX threads or Solaris threads, then - Erl_Interface needs access to some of the synchronization - facilities in your threads package, and you will need to specify - additional compiler flags in order to indicate which of the packages - you are using. Define and either or + Erl_Interface needs access to some of the synchronization + facilities in your threads package. You must specify extra + compiler flags to indicate which of the packages you use. Define + and either or . The default is to use POSIX threads if is specified.

- Initializing the erl_interface Library -

Before calling any of the other Erl_Interface functions, you - must call exactly once to initialize the library. - takes two arguments, however the arguments are no - longer used by Erl_Interface, and should therefore be specified - as .

+ Initializing the Erl_Interface Library +

Before calling any of the other Erl_Interface functions, call + exactly once to initialize the library. + takes two arguments. However, the arguments + are no longer used by Erl_Interface and are therefore to be + specified as .

- Encoding, Decoding and Sending Erlang Terms + Encoding, Decoding, and Sending Erlang Terms

Data sent between distributed Erlang nodes is encoded in the - Erlang external format. Consequently, you have to encode and decode + Erlang external format. You must therefore encode and decode Erlang terms into byte streams if you want to use the distribution - protocol to communicate between a C program and Erlang.

-

The Erl_Interface library supports this activity. It has a - number of C functions which create and manipulate Erlang data + protocol to communicate between a C program and Erlang.

+ +

The Erl_Interface library supports this activity. It has + several C functions that create and manipulate Erlang data structures. The library also contains an encode and a decode function. - The example below shows how to create and encode an Erlang tuple + The following example shows how to create and encode an Erlang tuple :

- +

Alternatively, you can use and - , which handle the encoding and decoding of - messages transparently.

-

Refer to the Reference Manual for a complete description of the - following modules:

+ , which handle the encoding and + decoding of messages transparently.

+ +

For a complete description, see the following modules:

- the module for creating Erlang terms - the module for encoding and decoding routines. + erl_eterm + for creating Erlang terms + erl_marshal + for encoding and decoding routines
+ Building Terms and Patterns -

The previous example can be simplified by using - to create an Erlang term.

- The previous example can be simplified by using the + erl_format module + to create an Erlang term:

+ -

Refer to the Reference Manual, the module, for a - full description of the different format directives. The following - example is more complex:

- For a complete description of the different format directives, see + the erl_format module.

+ +

The following example is more complex:

+ + -

As in previous examples, it is your responsibility to free the - memory allocated for Erlang terms. In this example, - ensures that the complete term pointed to - by is released. This is necessary, because the pointer from - the second call to is lost.

-

The following - example shows a slightly different solution:

- As in the previous examples, it is your responsibility to free the + memory allocated for Erlang terms. In this example, + ensures that the complete term + pointed to by is released. This is necessary + because the pointer from the second call to erl_format is lost.

+ +

The following example shows a slightly different solution:

+ + +

In this case, you free the two terms independently. The order in - which you free the terms and is not important, - because the Erl_Interface library uses reference counting to - determine when it is safe to actually remove objects.

-

If you are not sure whether you have freed the terms properly, you + which you free the terms and + is not important, + because the Erl_Interface library uses reference counting to + determine when it is safe to remove objects.

+ +

If you are unsure whether you have freed the terms properly, you can use the following function to see the status of the fixed term allocator:

+ -

Refer to the Reference Manual, the module for more - information.

+ +

For more information, see the + erl_malloc module.

Pattern Matching -

An Erlang pattern is a term that may contain unbound variables or - symbols. Such a pattern can be matched against a +

An Erlang pattern is a term that can contain unbound variables or + symbols. Such a pattern can be matched + against a term and, if the match is successful, any unbound variables in the pattern will be bound as a side effect. The content of a bound - variable can then be retrieved.

- + -

is used to perform pattern matching. It takes a + +

The + erl_format:erl_match function + performs pattern matching. It takes a pattern and a term and tries to match them. As a side effect any unbound - variables in the pattern will be bound. In the following example, we - create a pattern with a variable Age which appears at two + variables in the pattern will be bound. In the following example, a + pattern is created with a variable Age, which is included at two positions in the tuple. The pattern match is performed as follows:

- - will bind the contents of - Age to 21 the first time it reaches the variable - the second occurrence of Age will cause a test for - equality between the terms since Age is already bound to - 21. Since Age is bound to 21, the equality test will - succeed and the match continues until the end of the pattern. - if the end of the pattern is reached, the match succeeds and you - can retrieve the contents of the variable + + + +

erl_match binds the contents of Age to 21 + the first time it reaches the variable.

+ + +

The second occurrence of Age causes a test for + equality between the terms, as Age is already bound to + 21. As Age is bound to 21, the equality test + succeeds and the match continues until the end of the pattern.

+ + +

If the end of the pattern is reached, the match succeeds and you + can retrieve the contents of the variable.

+ + -

Refer to the Reference Manual, the function for - more information.

+ +

For more information, see the + + erl_format:erl_match function.

Connecting to a Distributed Erlang Node -

In order to connect to a distributed Erlang node you need to first - initialize the connection routine with , - which stores information such as the host name, node name, and IP +

To connect to a distributed Erlang node, you must first + initialize the connection routine with + + erl_connect:erl_connect_init, + which stores information, such as the hostname, node name, and IP address for later use:

+ -

Refer to the Reference Manual, the module for more information.

+ +

For more information, see the + erl_connect module.

+

After initialization, you set up the connection to the Erlang node. - Use to specify the Erlang node you want to - connect to. The following example sets up the connection and should - result in a valid socket file descriptor:

+ To specify the Erlang node you want to connect to, use + . The following example sets up the + connection and is to result in a valid socket file descriptor:

+ -

prints the specified string and terminates - the program. Refer to the Reference Manual, the - function for more information.

+ +

prints the specified string and + terminates the program. For more information, see the + erl_error module.

Using EPMD -

is the Erlang Port Mapper Daemon. Distributed Erlang nodes - register with on the localhost to indicate to other nodes that - they exist and can accept connections. maintains a register of +

erts:epmd + is the Erlang Port Mapper Daemon. Distributed + Erlang nodes register with on the local host to + indicate to other nodes that they exist and can accept connections. + maintains a register of node and port number information, and when a node wishes to connect to - another node, it first contacts in order to find out the correct - port number to connect to.

-

When you use to connect to an Erlang node, a - connection is first made to and, if the node is known, a + another node, it first contacts to find the + correct port number to connect to.

+ +

When you use + erl_connect + to connect to an Erlang node, a connection is first made to + and, if the node is known, a connection is then made to the Erlang node.

-

C nodes can also register themselves with if they want other + +

C nodes can also register themselves with + if they want other nodes in the system to be able to find and connect to them.

-

Before registering with , you need to first create a listen socket - and bind it to a port. Then:

+ +

Before registering with , you must first + create a listen socket and bind it to a port. Then:

+ -

is a file descriptor now connected to . - monitors the other end of the connection, and if it detects that the - connection has been closed, the node will be unregistered. So, if you - explicitly close the descriptor or if your node fails, it will be + +

is a file descriptor now connected to + . + monitors the other end of the connection. If it detects that the + connection has been closed, the node becomes unregistered. So, if you + explicitly close the descriptor or if your node fails, it becomes unregistered from .

-

Be aware that on some systems (such as VxWorks), a failed node will - not be detected by this mechanism since the operating system does not + +

Notice that on some systems (such as VxWorks), a failed node is + not detected by this mechanism, as the operating system does not automatically close descriptors that were left open when the node - failed. If a node has failed in this way, will prevent you from - registering a new node with the old name, since it thinks that the old + failed. If a node has failed in this way, + prevents you from + registering a new node with the old name, as it thinks that the old name is still in use. In this case, you must unregister the name explicitly:

+ -

This will cause to close the connection from the far end. Note + +

This causes to close the connection from the + far end. Notice that if the name was in fact still in use by a node, the results of this operation are unpredictable. Also, doing this does not cause the - local end of the connection to close, so resources may be consumed.

+ local end of the connection to close, so resources can be consumed.

Sending and Receiving Erlang Messages

Use one of the following two functions to send messages:

+ - - + + erl_connect:erl_send + + erl_connect:erl_reg_send -

As in Erlang, it is possible to send messages to a - Pid or to a registered name. It is easier to send a - message to a registered name because it avoids the problem of finding - a suitable Pid.

+ +

As in Erlang, messages can be sent to a + pid or to a registered name. It is easier to send a + message to a registered name, as it avoids the problem of finding + a suitable pid.

+

Use one of the following two functions to receive messages:

+ - - + + erl_connect:erl_receive + + erl_connect:erl_receive_msg -

receives the message into a buffer, while - decodes the message into an Erlang term.

+ +

receives the message into a buffer, + while decodes the message into an + Erlang term.

Example of Sending Messages

In the following example, is - sent to a registered process . The message is encoded - by :

+ sent to a registered process . The message + is encoded by :

+ +

The first element of the tuple that is sent is your own - Pid. This enables to reply. Refer to the - Reference Manual, the module for more information - about send primitives.

+ pid. This enables to reply. + For more information about the primitives, see the + erl_connect module.

Example of Receiving Messages -

In this example is received. The - received Pid is then used to return

+

In this example, is received. The + received pid is then used to return + .

+ -

In order to provide robustness, a distributed Erlang node - occasionally polls all its connected neighbours in an attempt to - detect failed nodes or communication links. A node which receives such - a message is expected to respond immediately with an message. - This is done automatically by , however when this - has occurred returns to the caller - without storing a message into the structure.

+ +

To provide robustness, a distributed Erlang node + occasionally polls all its connected neighbors in an attempt to + detect failed nodes or communication links. A node that receives such + a message is expected to respond immediately with an + message. This is done automatically by + . However, when this has occurred, + returns to + the caller without storing a message into the + structure.

+

When a message has been received, it is the caller's responsibility - to free the received message as well as - or , depending on the type of message received.

-

Refer to the Reference Manual for additional information about the - following modules:

- - - . - + to free the received message and + or , + depending on the type of message received.

+ +

For more information, see the + erl_connect and + erl_eterm modules.

@@ -394,10 +520,12 @@ if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) {

An Erlang node acting as a client to another Erlang node typically sends a request and waits for a reply. Such a request is included in a function call at a remote node and is called a remote - procedure call. The following example shows how the - Erl_Interface library supports remote procedure calls:

- +

The following example shows how the + Erl_Interface library supports remote procedure calls:

+ + compiler errors !\n"); erl_free_term(ep); erl_free_term(reply); ]]> -

is called to compile the specified module on the - remote node. checks that the compilation was + +

is called to compile the specified module on + the remote node. checks that the + compilation was successful by testing for the expected .

-

Refer to the Reference Manual, the module for - more information about , and its companions - and .

+ +

For more information about and its + companions and + , see the + erl_connect module.

Using Global Names -

A C node has access to names registered through the Erlang Global +

A C node has access to names registered through the + kernel:global module. Names can be looked up, allowing the C node to send messages to named Erlang services. C nodes can also register global names, allowing them to provide named services to Erlang processes or other C - nodes.

-

Erl_Interface does not provide a native implementation of the global - service. Instead it uses the global services provided by a "nearby" - Erlang node. In order to use the services described in this section, + nodes.

+ +

Erl_Interface does not provide a native implementation of the + global service. Instead it uses the global services provided by a "nearby" + Erlang node. To use the services described in this section, it is necessary to first open a connection to an Erlang node.

+

To see what names there are:

+ -

allocates and returns a buffer containing - all the names known to global. will be initialized to - indicate how many names are in the array. The array of strings in - names is terminated by a NULL pointer, so it is not necessary to use + +

+ erl_global:erl_global_names + allocates and returns a buffer containing + all the names known to the global module in Kernel. + is initialized to + indicate the number of names in the array. The array of strings in names + is terminated by a NULL pointer, so it is not necessary to use to determine when the last name is reached.

+

It is the caller's responsibility to free the array. - allocates the array and all of the strings - using a single call to , so is all - that is necessary.

+ erl_global_names allocates the array and all the strings + using a single call to , so + is all that is necessary.

+

To look up one of the names:

+ -

If is known to global, an Erlang pid is returned - that can be used to send messages to the schedule service. - Additionally, will be initialized to contain the name of + +

If is known to the + global module in Kernel, an Erlang pid is + returned that can be used to send messages to the schedule service. + Also, is initialized to contain the name of the node where the service is registered, so that you can make a - connection to it by simply passing the variable to .

+ connection to it by simply passing the variable to + erl_connect.

+

Before registering a name, you should already have registered your - port number with . This is not strictly necessary, but if you + port number with . This is not strictly necessary, + but if you neglect to do so, then other nodes wishing to communicate with your - service will be unable to find or connect to your process.

+ service cannot find or connect to your process.

+

Create a pid that Erlang processes can use to communicate with your service:

+ -

After registering the name, you should use to wait for - incoming connections.

-

Do not forget to free later with !

+ +

After registering the name, use + + erl_connect:erl_accept + to wait for incoming connections.

+ + +

Remember to free later with + + erl_malloc:erl_free_term.

+ +

To unregister a name:

+
- The Registry + Using the Registry

This section describes the use of the registry, a simple mechanism for storing key-value pairs in a C-node, as well as backing them up or - restoring them from a Mnesia table on an Erlang node. More detailed - information about the individual API functions can be found in the - Reference Manual.

-

Keys are strings, i.e. 0-terminated arrays of characters, and values - are arbitrary objects. Although integers and floating point numbers + restoring them from an Mnesia table on an Erlang node. For more + detailed information about the individual API functions, see the + registry module.

+ +

Keys are strings, that is, zero-terminated arrays of characters, and + values are arbitrary objects. Although integers and floating point numbers are treated specially by the registry, you can store strings or binary objects of any type as pointers.

-

To start, you need to open a registry:

+ +

To start, open a registry:

+ -

The number 45 in the example indicates the approximate number of + +

The number 45 in the example indicates the approximate number of objects that you expect to store in the registry. Internally the registry uses hash tables with collision chaining, so there is no absolute upper limit on the number of objects that the registry can - contain, but if performance or memory usage are important, then you - should choose a number accordingly. The registry can be resized later.

+ contain, but if performance or memory usage is important, then you + are to choose a number accordingly. The registry can be resized later.

+

You can open as many registries as you like (if memory permits).

-

Objects are stored and retrieved through set and get functions. In - the following examples you see how to store integers, floats, strings + +

Objects are stored and retrieved through set and get functions. + The following example shows how to store integers, floats, strings, and arbitrary binary objects:

+ l = 42; b->m = 12; ei_reg_setpval(reg,"jox",b,sizeof(*b)); ]]> -

If you attempt to store an object in the registry and there is an - existing object with the same key, the new value will replace the old + +

If you try to store an object in the registry and there is an + existing object with the same key, the new value replaces the old one. This is done regardless of whether the new object and the old one have the same type, so you can, for example, replace a string with an - integer. If the existing value is a string or binary, it will be freed + integer. If the existing value is a string or binary, it is freed before the new value is assigned.

+

Stored values are retrieved from the registry as follows:

+ -

In all of the above examples, the object must exist and it must be of + +

In all the above examples, the object must exist and it must be of the right type for the specified operation. If you do not know the - type of a given object, you can ask:

+ type of an object, you can ask:

+ -

Buf will be initialized to contain object attributes.

+ +

Buf is initialized to contain object attributes.

+

Objects can be removed from the registry:

+ +

When you are finished with a registry, close it to remove all the objects and free the memory back to the system:

+
Backing Up the Registry to Mnesia -

The contents of a registry can be backed up to Mnesia on a "nearby" - Erlang node. You need to provide an open connection to the Erlang node - (see ). Also, Mnesia 3.0 or later must be running +

The contents of a registry can be backed up to + Mnesia on a "nearby" Erlang + node. You must provide an open connection to the Erlang node + (see erl_connect). + Also, Mnesia 3.0 or later must be running on the Erlang node before the backup is initiated:

+ -

The example above will backup the contents of the registry to the - specified Mnesia table . Once a registry has been backed - up to Mnesia in this manner, additional backups will only affect - objects that have been modified since the most recent backup, i.e. - objects that have been created, changed or deleted. The backup - operation is done as a single atomic transaction, so that the entire - backup will be performed or none of it will.

-

In the same manner, a registry can be restored from a Mnesia table:

+ +

This example back up the contents of the registry to the + specified Mnesia table . + Once a registry has been backed + up to Mnesia like this, more backups only affect + objects that have been modified since the most recent backup, that is, + objects that have been created, changed, or deleted. The backup + operation is done as a single atomic transaction, so that either the + entire backup is performed or none of it.

+ +

Likewise, a registry can be restored from a Mnesia table:

+ -

This will read the entire contents of into the specified - registry. After the restore, all of the objects in the registry will - be marked as unmodified, so a subsequent backup will only affect + +

This reads the entire contents of into the + specified registry. After the restore, all the objects in the registry + are marked as unmodified, so a later backup only affects objects that you have modified since the restore.

-

Note that if you restore to a non-empty registry, objects in the - table will overwrite objects in the registry with the same keys. Also, + +

Notice that if you restore to a non-empty registry, objects in the + table overwrite objects in the registry with the same keys. Also, the entire contents of the registry is marked as unmodified after the restore, including any modified objects that were not - overwritten by the restore operation. This may not be your intention.

+ overwritten by the restore operation. This may not be your + intention.

Storing Strings and Binaries

When string or binary objects are stored in the registry it is - important that a number of simple guidelines are followed.

+ important that some simple guidelines are followed.

+

Most importantly, the object must have been created with a single call - to (or similar), so that it can later be removed by a - single call to . Objects will be freed by the registry + to (or similar), so that it can later be + removed by a single call to . + Objects are freed by the registry when it is closed, or when you assign a new value to an object that previously contained a string or binary.

-

You should also be aware that if you store binary objects that are - context-dependent (e.g. containing pointers or open file descriptors), - they will lose their meaning if they are backed up to a Mnesia table - and subsequently restored in a different context.

+ +

Notice that if you store binary objects that are context-dependent + (for example, containing pointers or open file descriptors), + they lose their meaning if they are backed up to a Mnesia table + and later restored in a different context.

+

When you retrieve a stored string or binary value from the registry, the registry maintains a pointer to the object and you are passed a copy of that pointer. You should never free an object retrieved in this manner because when the registry later attempts to free it, a - runtime error will occur that will likely cause the C-node to crash.

+ runtime error occurs that likely causes the C-node to crash.

+

You are free to modify the contents of an object retrieved this way. - However when you do so, the registry will not be aware of the changes - you make, possibly causing it to be missed the next time you make a - Mnesia backup of the registry contents. This can be avoided if you - mark the object as dirty after any such changes with - , or pass appropriate flags to - .

+ However, when you do so, the registry is not aware of your changes, + possibly causing it to be missed the next time you make an + Mnesia backup of the registry contents. This can be avoided if + you mark the object as dirty after any such changes with + + registry:ei_reg_markdirty, or pass appropriate flags to + + registry:ei_reg_dump.

diff --git a/lib/erl_interface/doc/src/erl_call.xml b/lib/erl_interface/doc/src/erl_call.xml index f8fe409560..ebd9172f98 100644 --- a/lib/erl_interface/doc/src/erl_call.xml +++ b/lib/erl_interface/doc/src/erl_call.xml @@ -28,135 +28,146 @@ Bjarne Däcker Torbjörn Törnkvist - 97-05-16 + 1997-05-16 B erl_call.xml erl_call Call/start a distributed Erlang node. -

makes it possible to start and/or communicate with - a distributed Erlang node. It is built upon the - library as an example application. Its purpose is to use an Unix shell script to interact with a distributed Erlang node. It performs all - communication with the Erlang rex server, using the standard Erlang RPC facility. It does not require any special - software to be run at the Erlang target node.

+

makes it possible to start and/or + communicate with a distributed Erlang node. It is built upon the + library as an example application. + Its purpose is to use a Unix shell script to interact with a distributed + Erlang node. It performs all communication with the Erlang + rex server, using the standard Erlang RPC facility. It does not + require any special software to be run at the Erlang target node.

+

The main use is to either start a distributed Erlang node or to make an ordinary function call. However, it is also - possible to pipe an Erlang module to and have it - compiled, or to pipe a sequence of Erlang expressions to be evaluated + possible to pipe an Erlang module to and have + it compiled, or to pipe a sequence of Erlang expressions to be evaluated (similar to the Erlang shell).

-

Options, which cause to be read, can be used with - advantage - as scripts from within (Unix) shell scripts. Another - nice use of could be from (http) CGI-bin scripts.

+ +

Options, which cause to be read, can be used + with advantage, + as scripts from within (Unix) shell scripts. Another nice use + of could be from (HTTP) CGI-bin scripts.

 + erl_call <options> Start/call Erlang. -

Each option flag is described below with its name, type and +

Starts/calls Erlang.

+

Each option flag is described below with its name, type, and meaning.

- -a [Mod [Fun [Args]]]] + -a [Mod [Fun [Args]]]] -

(optional): Applies the specified function - and returns the result. must be specified, however - start and [] are assumed for unspecified and , respectively. should - be in the same format as for . Note - that this flag takes exactly one argument, so quoting - may be necessary in order to group , - and , in a manner dependent on the behavior - of your command shell.

-

+

(Optional.) Applies the specified function + and returns the result. must be specified. + However, start and [] are assumed for unspecified + and , respectively. + is to be in the same format as for + + erlang:apply/3 in ERTS.

+

Notice that this flag takes exactly one argument, so quoting + can be necessary to group , + , and in a manner + dependent on the behavior of your command shell.

 - -c Cookie + -c Cookie -

(optional): Use this option to specify a certain cookie. If no cookie is specified, the file is read and its content are used as cookie. The Erlang node we want to communicate with must have the same cookie.

+

(Optional.) Use this option to specify a certain cookie. + If no cookie is specified, the + file is read and its content is used as cookie. The Erlang node + we want to communicate with must have the same cookie.

 - -d + -d -

(optional): Debug mode. This causes all IO to be output - to the file , where +

(Optional.) Debug mode. This causes all I/O to be output + to the file, where + is the node name of the Erlang node in question.

-

- -e + -e -

(optional): Reads a sequence of Erlang expressions, separated - by ',' and ended with a '.', from until - EOF (Control-D). Evaluates the expressions and returns the result from - the last expression. Returns if successful.

-

+

(Optional.) Reads a sequence of Erlang expressions, + separated by comma (,) and ended with a full stop (.), from + until EOF (Control-D). Evaluates the + expressions and returns the result from the last expression. + Returns on success.

 - -h HiddenName + -h HiddenName -

(optional): Specifies the name of the hidden node +

(Optional.) Specifies the name of the hidden node that represents.

-

- -m + -m -

(optional): Reads an Erlang module from and - compiles it.

-

+

(Optional.) Reads an Erlang module from + and compiles it.

 - -n Node + -n Node -

(one of is required): - Has the same meaning as and can still be used for - backwards compatibility reasons.

-

+

(One of is required.) + Has the same meaning as and can still be + used for backward compatibility reasons.

 - -name Node + -name Node -

(one of is required): is the name of the node to be +

(One of is required.) + is the name of the node to be started or communicated with. It is assumed that - is started with , which means that fully - qualified long node names are used. - If the option is given, an Erlang node will (if necessary) - be started with .

-

+ is started with + , which means that fully + qualified long node names are used. If option + is specified, an Erlang node will (if + necessary) be started with .

 - -q + -q -

(optional): Halts the Erlang node specified - with the -n switch. This switch overrides the -s switch.

-

+

(Optional.) Halts the Erlang node specified + with switch -n. This switch overrides switch -s.

 - -r + -r -

(optional): Generates a random name of the hidden node +

(Optional.) Generates a random name of the hidden node that represents.

-

- -s + -s -

(optional): Starts a distributed Erlang node if necessary. - This means that in a sequence of calls, where the '' - and '' are constant, only the first call will start - the Erlang node. This makes the rest of the communication - very fast. This flag is currently only available on the Unix platform.

-

+

(Optional.) Starts a distributed Erlang node if + necessary. This means that in a sequence of calls, where + '' and '' are + constant, only the first call starts the Erlang node. This makes + the rest of the communication very fast. This flag is currently + only available on Unix-like platforms (Linux, Mac OS X, Solaris, + and so on).

 - -sname Node + -sname Node -

(one of is required): is the name of the node to - be started or communicated with. It is assumed that is started with which means that short node names are used. - If option is given, an Erlang node will be started (if necessary) with .

-

+

(One of is required.) + is the name of the node to be started + or communicated with. It is assumed that + is started with , which means that + short node names are used. If option is + specified, an Erlang node is started (if necessary) with + .

 - -v + -v -

(optional): Prints a lot of information. - This is only useful for the developer and maintainer of .

-

+

(Optional.) Prints a lot of + information. This is only useful for the developer and maintainer + of .

 - -x ErlScript + -x ErlScript -

(optional): Specifies another name of the Erlang start-up script - to be used. If not specified, the standard start-up script - is used.

+

(Optional.) Specifies another name of the Erlang + startup script to be used. If not specified, the standard + startup script is used.

 @@ -165,20 +176,29 @@
Examples -

Starts an Erlang node and calls .

+

To start an Erlang node and call :

+ -

Terminates an Erlang node by calling .

+ +

To terminate an Erlang node by calling + :

+ -

An apply with several arguments.

+ +

To apply with many arguments:

+ -

Evaluates a couple of expressions. The input ends with EOF (Control-D).

+ +

To evaluate some expressions + (the input ends with EOF (Control-D)):

+ -

Compiles a module and runs it. Again, the input ends with EOF (Control-D). (In the example shown, the output has been formatted afterwards).

+ +

To compile a module and run it (again, the input ends with EOF + (Control-D)):

+

(In the example, the output has been formatted afterwards.)

+ Bjarne Däcker Torbjörn Törnkvist - 980703 + 1998-07-03 A erl_connect.xml erl_connect - Communicate with Distributed Erlang + Communicate with distributed Erlang.

This module provides support for communication between distributed - Erlang nodes and C nodes, in a manner that is transparent to Erlang + Erlang nodes and C-nodes, in a manner that is transparent to Erlang processes.

-

A C node appears to Erlang as a - hidden node. + +

A C-node appears to Erlang as a hidden node. That is, Erlang processes that know the name of the - C node are able to communicate with it in a normal manner, but - the node name will not appear in the listing provided by the - Erlang function .

+ C-node can communicate with it in a normal manner, but + the node name does not appear in the listing provided by + erlang:nodes/0 + in ERTS.

 + interl_accept(listensock, conp) Accept a connection. + int listensock; ErlConnect *conp; @@ -56,10 +59,12 @@

This function is used by a server process to accept a connection from a client process.

-

is an open socket descriptor on which - has previously been called.

-

is a pointer to an struct, - described as follows:

+ + is an open socket descriptor on + which has previously been called. + is a pointer to an + struct, described as follows: + is set to .

 + interl_close_connection(fd) Close a connection to an Erlang node. @@ -79,47 +85,54 @@ typedef struct { int fd; -

This function closes an open connection to an Erlang node.

+

Closes an open connection to an Erlang node.

is a file descriptor obtained from - or .

-

On success, 0 is returned. If the call fails, a non-zero value - is returned, and the reason for - the error can be obtained with the appropriate platform-dependent - call.

+ or + .

+

Returns 0 on success. If the call fails, a non-zero value + is returned, and the reason for the error can be obtained with the + appropriate platform-dependent call.

 + interl_connect(node) interl_xconnect(addr, alive) - Establishe a connection to an Erlang node. + Establish a connection to an Erlang node. char *node, *alive; struct in_addr *addr; -

These functions set up a connection to an Erlang node.

-

requires the IP address of the remote - host and the alive name of the remote node - to be specified. provides an alternative +

Sets up a connection to an Erlang node.

+

requires the IP address of the + remote host and the alivename of the remote node to be + specified. provides an alternative interface, and determines the information from the node name provided.

-

is the 32-bit IP address of the remote host.

-

is the alivename of the remote node.

-

is the name of the remote node.

-

These functions return an open file descriptor on success, or - a negative value indicating that an error occurred --- in - which case they will set to one of:

+ + is the 32-bit IP address of the remote + host. + is the alivename of the remote node. + + is the name of the remote node. + +

Returns an open file descriptor on success, otherwise a negative + value. In the latter case is set to one + of:

- The remote host is unreachable + The remote host is unreachable. - No more memory available. + No more memory is available. I/O error. -

Additionally, values from - (2) and (2) - system calls may be propagated into .

+

Also, values from + (2) and + (2) + system calls can be propagated into .

+

Example:

 + interl_connect_init(number, cookie, creation) interl_connect_xinit(host, alive, node, addr, cookie, creation) Initialize communication. + int number; char *cookie; @@ -147,47 +162,72 @@ erl_xconnect( &addr , ALIVE ); struct in_addr *addr; -

These functions initialize the - module. In particular, they are used to identify the name of the +

Initializes the module. + In particular, these functions are used to identify the name of the C-node from which they are called. One of these functions must - be called before any of the other functions in the erl_connect + be called before any of the other functions in the erl_connect module are used.

-

stores for later use information about - the node's host name , alive name , node - name , IP address , cookie , - and creation number . - provides an alternative interface which does not require as much - information from the caller. Instead, - uses to obtain default values. -

-

If you use your node will have a - short name, i.e., it will not be fully qualified. If you need to - use fully qualified (a.k.a. long) names, use - instead. -

-

is the name of the host on which the node is running.

-

is the alivename of the node.

-

is the name of the node. The nodename should - be of the form alivename@hostname.

-

is the 32-bit IP address of .

-

is the authorization string required for access - to the remote node. If NULL the user HOME directory is - searched for a cookie file . The path to - the home directory is retrieved from the environment variable - on Unix and from the and - variables on Windows. Refer to the - module for more details.

-

helps identify a particular instance of a C - node. In particular, it can help prevent us from receiving - messages sent to an earlier process with the same registered - name.

-

A C node acting as a server will be assigned a creation number +

stores for later use + information about:

+ + Hostname of the node, + Alivename, + Node name, + IP address, + Cookie, + Creation number, + +

+ provides an alternative interface that does not require as much + information from the caller. Instead, + + uses to obtain default values.

+

If you use , your node will + have a short name, that is, it will not be fully qualified. If you + need to use fully qualified (long) names, use + instead.

+ + +

is the name of the host on which the node + is running.

+ + +

is the alivename of the node.

+ + +

is the node name. It is to + be of the form alivename@hostname.

+ + +

is the 32-bit IP address of + .

+ + +

is the authorization string required + for access to the remote node. If NULL, the user + HOME directory is searched for a cookie file + . The path to + the home directory is retrieved from environment variable + on Unix and from the + and + variables on Windows. For more + details, see the + kernel:auth module.

+ + +

helps identifying a particular + instance of a C-node. In particular, it can help prevent us from + receiving messages sent to an earlier process with the same + registered name.

+ + +

A C-node acting as a server is assigned a creation number when it calls .

-

is used by to - construct the actual node name. In the second example shown - below, "c17@a.DNS.name" will be the resulting node - name.

-

Example 1:

+

is used by + to + construct the actual node name. In Example 2 + below, "c17@a.DNS.name" is the resulting node name.

+

Example 1:

when initializing !"); ]]> -

Example 2:

+

Example 2:

when initializing !"); ]]> + interl_publish(port) Publish a node name. @@ -213,66 +254,74 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) int port; -

These functions are used by a server process to register +

This function is used by a server process to register with the local name server epmd, thereby allowing other processes to send messages by using the registered name. - Before calling either of these functions, the process should - have called and on an open socket.

-

is the local name to register, and should be the - same as the port number that was previously bound to the socket.

-

To unregister with epmd, simply close the returned - descriptor. -

-

On success, the functions return a descriptor connecting the - calling process to epmd. On failure, they return -1 and set - to:

+ Before calling this function, the process should + have called and + on an open socket.

+

is the local name to register, and is to be + the same as the port number that was previously bound to the + socket.

+

To unregister with EPMD, simply close the returned descriptor.

+

On success, a descriptor connecting the calling process to EPMD is + returned. On failure, -1 is returned and + is set to:

- I/O error + I/O error. -

Additionally, values from (2) - and (2) system calls may be propagated - into . -

+

Also, values from + (2) + and (2) system calls can be + propagated into .

 + interl_receive(fd, bufp, bufsize) Receive a message. + int fd; char *bufp; int bufsize; -

This function receives a message consisting of a sequence +

Receives a message consisting of a sequence of bytes in the Erlang external format.

-

is an open descriptor to an Erlang connection.

-

is a buffer large enough to hold the expected - message.

-

indicates the size of .

-

If a tick occurs, i.e., the Erlang node on the + + is an open descriptor to an Erlang + connection. + is a buffer large enough to hold the + expected message. + indicates the size of + . + +

If a tick occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function will return and - no message will be placed in the buffer. Also, - will be set to .

+ is still alive, the function returns and + no message is placed in the buffer. Also, + is set to .

On success, the message is placed in the specified buffer and the function returns the number of bytes actually read. On - failure, the function returns a negative value and will set + failure, the function returns a negative value and sets to one of:

Temporary error: Try again. - Buffer too small. + Buffer is too small. I/O error. + interl_receive_msg(fd, bufp, bufsize, emsg) - Receive and decodes a message. + Receive and decode a message. + int fd; unsigned char *bufp; @@ -280,14 +329,20 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) ErlMessage *emsg; -

This function receives the message into the specified buffer, - and decodes into the .

-

is an open descriptor to an Erlang connection.

-

is a buffer large enough to hold the expected message.

-

indicates the size of .

-

is a pointer to an structure, - into which the message will be decoded. is - defined as follows:

+

Receives the message into the specified buffer + and decodes into .

+ + is an open descriptor to an Erlang + connection. + is a buffer large enough to hold the + expected message. + indicates the size of + . + > is a pointer to an + structure + into which the message will be decoded. + is defined as follows: +

The definition of has changed since - earlier versions of Erl_Interface.

+ earlier versions of Erl_Interface.

 -

identifies the type of message, one of - , , , - and . -

-

If contains - this indicates that an ordinary send operation has taken - place, and to]]> contains the Pid of the - recipient. If contains then a - registered send operation took place, and from]]> - contains the Pid of the sender. In both cases, the actual - message will be in msg]]>. -

-

If contains one of or - , then to]]> and from]]> - contain the pids of the sender and recipient of the link or unlink. - msg]]> is not used in these cases. -

-

If contains , then this - indicates that a link has been broken. In this case, - to]]> and from]]> contain the pids of the - linked processes, and msg]]> contains the reason for - the exit. -

+

identifies the type of message, one of the + following:

+ + + +

An ordinary send operation has occurred and + to]]> contains the pid of the recipient. + The message is in msg]]>.

+ + + +

A registered send operation has occurred and + from]]> contains the pid of the sender. + The message is in msg]]>.

+ + or + + +

to]]> and from]]> + contain the pids of the sender and recipient of the link or + unlink. msg]]> is not used.

+ + + +

A link is broken. to]]> and + from]]> contain the pids of the linked + processes, and msg]]> contains the reason + for the exit.

+ +

It is the caller's responsibility to release the - memory pointed to by msg]]>, to]]> and + memory pointed to by msg]]>, + to]]>, and from]]>.

 -

If a tick occurs, i.e., the Erlang node on the +

If a tick occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function will return + is still alive, the function returns indicating that the tick has been received and responded to, - but no message will be placed in the buffer. In this case you - should call again.

+ but no message is placed in the buffer. In this case you + are to call again.

On success, the function returns and the - struct will be initialized as described above, or + struct is initialized as described above, or , in which case no message is returned. On - failure, the function returns and will set + failure, the function returns and sets to one of:

- Buffer too small. + Buffer is too small. - No more memory available. + No more memory is available. I/O error. + interl_reg_send(fd, to, msg) Send a message to a registered name. + int fd; char *to; ETERM *msg; -

This function sends an Erlang term to a registered process.

-

is an open descriptor to an Erlang connection.

-

is a string containing the registered name of - the intended recipient of the message.

-

is the Erlang term to be sent.

-

The function returns 1 if successful, otherwise 0 --- in - which case it will set to one of:

+

Sends an Erlang term to a registered process.

+ + is an open descriptor to an Erlang + connection. + is a string containing the registered name + of the intended recipient of the message. + is the Erlang term to be sent. + +

Returns 1 on success, otherwise 0. In + the latter case is set to one of:

- No more memory available. + No more memory is available. I/O error. + ETERM *erl_rpc(fd, mod, fun, args) interl_rpc_from(fd, timeout, emsg) @@ -386,81 +455,97 @@ typedef struct { ErlMessage *emsg; -

These functions support calling Erlang functions on remote nodes. - sends an rpc request to a remote node and - receives the results of such a call. - combines the functionality of these two functions - by sending an rpc request and waiting for the results. See also - .

-

is an open descriptor to an Erlang connection.

-

is the maximum time (in ms) to wait for - results. Specify to wait forever. - When erl_rpc() calls erl_rpc_from(), the call will never - timeout.

-

is the name of the module containing the function - to be run on the remote node.

-

is the name of the function to run.

-

is an Erlang list, containing the arguments to be - passed to the function.

-

is a message containing the result of the - function call.

-

The actual message returned by the rpc server - is a 2-tuple . If you are using - in your code then this is the message you - will need to parse. If you are using then the +

Supports calling Erlang functions on remote nodes. + sends an RPC request to a remote node + and receives the results of such a + call. combines the functionality of + these two functions by sending an RPC request and waiting for the + results. See also + rpc:call/4 in Kernel.

+ + is an open descriptor to an Erlang + connection. + is the maximum time (in milliseconds) + to wait for + results. To wait forever, specify . + When erl_rpc() calls erl_rpc_from(), the call will + never timeout. + is the name of the module containing the + function to be run on the remote node. + is the name of the function to run. + + is an Erlang list, containing the + arguments to be passed to the function. + is a message containing the result of + the function call. + +

The actual message returned by the RPC server + is a 2-tuple . If you use + in your code, this is the message + you will need to parse. If you use , the tuple itself is parsed for you, and the message returned to your - program is the erlang term containing only. Replies - to rpc requests are always ERL_SEND messages. -

+ program is the Erlang term containing only. + Replies to RPC requests are always ERL_SEND messages.

It is the caller's responsibility to free the returned - structure as well as the memory pointed to by - msg]]> and to]]>.

+ structure and the memory pointed to by + msg]]> and to]]>.

 -

returns the remote function's return value (or - if it failed). returns 0 on - success, and a negative number on failure. - returns when successful (with now - containing the reply tuple), and one of , - and otherwise. When failing, +

returns the remote function's return + value on success, otherwise .

+

returns 0 on + success, otherwise a negative number.

+

returns + on success (with now + containing the reply tuple), otherwise one of + , , or + .

+

When failing, all three functions set to one of:

- No more memory available. + No more memory is available. I/O error. - Timeout expired. + Timeout has expired. Temporary error: Try again. + interl_send(fd, to, msg) Send a message. + int fd; ETERM *to, *msg; -

This function sends an Erlang term to a process.

-

is an open descriptor to an Erlang connection.

-

is an Erlang term containing the Pid of the - intended recipient of the message.

-

is the Erlang term to be sent.

-

The function returns 1 if successful, otherwise 0 --- in - which case it will set to one of:

+

Sends an Erlang term to a process.

+ + is an open descriptor to an Erlang + connection. + is an Erlang term containing the pid of + the intended recipient of the message. + > is the Erlang term to be sent. + +

Returns 1 on success, otherwise 0. In + the latter case is set to one of:

- Invalid argument: is not a valid Erlang pid. + Invalid argument: is not a valid Erlang + pid. - No more memory available. + No more memory is available. I/O error. + const char *erl_thisalivename() const char *erl_thiscookie() @@ -469,11 +554,13 @@ typedef struct { const char *erl_thisnodename() Retrieve some values. -

These functions can be used to retrieve information about - the C Node. These values are initially set with - or .

+

Retrieves information about + the C-node. These values are initially set with + or + .

 + interl_unpublish(alive) Forcefully unpublish a node name. @@ -482,28 +569,28 @@ typedef struct {

This function can be called by a process to unregister a - specified node from epmd on the localhost. This is however usually not - allowed, unless epmd was started with the -relaxed_command_check - flag, which it normally isn't.

- -

To unregister a node you have published, you should instead - close the descriptor that was returned by - .

- + specified node from EPMD on the local host. This is, however, usually + not allowed, unless EPMD was started with flag + -relaxed_command_check, which it normally is not.

+

To unregister a node you have published, you should instead + close the descriptor that was returned by + .

This function is deprecated and will be removed in a future - release.

+ release.

 -

is the name of the node to unregister, i.e., the - first component of the nodename, without the .

-

If the node was successfully unregistered from epmd, the - function returns 0. Otherwise, it returns -1 and sets - is to .

+

is the name of the node to unregister, that + is, the first component of the node name, without + .

+

If the node was successfully unregistered from EPMD, 0 is + returned, otherwise -1 is returned and + is set to .

 + interl_xreceive_msg(fd, bufpp, bufsizep, emsg) - Receive and decodes a message. + Receive and decode a message. int fd; unsigned char **bufpp; @@ -511,33 +598,35 @@ typedef struct { ErlMessage *emsg; -

This function is similar to . The - difference is that expects the buffer to - have been allocated by , and reallocates it if the received - message does not fit into the original buffer. For that reason, - both buffer and buffer length are given as pointers - their values - may change by the call. -

+

Similar to . The difference is + that expects the buffer to + have been allocated by , and reallocates it + if the received + message does not fit into the original buffer. Therefore + both buffer and buffer length are given as pointers; their values + can change by the call.

On success, the function returns and the - struct will be initialized as described above, or + struct is initialized as described above, or , in which case no message is returned. On - failure, the function returns and will set + failure, the function returns and sets to one of:

- Buffer too small. + Buffer is too small. - No more memory available. + No more memory is available. I/O error. + struct hostent*erl_gethostbyaddr(addr, length, type) struct hostent*erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop) struct hostent*erl_gethostbyname(name) struct hostent*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop) + Name lookup functions. const char *name; @@ -550,7 +639,7 @@ typedef struct { int *h_errnop; -

These are convenience functions for some common name lookup functions.

+

Convenience functions for some common name lookup functions.

 @@ -558,12 +647,13 @@ typedef struct {
Debug Information

If a connection attempt fails, the following can be checked:

+ - that the right cookie was used - that epmd is running - the remote Erlang node on the other side is running the same - version of Erlang as the library. + That the correct cookie was used + That EPMD is running + That the remote Erlang node on the other side is running the same + version of Erlang as the library
diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml index 5b8d546e12..a85969d7ff 100644 --- a/lib/erl_interface/doc/src/erl_error.xml +++ b/lib/erl_interface/doc/src/erl_error.xml @@ -28,21 +28,23 @@ Bjarne Däcker Torbjörn Törnkvist - 961014 + 1996-10-14 A erl_error.xml erl_error - Error Print Routines + Error print routines.

This module contains some error printing routines taken - from Advanced Programming in the UNIX Environment - by W. Richard Stevens.

+ from "Advanced Programming in the UNIX Environment" + by W. Richard Stevens.

+

These functions are all called in the same manner as - , i.e. with a string containing format specifiers - followed by a list of corresponding arguments. All output from + , that is, with a string containing format + specifiers followed by a list of corresponding arguments. All output from these functions is to .

 + voiderl_err_msg(FormatStr, ... ) @@ -55,6 +57,7 @@ function is simply a wrapper for .

 + voiderl_err_quit(FormatStr, ... ) Fatal error, but not system call error. @@ -63,11 +66,12 @@

Use this function when a fatal error has occurred that - is not due to a system call. The message provided by the - caller is printed and the process terminates with an exit - value of 1. The function does not return.

+ is not because of a system call. The message provided by the + caller is printed and the process terminates with exit + value 1. This function does not return.

 + voiderl_err_ret(FormatStr, ... ) Non-fatal system call error. @@ -80,6 +84,7 @@ describing the reason for failure.

 + voiderl_err_sys(FormatStr, ... ) Fatal system call error. @@ -90,7 +95,7 @@

Use this function after a failed system call. The message provided by the caller is printed followed by a string describing the reason for failure, and the process - terminates with an exit value of 1. The function does not + terminates with exit value 1. This function does not return.

 @@ -98,37 +103,41 @@
Error Reporting -

Most functions in erl_interface report failures to the caller by - returning some otherwise meaningless value (typically +

Most functions in Erl_Interface report failures to the caller by + returning some otherwise meaningless value (typically + or a negative number). As this only tells you that things did not - go well, you will have to examine the error code in - if you want to find out more about the failure.

+ go well, examine the error code in if you + want to find out more about the failure.

+ volatile interl_errno - The variable contains the erl_interface error number. You can change the value if you wish. + Variable contains the + Erl_Interface error number. You can change the value if you wish. + -

is initially (at program startup) zero and - is then set by many erl_interface functions on failure to a - non-zero error code to indicate what kind of error it - encountered. A successful function call might change +

is initially (at program startup) zero + and is then set by many Erl_Interface functions on failure to + a non-zero error code to indicate what kind of error it + encountered. A successful function call can change (by calling some other function that - fails), but no function will ever set it to zero. This means + fails), but no function does never set it to zero. This means that you cannot use to see if a function call failed. Instead, each function reports failure in its own way (usually by returning a negative number or - ), in which case you can examine - for details.

+ ), in which case you can examine + for details.

uses the error codes defined in your system's ]]>.

-

Actually, is a "modifiable lvalue" (just +

is a "modifiable lvalue" (just like ISO C defines to be) rather than a - variable. This means it might be implemented as a macro - (expanding to, e.g., ). For reasons of - thread- (or task-)safety, this is exactly what we do on most - platforms.

+ variable. This means it can be implemented as a macro + (expanding to, for example, ). + For reasons of thread safety (or task safety), this is exactly what + we do on most platforms.

 diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml index e5207a271e..8a46c20432 100644 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ b/lib/erl_interface/doc/src/erl_eterm.xml @@ -28,23 +28,26 @@ Bjarne Däcker Torbjörn Törnkvist - 980703 + 1998-07-03 A erl_eterm.xml erl_eterm - Functions for Erlang Term Construction + Functions for Erlang term construction. -

This module contains functions for creating and manipulating - Erlang terms.

+

This module provides functions for creating and manipulating + Erlang terms.

+

An Erlang term is represented by a C structure of type - . Applications should not reference any fields in this - structure directly, because it may be changed in future releases + . Applications should not reference any fields + in this structure directly, as it can be changed in future releases to provide faster and more compact term storage. Instead, - applications should us the macros and functions provided.

-

The following macros each take a single ETERM pointer as an - argument. They return a non-zero value if the test is true, and 0 - otherwise:

+ applications should use the macros and functions provided.

+ +

Each of the following macros takes a single ETERM pointer as an + argument. The macros return a non-zero value if the test is true, + otherwise 0.

+ True if is an integer. @@ -55,7 +58,7 @@ True if is an atom. - True if is a Pid (process identifier). + True if is a pid (process identifier). True if is a port. @@ -65,29 +68,31 @@ True if is a binary. - True if is a list with zero or more elements. + True if is a list with zero or more + elements. True if is an empty list. - True if is a list with at least one element. + True if is a list with at least one + element. +

The following macros can be used for retrieving parts of Erlang - terms. None of these do any type checking; results are undefined - if you pass an ETERM* containing the wrong type. For example, - passing a tuple to ERL_ATOM_PTR() will likely result in garbage. -

+ terms. None of these do any type checking. Results are undefined + if you pass an ETERM* containing the wrong type. For example, + passing a tuple to ERL_ATOM_PTR() likely results in garbage.

+ - + - A string representing atom . - + A string representing atom . - + - The length (in bytes) of atom t. + The length (in bytes) of atom . - A pointer to the contents of + A pointer to the contents of . The length (in bytes) of binary object . @@ -97,9 +102,9 @@ The floating point value of . - + - The Node in pid . + The node in pid . The sequence number in pid . @@ -111,16 +116,18 @@ The creation number in port . - + The node in port . - The first part of the reference number in ref . Use - only for compatibility. + The first part of the reference number in ref . + Use only for compatibility. - Pointer to the array of reference numbers in ref . + Pointer to the array of reference numbers in ref + . - The number of used reference numbers in ref . + The number of used reference numbers in ref + . The creation number in ref . @@ -128,31 +135,38 @@ The head element of list . - A List representing the tail elements of list . + A list representing the tail elements of list + . + ETERM *erl_cons(head, tail) - Prepends a term to the head of a list. + Prepend a term to the head of a list. ETERM *head; ETERM *tail; -

This function concatenates two Erlang terms, prepending - onto and thereby creating a cell. - To make a proper list, should always be a - list or an empty list. Note that NULL is not a valid list.

-

is the new term to be added.

-

is the existing list to which will - be concatenated.

+

Concatenates two Erlang terms, prepending + onto and thereby creating a + cell. + To make a proper list, is always to be a list + or an empty list. Notice that NULL is not a valid list.

+ + is the new term to be added. + is the existing list to which + is concatenated. +

The function returns a new list.

-

and +

and + can be used to retrieve the head and tail components - from the list. and will do + from the list. and + do the same thing, but check that the argument really is a list.

-

For example:

+

Example:

 + ETERM *erl_copy_term(term) - Creates a copy of an Erlang term. + Create a copy of an Erlang term. ETERM *term; -

This function creates and returns a copy of the Erlang term +

Creates and returns a copy of the Erlang term .

 + ETERM *erl_element(position, tuple) - Extracts an element from an Erlang tuple. + Extract an element from an Erlang tuple. int position; ETERM *tuple; -

This function extracts a specified element from an Erlang - tuple.

-

specifies which element to retrieve from - . The elements are numbered starting from 1.

-

is an Erlang term containing at least - elements.

-

The function returns a new Erlang term corresponding to the - requested element, or NULL if was greater than - the arity of .

+

Extracts a specified element from an Erlang tuple.

+ + specifies which element to retrieve + from . The elements are numbered starting + from 1. + is an Erlang term containing at least + elements. + +

Returns a new Erlang term corresponding to the requested element, or + NULL if was greater + than the arity of .

 + ETERM *erl_hd(list) - Extracts the first element from a list. + Extract the first element from a list. ETERM *list;

Extracts the first element from a list.

is an Erlang term containing a list.

-

The function returns an Erlang term corresponding to the - head element in the list, or a NULL pointer if was - not a list.

+

Returns an Erlang term corresponding to the head + head element in the list, or a NULL pointer if + was not a list.

 + voiderl_init(NULL, 0) Initialization routine. @@ -218,42 +238,45 @@ erl_free_compound(list); -

This function must be called before any of the others in - the library in order to initialize the +

This function must be called before any of the others in the + library to initialize the library functions. The arguments must be specified as .

 + interl_iolist_length(list) - Return the length of an IO list. + Return the length of an I/O list. ETERM *list; -

Returns the length of an IO list. -

-

is an Erlang term containing an IO list.

-

The function returns the length of , or -1 if - is not an IO list.

-

Refer to for the definition of - an IO list.

+

Returns the length of an I/O list.

+

is an Erlang term containing an I/O list.

+

Returns the length of , or + -1 if is not an I/O list.

+

For the definition of an I/O list, see + + erl_iolist_to_binary.

 + ETERM *erl_iolist_to_binary(term) - Converts an IO list to a binary. + Convert an I/O list to a binary. ETERM *list; -

This function converts an IO list to a binary term.

+

Converts an I/O list to a binary term.

is an Erlang term containing a list.

-

This function an Erlang binary term, or NULL if - was not an IO list.

-

Informally, an IO list is a deep list of characters and - binaries which can be sent to an Erlang port. In BNF, an IO - list is formally defined as follows:

+

Returns an Erlang binary term, or NULL if + was not an I/O list.

+ +

Informally, an I/O list is a deep list of characters and + binaries that can be sent to an Erlang port. In BNF, an I/O + list is formally defined as follows:

 + char *erl_iolist_to_string(list) - Converts an IO list to a zero terminated string. + Convert an I/O list to a zero-terminated string. ETERM *list; -

This function converts an IO list to a '\0' terminated C - string.

-

is an Erlang term containing an IO list. The IO - list must not contain the integer 0, since C strings may not +

Converts an I/O list to a '\0' terminated C string.

+

is an Erlang term containing an I/O list. + The I/O list must not contain the integer 0, as C strings may not contain this value except as a terminating marker.

-

This function returns a pointer to a dynamically allocated - buffer containing a string. If is not an IO list, - or if contains the integer 0, NULL is returned. It - is the caller's responsibility free the allocated buffer - with .

-

Refer to for the definition of an - IO list.

+

Returns a pointer to a dynamically allocated + buffer containing a string. If is not an I/O + list, or if contains the integer 0, + NULL is returned. It + is the caller's responsibility to free the allocated buffer + with .

+

For the definition of an I/O list, see + + erl_iolist_to_binary.

 + interl_length(list) - Determines the length of a list. + Determine the length of a list. ETERM *list;

Determines the length of a proper list.

-

is an Erlang term containing proper list. In a - proper list, all tails except the last point to another list +

is an Erlang term containing a proper list. + In a proper list, all tails except the last point to another list cell, and the last tail points to an empty list.

-

Returns -1 if is not a proper list.

+

Returns -1 if is not a proper + list.

 + ETERM *erl_mk_atom(string) - Creates an atom. + Create an atom. const char *string; @@ -311,97 +339,114 @@ iohead ::= Binary

Creates an atom.

is the sequence of characters that will be used to create the atom.

-

Returns an Erlang term containing an atom. Note that it is - the callers responsibility to make sure that +

Returns an Erlang term containing an atom. Notice that it is + the caller's responsibility to ensure that contains a valid name for an atom.

-

and - can be used to retrieve the atom name (as a null terminated string). - and returns the length of the atom name.

-

Note that the UTF8 variants were introduced in Erlang/OTP releases R16 - and the string returned by ERL_ATOM_PTR(atom) was not null terminated on older releases.

+

and + + can be used to retrieve the atom name (as a null-terminated string). + + and return the length + of the atom name.

+ +

The UTF-8 variants were introduced in Erlang/OTP R16 and the + string returned by ERL_ATOM_PTR(atom) was not + null-terminated on older releases.

 + ETERM *erl_mk_binary(bptr, size) - Creates a binary object. + Create a binary object. char *bptr; int size; -

This function produces an Erlang binary object from a +

Produces an Erlang binary object from a buffer containing a sequence of bytes.

-

is a pointer to a buffer containing data to be converted.

-

indicates the length of .

-

The function returns an Erlang binary object.

+ + is a pointer to a buffer containing + data to be converted. + indicates the length of + . + +

Returns an Erlang binary object.

retrieves a pointer to the binary data. retrieves the - size.

+ size.

 + ETERM *erl_mk_empty_list() - Creates an empty Erlang list. + Create an empty Erlang list. -

This function creates and returns an empty Erlang list. - Note that NULL is not used to represent an empty list; +

Creates and returns an empty Erlang list. + Notice that NULL is not used to represent an empty list; Use this function instead.

 + ETERM *erl_mk_estring(string, len) - Creates an Erlang string. + Create an Erlang string. char *string; int len; -

This function creates a list from a sequence of bytes.

-

is a buffer containing a sequence of - bytes. The buffer does not need to be zero-terminated.

-

is the length of .

-

The function returns an Erlang list object corresponding to +

Creates a list from a sequence of bytes.

+ + is a buffer containing a sequence of + bytes. The buffer does not need to be zero-terminated. + is the length of + . + +

Returns an Erlang list object corresponding to the character sequence in .

 + ETERM *erl_mk_float(f) - Creates an Erlang float. + Create an Erlang float. double f;

Creates an Erlang float.

-

is a value to be converted to an Erlang float.

-

-

The function returns an Erlang float object with the value - specified in or if - is not finite. -

+

is a value to be converted to an Erlang + float.

+

Returns an Erlang float object with the value + specified in or if + is not finite.

can be used to retrieve the - value from an Erlang float.

+ value from an Erlang float.

 + ETERM *erl_mk_int(n) - Creates an Erlang integer. + Create an Erlang integer. int n;

Creates an Erlang integer.

-

is a value to be converted to an Erlang integer.

-

-

The function returns an Erlang integer object with the +

is a value to be converted to an Erlang + integer.

+

Returns an Erlang integer object with the value specified in .

-

can be used to retrieve the value +

can be used to retrieve the value from an Erlang integer.

 + ETERM *erl_mk_list(array, arrsize) - Creates a list from an array. + Create a list from an array. ETERM **array; int arrsize; @@ -409,44 +454,51 @@ iohead ::= Binary

Creates an Erlang list from an array of Erlang terms, such that each element in the list corresponds to one element in - the array.

-

is an array of Erlang terms.

-

is the number of elements in .

+ the array.

+ + is an array of Erlang terms. + is the number of elements in + . +

The function creates an Erlang list object, whose length - and whose elements are taken from the terms in - .

+ and whose elements are taken from the + terms in .

 + ETERM *erl_mk_long_ref(node, n1, n2, n3, creation) - Creates an Erlang reference. + Create an Erlang reference. const char *node; unsigned int n1, n2, n3; unsigned int creation; -

This function creates an Erlang reference, with 82 bits.

-

is the name of the C node.

-

, and can be seen as one big number - which should be chosen uniquely for - each reference - created for a given C node.

-

is an arbitrary number.

-

Note that and are limited in - precision, so only the low 18 and 2 bits of these numbers - are actually used. -

-

The function returns an Erlang reference object.

-

, , - and - to retrieve the values used - to create the reference.

+

Creates an Erlang reference, with 82 bits.

+ + is the name of the C-node. + , , and + can be seen as one big number + , which is to be chosen + uniquely for each reference created for a given C-node. + is an arbitrary number. + +

Notice that and + are limited in precision, so only the low 18 and 2 bits of these + numbers are used.

+

Returns an Erlang reference object.

+

, + , + , and + can be used to retrieve the + values used to create the reference.

 + ETERM *erl_mk_pid(node, number, serial, creation) - Creates a process identifier. + Create a process identifier. const char *node; unsigned int number; @@ -454,106 +506,125 @@ iohead ::= Binary unsigned int creation; -

This function creates an Erlang process identifier. The +

Creates an Erlang process identifier (pid). The resulting pid can be used by Erlang processes wishing to - communicate with the C node.

-

is the name of the C node.

-

, and are - arbitrary numbers. Note though, that these are limited in - precision, so only the low 15, 3 and 2 bits of these numbers - are actually used.

-

The function returns an Erlang pid object.

-

, , - and + communicate with the C-node.

+ + is the name of the C-node. + , , and + are + arbitrary numbers. Notice that these are limited in + precision, so only the low 15, 3, and 2 bits of these numbers + are used. + +

Returns an Erlang pid object.

+

, + , + , and + can be used to retrieve the four values used to create the pid.

 + ETERM *erl_mk_port(node, number, creation) - Creates a port identifier. + Create a port identifier. const char *node; unsigned int number; unsigned int creation; -

This function creates an Erlang port identifier.

-

is the name of the C node.

-

and are arbitrary numbers. - Note though, that these are limited in - precision, so only the low 18 and 2 bits of these numbers - are actually used.

-

The function returns an Erlang port object.

-

, - and can be used to retrieve the three - values used to create the port.

+

Creates an Erlang port identifier.

+ + is the name of the C-node. + and are + arbitrary numbers. Notice that these are limited in + precision, so only the low 18 and 2 bits of these numbers + are used. + +

Returns an Erlang port object.

+

, + , + and can be used to retrieve the + three values used to create the port.

 + ETERM *erl_mk_ref(node, number, creation) - Creates an old Erlang reference. + Create an old Erlang reference. const char *node; unsigned int number; unsigned int creation; -

This function creates an old Erlang reference, with +

Creates an old Erlang reference, with only 18 bits - use instead.

-

is the name of the C node.

-

should be chosen uniquely for each reference - created for a given C node.

-

is an arbitrary number.

-

Note that and are limited in - precision, so only the low 18 and 2 bits of these numbers - are actually used. -

-

The function returns an Erlang reference object.

-

, , and - to retrieve the three values used - to create the reference.

+ + is the name of the C-node. + is to be chosen uniquely for each + reference created for a given C-node. + is an arbitrary number. + +

Notice that and + are limited in precision, so only the low 18 and 2 bits of these + numbers are used.

+

Returns an Erlang reference object.

+

, + , and + can be used to retrieve the + three values used to create the reference.

 + ETERM *erl_mk_string(string) - Creates a string. + Create a string. char *string; -

This function creates a list from a zero terminated string.

-

is the zero-terminated sequence of characters - (i.e. a C string) from which the list will be created.

-

The function returns an Erlang list.

+

Creates a list from a zero-terminated string.

+

is the zero-terminated sequence of + characters + (that is, a C string) from which the list will be created.

+

Returns an Erlang list.

 + ETERM *erl_mk_tuple(array, arrsize) - Creates an Erlang tuple from an array. + Create an Erlang tuple from an array. ETERM **array; int arrsize;

Creates an Erlang tuple from an array of Erlang terms.

-

is an array of Erlang terms.

-

is the number of elements in .

+ + is an array of Erlang terms. + is the number of elements in + . +

The function creates an Erlang tuple, whose arity is - and whose elements are taken from the terms in - .

-

To retrieve the size of a tuple, either use the - function (which checks the type of the checked - term and works for a binary as well as for a tuple), or the + and whose elements are taken from the terms + in .

+

To retrieve the size of a tuple, either use function + (which checks the type of the + checked term and works for a binary as well as for a tuple) or returns the arity of a tuple. - will do the same thing, but it checks that - the argument really is a tuple. + does the same thing, but it checks + that the argument is a tuple. returns the element - corresponding to a given position in the tuple.

+ corresponding to a given position in the tuple.

 + ETERM *erl_mk_uint(n) - Creates an unsigned integer. + Create an unsigned integer. unsigned int n; @@ -561,76 +632,83 @@ iohead ::= Binary

Creates an Erlang unsigned integer.

is a value to be converted to an Erlang unsigned integer.

-

-

The function returns an Erlang unsigned integer object with +

Returns an Erlang unsigned integer object with the value specified in .

can be used to retrieve the value from an Erlang unsigned integer.

 + ETERM *erl_mk_var(name) - Creates an Erlang variable. + Create an Erlang variable. char *name; -

This function creates an unbound Erlang variable. The - variable can later be bound through pattern matching or assignment.

+

Creates an unbound Erlang variable. The variable can later be bound + through pattern matching or assignment.

specifies a name for the variable.

-

The function returns an Erlang variable object with the - name .

+

Returns an Erlang variable object with the + name .

 + interl_print_term(stream, term) - Prints an Erlang term. + Print an Erlang term. FILE *stream; ETERM *term; -

This function prints the specified Erlang term to the given - output stream.

-

indicates where the function should send its - output.

-

is the Erlang term to print.

-

The function returns the number of characters written, or a - negative value if there was an error.

+

Prints the specified Erlang term to the specified output stream.

+ + indicates where the function is to + send its output. + is the Erlang term to print. + +

Returns the number of characters written on success, otherwise a + negative value.

 + voiderl_set_compat_rel(release_number) - Set the erl_interface library in compatibility mode. + Set the Erl_Interface 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 +

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 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 - directly after the call to the - erl_init() function.

+ directly after the call to function + erl_init().

You may run into trouble if this feature is used - carelessly. Always make sure that all communicating + 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.

 + interl_size(term) Return the arity of a tuple or binary. @@ -638,49 +716,55 @@ iohead ::= Binary ETERM *term; -

Returns the arity of an Erlang tuple, or the - number of bytes in an Erlang binary object.

-

is an Erlang tuple or an Erlang binary object.

-

The function returns the size of as described - above, or -1 if is not one of the two supported - types.

+

Returns either the arity of an Erlang tuple or the + number of bytes in an Erlang binary object.

+

is an Erlang tuple or an Erlang binary + object.

+

Returns the size of as described + above, or -1 if is not one of the two + supported types.

 + ETERM *erl_tl(list) - Extracts the tail from a list. + Extract the tail from a list. ETERM *list;

Extracts the tail from a list.

is an Erlang term containing a list.

-

The function returns an Erlang list corresponding to the - original list minus the first element, or NULL pointer if +

Returns an Erlang list corresponding to the + original list minus the first element, or NULL pointer if was not a list.

 + ETERM *erl_var_content(term, name) - Extracts the content of a variable. + Extract the content of a variable. ETERM *term; char *name; -

This function returns the contents of the specified - variable in an Erlang term. -

-

is an Erlang term. In order for this function - to succeed, must be an Erlang variable with the - specified name, or it must be an Erlang list or tuple - containing a variable with the specified name. Other Erlang - types cannot contain variables.

-

is the name of an Erlang variable.

+

Returns the contents of the specified variable in an Erlang term.

+ + is an Erlang term. In order for this + function to succeed, + must either be an Erlang variable with + the specified name, or it must be an Erlang list or tuple + containing a variable with the specified name. Other Erlang + types cannot contain variables. + is the name of an Erlang variable. + +

Returns the Erlang object corresponding to the value of - in . If no variable with the name - was found in , or if is - not a valid Erlang term, NULL is returned.

+ in . If no variable + with the name is found in + , or if is + not a valid Erlang term, NULL is returned.

 diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml index ce5163fbc7..9fe405d51c 100644 --- a/lib/erl_interface/doc/src/erl_format.xml +++ b/lib/erl_interface/doc/src/erl_format.xml @@ -28,51 +28,42 @@ Bjarne Däcker Torbjörn Törnkvist - 961016 + 1996-10-16 A erl_format.xml erl_format - Create and Match Erlang Terms + Create and match Erlang terms. -

This module contains two routines - one general function for +

This module contains two routines: one general function for creating Erlang terms and one for pattern matching Erlang terms.

 + - ETERM *erl_format(FormatStr, ... ) - Creates an Erlang term. + ETERM *erl_format(FormatStr, ...) + Create an Erlang term. char *FormatStr; -

This is a general function for creating Erlang terms using +

A general function for creating Erlang terms using a format specifier and a corresponding set of arguments, much in the way works.

-

is a format specification string. The set - of valid format specifiers is as follows:

+

is a format specification string. + The valid format specifiers are as follows:

- -

~i - Integer

- - -

~f - Floating point

- - -

~a - Atom

- - -

~s - String

- - -

~w - Arbitrary Erlang term

- + ~i - Integer + ~f - Floating point + ~a - Atom + ~s - String + ~w - Arbitrary Erlang term -

For each format specifier that appears in , +

For each format specifier included in , there must be a corresponding argument following - . An Erlang term is built according to the - with values and Erlang terms substituted from - the corresponding arguments and according to the individual + . An Erlang term is built according to + with values and Erlang terms substituted + from the corresponding arguments, and according to the individual format specifiers. For example:

-

This will create an structure corresponding - to the Erlang term: +

This creates an structure corresponding + to the Erlang term

-

The function returns an Erlang term, or NULL if - does not describe a valid Erlang term.

+

The function returns an Erlang term, or NULL if + does not describe a valid Erlang + term.

 + interl_match(Pattern, Term) - Performs pattern matching. + Perform pattern matching. + ETERM *Pattern,*Term;

This function is used to perform pattern matching similar - to that done in Erlang. Refer to an Erlang manual for matching - rules and more examples.

-

is an Erlang term, possibly containing unbound - variables.

-

is an Erlang term that we wish to match against - .

-

and are compared, and any - unbound variables in are bound to corresponding - values in .

-

If and can be matched, the - function returns a non-zero value and binds any unbound - variables in . If do - not match, the function returns 0. For example:

+ to that done in Erlang. For matching rules and more exemples, see + section + Pattern Matching in the Erlang Reference Manual.

+ + is an Erlang term, possibly + containing unbound variables. + is an Erlang term that we wish to match + against . + +

and are compared + and any unbound variables in are bound to + corresponding values in .

+

If and can be + matched, the function returns a non-zero value and binds any unbound + variables in . If + and do + not match, 0 is returned. For example:

Gordon Beaton Gordon Beaton - 980703 + 1998-07-03 A erl_global.xml erl_global - Access globally registered names + Access globally registered names.

This module provides support for registering, looking - up and unregistering names in the Erlang Global module. For more - information, see the description of Global in the reference manual.

-

Note that the functions below perform an RPC using an open file + up, and unregistering names in the global module. + For more information, see + kernel:global.

+ +

Notice that the functions below perform an RPC using an open file descriptor provided by the caller. This file descriptor must - not be used for other traffic during the global operation or the - function may receive unexpected data and fail.

+ not be used for other traffic during the global operation, as the + function can then receive unexpected data and fail.

 + char **erl_global_names(fd,count) - Obtain list of Global names. + Obtain list of global names. + int fd; int *count; -

Retrieve a list of all known global names. -

-

is an open descriptor to an Erlang connection. -

-

is the address of an integer, or NULL. If - is not NULL, it will be set by the function to - the number of names found. -

+

Retrieves a list of all known global names.

+ + is an open descriptor to an Erlang + connection. + is the address of an integer, or + NULL. If is not NULL, it is + set by the function to the number of names found. +

On success, the function returns an array of strings, each - containing a single registered name, and sets to + containing a single registered name, and sets + to the number of names found. The array is terminated - by a single NULL pointer. On failure, the function returns - NULL and is not modified. -

+ by a single NULL pointer. On failure, the function returns + NULL and is not modified.

It is the caller's responsibility to free the array afterwards. It has been allocated by the function with a - single call to , so a single is - all that is necessary.

+ single call to , so a single + is all that is necessary.

 + interl_global_register(fd,name,pid) - Register a name in Global. + Register a name in global. int fd; const char *name; ETERM *pid; -

This function registers a name in Global. -

-

is an open descriptor to an Erlang connection. -

-

is the name to register in Global. -

-

is the pid that should be associated with - . This is the value that Global will return when - processes request the location of . -

-

The function returns 0 on success, or -1 on failure.

+

Registers a name in global.

+ + is an open descriptor to an Erlang + connection. + is the name to register in + global. + is the pid that is to be associated with + . This value is returned by global + when processes request the location of . + + +

Returns 0 on success, otherwise -1.

 + interl_global_unregister(fd,name) - Unregister a name in Global. + Unregister a name from global. int fd; const char *name; -

This function unregisters a name from Global. -

-

is an open descriptor to an Erlang connection. -

-

is the name to unregister from Global. -

-

The function returns 0 on success, or -1 on failure.

+

Unregisters a name from global.

+ + is an open descriptor to an Erlang + connection. + is the name to unregister from + global. + +

Returns 0 on success, otherwise -1.

 + ETERM *erl_global_whereis(fd,name,node) Look up a name in global. @@ -122,19 +131,22 @@ char *node; -

is an open descriptor to an Erlang connection. -

-

is the name that is to be looked up in Global. -

-

If is not NULL, it is a pointer to a buffer - where the function can fill in the name of the node where - is found. can be passed directly to - if necessary. -

-

On success, the function returns an Erlang Pid containing the address - of the given name, and node will be initialized to - the nodename where is found. On failure NULL will be - returned and will not be modified.

+

Looks up a name in global.

+ + is an open descriptor to an Erlang + connection. + is the name that is to be looked up in + global. + +

If is not NULL, it is a pointer to a + buffer where the function can fill in the name of the node where + is found. can be + passed directly to if necessary.

+

On success, the function returns an Erlang pid containing the address + of the specified name, and the node is initialized to + the node name where is found. On failure, + NULL is returned and is not + modified.

 diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml index ba1f59a492..28de9dfa88 100644 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ b/lib/erl_interface/doc/src/erl_malloc.xml @@ -28,172 +28,177 @@ Bjarne Däcker Torbjörn Törnkvist - 980703 + 1998-07-03 A erl_malloc.xml erl_malloc - Memory Allocation Functions + Memory allocation functions.

This module provides functions for allocating and deallocating memory.

 + ETERM *erl_alloc_eterm(etype) - Allocates an ETERM structure. + Allocate an ETERM structure. unsigned char etype; -

This function allocates an structure. - Specify as one of the following constants:

+

Allocates an structure.

+

Specify as one of the following + constants:

- -

ERL_INTEGER

+ ERL_INTEGER - -

ERL_U_INTEGER

+ ERL_U_INTEGER (unsigned integer) - -

ERL_ATOM

+ ERL_ATOM - -

ERL_PID

+ ERL_PID (Erlang process identifier) - -

ERL_PORT

+ ERL_PORT - -

ERL_REF

+ ERL_REF (Erlang reference) - -

ERL_LIST

+ ERL_LIST - -

ERL_EMPTY_LIST

+ ERL_EMPTY_LIST - -

ERL_TUPLE

+ ERL_TUPLE - -

ERL_BINARY

+ ERL_BINARY - -

ERL_FLOAT

+ ERL_FLOAT - -

ERL_VARIABLE

+ ERL_VARIABLE - -

ERL_SMALL_BIG

+ ERL_SMALL_BIG (bignum) - -

ERL_U_SMALL_BIG

+ ERL_U_SMALL_BIG (bignum) -

and are for - creating Erlang , which can contain integers of - arbitrary size. The size of an integer in Erlang is machine - dependent, but in general any integer larger than 2^28 - requires a bignum.

+

and + are for + creating Erlang , which can contain integers + of any size. The size of an integer in Erlang is machine-dependent, + but any integer > 2^28 requires a bignum.

 + voiderl_eterm_release(void) - Clears the ETERM freelist. + Clear the ETERM freelist. -

Clears the - freelist, where blocks are placed when they are +

Clears the freelist, where blocks are placed when they are released by and - .

+ .

 + voiderl_eterm_statistics(allocated, freed) - Reports term allocation statistics. + Report term allocation statistics. long *allocated; long *freed; -

and are initialized to +

Reports term allocation statistics.

+

and are + initialized to contain information about the fix-allocator used to allocate - ETERM components. is the number of blocks - currently allocated to ETERM objects. is the - length of the freelist, where blocks are placed when they are - released by and - .

+ ETERM components.

+ + +

is the number of blocks currently + allocated to ETERM objects.

+ + +

is the length of the freelist, where + blocks are placed when they are + released by and + .

+ + + voiderl_free(ptr) - Frees some memory. + Free some memory. void *ptr; -

This function calls the standard - function.

+

Calls the standard + function.

 + voiderl_free_array(array, size) - Frees an array of ETERM structures. + Free an array of ETERM structures. ETERM **array; int size; -

This function frees an array of Erlang terms.

-

is an array of ETERM* objects. -

-

is the number of terms in the array.

+

Frees an array of Erlang terms.

+ + is an array of ETERM* objects. + is the number of terms in the array. + + + voiderl_free_compound(t) - Frees an array of ETERM structures. + Free an array of ETERM structures. ETERM *t;

Normally it is the programmer's responsibility to free each Erlang term that has been returned from any of the - functions. However since many of the + functions. However, as many of the functions that build new Erlang terms in fact share objects - with other existing terms, it may be difficult for the - programmer to maintain pointers to all such terms in order to - free them individually. -

-

will recursively free all of the - sub-terms associated with a given Erlang term, regardless of - whether we are still holding pointers to the sub-terms. -

-

There is an example in the User Manual under "Building - Terms and Patterns" -

+ with other existing terms, it can be difficult for the + programmer to maintain pointers to all such terms to + free them individually.

+

recursively frees all of the + subterms associated with a specified Erlang term, regardless of + whether we are still holding pointers to the subterms.

+

For an example, see section + Building Terms and + Patterns"> in the User's Guide.

 + voiderl_free_term(t) - Frees an ETERM structure. + Free an ETERM structure. + ETERM *t; -

Use this function to free an Erlang term.

+

Frees an Erlang term.

 + voiderl_malloc(size) - Allocates some memory. + Allocate some memory. long size; -

This function calls the standard - function.

+

Calls the standard + function.

 diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml index c70bdb53e1..30b7281a51 100644 --- a/lib/erl_interface/doc/src/erl_marshal.xml +++ b/lib/erl_interface/doc/src/erl_marshal.xml @@ -28,244 +28,240 @@ Bjarne Däcker Torbjörn Törnkvist - 980703 + 1998-07-03 A erl_marshal.xml erl_marshal - Encoding and Decoding of Erlang terms + Encoding and decoding of Erlang terms.

This module contains functions for encoding Erlang terms into a sequence of bytes, and for decoding Erlang terms from a sequence of bytes.

 + interl_compare_ext(bufp1, bufp2) - Compares encoded byte sequences. + Compare encoded byte sequences. unsigned char *bufp1,*bufp2; -

This function compares two encoded terms. -

-

is a buffer containing an encoded Erlang - term term1. -

-

is a buffer containing an encoded Erlang - term term2. -

-

The function returns 0 if the terms are equal, -1 if term1 - is less than term2, or 1 if term2 is less than term1. -

+

Compares two encoded terms.

+ + is a buffer containing an encoded + Erlang term term1. + is a buffer containing an encoded + Erlang term term2. + +

Returns 0 if the terms are equal, -1 if + term1 < term2, or 1 if term2 < + term1.

 + ETERM *erl_decode(bufp) ETERM *erl_decode_buf(bufpp) - Converts a term from Erlang external format. + Convert a term from Erlang external format. unsigned char *bufp; unsigned char **bufpp; -

and decode +

and + decode the contents of a buffer and return the corresponding - Erlang term. provides a simple + Erlang term. provides a simple mechanism for dealing with several encoded terms stored consecutively in the buffer.

-

is a pointer to a buffer containing one or - more encoded Erlang terms. -

-

is the address of a buffer pointer. The buffer - contains one or more consecutively encoded Erlang terms. - Following a successful call to , - will be updated so that it points to the next - encoded term. -

+ + +

is a pointer to a buffer containing one + or more encoded Erlang terms.

+ + +

is the address of a buffer pointer. The + buffer contains one or more consecutively encoded Erlang terms. + Following a successful call to + , is + updated so that it points to the next encoded term.

+ +

returns an Erlang term - corresponding to the contents of on success, or - NULL on failure. returns an Erlang + corresponding to the contents of on success, + otherwise NULL. + returns an Erlang term corresponding to the first of the consecutive terms in - and moves forward to point to the + and moves forward + to point to the next term in the buffer. On failure, each of the functions - returns NULL. -

+ return NULL.

 + interl_encode(term, bufp) interl_encode_buf(term, bufpp) - Converts a term into Erlang external format. + Convert a term into Erlang external format. ETERM *term; unsigned char *bufp; unsigned char **bufpp; -

and encode +

and + encode Erlang terms into external format for storage or transmission. provides a simple mechanism for - encoding several terms consecutively in the same - buffer. -

-

term is an Erlang term to be encoded. -

-

bufp is a pointer to a buffer containing one or - more encoded Erlang terms. -

-

bufpp is a pointer to a pointer to a buffer - containing one or more consecutively encoded Erlang terms. - Following a successful call to , - bufpp will be updated so that it points to the - position for the next encoded term. -

-

- These functions returns the number of bytes written to buffer - if successful, otherwise returns 0. -

-

Note that no bounds checking is done on the buffer. It is - the caller's responsibility to make sure that the buffer is + encoding several terms consecutively in the same buffer.

+ + +

term is an Erlang term to be encoded.

+ + +

bufp is a pointer to a buffer containing one or + more encoded Erlang terms.

+ + +

bufpp is a pointer to a pointer to a buffer + containing one or more consecutively encoded Erlang terms. + Following a successful call to + , bufpp is updated so + that it points to the + position for the next encoded term.

+ + +

These functions return the number of bytes written to buffer + on success, otherwise 0.

+

Notice that no bounds checking is done on the buffer. It is + the caller's responsibility to ensure that the buffer is large enough to hold the encoded terms. You can either use a - static buffer that is large enough to hold the terms you - expect to need in your program, or use - to determine the exact requirements for a given term. -

+ static buffer that is large enough to hold the terms you expect + to need in your program, or use + to determine the exact requirements for a given term.

The following can help you estimate the buffer - requirements for a term. Note that this information is - implementation specific, and may change in future versions. - If you are unsure, use . -

+ requirements for a term. Notice that this information is + implementation-specific, and can change in future versions. + If you are unsure, use .

Erlang terms are encoded with a 1 byte tag that identifies the type of object, a 2- or 4-byte length field, - and then the data itself. Specifically: -

+ and then the data itself. Specifically:

- need 5 bytes, plus the space for each element. + Need 5 bytes, plus the space for each element. - need 5 bytes, plus the space for each element, and 1 - additional byte for the empty list at the end. + Need 5 bytes, plus the space for each element, and 1 + more byte for the empty list at the end. - need 3 bytes, plus 1 byte for each character (the - terminating 0 is not encoded). Really long strings (more - than 64k characters) are encoded as lists. Atoms cannot - contain more than 256 characters. + Need 3 bytes, plus 1 byte for each character (the + terminating 0 is not encoded). Really long strings (more + than 64k characters) are encoded as lists. Atoms cannot + contain more than 256 characters. - need 5 bytes. + Need 5 bytes. - (integers < 256) need 2 bytes. + (Integers < 256) need 2 bytes. - need 32 bytes. + Need 32 bytes. - need 10 bytes, plus the space for the node name, which - is an atom. + Need 10 bytes, plus the space for the node name, which + is an atom. - need 6 bytes, plus the space for the node name, which - is an atom. + Need 6 bytes, plus the space for the node name, which + is an atom. -

The total space required will be the result calculated - from the information above, plus 1 additional byte for a - version identifier. -

+

The total space required is the result calculated + from the information above, plus 1 more byte for a + version identifier.

 + interl_ext_size(bufp) - Counts elements in encoded term. + Count elements in encoded term. unsigned char *bufp; -

This function returns the number of elements in an - encoded term.

+

Returns the number of elements in an encoded term.

 + unsigned charerl_ext_type(bufp) - Determines type of an encoded byte sequence. + Determine type of an encoded byte sequence. unsigned char *bufp; -

This function identifies and returns the type of Erlang term encoded - in a buffer. It will skip a trailing magic identifier. - Returns if the type can't be determined or one of

+

Identifies and returns the type of Erlang term encoded + in a buffer. It skips a trailing magic identifier.

+

Returns if the type cannot be determined or + one of:

- -

ERL_INTEGER

+ ERL_INTEGER - -

ERL_ATOM

+ ERL_ATOM - -

ERL_PID

+ ERL_PID (Erlang process identifier) - -

ERL_PORT

+ ERL_PORT - -

ERL_REF

+ ERL_REF (Erlang reference) - -

ERL_EMPTY_LIST

+ ERL_EMPTY_LIST - -

ERL_LIST

+ ERL_LIST - -

ERL_TUPLE

+ ERL_TUPLE - -

ERL_FLOAT

+ ERL_FLOAT - -

ERL_BINARY

+ ERL_BINARY - -

ERL_FUNCTION

+ ERL_FUNCTION + unsigned char *erl_peek_ext(bufp, pos) - Steps over encoded term. + Step over encoded term. unsigned char *bufp; int pos;

This function is used for stepping over one or more - encoded terms in a buffer, in order to directly access a - later term. -

-

is a pointer to a buffer containing one or - more encoded Erlang terms. -

-

indicates how many terms to step over in the - buffer. -

-

The function returns a pointer to a sub-term that can be - used in a subsequent call to in order to retrieve - the term at that position. If there is no term, or - would exceed the size of the terms in the buffer, NULL is returned. -

+ encoded terms in a buffer, to directly access later term.

+ + is a pointer to a buffer containing one + or more encoded Erlang terms. + indicates how many terms to step over in + the buffer. + +

Returns a pointer to a subterm that can be + used in a later call to to retrieve + the term at that position. If there is no term, or + would exceed the size of the terms in the + buffer, NULL is returned.

 + interl_term_len(t) - Determines encoded size of term. + Determine encoded size of term. ETERM *t; -

This function determines the buffer space that would be +

Determines the buffer space that would be needed by if it were encoded into Erlang external - format by . -

-

The size in bytes is returned. -

+ format by .

+

Returns the size in bytes.

 diff --git a/lib/erl_interface/doc/src/part.xml b/lib/erl_interface/doc/src/part.xml index d044e2b981..3b761df221 100644 --- a/lib/erl_interface/doc/src/part.xml +++ b/lib/erl_interface/doc/src/part.xml @@ -22,7 +22,7 @@ - EI User's Guide + Erl_Interface User's Guide Gordon Beaton 1998-11-30 diff --git a/lib/erl_interface/doc/src/ref_man.xml b/lib/erl_interface/doc/src/ref_man.xml index e23f00956a..1e20637cb7 100644 --- a/lib/erl_interface/doc/src/ref_man.xml +++ b/lib/erl_interface/doc/src/ref_man.xml @@ -21,7 +21,7 @@ limitations under the License. - Erl_Interface Command Reference + Erl_Interface Reference Manual Gordon Beaton 1998-11.30 @@ -29,17 +29,6 @@ ref_man.xml -

The ei and erl_interface are C interface libraries for - communication with Erlang.

- -

By default, the ei and erl_interface libraries are only guaranteed - to be compatible with other Erlang/OTP components from the same - release as the libraries themself. See the documentation of the - ei_set_compat_rel() and - erl_set_compat_rel() - functions on how to communicate with Erlang/OTP components from earlier - releases.

- diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml index fd3e29c30f..022af85149 100644 --- a/lib/erl_interface/doc/src/registry.xml +++ b/lib/erl_interface/doc/src/registry.xml @@ -28,18 +28,20 @@ Gordon Beaton Gordon Beaton - 980707 + 1998-07-07 A registry.xml registry - Store and backup key-value pairs. + Store and back up key-value pairs.

This module provides support for storing key-value pairs in a table known as a registry, backing up registries to - Mnesia in an atomic manner, and later restoring the contents of a - registry from Mnesia.

+ Mnesia + in an atomic manner, and later restoring the contents of a + registry from Mnesia.

 + intei_reg_close(reg) @@ -49,14 +51,13 @@

A registry that has previously been created with - is closed, and all the objects it contains - are freed. -

-

is the registry to close. -

-

The function returns 0.

+ is closed, and all the objects it + contains are freed.

+

is the registry to close.

+

Returns 0.

 + intei_reg_delete(reg,key) Delete an object from the registry. @@ -65,27 +66,28 @@ const char *key; -

Delete an object from the registry. The object is not - actually removed from the registry, it is only marked for later - removal so that on subsequent backups to Mnesia, the - corresponding object can be removed from the Mnesia table as +

Deletes an object from the registry. The object is not + removed from the registry, it is only marked for later + removal so that on later backups to Mnesia, the + corresponding object can be removed from the Mnesia table as well. If another object is later created with the same key, the - object will be reused. -

-

The object will be removed from the registry after a call to + object will be reused.

+

The object is removed from the registry after a call to or . -

-

is the registry containing . -

-

is the object to remove. -

-

If the object was found, the function returns 0 indicating - success. Otherwise the function returns -1.

+

+ + is the registry containing + . + is the object to remove. + +

Returns 0 on success, otherwise -1.

 + intei_reg_dump(fd,reg,mntab,flags) Back up a registry to Mnesia. + int fd; ei_reg *reg; @@ -93,38 +95,36 @@ int flags; -

Dump the contents of a registry to a Mnesia table in an - atomic manner, i.e. either all data will be updated, or none of - it will. If any errors are encountered while backing up - the data, the entire operation is aborted. -

-

is an open connection to Erlang. - Mnesia 3.0 or later must be running on the Erlang node. -

-

is the registry to back up. -

-

is the name of the Mnesia table where the backed - up data should be placed. If the table does not exist, it will - be created automatically using configurable defaults. See your - Mnesia documentation for information about configuring this - behaviour. -

-

If is 0, the backup will include only those - objects which have been created, modified or deleted since the - last backup or restore (i.e. an incremental backup). After the +

Dumps the contents of a registry to a Mnesia table in an + atomic manner, that is, either all data or no data is updated. + If any errors are encountered while backing up + the data, the entire operation is aborted.

+ + is an open connection to Erlang. + Mnesia 3.0 or later must be running on the Erlang node. + + is the registry to back up. + is the name of the Mnesia table + where the backed up data is to be placed. If the table does not + exist, it is created automatically using configurable defaults. + For information about configuring this behavior, see + Mnesia. + +

If is 0, the backup includes only + those objects that have been created, modified, or deleted since the + last backup or restore (that is, an incremental backup). After the backup, any objects that were marked dirty are now clean, and any - objects that had been marked for deletion are deleted. -

-

Alternatively, setting flags to EI_FORCE will cause a full - backup to be done, and EI_NOPURGE will cause the deleted objects - to be left in the registry afterwards. These can be bitwise ORed - together if both behaviours are desired. If EI_NOPURGE was - specified, you can use to explicitly remove - the deleted items from the registry later. -

-

The function returns 0 on success, or -1 on failure.

+ objects that had been marked for deletion are deleted.

+

Alternatively, setting flags to EI_FORCE causes a full + backup to be done, and EI_NOPURGE causes the deleted objects + to be left in the registry afterwards. These can be bitwise OR'ed + together if both behaviors are desired. If EI_NOPURGE was + specified, can be used to + explicitly remove the deleted items from the registry later.

+

Returns 0 on success, otherwise -1.

 + doubleei_reg_getfval(reg,key) Get a floating point object. @@ -133,22 +133,24 @@ const char *key; -

Get the value associated with in the - registry. The value must be a floating point type. -

-

is the registry where the object will be looked - up. -

-

is the name of the object to look up. -

-

On success, the function returns the value associated with . - If the object was not found or it was not a floating point - object, -1.0 is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between -1.0 and a - valid result) use the more general function - instead.

+

Gets the value associated with in the + registry. The value must be a floating point type.

+ + is the registry where the object will be + looked up. + is the name of the object to look up. + + +

On success, the function returns the value associated with + . + If the object is not found or if it is not a floating point + object, -1.0 is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between -1.0 and + a valid result), use the more general function + instead.

 + intei_reg_getival(reg,key) Get an integer object. @@ -157,22 +159,24 @@ const char *key; -

Get the value associated with in the - registry. The value must be an integer. -

-

is the registry where the object will be looked - up. -

-

is the name of the object to look up. -

-

On success, the function returns the value associated with . - If the object was not found or it was not an integer - object, -1 is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between -1 and a - valid result) use the more general function - instead.

+

Gets the value associated with in the + registry. The value must be an integer.

+ + is the registry where the object will be + looked up. + is the name of the object to look up. + + +

On success, the function returns the value associated with + . + If the object is not found or if it is not an integer + object, -1 is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between -1 and a + valid result), use the more general function + instead.

 + const void *ei_reg_getpval(reg,key,size) Get a binary object. @@ -182,26 +186,27 @@ int size; -

Get the value associated with in the - registry. The value must be a binary (pointer) type. -

-

is the registry where the object will be looked - up. -

-

is the name of the object to look up. -

-

will be initialized to contain the length in - bytes of the object, if it is found. -

+

Gets the value associated with in the + registry. The value must be a binary (pointer) type.

+ + is the registry where the object will be + looked up. + is the name of the object to look up. + + is initialized to contain the length in + bytes of the object, if it is found. +

On success, the function returns the value associated with - and indicates its length in . - If the object was not found or it was not a binary object, - NULL is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between NULL and a - valid result) use the more general function - instead.

+ and indicates its length in + . + If the object is not found or if it is not a binary object, + NULL is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between NULL and + a valid result), use the more general function + instead.

 + const char *ei_reg_getsval(reg,key) Get a string object. @@ -210,22 +215,23 @@ const char *key; -

Get the value associated with in the - registry. The value must be a string. -

-

is the registry where the object will be looked - up. -

-

is the name of the object to look up. -

+

Gets the value associated with in the + registry. The value must be a string.

+ + is the registry where the object will be + looked up. + is the name of the object to look up. + +

On success, the function returns the value associated with - . If the object was not found or it was not a string, - NULL is returned. To avoid problems with in-band error - reporting (i.e. if you cannot distinguish between NULL and a - valid result) use the more general function - instead.

+ . If the object is not found or if it is not a + string, NULL is returned. To avoid problems with in-band error + reporting (that is, if you cannot distinguish between NULL and + a valid result), use the more general function + instead.

 + intei_reg_getval(reg,key,flags,v,...) Get any object. @@ -236,56 +242,70 @@ void *v (see below) -

This is a general function for retrieving any kind of - object from the registry. -

-

is the registry where the object will be looked - up. -

-

is the name of the object to look up. -

-

indicates the type of object that you are - looking for. If is 0, then any kind of object will - be returned. If is one of EI_INT, EI_FLT, EI_STR or - EI_BIN, then only values of that kind will be returned. The - buffer pointed to by must be large enough to hold the return - data, i.e. it must be a pointer to one of , - , or , respectively. Also, - if is EI_BIN, then a fifth argument is required, so that the size of the object can be - returned. -

-

If the function succeeds, (and if the - object is binary) will be initialized with the value associated - with , and the function will return one of EI_INT, - EI_FLT, EI_STR or EI_BIN, indicating the type of object. On failure the - function will return -1 and the arguments will not be updated.

+

A general function for retrieving any kind of + object from the registry.

+ + +

is the registry where the object will be + looked up.

+ + +

is the name of the object to look up.

+ + +

indicates the type of object that you + are looking for. If is 0, any + kind of object is returned. + If is EI_INT, EI_FLT, + EI_STR, or EI_BIN, then only values of + that kind are returned.

+

The buffer pointed to by + must be large enough to hold the return data, that is, it must be + a pointer to one of , + , , or + , respectively.

+

If is EI_BIN, a fifth argument + is required, so that the size of the + object can be returned.

+ + +

On success, (and if the + object is binary) is initialized with the value associated + with , and the function returns EI_INT, + EI_FLT, EI_STR, or EI_BIN, indicating the type + of object. On failure, -1 is returned and the + arguments are not updated.

 + intei_reg_markdirty(reg,key) Mark an object as dirty. + ei_reg *reg; const char *key; -

Mark a registry object as dirty. This will ensure that - it is included in the next backup to Mnesia. Normally this - operation will not be necessary since all of the normal registry - 'set' functions do this automatically. However if you have +

Marks a registry object as dirty. This ensures that + it is included in the next backup to Mnesia. Normally this + operation is not necessary, as all of the normal registry + 'set' functions do this automatically. However, if you have retrieved the value of a string or binary object from the - registry and modified the contents, then the change will be - invisible to the registry and the object will be assumed to be + registry and modified the contents, then the change is + invisible to the registry and the object is assumed to be unmodified. This function allows you to make such modifications - and then let the registry know about them. -

-

is the registry containing the object. -

-

is the name of the object to mark. -

-

The function returns 0 on success, or -1 on failure.

+ and then let the registry know about them.

+ + is the registry containing the object. + + is the name of the object to mark. + + +

Returns 0 on success, otherwise -1.

 + ei_reg *ei_reg_open(size) Create and open a registry. @@ -293,24 +313,20 @@ int size; -

Open (create) a registry. The registry will be - initially empty. Use to close the registry - later. -

-

is the approximate number of objects you intend - to store in the registry. Since the registry uses a hash table - with collision chaining, there is no absolute upper limit on the - number of objects that can be stored in it. However for reasons +

Opens (creates) a registry, which initially is empty. To + close the registry later, use .

+

is the approximate number of objects you + intend to store in the registry. As the registry uses a hash table + with collision chaining, no absolute upper limit exists on the + number of objects that can be stored in it. However, for reasons of efficiency, it is a good idea to choose a number that is - appropriate for your needs. It is possible to use - to change the size later. Note that the - number you provide will be increased to the nearest larger prime - number. -

-

On success, an empty registry will be returned. On failure, NULL - will be returned.

+ appropriate for your needs. To change the size later, use + . Notice that the number + you provide is increased to the nearest larger prime number.

+

Returns an empty registry on success, otherwise NULL.

 + intei_reg_purge(reg) Remove deleted objects. @@ -318,20 +334,19 @@ ei_reg *reg; -

Remove all objects marked for deletion. When objects - are deleted with they are not actually - removed from the registry, only marked for later removal. This - is so that on a subsequent backup to Mnesia, the - objects can also be removed from the Mnesia table. If you are - not backing up to Mnesia then you may wish to remove the objects - manually with this function. -

+

Removes all objects marked for deletion. When objects + are deleted with they are not + removed from the registry, only marked for later removal. + On a later backup to Mnesia, the + objects can also be removed from the Mnesia table. If you are + not backing up to Mnesia, you may wish to remove the objects + manually with this function.

is a registry containing objects marked for - deletion. -

-

The function returns 0 on success, or -1 on failure.

+ deletion.

+

Returns 0 on success, otherwise -1.

 + intei_reg_resize(reg,newsize) Resize a registry. @@ -340,16 +355,15 @@ int newsize; -

Change the size of a registry. -

+

Changes the size of a registry.

is the new size to make the registry. The - number will be increased to the nearest larger prime number. -

-

On success, the registry will be resized, all contents - rehashed, and the function will return 0. On failure, the - registry will be left unchanged and the function will return -1.

+ number is increased to the nearest larger prime number.

+

On success, the registry is resized, all contents + rehashed, and 0 is returned. On failure, the + registry is left unchanged and -1 is returned.

 + intei_reg_restore(fd,reg,mntab) Restore a registry from Mnesia. @@ -359,35 +373,33 @@ const char *mntab; -

The contents of a Mnesia table are read into the - registry. -

-

is an open connection to Erlang. - Mnesia 3.0 or later must be running on the Erlang node. -

-

is the registry where the data should be placed. -

-

is the name of the Mnesia table to read data - from. -

-

Note that only tables of a certain format can be - restored, i.e. those that have been created and backed up to - with . If the registry was not empty before - the operation, then the contents of the table are added to the +

The contents of a Mnesia table are read into the registry.

+ + is an open connection to Erlang. + Mnesia 3.0 or later must be running on the Erlang node. + + is the registry where the data is to be + placed. + is the name of the Mnesia table + to read data from. + +

Notice that only tables of a certain format can be + restored, that is, those that have been created and backed up to + with . If the registry was not empty + before the operation, the contents of the table are added to the contents of the registry. If the table contains objects with the same keys as those already in the registry, the registry objects - will be overwritten with the new values. If the registry - contains objects that were not in the table, they will be - unchanged by this operation. -

+ are overwritten with the new values. If the registry + contains objects that were not in the table, they are + unchanged by this operation.

After the restore operation, the entire contents of the - registry is marked as unmodified. Note that this includes any + registry is marked as unmodified. Notice that this includes any objects that were modified before the restore and not - overwritten by the restore. -

-

The function returns 0 on success, or -1 on failure.

+ overwritten by the restore.

+

Returns 0 on success, otherwise -1.

 + intei_reg_setfval(reg,key,f) Assign a floating point object. @@ -397,20 +409,22 @@ double f; -

Create a key-value pair with the specified and - floating point value . If an object already existed with - the same , the new value replaces the old one. If the - previous value was a binary or string, it is freed with . -

-

is the registry where the object should be placed. -

-

is the name of the object. -

-

is the floating point value to assign. -

-

The function returns 0 on success, or -1 on failure.

+

Creates a key-value pair with the specified + and floating point value . If an object already + exists with the same , the new value replaces + the old one. If the previous value was a binary or string, it is + freed with .

+ + is the registry where the object is to be + placed. + is the object name. + is the floating point value to assign. + + +

Returns 0 on success, otherwise -1.

 + intei_reg_setival(reg,key,i) Assign an integer object. @@ -420,20 +434,21 @@ int i; -

Create a key-value pair with the specified and integer - value . If an object already existed with the same - , the new value replaces the old one. If the previous - value was a binary or string, it is freed with . -

-

is the registry where the object should be placed. -

-

is the name of the object. -

-

is the integer value to assign. -

-

The function returns 0 on success, or -1 on failure.

+

Creates a key-value pair with the specified + and integer value . If an object already exists + with the same , the new value replaces the old + one. If the previous value was a binary or string, it is freed with + .

+ + is the registry where the object is to be + placed. + is the object name. + is the integer value to assign. + +

Returns 0 on success, otherwise -1.

 + intei_reg_setpval(reg,key,p,size) Assign a binary object. @@ -444,26 +459,27 @@ int size; -

Create a key-value pair with the specified whose - "value" is the binary object pointed to by . If an - object already existed with the same , the new value - replaces the old one. If the previous value was a binary or - string, it is freed with . -

-

is the registry where the object should be placed. -

-

is the name of the object. -

-

is a pointer to the binary object. The object itself - must have been created through a single call to or - similar function, so that the registry can later delete it if - necessary by calling . -

-

is the length in bytes of the binary object. -

-

The function returns 0 on success, or -1 on failure.

+

Creates a key-value pair with the specified + whose "value" is the binary object pointed to by . + If an object already exists with the same , + the new value replaces the old one. If the previous value was a + binary or string, it is freed with .

+ + is the registry where the object is to be + placed. + is the object name. + is a pointer to the binary object. The + object itself must have been created through a single call to + or a similar function, so that the + registry can later delete it if necessary by calling + . + is the length in bytes of the binary + object. + +

Returns 0 on success, otherwise -1.

 + intei_reg_setsval(reg,key,s) Assign a string object. @@ -473,24 +489,25 @@ const char *s; -

Create a key-value pair with the specified whose - "value" is the specified string . If an object already - existed with the same , the new value replaces the old - one. If the previous value was a binary or string, it is freed - with . -

-

is the registry where the object should be placed. -

-

is the name of the object. -

-

is the string to assign. The string itself - must have been created through a single call to or - similar function, so that the registry can later delete it if - necessary by calling . -

-

The function returns 0 on success, or -1 on failure.

+

Creates a key-value pair with the specified + whose "value" is the specified string . If an + object already exists with the same , the new + value replaces the old one. If the previous value was a binary or + string, it is freed with .

+ + is the registry where the object is to be + placed. + is the object name. + is the string to assign. The string itself + must have been created through a single call to + or similar a function, + so that the registry can later delete it if + necessary by calling . + +

Returns 0 on success, otherwise -1.

 + intei_reg_setval(reg,key,flags,v,...) Assign a value to any object type. @@ -501,31 +518,41 @@ v (see below) -

Create a key-value pair with the specified whose - value is specified by . If an object already - existed with the same , the new value replaces the old - one. If the previous value was a binary or string, it is freed - with . -

-

is the registry where the object should be placed. -

-

is the name of the object. -

-

indicates the type of the object specified by - . Flags must be one of EI_INT, EI_FLT, EI_STR and - EI_BIN, indicating whether is , , - or . If is EI_BIN, then a - fifth argument is required, indicating the size - in bytes of the object pointed to by . -

+

Creates a key-value pair with the specified + whose value is specified by . If an object already + exists with the same , the new value replaces + the old one. If the previous value was a binary or string, it is freed + with .

+ + +

is the registry where the object is to be + placed.

+ + +

is the object name.

+ + +

indicates the type of the object + specified by . Flags must be one of + EI_INT, EI_FLT, EI_STR, and EI_BIN, + indicating whether + is , + , , or + .

+

If is EI_BIN, a fifth argument + is required, indicating the size + in bytes of the object pointed to by .

+ +

If you wish to store an arbitrary pointer in the registry, - specify a of 0. In this case, the object itself will - not be transferred by an operation, just - the pointer value. -

-

The function returns 0 on success, or -1 on failure.

+ specify a of 0. In this case, the + object itself is not transferred by an + operation, only the pointer + value.

+

Returns 0 on success, otherwise -1.

 + intei_reg_stat(reg,key,obuf) Get object information. @@ -535,34 +562,35 @@ struct ei_reg_stat *obuf; -

Return information about an object. -

-

is the registry containing the object. -

-

is the name of the object. -

-

is a pointer to an structure, - defined below: -

+

Returns information about an object.

+ + is the registry containing the object. + + is the object name. + is a pointer to an + structure, defined as follows: + -

In the object's attributes are stored as the logical - OR of its type (one of EI_INT, EI_FLT, EI_BIN and EI_STR), - whether it is marked for deletion (EI_DELET) and whether it has - been modified since the last backup to Mnesia (EI_DIRTY). -

-

The field indicates the size in bytes required to store - EI_STR (including the terminating 0) and EI_BIN objects, or 0 - for EI_INT and EI_FLT. -

-

The function returns 0 and initializes on - success, or returns -1 on failure.

+

In the attributes of the object are stored + as the logical OR of its type (one of EI_INT, + EI_FLT, EI_BIN, and EI_STR), + whether it is marked for deletion (EI_DELET), and whether it + has been modified since the last backup to Mnesia + (EI_DIRTY).

+

Field indicates the size in bytes required + to store EI_STR (including the terminating 0) and + EI_BIN objects, or 0 for EI_INT and + EI_FLT.

+

Returns 0 and initializes on success, + otherwise -1.

 + intei_reg_tabstat(reg,obuf) Get registry information. @@ -571,15 +599,16 @@ struct ei_reg_stat { struct ei_reg_tabstat *obuf; -

Return information about a registry. Using information +

Returns information about a registry. Using information returned by this function, you can see whether the size of the - registry is suitable for the amount of data it contains. -

-

is the registry to return information about. -

-

is a pointer to an structure, - defined below: -

+ registry is suitable for the amount of data it contains.

+ + is the registry to return information + about. + is a pointer to an + structure, defined as follows: + + -

The field indicates the number of hash positions +

Field indicates the number of hash positions in the registry. This is the number you provided when you created or last resized the registry, rounded up to the nearest - prime. -

-

indicates the number of elements stored in the - registry. It includes objects that are deleted but not purged. -

-

indicates the number of unique positions that are - occupied in the registry. -

-

indicates how many elements are sharing - positions in the registry. -

-

On success, the function returns 0 and is - initialized to contain table statistics. On failure, the function - returns -1.

+ prime number.

+ + indicates the number of elements stored + in the registry. It includes objects that are deleted but not + purged. + indicates the number of unique positions + that are occupied in the registry. + indicates how many elements are + sharing positions in the registry. + +

On success, 0 is returned and + is initialized to contain table statistics, + otherwise -1 is returned.

 -- cgit v1.2.3 From 036c56d3ee969daa39c1e03de69744ba394f0fe3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Thu, 20 Oct 2016 14:08:31 +0200 Subject: erl_interface: Fix editorial changes --- lib/erl_interface/doc/src/ei.xml | 20 ++++++++++---------- lib/erl_interface/doc/src/ei_connect.xml | 4 ++-- lib/erl_interface/doc/src/ei_users_guide.xml | 10 +++++----- lib/erl_interface/doc/src/erl_call.xml | 4 ++-- lib/erl_interface/doc/src/erl_connect.xml | 8 ++++---- lib/erl_interface/doc/src/erl_eterm.xml | 18 +++++++++--------- lib/erl_interface/doc/src/erl_format.xml | 4 ++-- lib/erl_interface/doc/src/erl_interface.xml | 6 +++--- lib/erl_interface/doc/src/erl_malloc.xml | 4 ++-- lib/erl_interface/doc/src/erl_marshal.xml | 2 +- lib/erl_interface/doc/src/part_erl_interface.xml | 5 ++--- lib/erl_interface/doc/src/ref_man_erl_interface.xml | 5 ++--- 12 files changed, 44 insertions(+), 46 deletions(-) (limited to 'lib/erl_interface') diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml index 6d416028a5..9b01f4af98 100644 --- a/lib/erl_interface/doc/src/ei.xml +++ b/lib/erl_interface/doc/src/ei.xml @@ -97,7 +97,7 @@ buffer must be allocated large enough, and for non-compound types the function returns the size required (notice that for strings an - extra byte is needed for the 0 string terminator).

+ extra byte is needed for the NULL-terminator).

@@ -110,14 +110,14 @@ typedef enum { ERLANG_ASCII = 1, ERLANG_LATIN1 = 2, ERLANG_UTF8 = 4 -}erlang_char_encoding; +} 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.

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

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

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 + are encoded. The name is to be NULL-terminated, except for the function.

@@ -426,7 +426,7 @@ typedef enum { (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 + (ASCII, Latin-1, or UTF-8). The name must either be NULL-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 @@ -645,7 +645,7 @@ 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 zero-terminated, except for + format.) The string is to be NULL-terminated, except for the function.

 @@ -731,7 +731,7 @@ ei_encode_tuple_header(buf, &i, 0);

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

@@ -753,7 +753,7 @@ ei_encode_tuple_header(buf, &i, 0); 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.

+ 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 contain a valid term. diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index a5a020ffda..08ae3db071 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -303,7 +303,7 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { Publish a node name.

Used by a server process to register - with the local name server epmd, thereby allowing + with the local name server EPMD, thereby allowing other processes to send messages by using the registered name. Before calling either of these functions, the process should have called and @@ -570,7 +570,7 @@ if (ei_reg_send(&ec, fd, x.buff, x.index) < 0) call. combines the functionality of these two functions by sending an RPC request and waiting for the results. See also - rpc:call/4 in Kernel.

+ rpc:call/4 in Kernel.

is the C-node structure previously diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index 9499a07467..e6f4acb55f 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.xml @@ -106,7 +106,7 @@ Eshell V4.7.4 (abort with ^G) argument on the command line, or add it to the definition in your . The correct value for this path is - Vsn, + , where:

@@ -115,7 +115,7 @@ Eshell V4.7.4 (abort with ^G) in the example above.

 -

Vsn is the version of the Erl_Interface application, +

is the version of the Erl_Interface application, for example, .

 @@ -552,8 +552,8 @@ erl_free_term(reply); ]]>
Using Global Names

A C node has access to names registered through the - kernel:global - module. Names can be looked up, allowing the C node to send messages + global + module in Kernel. Names can be looked up, allowing the C node to send messages to named Erlang services. C nodes can also register global names, allowing them to provide named services to Erlang processes or other C nodes.

@@ -648,7 +648,7 @@ erl_global_unregister(fd,servicename); ]]> detailed information about the individual API functions, see the registry module.

-

Keys are strings, that is, zero-terminated arrays of characters, and +

Keys are strings, that is, NULL-terminated arrays of characters, and values are arbitrary objects. Although integers and floating point numbers are treated specially by the registry, you can store strings or binary objects of any type as pointers.

diff --git a/lib/erl_interface/doc/src/erl_call.xml b/lib/erl_interface/doc/src/erl_call.xml index ebd9172f98..706dd271cc 100644 --- a/lib/erl_interface/doc/src/erl_call.xml +++ b/lib/erl_interface/doc/src/erl_call.xml @@ -215,8 +215,8 @@ Y=2,

(In the example, the output has been formatted afterwards.)

P = processes(), diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml index a027cb0a84..3796a763c3 100644 --- a/lib/erl_interface/doc/src/erl_connect.xml +++ b/lib/erl_interface/doc/src/erl_connect.xml @@ -165,7 +165,7 @@ erl_xconnect( &addr , ALIVE );

Initializes the module. In particular, these functions are used to identify the name of the C-node from which they are called. One of these functions must - be called before any of the other functions in the erl_connect + be called before any of the other functions in the erl_connect module are used.

stores for later use information about:

@@ -196,7 +196,7 @@ erl_xconnect( &addr , ALIVE );

is the node name. It is to - be of the form alivename@hostname.

+ be of the form alivename@hostname.

is the 32-bit IP address of @@ -212,7 +212,7 @@ erl_xconnect( &addr , ALIVE ); and variables on Windows. For more details, see the - kernel:auth module.

+ auth module in Kernel.

helps identifying a particular @@ -255,7 +255,7 @@ if (!erl_connect_init(17, "samplecookiestring...", 0))

This function is used by a server process to register - with the local name server epmd, thereby allowing + with the local name server EPMD, thereby allowing other processes to send messages by using the registered name. Before calling this function, the process should have called and diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml index 8a46c20432..ee10c3cf0b 100644 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ b/lib/erl_interface/doc/src/erl_eterm.xml @@ -201,13 +201,13 @@ erl_free_compound(list);

Extracts a specified element from an Erlang tuple.

- + specifies which element to retrieve from . The elements are numbered starting from 1. is an Erlang term containing at least elements. - +

Returns a new Erlang term corresponding to the requested element, or NULL if was greater than the arity of .

@@ -292,12 +292,12 @@ iohead ::= Binary char *erl_iolist_to_string(list) - Convert an I/O list to a zero-terminated string. + Convert an I/O list to a NULL-terminated string. ETERM *list; -

Converts an I/O list to a '\0' terminated C string.

+

Converts an I/O list to a NULL-terminated C string.

is an Erlang term containing an I/O list. The I/O list must not contain the integer 0, as C strings may not contain this value except as a terminating marker.

@@ -344,14 +344,14 @@ iohead ::= Binary contains a valid name for an atom.

and - can be used to retrieve the atom name (as a null-terminated string). + can be used to retrieve the atom name (as a NULL-terminated string). and return the length of the atom name.

The UTF-8 variants were introduced in Erlang/OTP R16 and the string returned by ERL_ATOM_PTR(atom) was not - null-terminated on older releases.

+ NULL-terminated on older releases.

 @@ -400,7 +400,7 @@ iohead ::= Binary

Creates a list from a sequence of bytes.

is a buffer containing a sequence of - bytes. The buffer does not need to be zero-terminated. + bytes. The buffer does not need to be NULL-terminated. is the length of . @@ -586,8 +586,8 @@ iohead ::= Binary char *string; -

Creates a list from a zero-terminated string.

-

is the zero-terminated sequence of +

Creates a list from a NULL-terminated string.

+

is a NULL-terminated sequence of characters (that is, a C string) from which the list will be created.

Returns an Erlang list.

diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml index 9fe405d51c..170e984b34 100644 --- a/lib/erl_interface/doc/src/erl_format.xml +++ b/lib/erl_interface/doc/src/erl_format.xml @@ -89,8 +89,8 @@ erl_format("[{name,~a},{age,~i},{data,~w}]",

This function is used to perform pattern matching similar - to that done in Erlang. For matching rules and more exemples, see - section + to that done in Erlang. For matching rules and more examples, see + section Pattern Matching in the Erlang Reference Manual.

is an Erlang term, possibly diff --git a/lib/erl_interface/doc/src/erl_interface.xml b/lib/erl_interface/doc/src/erl_interface.xml index a9d421bbeb..2a3831cf0f 100644 --- a/lib/erl_interface/doc/src/erl_interface.xml +++ b/lib/erl_interface/doc/src/erl_interface.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + The Erl_Interface Library @@ -500,7 +500,7 @@ erl_global_unregister(fd,servicename); ]]> restoring them from a Mnesia table on an Erlang node. More detailed information about the individual API functions can be found in the Reference Manual.

-

Keys are strings, i.e. 0-terminated arrays of characters, and values +

Keys are strings, i.e. NULL-terminated arrays of characters, and values are arbitrary objects. Although integers and floating point numbers are treated specially by the registry, you can store strings or binary objects of any type as pointers.

diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml index 28de9dfa88..3891073158 100644 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ b/lib/erl_interface/doc/src/erl_malloc.xml @@ -173,8 +173,8 @@ subterms associated with a specified Erlang term, regardless of whether we are still holding pointers to the subterms.

For an example, see section - Building Terms and - Patterns"> in the User's Guide.

+ Building Terms and Patterns + in the User's Guide.

diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml index 30b7281a51..b333bc9993 100644 --- a/lib/erl_interface/doc/src/erl_marshal.xml +++ b/lib/erl_interface/doc/src/erl_marshal.xml @@ -57,7 +57,7 @@

Returns 0 if the terms are equal, -1 if term1 < term2, or 1 if term2 < - term1.

+ term1.

diff --git a/lib/erl_interface/doc/src/part_erl_interface.xml b/lib/erl_interface/doc/src/part_erl_interface.xml index 2abe7ecd60..e256cfa193 100644 --- a/lib/erl_interface/doc/src/part_erl_interface.xml +++ b/lib/erl_interface/doc/src/part_erl_interface.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + Erl_Interface User's Guide @@ -31,4 +31,3 @@ - diff --git a/lib/erl_interface/doc/src/ref_man_erl_interface.xml b/lib/erl_interface/doc/src/ref_man_erl_interface.xml index fb39c5a7e4..4b1d0e9981 100644 --- a/lib/erl_interface/doc/src/ref_man_erl_interface.xml +++ b/lib/erl_interface/doc/src/ref_man_erl_interface.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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + Erl_Interface Library Reference @@ -50,4 +50,3 @@ - -- cgit v1.2.3 From 3a6ece2c93372fff5dba6914bdcf2d70e5b941e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Thu, 20 Oct 2016 16:34:04 +0200 Subject: erl_interface: Fix xmllint problems --- lib/erl_interface/doc/src/ei_connect.xml | 2 -- lib/erl_interface/doc/src/erl_connect.xml | 6 ------ lib/erl_interface/doc/src/erl_eterm.xml | 6 +----- lib/erl_interface/doc/src/erl_format.xml | 1 - lib/erl_interface/doc/src/erl_global.xml | 1 - lib/erl_interface/doc/src/erl_malloc.xml | 1 - lib/erl_interface/doc/src/registry.xml | 2 -- 7 files changed, 1 insertion(+), 18 deletions(-) (limited to 'lib/erl_interface') diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index 08ae3db071..06b54dbff4 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -348,7 +348,6 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { intei_receive(int fd, unsigned char* bufp, int bufsize) Receive a message. -

Receives a message consisting of a sequence of bytes in the Erlang external format.

@@ -432,7 +431,6 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { intei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x) intei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x) Receive a message. -

Receives a message to the buffer in . allows the buffer in diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml index 3796a763c3..a6b9e586f4 100644 --- a/lib/erl_interface/doc/src/erl_connect.xml +++ b/lib/erl_interface/doc/src/erl_connect.xml @@ -51,7 +51,6 @@ interl_accept(listensock, conp) Accept a connection. - int listensock; ErlConnect *conp; @@ -153,7 +152,6 @@ erl_xconnect( &addr , ALIVE ); interl_connect_init(number, cookie, creation) interl_connect_xinit(host, alive, node, addr, cookie, creation) Initialize communication. - int number; char *cookie; @@ -281,7 +279,6 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) interl_receive(fd, bufp, bufsize) Receive a message. - int fd; char *bufp; @@ -321,7 +318,6 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) interl_receive_msg(fd, bufp, bufsize, emsg) Receive and decode a message. - int fd; unsigned char *bufp; @@ -417,7 +413,6 @@ typedef struct { interl_reg_send(fd, to, msg) Send a message to a registered name. - int fd; char *to; @@ -518,7 +513,6 @@ typedef struct { interl_send(fd, to, msg) Send a message. - int fd; ETERM *to, *msg; diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml index ee10c3cf0b..e619232e4c 100644 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ b/lib/erl_interface/doc/src/erl_eterm.xml @@ -237,7 +237,6 @@ erl_free_compound(list); int 0; -

This function must be called before any of the others in the library to initialize the library functions. The arguments must be specified as @@ -273,7 +272,6 @@ erl_free_compound(list);

is an Erlang term containing a list.

Returns an Erlang binary term, or NULL if was not an I/O list.

-

Informally, an I/O list is a deep list of characters and binaries that can be sent to an Erlang port. In BNF, an I/O list is formally defined as follows:

@@ -676,16 +674,14 @@ iohead ::= Binary voiderl_set_compat_rel(release_number) Set the Erl_Interface 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 Erlang/OTP R10 + For example, from Erlang/OTP R10 is not compatible with an Erlang emulator from Erlang/OTP R9 by default.

A call to sets diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml index 170e984b34..f6f27326ff 100644 --- a/lib/erl_interface/doc/src/erl_format.xml +++ b/lib/erl_interface/doc/src/erl_format.xml @@ -83,7 +83,6 @@ erl_format("[{name,~a},{age,~i},{data,~w}]", interl_match(Pattern, Term) Perform pattern matching. - ETERM *Pattern,*Term; diff --git a/lib/erl_interface/doc/src/erl_global.xml b/lib/erl_interface/doc/src/erl_global.xml index fa565ba56c..0808ea0eee 100644 --- a/lib/erl_interface/doc/src/erl_global.xml +++ b/lib/erl_interface/doc/src/erl_global.xml @@ -50,7 +50,6 @@ char **erl_global_names(fd,count) Obtain list of global names. - int fd; int *count; diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml index 3891073158..2892afdf01 100644 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ b/lib/erl_interface/doc/src/erl_malloc.xml @@ -181,7 +181,6 @@ voiderl_free_term(t) Free an ETERM structure. - ETERM *t; diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml index 022af85149..14b31d91a6 100644 --- a/lib/erl_interface/doc/src/registry.xml +++ b/lib/erl_interface/doc/src/registry.xml @@ -87,7 +87,6 @@ intei_reg_dump(fd,reg,mntab,flags) Back up a registry to Mnesia. - int fd; ei_reg *reg; @@ -281,7 +280,6 @@ intei_reg_markdirty(reg,key) Mark an object as dirty. - ei_reg *reg; const char *key; -- cgit v1.2.3 From 7f237ebf67c24d4bec111f04dd81a83c83fd76f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Thu, 20 Oct 2016 17:09:13 +0200 Subject: erl_interface: Fix broken links in documentation --- lib/erl_interface/doc/src/ei_connect.xml | 2 +- lib/erl_interface/doc/src/ei_users_guide.xml | 6 +++--- lib/erl_interface/doc/src/erl_interface.xml | 5 ++--- lib/erl_interface/doc/src/erl_malloc.xml | 2 +- lib/erl_interface/doc/src/registry.xml | 4 ++-- 5 files changed, 9 insertions(+), 10 deletions(-) (limited to 'lib/erl_interface') diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index 06b54dbff4..be34fb7c53 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -292,7 +292,7 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) {

Used to set tracing on the distribution. The levels are different verbosity levels. A higher level means more information. See also - section + section Debug Information.

These functions are not thread safe.

 diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index e6f4acb55f..2c82f9ae7f 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.xml @@ -45,7 +45,7 @@ storage Communication between C nodes and Erlang processes Backup and restore of C node state to and from - Mnesia + Mnesia

By default, the Erl_Interface libraries are only guaranteed @@ -207,7 +207,7 @@ i = erl_encode(tuple, buf); ]]>

- + Building Terms and Patterns

The previous example can be simplified by using the erl_format module @@ -733,7 +733,7 @@ ei_reg_close(reg); ]]>

Backing Up the Registry to Mnesia

The contents of a registry can be backed up to - Mnesia on a "nearby" Erlang + Mnesia on a "nearby" Erlang node. You must provide an open connection to the Erlang node (see erl_connect). Also, Mnesia 3.0 or later must be running diff --git a/lib/erl_interface/doc/src/erl_interface.xml b/lib/erl_interface/doc/src/erl_interface.xml index 2a3831cf0f..ab5b46cc01 100644 --- a/lib/erl_interface/doc/src/erl_interface.xml +++ b/lib/erl_interface/doc/src/erl_interface.xml @@ -153,7 +153,7 @@ i = erl_encode(tuple, buf); ]]>

Building Terms and Patterns -

The previous example can be simplified by using +

The previous example can be simplified by using to create an Erlang term.

As in previous examples, it is your responsibility to free the - memory allocated for Erlang terms. In this example, + memory allocated for Erlang terms. In this example, ensures that the complete term pointed to by is released. This is necessary, because the pointer from the second call to is lost.

@@ -623,4 +623,3 @@ ei_reg_restore(fd, reg, "mtab"); ]]>
- diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml index 2892afdf01..e08924ec51 100644 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ b/lib/erl_interface/doc/src/erl_malloc.xml @@ -173,7 +173,7 @@ subterms associated with a specified Erlang term, regardless of whether we are still holding pointers to the subterms.

For an example, see section - Building Terms and Patterns + Building Terms and Patterns in the User's Guide.

diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml index 14b31d91a6..00b8f770de 100644 --- a/lib/erl_interface/doc/src/registry.xml +++ b/lib/erl_interface/doc/src/registry.xml @@ -37,7 +37,7 @@

This module provides support for storing key-value pairs in a table known as a registry, backing up registries to - Mnesia + Mnesia in an atomic manner, and later restoring the contents of a registry from Mnesia.

 @@ -107,7 +107,7 @@ where the backed up data is to be placed. If the table does not exist, it is created automatically using configurable defaults. For information about configuring this behavior, see - Mnesia. + Mnesia.

If is 0, the backup includes only those objects that have been created, modified, or deleted since the -- cgit v1.2.3 From 2aa61a092b11c63387574622f473ac16d8ace6e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Thu, 20 Oct 2016 18:10:24 +0200 Subject: erl_interface: Remove unused file --- lib/erl_interface/doc/src/fascicules.xml | 24 ------------------------ 1 file changed, 24 deletions(-) delete mode 100644 lib/erl_interface/doc/src/fascicules.xml (limited to 'lib/erl_interface') diff --git a/lib/erl_interface/doc/src/fascicules.xml b/lib/erl_interface/doc/src/fascicules.xml deleted file mode 100644 index f7edd8a973..0000000000 --- a/lib/erl_interface/doc/src/fascicules.xml +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - EI User's Guide - - - EI Library Reference - - - Erl_interface Library Reference - - - Command Reference - - - Release Notes - - - Off-Print - - - -- cgit v1.2.3 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 +++++++++---------- lib/erl_interface/doc/src/ei_connect.xml | 334 +++++++++++------------ lib/erl_interface/doc/src/ei_users_guide.xml | 152 +++++------ lib/erl_interface/doc/src/erl_call.xml | 76 +++--- lib/erl_interface/doc/src/erl_connect.xml | 332 +++++++++++------------ lib/erl_interface/doc/src/erl_error.xml | 32 +-- lib/erl_interface/doc/src/erl_eterm.xml | 392 +++++++++++++-------------- lib/erl_interface/doc/src/erl_format.xml | 38 +-- lib/erl_interface/doc/src/erl_global.xml | 42 +-- lib/erl_interface/doc/src/erl_interface.xml | 198 +++++++------- lib/erl_interface/doc/src/erl_malloc.xml | 36 +-- lib/erl_interface/doc/src/erl_marshal.xml | 66 ++--- lib/erl_interface/doc/src/ref_man_ei.xml | 13 +- lib/erl_interface/doc/src/registry.xml | 244 ++++++++--------- 14 files changed, 1117 insertions(+), 1118 deletions(-) (limited to 'lib/erl_interface') 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. diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index be34fb7c53..607a7cbff4 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -44,32 +44,32 @@ erlang:nodes/0 in ERTS.

-

The environment variable can be used +

The environment variable ERL_EPMD_PORT can be used to indicate which logical cluster a C-node belongs to.

Time-Out Functions

Most functions appear in a version with the suffix - appended to the function name. Those functions + _tmo appended to the function name. Those functions take an extra argument, a time-out in milliseconds. The semantics is this: for each communication primitive involved in the operation, if the primitive does not complete within the time specified, the function returns an error and - is set to . + erl_errno is set to ETIMEDOUT. With communication primitive is meant an operation on the socket, like - , , - , or .

+ connect, accept, + recv, or send.

Clearly the time-outs are for implementing fault tolerance, - not to keep hard real-time promises. The functions + not to keep hard real-time promises. The _tmo functions are for detecting non-responsive peers and to avoid blocking on socket operations.

-

A time-out value of (zero) means that time-outs are - disabled. Calling a function with the last - argument as is therefore the same thing as calling - the function without the suffix.

+

A time-out value of 0 (zero) means that time-outs are + disabled. Calling a _tmo function with the last + argument as 0 is therefore the same thing as calling + the function without the _tmo suffix.

As with all other functions starting with ei_, you are not expected @@ -80,9 +80,9 @@ avoid problems, leave the socket options alone. ei handles any socket options that need modification.

-

In all other senses, the functions inherit all +

In all other senses, the _tmo functions inherit all the return values and the semantics from the functions without - the suffix.

+ the _tmo suffix.

@@ -105,15 +105,15 @@ connection from a client process.

-

is the C-node structure.

+

ec is the C-node structure.

 -

is an open socket descriptor on - which has previously been called.

+

listensock is an open socket descriptor on + which listen() has previously been called.

 -

is a pointer to an - struct, described as follows:

+

conp is a pointer to an + ErlConnect struct, described as follows:

 -

On success, is filled in with the address and +

On success, conp is filled in with the address and node name of the connecting client and a file descriptor is - returned. On failure, is returned and - is set to .

+ returned. On failure, ERL_ERROR is returned and + erl_errno is set to EIO.

 @@ -146,34 +146,34 @@ typedef struct { Establish a connection to an Erlang node.

Sets up a connection to an Erlang node.

-

requires the IP address of the +

ei_xconnect() requires the IP address of the remote host and the alive name of the remote node to be - specified. provides an alternative + specified. ei_connect() provides an alternative interface and determines the information from the node name provided.

- is the 32-bit IP address of the remote + addr is the 32-bit IP address of the remote host. - is the alivename of the remote node. + alive is the alivename of the remote node. - is the name of the remote node. + node is the name of the remote node.

These functions return an open file descriptor on success, or a negative value indicating that an error occurred. In the latter - case they set to one of the + case they set erl_errno to one of the following:

- - The remote host is unreachable. - + EHOSTUNREACH + The remote host node is unreachable. + ENOMEM No more memory is available. - + EIO I/O error. -

Also, values from - (2) and - (2) - system calls may be propagated into .

+

Also, errno values from + socket(2) and + connect(2) + system calls may be propagated into erl_errno.

Example:

intei_connect_xinit(ei_cnode* ec, const char *thishostname, const char *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr, const char *cookie, short creation) Initialize for a connection. -

Initializes the structure, to +

Initializes the ec structure, to identify the node name and cookie of the server. One of them must be called before other functions that works on the - type or a file descriptor associated with + ei_cnode type or a file descriptor associated with a connection to another node is used.

-

is a structure containing information about - the C-node. It is used in other functions +

ec is a structure containing information about + the C-node. It is used in other ei functions for connecting and receiving data.

 -

is the registered name of the +

this_node_name is the registered name of the process (the name before '@').

 -

is the cookie for the node.

+

cookie is the cookie for the node.

 -

identifies a specific instance of a +

creation identifies a specific instance of a C-node. It can help prevent the node from receiving messages sent to an earlier process with the same registered name.

 -

is the name of the machine we are +

thishostname is the name of the machine we are running on. If long names are to be used, they are to be fully - qualified (that is, - instead of ).

+ qualified (that is, durin.erix.ericsson.se + instead of durin).

 -

is the registered name of the +

thisalivename is the registered name of the process.

 -

is the full name of the node, - that is, .

+

thisnodename is the full name of the node, + that is, einode@durin.

 -

if the IP address of the host.

+

thispaddr if the IP address of the host.

A C-node acting as a server is assigned a creation - number when it calls .

+ number when it calls ei_publish().

A connection is closed by simply closing the socket. For information about how to close the socket gracefully (when there are outgoing packets before close), see the relevant system @@ -306,32 +306,32 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { with the local name server EPMD, thereby allowing other processes to send messages by using the registered name. Before calling either of these functions, the process should - have called and + have called bind() and listen() on an open socket.

-

is the C-node structure.

+

ec is the C-node structure.

 -

is the local name to register, and is to +

port is the local name to register, and is to be the same as the port number that was previously bound to the socket.

 -

is the 32-bit IP address of the local +

addr is the 32-bit IP address of the local host.

To unregister with EPMD, simply close the returned descriptor. Do - not use , which is deprecated + not use ei_unpublish(), which is deprecated anyway.

On success, the function returns a descriptor connecting the calling process to EPMD. On failure, -1 is returned and - is set to .

-

Also, values from - (2) and - (2) system calls may be propagated - into .

+ erl_errno is set to EIO.

+

Also, errno values from + socket(2) and + connect(2) system calls may be propagated + into erl_errno.

 @@ -353,34 +353,34 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { of bytes in the Erlang external format.

-

is an open descriptor to an Erlang +

fd is an open descriptor to an Erlang connection. It is obtained from a previous - or .

+ ei_connect or ei_accept.

 -

is a buffer large enough to hold the +

bufp is a buffer large enough to hold the expected message.

 -

indicates the size of - .

+

bufsize indicates the size of + bufp.

If a tick occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function returns and + is still alive, the function returns ERL_TICK and no message is placed in the buffer. Also, - is set to .

+ erl_errno is set to EAGAIN.

On success, the message is placed in the specified buffer and the function returns the number of bytes actually read. On - failure, the function returns and sets - to one of the following:

+ failure, the function returns ERL_ERROR and sets + erl_errno to one of the following:

- + EAGAIN Temporary error: Try again. - + EMSGSIZE Buffer is too small. - + EIO I/O error. @@ -394,20 +394,20 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { generated by the interface compiler and with code following examples in the same application.

In essence, the function performs the same operation as - , but instead of using an + ei_xreceive_msg, but instead of using an ei_x_buff, the function expects a pointer to a character - pointer (), where the character pointer - is to point to a memory area allocated by . - Argument is to be a pointer to an integer + pointer (mbufp), where the character pointer + is to point to a memory area allocated by malloc. + Argument bufsz is to be a pointer to an integer containing the exact size (in bytes) of the memory area. The function may reallocate the memory area and will in such cases put the new - size in and update - .

+ size in *bufsz and update + *mbufp.

Returns either ERL_TICK or the - field of the - . The length - of the message is put in . On error - a value is returned.

+ msgtype field of the + erlang_msg *msg. The length + of the message is put in *msglen. On error + a value < 0 is returned.

It is recommended to use ei_xreceive_msg instead when possible, for the sake of readability. However, the function will be retained in the interface for compatibility and @@ -432,23 +432,23 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { intei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x) Receive a message. -

Receives a message to the buffer in . - allows the buffer in - to grow, but +

Receives a message to the buffer in x. + ei_xreceive_msg allows the buffer in + x to grow, but ei_receive_msg fails if the message is larger than the pre-allocated buffer in - .

+ x.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is a pointer to an - structure + msg is a pointer to an + erlang_msg structure and contains information on the message received. - is buffer obtained from - . + x is buffer obtained from + ei_x_new. -

On success, the functions return and the - struct is initialized. - is defined as follows:

+

On success, the functions return ERL_MSG and the + msg struct is initialized. + erlang_msg is defined as follows:

-

identifies the type of message, and is +

msgtype identifies the type of message, and is one of the following:

- + ERL_SEND

Indicates that an ordinary send operation has occurred. - to]]> contains the pid of the recipient (the + msg->to contains the pid of the recipient (the C-node).

 - + ERL_REG_SEND

A registered send operation occurred. - from]]> contains the pid of the sender.

+ msg->from contains the pid of the sender.

 - or - + ERL_LINK or + ERL_UNLINK -

to]]> and - from]]> contain the pids of the +

msg->to and + msg->from contain the pids of the sender and recipient of the link or unlink.

 - + ERL_EXIT -

Indicates a broken link. to]]> and - from]]> contain the pids of the linked +

Indicates a broken link. msg->to and + msg->from contain the pids of the linked processes.

 @@ -520,19 +520,19 @@ typedef struct {

Sends an Erlang term to a registered process.

-

is an open descriptor to an Erlang +

fd is an open descriptor to an Erlang connection.

 - is the registered name of the + server_name is the registered name of the intended recipient. - is the buffer containing the term in + buf is the buffer containing the term in binary format. - is the length of the message in bytes. + len is the length of the message in bytes.

Returns 0 if successful, otherwise -1. In - the latter case it sets to - .

+ the latter case it sets erl_errno to + EIO.

Example:

Send the atom "ok" to the process "worker":

Remote Procedure Call from C to Erlang.

Supports calling Erlang functions on remote nodes. - sends an RPC request to a remote node - and receives the results of such a - call. combines the functionality of these + ei_rpc_to() sends an RPC request to a remote node + and ei_rpc_from() receives the results of such a + call. ei_rpc() combines the functionality of these two functions by sending an RPC request and waiting for the results. See also rpc:call/4 in Kernel.

-

is the C-node structure previously - initiated by a call to or - .

+

ec is the C-node structure previously + initiated by a call to ei_connect_init() or + ei_connect_xinit().

 -

is an open descriptor to an Erlang +

fd is an open descriptor to an Erlang connection.

 -

is the maximum time (in milliseconds) - to wait for results. Specify to +

timeout is the maximum time (in milliseconds) + to wait for results. Specify ERL_NO_TIMEOUT to wait forever. - waits infinitely for the answer, + ei_rpc() waits infinitely for the answer, that is, the call will never time out.

 -

is the name of the module containing the +

mod is the name of the module containing the function to be run on the remote node.

 -

is the name of the function to run.

+

fun is the name of the function to run.

 -

is a pointer to a buffer with an +

argbuf is a pointer to a buffer with an encoded Erlang list, without a version magic number, containing the arguments to be passed to the function.

 -

is the length of the buffer +

argbuflen is the length of the buffer containing the encoded Erlang list.

 -

is structure of type - and contains information on the +

msg is structure of type + erlang_msg and contains information on the message - received. For a description of the + received. For a description of the erlang_msg format, see ei_receive_msg.

 -

points to the dynamic buffer that receives - the result. For this is the result +

x points to the dynamic buffer that receives + the result. For ei_rpc() this is the result without the version magic number. For - the result returns a version - magic number and a 2-tuple .

+ ei_rpc_from() the result returns a version + magic number and a 2-tuple {rex,Reply}.

 -

returns the number of bytes in the +

ei_rpc() returns the number of bytes in the result on success and -1 on failure. - returns the - number of bytes, otherwise one of , - , - and . When failing, all three - functions set to one of the + ei_rpc_from() returns the + number of bytes, otherwise one of ERL_TICK, + ERL_TIMEOUT, + and ERL_ERROR. When failing, all three + functions set erl_errno to one of the following:

- + EIO I/O error. - + ETIMEDOUT Time-out expired. - + EAGAIN Temporary error: Try again.

Example:

@@ -662,11 +662,11 @@ if (ei_decode_version(result.buff, &index) < 0 Retrieve the pid of the C-node.

Retrieves the pid of the C-node. Every C-node - has a (pseudo) pid used in , - , - and others. This is contained in a field in the + has a (pseudo) pid used in ei_send_reg, + ei_rpc, + and others. This is contained in a field in the ec structure. It will be safe for a long time to fetch this - field directly from the structure.

+ field directly from the ei_cnode structure.

 @@ -676,18 +676,18 @@ if (ei_decode_version(result.buff, &index) < 0

Sends an Erlang term to a process.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is the pid of the intended recipient of + to is the pid of the intended recipient of the message. - is the buffer containing the term in + buf is the buffer containing the term in binary format. - is the length of the message in bytes. + len is the length of the message in bytes.

Returns 0 if successful, otherwise -1. In - the latter case it sets to - .

+ the latter case it sets erl_errno to + EIO.

 @@ -720,14 +720,14 @@ if (ei_decode_version(result.buff, &index) < 0

This function is retained for compatibility with code generated by the interface compiler and with code following examples in the same application.

-

The function works as with one - exception. Instead of taking as first +

The function works as ei_reg_send with one + exception. Instead of taking ei_cnode as first argument, it takes a second argument, an - , + erlang_pid, which is to be the process identifier of the sending process (in the Erlang distribution protocol).

-

A suitable can be constructed from the - structure by the following example +

A suitable erlang_pid can be constructed from the + ei_cnode structure by the following example code:

num = fd;

Can be used to retrieve information about the C-node. These values are initially set with - or - .

+ ei_connect_init() or + ei_connect_xinit().

These function simply fetch the appropriate field from the - + ec structure. Read the field directly will probably be safe for a long time, so these functions are not really needed.

 @@ -788,16 +788,16 @@ self->num = fd; -relaxed_command_check, which it normally is not.

To unregister a node you have published, you should close the descriptor that was returned by - .

+ ei_publish().

This function is deprecated and will be removed in a future release.

 -

is the node structure of the node to +

ec is the node structure of the node to unregister.

If the node was successfully unregistered from EPMD, the function returns 0. Otherwise, -1 is returned and - is set to .

+ erl_errno is set to EIO.

 @@ -818,18 +818,18 @@ self->num = fd;

If a connection attempt fails, the following can be checked:

- . + erl_errno. That the correct cookie was used That EPMD is running That the remote Erlang node on the other side is running the - same version of Erlang as the library - That environment variable + same version of Erlang as the ei library + That environment variable ERL_EPMD_PORT is set correctly

The connection attempt can be traced by setting a trace level by either - using or by setting environment - variable . + using ei_set_tracelevel or by setting environment + variable EI_TRACELEVEL. The trace levels have the following messages:

diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index 2c82f9ae7f..0eed50b50b 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.xml @@ -102,21 +102,21 @@ Eshell V4.7.4 (abort with ^G) /usr/local/otp ]]>

To compile your code, ensure that your C compiler knows where - to find by specifying an appropriate - argument on the command line, or add it to - the definition in your - . The correct value for this path is - , + to find erl_interface.h by specifying an appropriate + -I argument on the command line, or add it to + the CFLAGS definition in your + Makefile. The correct value for this path is + $OTPROOT/lib/erl_interface-$EIVSN/include, where:

-

is the path reported by - in the example above.

+

$OTPROOT is the path reported by + code:root_dir/0 in the example above.

 -

is the version of the Erl_Interface application, - for example, .

+

$EIVSN is the version of the Erl_Interface application, + for example, erl_interface-3.2.3.

 @@ -128,16 +128,16 @@ $ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c ]]>

When linking:

- Specify the path to and - with - . + Specify the path to liberl_interface.a and + libei.a with + -L$OTPROOT/lib/erl_interface-3.2.3/lib. Specify the name of the libraries with - . + -lerl_interface -lei.

Do this on the command line or add the flags to the - definition in your - .

+ LDFLAGS definition in your + Makefile.

Linking the code:

@@ -146,9 +146,9 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ lib myprog.o -lerl_interface -lei -o myprog ]]>

On some systems it can be necessary to link with some more - libraries (for example, and - on Solaris, or - on Windows) to use the + libraries (for example, libnsl.a and + libsocket.a on Solaris, or + wsock32.lib on Windows) to use the communication facilities of Erl_Interface.

If you use the Erl_Interface functions in a threaded @@ -156,18 +156,18 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ Erl_Interface needs access to some of the synchronization facilities in your threads package. You must specify extra compiler flags to indicate which of the packages you use. Define - and either or - . The default is to use POSIX threads if - is specified.

+ _REENTRANT and either STHREADS or + PTHREADS. The default is to use POSIX threads if + _REENTRANT is specified.

Initializing the Erl_Interface Library

Before calling any of the other Erl_Interface functions, call - exactly once to initialize the library. - takes two arguments. However, the arguments + erl_init() exactly once to initialize the library. + erl_init() takes two arguments. However, the arguments are no longer used by Erl_Interface and are therefore to be - specified as .

+ specified as erl_init(NULL,0).

@@ -181,7 +181,7 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ several C functions that create and manipulate Erlang data structures. The library also contains an encode and a decode function. The following example shows how to create and encode an Erlang tuple - :

+ {tobbe,3928}:

-

Alternatively, you can use and - , which handle the encoding and +

Alternatively, you can use erl_send() and + erl_receive_msg, which handle the encoding and decoding of messages transparently.

For a complete description, see the following modules:

@@ -232,8 +232,8 @@ erl_free_compound(ep); ]]>

As in the previous examples, it is your responsibility to free the memory allocated for Erlang terms. In this example, - ensures that the complete term - pointed to by is released. This is necessary + erl_free_compound() ensures that the complete term + pointed to by ep is released. This is necessary because the pointer from the second call to erl_format is lost.

The following example shows a slightly different solution:

@@ -247,7 +247,7 @@ erl_free_term(ep); erl_free_term(ep2); ]]>

In this case, you free the two terms independently. The order in - which you free the terms and + which you free the terms ep and ep2 is not important, because the Erl_Interface library uses reference counting to determine when it is safe to remove objects.

@@ -274,7 +274,7 @@ erl_eterm_release();
Pattern Matching

An Erlang pattern is a term that can contain unbound variables or - symbols. Such a pattern can be matched + "do not care" symbols. Such a pattern can be matched against a term and, if the match is successful, any unbound variables in the pattern will be bound as a side effect. The content of a bound @@ -348,7 +348,7 @@ erl_connect_init(identification_number, cookie, creation); ]]>

After initialization, you set up the connection to the Erlang node. To specify the Erlang node you want to connect to, use - . The following example sets up the + erl_connect(). The following example sets up the connection and is to result in a valid socket file descriptor:

-

prints the specified string and +

erl_err_quit() prints the specified string and terminates the program. For more information, see the erl_error module.

@@ -366,24 +366,24 @@ if ((sockfd = erl_connect(nodename)) < 0) Using EPMD

erts:epmd is the Erlang Port Mapper Daemon. Distributed - Erlang nodes register with on the local host to + Erlang nodes register with epmd on the local host to indicate to other nodes that they exist and can accept connections. - maintains a register of + epmd maintains a register of node and port number information, and when a node wishes to connect to - another node, it first contacts to find the + another node, it first contacts epmd to find the correct port number to connect to.

When you use erl_connect to connect to an Erlang node, a connection is first made to - and, if the node is known, a + epmd and, if the node is known, a connection is then made to the Erlang node.

-

C nodes can also register themselves with +

C nodes can also register themselves with epmd if they want other nodes in the system to be able to find and connect to them.

-

Before registering with , you must first +

Before registering with epmd, you must first create a listen socket and bind it to a port. Then:

-

is a file descriptor now connected to - . +

pub is a file descriptor now connected to + epmd. epmd monitors the other end of the connection. If it detects that the connection has been closed, the node becomes unregistered. So, if you explicitly close the descriptor or if your node fails, it becomes - unregistered from .

+ unregistered from epmd.

Notice that on some systems (such as VxWorks), a failed node is not detected by this mechanism, as the operating system does not automatically close descriptors that were left open when the node - failed. If a node has failed in this way, + failed. If a node has failed in this way, epmd prevents you from registering a new node with the old name, as it thinks that the old name is still in use. In this case, you must unregister the name @@ -410,7 +410,7 @@ pub = erl_publish(port); ]]> -

This causes to close the connection from the +

This causes epmd to close the connection from the far end. Notice that if the name was in fact still in use by a node, the results of this operation are unpredictable. Also, doing this does not cause the @@ -442,15 +442,15 @@ erl_unpublish(node); ]]> erl_connect:erl_receive_msg -

receives the message into a buffer, - while decodes the message into an +

erl_receive() receives the message into a buffer, + while erl_receive_msg() decodes the message into an Erlang term.

Example of Sending Messages -

In the following example, is - sent to a registered process . The message - is encoded by :

+

In the following example, {Pid, hello_world} is + sent to a registered process my_server. The message + is encoded by erl_send():

The first element of the tuple that is sent is your own - pid. This enables to reply. + pid. This enables my_server to reply. For more information about the primitives, see the erl_connect module.

Example of Receiving Messages -

In this example, is received. The +

In this example, {Pid, Something} is received. The received pid is then used to return - .

+ {goodbye,Pid}.

message. This is done automatically by - . However, when this has occurred, - returns to + ERL_TICK message. This is done automatically by + erl_receive(). However, when this has occurred, + erl_receive returns ERL_TICK to the caller without storing a message into the - structure.

+ ErlMessage structure.

When a message has been received, it is the caller's responsibility - to free the received message and - or , + to free the received message emsg.msg and + emsg.to or emsg.from, depending on the type of message received.

For more information, see the @@ -538,14 +538,14 @@ if (!erl_match(ep, reply)) erl_free_term(ep); erl_free_term(reply); ]]> -

is called to compile the specified module on - the remote node. checks that the +

c:c/1 is called to compile the specified module on + the remote node. erl_match() checks that the compilation was - successful by testing for the expected .

+ successful by testing for the expected ok.

-

For more information about and its - companions and - , see the +

For more information about erl_rpc() and its + companions erl_rpc_to() and + erl_rpc_from(), see the erl_connect module.

@@ -582,15 +582,15 @@ free(names); ]]> erl_global:erl_global_names allocates and returns a buffer containing all the names known to the global module in Kernel. - is initialized to + count is initialized to indicate the number of names in the array. The array of strings in names is terminated by a NULL pointer, so it is not necessary to use - to determine when the last name is reached.

+ count to determine when the last name is reached.

It is the caller's responsibility to free the array. erl_global_names allocates the array and all the strings - using a single call to , so - is all that is necessary.

+ using a single call to malloc(), so + free(names) is all that is necessary.

To look up one of the names:

@@ -600,16 +600,16 @@ char node[256]; pid = erl_global_whereis(fd,"schedule",node); ]]> -

If is known to the +

If "schedule" is known to the global module in Kernel, an Erlang pid is returned that can be used to send messages to the schedule service. - Also, is initialized to contain the name of + Also, node is initialized to contain the name of the node where the service is registered, so that you can make a connection to it by simply passing the variable to erl_connect.

Before registering a name, you should already have registered your - port number with . This is not strictly necessary, + port number with epmd. This is not strictly necessary, but if you neglect to do so, then other nodes wishing to communicate with your service cannot find or connect to your process.

@@ -629,7 +629,7 @@ erl_global_register(fd,servicename,pid); ]]> to wait for incoming connections.

-

Remember to free later with +

Remember to free pid later with erl_malloc:erl_free_term.

 @@ -743,7 +743,7 @@ ei_reg_close(reg); ]]> ei_reg_dump(fd, reg, "mtab", dumpflags); ]]>

This example back up the contents of the registry to the - specified Mnesia table . + specified Mnesia table "mtab". Once a registry has been backed up to Mnesia like this, more backups only affect objects that have been modified since the most recent backup, that is, @@ -756,7 +756,7 @@ ei_reg_dump(fd, reg, "mtab", dumpflags); ]]> -

This reads the entire contents of into the +

This reads the entire contents of "mtab" into the specified registry. After the restore, all the objects in the registry are marked as unmodified, so a later backup only affects objects that you have modified since the restore.

@@ -775,8 +775,8 @@ ei_reg_restore(fd, reg, "mtab"); ]]> important that some simple guidelines are followed.

Most importantly, the object must have been created with a single call - to (or similar), so that it can later be - removed by a single call to . + to malloc() (or similar), so that it can later be + removed by a single call to free(). Objects are freed by the registry when it is closed, or when you assign a new value to an object that previously contained a string or binary.

diff --git a/lib/erl_interface/doc/src/erl_call.xml b/lib/erl_interface/doc/src/erl_call.xml index 706dd271cc..f1e52b1889 100644 --- a/lib/erl_interface/doc/src/erl_call.xml +++ b/lib/erl_interface/doc/src/erl_call.xml @@ -35,9 +35,9 @@ erl_call Call/start a distributed Erlang node. -

makes it possible to start and/or +

erl_call makes it possible to start and/or communicate with a distributed Erlang node. It is built upon the - library as an example application. + Erl_Interface library as an example application. Its purpose is to use a Unix shell script to interact with a distributed Erlang node. It performs all communication with the Erlang rex server, using the standard Erlang RPC facility. It does not @@ -45,14 +45,14 @@

The main use is to either start a distributed Erlang node or to make an ordinary function call. However, it is also - possible to pipe an Erlang module to and have + possible to pipe an Erlang module to erl_call and have it compiled, or to pipe a sequence of Erlang expressions to be evaluated (similar to the Erlang shell).

-

Options, which cause to be read, can be used +

Options, which cause stdin to be read, can be used with advantage, as scripts from within (Unix) shell scripts. Another nice use - of could be from (HTTP) CGI-bin scripts.

+ of erl_call could be from (HTTP) CGI-bin scripts.

 @@ -67,65 +67,65 @@ -a [Mod [Fun [Args]]]]

(Optional.) Applies the specified function - and returns the result. must be specified. + and returns the result. Mod must be specified. However, start and [] are assumed for unspecified - and , respectively. - is to be in the same format as for + Fun and Args, respectively. + Args is to be in the same format as for erlang:apply/3 in ERTS.

Notice that this flag takes exactly one argument, so quoting - can be necessary to group , - , and in a manner + can be necessary to group Mod, + Fun, and Args in a manner dependent on the behavior of your command shell.

 -c Cookie

(Optional.) Use this option to specify a certain cookie. - If no cookie is specified, the + If no cookie is specified, the ~/.erlang.cookie file is read and its content is used as cookie. The Erlang node we want to communicate with must have the same cookie.

 -d

(Optional.) Debug mode. This causes all I/O to be output - to the file, where - + to the ~/.erl_call.out.Nodename file, where + Nodename is the node name of the Erlang node in question.

 -e

(Optional.) Reads a sequence of Erlang expressions, separated by comma (,) and ended with a full stop (.), from - until EOF (Control-D). Evaluates the + stdin until EOF (Control-D). Evaluates the expressions and returns the result from the last expression. - Returns on success.

+ Returns {ok,Result} on success.

 -h HiddenName

(Optional.) Specifies the name of the hidden node - that represents.

+ that erl_call represents.

 -m

(Optional.) Reads an Erlang module from - and compiles it.

+ stdin and compiles it.

 -n Node -

(One of is required.) - Has the same meaning as and can still be +

(One of -n, -name, -sname is required.) + Has the same meaning as -name and can still be used for backward compatibility reasons.

 -name Node -

(One of is required.) - is the name of the node to be +

(One of -n, -name, -sname is required.) + Node is the name of the node to be started or communicated with. It is assumed that - is started with - , which means that fully + Node is started with + erl -name, which means that fully qualified long node names are used. If option - is specified, an Erlang node will (if - necessary) be started with .

+ -s is specified, an Erlang node will (if + necessary) be started with erl -name.

 -q @@ -135,13 +135,13 @@ -r

(Optional.) Generates a random name of the hidden node - that represents.

+ that erl_call represents.

 -s

(Optional.) Starts a distributed Erlang node if necessary. This means that in a sequence of calls, where - '' and '' are + '-s' and '-n Node' are constant, only the first call starts the Erlang node. This makes the rest of the communication very fast. This flag is currently only available on Unix-like platforms (Linux, Mac OS X, Solaris, @@ -149,25 +149,25 @@ -sname Node -

(One of is required.) - is the name of the node to be started - or communicated with. It is assumed that - is started with , which means that - short node names are used. If option is +

(One of -n, -name, -sname is required.) + Node is the name of the node to be started + or communicated with. It is assumed that Node + is started with erl -sname, which means that + short node names are used. If option -s is specified, an Erlang node is started (if necessary) with - .

+ erl -sname.

 -v -

(Optional.) Prints a lot of +

(Optional.) Prints a lot of verbose information. This is only useful for the developer and maintainer - of .

+ of erl_call.

 -x ErlScript

(Optional.) Specifies another name of the Erlang startup script to be used. If not specified, the standard - startup script is used.

+ erl startup script is used.

 @@ -176,7 +176,7 @@
Examples -

To start an Erlang node and call :

+

To start an Erlang node and call erlang:time/0:

To terminate an Erlang node by calling - :

+ erlang:halt/0:

This function is used by a server process to accept a connection from a client process.

- is an open socket descriptor on - which has previously been called. - is a pointer to an - struct, described as follows: + listensock is an open socket descriptor on + which listen() has previously been called. + conp is a pointer to an + ErlConnect struct, described as follows: -

On success, is filled in with the address and +

On success, conp is filled in with the address and node name of the connecting client and a file descriptor is - returned. On failure, is returned and - is set to .

+ returned. On failure, ERL_ERROR is returned and + erl_errno is set to EIO.

@@ -85,9 +85,9 @@ typedef struct {

Closes an open connection to an Erlang node.

-

is a file descriptor obtained from - or - .

+

Fd is a file descriptor obtained from + erl_connect() or + erl_xconnect().

Returns 0 on success. If the call fails, a non-zero value is returned, and the reason for the error can be obtained with the appropriate platform-dependent call.

@@ -104,33 +104,33 @@ typedef struct {

Sets up a connection to an Erlang node.

-

requires the IP address of the +

erl_xconnect() requires the IP address of the remote host and the alivename of the remote node to be - specified. provides an alternative + specified. erl_connect() provides an alternative interface, and determines the information from the node name provided.

- is the 32-bit IP address of the remote + addr is the 32-bit IP address of the remote host. - is the alivename of the remote node. + alive is the alivename of the remote node. - is the name of the remote node. + node is the name of the remote node.

Returns an open file descriptor on success, otherwise a negative - value. In the latter case is set to one + value. In the latter case erl_errno is set to one of:

- - The remote host is unreachable. - + EHOSTUNREACH + The remote host node is unreachable. + ENOMEM No more memory is available. - + EIO I/O error. -

Also, values from - (2) and - (2) - system calls can be propagated into .

+

Also, errno values from + socket(2) and + connect(2) + system calls can be propagated into erl_errno.

Example:

struct in_addr *addr; -

Initializes the module. +

Initializes the erl_connect module. In particular, these functions are used to identify the name of the C-node from which they are called. One of these functions must be called before any of the other functions in the erl_connect module are used.

-

stores for later use +

erl_connect_xinit() stores for later use information about:

- Hostname of the node, - Alivename, - Node name, - IP address, - Cookie, - Creation number, + Hostname of the node, host + Alivename, alive + Node name, node + IP address, addr + Cookie, cookie + Creation number, creation -

+

erl_connect_init() provides an alternative interface that does not require as much information from the caller. Instead, - - uses to obtain default values.

-

If you use , your node will + erl_connect_init() + uses gethostbyname() to obtain default values.

+

If you use erl_connect_init(), your node will have a short name, that is, it will not be fully qualified. If you need to use fully qualified (long) names, use - instead.

+ erl_connect_xinit() instead.

-

is the name of the host on which the node +

host is the name of the host on which the node is running.

 -

is the alivename of the node.

+

alive is the alivename of the node.

 -

is the node name. It is to +

node is the node name. It is to be of the form alivename@hostname.

 -

is the 32-bit IP address of - .

+

addr is the 32-bit IP address of + host.

 -

is the authorization string required +

cookie is the authorization string required for access to the remote node. If NULL, the user HOME directory is searched for a cookie file - . The path to + .erlang.cookie. The path to the home directory is retrieved from environment variable - on Unix and from the - and - variables on Windows. For more + HOME on Unix and from the + HOMEDRIVE and + HOMEPATH variables on Windows. For more details, see the auth module in Kernel.

 -

helps identifying a particular +

creation helps identifying a particular instance of a C-node. In particular, it can help prevent us from receiving messages sent to an earlier process with the same registered name.

A C-node acting as a server is assigned a creation number - when it calls .

-

is used by - to + when it calls erl_publish().

+

number is used by + erl_connect_init() to construct the actual node name. In Example 2 below, "c17@a.DNS.name" is the resulting node name.

Example 1:

@@ -256,23 +256,23 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) with the local name server EPMD, thereby allowing other processes to send messages by using the registered name. Before calling this function, the process should - have called and + have called bind() and listen() on an open socket.

-

is the local name to register, and is to be +

port is the local name to register, and is to be the same as the port number that was previously bound to the socket.

To unregister with EPMD, simply close the returned descriptor.

On success, a descriptor connecting the calling process to EPMD is returned. On failure, -1 is returned and - is set to:

+ erl_errno is set to:

- + EIO I/O error. -

Also, values from - (2) - and (2) system calls can be - propagated into .

+

Also, errno values from + socket(2) + and connect(2) system calls can be + propagated into erl_errno.

 @@ -288,28 +288,28 @@ if (!erl_connect_init(17, "samplecookiestring...", 0))

Receives a message consisting of a sequence of bytes in the Erlang external format.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is a buffer large enough to hold the + bufp is a buffer large enough to hold the expected message. - indicates the size of - . + bufsize indicates the size of + bufp.

If a tick occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function returns and + is still alive, the function returns ERL_TICK and no message is placed in the buffer. Also, - is set to .

+ erl_errno is set to EAGAIN.

On success, the message is placed in the specified buffer and the function returns the number of bytes actually read. On failure, the function returns a negative value and sets - to one of:

+ erl_errno to one of:

- + EAGAIN Temporary error: Try again. - + EMSGSIZE Buffer is too small. - + EIO I/O error. @@ -326,18 +326,18 @@ if (!erl_connect_init(17, "samplecookiestring...", 0))

Receives the message into the specified buffer - and decodes into .

+ and decodes into (ErlMessage *) emsg.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is a buffer large enough to hold the + bufp is a buffer large enough to hold the expected message. - indicates the size of - . - > is a pointer to an - structure + bufsize indicates the size of + bufp. + >emsg is a pointer to an + ErlMessage structure into which the message will be decoded. - is defined as follows: + ErlMessage is defined as follows: -

The definition of has changed since +

The definition of ErlMessage has changed since earlier versions of Erl_Interface.

 -

identifies the type of message, one of the +

type identifies the type of message, one of the following:

- + ERL_SEND

An ordinary send operation has occurred and - to]]> contains the pid of the recipient. - The message is in msg]]>.

+ emsg->to contains the pid of the recipient. + The message is in emsg->msg.

 - + ERL_REG_SEND

A registered send operation has occurred and - from]]> contains the pid of the sender. - The message is in msg]]>.

+ emsg->from contains the pid of the sender. + The message is in emsg->msg.

 - or + ERL_LINK or ERL_UNLINK -

to]]> and from]]> +

emsg->to and emsg->from contain the pids of the sender and recipient of the link or - unlink. msg]]> is not used.

+ unlink. emsg->msg is not used.

 - + ERL_EXIT -

A link is broken. to]]> and - from]]> contain the pids of the linked - processes, and msg]]> contains the reason +

A link is broken. emsg->to and + emsg->from contain the pids of the linked + processes, and emsg->msg contains the reason for the exit.

It is the caller's responsibility to release the - memory pointed to by msg]]>, - to]]>, and - from]]>.

+ memory pointed to by emsg->msg, + emsg->to, and + emsg->from.

If a tick occurs, that is, the Erlang node on the other end of the connection has polled this node to see if it - is still alive, the function returns + is still alive, the function returns ERL_TICK indicating that the tick has been received and responded to, but no message is placed in the buffer. In this case you - are to call again.

-

On success, the function returns and the - struct is initialized as described above, or - , in which case no message is returned. On - failure, the function returns and sets - to one of:

+ are to call erl_receive_msg() again.

+

On success, the function returns ERL_MSG and the + Emsg struct is initialized as described above, or + ERL_TICK, in which case no message is returned. On + failure, the function returns ERL_ERROR and sets + erl_errno to one of:

- + EMSGSIZE Buffer is too small. - + ENOMEM No more memory is available. - + EIO I/O error. @@ -421,18 +421,18 @@ typedef struct {

Sends an Erlang term to a registered process.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is a string containing the registered name + to is a string containing the registered name of the intended recipient of the message. - is the Erlang term to be sent. + msg is the Erlang term to be sent.

Returns 1 on success, otherwise 0. In - the latter case is set to one of:

+ the latter case erl_errno is set to one of:

- + ENOMEM No more memory is available. - + EIO I/O error. @@ -451,60 +451,60 @@ typedef struct {

Supports calling Erlang functions on remote nodes. - sends an RPC request to a remote node - and receives the results of such a - call. combines the functionality of + erl_rpc_to() sends an RPC request to a remote node + and erl_rpc_from() receives the results of such a + call. erl_rpc() combines the functionality of these two functions by sending an RPC request and waiting for the results. See also rpc:call/4 in Kernel.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is the maximum time (in milliseconds) + timeout is the maximum time (in milliseconds) to wait for - results. To wait forever, specify . + results. To wait forever, specify ERL_NO_TIMEOUT. When erl_rpc() calls erl_rpc_from(), the call will never timeout. - is the name of the module containing the + mod is the name of the module containing the function to be run on the remote node. - is the name of the function to run. + fun is the name of the function to run. - is an Erlang list, containing the + args is an Erlang list, containing the arguments to be passed to the function. - is a message containing the result of + emsg is a message containing the result of the function call.

The actual message returned by the RPC server - is a 2-tuple . If you use - in your code, this is the message - you will need to parse. If you use , the + is a 2-tuple {rex,Reply}. If you use + erl_rpc_from() in your code, this is the message + you will need to parse. If you use erl_rpc(), the tuple itself is parsed for you, and the message returned to your - program is the Erlang term containing only. + program is the Erlang term containing Reply only. Replies to RPC requests are always ERL_SEND messages.

It is the caller's responsibility to free the returned - structure and the memory pointed to by - msg]]> and to]]>.

+ ETERM structure and the memory pointed to by + emsg->msg and emsg->to.

 -

returns the remote function's return - value on success, otherwise .

-

returns 0 on +

erl_rpc() returns the remote function's return + value on success, otherwise NULL.

+

erl_rpc_to() returns 0 on success, otherwise a negative number.

-

returns - on success (with now +

erl_rcp_from() returns ERL_MSG + on success (with Emsg now containing the reply tuple), otherwise one of - , , or - .

+ ERL_TICK, ERL_TIMEOUT, or + ERL_ERROR.

When failing, - all three functions set to one of:

+ all three functions set erl_errno to one of:

- + ENOMEM No more memory is available. - + EIO I/O error. - + ETIMEDOUT Timeout has expired. - + EAGAIN Temporary error: Try again. @@ -520,21 +520,21 @@ typedef struct {

Sends an Erlang term to a process.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is an Erlang term containing the pid of + to is an Erlang term containing the pid of the intended recipient of the message. - > is the Erlang term to be sent. + >msg is the Erlang term to be sent.

Returns 1 on success, otherwise 0. In - the latter case is set to one of:

+ the latter case erl_errno is set to one of:

- - Invalid argument: is not a valid Erlang + EINVAL + Invalid argument: to is not a valid Erlang pid. - + ENOMEM No more memory is available. - + EIO I/O error. @@ -550,8 +550,8 @@ typedef struct {

Retrieves information about the C-node. These values are initially set with - or - .

+ erl_connect_init() or + erl_connect_xinit().

 @@ -568,17 +568,17 @@ typedef struct { -relaxed_command_check, which it normally is not.

To unregister a node you have published, you should instead close the descriptor that was returned by - .

+ ei_publish().

This function is deprecated and will be removed in a future release.

 -

is the name of the node to unregister, that +

alive is the name of the node to unregister, that is, the first component of the node name, without - .

+ @hostname.

If the node was successfully unregistered from EPMD, 0 is returned, otherwise -1 is returned and - is set to .

+ erl_errno is set to EIO.

 @@ -592,24 +592,24 @@ typedef struct { ErlMessage *emsg; -

Similar to . The difference is - that expects the buffer to - have been allocated by , and reallocates it +

Similar to erl_receive_msg. The difference is + that erl_xreceive_msg expects the buffer to + have been allocated by malloc, and reallocates it if the received message does not fit into the original buffer. Therefore both buffer and buffer length are given as pointers; their values can change by the call.

-

On success, the function returns and the - struct is initialized as described above, or - , in which case no message is returned. On - failure, the function returns and sets - to one of:

+

On success, the function returns ERL_MSG and the + Emsg struct is initialized as described above, or + ERL_TICK, in which case no message is returned. On + failure, the function returns ERL_ERROR and sets + erl_errno to one of:

- + EMSGSIZE Buffer is too small. - + ENOMEM No more memory is available. - + EIO I/O error. @@ -643,11 +643,11 @@ typedef struct {

If a connection attempt fails, the following can be checked:

- + erl_errno That the correct cookie was used That EPMD is running That the remote Erlang node on the other side is running the same - version of Erlang as the library + version of Erlang as the erl_interface library
diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml index a85969d7ff..8139c9b343 100644 --- a/lib/erl_interface/doc/src/erl_error.xml +++ b/lib/erl_interface/doc/src/erl_error.xml @@ -40,9 +40,9 @@ by W. Richard Stevens.

These functions are all called in the same manner as - , that is, with a string containing format + printf(), that is, with a string containing format specifiers followed by a list of corresponding arguments. All output from - these functions is to .

+ these functions is to stderr.

@@ -54,7 +54,7 @@

The message provided by the caller is printed. This - function is simply a wrapper for .

+ function is simply a wrapper for fprintf().

 @@ -105,37 +105,37 @@ Error Reporting

Most functions in Erl_Interface report failures to the caller by returning some otherwise meaningless value (typically - + NULL or a negative number). As this only tells you that things did not - go well, examine the error code in if you + go well, examine the error code in erl_errno if you want to find out more about the failure.

volatile interl_errno - Variable contains the + Variable erl_errno contains the Erl_Interface error number. You can change the value if you wish. -

is initially (at program startup) zero +

erl_errno is initially (at program startup) zero and is then set by many Erl_Interface functions on failure to a non-zero error code to indicate what kind of error it encountered. A successful function call can change - (by calling some other function that + erl_errno (by calling some other function that fails), but no function does never set it to zero. This means - that you cannot use to see if a + that you cannot use erl_errno to see if a function call failed. Instead, each function reports failure in its own way (usually by returning a negative number or - ), in which case you can examine - for details.

-

uses the error codes defined in your - system's ]]>.

+ NULL), in which case you can examine + erl_errno for details.

+

erl_errno uses the error codes defined in your + system's <errno.h>.

-

is a "modifiable lvalue" (just - like ISO C defines to be) rather than a +

erl_errno is a "modifiable lvalue" (just + like ISO C defines errno to be) rather than a variable. This means it can be implemented as a macro - (expanding to, for example, ). + (expanding to, for example, *_erl_errno()). For reasons of thread safety (or task safety), this is exactly what we do on most platforms.

 diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml index e619232e4c..9a05196a70 100644 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ b/lib/erl_interface/doc/src/erl_eterm.xml @@ -39,7 +39,7 @@ Erlang terms.

An Erlang term is represented by a C structure of type - . Applications should not reference any fields + ETERM. Applications should not reference any fields in this structure directly, as it can be changed in future releases to provide faster and more compact term storage. Instead, applications should use the macros and functions provided.

@@ -49,31 +49,31 @@ otherwise 0.

- - True if is an integer. - - True if is an integer. - - True if is a floating point number. - - True if is an atom. - - True if is a pid (process identifier). - - True if is a port. - - True if is a reference. - - True if is a tuple. - - True if is a binary. - - True if is a list with zero or more + ERL_IS_INTEGER(t) + True if t is an integer. + ERL_IS_UNSIGNED_INTEGER(t) + True if t is an integer. + ERL_IS_FLOAT(t) + True if t is a floating point number. + ERL_IS_ATOM(t) + True if t is an atom. + ERL_IS_PID(t) + True if t is a pid (process identifier). + ERL_IS_PORT(t) + True if t is a port. + ERL_IS_REF(t) + True if t is a reference. + ERL_IS_TUPLE(t) + True if t is a tuple. + ERL_IS_BINARY(t) + True if t is a binary. + ERL_IS_LIST(t) + True if t is a list with zero or more elements. - - True if is an empty list. - - True if is a list with at least one + ERL_IS_EMPTY_LIST(t) + True if t is an empty list. + ERL_IS_CONS(t) + True if t is a list with at least one element. @@ -83,60 +83,60 @@ passing a tuple to ERL_ATOM_PTR() likely results in garbage.

- + char *ERL_ATOM_PTR(t) - - A string representing atom . - + char *ERL_ATOM_PTR_UTF8(t) + A string representing atom t. + int ERL_ATOM_SIZE(t) - - The length (in bytes) of atom . - - A pointer to the contents of . - - The length (in bytes) of binary object . - - The integer of . - - The unsigned integer value of . - - The floating point value of . - + int ERL_ATOM_SIZE_UTF8(t) + The length (in bytes) of atom t. + void *ERL_BIN_PTR(t) + A pointer to the contents of t. + int ERL_BIN_SIZE(t) + The length (in bytes) of binary object t. + int ERL_INT_VALUE(t) + The integer of t. + unsigned int ERL_INT_UVALUE(t) + The unsigned integer value of t. + double ERL_FLOAT_VALUE(t) + The floating point value of t. + ETERM *ERL_PID_NODE(t) - - The node in pid . - - The sequence number in pid . - - The serial number in pid . - - The creation number in pid . - - The sequence number in port . - - The creation number in port . - + ETERM *ERL_PID_NODE_UTF8(t) + The node in pid t. + int ERL_PID_NUMBER(t) + The sequence number in pid t. + int ERL_PID_SERIAL(t) + The serial number in pid t. + int ERL_PID_CREATION(t) + The creation number in pid t. + int ERL_PORT_NUMBER(t) + The sequence number in port t. + int ERL_PORT_CREATION(t) + The creation number in port t. + ETERM *ERL_PORT_NODE(t) - - The node in port . - - The first part of the reference number in ref . + ETERM *ERL_PORT_NODE_UTF8(t) + The node in port t. + int ERL_REF_NUMBER(t) + The first part of the reference number in ref t. Use only for compatibility. - + int ERL_REF_NUMBERS(t) Pointer to the array of reference numbers in ref - . - + t. + int ERL_REF_LEN(t) The number of used reference numbers in ref - . - - The creation number in ref . - - The number of elements in tuple . - - The head element of list . - + t. + int ERL_REF_CREATION(t) + The creation number in ref t. + int ERL_TUPLE_SIZE(t) + The number of elements in tuple t. + ETERM *ERL_CONS_HEAD(t) + The head element of list t. + ETERM *ERL_CONS_TAIL(t) A list representing the tail elements of list - . + t. @@ -149,22 +149,22 @@ ETERM *tail; -

Concatenates two Erlang terms, prepending - onto and thereby creating a - cell. - To make a proper list, is always to be a list +

Concatenates two Erlang terms, prepending head + onto tail and thereby creating a + cons cell. + To make a proper list, tail is always to be a list or an empty list. Notice that NULL is not a valid list.

- is the new term to be added. - is the existing list to which - is concatenated. + head is the new term to be added. + tail is the existing list to which + head is concatenated.

The function returns a new list.

-

and - +

ERL_CONS_HEAD(list) and + ERL_CONS_TAIL(list) can be used to retrieve the head and tail components - from the list. and - do + from the list. erl_hd(list) and + erl_tl(list) do the same thing, but check that the argument really is a list.

Example:

Creates and returns a copy of the Erlang term - .

+ term.

 @@ -202,15 +202,15 @@ erl_free_compound(list);

Extracts a specified element from an Erlang tuple.

- specifies which element to retrieve - from . The elements are numbered starting + position specifies which element to retrieve + from tuple. The elements are numbered starting from 1. - is an Erlang term containing at least - elements. + tuple is an Erlang term containing at least + position elements.

Returns a new Erlang term corresponding to the requested element, or - NULL if was greater - than the arity of .

+ NULL if position was greater + than the arity of tuple.

 @@ -222,10 +222,10 @@ erl_free_compound(list);

Extracts the first element from a list.

-

is an Erlang term containing a list.

+

list is an Erlang term containing a list.

Returns an Erlang term corresponding to the head head element in the list, or a NULL pointer if - was not a list.

+ list was not a list.

 @@ -238,9 +238,9 @@ erl_free_compound(list);

This function must be called before any of the others in the - library to initialize the + Erl_Interface library to initialize the library functions. The arguments must be specified as - .

+ erl_init(NULL,0).

 @@ -252,9 +252,9 @@ erl_free_compound(list);

Returns the length of an I/O list.

-

is an Erlang term containing an I/O list.

-

Returns the length of , or - -1 if is not an I/O list.

+

list is an Erlang term containing an I/O list.

+

Returns the length of list, or + -1 if list is not an I/O list.

For the definition of an I/O list, see erl_iolist_to_binary.

@@ -269,9 +269,9 @@ erl_free_compound(list);

Converts an I/O list to a binary term.

-

is an Erlang term containing a list.

+

list is an Erlang term containing a list.

Returns an Erlang binary term, or NULL if - was not an I/O list.

+ list was not an I/O list.

Informally, an I/O list is a deep list of characters and binaries that can be sent to an Erlang port. In BNF, an I/O list is formally defined as follows:

@@ -296,15 +296,15 @@ iohead ::= Binary

Converts an I/O list to a NULL-terminated C string.

-

is an Erlang term containing an I/O list. +

list is an Erlang term containing an I/O list. The I/O list must not contain the integer 0, as C strings may not contain this value except as a terminating marker.

Returns a pointer to a dynamically allocated - buffer containing a string. If is not an I/O - list, or if contains the integer 0, + buffer containing a string. If list is not an I/O + list, or if list contains the integer 0, NULL is returned. It is the caller's responsibility to free the allocated buffer - with .

+ with erl_free().

For the definition of an I/O list, see erl_iolist_to_binary.

@@ -319,10 +319,10 @@ iohead ::= Binary

Determines the length of a proper list.

-

is an Erlang term containing a proper list. +

list is an Erlang term containing a proper list. In a proper list, all tails except the last point to another list cell, and the last tail points to an empty list.

-

Returns -1 if is not a proper +

Returns -1 if list is not a proper list.

 @@ -335,16 +335,16 @@ iohead ::= Binary

Creates an atom.

-

is the sequence of characters that will be +

string is the sequence of characters that will be used to create the atom.

Returns an Erlang term containing an atom. Notice that it is - the caller's responsibility to ensure that + the caller's responsibility to ensure that string contains a valid name for an atom.

-

and - +

ERL_ATOM_PTR(atom) and + ERL_ATOM_PTR_UTF8(atom) can be used to retrieve the atom name (as a NULL-terminated string). - - and return the length + ERL_ATOM_SIZE(atom) + and ERL_ATOM_SIZE_UTF8(atom) return the length of the atom name.

The UTF-8 variants were introduced in Erlang/OTP R16 and the @@ -365,14 +365,14 @@ iohead ::= Binary

Produces an Erlang binary object from a buffer containing a sequence of bytes.

- is a pointer to a buffer containing + bptr is a pointer to a buffer containing data to be converted. - indicates the length of - . + size indicates the length of + bptr.

Returns an Erlang binary object.

-

retrieves a pointer to - the binary data. retrieves the +

ERL_BIN_PTR(bin) retrieves a pointer to + the binary data. ERL_BIN_SIZE(bin) retrieves the size.

 @@ -397,13 +397,13 @@ iohead ::= Binary

Creates a list from a sequence of bytes.

- is a buffer containing a sequence of + string is a buffer containing a sequence of bytes. The buffer does not need to be NULL-terminated. - is the length of - . + len is the length of + string.

Returns an Erlang list object corresponding to - the character sequence in .

+ the character sequence in string.

 @@ -415,12 +415,12 @@ iohead ::= Binary

Creates an Erlang float.

-

is a value to be converted to an Erlang +

f is a value to be converted to an Erlang float.

Returns an Erlang float object with the value - specified in or if - is not finite.

-

can be used to retrieve the + specified in f or NULL if + f is not finite.

+

ERL_FLOAT_VALUE(t) can be used to retrieve the value from an Erlang float.

 @@ -433,11 +433,11 @@ iohead ::= Binary

Creates an Erlang integer.

-

is a value to be converted to an Erlang +

n is a value to be converted to an Erlang integer.

Returns an Erlang integer object with the - value specified in .

-

can be used to retrieve the + value specified in n.

+

ERL_INT_VALUE(t) can be used to retrieve the value from an Erlang integer.

 @@ -454,13 +454,13 @@ iohead ::= Binary that each element in the list corresponds to one element in the array.

- is an array of Erlang terms. - is the number of elements in - . + array is an array of Erlang terms. + arrsize is the number of elements in + array.

The function creates an Erlang list object, whose length - and whose elements are taken from the - terms in .

+ arrsize and whose elements are taken from the + terms in array.

 @@ -475,21 +475,21 @@ iohead ::= Binary

Creates an Erlang reference, with 82 bits.

- is the name of the C-node. - , , and - can be seen as one big number - , which is to be chosen + node is the name of the C-node. + n1, n2, and + n3 can be seen as one big number + n1*2^64+n2*2^32+n3, which is to be chosen uniquely for each reference created for a given C-node. - is an arbitrary number. + creation is an arbitrary number. -

Notice that and +

Notice that n3 and creation are limited in precision, so only the low 18 and 2 bits of these numbers are used.

Returns an Erlang reference object.

-

, - , - , and - can be used to retrieve the +

ERL_REF_NODE(ref), + ERL_REF_NUMBERS(ref), + ERL_REF_LEN(ref), and + ERL_REF_CREATION(ref) can be used to retrieve the values used to create the reference.

 @@ -508,18 +508,18 @@ iohead ::= Binary resulting pid can be used by Erlang processes wishing to communicate with the C-node.

- is the name of the C-node. - , , and - are + node is the name of the C-node. + number, serial, and + creation are arbitrary numbers. Notice that these are limited in precision, so only the low 15, 3, and 2 bits of these numbers are used.

Returns an Erlang pid object.

-

, - , - , and - +

ERL_PID_NODE(pid), + ERL_PID_NUMBER(pid), + ERL_PID_SERIAL(pid), and + ERL_PID_CREATION(pid) can be used to retrieve the four values used to create the pid.

 @@ -535,16 +535,16 @@ iohead ::= Binary

Creates an Erlang port identifier.

- is the name of the C-node. - and are + node is the name of the C-node. + number and creation are arbitrary numbers. Notice that these are limited in precision, so only the low 18 and 2 bits of these numbers are used.

Returns an Erlang port object.

-

, - , - and can be used to retrieve the +

ERL_PORT_NODE(port), + ERL_PORT_NUMBER(port), + and ERL_PORT_CREATION can be used to retrieve the three values used to create the port.

 @@ -559,20 +559,20 @@ iohead ::= Binary

Creates an old Erlang reference, with - only 18 bits - use instead.

+ only 18 bits - use erl_mk_long_ref instead.

- is the name of the C-node. - is to be chosen uniquely for each + node is the name of the C-node. + number is to be chosen uniquely for each reference created for a given C-node. - is an arbitrary number. + creation is an arbitrary number. -

Notice that and +

Notice that number and creation are limited in precision, so only the low 18 and 2 bits of these numbers are used.

Returns an Erlang reference object.

-

, - , and - can be used to retrieve the +

ERL_REF_NODE(ref), + ERL_REF_NUMBER(ref), and + ERL_REF_CREATION(ref) can be used to retrieve the three values used to create the reference.

 @@ -585,7 +585,7 @@ iohead ::= Binary

Creates a list from a NULL-terminated string.

-

is a NULL-terminated sequence of +

string is a NULL-terminated sequence of characters (that is, a C string) from which the list will be created.

Returns an Erlang list.

@@ -602,20 +602,20 @@ iohead ::= Binary

Creates an Erlang tuple from an array of Erlang terms.

- is an array of Erlang terms. - is the number of elements in - . + array is an array of Erlang terms. + arrsize is the number of elements in + array.

The function creates an Erlang tuple, whose arity is - and whose elements are taken from the terms - in .

+ size and whose elements are taken from the terms + in array.

To retrieve the size of a tuple, either use function - (which checks the type of the + erl_size (which checks the type of the checked term and works for a binary as well as for a tuple) or - returns the arity of a tuple. - does the same thing, but it checks + ERL_TUPLE_SIZE(tuple) returns the arity of a tuple. + erl_size() does the same thing, but it checks that the argument is a tuple. - returns the element + erl_element(index,tuple) returns the element corresponding to a given position in the tuple.

 @@ -628,11 +628,11 @@ iohead ::= Binary

Creates an Erlang unsigned integer.

-

is a value to be converted to an Erlang +

n is a value to be converted to an Erlang unsigned integer.

Returns an Erlang unsigned integer object with - the value specified in .

-

can be used to retrieve the + the value specified in n.

+

ERL_INT_UVALUE(t) can be used to retrieve the value from an Erlang unsigned integer.

 @@ -646,9 +646,9 @@ iohead ::= Binary

Creates an unbound Erlang variable. The variable can later be bound through pattern matching or assignment.

-

specifies a name for the variable.

+

name specifies a name for the variable.

Returns an Erlang variable object with the - name .

+ name name.

 @@ -662,9 +662,9 @@ iohead ::= Binary

Prints the specified Erlang term to the specified output stream.

- indicates where the function is to + stream indicates where the function is to send its output. - is the Erlang term to print. + term is the Erlang term to print.

Returns the number of characters written on success, otherwise a negative value.

@@ -678,16 +678,16 @@ iohead ::= Binary unsigned release_number; -

By default, the library is only +

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

@@ -714,10 +714,10 @@ iohead ::= Binary

Returns either the arity of an Erlang tuple or the number of bytes in an Erlang binary object.

-

is an Erlang tuple or an Erlang binary +

term is an Erlang tuple or an Erlang binary object.

-

Returns the size of as described - above, or -1 if is not one of the two +

Returns the size of term as described + above, or -1 if term is not one of the two supported types.

 @@ -730,10 +730,10 @@ iohead ::= Binary

Extracts the tail from a list.

-

is an Erlang term containing a list.

+

list is an Erlang term containing a list.

Returns an Erlang list corresponding to the original list minus the first element, or NULL pointer if - was not a list.

+ list was not a list.

 @@ -747,19 +747,19 @@ iohead ::= Binary

Returns the contents of the specified variable in an Erlang term.

- is an Erlang term. In order for this + term is an Erlang term. In order for this function to succeed, - must either be an Erlang variable with + term must either be an Erlang variable with the specified name, or it must be an Erlang list or tuple containing a variable with the specified name. Other Erlang types cannot contain variables. - is the name of an Erlang variable. + name is the name of an Erlang variable.

Returns the Erlang object corresponding to the value of - in . If no variable - with the name is found in - , or if is + name in term. If no variable + with the name name is found in + term, or if term is not a valid Erlang term, NULL is returned.

 diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml index f6f27326ff..5b8b7b5e78 100644 --- a/lib/erl_interface/doc/src/erl_format.xml +++ b/lib/erl_interface/doc/src/erl_format.xml @@ -49,8 +49,8 @@

A general function for creating Erlang terms using a format specifier and a corresponding set of arguments, much - in the way works.

-

is a format specification string. + in the way printf() works.

+

FormatStr is a format specification string. The valid format specifiers are as follows:

~i - Integer @@ -59,10 +59,10 @@ ~s - String ~w - Arbitrary Erlang term -

For each format specifier included in , +

For each format specifier included in FormatStr, there must be a corresponding argument following - . An Erlang term is built according to - with values and Erlang terms substituted + FormatStr. An Erlang term is built according to + FormatStr with values and Erlang terms substituted from the corresponding arguments, and according to the individual format specifiers. For example:

-

This creates an structure corresponding +

This creates an (ETERM *) structure corresponding to the Erlang term -

+ [{name,madonna},{age,21},{data,[{adr,"E-street",42}]}]

The function returns an Erlang term, or NULL if - does not describe a valid Erlang + FormatStr does not describe a valid Erlang term.

 @@ -92,18 +92,18 @@ erl_format("[{name,~a},{age,~i},{data,~w}]", section Pattern Matching in the Erlang Reference Manual.

- is an Erlang term, possibly + Pattern is an Erlang term, possibly containing unbound variables. - is an Erlang term that we wish to match - against . + Term is an Erlang term that we wish to match + against Pattern. -

and are compared - and any unbound variables in are bound to - corresponding values in .

-

If and can be +

Term and Pattern are compared + and any unbound variables in Pattern are bound to + corresponding values in Term.

+

If Term and Pattern can be matched, the function returns a non-zero value and binds any unbound - variables in . If - and do + variables in Pattern. If Term + and Pattern do not match, 0 is returned. For example:

-

can be used to retrieve the +

erl_var_content() can be used to retrieve the content of any variables bound as a result of a call to - .

+ erl_match().

 diff --git a/lib/erl_interface/doc/src/erl_global.xml b/lib/erl_interface/doc/src/erl_global.xml index 0808ea0eee..2fa0045adf 100644 --- a/lib/erl_interface/doc/src/erl_global.xml +++ b/lib/erl_interface/doc/src/erl_global.xml @@ -57,23 +57,23 @@

Retrieves a list of all known global names.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is the address of an integer, or - NULL. If is not NULL, it is + count is the address of an integer, or + NULL. If count is not NULL, it is set by the function to the number of names found.

On success, the function returns an array of strings, each containing a single registered name, and sets - to + count to the number of names found. The array is terminated by a single NULL pointer. On failure, the function returns - NULL and is not modified.

+ NULL and count is not modified.

It is the caller's responsibility to free the array afterwards. It has been allocated by the function with a - single call to , so a single - is all that is necessary.

+ single call to malloc(), so a single + free() is all that is necessary.

 @@ -89,13 +89,13 @@

Registers a name in global.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is the name to register in + name is the name to register in global. - is the pid that is to be associated with - . This value is returned by global - when processes request the location of . + pid is the pid that is to be associated with + name. This value is returned by global + when processes request the location of name.

Returns 0 on success, otherwise -1.

@@ -112,9 +112,9 @@

Unregisters a name from global.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is the name to unregister from + name is the name to unregister from global.

Returns 0 on success, otherwise -1.

@@ -132,19 +132,19 @@

Looks up a name in global.

- is an open descriptor to an Erlang + fd is an open descriptor to an Erlang connection. - is the name that is to be looked up in + name is the name that is to be looked up in global. -

If is not NULL, it is a pointer to a +

If node is not NULL, it is a pointer to a buffer where the function can fill in the name of the node where - is found. can be - passed directly to if necessary.

+ name is found. node can be + passed directly to erl_connect() if necessary.

On success, the function returns an Erlang pid containing the address of the specified name, and the node is initialized to - the node name where is found. On failure, - NULL is returned and is not + the node name where name is found. On failure, + NULL is returned and node is not modified.

 diff --git a/lib/erl_interface/doc/src/erl_interface.xml b/lib/erl_interface/doc/src/erl_interface.xml index ab5b46cc01..4e66655b39 100644 --- a/lib/erl_interface/doc/src/erl_interface.xml +++ b/lib/erl_interface/doc/src/erl_interface.xml @@ -72,51 +72,51 @@ Eshell V4.7.4 (abort with ^G) 1> code:root_dir(). /usr/local/otp ]]>

To compile your code, make sure that your C compiler knows where - to find by specifying an appropriate - argument on the command line, or by adding it to the - definition in your . The correct value for this path is - Vsn, where is the path - reported by in the above example, and Vsn is + to find erl_interface.h by specifying an appropriate -I + argument on the command line, or by adding it to the CFLAGS + definition in your Makefile. The correct value for this path is + $OTPROOT/lib/erl_interfaceVsn/include, where $OTPROOT is the path + reported by code:root_dir/0 in the above example, and Vsn is the version of the Erl_interface application, for example -

+ erl_interface-3.2.3

When linking, you will need to specify the path to - and with - , and you will need to specify the - name of the libraries with . You can do - this on the command line or by adding the flags to the - definition in your .

+ liberl_interface.a and libei.a with + -L$OTPROOT/lib/erl_interface-3.2.3/lib, and you will need to specify the + name of the libraries with -lerl_interface -lei. You can do + this on the command line or by adding the flags to the LDFLAGS + definition in your Makefile.

Also, on some systems it may be necessary to link with some - additional libraries (e.g. and on - Solaris, or on Windows) in order to use the + additional libraries (e.g. libnsl.a and libsocket.a on + Solaris, or wsock32.lib on Windows) in order to use the communication facilities of Erl_Interface.

If you are using Erl_Interface functions in a threaded application based on POSIX threads or Solaris threads, then Erl_Interface needs access to some of the synchronization facilities in your threads package, and you will need to specify additional compiler flags in order to indicate which of the packages - you are using. Define and either or - . The default is to use POSIX threads if - is specified.

+ you are using. Define _REENTRANT and either STHREADS or + PTHREADS. The default is to use POSIX threads if + _REENTRANT is specified.

Note that both single threaded and default versions of the Erl_interface and Ei libraries are provided. (The single threaded versions are named - and ). Whether the default + liberl_interface_st and libei_st). Whether the default versions of the libraries have support for threads or not is determined by if the platform in question has support for POSIX or Solaris threads. To check this, - have a look in the file in the erl_interface src directory.

+ have a look in the eidefs.mk file in the erl_interface src directory.

Initializing the erl_interface Library

Before calling any of the other Erl_Interface functions, you - must call exactly once to initialize the library. - takes two arguments, however the arguments are no + must call erl_init() exactly once to initialize the library. + erl_init() takes two arguments, however the arguments are no longer used by Erl_Interface, and should therefore be specified - as .

+ as erl_init(NULL,0).

@@ -129,7 +129,7 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ number of C functions which create and manipulate Erlang data structures. The library also contains an encode and a decode function. The example below shows how to create and encode an Erlang tuple - :

+ {tobbe,3928}:

-

Alternatively, you can use and - , which handle the encoding and decoding of +

Alternatively, you can use erl_send() and + erl_receive_msg, which handle the encoding and decoding of messages transparently.

Refer to the Reference Manual for a complete description of the following modules:

- the module for creating Erlang terms - the module for encoding and decoding routines. + the erl_eterm module for creating Erlang terms + the erl_marshal module for encoding and decoding routines.
Building Terms and Patterns

The previous example can be simplified by using - to create an Erlang term.

+ erl_format() to create an Erlang term.

-

Refer to the Reference Manual, the module, for a +

Refer to the Reference Manual, the erl_format module, for a full description of the different format directives. The following example is more complex:

As in previous examples, it is your responsibility to free the memory allocated for Erlang terms. In this example, - ensures that the complete term pointed to - by is released. This is necessary, because the pointer from - the second call to is lost.

+ erl_free_compound() ensures that the complete term pointed to + by ep is released. This is necessary, because the pointer from + the second call to erl_format() is lost.

The following example shows a slightly different solution:

In this case, you free the two terms independently. The order in - which you free the terms and is not important, + which you free the terms ep and ep2 is not important, because the Erl_Interface library uses reference counting to determine when it is safe to actually remove objects.

If you are not sure whether you have freed the terms properly, you @@ -204,14 +204,14 @@ printf("length of freelist: %ld\ /* really free the freelist */ erl_eterm_release(); ]]> -

Refer to the Reference Manual, the module for more +

Refer to the Reference Manual, the erl_malloc module for more information.

Pattern Matching

An Erlang pattern is a term that may contain unbound variables or - symbols. Such a pattern can be matched against a + "do not care" symbols. Such a pattern can be matched against a term and, if the match is successful, any unbound variables in the pattern will be bound as a side effect. The content of a bound variable can then be retrieved.

@@ -219,13 +219,13 @@ erl_eterm_release(); ETERM *pattern; pattern = erl_format("{madonna,Age,_}"); ]]> -

is used to perform pattern matching. It takes a +

erl_match() is used to perform pattern matching. It takes a pattern and a term and tries to match them. As a side effect any unbound variables in the pattern will be bound. In the following example, we create a pattern with a variable Age which appears at two positions in the tuple. The pattern match is performed as follows:

- will bind the contents of + erl_match() will bind the contents of Age to 21 the first time it reaches the variable the second occurrence of Age will cause a test for equality between the terms since Age is already bound to @@ -248,14 +248,14 @@ if (erl_match(pattern, term)) { } erl_free_term(pattern); erl_free_term(term); ]]> -

Refer to the Reference Manual, the function for +

Refer to the Reference Manual, the erl_match() function for more information.

Connecting to a Distributed Erlang Node

In order to connect to a distributed Erlang node you need to first - initialize the connection routine with , + initialize the connection routine with erl_connect_init(), which stores information such as the host name, node name, and IP address for later use:

-

Refer to the Reference Manual, the module for more information.

+

Refer to the Reference Manual, the erl_connect module for more information.

After initialization, you set up the connection to the Erlang node. - Use to specify the Erlang node you want to + Use erl_connect() to specify the Erlang node you want to connect to. The following example sets up the connection and should result in a valid socket file descriptor:

-

prints the specified string and terminates - the program. Refer to the Reference Manual, the +

erl_err_quit() prints the specified string and terminates + the program. Refer to the Reference Manual, the erl_error() function for more information.

Using EPMD -

is the Erlang Port Mapper Daemon. Distributed Erlang nodes - register with on the localhost to indicate to other nodes that - they exist and can accept connections. maintains a register of +

Epmd is the Erlang Port Mapper Daemon. Distributed Erlang nodes + register with epmd on the localhost to indicate to other nodes that + they exist and can accept connections. Epmd maintains a register of node and port number information, and when a node wishes to connect to - another node, it first contacts in order to find out the correct + another node, it first contacts epmd in order to find out the correct port number to connect to.

-

When you use to connect to an Erlang node, a - connection is first made to and, if the node is known, a +

When you use erl_connect() to connect to an Erlang node, a + connection is first made to epmd and, if the node is known, a connection is then made to the Erlang node.

-

C nodes can also register themselves with if they want other +

C nodes can also register themselves with epmd if they want other nodes in the system to be able to find and connect to them.

-

Before registering with , you need to first create a listen socket +

Before registering with epmd, you need to first create a listen socket and bind it to a port. Then:

-

is a file descriptor now connected to . +

pub is a file descriptor now connected to epmd. Epmd monitors the other end of the connection, and if it detects that the connection has been closed, the node will be unregistered. So, if you explicitly close the descriptor or if your node fails, it will be - unregistered from .

+ unregistered from epmd.

Be aware that on some systems (such as VxWorks), a failed node will not be detected by this mechanism since the operating system does not automatically close descriptors that were left open when the node - failed. If a node has failed in this way, will prevent you from + failed. If a node has failed in this way, epmd will prevent you from registering a new node with the old name, since it thinks that the old name is still in use. In this case, you must unregister the name explicitly:

-

This will cause to close the connection from the far end. Note +

This will cause epmd to close the connection from the far end. Note that if the name was in fact still in use by a node, the results of this operation are unpredictable. Also, doing this does not cause the local end of the connection to close, so resources may be consumed.

@@ -321,8 +321,8 @@ erl_unpublish(node); ]]> Sending and Receiving Erlang Messages

Use one of the following two functions to send messages:

- - + erl_send() + erl_reg_send()

As in Erlang, it is possible to send messages to a Pid or to a registered name. It is easier to send a @@ -330,17 +330,17 @@ erl_unpublish(node); ]]> a suitable Pid.

Use one of the following two functions to receive messages:

- - + erl_receive() + erl_receive_msg() -

receives the message into a buffer, while - decodes the message into an Erlang term.

+

erl_receive() receives the message into a buffer, while + erl_receive_msg() decodes the message into an Erlang term.

Example of Sending Messages -

In the following example, is - sent to a registered process . The message is encoded - by :

+

In the following example, {Pid, hello_world} is + sent to a registered process my_server. The message is encoded + by erl_send():

The first element of the tuple that is sent is your own - Pid. This enables to reply. Refer to the - Reference Manual, the module for more information + Pid. This enables my_server to reply. Refer to the + Reference Manual, the erl_connect module for more information about send primitives.

Example of Receiving Messages -

In this example is received. The - received Pid is then used to return

+

In this example {Pid, Something} is received. The + received Pid is then used to return {goodbye,Pid}

In order to provide robustness, a distributed Erlang node occasionally polls all its connected neighbours in an attempt to detect failed nodes or communication links. A node which receives such - a message is expected to respond immediately with an message. - This is done automatically by , however when this - has occurred returns to the caller - without storing a message into the structure.

+ a message is expected to respond immediately with an ERL_TICK message. + This is done automatically by erl_receive(), however when this + has occurred erl_receive returns ERL_TICK to the caller + without storing a message into the ErlMessage structure.

When a message has been received, it is the caller's responsibility - to free the received message as well as - or , depending on the type of message received.

+ to free the received message emsg.msg as well as emsg.to + or emsg.from, depending on the type of message received.

Refer to the Reference Manual for additional information about the following modules:

- - . + erl_connect + erl_eterm.
@@ -421,12 +421,12 @@ if (!erl_match(ep, reply)) "); erl_free_term(ep); erl_free_term(reply); ]]> -

is called to compile the specified module on the - remote node. checks that the compilation was - successful by testing for the expected .

-

Refer to the Reference Manual, the module for - more information about , and its companions - and .

+

c:c/1 is called to compile the specified module on the + remote node. erl_match() checks that the compilation was + successful by testing for the expected ok.

+

Refer to the Reference Manual, the erl_connect module for + more information about erl_rpc(), and its companions + erl_rpc_to() and erl_rpc_from().

@@ -454,14 +454,14 @@ if (names) ",names[i]); free(names); ]]> -

allocates and returns a buffer containing - all the names known to global. will be initialized to +

erl_global_names() allocates and returns a buffer containing + all the names known to global. count will be initialized to indicate how many names are in the array. The array of strings in names is terminated by a NULL pointer, so it is not necessary to use - to determine when the last name is reached.

+ count to determine when the last name is reached.

It is the caller's responsibility to free the array. - allocates the array and all of the strings - using a single call to , so is all + erl_global_names() allocates the array and all of the strings + using a single call to malloc(), so free(names) is all that is necessary.

To look up one of the names:

-

If is known to global, an Erlang pid is returned +

If "schedule" is known to global, an Erlang pid is returned that can be used to send messages to the schedule service. - Additionally, will be initialized to contain the name of + Additionally, node will be initialized to contain the name of the node where the service is registered, so that you can make a - connection to it by simply passing the variable to .

+ connection to it by simply passing the variable to erl_connect().

Before registering a name, you should already have registered your - port number with . This is not strictly necessary, but if you + port number with epmd. This is not strictly necessary, but if you neglect to do so, then other nodes wishing to communicate with your service will be unable to find or connect to your process.

Create a pid that Erlang processes can use to communicate with your @@ -485,9 +485,9 @@ ETERM *pid; pid = erl_mk_pid(thisnode,14,0,0); erl_global_register(fd,servicename,pid); ]]> -

After registering the name, you should use to wait for +

After registering the name, you should use erl_accept() to wait for incoming connections.

-

Do not forget to free later with !

+

Do not forget to free pid later with erl_free_term()!

To unregister a name:

@@ -570,12 +570,12 @@ ei_reg_close(reg); ]]> Backing Up the Registry to Mnesia

The contents of a registry can be backed up to Mnesia on a "nearby" Erlang node. You need to provide an open connection to the Erlang node - (see ). Also, Mnesia 3.0 or later must be running + (see erl_connect()). Also, Mnesia 3.0 or later must be running on the Erlang node before the backup is initiated:

The example above will backup the contents of the registry to the - specified Mnesia table . Once a registry has been backed + specified Mnesia table "mtab". Once a registry has been backed up to Mnesia in this manner, additional backups will only affect objects that have been modified since the most recent backup, i.e. objects that have been created, changed or deleted. The backup @@ -584,7 +584,7 @@ ei_reg_dump(fd, reg, "mtab", dumpflags); ]]>

In the same manner, a registry can be restored from a Mnesia table:

-

This will read the entire contents of into the specified +

This will read the entire contents of "mtab" into the specified registry. After the restore, all of the objects in the registry will be marked as unmodified, so a subsequent backup will only affect objects that you have modified since the restore.

@@ -600,8 +600,8 @@ ei_reg_restore(fd, reg, "mtab"); ]]>

When string or binary objects are stored in the registry it is important that a number of simple guidelines are followed.

Most importantly, the object must have been created with a single call - to (or similar), so that it can later be removed by a - single call to . Objects will be freed by the registry + to malloc() (or similar), so that it can later be removed by a + single call to free(). Objects will be freed by the registry when it is closed, or when you assign a new value to an object that previously contained a string or binary.

You should also be aware that if you store binary objects that are @@ -618,8 +618,8 @@ ei_reg_restore(fd, reg, "mtab"); ]]> you make, possibly causing it to be missed the next time you make a Mnesia backup of the registry contents. This can be avoided if you mark the object as dirty after any such changes with - , or pass appropriate flags to - .

+ ei_reg_markdirty(), or pass appropriate flags to + ei_reg_dump().

diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml index e08924ec51..c0eebc29e9 100644 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ b/lib/erl_interface/doc/src/erl_malloc.xml @@ -47,8 +47,8 @@ unsigned char etype; -

Allocates an structure.

-

Specify as one of the following +

Allocates an (ETERM) structure.

+

Specify etype as one of the following constants:

ERL_INTEGER @@ -80,9 +80,9 @@ ERL_U_SMALL_BIG (bignum) -

and - are for - creating Erlang , which can contain integers +

ERL_SMALL_BIG and + ERL_U_SMALL_BIG are for + creating Erlang bignums, which can contain integers of any size. The size of an integer in Erlang is machine-dependent, but any integer > 2^28 requires a bignum.

 @@ -93,8 +93,8 @@ Clear the ETERM freelist.

Clears the freelist, where blocks are placed when they are - released by and - .

+ released by erl_free_term() and + erl_free_compound().

 @@ -107,20 +107,20 @@

Reports term allocation statistics.

-

and are +

allocated and freed are initialized to contain information about the fix-allocator used to allocate ETERM components.

-

is the number of blocks currently +

allocated is the number of blocks currently allocated to ETERM objects.

 -

is the length of the freelist, where +

freed is the length of the freelist, where blocks are placed when they are - released by and - .

+ released by erl_free_term() and + erl_free_compound().

 @@ -134,7 +134,7 @@

Calls the standard - function.

+ free() function.

 @@ -148,8 +148,8 @@

Frees an array of Erlang terms.

- is an array of ETERM* objects. - is the number of terms in the array. + array is an array of ETERM* objects. + size is the number of terms in the array. @@ -164,12 +164,12 @@

Normally it is the programmer's responsibility to free each Erlang term that has been returned from any of the - functions. However, as many of the + Erl_Interface functions. However, as many of the functions that build new Erlang terms in fact share objects with other existing terms, it can be difficult for the programmer to maintain pointers to all such terms to free them individually.

-

recursively frees all of the +

erl_free_compound() recursively frees all of the subterms associated with a specified Erlang term, regardless of whether we are still holding pointers to the subterms.

For an example, see section @@ -197,7 +197,7 @@

Calls the standard - function.

+ malloc() function.

 diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml index b333bc9993..2ad658f78b 100644 --- a/lib/erl_interface/doc/src/erl_marshal.xml +++ b/lib/erl_interface/doc/src/erl_marshal.xml @@ -50,9 +50,9 @@

Compares two encoded terms.

- is a buffer containing an encoded + bufp1 is a buffer containing an encoded Erlang term term1. - is a buffer containing an encoded + bufp2 is a buffer containing an encoded Erlang term term2.

Returns 0 if the terms are equal, -1 if @@ -70,31 +70,31 @@ unsigned char **bufpp; -

and - decode +

erl_decode() and + erl_decode_buf() decode the contents of a buffer and return the corresponding - Erlang term. provides a simple + Erlang term. erl_decode_buf() provides a simple mechanism for dealing with several encoded terms stored consecutively in the buffer.

-

is a pointer to a buffer containing one +

bufp is a pointer to a buffer containing one or more encoded Erlang terms.

 -

is the address of a buffer pointer. The +

bufpp is the address of a buffer pointer. The buffer contains one or more consecutively encoded Erlang terms. Following a successful call to - , is + erl_decode_buf(), bufpp is updated so that it points to the next encoded term.

 -

returns an Erlang term - corresponding to the contents of on success, - otherwise NULL. +

erl_decode() returns an Erlang term + corresponding to the contents of bufp on success, + otherwise NULL. erl_decode_buf() returns an Erlang term corresponding to the first of the consecutive terms in - and moves forward + bufpp and moves bufpp forward to point to the next term in the buffer. On failure, each of the functions return NULL.

@@ -111,10 +111,10 @@ unsigned char **bufpp; -

and - encode +

erl_encode() and + erl_encode_buf() encode Erlang terms into external format for storage or transmission. - provides a simple mechanism for + erl_encode_buf() provides a simple mechanism for encoding several terms consecutively in the same buffer.

@@ -128,7 +128,7 @@

bufpp is a pointer to a pointer to a buffer containing one or more consecutively encoded Erlang terms. Following a successful call to - , bufpp is updated so + erl_encode_buf(), bufpp is updated so that it points to the position for the next encoded term.

 @@ -139,36 +139,36 @@ the caller's responsibility to ensure that the buffer is large enough to hold the encoded terms. You can either use a static buffer that is large enough to hold the terms you expect - to need in your program, or use + to need in your program, or use erl_term_len() to determine the exact requirements for a given term.

The following can help you estimate the buffer requirements for a term. Notice that this information is implementation-specific, and can change in future versions. - If you are unsure, use .

+ If you are unsure, use erl_term_len().

Erlang terms are encoded with a 1 byte tag that identifies the type of object, a 2- or 4-byte length field, and then the data itself. Specifically:

- + Tuples Need 5 bytes, plus the space for each element. - + Lists Need 5 bytes, plus the space for each element, and 1 more byte for the empty list at the end. - + Strings and atoms Need 3 bytes, plus 1 byte for each character (the terminating 0 is not encoded). Really long strings (more than 64k characters) are encoded as lists. Atoms cannot contain more than 256 characters. - + Integers Need 5 bytes. - + Characters (Integers < 256) need 2 bytes. - + Floating point numbers Need 32 bytes. - + Pids Need 10 bytes, plus the space for the node name, which is an atom. - + Ports and Refs Need 6 bytes, plus the space for the node name, which is an atom. @@ -198,7 +198,7 @@

Identifies and returns the type of Erlang term encoded in a buffer. It skips a trailing magic identifier.

-

Returns if the type cannot be determined or +

Returns 0 if the type cannot be determined or one of:

ERL_INTEGER @@ -238,15 +238,15 @@

This function is used for stepping over one or more encoded terms in a buffer, to directly access later term.

- is a pointer to a buffer containing one + bufp is a pointer to a buffer containing one or more encoded Erlang terms. - indicates how many terms to step over in + pos indicates how many terms to step over in the buffer.

Returns a pointer to a subterm that can be - used in a later call to to retrieve + used in a later call to erl_decode() to retrieve the term at that position. If there is no term, or - would exceed the size of the terms in the + pos would exceed the size of the terms in the buffer, NULL is returned.

 @@ -259,8 +259,8 @@

Determines the buffer space that would be - needed by if it were encoded into Erlang external - format by .

+ needed by t if it were encoded into Erlang external + format by erl_encode().

Returns the size in bytes.

 diff --git a/lib/erl_interface/doc/src/ref_man_ei.xml b/lib/erl_interface/doc/src/ref_man_ei.xml index d24828c394..92ff9ed328 100644 --- a/lib/erl_interface/doc/src/ref_man_ei.xml +++ b/lib/erl_interface/doc/src/ref_man_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 @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + EI Library Reference @@ -30,12 +30,12 @@ ref_man_ei.xml -

The library is a interface library for - communication with .

+

The ei library is a C interface library for + communication with Erlang.

-

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. See the documentation of the + release as the ei library itself. See the documentation of the ei_set_compat_rel() function on how to communicate with Erlang/OTP components from earlier releases.

@@ -45,4 +45,3 @@ - diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml index 00b8f770de..6d70fb3475 100644 --- a/lib/erl_interface/doc/src/registry.xml +++ b/lib/erl_interface/doc/src/registry.xml @@ -51,9 +51,9 @@

A registry that has previously been created with - is closed, and all the objects it + ei_reg_open() is closed, and all the objects it contains are freed.

-

is the registry to close.

+

reg is the registry to close.

Returns 0.

 @@ -73,12 +73,12 @@ well. If another object is later created with the same key, the object will be reused.

The object is removed from the registry after a call to - or . + ei_reg_dump() or ei_reg_purge().

- is the registry containing - . - is the object to remove. + reg is the registry containing + key. + key is the object to remove.

Returns 0 on success, otherwise -1.

 @@ -99,17 +99,17 @@ If any errors are encountered while backing up the data, the entire operation is aborted.

- is an open connection to Erlang. + fd is an open connection to Erlang. Mnesia 3.0 or later must be running on the Erlang node. - is the registry to back up. - is the name of the Mnesia table + reg is the registry to back up. + mntab is the name of the Mnesia table where the backed up data is to be placed. If the table does not exist, it is created automatically using configurable defaults. For information about configuring this behavior, see Mnesia. -

If is 0, the backup includes only +

If flags is 0, the backup includes only those objects that have been created, modified, or deleted since the last backup or restore (that is, an incremental backup). After the backup, any objects that were marked dirty are now clean, and any @@ -118,7 +118,7 @@ backup to be done, and EI_NOPURGE causes the deleted objects to be left in the registry afterwards. These can be bitwise OR'ed together if both behaviors are desired. If EI_NOPURGE was - specified, can be used to + specified, ei_reg_purge() can be used to explicitly remove the deleted items from the registry later.

Returns 0 on success, otherwise -1.

 @@ -132,21 +132,21 @@ const char *key; -

Gets the value associated with in the +

Gets the value associated with key in the registry. The value must be a floating point type.

- is the registry where the object will be + reg is the registry where the object will be looked up. - is the name of the object to look up. + key is the name of the object to look up.

On success, the function returns the value associated with - . + key. If the object is not found or if it is not a floating point object, -1.0 is returned. To avoid problems with in-band error reporting (that is, if you cannot distinguish between -1.0 and a valid result), use the more general function - instead.

+ ei_reg_getval() instead.

 @@ -158,21 +158,21 @@ const char *key; -

Gets the value associated with in the +

Gets the value associated with key in the registry. The value must be an integer.

- is the registry where the object will be + reg is the registry where the object will be looked up. - is the name of the object to look up. + key is the name of the object to look up.

On success, the function returns the value associated with - . + key. If the object is not found or if it is not an integer object, -1 is returned. To avoid problems with in-band error reporting (that is, if you cannot distinguish between -1 and a valid result), use the more general function - instead.

+ ei_reg_getval() instead.

 @@ -185,24 +185,24 @@ int size; -

Gets the value associated with in the +

Gets the value associated with key in the registry. The value must be a binary (pointer) type.

- is the registry where the object will be + reg is the registry where the object will be looked up. - is the name of the object to look up. + key is the name of the object to look up. - is initialized to contain the length in + size is initialized to contain the length in bytes of the object, if it is found.

On success, the function returns the value associated with - and indicates its length in - . + key and indicates its length in + size. If the object is not found or if it is not a binary object, NULL is returned. To avoid problems with in-band error reporting (that is, if you cannot distinguish between NULL and a valid result), use the more general function - instead.

+ ei_reg_getval() instead.

 @@ -214,20 +214,20 @@ const char *key; -

Gets the value associated with in the +

Gets the value associated with key in the registry. The value must be a string.

- is the registry where the object will be + reg is the registry where the object will be looked up. - is the name of the object to look up. + key is the name of the object to look up.

On success, the function returns the value associated with - . If the object is not found or if it is not a + key. If the object is not found or if it is not a string, NULL is returned. To avoid problems with in-band error reporting (that is, if you cannot distinguish between NULL and a valid result), use the more general function - instead.

+ ei_reg_getval() instead.

 @@ -245,32 +245,32 @@ object from the registry.

-

is the registry where the object will be +

reg is the registry where the object will be looked up.

 -

is the name of the object to look up.

+

key is the name of the object to look up.

 -

indicates the type of object that you - are looking for. If is 0, any +

flags indicates the type of object that you + are looking for. If flags is 0, any kind of object is returned. - If is EI_INT, EI_FLT, + If flags is EI_INT, EI_FLT, EI_STR, or EI_BIN, then only values of that kind are returned.

-

The buffer pointed to by +

The buffer pointed to by v must be large enough to hold the return data, that is, it must be - a pointer to one of , - , , or - , respectively.

-

If is EI_BIN, a fifth argument - is required, so that the size of the + a pointer to one of int, + double, char*, or + void*, respectively.

+

If flags is EI_BIN, a fifth argument + int *size is required, so that the size of the object can be returned.

 -

On success, (and if the +

On success, v (and size if the object is binary) is initialized with the value associated - with , and the function returns EI_INT, + with key, and the function returns EI_INT, EI_FLT, EI_STR, or EI_BIN, indicating the type of object. On failure, -1 is returned and the arguments are not updated.

@@ -295,9 +295,9 @@ unmodified. This function allows you to make such modifications and then let the registry know about them.

- is the registry containing the object. + reg is the registry containing the object. - is the name of the object to mark. + key is the name of the object to mark.

Returns 0 on success, otherwise -1.

@@ -312,14 +312,14 @@

Opens (creates) a registry, which initially is empty. To - close the registry later, use .

-

is the approximate number of objects you + close the registry later, use ei_reg_close().

+

size is the approximate number of objects you intend to store in the registry. As the registry uses a hash table with collision chaining, no absolute upper limit exists on the number of objects that can be stored in it. However, for reasons of efficiency, it is a good idea to choose a number that is appropriate for your needs. To change the size later, use - . Notice that the number + ei_reg_resize(). Notice that the number you provide is increased to the nearest larger prime number.

Returns an empty registry on success, otherwise NULL.

 @@ -333,13 +333,13 @@

Removes all objects marked for deletion. When objects - are deleted with they are not + are deleted with ei_reg_delete() they are not removed from the registry, only marked for later removal. On a later backup to Mnesia, the objects can also be removed from the Mnesia table. If you are not backing up to Mnesia, you may wish to remove the objects manually with this function.

-

is a registry containing objects marked for +

reg is a registry containing objects marked for deletion.

Returns 0 on success, otherwise -1.

 @@ -354,7 +354,7 @@

Changes the size of a registry.

-

is the new size to make the registry. The +

newsize is the new size to make the registry. The number is increased to the nearest larger prime number.

On success, the registry is resized, all contents rehashed, and 0 is returned. On failure, the @@ -373,17 +373,17 @@

The contents of a Mnesia table are read into the registry.

- is an open connection to Erlang. + fd is an open connection to Erlang. Mnesia 3.0 or later must be running on the Erlang node. - is the registry where the data is to be + reg is the registry where the data is to be placed. - is the name of the Mnesia table + mntab is the name of the Mnesia table to read data from.

Notice that only tables of a certain format can be restored, that is, those that have been created and backed up to - with . If the registry was not empty + with ei_reg_dump(). If the registry was not empty before the operation, the contents of the table are added to the contents of the registry. If the table contains objects with the same keys as those already in the registry, the registry objects @@ -407,16 +407,16 @@ double f; -

Creates a key-value pair with the specified - and floating point value . If an object already - exists with the same , the new value replaces +

Creates a key-value pair with the specified key + and floating point value f. If an object already + exists with the same key, the new value replaces the old one. If the previous value was a binary or string, it is - freed with .

+ freed with free().

- is the registry where the object is to be + reg is the registry where the object is to be placed. - is the object name. - is the floating point value to assign. + key is the object name. + f is the floating point value to assign.

Returns 0 on success, otherwise -1.

@@ -432,16 +432,16 @@ int i; -

Creates a key-value pair with the specified - and integer value . If an object already exists - with the same , the new value replaces the old +

Creates a key-value pair with the specified key + and integer value i. If an object already exists + with the same key, the new value replaces the old one. If the previous value was a binary or string, it is freed with - .

+ free().

- is the registry where the object is to be + reg is the registry where the object is to be placed. - is the object name. - is the integer value to assign. + key is the object name. + i is the integer value to assign.

Returns 0 on success, otherwise -1.

 @@ -457,21 +457,21 @@ int size; -

Creates a key-value pair with the specified - whose "value" is the binary object pointed to by . - If an object already exists with the same , +

Creates a key-value pair with the specified key + whose "value" is the binary object pointed to by p. + If an object already exists with the same key, the new value replaces the old one. If the previous value was a - binary or string, it is freed with .

+ binary or string, it is freed with free().

- is the registry where the object is to be + reg is the registry where the object is to be placed. - is the object name. - is a pointer to the binary object. The + key is the object name. + p is a pointer to the binary object. The object itself must have been created through a single call to - or a similar function, so that the + malloc() or a similar function, so that the registry can later delete it if necessary by calling - . - is the length in bytes of the binary + free(). + size is the length in bytes of the binary object.

Returns 0 on success, otherwise -1.

@@ -487,20 +487,20 @@ const char *s; -

Creates a key-value pair with the specified - whose "value" is the specified string . If an - object already exists with the same , the new +

Creates a key-value pair with the specified key + whose "value" is the specified string s. If an + object already exists with the same key, the new value replaces the old one. If the previous value was a binary or - string, it is freed with .

+ string, it is freed with free().

- is the registry where the object is to be + reg is the registry where the object is to be placed. - is the object name. - is the string to assign. The string itself + key is the object name. + s is the string to assign. The string itself must have been created through a single call to - or similar a function, + malloc() or similar a function, so that the registry can later delete it if - necessary by calling . + necessary by calling free().

Returns 0 on success, otherwise -1.

 @@ -516,36 +516,36 @@ v (see below) -

Creates a key-value pair with the specified - whose value is specified by . If an object already - exists with the same , the new value replaces +

Creates a key-value pair with the specified key + whose value is specified by v. If an object already + exists with the same key, the new value replaces the old one. If the previous value was a binary or string, it is freed - with .

+ with free().

-

is the registry where the object is to be +

reg is the registry where the object is to be placed.

 -

is the object name.

+

key is the object name.

 -

indicates the type of the object - specified by . Flags must be one of +

flags indicates the type of the object + specified by v. Flags must be one of EI_INT, EI_FLT, EI_STR, and EI_BIN, indicating whether - is , - , , or - .

-

If is EI_BIN, a fifth argument - is required, indicating the size - in bytes of the object pointed to by .

+ v is int, + double, char*, or + void*.

+

If flags is EI_BIN, a fifth argument + size is required, indicating the size + in bytes of the object pointed to by v.

If you wish to store an arbitrary pointer in the registry, - specify a of 0. In this case, the + specify a size of 0. In this case, the object itself is not transferred by an - operation, only the pointer + ei_reg_dump() operation, only the pointer value.

Returns 0 on success, otherwise -1.

 @@ -562,11 +562,11 @@

Returns information about an object.

- is the registry containing the object. + reg is the registry containing the object. - is the object name. - is a pointer to an - structure, defined as follows: + key is the object name. + obuf is a pointer to an + ei_reg_stat structure, defined as follows: -

In the attributes of the object are stored +

In attr the attributes of the object are stored as the logical OR of its type (one of EI_INT, EI_FLT, EI_BIN, and EI_STR), whether it is marked for deletion (EI_DELET), and whether it has been modified since the last backup to Mnesia (EI_DIRTY).

-

Field indicates the size in bytes required +

Field size indicates the size in bytes required to store EI_STR (including the terminating 0) and EI_BIN objects, or 0 for EI_INT and EI_FLT.

-

Returns 0 and initializes on success, +

Returns 0 and initializes obuf on success, otherwise -1.

 @@ -601,10 +601,10 @@ struct ei_reg_stat { returned by this function, you can see whether the size of the registry is suitable for the amount of data it contains.

- is the registry to return information + reg is the registry to return information about. - is a pointer to an - structure, defined as follows: + obuf is a pointer to an + ei_reg_tabstat structure, defined as follows: -

Field indicates the number of hash positions +

Field size indicates the number of hash positions in the registry. This is the number you provided when you created or last resized the registry, rounded up to the nearest prime number.

- indicates the number of elements stored + nelem indicates the number of elements stored in the registry. It includes objects that are deleted but not purged. - indicates the number of unique positions + npos indicates the number of unique positions that are occupied in the registry. - indicates how many elements are + collisions indicates how many elements are sharing positions in the registry.

On success, 0 is returned and - is initialized to contain table statistics, + obuf is initialized to contain table statistics, otherwise -1 is returned.

 -- cgit v1.2.3