From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/erl_interface/doc/html/.gitignore | 0 lib/erl_interface/doc/man1/.gitignore | 0 lib/erl_interface/doc/man3/.gitignore | 0 lib/erl_interface/doc/pdf/.gitignore | 0 lib/erl_interface/doc/src/Makefile | 129 ++++ lib/erl_interface/doc/src/book.xml | 49 ++ lib/erl_interface/doc/src/ei.xml | 728 +++++++++++++++++++++ lib/erl_interface/doc/src/ei_connect.xml | 639 ++++++++++++++++++ lib/erl_interface/doc/src/ei_users_guide.xml | 612 +++++++++++++++++ lib/erl_interface/doc/src/erl_call.xml | 240 +++++++ lib/erl_interface/doc/src/erl_connect.xml | 566 ++++++++++++++++ lib/erl_interface/doc/src/erl_error.xml | 136 ++++ lib/erl_interface/doc/src/erl_eterm.xml | 675 +++++++++++++++++++ lib/erl_interface/doc/src/erl_format.xml | 141 ++++ lib/erl_interface/doc/src/erl_global.xml | 141 ++++ lib/erl_interface/doc/src/erl_interface.xml | 625 ++++++++++++++++++ lib/erl_interface/doc/src/erl_malloc.xml | 200 ++++++ lib/erl_interface/doc/src/erl_marshal.xml | 272 ++++++++ lib/erl_interface/doc/src/fascicules.xml | 24 + lib/erl_interface/doc/src/make.dep | 24 + lib/erl_interface/doc/src/note.gif | Bin 0 -> 1539 bytes lib/erl_interface/doc/src/notes.xml | 535 +++++++++++++++ lib/erl_interface/doc/src/notes_history.xml | 367 +++++++++++ lib/erl_interface/doc/src/part.xml | 33 + lib/erl_interface/doc/src/part_erl_interface.xml | 33 + lib/erl_interface/doc/src/part_notes.xml | 38 ++ lib/erl_interface/doc/src/part_notes_history.xml | 36 + lib/erl_interface/doc/src/ref_man.xml | 55 ++ lib/erl_interface/doc/src/ref_man_ei.xml | 47 ++ .../doc/src/ref_man_erl_interface.xml | 52 ++ lib/erl_interface/doc/src/registry.xml | 611 +++++++++++++++++ lib/erl_interface/doc/src/warning.gif | Bin 0 -> 1498 bytes 32 files changed, 7008 insertions(+) create mode 100644 lib/erl_interface/doc/html/.gitignore create mode 100644 lib/erl_interface/doc/man1/.gitignore create mode 100644 lib/erl_interface/doc/man3/.gitignore create mode 100644 lib/erl_interface/doc/pdf/.gitignore create mode 100644 lib/erl_interface/doc/src/Makefile create mode 100644 lib/erl_interface/doc/src/book.xml create mode 100644 lib/erl_interface/doc/src/ei.xml create mode 100644 lib/erl_interface/doc/src/ei_connect.xml create mode 100644 lib/erl_interface/doc/src/ei_users_guide.xml create mode 100644 lib/erl_interface/doc/src/erl_call.xml create mode 100644 lib/erl_interface/doc/src/erl_connect.xml create mode 100644 lib/erl_interface/doc/src/erl_error.xml create mode 100644 lib/erl_interface/doc/src/erl_eterm.xml create mode 100644 lib/erl_interface/doc/src/erl_format.xml create mode 100644 lib/erl_interface/doc/src/erl_global.xml create mode 100644 lib/erl_interface/doc/src/erl_interface.xml create mode 100644 lib/erl_interface/doc/src/erl_malloc.xml create mode 100644 lib/erl_interface/doc/src/erl_marshal.xml create mode 100644 lib/erl_interface/doc/src/fascicules.xml create mode 100644 lib/erl_interface/doc/src/make.dep create mode 100644 lib/erl_interface/doc/src/note.gif create mode 100644 lib/erl_interface/doc/src/notes.xml create mode 100644 lib/erl_interface/doc/src/notes_history.xml create mode 100644 lib/erl_interface/doc/src/part.xml create mode 100644 lib/erl_interface/doc/src/part_erl_interface.xml create mode 100644 lib/erl_interface/doc/src/part_notes.xml create mode 100644 lib/erl_interface/doc/src/part_notes_history.xml create mode 100644 lib/erl_interface/doc/src/ref_man.xml create mode 100644 lib/erl_interface/doc/src/ref_man_ei.xml create mode 100644 lib/erl_interface/doc/src/ref_man_erl_interface.xml create mode 100644 lib/erl_interface/doc/src/registry.xml create mode 100644 lib/erl_interface/doc/src/warning.gif (limited to 'lib/erl_interface/doc') diff --git a/lib/erl_interface/doc/html/.gitignore b/lib/erl_interface/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/erl_interface/doc/man1/.gitignore b/lib/erl_interface/doc/man1/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/erl_interface/doc/man3/.gitignore b/lib/erl_interface/doc/man3/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/erl_interface/doc/pdf/.gitignore b/lib/erl_interface/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/erl_interface/doc/src/Makefile b/lib/erl_interface/doc/src/Makefile new file mode 100644 index 0000000000..e05b647cb2 --- /dev/null +++ b/lib/erl_interface/doc/src/Makefile @@ -0,0 +1,129 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1998-2009. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(EI_VSN) +APPLICATION=erl_interface + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- + +XML_REF1_FILES = erl_call.xml +XML_REF3_FILES = erl_connect.xml \ + erl_error.xml \ + erl_eterm.xml \ + erl_format.xml \ + erl_malloc.xml \ + erl_marshal.xml \ + erl_global.xml \ + ei.xml \ + ei_connect.xml \ + registry.xml + +BOOK_FILES = book.xml +XML_APPLICATION_FILES = ref_man.xml +#ref_man_ei.xml ref_man_erl_interface.xml +XML_PART_FILES = \ + part.xml \ + part_notes.xml \ + part_notes_history.xml +XML_CHAPTER_FILES = ei_users_guide.xml notes.xml notes_history.xml + +XML_FILES = $(XML_REF1_FILES) $(XML_REF3_FILES) $(BOOK_FILES) \ + $(XML_APPLICATION_FILES) $(XML_PART_FILES) $(XML_CHAPTER_FILES) +# ---------------------------------------------------- + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info + +GIF_FILES = + +MAN1_FILES = $(XML_REF1_FILES:%.xml=$(MAN1DIR)/%.1) +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html man + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +man: $(MAN1_FILES) $(MAN3_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +debug opt: + +clean clean_docs clean_tex: + rm -rf $(HTMLDIR)/* + rm -f $(MAN1DIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man1 + $(INSTALL_DATA) $(MAN1_FILES) $(RELEASE_PATH)/man/man1 + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3 + + +release_spec: + diff --git a/lib/erl_interface/doc/src/book.xml b/lib/erl_interface/doc/src/book.xml new file mode 100644 index 0000000000..e911b6aa2b --- /dev/null +++ b/lib/erl_interface/doc/src/book.xml @@ -0,0 +1,49 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Erlang Interface + Gordon Beaton + + 1998-11-30 + 1.2 + book.sgml +
+ + + Erlang Interface + + + + + + + + + + + + + + + + diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml new file mode 100644 index 0000000000..2f65a8c375 --- /dev/null +++ b/lib/erl_interface/doc/src/ei.xml @@ -0,0 +1,728 @@ + + + + +
+ + 20012009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + ei + Jakob Cederlund + Kent Boortz + 1 + Kenneth Lundin + + 2000-11-27 + PA1 + ei.sgml +
+ ei + 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 + 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 + 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 + 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 + is the way in to "preflight" term encoding.

