diff options
Diffstat (limited to 'lib/erl_interface/doc/src')
17 files changed, 230 insertions, 3439 deletions
diff --git a/lib/erl_interface/doc/src/Makefile b/lib/erl_interface/doc/src/Makefile index 03044a0ddd..95f3e77c61 100644 --- a/lib/erl_interface/doc/src/Makefile +++ b/lib/erl_interface/doc/src/Makefile @@ -36,93 +36,24 @@ 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 \ +XML_REF1_FILES = erl_call_cmd.xml +XML_REF3_FILES = ei_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 XML_CHAPTER_FILES = ei_users_guide.xml notes.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 +NO_CHUNKS=$(XML_REF3_FILES) # ---------------------------------------------------- -# 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 lcnt: - -clean clean_docs clean_tex: - rm -rf $(HTMLDIR)/* - rm -rf $(XMLDIR) - 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: +include $(ERL_TOP)/make/doc.mk diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml index 70af5642da..232871e864 100644 --- a/lib/erl_interface/doc/src/ei.xml +++ b/lib/erl_interface/doc/src/ei.xml @@ -49,14 +49,9 @@ <p><c>ei</c> 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 <c>ei</c> - and <c>erl_interface</c> is that <c>ei</c> uses - the binary format directly when sending and receiving terms. It is also + Erlang distribution format.The <c>ei</c> library is thread safe, and using threads, one process can handle multiple - C-nodes. The <c>erl_interface</c> library is built on top of - <c>ei</c>, but of legacy reasons, it does not allow for - multiple C-nodes. In general, <c>ei</c> is the preferred way - of doing C-nodes.</p> + C-nodes.</p> <p>The decode and encode functions use a buffer and an index into the buffer, which points at the point where to encode and @@ -378,22 +373,6 @@ typedef enum { </func> <func> - <name since=""><ret>int</ret><nametext>ei_decode_term(const char *buf, int *index, void *t)</nametext></name> - <fsummary>Decode a <c>ETERM</c>.</fsummary> - <desc> - <p>Decodes a term from the binary format. The term - is return in <c>t</c> as a <c>ETERM*</c>, so - <c>t</c> is actually an <c>ETERM**</c> (see - <seealso marker="erl_eterm"><c>erl_eterm</c></seealso>). - The term is later to be deallocated.</p> - <note><p>This function is deprecated as of OTP 22 and will be removed in - OTP 23 together with the old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>).</p> - </note> - </desc> - </func> - - <func> <name since=""><ret>int</ret><nametext>ei_decode_trace(const char *buf, int *index, erlang_trace *p)</nametext></name> <fsummary>Decode a trace token.</fsummary> <desc> @@ -707,22 +686,6 @@ ei_x_encode_string(&x, "Banana");</pre> the <c>ei_x_encode_string_len()</c> function.</p> </desc> </func> - - <func> - <name since=""><ret>int</ret><nametext>ei_encode_term(char *buf, int *index, void *t)</nametext></name> - <name since=""><ret>int</ret><nametext>ei_x_encode_term(ei_x_buff* x, void *t)</nametext></name> - <fsummary>Encode an <c>erl_interface</c> term.</fsummary> - <desc> - <p>Encodes an <c>ETERM</c>, as obtained from - <c>erl_interface</c>. Parameter <c>t</c> is - actually an <c>ETERM</c> pointer. This function - does not free the <c>ETERM</c>.</p> - <note><p>These functions are deprecated as of OTP 22 and will be removed in - OTP 23 together with the old legacy <c>erl_interface</c> library - (functions with prefix <c>erl_</c>).</p> - </note> - </desc> - </func> <func> <name since=""><ret>int</ret><nametext>ei_encode_trace(char *buf, int *index, const erlang_trace *p)</nametext></name> <name since=""><ret>int</ret><nametext>ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)</nametext></name> @@ -806,11 +769,7 @@ ei_encode_tuple_header(buf, &i, 0);</pre> <desc> <p>Initialize the <c>ei</c> library. This function should be called once (and only once) before calling any other functionality in the <c>ei</c> - library. However, note the exception below.</p> - <p>If the <c>ei</c> library is used together with the <c>erl_interface</c> - library, this function should <em>not</em> be called directly. It will be - called by the <c>erl_init()</c> function which should be used to initialize - the combination of the two libraries instead.</p> + library.</p> <p>On success zero is returned. On failure a posix error code is returned.</p> </desc> </func> @@ -990,8 +949,4 @@ encodes the tuple {numbers,12,3.14159}</pre> </list> </section> - <section> - <title>See Also</title> - <p><seealso marker="erl_eterm"><c>erl_eterm</c></seealso></p> - </section> </cref> diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index 795f1249b3..06fe9d1960 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -422,6 +422,8 @@ typedef struct { <func> <name since=""><ret>int</ret><nametext>ei_connect(ei_cnode* ec, char *nodename)</nametext></name> <name since=""><ret>int</ret><nametext>ei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename)</nametext></name> + <name since="OTP @OTP-16251@"><ret>int</ret><nametext>ei_connect_host_port(ei_cnode* ec, char *hostname, int port)</nametext></name> + <name since="OTP @OTP-16251@"><ret>int</ret><nametext>ei_xconnect_host_port(ei_cnode* ec, Erl_IpAddr adr, int port)</nametext></name> <fsummary>Establish a connection to an Erlang node.</fsummary> <desc> <p>Sets up a connection to an Erlang node.</p> @@ -429,13 +431,21 @@ typedef struct { remote host and the alive name of the remote node to be specified. <c>ei_connect()</c> provides an alternative interface and determines the information from the node name - provided.</p> + provided. The <c>ei_xconnect_host_port()</c> function provides + yet another alternative that will work even if there is no + EPMD instance on the host where the remote node is running. The + <c>ei_xconnect_host_port()</c> function requires the IP + address and port of the remote node to be specified. + The <c>ei_connect_host_port()</c> function is an alternative + to <c>ei_xconnect_host_port()</c> that lets the user specify + a hostname instead of an IP address.</p> <list type="bulleted"> - <item><c>addr</c> is the 32-bit IP address of the remote + <item><c>adr</c> is the 32-bit IP address of the remote host.</item> <item><c>alive</c> is the alivename of the remote node. </item> <item><c>node</c> is the name of the remote node.</item> + <item><c>port</c> is the port number of the remote node.</item> </list> <p>These functions return an open file descriptor on success, or a negative value indicating that an error occurred. In the latter @@ -571,13 +581,16 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { <func> <name since=""><ret>int</ret><nametext>ei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms)</nametext></name> <name since=""><ret>int</ret><nametext>ei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms)</nametext></name> + <name since="OTP @OTP-16251@"><ret>int</ret><nametext>ei_connect_host_port_tmo(ei_cnode* ec, char *hostname, int port, unsigned ms)</nametext></name> + <name since="OTP @OTP-16251@"><ret>int</ret><nametext>ei_xconnect_host_port_tmo(ei_cnode* ec, Erl_IpAddr adr, int port, unsigned ms)</nametext></name> <fsummary>Establish a connection to an Erlang node with optional time-out.</fsummary> <desc> - <p>Equivalent to - <c>ei_connect</c> and <c>ei_xconnect</c> with an optional time-out - argument, see the description at the beginning of this manual - page.</p> + <p>Equivalent to <c>ei_connect</c>, <c>ei_xconnect</c>, + <c>ei_connect_host_port</c> and + <c>ei_xconnect_host_port</c> with an optional time-out + argument, see the description at the beginning of this manual + page.</p> </desc> </func> diff --git a/lib/erl_interface/doc/src/erl_global.xml b/lib/erl_interface/doc/src/ei_global.xml index 39085b46f0..4c6b94f7dd 100644 --- a/lib/erl_interface/doc/src/erl_global.xml +++ b/lib/erl_interface/doc/src/ei_global.xml @@ -22,7 +22,7 @@ </legalnotice> - <title>erl_global</title> + <title>ei_global</title> <prepared>Gordon Beaton</prepared> <responsible>Gordon Beaton</responsible> <docno></docno> @@ -30,20 +30,14 @@ <checked>Gordon Beaton</checked> <date>1998-07-03</date> <rev>A</rev> - <file>erl_global.xml</file> + <file>ei_global.xml</file> </header> - <lib>erl_global</lib> + <lib>ei_global</lib> <libsummary>Access globally registered names.</libsummary> <description> <note><p>The support for VxWorks is deprecated as of OTP 22, and will be removed in OTP 23.</p></note> - <note><p>The old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>) is deprecated as of OTP 22, and will be - removed in OTP 23. This does not apply to the <c>ei</c> - library. Reasonably new <c>gcc</c> compilers will issue deprecation - warnings. In order to disable these warnings, define the macro - <c>EI_NO_DEPR_WARN</c>.</p></note> - + <p>This module provides support for registering, looking up, and unregistering names in the <c>global</c> module. For more information, see @@ -57,15 +51,17 @@ <funcs> <func> - <name since=""><ret>char **</ret><nametext>erl_global_names(fd,count)</nametext></name> + <name since=""><ret>char **</ret><nametext>ei_global_names(ec,fd,count)</nametext></name> <fsummary>Obtain list of global names.</fsummary> <type> + <v>ei_cnode *ec;</v> <v>int fd;</v> <v>int *count;</v> </type> <desc> <p>Retrieves a list of all known global names.</p> <list type="bulleted"> + <item><c>ec</c> is the ei_cnode representing the current cnode.</item> <item><c>fd</c> is an open descriptor to an Erlang connection.</item> <item><c>count</c> is the address of an integer, or @@ -88,12 +84,12 @@ </func> <func> - <name since=""><ret>int</ret><nametext>erl_global_register(fd,name,pid)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_global_register(fd,name,pid)</nametext></name> <fsummary>Register a name in global.</fsummary> <type> <v>int fd;</v> <v>const char *name;</v> - <v>ETERM *pid;</v> + <v>erlang_pid *pid;</v> </type> <desc> <p>Registers a name in <c>global</c>.</p> @@ -112,15 +108,17 @@ </func> <func> - <name since=""><ret>int</ret><nametext>erl_global_unregister(fd,name)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_global_unregister(ec,fd,name)</nametext></name> <fsummary>Unregister a name from global.</fsummary> <type> + <v>ei_cnode *ec;</v> <v>int fd;</v> <v>const char *name;</v> </type> <desc> <p>Unregisters a name from <c>global</c>.</p> <list type="bulleted"> + <item><c>ec</c> is the ei_cnode representing the current cnode.</item> <item><c>fd</c> is an open descriptor to an Erlang connection.</item> <item><c>name</c> is the name to unregister from @@ -131,30 +129,35 @@ </func> <func> - <name since=""><ret>ETERM *</ret><nametext>erl_global_whereis(fd,name,node)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_global_whereis(ec,fd,name,pid,node)</nametext></name> <fsummary>Look up a name in global.</fsummary> <type> + <v>ei_cnode *ec;</v> <v>int fd;</v> <v>const char *name;</v> + <v>erlang_pid* pid;</v> <v>char *node;</v> </type> <desc> <p>Looks up a name in <c>global</c>.</p> <list type="bulleted"> + <item><c>ec</c> is the ei_cnode representing the current cnode.</item> <item><c>fd</c> is an open descriptor to an Erlang connection.</item> <item><c>name</c> is the name that is to be looked up in <c>global</c>.</item> </list> + <p>The <c>pid</c> parameter is a pointer to a + <c>erlang_pid</c> that the function will update with the pid associated + with the global name, if successful.</p> <p>If <c>node</c> is not <c>NULL</c>, it is a pointer to a buffer where the function can fill in the name of the node where <c>name</c> is found. <c>node</c> can be - passed directly to <c>erl_connect()</c> if necessary.</p> - <p>On success, the function returns an Erlang pid containing the address - of the specified name, and the node is initialized to + passed directly to <c>ei_connect()</c> if necessary.</p> + <p>On success, the function returns 0, updates the <c>erlang_pid</c> + pointed to by the pid parameter, and the <c>node</c> parameter is initialized to the node name where <c>name</c> is found. On failure, - <c>NULL</c> is returned and <c>node</c> is not - modified.</p> + a negative number is returned.</p> </desc> </func> </funcs> diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index 7ca10d1a99..4ce8b9237f 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.xml @@ -37,12 +37,6 @@ <title>Deprecation and Removal</title> <note><p>The support for VxWorks is deprecated as of OTP 22, and will be removed in OTP 23.</p></note> - <note><p>The old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>) is deprecated as of OTP 22, and will be - removed in OTP 23. This does not apply to the <c>ei</c> - library. Reasonably new <c>gcc</c> compilers will issue deprecation - warnings. In order to disable these warnings, define the macro - <c>EI_NO_DEPR_WARN</c>.</p></note> </section> <section> @@ -60,14 +54,12 @@ <seealso marker="mnesia:mnesia">Mnesia</seealso></item> </list> <note> - <p>By default, the <c>Erl_Interface</c> libraries are only guaranteed + <p>By default, the <c>Erl_Interface</c> library is only guaranteed to be compatible with other Erlang/OTP components from the same release as the libraries themselves. For information about how to communicate with Erlang/OTP components from earlier releases, see function <seealso marker="ei#ei_set_compat_rel"> - <c>ei:ei_set_compat_rel</c></seealso> and - <seealso marker="erl_eterm#erl_set_compat_rel"> - <c>erl_eterm:erl_set_compat_rel</c></seealso>.</p> + <c>ei_set_compat_rel</c></seealso>.</p> </note> <section> @@ -98,10 +90,9 @@ <section> <title>Compiling and Linking Your Code</title> <p>To use any of the <c>Erl_Interface</c> functions, include the - following lines in your code:</p> + following line in your code:</p> <code type="none"><![CDATA[ -#include "erl_interface.h" #include "ei.h" ]]></code> <p>Determine where the top directory of your OTP installation is. @@ -114,7 +105,7 @@ Eshell V4.7.4 (abort with ^G) /usr/local/otp ]]></code> <p>To compile your code, ensure that your C compiler knows where - to find <c>erl_interface.h</c> by specifying an appropriate + to find <c>ei.h</c> by specifying an appropriate <c>-I</c> argument on the command line, or add it to the <c>CFLAGS</c> definition in your <c>Makefile</c>. The correct value for this path is @@ -140,11 +131,9 @@ $ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c ]]></code> <p>When linking:</p> <list type="bulleted"> - <item>Specify the path to <c>liberl_interface.a</c> and - <c>libei.a</c> with + <item>Specify the path to <c>libei.a</c> with <c>-L$OTPROOT/lib/erl_interface-3.2.3/lib</c>.</item> - <item>Specify the name of the libraries with - <c>-lerl_interface -lei</c>.</item> + <item>Specify the name of the library with <c>-lei</c>.</item> </list> <p>Do this on the command line or add the flags to the @@ -155,7 +144,7 @@ $ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c ]]></code> <code type="none"><![CDATA[ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ - lib myprog.o -lerl_interface -lei -o myprog ]]></code> + lib myprog.o -lei -o myprog ]]></code> <p>On some systems it can be necessary to link with some more libraries (for example, <c>libnsl.a</c> and @@ -174,19 +163,11 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ </section> <section> - <title>Initializing the Libraries</title> + <title>Initializing the Library</title> <p> - Before calling any of the other functions in the <c>erl_interface</c> - and <c>ei</c> libraries, call <c>erl_init()</c> exactly once to initialize - both libraries. - <c>erl_init()</c> takes two arguments. However, the arguments - are no longer used by <c>erl_interface</c> and are therefore to be - specified as <c>erl_init(NULL,0)</c>. - </p> - <p> - If you only use the <c>ei</c> library, instead initialize it by calling - <c>ei_init()</c> exactly once before calling any other functions in - the <c>ei</c> library. + Before calling any of the other functions in the library, + initialize it by calling + <c>ei_init()</c> exactly once. </p> </section> @@ -199,187 +180,93 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ <p>The <c>Erl_Interface</c> library supports this activity. It has several C functions that create and manipulate Erlang data - structures. The library also contains an encode and a decode function. - The following example shows how to create and encode an Erlang tuple - <c>{tobbe,3928}</c>:</p> + structures. The following example shows how to create and encode + an Erlang tuple <c>{tobbe,3928}</c>:</p> <code type="none"><![CDATA[ -ETERM *arr[2], *tuple; -char buf[BUFSIZ]; -int i; - -arr[0] = erl_mk_atom("tobbe"); -arr[1] = erl_mk_integer(3928); -tuple = erl_mk_tuple(arr, 2); -i = erl_encode(tuple, buf); ]]></code> - - <p>Alternatively, you can use <c>erl_send()</c> and - <c>erl_receive_msg</c>, which handle the encoding and - decoding of messages transparently.</p> - - <p>For a complete description, see the following modules:</p> - <list type="bulleted"> - <item><seealso marker="erl_eterm"><c>erl_eterm</c></seealso> - for creating Erlang terms</item> - <item><seealso marker="erl_marshal"><c>erl_marshal</c></seealso> - for encoding and decoding routines</item> - </list> +ei_x_buff buf; +ei_x_new(&buf); +int i = 0; +ei_x_encode_tuple_header(&buf, 2); +ei_x_encode_atom(&buf, "tobbe"); +ei_x_encode_long(&buf, 3928); ]]></code> + + <p>For a complete description, see the + <seealso marker="ei"><c>ei</c></seealso> module.</p> </section> <section> <marker id="building_terms_and_patterns"/> - <title>Building Terms and Patterns</title> + <title>Building Terms</title> <p>The previous example can be simplified by using the - <seealso marker="erl_format"><c>erl_format</c></seealso> module + <seealso marker="ei#ei_x_format_wo_ver"><c>ei_x_format_wo_ver</c></seealso> function to create an Erlang term:</p> <code type="none"><![CDATA[ -ETERM *ep; -ep = erl_format("{~a,~i}", "tobbe", 3928); ]]></code> +ei_x_buff buf; +ei_x_new(&buf); +ei_x_format_wo_ver(&buf, "{~a,~i}", "tobbe", 3928); ]]></code> - <p>For a complete description of the different format directives, see - the <seealso marker="erl_format"><c>erl_format</c></seealso> module.</p> + <p>For a complete description of the different format directives, see the + the <seealso marker="ei#ei_x_format_wo_ver"><c>ei_x_format_wo_ver</c></seealso> function.</p> <p>The following example is more complex:</p> <code type="none"><![CDATA[ -ETERM *ep; -ep = erl_format("[{name,~a},{age,~i},{data,~w}]", - "madonna", - 21, - erl_format("[{adr,~s,~i}]", "E-street", 42)); -erl_free_compound(ep); ]]></code> +ei_x_buff buf; +int i = 0; +ei_x_new(&buf); +ei_x_format_wo_ver(&buf, + "[{name,~a},{age,~i},{data,[{adr,~s,~i}]}]", + "madonna", + 21, + "E-street", 42); +ei_print_term(stdout, buf.buff, &i); +ei_x_free(&buf); ]]></code> <p>As in the previous examples, it is your responsibility to free the memory allocated for Erlang terms. In this example, - <c>erl_free_compound()</c> ensures that the complete term - pointed to by <c>ep</c> is released. This is necessary - because the pointer from the second call to <c>erl_format</c> is lost.</p> - - <p>The following example shows a slightly different solution:</p> - - <code type="none"><![CDATA[ -ETERM *ep,*ep2; -ep2 = erl_format("[{adr,~s,~i}]","E-street",42); -ep = erl_format("[{name,~a},{age,~i},{data,~w}]", - "madonna", 21, ep2); -erl_free_term(ep); -erl_free_term(ep2); ]]></code> - - <p>In this case, you free the two terms independently. The order in - which you free the terms <c>ep</c> and <c>ep2</c> - is not important, - because the <c>Erl_Interface</c> library uses reference counting to - determine when it is safe to remove objects.</p> - - <p>If you are unsure whether you have freed the terms properly, you - can use the following function to see the status of the fixed term - allocator:</p> - - <code type="none"><![CDATA[ -long allocated, freed; - -erl_eterm_statistics(&allocated,&freed); -printf("currently allocated blocks: %ld\n",allocated); -printf("length of freelist: %ld\n",freed); - -/* really free the freelist */ -erl_eterm_release(); - ]]></code> - - <p>For more information, see the - <seealso marker="erl_malloc"><c>erl_malloc</c></seealso> module.</p> - </section> - - <section> - <title>Pattern Matching</title> - <p>An Erlang pattern is a term that can contain unbound variables or - <c>"do not care"</c> 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:</p> - - <code type="none"><![CDATA[ -ETERM *pattern; -pattern = erl_format("{madonna,Age,_}"); ]]></code> - - <p>The <seealso marker="erl_format#erl_match"> - <c>erl_format:erl_match</c></seealso> function - performs pattern matching. It takes a - pattern and a term and tries to match them. As a side effect any unbound - variables in the pattern will be bound. In the following example, a - pattern is created with a variable <c>Age</c>, which is included at two - positions in the tuple. The pattern match is performed as follows:</p> - - <list type="bulleted"> - <item> - <p><c>erl_match</c> binds the contents of <c>Age</c> to <c>21</c> - the first time it reaches the variable.</p> - </item> - <item> - <p>The second occurrence of <c>Age</c> causes a test for - equality between the terms, as <c>Age</c> is already bound to - <c>21</c>. As <c>Age</c> is bound to <c>21</c>, the equality test - succeeds and the match continues until the end of the pattern.</p> - </item> - <item> - <p>If the end of the pattern is reached, the match succeeds and you - can retrieve the contents of the variable.</p> - </item> - </list> - - <code type="none"><![CDATA[ -ETERM *pattern,*term; -pattern = erl_format("{madonna,Age,Age}"); -term = erl_format("{madonna,21,21}"); -if (erl_match(pattern, term)) { - fprintf(stderr, "Yes, they matched: Age = "); - ep = erl_var_content(pattern, "Age"); - erl_print_term(stderr, ep); - fprintf(stderr,"\n"); - erl_free_term(ep); -} -erl_free_term(pattern); -erl_free_term(term); ]]></code> + <c>ei_x_free()</c> ensures that the data + pointed to by <c>buf</c> is released.</p> - <p>For more information, see the - <seealso marker="erl_format#erl_match"> - <c>erl_format:erl_match</c></seealso> function.</p> </section> <section> <title>Connecting to a Distributed Erlang Node</title> <p>To connect to a distributed Erlang node, you must first - initialize the connection routine with - <seealso marker="erl_connect#erl_connect_init"> - <c>erl_connect:erl_connect_init</c></seealso>, - which stores information, such as the hostname, node name, and IP - address for later use:</p> + initialize the connection routine with one of the + <seealso marker="ei_connect#ei_connect_init"> + <c>ei_connect_init_*</c></seealso> functions, + which stores information, such as the hostname, and node name + for later use:</p> <code type="none"><![CDATA[ int identification_number = 99; int creation=1; char *cookie="a secret cookie string"; /* An example */ -erl_connect_init(identification_number, cookie, creation); ]]></code> +const char* node_name = "einode@durin"; +const char *cookie = NULL; +short creation = time(NULL) + 1; +ei_cnode ec; +ei_connect_init(ec, + node_name, + cookie, + creation); ]]></code> <p>For more information, see the - <seealso marker="erl_connect"><c>erl_connect</c></seealso> module.</p> + <seealso marker="ei_connect"><c>ei_connect</c></seealso> module.</p> <p>After initialization, you set up the connection to the Erlang node. - To specify the Erlang node you want to connect to, use - <c>erl_connect()</c>. The following example sets up the + To specify the Erlang node you want to connect to, use the + <c>ei_connect_*()</c> family of functions. The following example sets up the connection and is to result in a valid socket file descriptor:</p> <code type="none"><![CDATA[ int sockfd; -char *nodename="xyz@chivas.du.etx.ericsson.se"; /* An example */ -if ((sockfd = erl_connect(nodename)) < 0) - erl_err_quit("ERROR: erl_connect failed"); ]]></code> +const char* node_name = "einode@durin"; /* An example */ +if ((sockfd = ei_connect(ec, nodename)) < 0) + fprintf(stderr, "ERROR: ei_connect failed"); ]]></code> - <p><c>erl_err_quit()</c> prints the specified string and - terminates the program. For more information, see the - <seealso marker="erl_error"><c>erl_error</c></seealso> module.</p> </section> <section> @@ -394,7 +281,7 @@ if ((sockfd = erl_connect(nodename)) < 0) correct port number to connect to.</p> <p>When you use - <seealso marker="erl_connect"><c>erl_connect</c></seealso> + <seealso marker="ei_connect"><c>ei_connect</c></seealso> to connect to an Erlang node, a connection is first made to <c>epmd</c> and, if the node is known, a connection is then made to the Erlang node.</p> @@ -409,7 +296,7 @@ if ((sockfd = erl_connect(nodename)) < 0) <code type="none"><![CDATA[ int pub; -pub = erl_publish(port); ]]></code> +pub = ei_publish(ec, port); ]]></code> <p><c>pub</c> is a file descriptor now connected to <c>epmd</c>. <c>epmd</c> @@ -424,17 +311,9 @@ pub = erl_publish(port); ]]></code> failed. If a node has failed in this way, <c>epmd</c> prevents you from registering a new node with the old name, as it thinks that the old - name is still in use. In this case, you must unregister the name - explicitly:</p> + name is still in use. In this case, you must close the port + explicitly</p> - <code type="none"><![CDATA[ -erl_unpublish(node); ]]></code> - - <p>This causes <c>epmd</c> to close the connection from the - far end. Notice - that if the name was in fact still in use by a node, the results of - this operation are unpredictable. Also, doing this does not cause the - local end of the connection to close, so resources can be consumed.</p> </section> <section> @@ -442,10 +321,10 @@ erl_unpublish(node); ]]></code> <p>Use one of the following two functions to send messages:</p> <list type="bulleted"> - <item><seealso marker="erl_connect#erl_send"> - <c>erl_connect:erl_send</c></seealso></item> - <item><seealso marker="erl_connect#erl_reg_send"> - <c>erl_connect:erl_reg_send</c></seealso></item> + <item><seealso marker="ei_connect#ei_send"> + <c>ei_send</c></seealso></item> + <item><seealso marker="ei_connect#ei_reg_send"> + <c>ei_reg_send</c></seealso></item> </list> <p>As in Erlang, messages can be sent to a @@ -456,82 +335,79 @@ erl_unpublish(node); ]]></code> <p>Use one of the following two functions to receive messages:</p> <list type="bulleted"> - <item><seealso marker="erl_connect#erl_receive"> - <c>erl_connect:erl_receive</c></seealso></item> - <item><seealso marker="erl_connect#erl_receive_msg"> - <c>erl_connect:erl_receive_msg</c></seealso></item> + <item><seealso marker="ei_connect#ei_receive"> + <c>ei_receive</c></seealso></item> + <item><seealso marker="ei_connect#ei_receive_msg"> + <c>ei_receive_msg</c></seealso></item> </list> - <p><c>erl_receive()</c> receives the message into a buffer, - while <c>erl_receive_msg()</c> decodes the message into an - Erlang term.</p> - <section> <title>Example of Sending Messages</title> <p>In the following example, <c>{Pid, hello_world}</c> is - sent to a registered process <c>my_server</c>. The message - is encoded by <c>erl_send()</c>:</p> + sent to a registered process <c>my_server</c>:</p> <code type="none"><![CDATA[ -extern const char *erl_thisnodename(void); -extern short erl_thiscreation(void); -#define SELF(fd) erl_mk_pid(erl_thisnodename(),fd,0,erl_thiscreation()) -ETERM *arr[2], *emsg; -int sockfd, creation=1; - -arr[0] = SELF(sockfd); -arr[1] = erl_mk_atom("Hello world"); -emsg = erl_mk_tuple(arr, 2); - -erl_reg_send(sockfd, "my_server", emsg); -erl_free_term(emsg); ]]></code> +ei_x_buff buf; +ei_x_new_with_version(&buf); + +ei_x_encode_tuple_header(&buf, 2); +ei_x_encode_pid(&buf, ei_self(ec)); +ei_x_encode_atom(&buf, "Hello world"); + +ei_reg_send(ec,fd,"my_server",buf,buf.index);]]></code> <p>The first element of the tuple that is sent is your own pid. This enables <c>my_server</c> to reply. For more information about the primitives, see the - <seealso marker="erl_connect"><c>erl_connect</c></seealso> module.</p> + <seealso marker="ei_connect"><c>ei_connect</c></seealso> module.</p> </section> <section> <title>Example of Receiving Messages</title> - <p>In this example, <c>{Pid, Something}</c> is received. The - received pid is then used to return - <c>{goodbye,Pid}</c>.</p> - - <code type="none"><![CDATA[ -ETERM *arr[2], *answer; -int sockfd,rc; -char buf[BUFSIZE]; -ErlMessage emsg; - -if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) { - arr[0] = erl_mk_atom("goodbye"); - arr[1] = erl_element(1, emsg.msg); - answer = erl_mk_tuple(arr, 2); - erl_send(sockfd, arr[1], answer); - erl_free_term(answer); - erl_free_term(emsg.msg); - erl_free_term(emsg.to); -} ]]></code> + <p>In this example, <c>{Pid, Something}</c> is received.</p> + + <code type="none"><![CDATA[ +erlang_msg msg; +int index = 0; +int version; +int arity = 0; +erlang_pid pid; +ei_x_buff buf; +ei_x_new(&buf); +for (;;) { + int got = ei_xreceive_msg(fd, &msg, &x); + if (got == ERL_TICK) + continue; + if (got == ERL_ERROR) { + fprintf(stderr, "ei_xreceive_msg, got==%d", got); + exit(1); + } + break; +} +ei_decode_version(buf.buff, &index, &version); +ei_decode_tuple_header(buf.buff, &index, &arity); +if (arity != 2) { + fprintf(stderr, "got wrong message"); + exit(1); +} +ei_decode_pid(buf.buff, &index, &pid); ]]></code> <p>To provide robustness, a distributed Erlang node occasionally polls all its connected neighbors in an attempt to detect failed nodes or communication links. A node that receives such a message is expected to respond immediately with an <c>ERL_TICK</c> message. This is done automatically by - <c>erl_receive()</c>. However, when this has occurred, - <c>erl_receive</c> returns <c>ERL_TICK</c> to + <c>ei_xreceive_msg()</c>. However, when this has occurred, + <c>ei_xreceive_msg</c> returns <c>ERL_TICK</c> to the caller without storing a message into the - <c>ErlMessage</c> structure.</p> + <c>erlang_msg</c> structure.</p> <p>When a message has been received, it is the caller's responsibility - to free the received message <c>emsg.msg</c> and - <c>emsg.to</c> or <c>emsg.from</c>, - depending on the type of message received.</p> + to free the received message.</p> <p>For more information, see the - <seealso marker="erl_connect"><c>erl_connect</c></seealso> and - <seealso marker="erl_eterm"><c>erl_eterm</c></seealso> modules.</p> + <seealso marker="ei_connect"><c>ei_connect</c></seealso> and + <seealso marker="ei"><c>ei</c></seealso> modules.</p> </section> </section> @@ -542,31 +418,30 @@ if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) { included in a function call at a remote node and is called a remote procedure call.</p> - <p>The following example shows how the - <c>Erl_Interface</c> library supports remote procedure calls:</p> + <p>The following example checks if a specific Erlang process is alive:</p> <code type="none"><![CDATA[ -char modname[]=THE_MODNAME; -ETERM *reply,*ep; -ep = erl_format("[~a,[]]", modname); -if (!(reply = erl_rpc(fd, "c", "c", ep))) - erl_err_msg("<ERROR> when compiling file: %s.erl !\n", modname); -erl_free_term(ep); -ep = erl_format("{ok,_}"); -if (!erl_match(ep, reply)) - erl_err_msg("<ERROR> compiler errors !\n"); -erl_free_term(ep); -erl_free_term(reply); ]]></code> - - <p><c>c:c/1</c> is called to compile the specified module on - the remote node. <c>erl_match()</c> checks that the - compilation was - successful by testing for the expected <c>ok</c>.</p> - - <p>For more information about <c>erl_rpc()</c> and its - companions <c>erl_rpc_to()</c> and - <c>erl_rpc_from()</c>, see the - <seealso marker="erl_connect"><c>erl_connect</c></seealso> module.</p> +int index = 0, is_alive; +ei_x_buff args, result; + +ei_x_new(&result); +ei_x_new(&args); +ei_x_encode_list_header(&args, 1); +ei_x_encode_pid(&args, &check_pid); +ei_x_encode_empty_list(&args); + +if (ei_rpc(&ec, fd, "erlang", "is_process_alive", + args.buff, args.index, &result) < 0) + handle_error(); + +if (ei_decode_version(result.buff, &index) < 0 + || ei_decode_bool(result.buff, &index, &is_alive) < 0) + handle_error(); ]]></code> + + <p>For more information about <c>ei_rpc()</c> and its + companions <c>ei_rpc_to()</c> and + <c>ei_rpc_from()</c>, see the + <seealso marker="ei_connect"><c>ei_connect</c></seealso> module.</p> </section> <section> @@ -590,7 +465,7 @@ char **names; int count; int i; -names = erl_global_names(fd,&count); +names = ei_global_names(ec,fd,&count); if (names) for (i=0; i<count; i++) @@ -598,8 +473,8 @@ if (names) free(names); ]]></code> - <p><seealso marker="erl_global#erl_global_names"> - <c>erl_global:erl_global_names</c></seealso> + <p><seealso marker="ei_global#ei_global_names"> + <c>ei_global_names</c></seealso> allocates and returns a buffer containing all the names known to the <c>global</c> module in <c>Kernel</c>. <c>count</c> is initialized to @@ -608,7 +483,7 @@ free(names); ]]></code> <c>count</c> to determine when the last name is reached.</p> <p>It is the caller's responsibility to free the array. - <c>erl_global_names</c> allocates the array and all the strings + <c>ei_global_names</c> allocates the array and all the strings using a single call to <c>malloc()</c>, so <c>free(names)</c> is all that is necessary.</p> @@ -617,16 +492,18 @@ free(names); ]]></code> <code type="none"><![CDATA[ ETERM *pid; char node[256]; +erlang_pid the_pid; -pid = erl_global_whereis(fd,"schedule",node); ]]></code> +if (ei_global_whereis(ec,fd,"schedule",&the_pid,node) < 0) + fprintf(stderr, "ei_global_whereis error\n"); ]]></code> <p>If <c>"schedule"</c> is known to the <c>global</c> module in <c>Kernel</c>, an Erlang pid is - returned that can be used to send messages to the schedule service. + written to the_pid. This pid that can be used to send messages to the schedule service. Also, <c>node</c> is initialized to contain the name of the node where the service is registered, so that you can make a connection to it by simply passing the variable to - <seealso marker="erl_connect"><c>erl_connect</c></seealso>.</p> + <seealso marker="ei_connect"><c>ei_connect</c></seealso>.</p> <p>Before registering a name, you should already have registered your port number with <c>epmd</c>. This is not strictly necessary, @@ -634,30 +511,27 @@ pid = erl_global_whereis(fd,"schedule",node); ]]></code> neglect to do so, then other nodes wishing to communicate with your service cannot find or connect to your process.</p> - <p>Create a pid that Erlang processes can use to communicate with your + <p>Create a name that Erlang processes can use to communicate with your service:</p> <code type="none"><![CDATA[ -ETERM *pid; - -pid = erl_mk_pid(thisnode,14,0,0); -erl_global_register(fd,servicename,pid); ]]></code> +ei_global_register(fd,servicename,ei_self(ec)); ]]></code> <p>After registering the name, use - <seealso marker="erl_connect#erl_accept"> - <c>erl_connect:erl_accept</c></seealso> + <seealso marker="ei_connect#ei_accept"> + <c>ei_accept</c></seealso> to wait for incoming connections.</p> <note> <p>Remember to free <c>pid</c> later with - <seealso marker="erl_malloc#erl_free_term"> - <c>erl_malloc:erl_free_term</c></seealso>.</p> + <seealso marker="ei#ei_x_free"> + <c>ei_x_free</c></seealso>.</p> </note> <p>To unregister a name:</p> <code type="none"><![CDATA[ -erl_global_unregister(fd,servicename); ]]></code> +ei_global_unregister(ec,fd,servicename); ]]></code> </section> <section> @@ -755,7 +629,7 @@ ei_reg_close(reg); ]]></code> <p>The contents of a registry can be backed up to <seealso marker="mnesia:mnesia"><c>Mnesia</c></seealso> on a "nearby" Erlang node. You must provide an open connection to the Erlang node - (see <seealso marker="erl_connect"><c>erl_connect</c></seealso>). + (see <seealso marker="ei_connect"><c>ei_connect</c></seealso>). Also, <c>Mnesia</c> 3.0 or later must be running on the Erlang node before the backup is initiated:</p> @@ -818,9 +692,9 @@ ei_reg_restore(fd, reg, "mtab"); ]]></code> <c>Mnesia</c> backup of the registry contents. This can be avoided if you mark the object as dirty after any such changes with <seealso marker="registry#ei_reg_markdirty"> - <c>registry:ei_reg_markdirty</c></seealso>, or pass appropriate flags to + <c>ei_reg_markdirty</c></seealso>, or pass appropriate flags to <seealso marker="registry#ei_reg_dump"> - <c>registry:ei_reg_dump</c></seealso>.</p> + <c>ei_reg_dump</c></seealso>.</p> </section> </section> </chapter> diff --git a/lib/erl_interface/doc/src/erl_call.xml b/lib/erl_interface/doc/src/erl_call_cmd.xml index 73b9b13e4d..91cb9dbd32 100644 --- a/lib/erl_interface/doc/src/erl_call.xml +++ b/lib/erl_interface/doc/src/erl_call_cmd.xml @@ -78,6 +78,22 @@ <c>Fun</c>, and <c>Args</c> in a manner dependent on the behavior of your command shell.</p> </item> + <tag><c>-address [Hostname:]Port</c></tag> + <item> + <p>(One of <c>-n</c>, <c>-name</c>, <c>-sname</c> or + <c>-address</c> is required.) <c>Hostname</c> is the + hostname of the machine that is running the node that + <c>erl_call</c> shall communicate with. The default + hostname is the hostname of the local machine. <c>Port</c> + is the port number of the node that <c>erl_call</c> shall + communicate with. The <c>-address</c> flag cannot be + combined with any of the flags <c>-n</c>, <c>-name</c>, + <c>-sname</c> or <c>-s</c>.</p> + <p>The <c>-address</c> flag is typically useful when one + wants to call a node that is running on machine without an + accessible <seealso marker="erts:epmd">epmd</seealso> + instance.</p> + </item> <tag><c>-c Cookie</c></tag> <item> <p>(<em>Optional.</em>) Use this option to specify a certain cookie. @@ -112,13 +128,15 @@ </item> <tag><c>-n Node</c></tag> <item> - <p>(One of <c>-n, -name, -sname</c> is required.) + <p>(One of <c>-n</c>, <c>-name</c>, <c>-sname</c> or + <c>-address</c> is required.) Has the same meaning as <c>-name</c> and can still be used for backward compatibility reasons.</p> </item> <tag><c>-name Node</c></tag> <item> - <p>(One of <c>-n, -name, -sname</c> is required.) + <p>(One of <c>-n</c>, <c>-name</c>, <c>-sname</c> or + <c>-address</c> is required.) <c>Node</c> is the name of the node to be started or communicated with. It is assumed that <c>Node</c> is started with @@ -149,7 +167,8 @@ </item> <tag><c>-sname Node</c></tag> <item> - <p>(One of <c>-n, -name, -sname</c> is required.) + <p>(One of <c>-n</c>, <c>-name</c>, <c>-sname</c> or + <c>-address</c> is required.) <c>Node</c> is the name of the node to be started or communicated with. It is assumed that <c>Node</c> is started with <c>erl -sname</c>, which means that diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml deleted file mode 100644 index 9492a82864..0000000000 --- a/lib/erl_interface/doc/src/erl_connect.xml +++ /dev/null @@ -1,662 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>1996</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>erl_connect</title> - <prepared>Torbjörn Törnkvist</prepared> - <responsible>Torbjörn Törnkvist</responsible> - <docno></docno> - <approved>Bjarne Däcker</approved> - <checked>Torbjörn Törnkvist</checked> - <date>1998-07-03</date> - <rev>A</rev> - <file>erl_connect.xml</file> - </header> - <lib>erl_connect</lib> - <libsummary>Communicate with distributed Erlang.</libsummary> - <description> - <note><p>The support for VxWorks is deprecated as of OTP 22, and - will be removed in OTP 23.</p></note> - <note><p>The old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>) is deprecated as of OTP 22, and will be - removed in OTP 23. This does not apply to the <c>ei</c> - library. Reasonably new <c>gcc</c> compilers will issue deprecation - warnings. In order to disable these warnings, define the macro - <c>EI_NO_DEPR_WARN</c>.</p></note> - - <p>This module provides support for communication between distributed - Erlang nodes and C-nodes, in a manner that is transparent to Erlang - processes.</p> - - <p>A C-node appears to Erlang as a <em>hidden node</em>. - That is, Erlang processes that know the name of the - C-node can communicate with it in a normal manner, but - the node name does not appear in the listing provided by - <seealso marker="erts:erlang#nodes/0"><c>erlang:nodes/0</c></seealso> - in <c>ERTS</c>.</p> - </description> - - <funcs> - <func> - <name since=""><ret>int</ret><nametext>erl_accept(listensock, conp)</nametext></name> - <fsummary>Accept a connection.</fsummary> - <type> - <v>int listensock;</v> - <v>ErlConnect *conp;</v> - </type> - <desc> - <p>This function is used by a server process to accept a - connection from a client process.</p> - <list type="bulleted"> - <item><c>listensock</c> is an open socket descriptor on - which <c>listen()</c> has previously been called.</item> - <item><c>conp</c> is a pointer to an - <c>ErlConnect</c> struct, described as follows:</item> - </list> - <code type="none"><![CDATA[ -typedef struct { - char ipadr[4]; - char nodename[MAXNODELEN]; -} ErlConnect; - ]]></code> - <p>On success, <c>conp</c> is filled in with the address and - node name of the connecting client and a file descriptor is - returned. On failure, <c>ERL_ERROR</c> is returned and - <c>erl_errno</c> is set to <c>EIO</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_close_connection(fd)</nametext></name> - <fsummary>Close a connection to an Erlang node.</fsummary> - <type> - <v>int fd;</v> - </type> - <desc> - <p>Closes an open connection to an Erlang node.</p> - <p><c>Fd</c> is a file descriptor obtained from - <c>erl_connect()</c> or - <c>erl_xconnect()</c>.</p> - <p>Returns <c>0</c> on success. If the call fails, a non-zero value - is returned, and the reason for the error can be obtained with the - appropriate platform-dependent call.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_connect(node)</nametext></name> - <name since=""><ret>int</ret><nametext>erl_xconnect(addr, alive)</nametext></name> - <fsummary>Establish a connection to an Erlang node.</fsummary> - <type> - <v>char *node, *alive;</v> - <v>struct in_addr *addr;</v> - </type> - <desc> - <p>Sets up a connection to an Erlang node.</p> - <p><c>erl_xconnect()</c> requires the IP address of the - remote host and the alivename of the remote node to be - specified. <c>erl_connect()</c> provides an alternative - interface, and determines the information from the node name - provided.</p> - <list type="bulleted"> - <item><c>addr</c> is the 32-bit IP address of the remote - host.</item> - <item><c>alive</c> is the alivename of the remote node. - </item> - <item><c>node</c> is the name of the remote node.</item> - </list> - <p>Returns an open file descriptor on success, otherwise a negative - value. In the latter case <c>erl_errno</c> is set to one - of:</p> - <taglist> - <tag><c>EHOSTUNREACH</c></tag> - <item>The remote host <c>node</c> is unreachable.</item> - <tag><c>ENOMEM</c></tag> - <item>No more memory is available.</item> - <tag><c>EIO</c></tag> - <item>I/O error.</item> - </taglist> - <p>Also, <c>errno</c> values from - <c>socket</c><em>(2)</em> and - <c>connect</c><em>(2)</em> - system calls can be propagated into <c>erl_errno</c>.</p> - <p><em>Example:</em></p> - <code type="none"><![CDATA[ -#define NODE "madonna@chivas.du.etx.ericsson.se" -#define ALIVE "madonna" -#define IP_ADDR "150.236.14.75" - -/*** Variant 1 ***/ -erl_connect( NODE ); - -/*** Variant 2 ***/ -struct in_addr addr; -addr = inet_addr(IP_ADDR); -erl_xconnect( &addr , ALIVE ); - ]]></code> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_connect_init(number, cookie, creation)</nametext></name> - <name since=""><ret>int</ret><nametext>erl_connect_xinit(host, alive, node, addr, cookie, creation)</nametext></name> - <fsummary>Initialize communication.</fsummary> - <type> - <v>int number;</v> - <v>char *cookie;</v> - <v>short creation;</v> - <v>char *host,*alive,*node;</v> - <v>struct in_addr *addr;</v> - </type> - <desc> - <p>Initializes the <c>erl_connect</c> module. - In particular, these functions are used to identify the name of the - C-node from which they are called. One of these functions must - be called before any of the other functions in the <c>erl_connect</c> - module are used.</p> - <p><c>erl_connect_xinit()</c> stores for later use - information about:</p> - <list type="bulleted"> - <item>Hostname of the node, <c>host</c></item> - <item>Alivename, <c>alive</c></item> - <item>Node name, <c>node</c></item> - <item>IP address, <c>addr</c></item> - <item>Cookie, <c>cookie</c></item> - <item>Creation number, <c>creation</c></item> - </list> - <p><c>erl_connect_init()</c> - provides an alternative interface that does not require as much - information from the caller. Instead, - <c>erl_connect_init()</c> - uses <c>gethostbyname()</c> to obtain default values.</p> - <p>If you use <c>erl_connect_init()</c>, your node will - have a short name, that is, it will not be fully qualified. If you - need to use fully qualified (long) names, use - <c>erl_connect_xinit()</c> instead.</p> - <list type="bulleted"> - <item> - <p><c>host</c> is the name of the host on which the node - is running.</p> - </item> - <item> - <p><c>alive</c> is the alivename of the node.</p> - </item> - <item> - <p><c>node</c> is the node name. It is to - be of the form <em>alivename@hostname</em>.</p> - </item> - <item> - <p><c>addr</c> is the 32-bit IP address of - <c>host</c>.</p> - </item> - <item> - <p><c>cookie</c> is the authorization string required - for access to the remote node. If <c>NULL</c>, the user - <c>HOME</c> directory is searched for a cookie file - <c>.erlang.cookie</c>. The path to - the home directory is retrieved from environment variable - <c>HOME</c> on Unix and from the - <c>HOMEDRIVE</c> and - <c>HOMEPATH</c> variables on Windows. For more - details, see the <seealso marker="kernel:auth"> - <c>auth</c></seealso> module in Kernel.</p> - </item> - <item> - <p><c>creation</c> helps identifying a particular - instance of a C-node. In particular, it can help prevent us from - receiving messages sent to an earlier process with the same - registered name.</p> - </item> - </list> - <p>A C-node acting as a server is assigned a creation number - when it calls <c>erl_publish()</c>.</p> - <p><c>number</c> is used by - <c>erl_connect_init()</c> to - construct the actual node name. In Example 2 - below, <em>"c17@a.DNS.name"</em> is the resulting node name.</p> - <p><em>Example 1:</em></p> - <code type="none"><![CDATA[ -struct in_addr addr; -addr = inet_addr("150.236.14.75"); -if (!erl_connect_xinit("chivas", - "madonna", - "madonna@chivas.du.etx.ericsson.se", - &addr; - "samplecookiestring..."), - 0) - erl_err_quit("<ERROR> when initializing !"); - ]]></code> - <p><em>Example 2:</em></p> - <code type="none"><![CDATA[ -if (!erl_connect_init(17, "samplecookiestring...", 0)) - erl_err_quit("<ERROR> when initializing !"); - ]]></code> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_publish(port)</nametext></name> - <fsummary>Publish a node name.</fsummary> - <type> - <v>int port;</v> - </type> - <desc> - <p>This function is used by a server process to register - with the local name server EPMD, thereby allowing - other processes to send messages by using the registered name. - Before calling this function, the process should - have called <c>bind()</c> and <c>listen()</c> - on an open socket.</p> - <p><c>port</c> is the local name to register, and is to be - the same as the port number that was previously bound to the - socket.</p> - <p>To unregister with EPMD, simply close the returned descriptor.</p> - <p>On success, a descriptor connecting the calling process to EPMD is - returned. On failure, <c>-1</c> is returned and - <c>erl_errno</c> is set to:</p> - <taglist> - <tag><c>EIO</c></tag> - <item>I/O error.</item> - </taglist> - <p>Also, <c>errno</c> values from - <c>socket</c><em>(2)</em> - and <c>connect</c><em>(2)</em> system calls can be - propagated into <c>erl_errno</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_receive(fd, bufp, bufsize)</nametext></name> - <fsummary>Receive a message.</fsummary> - <type> - <v>int fd;</v> - <v>char *bufp;</v> - <v>int bufsize;</v> - </type> - <desc> - <p>Receives a message consisting of a sequence - of bytes in the Erlang external format.</p> - <list type="bulleted"> - <item><c>fd</c> is an open descriptor to an Erlang - connection.</item> - <item><c>bufp</c> is a buffer large enough to hold the - expected message.</item> - <item><c>bufsize</c> indicates the size of - <c>bufp</c>.</item> - </list> - <p>If a <em>tick</em> occurs, that is, the Erlang node on the - other end of the connection has polled this node to see if it - is still alive, the function returns <c>ERL_TICK</c> and - no message is placed in the buffer. Also, - <c>erl_errno</c> is set to <c>EAGAIN</c>.</p> - <p>On success, the message is placed in the specified buffer - and the function returns the number of bytes actually read. On - failure, the function returns a negative value and sets - <c>erl_errno</c> to one of:</p> - <taglist> - <tag><c>EAGAIN</c></tag> - <item>Temporary error: Try again.</item> - <tag><c>EMSGSIZE</c></tag> - <item>Buffer is too small.</item> - <tag><c>EIO</c></tag> - <item>I/O error.</item> - </taglist> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_receive_msg(fd, bufp, bufsize, emsg)</nametext></name> - <fsummary>Receive and decode a message.</fsummary> - <type> - <v>int fd;</v> - <v>unsigned char *bufp;</v> - <v>int bufsize;</v> - <v>ErlMessage *emsg;</v> - </type> - <desc> - <p>Receives the message into the specified buffer - and decodes into <c>(ErlMessage *) emsg</c>.</p> - <list type="bulleted"> - <item><c>fd</c> is an open descriptor to an Erlang - connection.</item> - <item><c>bufp</c> is a buffer large enough to hold the - expected message.</item> - <item><c>bufsize</c> indicates the size of - <c>bufp</c>.</item> - <item>><c>emsg</c> is a pointer to an - <c>ErlMessage</c> structure - into which the message will be decoded. - <c>ErlMessage</c> is defined as follows:</item> - </list> - <code type="none"><![CDATA[ -typedef struct { - int type; - ETERM *msg; - ETERM *to; - ETERM *from; - char to_name[MAXREGLEN]; -} ErlMessage; - ]]></code> - <note> - <p>The definition of <c>ErlMessage</c> has changed since - earlier versions of <c>Erl_Interface</c>.</p> - </note> - <p><c>type</c> identifies the type of message, one of the - following:</p> - <taglist> - <tag><c>ERL_SEND</c></tag> - <item> - <p>An ordinary send operation has occurred and - <c>emsg->to</c> contains the pid of the recipient. - The message is in <c>emsg->msg</c>.</p> - </item> - <tag><c>ERL_REG_SEND</c></tag> - <item> - <p>A registered send operation has occurred and - <c>emsg->from</c> contains the pid of the sender. - The message is in <c>emsg->msg</c>.</p> - </item> - <tag><c>ERL_LINK</c> or <c>ERL_UNLINK</c> - </tag> - <item> - <p><c>emsg->to</c> and <c>emsg->from</c> - contain the pids of the sender and recipient of the link or - unlink. <c>emsg->msg</c> is not used.</p> - </item> - <tag><c>ERL_EXIT</c></tag> - <item> - <p>A link is broken. <c>emsg->to</c> and - <c>emsg->from</c> contain the pids of the linked - processes, and <c>emsg->msg</c> contains the reason - for the exit.</p> - </item> - </taglist> - <note> - <p>It is the caller's responsibility to release the - memory pointed to by <c>emsg->msg</c>, - <c>emsg->to</c>, and - <c>emsg->from</c>.</p> - </note> - <p>If a <em>tick</em> occurs, that is, the Erlang node on the - other end of the connection has polled this node to see if it - is still alive, the function returns <c>ERL_TICK</c> - indicating that the tick has been received and responded to, - but no message is placed in the buffer. In this case you - are to call <c>erl_receive_msg()</c> again.</p> - <p>On success, the function returns <c>ERL_MSG</c> and the - <c>Emsg</c> struct is initialized as described above, or - <c>ERL_TICK</c>, in which case no message is returned. On - failure, the function returns <c>ERL_ERROR</c> and sets - <c>erl_errno</c> to one of:</p> - <taglist> - <tag><c>EMSGSIZE</c></tag> - <item>Buffer is too small.</item> - <tag><c>ENOMEM</c></tag> - <item>No more memory is available.</item> - <tag><c>EIO</c></tag> - <item>I/O error.</item> - </taglist> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_reg_send(fd, to, msg)</nametext></name> - <fsummary>Send a message to a registered name.</fsummary> - <type> - <v>int fd;</v> - <v>char *to;</v> - <v>ETERM *msg;</v> - </type> - <desc> - <p>Sends an Erlang term to a registered process.</p> - <list type="bulleted"> - <item><c>fd</c> is an open descriptor to an Erlang - connection.</item> - <item><c>to</c> is a string containing the registered name - of the intended recipient of the message.</item> - <item><c>msg</c> is the Erlang term to be sent.</item> - </list> - <p>Returns <c>1</c> on success, otherwise <c>0</c>. In - the latter case <c>erl_errno</c> is set to one of:</p> - <taglist> - <tag><c>ENOMEM</c></tag> - <item>No more memory is available.</item> - <tag><c>EIO</c></tag> - <item>I/O error.</item> - </taglist> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_rpc(fd, mod, fun, args)</nametext></name> - <name since=""><ret>int</ret><nametext>erl_rpc_from(fd, timeout, emsg)</nametext></name> - <name since=""><ret>int</ret><nametext>erl_rpc_to(fd, mod, fun, args)</nametext></name> - <fsummary>Remote Procedure Call.</fsummary> - <type> - <v>int fd, timeout;</v> - <v>char *mod, *fun;</v> - <v>ETERM *args;</v> - <v>ErlMessage *emsg;</v> - </type> - <desc> - <p>Supports calling Erlang functions on remote nodes. - <c>erl_rpc_to()</c> sends an RPC request to a remote node - and <c>erl_rpc_from()</c> receives the results of such a - call. <c>erl_rpc()</c> combines the functionality of - these two functions by sending an RPC request and waiting for the - results. See also <seealso marker="kernel:rpc#call/4"> - <c>rpc:call/4</c></seealso> in <c>Kernel</c>.</p> - <list type="bulleted"> - <item><c>fd</c> is an open descriptor to an Erlang - connection.</item> - <item><c>timeout</c> is the maximum time (in milliseconds) - to wait for - results. To wait forever, specify <c>ERL_NO_TIMEOUT</c>. - When <c>erl_rpc()</c> calls <c>erl_rpc_from()</c>, the call will - never timeout.</item> - <item><c>mod</c> is the name of the module containing the - function to be run on the remote node.</item> - <item><c>fun</c> is the name of the function to run. - </item> - <item><c>args</c> is an Erlang list, containing the - arguments to be passed to the function.</item> - <item><c>emsg</c> is a message containing the result of - the function call.</item> - </list> - <p>The actual message returned by the RPC server - is a 2-tuple <c>{rex,Reply}</c>. If you use - <c>erl_rpc_from()</c> in your code, this is the message - you will need to parse. If you use <c>erl_rpc()</c>, the - tuple itself is parsed for you, and the message returned to your - program is the Erlang term containing <c>Reply</c> only. - Replies to RPC requests are always <c>ERL_SEND</c> messages.</p> - <note> - <p>It is the caller's responsibility to free the returned - <c>ETERM</c> structure and the memory pointed to by - <c>emsg->msg</c> and <c>emsg->to</c>.</p> - </note> - <p><c>erl_rpc()</c> returns the remote function's return - value on success, otherwise <c>NULL</c>.</p> - <p><c>erl_rpc_to()</c> returns <c>0</c> on - success, otherwise a negative number.</p> - <p><c>erl_rcp_from()</c> returns <c>ERL_MSG</c> - on success (with <c>Emsg</c> now - containing the reply tuple), otherwise one of - <c>ERL_TICK</c>, <c>ERL_TIMEOUT</c>, or - <c>ERL_ERROR</c>.</p> - <p>When failing, - all three functions set <c>erl_errno</c> to one of:</p> - <taglist> - <tag><c>ENOMEM</c></tag> - <item>No more memory is available.</item> - <tag><c>EIO</c></tag> - <item>I/O error.</item> - <tag><c>ETIMEDOUT</c></tag> - <item>Timeout has expired.</item> - <tag><c>EAGAIN</c></tag> - <item>Temporary error: Try again.</item> - </taglist> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_send(fd, to, msg)</nametext></name> - <fsummary>Send a message.</fsummary> - <type> - <v>int fd;</v> - <v>ETERM *to, *msg;</v> - </type> - <desc> - <p>Sends an Erlang term to a process.</p> - <list type="bulleted"> - <item><c>fd</c> is an open descriptor to an Erlang - connection.</item> - <item><c>to</c> is an Erlang term containing the pid of - the intended recipient of the message.</item> - <item>><c>msg</c> is the Erlang term to be sent.</item> - </list> - <p>Returns <c>1</c> on success, otherwise <c>0</c>. In - the latter case <c>erl_errno</c> is set to one of:</p> - <taglist> - <tag><c>EINVAL</c></tag> - <item>Invalid argument: <c>to</c> is not a valid Erlang - pid.</item> - <tag><c>ENOMEM</c></tag> - <item>No more memory is available.</item> - <tag><c>EIO</c></tag> - <item>I/O error.</item> - </taglist> - </desc> - </func> - - <func> - <name since=""><ret>const char *</ret><nametext>erl_thisalivename()</nametext></name> - <name since=""><ret>const char *</ret><nametext>erl_thiscookie()</nametext></name> - <name since=""><ret>short</ret><nametext>erl_thiscreation()</nametext></name> - <name since=""><ret>const char *</ret><nametext>erl_thishostname()</nametext></name> - <name since=""><ret>const char *</ret><nametext>erl_thisnodename()</nametext></name> - <fsummary>Retrieve some values.</fsummary> - <desc> - <p>Retrieves information about - the C-node. These values are initially set with - <c>erl_connect_init()</c> or - <c>erl_connect_xinit()</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_unpublish(alive)</nametext></name> - <fsummary>Forcefully unpublish a node name.</fsummary> - <type> - <v>char *alive;</v> - </type> - <desc> - <p>This function can be called by a process to unregister a - specified node from EPMD on the local host. This is, however, usually - not allowed, unless EPMD was started with flag - <c>-relaxed_command_check</c>, which it normally is not.</p> - <p>To unregister a node you have published, you should instead - close the descriptor that was returned by - <c>ei_publish()</c>.</p> - <warning> - <p>This function is deprecated and will be removed in a future - release.</p> - </warning> - <p><c>alive</c> is the name of the node to unregister, that - is, the first component of the node name, without - <c>@hostname</c>.</p> - <p>If the node was successfully unregistered from EPMD, <c>0</c> is - returned, otherwise <c>-1</c> is returned and - <c>erl_errno</c> is set to <c>EIO</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_xreceive_msg(fd, bufpp, bufsizep, emsg)</nametext></name> - <fsummary>Receive and decode a message.</fsummary> - <type> - <v>int fd;</v> - <v>unsigned char **bufpp;</v> - <v>int *bufsizep;</v> - <v>ErlMessage *emsg;</v> - </type> - <desc> - <p>Similar to <c>erl_receive_msg</c>. The difference is - that <c>erl_xreceive_msg</c> expects the buffer to - have been allocated by <c>malloc</c>, and reallocates it - if the received - message does not fit into the original buffer. Therefore - both buffer and buffer length are given as pointers; their values - can change by the call.</p> - <p>On success, the function returns <c>ERL_MSG</c> and the - <c>Emsg</c> struct is initialized as described above, or - <c>ERL_TICK</c>, in which case no message is returned. On - failure, the function returns <c>ERL_ERROR</c> and sets - <c>erl_errno</c> to one of:</p> - <taglist> - <tag><c>EMSGSIZE</c></tag> - <item>Buffer is too small.</item> - <tag><c>ENOMEM</c></tag> - <item>No more memory is available.</item> - <tag><c>EIO</c></tag> - <item>I/O error.</item> - </taglist> - </desc> - </func> - - <func> - <name since=""><ret>struct hostent *</ret><nametext>erl_gethostbyaddr(addr, length, type)</nametext></name> - <name since=""><ret>struct hostent *</ret><nametext>erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop)</nametext></name> - <name since=""><ret>struct hostent *</ret><nametext>erl_gethostbyname(name)</nametext></name> - <name since=""><ret>struct hostent *</ret><nametext>erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop)</nametext></name> - - <fsummary>Name lookup functions.</fsummary> - <type> - <v>const char *name;</v> - <v>const char *addr;</v> - <v>int length;</v> - <v>int type;</v> - <v>struct hostent *hostp;</v> - <v>char *buffer;</v> - <v>int buflen;</v> - <v>int *h_errnop;</v> - </type> - <desc> - <p>Convenience functions for some common name lookup functions.</p> - </desc> - </func> - </funcs> - - <section> - <title>Debug Information</title> - <p>If a connection attempt fails, the following can be checked:</p> - - <list type="bulleted"> - <item><c>erl_errno</c></item> - <item>That the correct cookie was used</item> - <item>That EPMD is running</item> - <item>That the remote Erlang node on the other side is running the same - version of Erlang as the <c>erl_interface</c> library</item> - </list> - </section> -</cref> diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml deleted file mode 100644 index 6fac94e442..0000000000 --- a/lib/erl_interface/doc/src/erl_error.xml +++ /dev/null @@ -1,145 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>1996</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>erl_error</title> - <prepared>Torbjörn Törnkvist</prepared> - <responsible>Torbjörn Törnkvist</responsible> - <docno></docno> - <approved>Bjarne Däcker</approved> - <checked>Torbjörn Törnkvist</checked> - <date>1996-10-14</date> - <rev>A</rev> - <file>erl_error.xml</file> - </header> - <lib>erl_error</lib> - <libsummary>Error print routines.</libsummary> - <description> - <p>This module contains some error printing routines taken - from "Advanced Programming in the UNIX Environment" - by W. Richard Stevens.</p> - - <p>These functions are all called in the same manner as - <c>printf()</c>, that is, with a string containing format - specifiers followed by a list of corresponding arguments. All output from - these functions is to <c>stderr</c>.</p> - </description> - - <funcs> - <func> - <name since=""><ret>void</ret><nametext>erl_err_msg(FormatStr, ... )</nametext></name> - <fsummary>Non-fatal error, and not system call error.</fsummary> - <type> - <v>const char *FormatStr;</v> - </type> - <desc> - <p>The message provided by the caller is printed. This - function is simply a wrapper for <c>fprintf()</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_err_quit(FormatStr, ... )</nametext></name> - <fsummary>Fatal error, but not system call error.</fsummary> - <type> - <v>const char *FormatStr;</v> - </type> - <desc> - <p>Use this function when a fatal error has occurred that - is not because of a system call. The message provided by the - caller is printed and the process terminates with exit - value <c>1</c>. This function does not return.</p> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_err_ret(FormatStr, ... )</nametext></name> - <fsummary>Non-fatal system call error.</fsummary> - <type> - <v>const char *FormatStr;</v> - </type> - <desc> - <p>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.</p> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_err_sys(FormatStr, ... )</nametext></name> - <fsummary>Fatal system call error.</fsummary> - <type> - <v>const char *FormatStr;</v> - </type> - <desc> - <p>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 exit value <c>1</c>. This function does not - return.</p> - </desc> - </func> - </funcs> - - <section> - <title>Error Reporting</title> - <p>Most functions in <c>Erl_Interface</c> report failures to the caller by - returning some otherwise meaningless value (typically - <c>NULL</c> - or a negative number). As this only tells you that things did not - go well, examine the error code in <c>erl_errno</c> if you - want to find out more about the failure.</p> - </section> - - <funcs> - <func> - <name since=""><ret>volatile int</ret><nametext>erl_errno</nametext></name> - <fsummary>Variable <c>erl_errno</c> contains the - Erl_Interface error number. You can change the value if you wish. - </fsummary> - <desc> - <p><c>erl_errno</c> is initially (at program startup) zero - and is then set by many <c>Erl_Interface</c> functions on failure to - a non-zero error code to indicate what kind of error it - encountered. A successful function call can change - <c>erl_errno</c> (by calling some other function that - fails), but no function does never set it to zero. This means - that you cannot use <c>erl_errno</c> to see <em>if</em> a - function call failed. Instead, each function reports failure - in its own way (usually by returning a negative number or - <c>NULL</c>), in which case you can examine - <c>erl_errno</c> for details.</p> - <p><c>erl_errno</c> uses the error codes defined in your - system's <c><errno.h></c>.</p> - <note> - <p><c>erl_errno</c> is a "modifiable lvalue" (just - like ISO C defines <c>errno</c> to be) rather than a - variable. This means it can be implemented as a macro - (expanding to, for example, <c>*_erl_errno()</c>). - For reasons of thread safety (or task safety), this is exactly what - we do on most platforms.</p> - </note> - </desc> - </func> - </funcs> -</cref> diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml deleted file mode 100644 index 295760b4e6..0000000000 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ /dev/null @@ -1,776 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>1996</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>erl_eterm</title> - <prepared>Torbjörn Törnkvist</prepared> - <responsible>Torbjörn Törnkvist</responsible> - <docno></docno> - <approved>Bjarne Däcker</approved> - <checked>Torbjörn Törnkvist</checked> - <date>1998-07-03</date> - <rev>A</rev> - <file>erl_eterm.xml</file> - </header> - <lib>erl_eterm</lib> - <libsummary>Functions for Erlang term construction.</libsummary> - <description> - <note><p>The support for VxWorks is deprecated as of OTP 22, and - will be removed in OTP 23.</p></note> - <note><p>The old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>) is deprecated as of OTP 22, and will be - removed in OTP 23. This does not apply to the <c>ei</c> - library. Reasonably new <c>gcc</c> compilers will issue deprecation - warnings. In order to disable these warnings, define the macro - <c>EI_NO_DEPR_WARN</c>.</p></note> - - <p>This module provides functions for creating and manipulating - Erlang terms.</p> - - <p>An Erlang term is represented by a C structure of type - <c>ETERM</c>. Applications should not reference any fields - in this structure directly, as it can be changed in future releases - to provide faster and more compact term storage. Instead, - applications should use the macros and functions provided.</p> - - <p>Each of the following macros takes a single <c>ETERM</c> pointer as an - argument. The macros return a non-zero value if the test is true, - otherwise <c>0</c>.</p> - - <taglist> - <tag><c>ERL_IS_INTEGER(t)</c></tag> - <item>True if <c>t</c> is an integer.</item> - <tag><c>ERL_IS_UNSIGNED_INTEGER(t)</c></tag> - <item>True if <c>t</c> is an integer.</item> - <tag><c>ERL_IS_FLOAT(t)</c></tag> - <item>True if <c>t</c> is a floating point number.</item> - <tag><c>ERL_IS_ATOM(t)</c></tag> - <item>True if <c>t</c> is an atom.</item> - <tag><c>ERL_IS_PID(t)</c></tag> - <item>True if <c>t</c> is a pid (process identifier).</item> - <tag><c>ERL_IS_PORT(t)</c></tag> - <item>True if <c>t</c> is a port.</item> - <tag><c>ERL_IS_REF(t)</c></tag> - <item>True if <c>t</c> is a reference.</item> - <tag><c>ERL_IS_TUPLE(t)</c></tag> - <item>True if <c>t</c> is a tuple.</item> - <tag><c>ERL_IS_BINARY(t)</c></tag> - <item>True if <c>t</c> is a binary.</item> - <tag><c>ERL_IS_LIST(t)</c></tag> - <item>True if <c>t</c> is a list with zero or more - elements.</item> - <tag><c>ERL_IS_EMPTY_LIST(t)</c></tag> - <item>True if <c>t</c> is an empty list.</item> - <tag><c>ERL_IS_CONS(t)</c></tag> - <item>True if <c>t</c> is a list with at least one - element.</item> - </taglist> - - <p>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 <c>ETERM*</c> containing the wrong type. For example, - passing a tuple to <c>ERL_ATOM_PTR()</c> likely results in garbage.</p> - - <taglist> - <tag><c>char *ERL_ATOM_PTR(t)</c></tag> - <item></item> - <tag><c>char *ERL_ATOM_PTR_UTF8(t)</c></tag> - <item>A string representing atom <c>t</c>.</item> - <tag><c>int ERL_ATOM_SIZE(t)</c></tag> - <item></item> - <tag><c>int ERL_ATOM_SIZE_UTF8(t)</c></tag> - <item>The length (in bytes) of atom <c>t</c>.</item> - <tag><c>void *ERL_BIN_PTR(t)</c></tag> - <item>A pointer to the contents of <c>t</c>.</item> - <tag><c>int ERL_BIN_SIZE(t)</c></tag> - <item>The length (in bytes) of binary object <c>t</c>.</item> - <tag><c>int ERL_INT_VALUE(t)</c></tag> - <item>The integer of <c>t</c>.</item> - <tag><c>unsigned int ERL_INT_UVALUE(t)</c></tag> - <item>The unsigned integer value of <c>t</c>.</item> - <tag><c>double ERL_FLOAT_VALUE(t)</c></tag> - <item>The floating point value of <c>t</c>.</item> - <tag><c>ETERM *ERL_PID_NODE(t)</c></tag> - <item></item> - <tag><c>ETERM *ERL_PID_NODE_UTF8(t)</c></tag> - <item>The node in pid <c>t</c>.</item> - <tag><c>int ERL_PID_NUMBER(t)</c></tag> - <item>The sequence number in pid <c>t</c>.</item> - <tag><c>int ERL_PID_SERIAL(t)</c></tag> - <item>The serial number in pid <c>t</c>.</item> - <tag><c>int ERL_PID_CREATION(t)</c></tag> - <item>The creation number in pid <c>t</c>.</item> - <tag><c>int ERL_PORT_NUMBER(t)</c></tag> - <item>The sequence number in port <c>t</c>.</item> - <tag><c>int ERL_PORT_CREATION(t)</c></tag> - <item>The creation number in port <c>t</c>.</item> - <tag><c>ETERM *ERL_PORT_NODE(t)</c></tag> - <item></item> - <tag><c>ETERM *ERL_PORT_NODE_UTF8(t)</c></tag> - <item>The node in port <c>t</c>.</item> - <tag><c>int ERL_REF_NUMBER(t)</c></tag> - <item>The first part of the reference number in ref <c>t</c>. - Use only for compatibility.</item> - <tag><c>int ERL_REF_NUMBERS(t)</c></tag> - <item>Pointer to the array of reference numbers in ref - <c>t</c>.</item> - <tag><c>int ERL_REF_LEN(t)</c></tag> - <item>The number of used reference numbers in ref - <c>t</c>.</item> - <tag><c>int ERL_REF_CREATION(t)</c></tag> - <item>The creation number in ref <c>t</c>.</item> - <tag><c>int ERL_TUPLE_SIZE(t)</c></tag> - <item>The number of elements in tuple <c>t</c>.</item> - <tag><c>ETERM *ERL_CONS_HEAD(t)</c></tag> - <item>The head element of list <c>t</c>.</item> - <tag><c>ETERM *ERL_CONS_TAIL(t)</c></tag> - <item>A list representing the tail elements of list - <c>t</c>.</item> - </taglist> - </description> - - <funcs> - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_cons(head, tail)</nametext></name> - <fsummary>Prepend a term to the head of a list.</fsummary> - <type> - <v>ETERM *head;</v> - <v>ETERM *tail;</v> - </type> - <desc> - <p>Concatenates two Erlang terms, prepending <c>head</c> - onto <c>tail</c> and thereby creating a - <c>cons</c> cell. - To make a proper list, <c>tail</c> is always to be a list - or an empty list. Notice that <c>NULL</c> is not a valid list.</p> - <list type="bulleted"> - <item><c>head</c> is the new term to be added.</item> - <item><c>tail</c> is the existing list to which - <c>head</c> is concatenated.</item> - </list> - <p>The function returns a new list.</p> - <p><c>ERL_CONS_HEAD(list)</c> and - <c>ERL_CONS_TAIL(list)</c> - can be used to retrieve the head and tail components - from the list. <c>erl_hd(list)</c> and - <c>erl_tl(list)</c> do - the same thing, but check that the argument really is a list.</p> - <p><em>Example:</em></p> - <code type="none"><![CDATA[ -ETERM *list,*anAtom,*anInt; -anAtom = erl_mk_atom("madonna"); -anInt = erl_mk_int(21); -list = erl_mk_empty_list(); -list = erl_cons(anAtom, list); -list = erl_cons(anInt, list); - ... /* do some work */ -erl_free_compound(list); - ]]></code> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_copy_term(term)</nametext></name> - <fsummary>Create a copy of an Erlang term.</fsummary> - <type> - <v>ETERM *term;</v> - </type> - <desc> - <p>Creates and returns a copy of the Erlang term - <c>term</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_element(position, tuple)</nametext></name> - <fsummary>Extract an element from an Erlang tuple.</fsummary> - <type> - <v>int position;</v> - <v>ETERM *tuple;</v> - </type> - <desc> - <p>Extracts a specified element from an Erlang tuple.</p> - <list type="bulleted"> - <item><c>position</c> specifies which element to retrieve - from <c>tuple</c>. The elements are numbered starting - from 1.</item> - <item><c>tuple</c> is an Erlang term containing at least - <c>position</c> elements.</item> - </list> - <p>Returns a new Erlang term corresponding to the requested element, or - <c>NULL</c> if <c>position</c> was greater - than the arity of <c>tuple</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_hd(list)</nametext></name> - <fsummary>Extract the first element from a list.</fsummary> - <type> - <v>ETERM *list;</v> - </type> - <desc> - <p>Extracts the first element from a list.</p> - <p><c>list</c> is an Erlang term containing a list.</p> - <p>Returns an Erlang term corresponding to the head - head element in the list, or a <c>NULL</c> pointer if - <c>list</c> was not a list.</p> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_init(NULL, 0)</nametext></name> - <fsummary>Initialization routine.</fsummary> - <type> - <v>void *NULL;</v> - <v>int 0;</v> - </type> - <desc> - <p>This function must be called before any of the others in the - <c>Erl_Interface</c> library to initialize the - library functions. The arguments must be specified as - <c>erl_init(NULL,0)</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_iolist_length(list)</nametext></name> - <fsummary>Return the length of an I/O list.</fsummary> - <type> - <v>ETERM *list;</v> - </type> - <desc> - <p>Returns the length of an I/O list.</p> - <p><c>list</c> is an Erlang term containing an I/O list.</p> - <p>Returns the length of <c>list</c>, or - <c>-1</c> if <c>list</c> is not an I/O list.</p> - <p>For the definition of an I/O list, see - <seealso marker="#erl_iolist_to_binary"> - <c>erl_iolist_to_binary</c></seealso>.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_iolist_to_binary(term)</nametext></name> - <fsummary>Convert an I/O list to a binary.</fsummary> - <type> - <v>ETERM *list;</v> - </type> - <desc> - <p>Converts an I/O list to a binary term.</p> - <p><c>list</c> is an Erlang term containing a list.</p> - <p>Returns an Erlang binary term, or <c>NULL</c> if - <c>list</c> was not an I/O list.</p> - <p>Informally, an I/O list is a deep list of characters and - binaries that can be sent to an Erlang port. In BNF, an I/O - list is formally defined as follows:</p> - <code type="none"><![CDATA[ -iolist ::= [] - | Binary - | [iohead | iolist] - ; -iohead ::= Binary - | Byte (integer in the range [0..255]) - | iolist - ; - ]]></code> - </desc> - </func> - - <func> - <name since=""><ret>char *</ret><nametext>erl_iolist_to_string(list)</nametext></name> - <fsummary>Convert an I/O list to a <c>NULL</c>-terminated string.</fsummary> - <type> - <v>ETERM *list;</v> - </type> - <desc> - <p>Converts an I/O list to a <c>NULL</c>-terminated C string.</p> - <p><c>list</c> is an Erlang term containing an I/O list. - The I/O list must not contain the integer 0, as C strings may not - contain this value except as a terminating marker.</p> - <p>Returns a pointer to a dynamically allocated - buffer containing a string. If <c>list</c> is not an I/O - list, or if <c>list</c> contains the integer 0, - <c>NULL</c> is returned. It - is the caller's responsibility to free the allocated buffer - with <c>erl_free()</c>.</p> - <p>For the definition of an I/O list, see - <seealso marker="#erl_iolist_to_binary"> - <c>erl_iolist_to_binary</c></seealso>.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_length(list)</nametext></name> - <fsummary>Determine the length of a list.</fsummary> - <type> - <v>ETERM *list;</v> - </type> - <desc> - <p>Determines the length of a proper list.</p> - <p><c>list</c> is an Erlang term containing a proper list. - In a proper list, all tails except the last point to another list - cell, and the last tail points to an empty list.</p> - <p>Returns <c>-1</c> if <c>list</c> is not a proper - list.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_atom(string)</nametext></name> - <fsummary>Create an atom.</fsummary> - <type> - <v>const char *string;</v> - </type> - <desc> - <p>Creates an atom.</p> - <p><c>string</c> is the sequence of characters that will be - used to create the atom.</p> - <p>Returns an Erlang term containing an atom. Notice that it is - the caller's responsibility to ensure that <c>string</c> - contains a valid name for an atom.</p> - <p><c>ERL_ATOM_PTR(atom)</c> and - <c>ERL_ATOM_PTR_UTF8(atom)</c> - can be used to retrieve the atom name (as a <c>NULL</c>-terminated string). - <c>ERL_ATOM_SIZE(atom)</c> - and <c>ERL_ATOM_SIZE_UTF8(atom)</c> return the length - of the atom name.</p> - <note> - <p>The UTF-8 variants were introduced in Erlang/OTP R16 and the - string returned by <c>ERL_ATOM_PTR(atom)</c> was not - <c>NULL</c>-terminated on older releases.</p> - </note> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_binary(bptr, size)</nametext></name> - <fsummary>Create a binary object.</fsummary> - <type> - <v>char *bptr;</v> - <v>int size;</v> - </type> - <desc> - <p>Produces an Erlang binary object from a - buffer containing a sequence of bytes.</p> - <list type="bulleted"> - <item><c>bptr</c> is a pointer to a buffer containing - data to be converted.</item> - <item><c>size</c> indicates the length of - <c>bptr</c>.</item> - </list> - <p>Returns an Erlang binary object.</p> - <p><c>ERL_BIN_PTR(bin)</c> retrieves a pointer to - the binary data. <c>ERL_BIN_SIZE(bin)</c> retrieves the - size.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_empty_list()</nametext></name> - <fsummary>Create an empty Erlang list.</fsummary> - <desc> - <p>Creates and returns an empty Erlang list. - Notice that <c>NULL</c> is not used to represent an empty list; - Use this function instead.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_estring(string, len)</nametext></name> - <fsummary>Create an Erlang string.</fsummary> - <type> - <v>char *string;</v> - <v>int len;</v> - </type> - <desc> - <p>Creates a list from a sequence of bytes.</p> - <list type="bulleted"> - <item><c>string</c> is a buffer containing a sequence of - bytes. The buffer does not need to be <c>NULL</c>-terminated.</item> - <item><c>len</c> is the length of - <c>string</c>.</item> - </list> - <p>Returns an Erlang list object corresponding to - the character sequence in <c>string</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_float(f)</nametext></name> - <fsummary>Create an Erlang float.</fsummary> - <type> - <v>double f;</v> - </type> - <desc> - <p>Creates an Erlang float.</p> - <p><c>f</c> is a value to be converted to an Erlang - float.</p> - <p>Returns an Erlang float object with the value - specified in <c>f</c> or <c>NULL</c> if - <c>f</c> is not finite.</p> - <p><c>ERL_FLOAT_VALUE(t)</c> can be used to retrieve the - value from an Erlang float.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_int(n)</nametext></name> - <fsummary>Create an Erlang integer.</fsummary> - <type> - <v>int n;</v> - </type> - <desc> - <p>Creates an Erlang integer.</p> - <p><c>n</c> is a value to be converted to an Erlang - integer.</p> - <p>Returns an Erlang integer object with the - value specified in <c>n</c>.</p> - <p><c>ERL_INT_VALUE(t)</c> can be used to retrieve the - value from an Erlang integer.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_list(array, arrsize)</nametext></name> - <fsummary>Create a list from an array.</fsummary> - <type> - <v>ETERM **array;</v> - <v>int arrsize;</v> - </type> - <desc> - <p>Creates an Erlang list from an array of Erlang terms, such - that each element in the list corresponds to one element in - the array.</p> - <list type="bulleted"> - <item><c>array</c> is an array of Erlang terms.</item> - <item><c>arrsize</c> is the number of elements in - <c>array</c>.</item> - </list> - <p>The function creates an Erlang list object, whose length - <c>arrsize</c> and whose elements are taken from the - terms in <c>array</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_long_ref(node, n1, n2, n3, creation)</nametext></name> - <fsummary>Create an Erlang reference.</fsummary> - <type> - <v>const char *node;</v> - <v>unsigned int n1, n2, n3;</v> - <v>unsigned int creation;</v> - </type> - <desc> - <p>Creates an Erlang reference, with 82 bits.</p> - <list type="bulleted"> - <item><c>node</c> is the name of the C-node.</item> - <item><c>n1</c>, <c>n2</c>, and - <c>n3</c> can be seen as one big number - <c>n1*2^64+n2*2^32+n3</c>, which is to be chosen - uniquely for each reference created for a given C-node.</item> - <item><c>creation</c> is an arbitrary number.</item> - </list> - <p>Notice that <c>n3</c> and <c>creation</c> - are limited in precision, so only the low 18 and 2 bits of these - numbers are used.</p> - <p>Returns an Erlang reference object.</p> - <p><c>ERL_REF_NODE(ref)</c>, - <c>ERL_REF_NUMBERS(ref)</c>, - <c>ERL_REF_LEN(ref)</c>, and - <c>ERL_REF_CREATION(ref)</c> can be used to retrieve the - values used to create the reference.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_pid(node, number, serial, creation)</nametext></name> - <fsummary>Create a process identifier.</fsummary> - <type> - <v>const char *node;</v> - <v>unsigned int number;</v> - <v>unsigned int serial;</v> - <v>unsigned int creation;</v> - </type> - <desc> - <p>Creates an Erlang process identifier (pid). The - resulting pid can be used by Erlang processes wishing to - communicate with the C-node.</p> - <list type="bulleted"> - <item><c>node</c> is the name of the C-node.</item> - <item><c>number</c>, <c>serial</c>, and - <c>creation</c> are - arbitrary numbers. Notice that these are limited in - precision, so only the low 15, 3, and 2 bits of these numbers - are used.</item> - </list> - <p>Returns an Erlang pid object.</p> - <p><c>ERL_PID_NODE(pid)</c>, - <c>ERL_PID_NUMBER(pid)</c>, - <c>ERL_PID_SERIAL(pid)</c>, and - <c>ERL_PID_CREATION(pid)</c> - can be used to retrieve the four values used to create the pid.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_port(node, number, creation)</nametext></name> - <fsummary>Create a port identifier.</fsummary> - <type> - <v>const char *node;</v> - <v>unsigned int number;</v> - <v>unsigned int creation;</v> - </type> - <desc> - <p>Creates an Erlang port identifier.</p> - <list type="bulleted"> - <item><c>node</c> is the name of the C-node.</item> - <item><c>number</c> and <c>creation</c> are - arbitrary numbers. Notice that these are limited in - precision, so only the low 18 and 2 bits of these numbers - are used.</item> - </list> - <p>Returns an Erlang port object.</p> - <p><c>ERL_PORT_NODE(port)</c>, - <c>ERL_PORT_NUMBER(port)</c>, - and <c>ERL_PORT_CREATION</c> can be used to retrieve the - three values used to create the port.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_ref(node, number, creation)</nametext></name> - <fsummary>Create an old Erlang reference.</fsummary> - <type> - <v>const char *node;</v> - <v>unsigned int number;</v> - <v>unsigned int creation;</v> - </type> - <desc> - <p>Creates an old Erlang reference, with - only 18 bits - use <c>erl_mk_long_ref</c> instead.</p> - <list type="bulleted"> - <item><c>node</c> is the name of the C-node.</item> - <item><c>number</c> is to be chosen uniquely for each - reference created for a given C-node.</item> - <item><c>creation</c> is an arbitrary number.</item> - </list> - <p>Notice that <c>number</c> and <c>creation</c> - are limited in precision, so only the low 18 and 2 bits of these - numbers are used.</p> - <p>Returns an Erlang reference object.</p> - <p><c>ERL_REF_NODE(ref)</c>, - <c>ERL_REF_NUMBER(ref)</c>, and - <c>ERL_REF_CREATION(ref)</c> can be used to retrieve the - three values used to create the reference.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_string(string)</nametext></name> - <fsummary>Create a string.</fsummary> - <type> - <v>char *string;</v> - </type> - <desc> - <p>Creates a list from a <c>NULL</c>-terminated string.</p> - <p><c>string</c> is a <c>NULL</c>-terminated sequence of - characters - (that is, a C string) from which the list will be created.</p> - <p>Returns an Erlang list.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_tuple(array, arrsize)</nametext></name> - <fsummary>Create an Erlang tuple from an array.</fsummary> - <type> - <v>ETERM **array;</v> - <v>int arrsize;</v> - </type> - <desc> - <p>Creates an Erlang tuple from an array of Erlang terms.</p> - <list type="bulleted"> - <item><c>array</c> is an array of Erlang terms.</item> - <item><c>arrsize</c> is the number of elements in - <c>array</c>.</item> - </list> - <p>The function creates an Erlang tuple, whose arity is - <c>size</c> and whose elements are taken from the terms - in <c>array</c>.</p> - <p>To retrieve the size of a tuple, either use function - <c>erl_size</c> (which checks the type of the - checked term and works for a binary as well as for a tuple) or - <c>ERL_TUPLE_SIZE(tuple)</c> returns the arity of a tuple. - <c>erl_size()</c> does the same thing, but it checks - that the argument is a tuple. - <c>erl_element(index,tuple)</c> returns the element - corresponding to a given position in the tuple.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_uint(n)</nametext></name> - <fsummary>Create an unsigned integer.</fsummary> - <type> - <v>unsigned int n;</v> - </type> - <desc> - <p>Creates an Erlang unsigned integer.</p> - <p><c>n</c> is a value to be converted to an Erlang - unsigned integer.</p> - <p>Returns an Erlang unsigned integer object with - the value specified in <c>n</c>.</p> - <p><c>ERL_INT_UVALUE(t)</c> can be used to retrieve the - value from an Erlang unsigned integer.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_mk_var(name)</nametext></name> - <fsummary>Create an Erlang variable.</fsummary> - <type> - <v>char *name;</v> - </type> - <desc> - <p>Creates an unbound Erlang variable. The variable can later be bound - through pattern matching or assignment.</p> - <p><c>name</c> specifies a name for the variable.</p> - <p>Returns an Erlang variable object with the - name <c>name</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_print_term(stream, term)</nametext></name> - <fsummary>Print an Erlang term.</fsummary> - <type> - <v>FILE *stream;</v> - <v>ETERM *term;</v> - </type> - <desc> - <p>Prints the specified Erlang term to the specified output stream.</p> - <list type="bulleted"> - <item><c>stream</c> indicates where the function is to - send its output.</item> - <item><c>term</c> is the Erlang term to print.</item> - </list> - <p>Returns the number of characters written on success, otherwise a - negative value.</p> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_set_compat_rel(release_number)</nametext></name> - <fsummary>Set the Erl_Interface library in compatibility mode.</fsummary> - <type> - <v>unsigned release_number;</v> - </type> - <desc> - <p>By default, the <c>Erl_Interface</c> library is only - guaranteed to be compatible with other Erlang/OTP components from the - same release as the <c>Erl_Interface</c> library itself. - For example, <c>Erl_Interface</c> from Erlang/OTP R10 - is not compatible - with an Erlang emulator from Erlang/OTP R9 by default.</p> - <p>A call to <c>erl_set_compat_rel(release_number)</c> sets - the <c>Erl_Interface</c> library in compatibility mode of - release <c>release_number</c>. Valid range of - <c>release_number</c> - is [7, current release]. This makes it possible to - communicate with Erlang/OTP components from earlier releases.</p> - <note> - <p>If this function is called, it may only be called once - directly after the call to function - <seealso marker="#erl_init">erl_init()</seealso>.</p> - </note> - <warning> - <p>You may run into trouble if this feature is used - carelessly. Always ensure that all communicating - components are either from the same Erlang/OTP release, or - from release X and release Y where all components - from release Y are in compatibility mode of release X.</p> - </warning> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_size(term)</nametext></name> - <fsummary>Return the arity of a tuple or binary.</fsummary> - <type> - <v>ETERM *term;</v> - </type> - <desc> - <p>Returns either the arity of an Erlang tuple or the - number of bytes in an Erlang binary object.</p> - <p><c>term</c> is an Erlang tuple or an Erlang binary - object.</p> - <p>Returns the size of <c>term</c> as described - above, or <c>-1</c> if <c>term</c> is not one of the two - supported types.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_tl(list)</nametext></name> - <fsummary>Extract the tail from a list.</fsummary> - <type> - <v>ETERM *list;</v> - </type> - <desc> - <p>Extracts the tail from a list.</p> - <p><c>list</c> is an Erlang term containing a list.</p> - <p>Returns an Erlang list corresponding to the - original list minus the first element, or <c>NULL</c> pointer if - <c>list</c> was not a list.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_var_content(term, name)</nametext></name> - <fsummary>Extract the content of a variable.</fsummary> - <type> - <v>ETERM *term;</v> - <v>char *name;</v> - </type> - <desc> - <p>Returns the contents of the specified variable in an Erlang term.</p> - <list type="bulleted"> - <item><c>term</c> is an Erlang term. In order for this - function to succeed, - <c>term</c> must either be an Erlang variable with - the specified name, or it must be an Erlang list or tuple - containing a variable with the specified name. Other Erlang - types cannot contain variables.</item> - <item><c>name</c> is the name of an Erlang variable. - </item> - </list> - <p>Returns the Erlang object corresponding to the value of - <c>name</c> in <c>term</c>. If no variable - with the name <c>name</c> is found in - <c>term</c>, or if <c>term</c> is - not a valid Erlang term, <c>NULL</c> is returned.</p> - </desc> - </func> - </funcs> -</cref> diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml deleted file mode 100644 index b5e895c720..0000000000 --- a/lib/erl_interface/doc/src/erl_format.xml +++ /dev/null @@ -1,138 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>1996</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>erl_format</title> - <prepared>Torbjörn Törnkvist</prepared> - <responsible>Torbjörn Törnkvist</responsible> - <docno></docno> - <approved>Bjarne Däcker</approved> - <checked>Torbjörn Törnkvist</checked> - <date>1996-10-16</date> - <rev>A</rev> - <file>erl_format.xml</file> - </header> - <lib>erl_format</lib> - <libsummary>Create and match Erlang terms.</libsummary> - <description> - <p>This module contains two routines: one general function for - creating Erlang terms and one for pattern matching Erlang terms.</p> - </description> - - <funcs> - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_format(FormatStr, ...)</nametext></name> - <fsummary>Create an Erlang term.</fsummary> - <type> - <v>char *FormatStr;</v> - </type> - <desc> - <p>A general function for creating Erlang terms using - a format specifier and a corresponding set of arguments, much - in the way <c>printf()</c> works.</p> - <p><c>FormatStr</c> is a format specification string. - The valid format specifiers are as follows:</p> - <list type="bulleted"> - <item><c>~i</c> - Integer</item> - <item><c>~f</c> - Floating point</item> - <item><c>~a</c> - Atom</item> - <item><c>~s</c> - String</item> - <item><c>~w</c> - Arbitrary Erlang term</item> - </list> - <p>For each format specifier included in <c>FormatStr</c>, - there must be a corresponding argument following - <c>FormatStr</c>. An Erlang term is built according to - <c>FormatStr</c> with values and Erlang terms substituted - from the corresponding arguments, and according to the individual - format specifiers. For example:</p> - <code type="none"><![CDATA[ -erl_format("[{name,~a},{age,~i},{data,~w}]", - "madonna", - 21, - erl_format("[{adr,~s,~i}]","E-street",42)); - ]]></code> - <p>This creates an <c>(ETERM *)</c> structure corresponding - to the Erlang term - <c>[{name,madonna},{age,21},{data,[{adr,"E-street",42}]}]</c></p> - <p>The function returns an Erlang term, or <c>NULL</c> if - <c>FormatStr</c> does not describe a valid Erlang - term.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_match(Pattern, Term)</nametext></name> - <fsummary>Perform pattern matching.</fsummary> - <type> - <v>ETERM *Pattern,*Term;</v> - </type> - <desc> - <p>This function is used to perform pattern matching similar - to that done in Erlang. For matching rules and more examples, see - section <seealso marker="doc/reference_manual:patterns"> - Pattern Matching</seealso> in the Erlang Reference Manual.</p> - <list type="bulleted"> - <item><c>Pattern</c> is an Erlang term, possibly - containing unbound variables.</item> - <item><c>Term</c> is an Erlang term that we wish to match - against <c>Pattern</c>.</item> - </list> - <p><c>Term</c> and <c>Pattern</c> are compared - and any unbound variables in <c>Pattern</c> are bound to - corresponding values in <c>Term</c>.</p> - <p>If <c>Term</c> and <c>Pattern</c> can be - matched, the function returns a non-zero value and binds any unbound - variables in <c>Pattern</c>. If <c>Term</c> - and <c>Pattern</c> do - not match, <c>0</c> is returned. For example:</p> - <code type="none"><![CDATA[ -ETERM *term, *pattern, *pattern2; -term1 = erl_format("{14,21}"); -term2 = erl_format("{19,19}"); -pattern1 = erl_format("{A,B}"); -pattern2 = erl_format("{F,F}"); -if (erl_match(pattern1, term1)) { - /* match succeeds: - * A gets bound to 14, - * B gets bound to 21 - */ - ... -} -if (erl_match(pattern2, term1)) { - /* match fails because F cannot be - * bound to two separate values, 14 and 21 - */ - ... -} -if (erl_match(pattern2, term2)) { - /* match succeeds and F gets bound to 19 */ - ... -} - ]]></code> - <p><c>erl_var_content()</c> can be used to retrieve the - content of any variables bound as a result of a call to - <c>erl_match()</c>.</p> - </desc> - </func> - </funcs> -</cref> diff --git a/lib/erl_interface/doc/src/erl_interface.xml b/lib/erl_interface/doc/src/erl_interface.xml deleted file mode 100644 index decd66046a..0000000000 --- a/lib/erl_interface/doc/src/erl_interface.xml +++ /dev/null @@ -1,637 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1996</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>The Erl_Interface Library</title> - <prepared>Torbjörn Törnkvist</prepared> - <responsible>Torbjörn Törnkvist</responsible> - <docno></docno> - <approved>Bjarne Däcker</approved> - <checked>K.Lundin</checked> - <date>990113</date> - <rev>A</rev> - <file>erl_interface.sgml</file> - </header> - <p>The Erl_Interface library contains functions. which help you - integrate programs written in C and Erlang. The functions in - Erl_Interface support the following:</p> - <list type="bulleted"> - <item>manipulation of data represented as Erlang data types</item> - <item>conversion of data between C and Erlang formats</item> - <item>encoding and decoding of Erlang data types for transmission or storage</item> - <item>communication between C nodes and Erlang processes</item> - <item>backup and restore of C node state to and from Mnesia</item> - </list> - <p>In the following sections, these topics are described:</p> - <list type="bulleted"> - <item>compiling your code for use with Erl_Interface</item> - <item>initializing Erl_Interface</item> - <item>encoding, decoding, and sending Erlang terms</item> - <item>building terms and patterns</item> - <item>pattern matching</item> - <item>connecting to a distributed Erlang node</item> - <item>using EPMD</item> - <item>sending and receiving Erlang messages</item> - <item>remote procedure calls</item> - <item>global names</item> - <item>the registry</item> - </list> - - <section> - <title>Deprecation and Removal</title> - <note><p>The support for VxWorks is deprecated as of OTP 22, and - will be removed in OTP 23.</p></note> - <note><p>The old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>) is deprecated as of OTP 22, and will be - removed in OTP 23. This does not apply to the <c>ei</c> - library. Reasonably new <c>gcc</c> compilers will issue deprecation - warnings. In order to disable these warnings, define the macro - <c>EI_NO_DEPR_WARN</c>.</p></note> - </section> - - <section> - <title>Compiling and Linking Your Code</title> - <p>In order to use any of the Erl_Interface functions, include the - following lines in your code:</p> - <code type="none"><![CDATA[ -#include "erl_interface.h" -#include "ei.h" ]]></code> - <p>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:</p> - <code type="none"><![CDATA[ -Eshell V4.7.4 (abort with ^G) -1> code:root_dir(). -/usr/local/otp ]]></code> - <p>To compile your code, make sure that your C compiler knows where - to find <c>erl_interface.h</c> by specifying an appropriate <c>-I</c> - argument on the command line, or by adding it to the <c>CFLAGS</c> - definition in your <c>Makefile</c>. The correct value for this path is - <c>$OTPROOT/lib/erl_interface</c><em>Vsn</em><c>/include</c>, where <c>$OTPROOT</c> is the path - reported by <c>code:root_dir/0</c> in the above example, and <em>Vsn</em> is - the version of the Erl_interface application, for example - <c>erl_interface-3.2.3</c></p> - <code type="none"><![CDATA[ -$ cc -c -I/usr/local/otp/lib/erl_interface-3.2.3/include myprog.c ]]></code> - <p>When linking, you will need to specify the path to - <c>liberl_interface.a</c> and <c>libei.a</c> with - <c>-L$OTPROOT/lib/erl_interface-3.2.3/lib</c>, and you will need to specify the - name of the libraries with <c>-lerl_interface -lei</c>. You can do - this on the command line or by adding the flags to the <c>LDFLAGS</c> - definition in your <c>Makefile</c>.</p> - <code type="none"><![CDATA[ -$ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ - lib myprog.o -lerl_interface -lei -o myprog ]]></code> - <p>Also, on some systems it may be necessary to link with some - additional libraries (e.g. <c>libnsl.a</c> and <c>libsocket.a</c> on - Solaris, or <c>wsock32.lib</c> on Windows) in order to use the - communication facilities of Erl_Interface.</p> - <p>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 <c>_REENTRANT</c> and either <c>STHREADS</c> or - <c>PTHREADS</c>. The default is to use POSIX threads if - <c>_REENTRANT</c> is specified.</p> - <p>Note that both single threaded and default versions of the Erl_interface - and Ei libraries are provided. (The single threaded versions are named - <c>liberl_interface_st</c> and <c>libei_st</c>). 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 <c>eidefs.mk</c> file in the erl_interface src directory.</p> - </section> - - <section> - <title>Initializing the erl_interface Library</title> - <p>Before calling any of the other Erl_Interface functions, you - must call <c>erl_init()</c> exactly once to initialize the library. - <c>erl_init()</c> takes two arguments, however the arguments are no - longer used by Erl_Interface, and should therefore be specified - as <c>erl_init(NULL,0)</c>.</p> - </section> - - <section> - <title>Encoding, Decoding and Sending Erlang Terms</title> - <p>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. </p> - <p>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 - <c>{tobbe,3928}</c>:</p> - <code type="none"><![CDATA[ - -ETERM *arr[2], *tuple; -char buf[BUFSIZ]; -int i; - -arr[0] = erl_mk_atom("tobbe"); -arr[1] = erl_mk_integer(3928); -tuple = erl_mk_tuple(arr, 2); -i = erl_encode(tuple, buf); ]]></code> - <p>Alternatively, you can use <c>erl_send()</c> and - <c>erl_receive_msg</c>, which handle the encoding and decoding of - messages transparently.</p> - <p>Refer to the Reference Manual for a complete description of the - following modules:</p> - <list type="bulleted"> - <item>the <c>erl_eterm</c> module for creating Erlang terms</item> - <item>the <c>erl_marshal</c> module for encoding and decoding routines.</item> - </list> - </section> - - <section> - <title>Building Terms and Patterns</title> - <p>The previous example can be simplified by using - <c>erl_format()</c> to create an Erlang term.</p> - <code type="none"><![CDATA[ - -ETERM *ep; -ep = erl_format("{~a,~i}", "tobbe", 3928); ]]></code> - <p>Refer to the Reference Manual, the <c>erl_format</c> module, for a - full description of the different format directives. The following - example is more complex:</p> - <code type="none"><![CDATA[ - -ETERM *ep; -ep = erl_format("[{name,~a},{age,~i},{data,~w}]", - "madonna", - 21, - erl_format("[{adr,~s,~i}]", "E-street", 42)); -erl_free_compound(ep); ]]></code> - <p>As in previous examples, it is your responsibility to free the - memory allocated for Erlang terms. In this example, - <c>erl_free_compound()</c> ensures that the complete term pointed to - by <c>ep</c> is released. This is necessary, because the pointer from - the second call to <c>erl_format()</c> is lost. </p> - <p>The following - example shows a slightly different solution:</p> - <code type="none"><![CDATA[ - -ETERM *ep,*ep2; -ep2 = erl_format("[{adr,~s,~i}]","E-street",42); -ep = erl_format("[{name,~a},{age,~i},{data,~w}]", - "madonna", 21, ep2); -erl_free_term(ep); -erl_free_term(ep2); ]]></code> - <p>In this case, you free the two terms independently. The order in - which you free the terms <c>ep</c> and <c>ep2</c> is not important, - because the Erl_Interface library uses reference counting to - determine when it is safe to actually remove objects. </p> - <p>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:</p> - <code type="none"><![CDATA[ -long allocated, freed; - -erl_eterm_statistics(&allocated,&freed); -printf("currently allocated blocks: %ld\ -",allocated); -printf("length of freelist: %ld\ -",freed); - -/* really free the freelist */ -erl_eterm_release(); - ]]></code> - <p>Refer to the Reference Manual, the <c>erl_malloc</c> module for more - information.</p> - </section> - - <section> - <title>Pattern Matching</title> - <p>An Erlang pattern is a term that may contain unbound variables or - <c>"do not care"</c> 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.</p> - <code type="none"><![CDATA[ - -ETERM *pattern; -pattern = erl_format("{madonna,Age,_}"); ]]></code> - <p><c>erl_match()</c> 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 <em>Age</em> which appears at two - positions in the tuple. The pattern match is performed as follows:</p> - <list type="ordered"> - <item><c>erl_match()</c> will bind the contents of - <em>Age</em> to <em>21</em> the first time it reaches the variable</item> - <item>the second occurrence of <em>Age</em> will cause a test for - equality between the terms since <em>Age</em> is already bound to - <em>21</em>. Since <em>Age</em> is bound to 21, the equality test will - succeed and the match continues until the end of the pattern.</item> - <item>if the end of the pattern is reached, the match succeeds and you - can retrieve the contents of the variable</item> - </list> - <code type="none"><![CDATA[ -ETERM *pattern,*term; -pattern = erl_format("{madonna,Age,Age}"); -term = erl_format("{madonna,21,21}"); -if (erl_match(pattern, term)) { - fprintf(stderr, "Yes, they matched: Age = "); - ep = erl_var_content(pattern, "Age"); - erl_print_term(stderr, ep); - fprintf(stderr,"\ -"); - erl_free_term(ep); -} -erl_free_term(pattern); -erl_free_term(term); ]]></code> - <p>Refer to the Reference Manual, the <c>erl_match()</c> function for - more information.</p> - </section> - - <section> - <title>Connecting to a Distributed Erlang Node</title> - <p>In order to connect to a distributed Erlang node you need to first - initialize the connection routine with <c>erl_connect_init()</c>, - which stores information such as the host name, node name, and IP - address for later use:</p> - <code type="none"><![CDATA[ -int identification_number = 99; -int creation=1; -char *cookie="a secret cookie string"; /* An example */ -erl_connect_init(identification_number, cookie, creation); ]]></code> - <p>Refer to the Reference Manual, the <c>erl_connect</c> module for more information.</p> - <p>After initialization, you set up the connection to the Erlang node. - Use <c>erl_connect()</c> 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:</p> - <code type="none"><![CDATA[ -int sockfd; -char *nodename="xyz@chivas.du.etx.ericsson.se"; /* An example */ -if ((sockfd = erl_connect(nodename)) < 0) - erl_err_quit("ERROR: erl_connect failed"); ]]></code> - <p><c>erl_err_quit()</c> prints the specified string and terminates - the program. Refer to the Reference Manual, the <c>erl_error()</c> - function for more information.</p> - </section> - - <section> - <title>Using EPMD</title> - <p><c>Epmd</c> is the Erlang Port Mapper Daemon. Distributed Erlang nodes - register with <c>epmd</c> on the localhost to indicate to other nodes that - they exist and can accept connections. <c>Epmd</c> maintains a register of - node and port number information, and when a node wishes to connect to - another node, it first contacts <c>epmd</c> in order to find out the correct - port number to connect to.</p> - <p>When you use <c>erl_connect()</c> to connect to an Erlang node, a - connection is first made to <c>epmd</c> and, if the node is known, a - connection is then made to the Erlang node.</p> - <p>C nodes can also register themselves with <c>epmd</c> if they want other - nodes in the system to be able to find and connect to them.</p> - <p>Before registering with <c>epmd</c>, you need to first create a listen socket - and bind it to a port. Then:</p> - <code type="none"><![CDATA[ -int pub; - -pub = erl_publish(port); ]]></code> - <p><c>pub</c> is a file descriptor now connected to <c>epmd</c>. <c>Epmd</c> - 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 <c>epmd</c>.</p> - <p>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, <c>epmd</c> 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:</p> - <code type="none"><![CDATA[ -erl_unpublish(node); ]]></code> - <p>This will cause <c>epmd</c> 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.</p> - </section> - - <section> - <title>Sending and Receiving Erlang Messages</title> - <p>Use one of the following two functions to send messages:</p> - <list type="bulleted"> - <item><c>erl_send()</c></item> - <item><c>erl_reg_send()</c></item> - </list> - <p>As in Erlang, it is possible to send messages to a - <em>Pid</em> 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 <em>Pid</em>.</p> - <p>Use one of the following two functions to receive messages:</p> - <list type="bulleted"> - <item><c>erl_receive()</c></item> - <item><c>erl_receive_msg()</c></item> - </list> - <p><c>erl_receive()</c> receives the message into a buffer, while - <c>erl_receive_msg()</c> decodes the message into an Erlang term. </p> - - <section> - <title>Example of Sending Messages</title> - <p>In the following example, <c>{Pid, hello_world}</c> is - sent to a registered process <c>my_server</c>. The message is encoded - by <c>erl_send()</c>:</p> - <code type="none"><![CDATA[ -extern const char *erl_thisnodename(void); -extern short erl_thiscreation(void); -#define SELF(fd) erl_mk_pid(erl_thisnodename(),fd,0,erl_thiscreation()) -ETERM *arr[2], *emsg; -int sockfd, creation=1; - -arr[0] = SELF(sockfd); -arr[1] = erl_mk_atom("Hello world"); -emsg = erl_mk_tuple(arr, 2); - -erl_reg_send(sockfd, "my_server", emsg); -erl_free_term(emsg); ]]></code> - <p>The first element of the tuple that is sent is your own - <em>Pid</em>. This enables <c>my_server</c> to reply. Refer to the - Reference Manual, the <c>erl_connect</c> module for more information - about send primitives.</p> - </section> - - <section> - <title>Example of Receiving Messages</title> - <p>In this example <c>{Pid, Something}</c> is received. The - received Pid is then used to return <c>{goodbye,Pid}</c></p> - <code type="none"><![CDATA[ -ETERM *arr[2], *answer; -int sockfd,rc; -char buf[BUFSIZE]; -ErlMessage emsg; - -if ((rc = erl_receive_msg(sockfd , buf, BUFSIZE, &emsg)) == ERL_MSG) { - arr[0] = erl_mk_atom("goodbye"); - arr[1] = erl_element(1, emsg.msg); - answer = erl_mk_tuple(arr, 2); - erl_send(sockfd, arr[1], answer); - erl_free_term(answer); - erl_free_term(emsg.msg); - erl_free_term(emsg.to); -} -} ]]></code> - <p>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 <c>ERL_TICK</c> message. - This is done automatically by <c>erl_receive()</c>, however when this - has occurred <c>erl_receive</c> returns <c>ERL_TICK</c> to the caller - without storing a message into the <c>ErlMessage</c> structure.</p> - <p>When a message has been received, it is the caller's responsibility - to free the received message <c>emsg.msg</c> as well as <c>emsg.to</c> - or <c>emsg.from</c>, depending on the type of message received.</p> - <p>Refer to the Reference Manual for additional information about the - following modules:</p> - <list type="bulleted"> - <item><c>erl_connect</c></item> - <item><c>erl_eterm</c>.</item> - </list> - </section> - </section> - - <section> - <title>Remote Procedure Calls</title> - <p>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:</p> - <code type="none"><![CDATA[ - -char modname[]=THE_MODNAME; -ETERM *reply,*ep; -ep = erl_format("[~a,[]]", modname); -if (!(reply = erl_rpc(fd, "c", "c", ep))) - erl_err_msg("<ERROR> when compiling file: %s.erl !\ -", modname); -erl_free_term(ep); -ep = erl_format("{ok,_}"); -if (!erl_match(ep, reply)) - erl_err_msg("<ERROR> compiler errors !\ -"); -erl_free_term(ep); -erl_free_term(reply); ]]></code> - <p><c>c:c/1</c> is called to compile the specified module on the - remote node. <c>erl_match()</c> checks that the compilation was - successful by testing for the expected <c>ok</c>.</p> - <p>Refer to the Reference Manual, the <c>erl_connect</c> module for - more information about <c>erl_rpc()</c>, and its companions - <c>erl_rpc_to()</c> and <c>erl_rpc_from()</c>.</p> - </section> - - <section> - <title>Using Global Names</title> - <p>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. </p> - <p>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.</p> - <p>To see what names there are:</p> - <code type="none"><![CDATA[ -char **names; -int count; -int i; - -names = erl_global_names(fd,&count); - -if (names) - for (i=0; i<count; i++) - printf("%s\ -",names[i]); - -free(names); ]]></code> - <p><c>erl_global_names()</c> allocates and returns a buffer containing - all the names known to global. <c>count</c> 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 - <c>count</c> to determine when the last name is reached.</p> - <p>It is the caller's responsibility to free the array. - <c>erl_global_names()</c> allocates the array and all of the strings - using a single call to <c>malloc()</c>, so <c>free(names)</c> is all - that is necessary.</p> - <p>To look up one of the names:</p> - <code type="none"><![CDATA[ -ETERM *pid; -char node[256]; - -pid = erl_global_whereis(fd,"schedule",node); ]]></code> - <p>If <c>"schedule"</c> is known to global, an Erlang pid is returned - that can be used to send messages to the schedule service. - Additionally, <c>node</c> 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 <c>erl_connect()</c>.</p> - <p>Before registering a name, you should already have registered your - port number with <c>epmd</c>. 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.</p> - <p>Create a pid that Erlang processes can use to communicate with your - service:</p> - <code type="none"><![CDATA[ -ETERM *pid; - -pid = erl_mk_pid(thisnode,14,0,0); -erl_global_register(fd,servicename,pid); ]]></code> - <p>After registering the name, you should use <c>erl_accept()</c> to wait for - incoming connections.</p> - <p>Do not forget to free <c>pid</c> later with <c>erl_free_term()</c>!</p> - <p>To unregister a name:</p> - <code type="none"><![CDATA[ -erl_global_unregister(fd,servicename); ]]></code> - </section> - - <section> - <title>The Registry</title> - <p>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.</p> - <p>Keys are strings, i.e. <c>NULL</c>-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.</p> - <p>To start, you need to open a registry:</p> - <code type="none"><![CDATA[ -ei_reg *reg; - -reg = ei_reg_open(45); ]]></code> - <p>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.</p> - <p>You can open as many registries as you like (if memory permits).</p> - <p>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:</p> - <code type="none"><![CDATA[ -struct bonk *b = malloc(sizeof(*b)); -char *name = malloc(7); - -ei_reg_setival(reg,"age",29); -ei_reg_setfval(reg,"height",1.85); - -strcpy(name,"Martin"); -ei_reg_setsval(reg,"name",name); - -b->l = 42; -b->m = 12; -ei_reg_setpval(reg,"jox",b,sizeof(*b)); ]]></code> - <p>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.</p> - <p>Stored values are retrieved from the registry as follows:</p> - <code type="none"><![CDATA[ -long i; -double f; -char *s; -struct bonk *b; -int size; - -i = ei_reg_getival(reg,"age"); -f = ei_reg_getfval(reg,"height"); -s = ei_reg_getsval(reg,"name"); -b = ei_reg_getpval(reg,"jox",&size); ]]></code> - <p>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:</p> - <code type="none"><![CDATA[ -struct ei_reg_stat buf; - -ei_reg_stat(reg,"name",&buf); ]]></code> - <p>Buf will be initialized to contain object attributes.</p> - <p>Objects can be removed from the registry:</p> - <code type="none"><![CDATA[ -ei_reg_delete(reg,"name"); ]]></code> - <p>When you are finished with a registry, close it to remove all the - objects and free the memory back to the system:</p> - <code type="none"><![CDATA[ -ei_reg_close(reg); ]]></code> - - <section> - <title>Backing Up the Registry to Mnesia</title> - <p>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 <c>erl_connect()</c>). Also, Mnesia 3.0 or later must be running - on the Erlang node before the backup is initiated:</p> - <code type="none"><![CDATA[ -ei_reg_dump(fd, reg, "mtab", dumpflags); ]]></code> - <p>The example above will backup the contents of the registry to the - specified Mnesia table <c>"mtab"</c>. 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.</p> - <p>In the same manner, a registry can be restored from a Mnesia table:</p> - <code type="none"><![CDATA[ -ei_reg_restore(fd, reg, "mtab"); ]]></code> - <p>This will read the entire contents of <c>"mtab"</c> 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.</p> - <p>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 <em>entire</em> 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.</p> - </section> - - <section> - <title>Storing Strings and Binaries</title> - <p>When string or binary objects are stored in the registry it is - important that a number of simple guidelines are followed. </p> - <p>Most importantly, the object must have been created with a single call - to <c>malloc()</c> (or similar), so that it can later be removed by a - single call to <c>free()</c>. 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.</p> - <p>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.</p> - <p>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.</p> - <p>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 - <c>ei_reg_markdirty()</c>, or pass appropriate flags to - <c>ei_reg_dump()</c>.</p> - </section> - </section> -</chapter> diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml deleted file mode 100644 index 6650620064..0000000000 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ /dev/null @@ -1,212 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>1996</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>erl_malloc</title> - <prepared>Torbjörn Törnkvist</prepared> - <responsible>Torbjörn Törnkvist</responsible> - <docno></docno> - <approved>Bjarne Däcker</approved> - <checked>Torbjörn Törnkvist</checked> - <date>1998-07-03</date> - <rev>A</rev> - <file>erl_malloc.xml</file> - </header> - <lib>erl_malloc</lib> - <libsummary>Memory allocation functions.</libsummary> - <description> - <note><p>The support for VxWorks is deprecated as of OTP 22, and - will be removed in OTP 23.</p></note> - <note><p>The old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>) is deprecated as of OTP 22, and will be - removed in OTP 23. This does not apply to the <c>ei</c> - library. Reasonably new <c>gcc</c> compilers will issue deprecation - warnings. In order to disable these warnings, define the macro - <c>EI_NO_DEPR_WARN</c>.</p></note> - <p>This module provides functions for allocating and deallocating - memory.</p> - </description> - - <funcs> - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_alloc_eterm(etype)</nametext></name> - <fsummary>Allocate an ETERM structure.</fsummary> - <type> - <v>unsigned char etype;</v> - </type> - <desc> - <p>Allocates an <c>(ETERM)</c> structure.</p> - <p>Specify <c>etype</c> as one of the following - constants:</p> - <list type="bulleted"> - <item><c>ERL_INTEGER</c> - </item> - <item><c>ERL_U_INTEGER</c> (unsigned integer) - </item> - <item><c>ERL_ATOM</c> - </item> - <item><c>ERL_PID</c> (Erlang process identifier) - </item> - <item><c>ERL_PORT</c> - </item> - <item><c>ERL_REF</c> (Erlang reference) - </item> - <item><c>ERL_LIST</c> - </item> - <item><c>ERL_EMPTY_LIST</c> - </item> - <item><c>ERL_TUPLE</c> - </item> - <item><c>ERL_BINARY</c> - </item> - <item><c>ERL_FLOAT</c> - </item> - <item><c>ERL_VARIABLE</c> - </item> - <item><c>ERL_SMALL_BIG</c> (bignum) - </item> - <item><c>ERL_U_SMALL_BIG</c> (bignum) - </item> - </list> - <p><c>ERL_SMALL_BIG</c> and - <c>ERL_U_SMALL_BIG</c> are for - creating Erlang <c>bignums</c>, which can contain integers - of any size. The size of an integer in Erlang is machine-dependent, - but any integer > 2^28 requires a bignum.</p> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_eterm_release(void)</nametext></name> - <fsummary>Clear the ETERM freelist.</fsummary> - <desc> - <p>Clears the freelist, where blocks are placed when they are - released by <c>erl_free_term()</c> and - <c>erl_free_compound()</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_eterm_statistics(allocated, freed)</nametext></name> - <fsummary>Report term allocation statistics.</fsummary> - <type> - <v>long *allocated;</v> - <v>long *freed;</v> - </type> - <desc> - <p>Reports term allocation statistics.</p> - <p><c>allocated</c> and <c>freed</c> are - initialized to - contain information about the fix-allocator used to allocate - <c>ETERM</c> components.</p> - <list type="bulleted"> - <item> - <p><c>allocated</c> is the number of blocks currently - allocated to <c>ETERM</c> objects.</p> - </item> - <item> - <p><c>freed</c> is the length of the freelist, where - blocks are placed when they are - released by <c>erl_free_term()</c> and - <c>erl_free_compound()</c>.</p> - </item> - </list> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_free(ptr)</nametext></name> - <fsummary>Free some memory.</fsummary> - <type> - <v>void *ptr;</v> - </type> - <desc> - <p>Calls the standard - <c>free()</c> function.</p> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_free_array(array, size)</nametext></name> - <fsummary>Free an array of ETERM structures.</fsummary> - <type> - <v>ETERM **array;</v> - <v>int size;</v> - </type> - <desc> - <p>Frees an array of Erlang terms.</p> - <list type="bulleted"> - <item><c>array</c> is an array of ETERM* objects.</item> - <item><c>size</c> is the number of terms in the array. - </item> - </list> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_free_compound(t)</nametext></name> - <fsummary>Free an array of ETERM structures.</fsummary> - <type> - <v>ETERM *t;</v> - </type> - <desc> - <p>Normally it is the programmer's responsibility to free each - Erlang term that has been returned from any of the - <c>Erl_Interface</c> functions. However, as many of the - functions that build new Erlang terms in fact share objects - with other existing terms, it can be difficult for the - programmer to maintain pointers to all such terms to - free them individually.</p> - <p><c>erl_free_compound()</c> recursively frees all of the - subterms associated with a specified Erlang term, regardless of - whether we are still holding pointers to the subterms.</p> - <p>For an example, see section - <seealso marker="ei_users_guide#building_terms_and_patterns">Building Terms and Patterns</seealso> - in the User's Guide.</p> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_free_term(t)</nametext></name> - <fsummary>Free an ETERM structure.</fsummary> - <type> - <v>ETERM *t;</v> - </type> - <desc> - <p>Frees an Erlang term.</p> - </desc> - </func> - - <func> - <name since=""><ret>void</ret><nametext>erl_malloc(size)</nametext></name> - <fsummary>Allocate some memory.</fsummary> - <type> - <v>long size;</v> - </type> - <desc> - <p>Calls the standard - <c>malloc()</c> function.</p> - </desc> - </func> - </funcs> -</cref> diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml deleted file mode 100644 index 33d359d871..0000000000 --- a/lib/erl_interface/doc/src/erl_marshal.xml +++ /dev/null @@ -1,276 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>1996</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>erl_marshal</title> - <prepared>Torbjörn Törnkvist</prepared> - <responsible>Torbjörn Törnkvist</responsible> - <docno></docno> - <approved>Bjarne Däcker</approved> - <checked>Torbjörn Törnkvist</checked> - <date>1998-07-03</date> - <rev>A</rev> - <file>erl_marshal.xml</file> - </header> - <lib>erl_marshal</lib> - <libsummary>Encoding and decoding of Erlang terms.</libsummary> - <description> - <note><p>The support for VxWorks is deprecated as of OTP 22, and - will be removed in OTP 23.</p></note> - <note><p>The old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>) is deprecated as of OTP 22, and will be - removed in OTP 23. This does not apply to the <c>ei</c> - library. Reasonably new <c>gcc</c> compilers will issue deprecation - warnings. In order to disable these warnings, define the macro - <c>EI_NO_DEPR_WARN</c>.</p></note> - <p>This module contains functions for encoding Erlang terms into - a sequence of bytes, and for decoding Erlang terms from a - sequence of bytes.</p> - </description> - - <funcs> - <func> - <name since=""><ret>int</ret><nametext>erl_compare_ext(bufp1, bufp2)</nametext></name> - <fsummary>Compare encoded byte sequences.</fsummary> - <type> - <v>unsigned char *bufp1,*bufp2;</v> - </type> - <desc> - <p>Compares two encoded terms.</p> - <list type="bulleted"> - <item><c>bufp1</c> is a buffer containing an encoded - Erlang term term1.</item> - <item><c>bufp2</c> is a buffer containing an encoded - Erlang term term2.</item> - </list> - <p>Returns <c>0</c> if the terms are equal, <c>-1</c> if - <c>term1</c> < <c>term2</c>, or <c>1</c> if <c>term2</c> < - <c>term1</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>ETERM *</ret><nametext>erl_decode(bufp)</nametext></name> - <name since=""><ret>ETERM *</ret><nametext>erl_decode_buf(bufpp)</nametext></name> - <fsummary>Convert a term from Erlang external format.</fsummary> - <type> - <v>unsigned char *bufp;</v> - <v>unsigned char **bufpp;</v> - </type> - <desc> - <p><c>erl_decode()</c> and - <c>erl_decode_buf()</c> decode - the contents of a buffer and return the corresponding - Erlang term. <c>erl_decode_buf()</c> provides a simple - mechanism for dealing with several encoded terms stored - consecutively in the buffer.</p> - <list type="bulleted"> - <item> - <p><c>bufp</c> is a pointer to a buffer containing one - or more encoded Erlang terms.</p> - </item> - <item> - <p><c>bufpp</c> is the address of a buffer pointer. The - buffer contains one or more consecutively encoded Erlang terms. - Following a successful call to - <c>erl_decode_buf()</c>, <c>bufpp</c> is - updated so that it points to the next encoded term.</p> - </item> - </list> - <p><c>erl_decode()</c> returns an Erlang term - corresponding to the contents of <c>bufp</c> on success, - otherwise <c>NULL</c>. <c>erl_decode_buf()</c> - returns an Erlang - term corresponding to the first of the consecutive terms in - <c>bufpp</c> and moves <c>bufpp</c> forward - to point to the - next term in the buffer. On failure, each of the functions - return <c>NULL</c>.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_encode(term, bufp)</nametext></name> - <name since=""><ret>int</ret><nametext>erl_encode_buf(term, bufpp)</nametext></name> - <fsummary>Convert a term into Erlang external format.</fsummary> - <type> - <v>ETERM *term;</v> - <v>unsigned char *bufp;</v> - <v>unsigned char **bufpp;</v> - </type> - <desc> - <p><c>erl_encode()</c> and - <c>erl_encode_buf()</c> encode - Erlang terms into external format for storage or transmission. - <c>erl_encode_buf()</c> provides a simple mechanism for - encoding several terms consecutively in the same buffer.</p> - <list type="bulleted"> - <item> - <p><c>term</c> is an Erlang term to be encoded.</p> - </item> - <item> - <p><c>bufp</c> is a pointer to a buffer containing one or - more encoded Erlang terms.</p> - </item> - <item> - <p><c>bufpp</c> is a pointer to a pointer to a buffer - containing one or more consecutively encoded Erlang terms. - Following a successful call to - <c>erl_encode_buf()</c>, <c>bufpp</c> is updated so - that it points to the - position for the next encoded term.</p> - </item> - </list> - <p>These functions return the number of bytes written to buffer - on success, otherwise <c>0</c>.</p> - <p>Notice that no bounds checking is done on the buffer. It is - the caller's responsibility to ensure that the buffer is - large enough to hold the encoded terms. You can either use a - static buffer that is large enough to hold the terms you expect - to need in your program, or use <c>erl_term_len()</c> - to determine the exact requirements for a given term.</p> - <p>The following can help you estimate the buffer - requirements for a term. Notice that this information is - implementation-specific, and can change in future versions. - If you are unsure, use <c>erl_term_len()</c>.</p> - <p>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:</p> - <taglist> - <tag><c>Tuples</c></tag> - <item>Need 5 bytes, plus the space for each element.</item> - <tag><c>Lists</c></tag> - <item>Need 5 bytes, plus the space for each element, and 1 - more byte for the empty list at the end.</item> - <tag><c>Strings and atoms</c></tag> - <item>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.</item> - <tag><c>Integers</c></tag> - <item>Need 5 bytes.</item> - <tag><c>Characters</c></tag> - <item>(Integers < 256) need 2 bytes.</item> - <tag><c>Floating point numbers</c></tag> - <item>Need 32 bytes.</item> - <tag><c>Pids</c></tag> - <item>Need 10 bytes, plus the space for the node name, which - is an atom.</item> - <tag><c>Ports and Refs</c></tag> - <item>Need 6 bytes, plus the space for the node name, which - is an atom.</item> - </taglist> - <p>The total space required is the result calculated - from the information above, plus 1 more byte for a - version identifier.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_ext_size(bufp)</nametext></name> - <fsummary>Count elements in encoded term.</fsummary> - <type> - <v>unsigned char *bufp;</v> - </type> - <desc> - <p>Returns the number of elements in an encoded term.</p> - </desc> - </func> - - <func> - <name since=""><ret>unsigned char</ret><nametext>erl_ext_type(bufp)</nametext></name> - <fsummary>Determine type of an encoded byte sequence.</fsummary> - <type> - <v>unsigned char *bufp;</v> - </type> - <desc> - <p>Identifies and returns the type of Erlang term encoded - in a buffer. It skips a trailing <em>magic</em> identifier.</p> - <p>Returns <c>0</c> if the type cannot be determined or - one of:</p> - <list type="bulleted"> - <item><c>ERL_INTEGER</c> - </item> - <item><c>ERL_ATOM</c> - </item> - <item><c>ERL_PID</c> (Erlang process identifier) - </item> - <item><c>ERL_PORT</c> - </item> - <item><c>ERL_REF</c> (Erlang reference) - </item> - <item><c>ERL_EMPTY_LIST</c> - </item> - <item><c>ERL_LIST</c> - </item> - <item><c>ERL_TUPLE</c> - </item> - <item><c>ERL_FLOAT</c> - </item> - <item><c>ERL_BINARY</c> - </item> - <item><c>ERL_FUNCTION</c> - </item> - </list> - </desc> - </func> - - <func> - <name since=""><ret>unsigned char *</ret><nametext>erl_peek_ext(bufp, pos)</nametext></name> - <fsummary>Step over encoded term.</fsummary> - <type> - <v>unsigned char *bufp;</v> - <v>int pos;</v> - </type> - <desc> - <p>This function is used for stepping over one or more - encoded terms in a buffer, to directly access later term.</p> - <list type="bulleted"> - <item><c>bufp</c> is a pointer to a buffer containing one - or more encoded Erlang terms.</item> - <item><c>pos</c> indicates how many terms to step over in - the buffer.</item> - </list> - <p>Returns a pointer to a subterm that can be - used in a later call to <c>erl_decode()</c> to retrieve - the term at that position. If there is no term, or - <c>pos</c> would exceed the size of the terms in the - buffer, <c>NULL</c> is returned.</p> - </desc> - </func> - - <func> - <name since=""><ret>int</ret><nametext>erl_term_len(t)</nametext></name> - <fsummary>Determine encoded size of term.</fsummary> - <type> - <v>ETERM *t;</v> - </type> - <desc> - <p>Determines the buffer space that would be - needed by <c>t</c> if it were encoded into Erlang external - format by <c>erl_encode()</c>.</p> - <p>Returns the size in bytes.</p> - </desc> - </func> - </funcs> -</cref> diff --git a/lib/erl_interface/doc/src/part_erl_interface.xml b/lib/erl_interface/doc/src/part_erl_interface.xml deleted file mode 100644 index e256cfa193..0000000000 --- a/lib/erl_interface/doc/src/part_erl_interface.xml +++ /dev/null @@ -1,33 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part xmlns:xi="http://www.w3.org/2001/XInclude"> - <header> - <copyright> - <year>1996</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>Erl_Interface User's Guide</title> - <prepared>Gordon Beaton</prepared> - <docno></docno> - <date>1998-11-30</date> - <rev>1.2</rev> - <file>part_erl_interface.sgml</file> - </header> - <xi:include href="erl_interface.xml"/> -</part> diff --git a/lib/erl_interface/doc/src/ref_man.xml b/lib/erl_interface/doc/src/ref_man.xml index a4f947c79f..d00868562f 100644 --- a/lib/erl_interface/doc/src/ref_man.xml +++ b/lib/erl_interface/doc/src/ref_man.xml @@ -31,22 +31,10 @@ <description> <note><p>The support for VxWorks is deprecated as of OTP 22, and will be removed in OTP 23.</p></note> - <note><p>The old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>) is deprecated as of OTP 22, and will be - removed in OTP 23. This does not apply to the <c>ei</c> - library. Reasonably new <c>gcc</c> compilers will issue deprecation - warnings. In order to disable these warnings, define the macro - <c>EI_NO_DEPR_WARN</c>.</p></note> </description> <xi:include href="ei.xml"/> <xi:include href="ei_connect.xml"/> <xi:include href="registry.xml"/> - <xi:include href="erl_connect.xml"/> - <xi:include href="erl_error.xml"/> - <xi:include href="erl_eterm.xml"/> - <xi:include href="erl_format.xml"/> - <xi:include href="erl_global.xml"/> - <xi:include href="erl_malloc.xml"/> - <xi:include href="erl_marshal.xml"/> - <xi:include href="erl_call.xml"/> + <xi:include href="ei_global.xml"/> + <xi:include href="erl_call_cmd.xml"/> </application> diff --git a/lib/erl_interface/doc/src/ref_man_ei.xml b/lib/erl_interface/doc/src/ref_man_ei.xml deleted file mode 100644 index d8d1deaea1..0000000000 --- a/lib/erl_interface/doc/src/ref_man_ei.xml +++ /dev/null @@ -1,53 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE application SYSTEM "application.dtd"> - -<application xmlns:xi="http://www.w3.org/2001/XInclude"> - <header> - <copyright> - <year>2002</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>EI Library Reference</title> - <prepared>Gordon Beaton</prepared> - <docno></docno> - <date>1998-11-30</date> - <rev>1.2</rev> - <file>ref_man_ei.xml</file> - </header> - <description> - <note><p>The support for VxWorks is deprecated as of OTP 22, and - will be removed in OTP 23.</p></note> - <note><p>The old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>) is deprecated as of OTP 22, and will be - removed in OTP 23. This does not apply to the <c>ei</c> - library. Reasonably new <c>gcc</c> compilers will issue deprecation - warnings. In order to disable these warnings, define the macro - <c>EI_NO_DEPR_WARN</c>.</p></note> - <note> - <p>By default, the <c>ei</c> library is only guaranteed - to be compatible with other Erlang/OTP components from the same - release as the <c>ei</c> library itself. See the documentation of the - <seealso marker="ei#ei_set_compat_rel">ei_set_compat_rel()</seealso> - function on how to communicate with Erlang/OTP components from earlier - releases.</p> - </note> - </description> - <xi:include href="ei.xml"/> - <xi:include href="ei_connect.xml"/> - <xi:include href="registry.xml"/> -</application> diff --git a/lib/erl_interface/doc/src/ref_man_erl_interface.xml b/lib/erl_interface/doc/src/ref_man_erl_interface.xml deleted file mode 100644 index 2b69d0fa74..0000000000 --- a/lib/erl_interface/doc/src/ref_man_erl_interface.xml +++ /dev/null @@ -1,60 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE application SYSTEM "application.dtd"> - -<application xmlns:xi="http://www.w3.org/2001/XInclude"> - <header> - <copyright> - <year>1996</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>Erl_Interface Library Reference</title> - <prepared>Gordon Beaton</prepared> - <docno></docno> - <date>1998-11-30</date> - <rev>1.2</rev> - <file>ref_man_erl_interface.xml</file> - </header> - <description> - <note><p>The support for VxWorks is deprecated as of OTP 22, and - will be removed in OTP 23.</p></note> - <note><p>The old legacy <c>erl_interface</c> library (functions - with prefix <c>erl_</c>) is deprecated as of OTP 22, and will be - removed in OTP 23. This does not apply to the <c>ei</c> - library. Reasonably new <c>gcc</c> compilers will issue deprecation - warnings. In order to disable these warnings, define the macro - <c>EI_NO_DEPR_WARN</c>.</p></note> - <p>The <c>erl_interface</c> library is a <c>C</c> interface library - for communication with <c>Erlang</c>.</p> - <note> - <p>By default, the <c>erl_interface</c> library is only guaranteed - to be compatible with other Erlang/OTP components from the same - release as the <c>erl_interface</c> library. See the documentation - of the - <seealso marker="erl_eterm#erl_set_compat_rel">erl_set_compat_rel()</seealso> - function on how to communicate with Erlang/OTP components from earlier - releases.</p> - </note> - </description> - <xi:include href="erl_connect.xml"/> - <xi:include href="erl_error.xml"/> - <xi:include href="erl_eterm.xml"/> - <xi:include href="erl_format.xml"/> - <xi:include href="erl_global.xml"/> - <xi:include href="erl_malloc.xml"/> - <xi:include href="erl_marshal.xml"/> -</application> |