+

There are also encode-functions that uses 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 + the + function returns the size required (note that for strings an + extra byte is needed for the 0 string terminator).

+ + + + 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_encode_version(char *buf, int *index) + intei_x_encode_version(ei_x_buff* x) + Encode version + +

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

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

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

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

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

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 + the C compilers and system may define to be + signed.

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

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

Encodes an atom in the binary format. The parameter + is the name of the atom. Only upto bytes + are encoded. The name should be zero-terminated, except for + the function.

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

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

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

+ + + + 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 + points to an structure. The + is not freed automatically, the + should be called if the fun is not needed + after encoding.

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

Encodes an erlang port in the binary format. The + 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 + +

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

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

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_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 + arity. The next terms are the elements + (actually it's 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 :

+ 
+ei_encode_list_header(buf, &i, 3);
+ei_encode_atom(buf, &i, "c");
+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);
+
+ +

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.

+ +

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

+ 
+while (something()) {
+    ei_x_encode_list_header(&x, 1);
+    ei_x_encode_ulong(&x, i); /* just an example */
+}
+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 () + +

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

+ + + + 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 + name of the atom is placed at . There can be at most + bytes placed in the buffer.

+ + + + 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_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 + 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_decode_pid(const char *buf, int *index, erlang_pid *p) + Decode a + +

Decodes a pid, process identifier, 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.

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

This function decodes a reference from the binary format.

+ + + + 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_list_header(const char *buf, int *index, int *arity) + Decode a list + +

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_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 0 on successful encoding, -1 on error, + and 1 if the term seems alright, but does not fit in the + structure. If it returns 0, 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_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 + library.

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

+ + + + intei_x_format(ei_x_buff* x, const char* fmt, ...) + 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 + 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*
+~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
+
+

For instance, 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.

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

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

Some tips on what to check when the emulator doesn't 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 + +
+ +
+ See Also +

erl_interface(3)

+
+ + diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml new file mode 100644 index 0000000000..08e7b122c6 --- /dev/null +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -0,0 +1,639 @@ + + + + +
+ + 20012009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + ei_connect + Jakob Cederlund + + ? + ? + 2001-09-01 + A + ei_connect.sgml +
+ ei_connect + 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. + 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 .

+

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

+ + +
+ Timeout 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 + 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 ment an operation on the socket, like + , , or .

+

Obviously the timeouts are for implementing fault tolerance, + not to keep hard realtime 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 + 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 + 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.

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

+

Example 1: +

+ +

Example 2: +

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

ei_connect and ei_xconnect 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 + +

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

+

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:

+ + + Temporary error: Try again. + + Buffer too small. + + I/O error. + + + + + intei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms) + Receive a message with optional timeout + +

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

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:

+ +

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.

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

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

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

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":

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

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

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:

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

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

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

+

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_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_unpublish(ei_cnode *ec) + Unpublish a node name + +

This function can be called by a process to unregister a + specified node from epmd on the localhost. This may be + useful, for example, when epmd has not detected the failure of a + node, and will not allow the name to be reused. If you use this + function to unregister your own process, be sure to also close + the descriptor that was returned by .

+ +

Careless use of this function may have unpredictable + results, if the registered node is in fact still running.

+ +

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_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms) + Unpublish a node name with optional timeout + +

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

+ + + + 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 + structure. Read the field directly will probably be safe for + a long time, so these functions are not really needed.

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

These are convenience functions for some common name lookup functions.

+ + + + +
+ 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. + +
+ + diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml new file mode 100644 index 0000000000..5d18e356cb --- /dev/null +++ b/lib/erl_interface/doc/src/ei_users_guide.xml @@ -0,0 +1,612 @@ + + + + +
+ + 20022009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + The El Library User's Guide + Kent Boortz + Kent Boortz + + + + + + 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 + + +
+ Compiling and Linking Your Code +

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

+ +

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 .

+ +

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

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

+
+ +
+ 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 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 + structures. The library also contains an encode and a decode function. + The example below 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:

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

The previous example can be simplified by using + 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:

+ +

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:

+ +

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 + can use the following function to see the status of the fixed term + allocator:

+ +

Refer to the Reference Manual, the 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 + 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 + 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 + 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 + + +

Refer to the Reference Manual, the 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 , + 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.

+

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:

+ +

prints the specified string and terminates + the program. Refer to the Reference Manual, the + 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 + 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 + connection is then made to the Erlang node.

+

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:

+ +

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

+
+ +
+ Sending and Receiving Erlang Messages +

Use one of the following two functions to send messages:

+ + + + +

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.

+

Use one of the following two functions to receive messages:

+ + + + +

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 :

+ +

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.

+
+ +
+ Example of Receiving Messages +

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.

+

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:

+ + + . + +
+
+ +
+ Remote Procedure Calls +

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:

+ when compiling file: %s.erl !\n", modname); +erl_free_term(ep); +ep = erl_format("{ok,_}"); +if (!erl_match(ep, reply)) + erl_err_msg(" 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 + successful by testing for the expected .

+

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

+
+ +
+ Using Global Names +

A C node has access to names registered through the Erlang 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, + 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 + 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.

+

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 + the node where the service is registered, so that you can make a + connection to it by simply passing the variable to .

+

Before registering a name, you should already have registered your + 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.

+

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 !

+

To unregister a name:

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

+ +

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.

+

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 + 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 + 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 + 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 + the right type for the specified operation. If you do not know the + type of a given object, you can ask:

+ +

Buf will be 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 + 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 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 + 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, + 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.

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

+

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

+

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.

+

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

+
+
+ + diff --git a/lib/erl_interface/doc/src/erl_call.xml b/lib/erl_interface/doc/src/erl_call.xml new file mode 100644 index 0000000000..2d88e7616a --- /dev/null +++ b/lib/erl_interface/doc/src/erl_call.xml @@ -0,0 +1,240 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + erl_call + Torbjörn Törnkvist + Torbjörn Törnkvist + + Bjarne Däcker + Torbjörn Törnkvist + 97-05-16 + B + erl_call.sgml +
+ 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.

+

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

+ + + + erl_call <options> + Start/Call Erlang + +

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

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

(optional): Applies the specified function + and returns the result. must be specified, however + [] is assumed for unspecified and . 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.

+

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

+ + -d + +

(optional): Debug mode. This causes all IO to be output + to the file , where + is the node name of the Erlang node in question.

+

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

+

+ + -h HiddenName + +

(optional): Specifies the name of the hidden node + that represents.

+

+ + -m + +

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

+

+ + -n Node + +

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

+

+ + -q + +

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

+

+ + -r + +

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

+

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

+

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

+

+ + -v + +

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

+

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

+ + + + + + +
+ Examples +

Starts an Erlang node and calls .

+ +

Terminates an Erlang node by calling .

+ +

An apply with several arguments.

+ +

Evaluates a couple of 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).

+ + P = processes(), + F = fun(X) -> {X,process_info(X,registered_name)} end, + lists:map(F,[],P). +^D +[{, + {registered_name,init}}, + {, + {registered_name,erl_prim_loader}}, + {, + {registered_name,error_logger}}, + {, + {registered_name,application_controller}}, + {, + {registered_name,kernel}}, + {, + []}, + {, + {registered_name,kernel_sup}}, + {, + {registered_name,net_sup}}, + {, + {registered_name,net_kernel}}, + {, + []}, + {, + {registered_name,global_name_server}}, + {, + {registered_name,auth}}, + {, + {registered_name,rex}}, + {, + []}, + {, + {registered_name,file_server}}, + {, + {registered_name,code_server}}, + {, + {registered_name,user}}, + {, + []}] + ]]> +
+ + diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml new file mode 100644 index 0000000000..b2235925b2 --- /dev/null +++ b/lib/erl_interface/doc/src/erl_connect.xml @@ -0,0 +1,566 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + erl_connect + Torbjörn Törnkvist + Torbjörn Törnkvist + + Bjarne Däcker + Torbjörn Törnkvist + 980703 + A + erl_connect.sgml +
+ erl_connect + 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 + processes.

+

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 .

+ + + + interl_connect_init(number, cookie, creation) + interl_connect_xinit(host, alive, node, addr, cookie, creation) + Initialize communication + + int number; + char *cookie; + short creation; + char *host,*alive,*node; + struct in_addr *addr; + + +

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

+ when initializing !"); + ]]> +

Example 2:

+ when initializing !"); + ]]> + + + + 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_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_receive(fd, bufp, bufsize) + Receive a message + + int fd; + char *bufp; + int bufsize; + + +

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

+

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 + to one of:

+ + + Temporary error: Try again. + + Buffer too small. + + I/O error. + + + + + interl_receive_msg(fd, bufp, bufsize, emsg) + Receive and decodes a message + + int fd; + unsigned char *bufp; + int bufsize; + 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:

+ + +

The definition of has changed since + 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. +

+ +

It is the caller's responsibility to release the + memory pointed to by msg]]>, to]]> and + from]]>.

+ +

If a tick occurs, i.e., 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 + 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.

+

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

+ + + No more memory available. + + I/O error. + + + + + ETERM *erl_rpc(fd, mod, fun, args) + interl_rpc_to(fd, mod, fun, args) + interl_rpc_from(fd, timeout, emsg) + Remote Procedure Call + + int fd, timeout; + char *mod, *fun; + ETERM *args; + 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 + 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. +

+ +

It is the caller's responsibility to free the returned + structure as well as 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, + all three functions set to one of:

+ + + No more memory available. + + I/O error. + + Timeout expired. + + Temporary error: Try again. + + + + + interl_publish(port) + Publish a node name + + int port; + + +

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

+

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

+ + + 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() + shorterl_thiscreation() + Retrieve some values + +

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

+ + + + interl_unpublish(alive) + Unpublish a node name + + char *alive; + + +

This function can be called by a process to unregister a + specified node name from epmd on the localhost. This may be + useful, for example, when epmd has not detected the failure of a + node, and will not allow the name to be reused. If you use this + function to unregister your own process, be sure to also close + the descriptor that was returned by .

+ +

Careless use of this function may have unpredictable + results, if the registered node is in fact still running.

+ +

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 .

+ + + + struct hostent*erl_gethostbyname(name) + 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 + + const char *name; + const char *addr; + int length; + int type; + struct hostent *hostp; + char *buffer; + int buflen; + int *h_errnop; + + +

These are convenience functions for some common name lookup functions.

+ + + + +
+ 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. + +
+ + diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml new file mode 100644 index 0000000000..4a3f34fac7 --- /dev/null +++ b/lib/erl_interface/doc/src/erl_error.xml @@ -0,0 +1,136 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + erl_error + Torbjörn Törnkvist + Torbjörn Törnkvist + + Bjarne Däcker + Torbjörn Törnkvist + 961014 + A + erl_error.sgml +
+ erl_error + Error Print Routines + +

This module contains some error printing routines taken + 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 + these functions is to .

+ + + + voiderl_err_msg(FormatStr, ... ) + Non-fatal error, and not system call error + + const char *FormatStr; + + +

The message provided by the caller is printed. This + function is simply a wrapper for .

+ + + + voiderl_err_quit(FormatStr, ... ) + Fatal error, but not system call error + + const char *FormatStr; + + +

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.

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

+ + + + voiderl_err_sys(FormatStr, ... ) + 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, and the process + terminates with an exit value of 1. The function does not + return.

+ + + + +
+ Error Reporting +

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.

+
+ + + volatile interl_errno + 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 + non-zero error code to indicate what kind of error it + encountered. A successful function call might change + (by calling some other function that + fails), but no function will ever 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.

+

uses the error codes defined in your + system's ]]>.

+ +

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

+ + + + + + diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml new file mode 100644 index 0000000000..ce14549672 --- /dev/null +++ b/lib/erl_interface/doc/src/erl_eterm.xml @@ -0,0 +1,675 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + erl_eterm + Torbjörn Törnkvist + Torbjörn Törnkvist + + Bjarne Däcker + Torbjörn Törnkvist + 980703 + A + erl_eterm.sgml +
+ erl_eterm + Functions for Erlang Term Construction + +

This module contains 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 + 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:

+ + + 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 elements. + + True if is an empty list. + + 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. +

+ + + A string representing atom . + + + The length (in characters) of atom t. + + 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 . + + 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 . + + The node in port . + + The first part of the reference number in ref . Use + only for compatibility. + + Pointer to the array of reference numbers in ref . + + The number of used reference numbers in ref . + + The creation number in ref . + + The number of elements in tuple . + + The head element of list . + + A List representing the tail elements of list . + + + + + ETERM *erl_cons(head, tail) + Prepends 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.

+

The function returns a new list.

+

and + can be used to retrieve the head and tail components + from the list. and will do + the same thing, but check that the argument really is a list.

+

For example:

+ + + + + ETERM *erl_copy_term(term) + Creates a copy of an Erlang term + + ETERM *term; + + +

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

+ + + + ETERM *erl_element(position, tuple) + Extracts 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 .

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

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

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

+ + + + ETERM *erl_iolist_to_binary(term) + Converts an IO list to a binary + + ETERM *list; + + +

This function converts an IO 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:

+ + + + + char *erl_iolist_to_string(list) + Converts an IO 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 + 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.

+ + + + 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 + + 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 + cell, and the last tail points to an empty list.

+

Returns -1 if is not a proper list.

+ + + + ETERM *erl_mk_atom(string) + Creates an atom + + char *string; + + +

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 + contains a valid name for an atom.

+

can be used to retrieve the + atom name (as a string). Note that the string is not + 0-terminated in the atom. returns + the length of the atom name.

+ + + + ETERM *erl_mk_binary(bptr, size) + Creates a binary object + + char *bptr; + int size; + + +

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

+

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

+ + + + ETERM *erl_mk_empty_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; + Use this function instead.

+ + + + ETERM *erl_mk_estring(string, len) + Creates 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 + the character sequence in .

+ + + + ETERM *erl_mk_float(f) + Creates 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 .

+

can be used to retrieve the + value from an Erlang float.

+ + + + ETERM *erl_mk_int(n) + Creates 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 + value specified in .

+

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

+ + + + ETERM *erl_mk_list(array, arrsize) + Creates a list from an array + + ETERM **array; + int arrsize; + + +

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 function creates an Erlang list object, whose length + and whose elements are taken from the terms in + .

+ + + + ETERM *erl_mk_pid(node, number, serial, creation) + Creates a process identifier + + const char *node; + unsigned int number; + unsigned int serial; + unsigned int creation; + + +

This function creates an Erlang process identifier. 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 + can be used to retrieve the four values used to create the pid.

+ + + + ETERM *erl_mk_port(node, number, creation) + Creates 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.

+ + + + ETERM *erl_mk_ref(node, number, creation) + Creates an old Erlang reference + + const char *node; + unsigned int number; + unsigned int creation; + + +

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

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

+ + + + ETERM *erl_mk_tuple(array, arrsize) + Creates 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 .

+

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 + returns the arity of a tuple. + will do the same thing, but it checks that + the argument really is a tuple. + returns the element + corresponding to a given position in the tuple.

+ + + + ETERM *erl_mk_uint(n) + Creates an unsigned integer + + unsigned int n; + + +

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 + 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 + + char *name; + + +

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

+ + + + interl_print_term(stream, term) + Prints 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.

+ + + + 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 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 + directly after the call to the + erl_init() function.

+ + +

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.

+ + + + + interl_size(term) + Return the arity of a tuple or 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.

+ + + + ETERM *erl_tl(list) + Extracts 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 + was not a list.

+ + + + ETERM *erl_var_content(term, name) + Extracts 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 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.

+ + + + + diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml new file mode 100644 index 0000000000..5699485845 --- /dev/null +++ b/lib/erl_interface/doc/src/erl_format.xml @@ -0,0 +1,141 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + erl_format + Torbjörn Törnkvist + Torbjörn Törnkvist + + Bjarne Däcker + Torbjörn Törnkvist + 961016 + A + erl_format.sgml +
+ erl_format + Create and Match Erlang Terms + +

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 + + char *FormatStr; + + +

This is 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:

+ + +

~i - Integer

+ + +

~f - Floating point

+ + +

~a - Atom

+ + +

~s - String

+ + +

~w - Arbitrary Erlang term

+ + +

For each format specifier that appears 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 + format specifiers. For example:

+ +

This will create an structure corresponding + to the 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 + + 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:

+ +

can be used to retrieve the + content of any variables bound as a result of a call to + .

+ + + + + diff --git a/lib/erl_interface/doc/src/erl_global.xml b/lib/erl_interface/doc/src/erl_global.xml new file mode 100644 index 0000000000..8f9a354b4f --- /dev/null +++ b/lib/erl_interface/doc/src/erl_global.xml @@ -0,0 +1,141 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + erl_global + Gordon Beaton + Gordon Beaton + + Gordon Beaton + Gordon Beaton + 980703 + A + erl_global.sgml +
+ erl_global + 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 + 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 + + 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. +

+

On success, the function returns an array of strings, each + 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. +

+ +

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.

+ + + + + interl_global_register(fd,name,pid) + 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.

+ + + + interl_global_unregister(fd,name) + Unregister a name in 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.

+ + + + ETERM *erl_global_whereis(fd,name,node) + Look up a name in global + + int fd; + const char *name; + 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.

+ + + + + diff --git a/lib/erl_interface/doc/src/erl_interface.xml b/lib/erl_interface/doc/src/erl_interface.xml new file mode 100644 index 0000000000..850a4127f4 --- /dev/null +++ b/lib/erl_interface/doc/src/erl_interface.xml @@ -0,0 +1,625 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + The Erl_Interface Library + Torbjörn Törnkvist + Torbjörn Törnkvist + + Bjarne Däcker + K.Lundin + 990113 + A + erl_interface.sgml +
+

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 + + +
+ Compiling and Linking Your Code +

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

+ +

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 .

+ +

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

+

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

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

+
+ +
+ 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 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 + structures. The library also contains an encode and a decode function. + The example below 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:

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

The previous example can be simplified by using + 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:

+ +

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:

+ +

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 + can use the following function to see the status of the fixed term + allocator:

+ +

Refer to the Reference Manual, the 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 + 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 + 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 + 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 + + +

Refer to the Reference Manual, the 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 , + 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.

+

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:

+ +

prints the specified string and terminates + the program. Refer to the Reference Manual, the + 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 + 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 + connection is then made to the Erlang node.

+

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:

+ +

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

+
+ +
+ Sending and Receiving Erlang Messages +

Use one of the following two functions to send messages:

+ + + + +

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.

+

Use one of the following two functions to receive messages:

+ + + + +

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 :

+ +

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.

+
+ +
+ Example of Receiving Messages +

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.

+

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:

+ + + . + +
+
+ +
+ Remote Procedure Calls +

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:

+ when compiling file: %s.erl !\ +", modname); +erl_free_term(ep); +ep = erl_format("{ok,_}"); +if (!erl_match(ep, reply)) + erl_err_msg(" compiler errors !\ +"); +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 .

+
+ +
+ Using Global Names +

A C node has access to names registered through the Erlang 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, + 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 + 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.

+

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 + the node where the service is registered, so that you can make a + connection to it by simply passing the variable to .

+

Before registering a name, you should already have registered your + 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.

+

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 !

+

To unregister a name:

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

+ +

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.

+

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 + 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 + 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 + 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 + the right type for the specified operation. If you do not know the + type of a given object, you can ask:

+ +

Buf will be 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 + 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 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 + 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, + 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.

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

+

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

+

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.

+

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

+
+
+ + diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml new file mode 100644 index 0000000000..8c8750d62a --- /dev/null +++ b/lib/erl_interface/doc/src/erl_malloc.xml @@ -0,0 +1,200 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + erl_malloc + Torbjörn Törnkvist + Torbjörn Törnkvist + + Bjarne Däcker + Torbjörn Törnkvist + 980703 + A + erl_malloc.sgml +
+ erl_malloc + Memory Allocation Functions + +

This module provides functions for allocating and deallocating + memory.

+ + + + ETERM *erl_alloc_eterm(etype) + Allocates an ETERM structure + + unsigned char etype; + + +

This function allocates an structure. + Specify as one of the following constants:

+ + +

ERL_INTEGER

+ + +

ERL_U_INTEGER

+ + +

ERL_ATOM

+ + +

ERL_PID

+ + +

ERL_PORT

+ + +

ERL_REF

+ + +

ERL_LIST

+ + +

ERL_EMPTY_LIST

+ + +

ERL_TUPLE

+ + +

ERL_BINARY

+ + +

ERL_FLOAT

+ + +

ERL_VARIABLE

+ + +

ERL_SMALL_BIG

+ + +

ERL_U_SMALL_BIG

+ + +

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.

+ + + + voiderl_eterm_release(void) + Clears the ETERM freelist + +

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

+ + + + voiderl_eterm_statistics(allocated, freed) + Reports term allocation statistics + + long *allocated; + long *freed; + + +

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

+ + + + voiderl_free_array(array, size) + Frees 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.

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

+ + + + voiderl_malloc(size) + Allocates some memory + + long size; + + +

This function calls the standard + function.

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

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 new file mode 100644 index 0000000000..a7eaf78f35 --- /dev/null +++ b/lib/erl_interface/doc/src/erl_marshal.xml @@ -0,0 +1,272 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + erl_marshal + Torbjörn Törnkvist + Torbjörn Törnkvist + + Bjarne Däcker + Torbjörn Törnkvist + 980703 + A + erl_marshal.sgml +
+ erl_marshal + 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 + + 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. +

+ + + + ETERM *erl_decode(bufp) + ETERM *erl_decode_buf(bufpp) + Converts a term from Erlang external format + + unsigned char *bufp; + unsigned char **bufpp; + + +

and decode + the contents of a buffer and return the corresponding + 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. +

+

returns an Erlang term + corresponding to the contents of on success, or + NULL on failure. returns an Erlang + term corresponding to the first of the consecutive terms in + and moves forward to point to the + next term in the buffer. On failure, each of the functions + returns NULL. +

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

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

+

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

+

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

+ + + 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 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. + + (integers < 256) need 2 bytes. + + need 32 bytes. + + 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. + +

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

+ + + + interl_ext_size(bufp) + Counts elements in encoded term + + unsigned char *bufp; + + +

This function returns the number of elements in an + encoded term.

+ + + + unsigned charerl_ext_type(bufp) + Determines 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

+ + +

ERL_INTEGER

+ + +

ERL_ATOM

+ + +

ERL_PID

+ + +

ERL_PORT

+ + +

ERL_REF

+ + +

ERL_EMPTY_LIST

+ + +

ERL_LIST

+ + +

ERL_TUPLE

+ + +

ERL_FLOAT

+ + +

ERL_BINARY

+ + +

ERL_FUNCTION

+ + + + + + unsigned char *erl_peek_ext(bufp, pos) + Steps 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. +

+ + + + interl_term_len(t) + Determines encoded size of term + + ETERM *t; + + +

This function determines the buffer space that would be + needed by if it were encoded into Erlang external + format by . +

+

The size in bytes is returned. +

+ + + + + diff --git a/lib/erl_interface/doc/src/fascicules.xml b/lib/erl_interface/doc/src/fascicules.xml new file mode 100644 index 0000000000..3d6219a2bd --- /dev/null +++ b/lib/erl_interface/doc/src/fascicules.xml @@ -0,0 +1,24 @@ + + + + + + EI User's Guide + + + EI Library Reference + + + Erl_interface Library Reference + + + Command Reference + + + Release Notes + + + Off-Print + + + diff --git a/lib/erl_interface/doc/src/make.dep b/lib/erl_interface/doc/src/make.dep new file mode 100644 index 0000000000..3f43cf64fe --- /dev/null +++ b/lib/erl_interface/doc/src/make.dep @@ -0,0 +1,24 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin//docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: book.tex ei.tex ei_connect.tex ei_users_guide.tex \ + erl_call.tex erl_connect.tex erl_error.tex \ + erl_eterm.tex erl_format.tex erl_global.tex \ + erl_malloc.tex erl_marshal.tex part_ei.tex \ + ref_man.tex ref_man_ei.tex ref_man_erl_interface.tex \ + registry.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: ref_man.xml ref_man_ei.xml ref_man_erl_interface.xml + diff --git a/lib/erl_interface/doc/src/note.gif b/lib/erl_interface/doc/src/note.gif new file mode 100644 index 0000000000..6fffe30419 Binary files /dev/null and b/lib/erl_interface/doc/src/note.gif differ diff --git a/lib/erl_interface/doc/src/notes.xml b/lib/erl_interface/doc/src/notes.xml new file mode 100644 index 0000000000..f2519fda0b --- /dev/null +++ b/lib/erl_interface/doc/src/notes.xml @@ -0,0 +1,535 @@ + + + + +
+ + 20042009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Erl_interface Release Notes + otp_appnotes + nil + nil + nil + notes.xml +
+

This document describes the changes made to the Erl_interface application.

+ +
Erl_Interface 3.6.4 + +
Improvements and New Features + + +

+ The documentation is now built with open source tools + (xsltproc and fop) that exists on most platforms. One + visible change is that the frames are removed.

+

+ Own Id: OTP-8201

+ + +
+ +
+ +
Erl_Interface 3.6.3 + +
Fixed Bugs and Malfunctions + + +

+ The manual states that erl_receive() return the reason in + the ErlMessage struct. This was not the case and + the function is now corrected.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-4969

+ + +

+ In send_exit.c an errorneous size of memory + allocation could occur when reallocating a buffer.

+

+ In ei_decode_trace.c the index could be updated + when the decoding failed.

+

+ In ei_printterm.c the index could be updated when + the decoding failed in lists and tuples.

+

+ In ei_decode_term.c when decoding a double + (ERL_FLOAT_EXT) no check was done to ensure that the last + of the 31 bytes was null terminated.

+

+ In ei_decode_term.c when decoding references, only + the first 3 bytes are read, but the index did not + increment by the total size.

+

+ In ei_decode_fun.c no check of correct buffer + allocation or data length was done.

+

+ In ei_decode_string.c the integer list string case + did not decode the NIL tail correctly.

+

+ These errors has now been fixed. (Thanks to Romain + Lenglet, Paul Mineiro and Paul Guyot).

+

+ Own Id: OTP-6117

+ + +

+ ei_decode_big could be decoded with a garbage + byte.

+

+ ei_encode_big and ei_x_encode_big is now + available.

+

+ Own Id: OTP-7554

+ + +

+ The function erl_init_resolve() did not conform to + C99 standard which caused a build error on some + platforms. This has now been fixed.

+

+ Own Id: OTP-8093

+ + +

+ Makefile.in has been updated to use the LDFLAGS + environment variable (if set). (Thanks to Davide + Pesavento.)

+

+ Own Id: OTP-8157

+ + +
+ + +
Improvements and New Features + + +

+ Added support for 64-bit integers in encoding/decoding.

+

+ Added support for better printouts of binaries.

+

+ Own Id: OTP-6091

+ + +
+ +
+ +
Erl_Interface 3.6.2 + +
Fixed Bugs and Malfunctions + + +

+ A problem with gethostbyname in erl_start.c + could cause a buffer overflow. This has now been fixed.

+

+ Clean up of code and removed compiler warnings.

+

+ Own Id: OTP-7978

+ + +
+ +
+ +
Erl_Interface 3.6.1 + +
Fixed Bugs and Malfunctions + + +

A faulty validation in ei_reg_getpval caused it + to never return the key-value. This has now been fixed. + (Thanks to Matt Stancliff)

+

+ Own Id: OTP-7960

+ + +
+ + +
Improvements and New Features + + +

Minor update to the configure script.

+

+ Own Id: OTP-7959

+ + +
+ +
+ +
Erl_Interface 3.6.1 + +
Improvements and New Features + + +

Minor update to the configure script.

+

+ Own Id: OTP-7959

+ + +
+ +
+ +
Erl_Interface 3.6 + +
Improvements and New Features + + +

+ Nodes belonging to different independent clusters can now + co-exist on the same host with the help of a new + environment variable setting ERL_EPMD_PORT.

+

+ Own Id: OTP-7826

+ + +
+ +
+ +
Erl_Interface 3.5.9 + +
Fixed Bugs and Malfunctions + + +

+ A type-casting bug in ei_skip_term and ei_printterm on + 64bit platforms rendering undefined results is now + corrected.

+

+ Own Id: OTP-7577

+ + +

+ A bug in the hostent copying code of erl_interface on + MacOS X/Darwin is now corrected.

+

+ Own Id: OTP-7593

+ + +

A problem with building erl_interface on + FreeBSD has been fixed (Thanks to Akira Kitada).

+

+ Own Id: OTP-7611

+ + +
+ +
+ +
Erl_Interface 3.5.8 + +
Fixed Bugs and Malfunctions + + +

+ Fixed bug in erl_interface when decoding broken data

+

+ Own Id: OTP-7448

+ + +
+ +
+ + +
Erl_Interface 3.5.7 + +
Fixed Bugs and Malfunctions + + +

+ An erroneous freeing of memory could occur when using + ei_x_format_wo_ver in erl_interface, resulting in + a segmentation fault.

+

+ Own Id: OTP-6795

+ + +

+ A faulty compare in erl_marshal has now been + fixed. (Thanks to Simon Cornish and Paul Mineiro)

+

+ Own Id: OTP-7368

+ + +
+ +
+ +
Erl_Interface 3.5.6 + +
Fixed Bugs and Malfunctions + + +

+ Minor documentation fixes.

+

+ Own Id: OTP-7183 Aux Id: OTP-7118

+ + +
+ +
+ +
Erl_Interface 3.5.5.4 + +
Fixed Bugs and Malfunctions + + +

+ The symbol __erl_errno was undefined in the single thread + version of the ei library, but is now defined.

+

+ Own Id: OTP-6887

+ + +

+ Corrected FreeBSD build error.

+

+ Own Id: OTP-7093

+ + +
+ +
+ +
+ Erl_Interface 3.5.5.3 + +
+ Improvements and New Features + + +

Calls to alloca in erl_marshal.c have been removed. A + static buffer is now used instead to store node names + temporarily.

+

Own Id: OTP-6331 Aux Id: seq10468

+ + +

ei_print_term interprets a list of integers with values + from 0 to 255 as a string. If the original list contains + the integer 0, this is considered terminator of the + string. This is incorrect. The function has now been + modified to not look for '\\0' in a string, but always + print all characters.

+

Own Id: OTP-6339 Aux Id: seq10492

+ + +
+
+ +
+ Erl_Interface 3.5.5.2 + +
+ Fixed Bugs and Malfunctions + + +

The combination of xeon processors with 64bit x86 + extensions and a 32bit linux could cause ei_decode_long + and ei_decode_longlong to fail for the value LONG_MIN and + LONGLONG_MIN. The conversion is now made more portable.

+

Own Id: OTP-6216

+ + +
+
+ +
+ Erl_Interface 3.5.5.1 + +
+ Improvements and New Features + + +

Portability enhancements.

+

Own Id: OTP-6132

+ + +
+
+ +
+ Erl_Interface 3.5.5 + +
+ Fixed Bugs and Malfunctions + + +

Different (and old) files in the + and applications would + cause build problems on the new Intel-based iMacs. + (Thanks to Sebastion Strollo.)

+

Own Id: OTP-5967

+ + +

pthread header and library mismatch on linux systems (at + least some SuSE and Debian) with both NPTL and + Linuxthreads libraries installed.

+

Own Id: OTP-5981

+ + +
+ +
+ Improvements and New Features + + +

Support for a C node to connect to an Erlang node on a + standalone host has been added.

+

Own Id: OTP-5883 Aux Id: seq10170

+ + +
+
+ +
+ Erl_interface 3.5.2 + +
+ Improvements and New Features + + +

A configuration test error caused erl_interface to be + built without support for threads. This has been + corrected.

+

Own Id: OTP-5456

+ + +
+
+ +
+ Erl_interface 3.5.1 + +
+ Improvements and New Features + + +

Changes and improvements have been made to the build and + test environment to solve problems with failing + erl_interface test cases.

+

Own Id: OTP-5295 Aux Id: OTP-5387

+ + +
+
+ +
+ Erl_interface 3.5 + +
+ Improvements and New Features + + +

Process identifiers and port identifiers have been + made more unique. Previously 18 bits were used as id in + the internal representation of process and port + identifiers. Now 28 bits are used.

+

The maximum + limit on the number of concurrently existing processes + due to the representation of pids has been increased to + 268435456 processes. The same is true for ports. This + limit will at least on a 32-bit architecture be + impossible to reach due to memory shortage.

+

NOTE: By default, the , and the + , , and + libraries are now only guaranteed to be compatible with + other Erlang/OTP components from the same release. It is + possible to set each component in compatibility mode of + an earlier release, though. See the documentation for + respective component on how to set it in compatibility + mode.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-4968 Aux Id: OTP-4196

+ + +
+
+ +
+ Erl_interface 3.4.5 + +
+ Fixed Bugs and Malfunctions + + +

Corrections for mistakes done for patch erl_605/OTP-4874.

+

Own Id: OTP-4995 Aux Id: OTP-4874

+ + +
+
+ +
+ Erl_interface 3.4.4 + +
+ Fixed Bugs and Malfunctions + + +

A small optimization in ei_rpc*() was added and a bug in + ei_decode_longlong() was corrected.

+

Own Id: OTP-4784

+ + +
+
+ +
+ Erl_interface 3.4.2 + +
+ Fixed Bugs and Malfunctions + + +

Strings longer than 65535 bytes were encoded wrong in + ei/erl_interface.

+

Own Id: OTP-4865 Aux Id: EABln07451

+ + +
+
+ +
+ Erl_interface 3.4.1 + +
+ Fixed Bugs and Malfunctions + + +

erl_call -a parsed erlang terms incorrectly due to a bug + in ei_format, which is now corrected.

+

Own Id: OTP-4777 Aux Id: seq8099

+ + +
+
+ + diff --git a/lib/erl_interface/doc/src/notes_history.xml b/lib/erl_interface/doc/src/notes_history.xml new file mode 100644 index 0000000000..f484f3c04e --- /dev/null +++ b/lib/erl_interface/doc/src/notes_history.xml @@ -0,0 +1,367 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Erl_Interface Release Notes History + + + + +
+ +
+ Erl_Interface 3.4 + +
+ Fixed Bugs and Malfunctions + + +

and could not + previously handle uints. This bug has now been fixed.

+

Own Id: OTP-4061 Aux Id: seq7079

+ + +

was not working correctly for floating + point arguments on some platforms. This is now corrected.

+

Own Id: OTP-4379

+ + +

did not compare the node parts of + pids, ports, and references. This has now been fixed. + Comparison between two pids, ports, or references does now + conform to the Erlang specification.

+

Own Id: OTP-4512 Aux Id: OTP-4511

+ + +
+ +
+ Improvements and New Features + + +

Erl_Interface and EI now supports 64 bit architectures.

+

Own Id: OTP-4772

+ + +

There are new functions that support the GCC and Visual + C++ 64 bit extended integer types.

+ +

Own Id: OTP-4772

+ + +

If you compile the library from source you can use the ei + library together with GMP, the GNU multi precision + library, to convert integers larger than 64 bits from and + to the external format.

+ +

Own Id: OTP-4772

+ + +

Some general code improvements where done like correcting + buffer sizes, added more error checking etc.

+

Own Id: OTP-4772

+ + +

In order to conform to the Erlang specification, + comparison between two pids was changed in the R9B + release. This change did however break a deadlock + prevention algorithm used by Mnesia during release + upgrade. Therefore, comparison between two pids has been + changed back so that R9B nodes are compatible with Erlang + nodes running pre-R9 releases.

+

Pre-R9 comparison between two pids which now is used + again: If t1 and t2 are both pids, t1 will precede t2 if + and only if either

+ + the node local id of t1 precedes the node local id + of t2, or + the node local ids of t1 and t2 are equal, and + node(t1) precedes node(t2), or + the node local ids of t1 and t2 are equal, and also + node(t1) and node(t2) are equal, and node(t1) was + created before node(t2). + +

The node local id consist of two integers; serial which + is most significant, and number.

+

The Erlang specification states: If t1 and t2 are both + refs, both PIDs, or both ports, then t1 precedes t2 if + and only if either

+ + node(t1) precedes node(t2), or + node(t1) equals node(t2) and t1 was created before + t2. + +

Note that comparisons between two refs, or two ports will + still conform to the Erlang specification.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-4715 Aux Id: OTP-4511, OTP-4512

+ + +
+
+ +
+ ErlInterface 3.3 + +
+ Improvements and New Features + + +

Erl_Interface has been rewritten extensively. The library + is now documented and supported. The old + is considered obsolete, and provided + only for backward compatibility.

+ + +

Erl_Interface is now thread-safe, and multiple C-nodes may + run from the same process.

+ + +

New functions are added for connecting and accepting + connections from ; these are documented in + .

+ + +

New functions are added for converting to and from Erlang + binary format; these are documented in .

+ + +
+
+ +
+ Erl_Interface 3.2.9 + +
+ Fixed Bugs and Malfunctions + + +

Changed back the return values from and + to 1 (as they used to be). + Incompatible with plain R7, compatible with previous + versions.

+

*** INCOMPATIBILITY with R7B ***

+

Own Id: OTP-3772

+ + +

A race-condition bug in the term allocation routines was + corrected.

+

Own Id: OTP-3809

+ + +

Erl_Interface could not be linked with pthreads.

+

Own Id: OTP-3810 Aux Id: Seq 5032

+ + +

The TCB of VxWorks processes no longer grows when + is accessed. On Pthreads platforms + the use of no longer crashes programs + using multithreading.

+

Own Id: OTP-3820

+ + +

Name clashes between Erlang emulator and Erl_Interface + on VxWorks removed.

+

Own Id: OTP-3824

+ + +
+
+ +
+ Erl_Interface 3.2.3 + +
+ Fixed Bugs and Malfunctions + + +

Memory lossage affecting pids, ports and refs fixed.

+ + +
+
+ +
+ Erl_Interface 3.2.2 + +
+ Improvements and New Features + + +

An error reporting facility has been + introduced.

+

Own Id: OTP-3641

+ + +

ETERMs are now shrunk to a more reasonable size.

+

Own Id: OTP-3648

+

+ + +
+
+ +
+ Erl_Interface 3.2.1 + +
+ Fixed Errors and Malfunctions + + +

Lists containing negative numbers were incorrectly + encoded by . This has been corrected.

+

Own Id: OTP-3535

+ + +
+
+ +
+ Erl_Interface 3.2 + +
+ Improvements and New Features + + +

The reference type has been extended from 18 bits to + 82 bits. For compatibility with older nodes, an R6 node + can send a ref to an older node; if the older node sends + it back, it has lost all but its 18 least significant + bits, but still compares equal to the original ref. + The external format has been extended to represent the new + longer refs; that means for example that binaries with + refs, produced on an R6 node, cannot be converted to a + term on an older node. + In , a function + has been added, and macros and + .

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-3140 Aux Id: OTP-3139

+ + +

The function has the problem that + a fixed buffer must be given - a larger message than + expected is simply discarded. A function + has been introduced, which + dynamically resizes the buffer given to it, if needed.

+

Own Id: OTP-3313 Aux Id: OTP-2927

+ + +
+
+ +
+ Erl_Interface 3.1.1 + +
+ Improvements and New Features + + +

is added to all the + and files in order to support + use from C++.

+

On Unix the object files are now produced with + the option to make it possible to include + them in a shared library.

+

Own Id: OTP-3138 Aux Id: Seq 1722

+ + +
+
+ +
+ Erl_Interface 3.1 + +
+ Fixed Bugs and Malfunctions + + +

A buffer overflow in was causing + C-node crashes on Linux.

+

Own Id: OTP-2743

+ + +

When decoding very long strings (more than 65535 + characters) the terminating 0 was left out.

+

Own Id: OTP-2744

+ + +

was not handshaking properly with + Erlang, causing incoming connection attempts to fail.

+

Own Id: OTP-2862

+ + +

Very large negative numbers are no longer encoded + incorrectly.

+

Own Id: OTP-2897

+ + +

Atoms could sometimes contain an unterminated string. + This is fixed.

+

Own Id: OTP-2956

+ + +

Erl_Interface now uses the SENS resolver functions if + they are available at runtime. This primarily concerns + use on the VxWorks platform.

+

Own Id: OTP-3034 Aux Id: Seq 1559

+ + +

The documentation for no longer + makes erroneous reference to the remote node.

+

Own Id: OTP-3102 Aux Id: Seq 1671

+ + +
+ +
+ Improvements and New Features + + +

Erl_Interface has been moved out of the Erlang runtime + system (ERTS) and is now a separate application. This has + implications for all users of Erl_Interface, who will + need to make changes to the Makefiles used to build + applications based on Erl_Interface. In particular, + header and library files are no longer in + . The and + directories are now located in the directory + (i.e. + the directory name is now version specific).

+

Own Id: OTP-3082

+ + +
+
+ + diff --git a/lib/erl_interface/doc/src/part.xml b/lib/erl_interface/doc/src/part.xml new file mode 100644 index 0000000000..e38b9164b8 --- /dev/null +++ b/lib/erl_interface/doc/src/part.xml @@ -0,0 +1,33 @@ + + + + +
+ + 20022009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + EI User's Guide + Gordon Beaton + + 1998-11-30 + 1.2 + part.xml +
+ + + diff --git a/lib/erl_interface/doc/src/part_erl_interface.xml b/lib/erl_interface/doc/src/part_erl_interface.xml new file mode 100644 index 0000000000..c69cc85c63 --- /dev/null +++ b/lib/erl_interface/doc/src/part_erl_interface.xml @@ -0,0 +1,33 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Erl_Interface User's Guide + Gordon Beaton + + 1998-11-30 + 1.2 + part_erl_interface.sgml +
+ + + diff --git a/lib/erl_interface/doc/src/part_notes.xml b/lib/erl_interface/doc/src/part_notes.xml new file mode 100644 index 0000000000..14c1de1d6e --- /dev/null +++ b/lib/erl_interface/doc/src/part_notes.xml @@ -0,0 +1,38 @@ + + + + +
+ + 20042009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Erl_Interface Release Notes + + + + +
+ +

Erl_Interface is a C interface library for communication + with Erlang.

+

For information about older versions, see + Release Notes History.

+ + + + diff --git a/lib/erl_interface/doc/src/part_notes_history.xml b/lib/erl_interface/doc/src/part_notes_history.xml new file mode 100644 index 0000000000..612b4a9e1e --- /dev/null +++ b/lib/erl_interface/doc/src/part_notes_history.xml @@ -0,0 +1,36 @@ + + + + +
+ + 20062009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Erl_Interface Release Notes History + + + + +
+ +

Erl_Interface is a C interface library for communication + with Erlang.

+ + + + diff --git a/lib/erl_interface/doc/src/ref_man.xml b/lib/erl_interface/doc/src/ref_man.xml new file mode 100644 index 0000000000..9ae4cf27f5 --- /dev/null +++ b/lib/erl_interface/doc/src/ref_man.xml @@ -0,0 +1,55 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + Erl_Interface Command Reference + Gordon Beaton + + 1998-11.30 + 1.2 + 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/ref_man_ei.xml b/lib/erl_interface/doc/src/ref_man_ei.xml new file mode 100644 index 0000000000..ff161f9e7f --- /dev/null +++ b/lib/erl_interface/doc/src/ref_man_ei.xml @@ -0,0 +1,47 @@ + + + + +
+ + 20022009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + EI Library Reference + Gordon Beaton + + 1998-11-30 + 1.2 + ref_man_ei.xml +
+ +

The library is a interface library for + communication with .

+ +

By default, the 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 + ei_set_compat_rel() + function on how to communicate with Erlang/OTP components from earlier + releases.

+ + + + + + + diff --git a/lib/erl_interface/doc/src/ref_man_erl_interface.xml b/lib/erl_interface/doc/src/ref_man_erl_interface.xml new file mode 100644 index 0000000000..7ffa0cfb23 --- /dev/null +++ b/lib/erl_interface/doc/src/ref_man_erl_interface.xml @@ -0,0 +1,52 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Erl_Interface Library Reference + Gordon Beaton + + 1998-11-30 + 1.2 + ref_man_erl_interface.xml +
+ +

The erl_interface library is a C interface library + for communication with Erlang.

+ +

By default, the erl_interface library is only guaranteed + to be compatible with other Erlang/OTP components from the same + release as the erl_interface library. See the documentation + of the + erl_set_compat_rel() + function 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 new file mode 100644 index 0000000000..8aeb378d95 --- /dev/null +++ b/lib/erl_interface/doc/src/registry.xml @@ -0,0 +1,611 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + registry + Gordon Beaton + Gordon Beaton + + Gordon Beaton + Gordon Beaton + 980707 + A + registry.sgml +
+ registry + 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 + Mnesia in an atomic manner, and later restoring the contents of a + 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 + + ei_reg *reg; + + +

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.

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

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

+ + + + const char *ei_reg_getsval(reg,key) + Get a string object + + ei_reg *reg; + 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. +

+

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.

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

+ + + + intei_reg_getval(reg,key,flags,v,...) + Get any object + + ei_reg *reg; + const char *key; + int flags; + 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.

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

+ + + + intei_reg_delete(reg,key) + Delete an object from the registry + + ei_reg *reg; + 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 + 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 . +

+

is the object to remove. +

+

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

+ + + + intei_reg_stat(reg,key,obuf) + Get object information + + ei_reg *reg; + const char *key; + 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: +

+ +

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.

+ + + + intei_reg_tabstat(reg,obuf) + Get registry information + + ei_reg *reg; + struct ei_reg_tabstat *obuf; + + +

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

+ +

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

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

+ + + + + diff --git a/lib/erl_interface/doc/src/warning.gif b/lib/erl_interface/doc/src/warning.gif new file mode 100644 index 0000000000..96af52360e Binary files /dev/null and b/lib/erl_interface/doc/src/warning.gif differ -- cgit v1.2.3