diff options
Diffstat (limited to 'lib/erl_interface/doc/src')
21 files changed, 1212 insertions, 373 deletions
diff --git a/lib/erl_interface/doc/src/Makefile b/lib/erl_interface/doc/src/Makefile index 204a6051b2..507a84a453 100644 --- a/lib/erl_interface/doc/src/Makefile +++ b/lib/erl_interface/doc/src/Makefile @@ -1,8 +1,8 @@ # # %CopyrightBegin% -# -# Copyright Ericsson AB 1998-2016. All Rights Reserved. -# +# +# Copyright Ericsson AB 1998-2018. All Rights Reserved. +# # 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 @@ -14,7 +14,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# +# # %CopyrightEnd% # include $(ERL_TOP)/make/target.mk @@ -36,7 +36,7 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) # Target Specs # ---------------------------------------------------- -XML_REF1_FILES = erl_call.xml +XML_REF1_FILES = erl_call.xml XML_REF3_FILES = erl_connect.xml \ erl_error.xml \ erl_eterm.xml \ @@ -46,16 +46,14 @@ XML_REF3_FILES = erl_connect.xml \ erl_global.xml \ ei.xml \ ei_connect.xml \ - registry.xml + registry.xml BOOK_FILES = book.xml -XML_APPLICATION_FILES = ref_man.xml +XML_APPLICATION_FILES = ref_man.xml #ref_man_ei.xml ref_man_erl_interface.xml XML_PART_FILES = \ - part.xml \ - part_notes.xml \ - part_notes_history.xml -XML_CHAPTER_FILES = ei_users_guide.xml notes.xml notes_history.xml + 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) @@ -66,7 +64,7 @@ HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ INFO_FILE = ../../info -GIF_FILES = +GIF_FILES = MAN1_FILES = $(XML_REF1_FILES:%.xml=$(MAN1DIR)/%.1) MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) @@ -76,9 +74,9 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf # ---------------------------------------------------- -# FLAGS +# FLAGS # ---------------------------------------------------- -XML_FLAGS += +XML_FLAGS += # ---------------------------------------------------- # Targets @@ -98,10 +96,11 @@ man: $(MAN1_FILES) $(MAN3_FILES) gifs: $(GIF_FILES:%=$(HTMLDIR)/%) -debug opt: +debug opt: 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) @@ -110,7 +109,7 @@ clean clean_docs clean_tex: # ---------------------------------------------------- # Release Target -# ---------------------------------------------------- +# ---------------------------------------------------- include $(ERL_TOP)/make/otp_release_targets.mk release_docs_spec: docs @@ -127,4 +126,3 @@ release_docs_spec: docs release_spec: - diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml index ddfb4d88a8..70af5642da 100644 --- a/lib/erl_interface/doc/src/ei.xml +++ b/lib/erl_interface/doc/src/ei.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2001</year><year>2016</year> + <year>2001</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -35,6 +35,9 @@ <lib>ei</lib> <libsummary>Routines for handling the Erlang binary term format.</libsummary> <description> + <note><p>The support for VxWorks is deprecated as of OTP 22, and + will be removed in OTP 23.</p></note> + <p>The library <c>ei</c> contains macros and functions to encode and decode the Erlang binary term format.</p> @@ -124,7 +127,7 @@ typedef enum { <funcs> <func> - <name><ret>int</ret><nametext>ei_decode_atom(const char *buf, int *index, char *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_atom(const char *buf, int *index, char *p)</nametext></name> <fsummary>Decode an atom.</fsummary> <desc> <p>Decodes an atom from the binary format. The <c>NULL</c>-terminated @@ -134,7 +137,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_atom_as(const char *buf, int *index, char *p, int plen, erlang_char_encoding want, erlang_char_encoding* was, erlang_char_encoding* result)</nametext></name> + <name since="OTP R16B"><ret>int</ret><nametext>ei_decode_atom_as(const char *buf, int *index, char *p, int plen, erlang_char_encoding want, erlang_char_encoding* was, erlang_char_encoding* result)</nametext></name> <fsummary>Decode an atom.</fsummary> <desc> <p>Decodes an atom from the binary format. The <c>NULL</c>-terminated @@ -158,7 +161,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_bignum(const char *buf, int *index, mpz_t obj)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_bignum(const char *buf, int *index, mpz_t obj)</nametext></name> <fsummary>Decode a GMP arbitrary precision integer.</fsummary> <desc> <p>Decodes an integer in the binary format to a GMP @@ -168,7 +171,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_binary(const char *buf, int *index, void *p, long *len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_binary(const char *buf, int *index, void *p, long *len)</nametext></name> <fsummary>Decode a binary.</fsummary> <desc> <p>Decodes a binary from the binary format. Parameter @@ -180,7 +183,44 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_boolean(const char *buf, int *index, int *p)</nametext></name> + <name since="OTP 22.0"><ret>int</ret><nametext>ei_decode_bitstring(const char *buf, int *index, const char **pp, unsigned int *bitoffsp, size_t *nbitsp)</nametext></name> + <fsummary>Decode a bitstring.</fsummary> + <desc> + <p>Decodes a bit string from the binary format.</p> + <taglist> + <tag><c>pp</c></tag> + <item><p>Either <c>NULL</c> or <c>*pp</c> returns a pointer to + the first byte of the bit string. The returned bit string is + readable as long as the buffer pointed to by <c>buf</c> is + readable and not written to.</p> + </item> + <tag><c>bitoffsp</c></tag> + <item><p>Either <c>NULL</c> or <c>*bitoffsp</c> returns the + number of unused bits in the first byte pointed to by + <c>*pp</c>. The value of <c>*bitoffsp</c> is between 0 and 7. + Unused bits in the first byte are the most significant bits.</p> + </item> + <tag><c>nbitsp</c></tag> + <item><p>Either <c>NULL</c> or <c>*nbitsp</c> returns the length + of the bit string in <em>bits</em>.</p> + </item> + </taglist> + <p>Returns <c>0</c> if it was a bit string term.</p> + <p>The number of <em>bytes</em> pointed to by <c>*pp</c>, which are + part of the bit string, is <c>(*bitoffsp + *nbitsp + 7)/8</c>. If + <c>(*bitoffsp + *bitsp)%8 > 0</c> then only <c>(*bitoffsp + + *bitsp)%8</c> bits of the last byte are used. Unused bits in + the last byte are the least significant bits.</p> + <p>The values of unused bits in the first and last byte are undefined + and cannot be relied on.</p> + <p>Number of bits may be divisible by 8, which means a binary + decodable by <c>ei_decode_binary</c> is also decodable by + <c>ei_decode_bitstring</c>.</p> + </desc> + </func> + + <func> + <name since=""><ret>int</ret><nametext>ei_decode_boolean(const char *buf, int *index, int *p)</nametext></name> <fsummary>Decode a boolean.</fsummary> <desc> <p>Decodes a boolean value from the binary format. @@ -190,7 +230,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_char(const char *buf, int *index, char *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_char(const char *buf, int *index, char *p)</nametext></name> <fsummary>Decode an 8-bit integer between 0-255.</fsummary> <desc> <p>Decodes a char (8-bit) integer between 0-255 from the binary format. @@ -203,7 +243,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_double(const char *buf, int *index, double *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_double(const char *buf, int *index, double *p)</nametext></name> <fsummary>Decode a double.</fsummary> <desc> <p>Decodes a double-precision (64-bit) floating @@ -212,7 +252,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_ei_term(const char* buf, int* index, ei_term* term)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_ei_term(const char* buf, int* index, ei_term* term)</nametext></name> <fsummary>Decode a term, without previous knowledge of type.</fsummary> <desc> <p>Decodes any term, or at least tries to. If the term @@ -233,8 +273,8 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_fun(const char *buf, int *index, erlang_fun *p)</nametext></name> - <name><ret>void</ret><nametext>free_fun(erlang_fun* f)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_fun(const char *buf, int *index, erlang_fun *p)</nametext></name> + <name since=""><ret>void</ret><nametext>free_fun(erlang_fun* f)</nametext></name> <fsummary>Decode a fun.</fsummary> <desc> <p>Decodes a fun from the binary format. Parameter @@ -248,7 +288,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_list_header(const char *buf, int *index, int *arity)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_list_header(const char *buf, int *index, int *arity)</nametext></name> <fsummary>Decode a list.</fsummary> <desc> <p>Decodes a list header from the binary @@ -265,7 +305,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_long(const char *buf, int *index, long *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_long(const char *buf, int *index, long *p)</nametext></name> <fsummary>Decode integer.</fsummary> <desc> <p>Decodes a long integer from the binary format. @@ -275,7 +315,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_longlong(const char *buf, int *index, long long *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_longlong(const char *buf, int *index, long long *p)</nametext></name> <fsummary>Decode integer.</fsummary> <desc> <p>Decodes a GCC <c>long long</c> or Visual C++ @@ -286,7 +326,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_map_header(const char *buf, int *index, int *arity)</nametext></name> + <name since="OTP 17.0"><ret>int</ret><nametext>ei_decode_map_header(const char *buf, int *index, int *arity)</nametext></name> <fsummary>Decode a map.</fsummary> <desc> <p>Decodes a map header from the binary @@ -299,7 +339,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_pid(const char *buf, int *index, erlang_pid *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_pid(const char *buf, int *index, erlang_pid *p)</nametext></name> <fsummary>Decode a <c>pid</c>.</fsummary> <desc> <p>Decodes a process identifier (pid) from the binary format.</p> @@ -307,7 +347,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_port(const char *buf, int *index, erlang_port *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_port(const char *buf, int *index, erlang_port *p)</nametext></name> <fsummary>Decode a port.</fsummary> <desc> <p>Decodes a port identifier from the binary format.</p> @@ -315,7 +355,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_ref(const char *buf, int *index, erlang_ref *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_ref(const char *buf, int *index, erlang_ref *p)</nametext></name> <fsummary>Decode a reference.</fsummary> <desc> <p>Decodes a reference from the binary format.</p> @@ -323,7 +363,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_string(const char *buf, int *index, char *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_string(const char *buf, int *index, char *p)</nametext></name> <fsummary>Decode a string.</fsummary> <desc> <p>Decodes a string from the binary format. A @@ -338,7 +378,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_term(const char *buf, int *index, void *t)</nametext></name> + <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 @@ -346,13 +386,15 @@ typedef enum { <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> - <p>Notice that this function is located in the <c>Erl_Interface</c> - library.</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><ret>int</ret><nametext>ei_decode_trace(const char *buf, int *index, erlang_trace *p)</nametext></name> + <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> <p>Decodes an Erlang trace token from the binary format.</p> @@ -360,7 +402,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_tuple_header(const char *buf, int *index, int *arity)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_tuple_header(const char *buf, int *index, int *arity)</nametext></name> <fsummary>Decode a tuple.</fsummary> <desc> <p>Decodes a tuple header, the number of elements @@ -370,7 +412,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_ulong(const char *buf, int *index, unsigned long *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_ulong(const char *buf, int *index, unsigned long *p)</nametext></name> <fsummary>Decode unsigned integer.</fsummary> <desc> <p>Decodes an unsigned long integer from the binary format. @@ -380,7 +422,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_ulonglong(const char *buf, int *index, unsigned long long *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_ulonglong(const char *buf, int *index, unsigned long long *p)</nametext></name> <fsummary>Decode unsigned integer.</fsummary> <desc> <p>Decodes a GCC <c>unsigned long long</c> or Visual C++ @@ -390,7 +432,7 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_decode_version(const char *buf, int *index, int *version)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_decode_version(const char *buf, int *index, int *version)</nametext></name> <fsummary>Decode an empty list (<c>nil</c>).</fsummary> <desc> <p>Decodes the version magic number for the @@ -400,10 +442,10 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_encode_atom(char *buf, int *index, const char *p)</nametext></name> - <name><ret>int</ret><nametext>ei_encode_atom_len(char *buf, int *index, const char *p, int len)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_atom(ei_x_buff* x, const char *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_atom_len(ei_x_buff* x, const char *p, int len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_atom(char *buf, int *index, const char *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_atom_len(char *buf, int *index, const char *p, int len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_atom(ei_x_buff* x, const char *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_atom_len(ei_x_buff* x, const char *p, int len)</nametext></name> <fsummary>Encode an atom.</fsummary> <desc> <p>Encodes an atom in the binary format. Parameter <c>p</c> @@ -415,34 +457,28 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_encode_atom_as(char *buf, int *index, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> - <name><ret>int</ret><nametext>ei_encode_atom_len_as(char *buf, int *index, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_atom_as(ei_x_buff* x, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_atom_len_as(ei_x_buff* x, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> + <name since="OTP R16B"><ret>int</ret><nametext>ei_encode_atom_as(char *buf, int *index, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> + <name since="OTP R16B"><ret>int</ret><nametext>ei_encode_atom_len_as(char *buf, int *index, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> + <name since="OTP R16B"><ret>int</ret><nametext>ei_x_encode_atom_as(ei_x_buff* x, const char *p, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> + <name since="OTP R16B"><ret>int</ret><nametext>ei_x_encode_atom_len_as(ei_x_buff* x, const char *p, int len, erlang_char_encoding from_enc, erlang_char_encoding to_enc)</nametext></name> <fsummary>Encode an atom.</fsummary> <desc> - <p>Encodes an atom in the binary format with character encoding - <seealso marker="#erlang_char_encoding"><c>to_enc</c></seealso> - (Latin-1 or UTF-8). Parameter <c>p</c> is the name of the atom with + <p>Encodes an atom in the binary format. Parameter <c>p</c> is the name of the atom with character encoding <seealso marker="#erlang_char_encoding"><c>from_enc</c></seealso> (ASCII, Latin-1, or UTF-8). The name must either be <c>NULL</c>-terminated or - a function variant with a <c>len</c> parameter must be used. - If <c>to_enc</c> is set to the bitwise OR'd combination - <c>(ERLANG_LATIN1|ERLANG_UTF8)</c>, UTF-8 encoding is only used if the - atom string cannot be represented in Latin-1 encoding.</p> - <p>The encoding fails if <c>p</c> is an invalid string in encoding - <c>from_enc</c>, if the string is too long, or if it cannot be - represented with character encoding <c>to_enc</c>.</p> - <p>These functions were introduced in Erlang/OTP R16 as part of a first - step to support UTF-8 atoms. Atoms encoded with <c>ERLANG_UTF8</c> - cannot be decoded by earlier releases than R16.</p> + a function variant with a <c>len</c> parameter must be used.</p> + <p>The encoding fails if <c>p</c> is not a valid string in encoding + <c>from_enc</c>.</p> + + <p>Argument <c>to_enc</c> is ignored. As from Erlang/OTP 20 the encoding is always + done in UTF-8 which is readable by nodes as old as Erlang/OTP R16.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_encode_bignum(char *buf, int *index, mpz_t obj)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_bignum(ei_x_buff *x, mpz_t obj)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_bignum(char *buf, int *index, mpz_t obj)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_bignum(ei_x_buff *x, mpz_t obj)</nametext></name> <fsummary>Encode an arbitrary precision integer.</fsummary> <desc> <p>Encodes a GMP <c>mpz_t</c> integer to binary format. @@ -452,8 +488,8 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_encode_binary(char *buf, int *index, const void *p, long len)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_binary(ei_x_buff* x, const void *p, long len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_binary(char *buf, int *index, const void *p, long len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_binary(ei_x_buff* x, const void *p, long len)</nametext></name> <fsummary>Encode a binary.</fsummary> <desc> <p>Encodes a binary in the binary format. The data is at @@ -462,8 +498,30 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_encode_boolean(char *buf, int *index, int p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_boolean(ei_x_buff* x, int p)</nametext></name> + <name since="OTP 22.0"><ret>int</ret> + <nametext>ei_encode_bitstring(char *buf, int *index, const char *p, size_t bitoffs, size_t nbits)</nametext></name> + <name since="OTP 22.0"><ret>int</ret> + <nametext>ei_x_encode_bitstring(ei_x_buff* x, const char *p, size_t bitoffs, size_t nbits)</nametext></name> + <fsummary>Encode a bitstring.</fsummary> + <desc> + <p>Encodes a bit string in the binary format.</p> + <p>The data is at <c>p</c>. The length of the bit string is <c>nbits</c> + bits. The first <c>bitoffs</c> bits of the data at <c>p</c> are unused. + The first byte which is part of the bit string is + <c>p[bitoffs/8]</c>. The <c>bitoffs%8</c> most significant bits of + the first byte <c>p[bitoffs/8]</c> are unused.</p> + <p>The number of bytes which is part of the bit string is <c>(bitoffs + + nbits + 7)/8</c>. If <c>(bitoffs + nbits)%8 > 0</c> then only <c>(bitoffs + + nbits)%8</c> bits of the last byte are used. Unused bits in + the last byte are the least significant bits.</p> + <p>The values of unused bits are disregarded and does not need to be + cleared.</p> + </desc> + </func> + + <func> + <name since=""><ret>int</ret><nametext>ei_encode_boolean(char *buf, int *index, int p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_boolean(ei_x_buff* x, int p)</nametext></name> <fsummary>Encode a boolean.</fsummary> <desc> <p>Encodes a boolean value as the atom <c>true</c> if @@ -473,8 +531,8 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_encode_char(char *buf, int *index, char p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_char(ei_x_buff* x, char p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_char(char *buf, int *index, char p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_char(ei_x_buff* x, char p)</nametext></name> <fsummary>Encode an 8-bit integer between 0-255.</fsummary> <desc> <p>Encodes a char (8-bit) as an integer between 0-255 in the binary @@ -487,8 +545,8 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_encode_double(char *buf, int *index, double p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_double(ei_x_buff* x, double p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_double(char *buf, int *index, double p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_double(ei_x_buff* x, double p)</nametext></name> <fsummary>Encode a double float.</fsummary> <desc> <p>Encodes a double-precision (64-bit) floating point number in @@ -499,8 +557,8 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_encode_empty_list(char* buf, int* index)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_empty_list(ei_x_buff* x)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_empty_list(char* buf, int* index)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_empty_list(ei_x_buff* x)</nametext></name> <fsummary>Encode an empty list (<c>nil</c>).</fsummary> <desc> <p>Encodes an empty list. It is often used at the tail of a list.</p> @@ -508,8 +566,8 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_encode_fun(char *buf, int *index, const erlang_fun *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_fun(char *buf, int *index, const erlang_fun *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_fun(ei_x_buff* x, const erlang_fun* fun)</nametext></name> <fsummary>Encode a fun.</fsummary> <desc> <p>Encodes a fun in the binary format. Parameter <c>p</c> @@ -521,8 +579,8 @@ typedef enum { </func> <func> - <name><ret>int</ret><nametext>ei_encode_list_header(char *buf, int *index, int arity)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_list_header(ei_x_buff* x, int arity)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_list_header(char *buf, int *index, int arity)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_list_header(ei_x_buff* x, int arity)</nametext></name> <fsummary>Encode a list.</fsummary> <desc> <p>Encodes a list header, with a specified @@ -558,8 +616,8 @@ ei_x_encode_empty_list(&x);</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_long(char *buf, int *index, long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_long(ei_x_buff* x, long p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_long(char *buf, int *index, long p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_long(ei_x_buff* x, long p)</nametext></name> <fsummary>Encode integer.</fsummary> <desc> <p>Encodes a long integer in the binary format. @@ -569,8 +627,8 @@ ei_x_encode_empty_list(&x);</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_longlong(char *buf, int *index, long long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_longlong(ei_x_buff* x, long long p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_longlong(char *buf, int *index, long long p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_longlong(ei_x_buff* x, long long p)</nametext></name> <fsummary>Encode integer.</fsummary> <desc> <p>Encodes a GCC <c>long long</c> or Visual C++ @@ -580,8 +638,8 @@ ei_x_encode_empty_list(&x);</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_map_header(char *buf, int *index, int arity)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_map_header(ei_x_buff* x, int arity)</nametext></name> + <name since="OTP 17.0"><ret>int</ret><nametext>ei_encode_map_header(char *buf, int *index, int arity)</nametext></name> + <name since="OTP 17.0"><ret>int</ret><nametext>ei_x_encode_map_header(ei_x_buff* x, int arity)</nametext></name> <fsummary>Encode a map.</fsummary> <desc> <p>Encodes a map header, with a specified arity. The next @@ -601,8 +659,8 @@ ei_x_encode_string(&x, "Banana");</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_pid(char *buf, int *index, const erlang_pid *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_pid(ei_x_buff* x, const erlang_pid *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_pid(char *buf, int *index, const erlang_pid *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_pid(ei_x_buff* x, const erlang_pid *p)</nametext></name> <fsummary>Encode a pid.</fsummary> <desc> <p>Encodes an Erlang process identifier (pid) in the binary @@ -613,8 +671,8 @@ ei_x_encode_string(&x, "Banana");</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_port(char *buf, int *index, const erlang_port *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_port(ei_x_buff* x, const erlang_port *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_port(char *buf, int *index, const erlang_port *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_port(ei_x_buff* x, const erlang_port *p)</nametext></name> <fsummary>Encode a port.</fsummary> <desc> <p>Encodes an Erlang port in the binary format. Parameter @@ -625,8 +683,8 @@ ei_x_encode_string(&x, "Banana");</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_ref(char *buf, int *index, const erlang_ref *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_ref(char *buf, int *index, const erlang_ref *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_ref(ei_x_buff* x, const erlang_ref *p)</nametext></name> <fsummary>Encode a ref.</fsummary> <desc> <p>Encodes an Erlang reference in the binary format. Parameter @@ -637,10 +695,10 @@ ei_x_encode_string(&x, "Banana");</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_string(char *buf, int *index, const char *p)</nametext></name> - <name><ret>int</ret><nametext>ei_encode_string_len(char *buf, int *index, const char *p, int len)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_string(ei_x_buff* x, const char *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_string(char *buf, int *index, const char *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_string_len(char *buf, int *index, const char *p, int len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_string(ei_x_buff* x, const char *p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_string_len(ei_x_buff* x, const char* s, int len)</nametext></name> <fsummary>Encode a string.</fsummary> <desc> <p>Encodes a string in the binary format. (A string in Erlang @@ -651,19 +709,23 @@ ei_x_encode_string(&x, "Banana");</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_term(char *buf, int *index, void *t)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_term(ei_x_buff* x, void *t)</nametext></name> + <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><ret>int</ret><nametext>ei_encode_trace(char *buf, int *index, const erlang_trace *p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_trace(ei_x_buff* x, const erlang_trace *p)</nametext></name> + <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> <fsummary>Encode a trace token.</fsummary> <desc> <p>Encodes an Erlang trace token in the binary format. @@ -674,8 +736,8 @@ ei_x_encode_string(&x, "Banana");</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_tuple_header(char *buf, int *index, int arity)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_tuple_header(ei_x_buff* x, int arity)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_tuple_header(char *buf, int *index, int arity)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_tuple_header(ei_x_buff* x, int arity)</nametext></name> <fsummary>Encode a tuple.</fsummary> <desc> <p>Encodes a tuple header, with a specified @@ -693,8 +755,8 @@ ei_encode_tuple_header(buf, &i, 0);</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_ulong(char *buf, int *index, unsigned long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_ulong(ei_x_buff* x, unsigned long p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_ulong(char *buf, int *index, unsigned long p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_ulong(ei_x_buff* x, unsigned long p)</nametext></name> <fsummary>Encode unsigned integer.</fsummary> <desc> <p>Encodes an unsigned long integer in the binary format. @@ -704,8 +766,8 @@ ei_encode_tuple_header(buf, &i, 0);</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_ulonglong(char *buf, int *index, unsigned long long p)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_ulonglong(char *buf, int *index, unsigned long long p)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_ulonglong(ei_x_buff* x, unsigned long long p)</nametext></name> <fsummary>Encode unsigned integer.</fsummary> <desc> <p>Encodes a GCC <c>unsigned long long</c> or Visual C++ @@ -715,8 +777,8 @@ ei_encode_tuple_header(buf, &i, 0);</pre> </func> <func> - <name><ret>int</ret><nametext>ei_encode_version(char *buf, int *index)</nametext></name> - <name><ret>int</ret><nametext>ei_x_encode_version(ei_x_buff* x)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_encode_version(char *buf, int *index)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_encode_version(ei_x_buff* x)</nametext></name> <fsummary>Encode version.</fsummary> <desc> <p>Encodes a version magic number for the binary format. Must @@ -725,22 +787,37 @@ ei_encode_tuple_header(buf, &i, 0);</pre> </func> <func> - <name><ret>int</ret><nametext>ei_get_type(const char *buf, const int *index, int *type, int *size)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_get_type(const char *buf, const int *index, int *type, int *size)</nametext></name> <fsummary>Fetch the type and size of an encoded term.</fsummary> <desc> - <p>Returns the type in <c>type</c> and size in - <c>size</c> of the encoded term. For strings and atoms, + <p>Returns the type in <c>*type</c> and size in + <c>*size</c> of the encoded term. For strings and atoms, size is the number of characters <em>not</em> including the - terminating <c>NULL</c>. For binaries, <c>size</c> is the number of - bytes. For lists and tuples, <c>size</c> is the arity of - the object. For other types, <c>size</c> is 0. In all + terminating <c>NULL</c>. For binaries and bitstrings, <c>*size</c> is + the number of bytes. For lists, tuples and maps, <c>*size</c> is the + arity of the object. For other types, <c>*size</c> is 0. In all cases, <c>index</c> is left unchanged.</p> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_print_term(FILE* fp, const char* buf, int* index)</nametext></name> - <name><ret>int</ret><nametext>ei_s_print_term(char** s, const char* buf, int* index)</nametext></name> + <name since="OTP 21.3"><ret>int</ret><nametext>ei_init(void)</nametext></name> + <fsummary>Initialize the ei library.</fsummary> + <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> + <p>On success zero is returned. On failure a posix error code is returned.</p> + </desc> + </func> + + <func> + <name since=""><ret>int</ret><nametext>ei_print_term(FILE* fp, const char* buf, int* index)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_s_print_term(char** s, const char* buf, int* index)</nametext></name> <fsummary>Print a term in clear text.</fsummary> <desc> <p>Prints a term, in clear text, to the file @@ -765,42 +842,60 @@ ei_encode_tuple_header(buf, &i, 0);</pre> </func> <func> - <name><ret>void</ret><nametext>ei_set_compat_rel(release_number)</nametext></name> + <name since=""><ret>void</ret><nametext>ei_set_compat_rel(release_number)</nametext></name> <fsummary>Set the ei library in compatibility mode.</fsummary> <type> <v>unsigned release_number;</v> </type> <desc> <marker id="ei_set_compat_rel"></marker> - <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. For example, - <c>ei</c> from - Erlang/OTP R10 is not compatible with an Erlang emulator - from Erlang/OTP R9 by default.</p> - <p>A call to <c>ei_set_compat_rel(release_number)</c> sets - the <c>ei</c> library in compatibility mode of release - <c>release_number</c>. Valid range of - <c>release_number</c> - is <c>[7, current release]</c>. This makes it possible to - communicate with Erlang/OTP components from earlier releases.</p> + <p>In general, the <c>ei</c> library is guaranteed + to be compatible with other Erlang/OTP components that are 2 major + releases older or newer than the <c>ei</c> library itself.</p> + <p>Sometimes an exception to the above rule has to be made to make new + features (or even bug fixes) possible. A call to + <c>ei_set_compat_rel(release_number)</c> sets + the <c>ei</c> library in compatibility mode of OTP release + <c>release_number</c>.</p> + <p>The only useful value for <c>release_number</c> is currently + <c>21</c>. This will only be useful and have an effect if <em>bit + strings</em> or <em>export funs</em> are received from a connected + node. Before OTP 22, bit strings and export funs were not supported by + <c>ei</c>. They were instead encoded using an undocumented fallback + tuple format when sent from the emulator to <c>ei</c>:</p> + <taglist> + <tag><c>Bit string</c></tag> + <item><p>The term <c><<42, 1:1>></c> was encoded as + <c>{<<42, 128>>, 1}</c>. The first element of the tuple is a + binary and the second element denotes how many bits of the last bytes + are part of the bit string. In this example only the most significant + bit of the last byte (128) is part of the bit string.</p> + </item> + <tag><c>Export fun</c></tag> + <item><p>The term <c>fun lists:map/2</c> was encoded as + <c>{lists,map}</c>. A tuple with the module, function and a missing + arity.</p> + </item> + </taglist> + <p>If <c>ei_set_compat_rel(21)</c> is <em>not</em> called then a connected + emulator will send bit strings and export funs correctly encoded. The + functions <seealso marker="#ei_decode_bitstring"><c>ei_decode_bitstring</c></seealso> + and <seealso marker="#ei_decode_fun"><c>ei_decode_fun</c></seealso> + has to be used to decode such terms. Calling + <c>ei_set_compat_rel(21)</c> should only be done as a workaround to + keep an old implementation alive, which expects to receive the + undocumented tuple formats for bit strings and/or export funs. + </p> <note> <p>If this function is called, it can only be called once and must be called before any other functions in the <c>ei</c> library are called.</p> </note> - <warning> - <p>You can run into trouble if this feature is used - carelessly. Always ensure that all communicating - components are either from the same Erlang/OTP release, or - from release X and release Y where all components - from release Y are in compatibility mode of release X.</p> - </warning> </desc> </func> <func> - <name><ret>int</ret><nametext>ei_skip_term(const char* buf, int* index)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_skip_term(const char* buf, int* index)</nametext></name> <fsummary>Skip a term.</fsummary> <desc> <p>Skips a term in the specified buffer; @@ -821,8 +916,8 @@ ei_encode_tuple_header(buf, &i, 0);</pre> </func> <func> - <name><ret>int</ret><nametext>ei_x_append(ei_x_buff* x, const ei_x_buff* x2)</nametext></name> - <name><ret>int</ret><nametext>ei_x_append_buf(ei_x_buff* x, const char* buf, int len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_append(ei_x_buff* x, const ei_x_buff* x2)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_append_buf(ei_x_buff* x, const char* buf, int len)</nametext></name> <fsummary>Append a buffer at the end.</fsummary> <desc> <p>Appends data at the end of buffer <c>x</c>.</p> @@ -830,8 +925,8 @@ ei_encode_tuple_header(buf, &i, 0);</pre> </func> <func> - <name><ret>int</ret><nametext>ei_x_format(ei_x_buff* x, const char* fmt, ...)</nametext></name> - <name><ret>int</ret><nametext>ei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... )</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_format(ei_x_buff* x, const char* fmt, ...)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_format_wo_ver(ei_x_buff* x, const char *fmt, ... )</nametext></name> <fsummary>Format a term from a format string and parameters.</fsummary> <desc> <p>Formats a term, given as a string, to a buffer. @@ -859,7 +954,7 @@ encodes the tuple {numbers,12,3.14159}</pre> </func> <func> - <name><ret>int</ret><nametext>ei_x_free(ei_x_buff* x)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_free(ei_x_buff* x)</nametext></name> <fsummary>Free a buffer.</fsummary> <desc> <p>Frees an <c>ei_x_buff</c> buffer. @@ -868,8 +963,8 @@ encodes the tuple {numbers,12,3.14159}</pre> </func> <func> - <name><ret>int</ret><nametext>ei_x_new(ei_x_buff* x)</nametext></name> - <name><ret>int</ret><nametext>ei_x_new_with_version(ei_x_buff* x)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_new(ei_x_buff* x)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_x_new_with_version(ei_x_buff* x)</nametext></name> <fsummary>Allocate a new buffer.</fsummary> <desc> <p>Allocates a new <c>ei_x_buff</c> buffer. The diff --git a/lib/erl_interface/doc/src/ei_connect.xml b/lib/erl_interface/doc/src/ei_connect.xml index 607a7cbff4..795f1249b3 100644 --- a/lib/erl_interface/doc/src/ei_connect.xml +++ b/lib/erl_interface/doc/src/ei_connect.xml @@ -34,6 +34,9 @@ <lib>ei_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> + <p>This module enables C-programs to communicate with Erlang nodes, using the Erlang distribution over TCP/IP.</p> @@ -85,20 +88,288 @@ the <c>_tmo</c> suffix.</p> </section> + <section> + <marker id="ussi"/> + <title>User Supplied Socket Implementation</title> + <p>By default <c>ei</c> supplies a TCP/IPv4 socket interface + that is used when communicating. The user can however plug in + his/her own IPv4 socket implementation. This, for example, in order + to communicate over TLS. A user supplied socket implementation + is plugged in by passing a + <seealso marker="#ei_socket_callbacks">callback structure</seealso> + to either + <seealso marker="#ei_connect_init"><c>ei_connect_init_ussi()</c></seealso> + or + <seealso marker="#ei_connect_init"><c>ei_connect_xinit_ussi()</c></seealso>.</p> + + <p>All callbacks in the <c>ei_socket_callbacks</c> structure + <em>should</em> return zero on success; and a posix error + code on failure.</p> + + <p>The <c>addr</c> argument of the <c>listen</c>, <c>accept</c>, + and <c>connect</c> callbacks refer to appropriate address + structure for currently used protocol. Currently <c>ei</c> + only supports IPv4. That is, at this time <c>addr</c> always + points to a <c>struct sockaddr_in</c> structure.</p> + + <p>The <c>ei_socket_callbacks</c> structure may be enlarged in + the future. All fields not set, <em>needs</em> to be zeroed out.</p> + + <marker id="ei_socket_callbacks"/> + <code type="none"><![CDATA[ +typedef struct { + int flags; + int (*socket)(void **ctx, void *setup_ctx); + int (*close)(void *ctx); + int (*listen)(void *ctx, void *addr, int *len, int backlog); + int (*accept)(void **ctx, void *addr, int *len, unsigned tmo); + int (*connect)(void *ctx, void *addr, int len, unsigned tmo); + int (*writev)(void *ctx, const void *iov, int iovcnt, ssize_t *len, unsigned tmo); + int (*write)(void *ctx, const char *buf, ssize_t *len, unsigned tmo); + int (*read)(void *ctx, char *buf, ssize_t *len, unsigned tmo); + int (*handshake_packet_header_size)(void *ctx, int *sz); + int (*connect_handshake_complete)(void *ctx); + int (*accept_handshake_complete)(void *ctx); + int (*get_fd)(void *ctx, int *fd); +} ei_socket_callbacks; + ]]></code> + + <taglist> + + <tag><c>flags</c></tag> + <item> + <p>Flags informing <c>ei</c> about the behaviour of the + callbacks. Flags should be bitwise or:ed together. If no flag, + is set, the <c>flags</c> field should contain <c>0</c>. Currently, + supported flags:</p> + <taglist> + <tag><c>EI_SCLBK_FLG_FULL_IMPL</c></tag> + <item> + <p> + If set, the <c>accept()</c>, <c>connect()</c>, + <c>writev()</c>, <c>write()</c>, and <c>read()</c> callbacks + implements timeouts. The timeout is passed in the <c>tmo</c> + argument and is given in milli seconds. Note that the + <c>tmo</c> argument to these callbacks differ from the + timeout arguments in the <c>ei</c> API. Zero means a zero + timeout. That is, poll and timeout immediately unless the + operation is successful. <c>EI_SCLBK_INF_TMO</c> + (max <c>unsigned</c>) means infinite timeout. The file + descriptor is in blocking mode when a callback is called, + and it must be in blocking mode when the callback returns. + </p> + <p> + If not set, <c>ei</c> will implement the timeout using + <c>select()</c> in order to determine when to call the + callbacks and when to time out. The <c>tmo</c> arguments + of the <c>accept()</c>, <c>connect()</c>, <c>writev()</c>, + <c>write()</c>, and <c>read()</c> callbacks should be + ignored. The callbacks may be called in non-blocking mode. + The callbacks are not allowed to change between blocking + and non-blocking mode. In order for this to work, + <c>select()</c> needs to interact with the socket primitives + used the same way as it interacts with the ordinary socket + primitives. If this is not the case, the callbacks + <em>need</em> to implement timeouts and this flag should + be set. + </p> + </item> + </taglist> + <p>More flags may be introduced in the future.</p> + </item> + + <tag><c>int (*socket)(void **ctx, void *setup_ctx)</c></tag> + <item> + <p>Create a socket and a context for the socket.</p> + + <p>On success it should set <c>*ctx</c> to point to a context for + the created socket. This context will be passed to all other + socket callbacks. This function will be passed the same + <c>setup_context</c> as passed to the preceeding + <seealso marker="#ei_connect_init"><c>ei_connect_init_ussi()</c></seealso> + or + <seealso marker="#ei_connect_init"><c>ei_connect_xinit_ussi()</c></seealso> + call.</p> + + <note><p>During the lifetime of a socket, the pointer <c>*ctx</c> + <em>has</em> to remain the same. That is, it cannot later be + relocated.</p></note> + + <p>This callback is mandatory.</p> + </item> + + <tag><c>int (*close)(void *ctx)</c></tag> + <item> + <p>Close the socket identified by <c>ctx</c> and destroy the context.</p> + + <p>This callback is mandatory.</p> + </item> + + <tag><c>int (*listen)(void *ctx, void *addr, int *len, int backlog)</c></tag> + <item> + <p>Bind the socket identified by <c>ctx</c> to a local interface + and then listen on it.</p> + + <p>The <c>addr</c> and <c>len</c> arguments are both input and output + arguments. When called <c>addr</c> points to an address structure of + lenght <c>*len</c> containing information on how to bind the socket. + Uppon return this callback should have updated the structure referred + by <c>addr</c> with information on how the socket actually was bound. + <c>*len</c> should be updated to reflect the size of <c>*addr</c> + updated. <c>backlog</c> identifies the size of the backlog for the + listen socket.</p> + + <p>This callback is mandatory.</p> + </item> + + <tag><c>int (*accept)(void **ctx, void *addr, int *len, unsigned tmo)</c></tag> + <item> + <p>Accept connections on the listen socket identified by + <c>*ctx</c>.</p> + + <p>When a connection is accepted, a new context for the accepted + connection should be created and <c>*ctx</c> should be updated + to point to the new context for the accepted connection. When + called <c>addr</c> points to an uninitialized address structure + of lenght <c>*len</c>. Uppon return this callback should have + updated this structure with information about the client address. + <c>*len</c> should be updated to reflect the size of <c>*addr</c> + updated. + </p> + + <p>If the <c>EI_SCLBK_FLG_FULL_IMPL</c> flag has been set, + <c>tmo</c> contains timeout time in milliseconds.</p> + + <note><p>During the lifetime of a socket, the pointer <c>*ctx</c> + <em>has</em> to remain the same. That is, it cannot later be + relocated.</p></note> + + <p>This callback is mandatory.</p> + </item> + + <tag><c>int (*connect)(void *ctx, void *addr, int len, unsigned tmo)</c></tag> + <item> + <p>Connect the socket identified by <c>ctx</c> to the address + identified by <c>addr</c>.</p> + + <p>When called <c>addr</c> points to an address structure of + lenght <c>len</c> containing information on where to connect.</p> + + <p>If the <c>EI_SCLBK_FLG_FULL_IMPL</c> flag has been set, + <c>tmo</c> contains timeout time in milliseconds.</p> + + <p>This callback is mandatory.</p> + </item> + + <tag><c>int (*writev)(void *ctx, const void *iov, long iovcnt, ssize_t *len, unsigned tmo)</c></tag> + <item> + <p>Write data on the connected socket identified by <c>ctx</c>.</p> + + <p><c>iov</c> points to an array of <c>struct iovec</c> structures of + length <c>iovcnt</c> containing data to write to the socket. On success, + this callback should set <c>*len</c> to the amount of bytes successfully + written on the socket.</p> + + <p>If the <c>EI_SCLBK_FLG_FULL_IMPL</c> flag has been set, + <c>tmo</c> contains timeout time in milliseconds.</p> + + <p>This callback is optional. Set the <c>writev</c> field + in the the <c>ei_socket_callbacks</c> structure to <c>NULL</c> if not + implemented.</p> + </item> + + <tag><c>int (*write)(void *ctx, const char *buf, ssize_t *len, unsigned tmo)</c></tag> + <item> + <p>Write data on the connected socket identified by <c>ctx</c>.</p> + + <p>When called <c>buf</c> points to a buffer of length <c>*len</c> + containing the data to write on the socket. On success, this callback + should set <c>*len</c> to the amount of bytes successfully written on + the socket.</p> + + <p>If the <c>EI_SCLBK_FLG_FULL_IMPL</c> flag has been set, + <c>tmo</c> contains timeout time in milliseconds.</p> + + <p>This callback is mandatory.</p> + </item> + + <tag><c>int (*read)(void *ctx, char *buf, ssize_t *len, unsigned tmo)</c></tag> + <item> + <p>Read data on the connected socket identified by <c>ctx</c>.</p> + + <p><c>buf</c> points to a buffer of length <c>*len</c> where the + read data should be placed. On success, this callback should update + <c>*len</c> to the amount of bytes successfully read on the socket.</p> + + <p>If the <c>EI_SCLBK_FLG_FULL_IMPL</c> flag has been set, + <c>tmo</c> contains timeout time in milliseconds.</p> + + <p>This callback is mandatory.</p> + </item> + + <tag><c>int (*handshake_packet_header_size)(void *ctx, int *sz)</c></tag> + <item> + <p>Inform about handshake packet header size to use during the Erlang + distribution handshake.</p> + + <p>On success, <c>*sz</c> should be set to the handshake packet header + size to use. Valid values are <c>2</c> and <c>4</c>. Erlang TCP + distribution use a handshake packet size of <c>2</c> and Erlang TLS + distribution use a handshake packet size of <c>4</c>.</p> + + <p>This callback is mandatory.</p> + </item> + + <tag><c>int (*connect_handshake_complete)(void *ctx)</c></tag> + <item> + <p>Called when a locally started handshake has completed successfully.</p> + + <p>This callback is optional. Set the <c>connect_handshake_complete</c> field + in the <c>ei_socket_callbacks</c> structure to <c>NULL</c> if not implemented.</p> + </item> + + <tag><c>int (*accept_handshake_complete)(void *ctx)</c></tag> + <item> + <p>Called when a remotely started handshake has completed successfully.</p> + + <p>This callback is optional. Set the <c>accept_handshake_complete</c> field in + the <c>ei_socket_callbacks</c> structure to <c>NULL</c> if not implemented.</p> + </item> + + <tag><c>int (*get_fd)(void *ctx, int *fd)</c></tag> + <item> + <p>Inform about file descriptor used by the socket which is identified + by <c>ctx</c>.</p> + + <note><p>During the lifetime of a socket, the file descriptor + <em>has</em> to remain the same. That is, repeated calls to this + callback with the same context <c>should</c> always report the same + file descriptor.</p> + <p>The file descriptor <em>has</em> to be a real file descriptor. + That is, no other operation should be able to get the same file + descriptor until it has been released by the <c>close()</c> + callback.</p> + </note> + + <p>This callback is mandatory.</p> + </item> + </taglist> + </section> <funcs> <func> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr(const char *addr, int len, int type)</nametext></name> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyaddr_r(const char *addr, int length, int type, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyname(const char *name)</nametext></name> - <name><ret>struct hostent</ret><nametext>*ei_gethostbyname_r(const char *name, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> + <name since=""><ret>struct hostent *</ret><nametext>ei_gethostbyaddr(const char *addr, int len, int type)</nametext></name> + <name since=""><ret>struct hostent *</ret><nametext>ei_gethostbyaddr_r(const char *addr, int length, int type, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> + <name since=""><ret>struct hostent *</ret><nametext>ei_gethostbyname(const char *name)</nametext></name> + <name since=""><ret>struct hostent *</ret><nametext>ei_gethostbyname_r(const char *name, struct hostent *hostp, char *buffer, int buflen, int *h_errnop)</nametext></name> <fsummary>Name lookup functions.</fsummary> <desc> <p>Convenience functions for some common name lookup functions.</p> </desc> </func> + <func> - <name><ret>int</ret><nametext>ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_accept(ei_cnode *ec, int listensock, ErlConnect *conp)</nametext></name> <fsummary>Accept a connection from another node.</fsummary> <desc> <p>Used by a server process to accept a @@ -130,7 +401,7 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>ei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_accept_tmo(ei_cnode *ec, int listensock, ErlConnect *conp, unsigned timeout_ms)</nametext></name> <fsummary>Accept a connection from another node with optional time-out.</fsummary> <desc> @@ -141,8 +412,16 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>ei_connect(ei_cnode* ec, char *nodename)</nametext></name> - <name><ret>int</ret><nametext>ei_xconnect(ei_cnode* ec, Erl_IpAddr adr, char *alivename)</nametext></name> + <name since="OTP 21.3"><ret>int</ret><nametext>ei_close_connection(int fd)</nametext></name> + <fsummary>Close a connection.</fsummary> + <desc> + <p>Closes a previously opened connection or listen socket.</p> + </desc> + </func> + + <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> <fsummary>Establish a connection to an Erlang node.</fsummary> <desc> <p>Sets up a connection to an Erlang node.</p> @@ -192,8 +471,10 @@ fd = ei_xconnect(&ec, &addr, ALIVE); </func> <func> - <name><ret>int</ret><nametext>ei_connect_init(ei_cnode* ec, const char* this_node_name, const char *cookie, short creation)</nametext></name> - <name><ret>int</ret><nametext>ei_connect_xinit(ei_cnode* ec, const char *thishostname, const char *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr, const char *cookie, short creation)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_connect_init(ei_cnode* ec, const char* this_node_name, const char *cookie, short creation)</nametext></name> + <name since="OTP 21.3"><ret>int</ret><nametext>ei_connect_init_ussi(ei_cnode* ec, const char* this_node_name, const char *cookie, short creation, ei_socket_callbacks *cbs, int cbs_sz, void *setup_context)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_connect_xinit(ei_cnode* ec, const char *thishostname, const char *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr, const char *cookie, short creation)</nametext></name> + <name since="OTP 21.3"><ret>int</ret><nametext>ei_connect_xinit_ussi(ei_cnode* ec, const char *thishostname, const char *thisalivename, const char *thisnodename, Erl_IpAddr thisipaddr, const char *cookie, short creation, ei_socket_callbacks *cbs, int cbs_sz, void *setup_context)</nametext></name> <fsummary>Initialize for a connection.</fsummary> <desc> <p>Initializes the <c>ec</c> structure, to @@ -236,6 +517,21 @@ fd = ei_xconnect(&ec, &addr, ALIVE); <item> <p><c>thispaddr</c> if the IP address of the host.</p> </item> + <item> + <p><c>cbs</c> is a pointer to a + <seealso marker="#ei_socket_callbacks">callback structure</seealso> + implementing and alternative socket interface.</p> + </item> + <item> + <p><c>cbs_sz</c> is the size of the structure + pointed to by <c>cbs</c>.</p> + </item> + <item> + <p><c>setup_context</c> is a pointer to a structure that + will be passed as second argument to the <c>socket</c> callback + in the <c>cbs</c> structure.</p> + </item> + </list> <p>A C-node acting as a server is assigned a creation number when it calls <c>ei_publish()</c>.</p> @@ -273,8 +569,8 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { </func> <func> - <name><ret>int</ret><nametext>ei_connect_tmo(ei_cnode* ec, char *nodename, unsigned timeout_ms)</nametext></name> - <name><ret>int</ret><nametext>ei_xconnect_tmo(ei_cnode* ec, Erl_IpAddr adr, char *alivename, unsigned timeout_ms)</nametext></name> + <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> <fsummary>Establish a connection to an Erlang node with optional time-out.</fsummary> <desc> @@ -286,8 +582,8 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { </func> <func> - <name><ret>int</ret><nametext>ei_get_tracelevel(void)</nametext></name> - <name><ret>void</ret><nametext>ei_set_tracelevel(int level)</nametext></name> + <name since="OTP R13B04"><ret>int</ret><nametext>ei_get_tracelevel(void)</nametext></name> + <name since="OTP R13B04"><ret>void</ret><nametext>ei_set_tracelevel(int level)</nametext></name> <fsummary>Get and set functions for tracing.</fsummary> <desc> <p>Used to set tracing on the distribution. The levels are different @@ -299,7 +595,46 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { </func> <func> - <name><ret>int</ret><nametext>ei_publish(ei_cnode *ec, int port)</nametext></name> + <name since="OTP 21.3"><ret>int</ret><nametext>ei_listen(ei_cnode *ec, int *port, int backlog)</nametext></name> + <name since="OTP 21.3"><ret>int</ret><nametext>ei_xlisten(ei_cnode *ec, Erl_IpAddr adr, int *port, int backlog)</nametext></name> + <fsummary>Create a listen socket.</fsummary> + <desc> + <p>Used by a server process to setup a listen socket which + later can be used for accepting connections from client processes. + </p> + <list type="bulleted"> + <item> + <p><c>ec</c> is the C-node structure.</p> + </item> + <item> + <p><c>adr</c> is local interface to bind to.</p> + </item> + <item> + <p><c>port</c> is a pointer to an integer containing the + port number to bind to. If <c>*port</c> equals <c>0</c> + when calling <c>ei_listen()</c>, the socket will be bound to + an ephemeral port. On success, <c>ei_listen()</c> will update + the value of <c>*port</c> to the port actually bound to. + </p> + </item> + <item> + <p><c>backlog</c> is maximum backlog of pending connections.</p> + </item> + </list> + <p><c>ei_listen</c> will create a socket, bind to a port on the + local interface identified by <c>adr</c> (or all local interfaces if + <c>ei_listen()</c> is called), and mark the socket as a passive socket + (that is, a socket that will be used for accepting incoming connections). + </p> + <p> + On success, a file descriptor is returned which can be used in a call to + <c>ei_accept()</c>. 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>ei_publish(ei_cnode *ec, int port)</nametext></name> <fsummary>Publish a node name.</fsummary> <desc> <p>Used by a server process to register @@ -336,7 +671,7 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { </func> <func> - <name><ret>int</ret><nametext>ei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_publish_tmo(ei_cnode *ec, int port, unsigned timeout_ms)</nametext></name> <fsummary>Publish a node name with optional time-out.</fsummary> <desc> <p>Equivalent to @@ -346,7 +681,7 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { </func> <func> - <name><ret>int</ret><nametext>ei_receive(int fd, unsigned char* bufp, int bufsize)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_receive(int fd, unsigned char* bufp, int bufsize)</nametext></name> <fsummary>Receive a message.</fsummary> <desc> <p>Receives a message consisting of a sequence @@ -387,7 +722,7 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { </func> <func> - <name><ret>int</ret><nametext>ei_receive_encoded(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_receive_encoded(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen)</nametext></name> <fsummary>Obsolete function for receiving a message.</fsummary> <desc> <p>This function is retained for compatibility with code @@ -417,7 +752,7 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { </func> <func> - <name><ret>int</ret><nametext>ei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen, unsigned timeout_ms)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_receive_encoded_tmo(int fd, char **mbufp, int *bufsz, erlang_msg *msg, int *msglen, unsigned timeout_ms)</nametext></name> <fsummary>Obsolete function for receiving a message with time-out. </fsummary> <desc> @@ -428,8 +763,8 @@ if (ei_connect_init(&ec, "madonna", "cookie...", n++) < 0) { </func> <func> - <name><ret>int</ret><nametext>ei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name> - <name><ret>int</ret><nametext>ei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_receive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_xreceive_msg(int fd, erlang_msg* msg, ei_x_buff* x)</nametext></name> <fsummary>Receive a message.</fsummary> <desc> <p>Receives a message to the buffer in <c>x</c>. @@ -493,8 +828,8 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>ei_receive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned imeout_ms)</nametext></name> - <name><ret>int</ret><nametext>ei_xreceive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned timeout_ms)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_receive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned imeout_ms)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_xreceive_msg_tmo(int fd, erlang_msg* msg, ei_x_buff* x, unsigned timeout_ms)</nametext></name> <fsummary>Receive a message with optional time-out.</fsummary> <desc> <p>Equivalent to <c>ei_receive_msg</c> and <c>ei_xreceive_msg</c> @@ -504,7 +839,7 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>ei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_receive_tmo(int fd, unsigned char* bufp, int bufsize, unsigned timeout_ms)</nametext></name> <fsummary>Receive a message with optional time-out.</fsummary> <desc> <p>Equivalent to @@ -514,7 +849,7 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>ei_reg_send(ei_cnode* ec, int fd, char* server_name, char* buf, int len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_send(ei_cnode* ec, int fd, char* server_name, char* buf, int len)</nametext></name> <fsummary>Send a message to a registered name.</fsummary> <desc> <p>Sends an Erlang term to a registered process.</p> @@ -546,7 +881,7 @@ if (ei_reg_send(&ec, fd, x.buff, x.index) < 0) </func> <func> - <name><ret>int</ret><nametext>ei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf, int len, unsigned timeout_ms)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_send_tmo(ei_cnode* ec, int fd, char* server_name, char* buf, int len, unsigned timeout_ms)</nametext></name> <fsummary>Send a message to a registered name with optional time-out </fsummary> <desc> @@ -557,9 +892,9 @@ if (ei_reg_send(&ec, fd, x.buff, x.index) < 0) </func> <func> - <name><ret>int</ret><nametext>ei_rpc(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen, ei_x_buff *x)</nametext></name> - <name><ret>int</ret><nametext>ei_rpc_to(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen)</nametext></name> - <name><ret>int</ret><nametext>ei_rpc_from(ei_cnode *ec, int fd, int timeout, erlang_msg *msg, ei_x_buff *x)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_rpc(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen, ei_x_buff *x)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_rpc_to(ei_cnode *ec, int fd, char *mod, char *fun, const char *argbuf, int argbuflen)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_rpc_from(ei_cnode *ec, int fd, int timeout, erlang_msg *msg, ei_x_buff *x)</nametext></name> <fsummary>Remote Procedure Call from C to Erlang.</fsummary> <desc> <p>Supports calling Erlang functions on remote nodes. @@ -658,7 +993,7 @@ if (ei_decode_version(result.buff, &index) < 0 </func> <func> - <name><ret>erlang_pid *</ret><nametext>ei_self(ei_cnode *ec)</nametext></name> + <name since=""><ret>erlang_pid *</ret><nametext>ei_self(ei_cnode *ec)</nametext></name> <fsummary>Retrieve the pid of the C-node.</fsummary> <desc> <p>Retrieves the pid of the C-node. Every C-node @@ -671,7 +1006,7 @@ if (ei_decode_version(result.buff, &index) < 0 </func> <func> - <name><ret>int</ret><nametext>ei_send(int fd, erlang_pid* to, char* buf, int len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_send(int fd, erlang_pid* to, char* buf, int len)</nametext></name> <fsummary>Send a message.</fsummary> <desc> <p>Sends an Erlang term to a process.</p> @@ -692,7 +1027,7 @@ if (ei_decode_version(result.buff, &index) < 0 </func> <func> - <name><ret>int</ret><nametext>ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_send_encoded(int fd, erlang_pid* to, char* buf, int len)</nametext></name> <fsummary>Obsolete function to send a message.</fsummary> <desc> <p>Works exactly as <c>ei_send</c>, the alternative name is retained for @@ -702,7 +1037,7 @@ if (ei_decode_version(result.buff, &index) < 0 </func> <func> - <name><ret>int</ret><nametext>ei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_send_encoded_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> <fsummary>Obsolete function to send a message with optional time-out. </fsummary> <desc> @@ -713,7 +1048,7 @@ if (ei_decode_version(result.buff, &index) < 0 </func> <func> - <name><ret>int</ret><nametext>ei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_send_reg_encoded(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> <fsummary>Obsolete function to send a message to a registered name. </fsummary> <desc> @@ -741,7 +1076,7 @@ self->num = fd; </func> <func> - <name><ret>int</ret><nametext>ei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_send_reg_encoded_tmo(int fd, const erlang_pid *from, const char *to, const char *buf, int len)</nametext></name> <fsummary>Obsolete function to send a message to a registered name with time-out.</fsummary> <desc> @@ -752,7 +1087,7 @@ self->num = fd; </func> <func> - <name><ret>int</ret><nametext>ei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_send_tmo(int fd, erlang_pid* to, char* buf, int len, unsigned timeout_ms)</nametext></name> <fsummary>Send a message with optional time-out.</fsummary> <desc> <p>Equivalent to @@ -762,9 +1097,9 @@ self->num = fd; </func> <func> - <name><ret>const char *</ret><nametext>ei_thisnodename(ei_cnode *ec)</nametext></name> - <name><ret>const char *</ret><nametext>ei_thishostname(ei_cnode *ec)</nametext></name> - <name><ret>const char *</ret><nametext>ei_thisalivename(ei_cnode *ec)</nametext></name> + <name since=""><ret>const char *</ret><nametext>ei_thisnodename(ei_cnode *ec)</nametext></name> + <name since=""><ret>const char *</ret><nametext>ei_thishostname(ei_cnode *ec)</nametext></name> + <name since=""><ret>const char *</ret><nametext>ei_thisalivename(ei_cnode *ec)</nametext></name> <fsummary>Retrieve some values.</fsummary> <desc> <p>Can be used to retrieve information about @@ -779,7 +1114,7 @@ self->num = fd; </func> <func> - <name><ret>int</ret><nametext>ei_unpublish(ei_cnode *ec)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_unpublish(ei_cnode *ec)</nametext></name> <fsummary>Forcefully unpublish a node name.</fsummary> <desc> <p>Can be called by a process to unregister a @@ -802,7 +1137,7 @@ self->num = fd; </func> <func> - <name><ret>int</ret><nametext>ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_unpublish_tmo(ei_cnode *ec, unsigned timeout_ms)</nametext></name> <fsummary>Unpublish a node name with optional time-out.</fsummary> <desc> <p>Equivalent to diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml index 0eed50b50b..7ca10d1a99 100644 --- a/lib/erl_interface/doc/src/ei_users_guide.xml +++ b/lib/erl_interface/doc/src/ei_users_guide.xml @@ -34,6 +34,18 @@ </header> <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>Introduction</title> <p>The <c>Erl_Interface</c> library contains functions that help you integrate programs written in C and Erlang. The functions in @@ -162,12 +174,20 @@ $ ld -L/usr/local/otp/lib/erl_interface-3.2.3/ </section> <section> - <title>Initializing the Erl_Interface Library</title> - <p>Before calling any of the other <c>Erl_Interface</c> functions, call - <c>erl_init()</c> exactly once to initialize the library. + <title>Initializing the Libraries</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> + 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. + </p> </section> <section> diff --git a/lib/erl_interface/doc/src/erl_connect.xml b/lib/erl_interface/doc/src/erl_connect.xml index 76ef6588c2..9492a82864 100644 --- a/lib/erl_interface/doc/src/erl_connect.xml +++ b/lib/erl_interface/doc/src/erl_connect.xml @@ -35,6 +35,15 @@ <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> @@ -49,7 +58,7 @@ <funcs> <func> - <name><ret>int</ret><nametext>erl_accept(listensock, conp)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_accept(listensock, conp)</nametext></name> <fsummary>Accept a connection.</fsummary> <type> <v>int listensock;</v> @@ -78,7 +87,7 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>erl_close_connection(fd)</nametext></name> + <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> @@ -95,8 +104,8 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>erl_connect(node)</nametext></name> - <name><ret>int</ret><nametext>erl_xconnect(addr, alive)</nametext></name> + <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> @@ -149,8 +158,8 @@ erl_xconnect( &addr , ALIVE ); </func> <func> - <name><ret>int</ret><nametext>erl_connect_init(number, cookie, creation)</nametext></name> - <name><ret>int</ret><nametext>erl_connect_xinit(host, alive, node, addr, cookie, creation)</nametext></name> + <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> @@ -246,7 +255,7 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) </func> <func> - <name><ret>int</ret><nametext>erl_publish(port)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_publish(port)</nametext></name> <fsummary>Publish a node name.</fsummary> <type> <v>int port;</v> @@ -277,7 +286,7 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) </func> <func> - <name><ret>int</ret><nametext>erl_receive(fd, bufp, bufsize)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_receive(fd, bufp, bufsize)</nametext></name> <fsummary>Receive a message.</fsummary> <type> <v>int fd;</v> @@ -316,7 +325,7 @@ if (!erl_connect_init(17, "samplecookiestring...", 0)) </func> <func> - <name><ret>int</ret><nametext>erl_receive_msg(fd, bufp, bufsize, emsg)</nametext></name> + <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> @@ -411,7 +420,7 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>erl_reg_send(fd, to, msg)</nametext></name> + <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> @@ -439,9 +448,9 @@ typedef struct { </func> <func> - <name><ret>ETERM *</ret><nametext>erl_rpc(fd, mod, fun, args)</nametext></name> - <name><ret>int</ret><nametext>erl_rpc_from(fd, timeout, emsg)</nametext></name> - <name><ret>int</ret><nametext>erl_rpc_to(fd, mod, fun, args)</nametext></name> + <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> @@ -511,7 +520,7 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>erl_send(fd, to, msg)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_send(fd, to, msg)</nametext></name> <fsummary>Send a message.</fsummary> <type> <v>int fd;</v> @@ -541,11 +550,11 @@ typedef struct { </func> <func> - <name><ret>const char *</ret><nametext>erl_thisalivename()</nametext></name> - <name><ret>const char *</ret><nametext>erl_thiscookie()</nametext></name> - <name><ret>short</ret><nametext>erl_thiscreation()</nametext></name> - <name><ret>const char *</ret><nametext>erl_thishostname()</nametext></name> - <name><ret>const char *</ret><nametext>erl_thisnodename()</nametext></name> + <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 @@ -556,7 +565,7 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>erl_unpublish(alive)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_unpublish(alive)</nametext></name> <fsummary>Forcefully unpublish a node name.</fsummary> <type> <v>char *alive;</v> @@ -583,7 +592,7 @@ typedef struct { </func> <func> - <name><ret>int</ret><nametext>erl_xreceive_msg(fd, bufpp, bufsizep, emsg)</nametext></name> + <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> @@ -616,10 +625,10 @@ typedef struct { </func> <func> - <name><ret>struct hostent</ret><nametext>*erl_gethostbyaddr(addr, length, type)</nametext></name> - <name><ret>struct hostent</ret><nametext>*erl_gethostbyaddr_r(addr, length, type, hostp, buffer, buflen, h_errnop)</nametext></name> - <name><ret>struct hostent</ret><nametext>*erl_gethostbyname(name)</nametext></name> - <name><ret>struct hostent</ret><nametext>*erl_gethostbyname_r(name, hostp, buffer, buflen, h_errnop)</nametext></name> + <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> diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml index 8139c9b343..6fac94e442 100644 --- a/lib/erl_interface/doc/src/erl_error.xml +++ b/lib/erl_interface/doc/src/erl_error.xml @@ -47,7 +47,7 @@ <funcs> <func> - <name><ret>void</ret><nametext>erl_err_msg(FormatStr, ... )</nametext></name> + <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> @@ -59,7 +59,7 @@ </func> <func> - <name><ret>void</ret><nametext>erl_err_quit(FormatStr, ... )</nametext></name> + <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> @@ -73,7 +73,7 @@ </func> <func> - <name><ret>void</ret><nametext>erl_err_ret(FormatStr, ... )</nametext></name> + <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> @@ -86,7 +86,7 @@ </func> <func> - <name><ret>void</ret><nametext>erl_err_sys(FormatStr, ... )</nametext></name> + <name since=""><ret>void</ret><nametext>erl_err_sys(FormatStr, ... )</nametext></name> <fsummary>Fatal system call error.</fsummary> <type> <v>const char *FormatStr;</v> @@ -113,7 +113,7 @@ <funcs> <func> - <name><ret>volatile int</ret><nametext>erl_errno</nametext></name> + <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> diff --git a/lib/erl_interface/doc/src/erl_eterm.xml b/lib/erl_interface/doc/src/erl_eterm.xml index 9a05196a70..295760b4e6 100644 --- a/lib/erl_interface/doc/src/erl_eterm.xml +++ b/lib/erl_interface/doc/src/erl_eterm.xml @@ -35,6 +35,15 @@ <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> @@ -142,7 +151,7 @@ <funcs> <func> - <name><ret>ETERM *</ret><nametext>erl_cons(head, tail)</nametext></name> + <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> @@ -181,7 +190,7 @@ erl_free_compound(list); </func> <func> - <name><ret>ETERM *</ret><nametext>erl_copy_term(term)</nametext></name> + <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> @@ -193,7 +202,7 @@ erl_free_compound(list); </func> <func> - <name><ret>ETERM *</ret><nametext>erl_element(position, tuple)</nametext></name> + <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> @@ -215,7 +224,7 @@ erl_free_compound(list); </func> <func> - <name><ret>ETERM *</ret><nametext>erl_hd(list)</nametext></name> + <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> @@ -230,7 +239,7 @@ erl_free_compound(list); </func> <func> - <name><ret>void</ret><nametext>erl_init(NULL, 0)</nametext></name> + <name since=""><ret>void</ret><nametext>erl_init(NULL, 0)</nametext></name> <fsummary>Initialization routine.</fsummary> <type> <v>void *NULL;</v> @@ -245,7 +254,7 @@ erl_free_compound(list); </func> <func> - <name><ret>int</ret><nametext>erl_iolist_length(list)</nametext></name> + <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> @@ -262,7 +271,7 @@ erl_free_compound(list); </func> <func> - <name><ret>ETERM *</ret><nametext>erl_iolist_to_binary(term)</nametext></name> + <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> @@ -289,7 +298,7 @@ iohead ::= Binary </func> <func> - <name><ret>char *</ret><nametext>erl_iolist_to_string(list)</nametext></name> + <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> @@ -312,7 +321,7 @@ iohead ::= Binary </func> <func> - <name><ret>int</ret><nametext>erl_length(list)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_length(list)</nametext></name> <fsummary>Determine the length of a list.</fsummary> <type> <v>ETERM *list;</v> @@ -328,7 +337,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_atom(string)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_mk_atom(string)</nametext></name> <fsummary>Create an atom.</fsummary> <type> <v>const char *string;</v> @@ -355,7 +364,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_binary(bptr, size)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_mk_binary(bptr, size)</nametext></name> <fsummary>Create a binary object.</fsummary> <type> <v>char *bptr;</v> @@ -378,7 +387,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_empty_list()</nametext></name> + <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. @@ -388,7 +397,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_estring(string, len)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_mk_estring(string, len)</nametext></name> <fsummary>Create an Erlang string.</fsummary> <type> <v>char *string;</v> @@ -408,7 +417,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_float(f)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_mk_float(f)</nametext></name> <fsummary>Create an Erlang float.</fsummary> <type> <v>double f;</v> @@ -426,7 +435,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_int(n)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_mk_int(n)</nametext></name> <fsummary>Create an Erlang integer.</fsummary> <type> <v>int n;</v> @@ -443,7 +452,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_list(array, arrsize)</nametext></name> + <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> @@ -465,7 +474,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_long_ref(node, n1, n2, n3, creation)</nametext></name> + <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> @@ -495,7 +504,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_pid(node, number, serial, creation)</nametext></name> + <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> @@ -525,7 +534,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_port(node, number, creation)</nametext></name> + <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> @@ -550,7 +559,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_ref(node, number, creation)</nametext></name> + <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> @@ -578,7 +587,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_string(string)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_mk_string(string)</nametext></name> <fsummary>Create a string.</fsummary> <type> <v>char *string;</v> @@ -593,7 +602,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_tuple(array, arrsize)</nametext></name> + <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> @@ -621,7 +630,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_uint(n)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_mk_uint(n)</nametext></name> <fsummary>Create an unsigned integer.</fsummary> <type> <v>unsigned int n;</v> @@ -638,7 +647,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_mk_var(name)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_mk_var(name)</nametext></name> <fsummary>Create an Erlang variable.</fsummary> <type> <v>char *name;</v> @@ -653,7 +662,7 @@ iohead ::= Binary </func> <func> - <name><ret>int</ret><nametext>erl_print_term(stream, term)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_print_term(stream, term)</nametext></name> <fsummary>Print an Erlang term.</fsummary> <type> <v>FILE *stream;</v> @@ -672,7 +681,7 @@ iohead ::= Binary </func> <func> - <name><ret>void</ret><nametext>erl_set_compat_rel(release_number)</nametext></name> + <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> @@ -706,7 +715,7 @@ iohead ::= Binary </func> <func> - <name><ret>int</ret><nametext>erl_size(term)</nametext></name> + <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> @@ -723,7 +732,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_tl(list)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_tl(list)</nametext></name> <fsummary>Extract the tail from a list.</fsummary> <type> <v>ETERM *list;</v> @@ -738,7 +747,7 @@ iohead ::= Binary </func> <func> - <name><ret>ETERM *</ret><nametext>erl_var_content(term, name)</nametext></name> + <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> diff --git a/lib/erl_interface/doc/src/erl_format.xml b/lib/erl_interface/doc/src/erl_format.xml index 5b8b7b5e78..b5e895c720 100644 --- a/lib/erl_interface/doc/src/erl_format.xml +++ b/lib/erl_interface/doc/src/erl_format.xml @@ -41,7 +41,7 @@ <funcs> <func> - <name><ret>ETERM *</ret><nametext>erl_format(FormatStr, ...)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_format(FormatStr, ...)</nametext></name> <fsummary>Create an Erlang term.</fsummary> <type> <v>char *FormatStr;</v> @@ -81,7 +81,7 @@ erl_format("[{name,~a},{age,~i},{data,~w}]", </func> <func> - <name><ret>int</ret><nametext>erl_match(Pattern, Term)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_match(Pattern, Term)</nametext></name> <fsummary>Perform pattern matching.</fsummary> <type> <v>ETERM *Pattern,*Term;</v> diff --git a/lib/erl_interface/doc/src/erl_global.xml b/lib/erl_interface/doc/src/erl_global.xml index 2fa0045adf..39085b46f0 100644 --- a/lib/erl_interface/doc/src/erl_global.xml +++ b/lib/erl_interface/doc/src/erl_global.xml @@ -35,6 +35,15 @@ <lib>erl_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 @@ -48,7 +57,7 @@ <funcs> <func> - <name><ret>char **</ret><nametext>erl_global_names(fd,count)</nametext></name> + <name since=""><ret>char **</ret><nametext>erl_global_names(fd,count)</nametext></name> <fsummary>Obtain list of global names.</fsummary> <type> <v>int fd;</v> @@ -79,7 +88,7 @@ </func> <func> - <name><ret>int</ret><nametext>erl_global_register(fd,name,pid)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_global_register(fd,name,pid)</nametext></name> <fsummary>Register a name in global.</fsummary> <type> <v>int fd;</v> @@ -103,7 +112,7 @@ </func> <func> - <name><ret>int</ret><nametext>erl_global_unregister(fd,name)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_global_unregister(fd,name)</nametext></name> <fsummary>Unregister a name from global.</fsummary> <type> <v>int fd;</v> @@ -122,7 +131,7 @@ </func> <func> - <name><ret>ETERM *</ret><nametext>erl_global_whereis(fd,name,node)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_global_whereis(fd,name,node)</nametext></name> <fsummary>Look up a name in global.</fsummary> <type> <v>int fd;</v> diff --git a/lib/erl_interface/doc/src/erl_interface.xml b/lib/erl_interface/doc/src/erl_interface.xml index 4e66655b39..decd66046a 100644 --- a/lib/erl_interface/doc/src/erl_interface.xml +++ b/lib/erl_interface/doc/src/erl_interface.xml @@ -58,6 +58,18 @@ </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> diff --git a/lib/erl_interface/doc/src/erl_malloc.xml b/lib/erl_interface/doc/src/erl_malloc.xml index c0eebc29e9..6650620064 100644 --- a/lib/erl_interface/doc/src/erl_malloc.xml +++ b/lib/erl_interface/doc/src/erl_malloc.xml @@ -35,13 +35,21 @@ <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><ret>ETERM *</ret><nametext>erl_alloc_eterm(etype)</nametext></name> + <name since=""><ret>ETERM *</ret><nametext>erl_alloc_eterm(etype)</nametext></name> <fsummary>Allocate an ETERM structure.</fsummary> <type> <v>unsigned char etype;</v> @@ -89,7 +97,7 @@ </func> <func> - <name><ret>void</ret><nametext>erl_eterm_release(void)</nametext></name> + <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 @@ -99,7 +107,7 @@ </func> <func> - <name><ret>void</ret><nametext>erl_eterm_statistics(allocated, freed)</nametext></name> + <name since=""><ret>void</ret><nametext>erl_eterm_statistics(allocated, freed)</nametext></name> <fsummary>Report term allocation statistics.</fsummary> <type> <v>long *allocated;</v> @@ -127,7 +135,7 @@ </func> <func> - <name><ret>void</ret><nametext>erl_free(ptr)</nametext></name> + <name since=""><ret>void</ret><nametext>erl_free(ptr)</nametext></name> <fsummary>Free some memory.</fsummary> <type> <v>void *ptr;</v> @@ -139,7 +147,7 @@ </func> <func> - <name><ret>void</ret><nametext>erl_free_array(array, size)</nametext></name> + <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> @@ -156,7 +164,7 @@ </func> <func> - <name><ret>void</ret><nametext>erl_free_compound(t)</nametext></name> + <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> @@ -179,7 +187,7 @@ </func> <func> - <name><ret>void</ret><nametext>erl_free_term(t)</nametext></name> + <name since=""><ret>void</ret><nametext>erl_free_term(t)</nametext></name> <fsummary>Free an ETERM structure.</fsummary> <type> <v>ETERM *t;</v> @@ -190,7 +198,7 @@ </func> <func> - <name><ret>void</ret><nametext>erl_malloc(size)</nametext></name> + <name since=""><ret>void</ret><nametext>erl_malloc(size)</nametext></name> <fsummary>Allocate some memory.</fsummary> <type> <v>long size;</v> diff --git a/lib/erl_interface/doc/src/erl_marshal.xml b/lib/erl_interface/doc/src/erl_marshal.xml index 2ad658f78b..33d359d871 100644 --- a/lib/erl_interface/doc/src/erl_marshal.xml +++ b/lib/erl_interface/doc/src/erl_marshal.xml @@ -35,6 +35,14 @@ <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> @@ -42,7 +50,7 @@ <funcs> <func> - <name><ret>int</ret><nametext>erl_compare_ext(bufp1, bufp2)</nametext></name> + <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> @@ -62,8 +70,8 @@ </func> <func> - <name><ret>ETERM *</ret><nametext>erl_decode(bufp)</nametext></name> - <name><ret>ETERM *</ret><nametext>erl_decode_buf(bufpp)</nametext></name> + <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> @@ -102,8 +110,8 @@ </func> <func> - <name><ret>int</ret><nametext>erl_encode(term, bufp)</nametext></name> - <name><ret>int</ret><nametext>erl_encode_buf(term, bufpp)</nametext></name> + <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> @@ -179,7 +187,7 @@ </func> <func> - <name><ret>int</ret><nametext>erl_ext_size(bufp)</nametext></name> + <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> @@ -190,7 +198,7 @@ </func> <func> - <name><ret>unsigned char</ret><nametext>erl_ext_type(bufp)</nametext></name> + <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> @@ -228,7 +236,7 @@ </func> <func> - <name><ret>unsigned char *</ret><nametext>erl_peek_ext(bufp, pos)</nametext></name> + <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> @@ -252,7 +260,7 @@ </func> <func> - <name><ret>int</ret><nametext>erl_term_len(t)</nametext></name> + <name since=""><ret>int</ret><nametext>erl_term_len(t)</nametext></name> <fsummary>Determine encoded size of term.</fsummary> <type> <v>ETERM *t;</v> diff --git a/lib/erl_interface/doc/src/note.gif b/lib/erl_interface/doc/src/note.gif Binary files differdeleted file mode 100644 index 6fffe30419..0000000000 --- a/lib/erl_interface/doc/src/note.gif +++ /dev/null diff --git a/lib/erl_interface/doc/src/notes.xml b/lib/erl_interface/doc/src/notes.xml index b5d8def655..c47f0d2bd1 100644 --- a/lib/erl_interface/doc/src/notes.xml +++ b/lib/erl_interface/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2016</year> + <year>2004</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,397 @@ </header> <p>This document describes the changes made to the Erl_interface application.</p> +<section><title>Erl_Interface 3.12</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The vxworks configure has been updated to respect the + environment CFLAGS.</p> + <p> + Own Id: OTP-15773</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Minor adjustments made to build system for parallel + configure.</p> + <p> + Own Id: OTP-15340 Aux Id: OTP-14625 </p> + </item> + <item> + <p> + The limited support for VxWorks is deprecated as of OTP + 22, and will be removed in OTP 23.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15621</p> + </item> + <item> + <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> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15622</p> + </item> + <item> + <p>Added support to receive, decode, encode and send both + bit strings and export funs (<c>fun M:F/A</c>).</p> + <p>New functions <c>ei_decode_bitstring</c> and + <c>ei_encode_bitstring</c> have been added in order to + decode and encode bit strings where the number of bits is + not necessary divisible by 8 (a whole number of bytes). + The existing functions <c>ei_decode_fun</c> and + <c>ei_encode_fun</c> can now also handle export funs.</p> + <p>Before this change, bit strings and export funs sent + to an erl_interface c-node were encoded using an + undocumented fallback tuple format. For bit strings + <c>{Binary,BitsInLastByte}</c> and for export funs + <c>{M,F}</c>. Existing c-node implementations expecting + these tuples must be changed to instead use + <c>ei_decode_bitstring</c> and <c>ei_decode_fun</c>. As a + temporary solution you can also build erl_interface with + macro <c>EI_COMPAT=21</c> or call + <c>ei_set_compat_rel(21)</c> to receive the old fallback + tuples.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-15712 Aux Id: OTP-15774 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.11.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + <c>erl_interface</c>/<c>ei</c> refused to use node names + with an alive name (the part of the node name preceding + the @ sign) longer than 63 characters and a host name + longer than 64 characters. The total amount of characters + allowed in a node name (alivename@hostname) was thus + limited to 128 characters. These limits applied both to + the own node name as well as node names of other nodes. + Ordinary Erlang nodes limit the node name length to 256 + characters, which meant that you could not communicate + with certain Erlang nodes due to their node name used.</p> + <p> + <c>erl_interface</c>/<c>ei</c> now allow the total amount + of characters in a node name to be up to 256 characters. + These characters may be distributed between alive name + and host name in whatever way needed. That is, the + maximum amount of characters in the alive name may be 254 + and the maximum amount of characters in the host name may + be 254, but in total the node name must not exceed 256 + characters.</p> + <p> + Own Id: OTP-15781 Aux Id: ERIERL-356 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.11.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + <c>erl_interface</c>/<c>ei</c> refused to use node names + with an alive name (the part of the node name preceding + the @ sign) longer than 63 characters and a host name + longer than 64 characters. The total amount of characters + allowed in a node name (alivename@hostname) was thus + limited to 128 characters. These limits applied both to + the own node name as well as node names of other nodes. + Ordinary Erlang nodes limit the node name length to 256 + characters, which meant that you could not communicate + with certain Erlang nodes due to their node name used.</p> + <p> + <c>erl_interface</c>/<c>ei</c> now allow the total amount + of characters in a node name to be up to 256 characters. + These characters may be distributed between alive name + and host name in whatever way needed. That is, the + maximum amount of characters in the alive name may be 254 + and the maximum amount of characters in the host name may + be 254, but in total the node name must not exceed 256 + characters.</p> + <p> + Own Id: OTP-15781 Aux Id: ERIERL-356 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.11.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix handling of Makefile dependencies so that parallel + make works properly.</p> + <p> + Own Id: OTP-15757</p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.11.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed two bugs in the <c>erl_call</c> program. A missing + initialization (introduced in <c>erl_interface-3.11</c>) + which either caused a crash or failure to connect to or + start a node, and an incorrectly calculated timeout which + could cause failure to start an erlang node. These bugs + only caused failures on some platforms.</p> + <p> + Own Id: OTP-15676 Aux Id: OTP-15442, ERL-881 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.11</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Support for plugin of a <seealso + marker="ei_connect#ussi">user supplied socket + implementation</seealso> has been added.</p> + <p> + Own Id: OTP-15442 Aux Id: ERIERL-258 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.10.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Make <c>ei_connect</c> and friends also accept state + <c>ok_simultaneous</c> during handshake, which means the + other node has initiated a connection setup that will be + cancelled in favor of this connection.</p> + <p> + Own Id: OTP-15161 Aux Id: ERIERL-191 </p> + </item> + <item> + <p> + Fixed bug in <c>ei_receive_msg</c>, + <c>ei_xreceive_msg</c>, <c>ei_receive_msg_tmo</c> and + <c>ei_xreceive_msg_tmo</c>. The <c>x->index</c> was + set to entire buffer size instead of the number of bytes + actually received.</p> + <p> + Own Id: OTP-15171</p> + </item> + <item> + <p> + Fixed bug in <c>ei_connect_init</c> which could be + provoked if called by concurrent threads. + <c>ei_connect_init</c> called posix interface + <c>gethostbyname</c> which is documented as not thread + safe.</p> + <p> + Own Id: OTP-15191</p> + </item> + <item> + <p> + Fixed bug in erl_compare_ext() ignoring the tail of lists + of otherwise equal content. Example: <c>[a | b]</c> and + <c>[a | c]</c> compared equal and <c>{[a], b}</c> and + <c>{[a], c}</c> compared equal.</p> + <p> + Own Id: OTP-15277 Aux Id: PR-1929 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.10.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix bug where calling erl_init on certain platforms could + result in a buffer overflow bug.</p> + <p> + Own Id: OTP-15033</p> + </item> + <item> + <p> + Fixed <c>erl_call -m</c> to not deallocate module source + binary before it has been read.</p> + <p> + Own Id: OTP-15105 Aux Id: ERL-629 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> The program <c>erl_call</c> calls + <c>erl_eval:eval_str/1</c> when it used to call + <c>lib:eval_str/1</c>. This means that <c>erl_call</c> + will fail when trying interact with an Erlang node + running Erlang/OTP 20 or earlier. </p> + <p> + Own Id: OTP-15114 Aux Id: OTP-15072, ERL-634 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.10.2.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix handling of Makefile dependencies so that parallel + make works properly.</p> + <p> + Own Id: OTP-15757</p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.10.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Make <c>ei_connect</c> and friends also accept state + <c>ok_simultaneous</c> during handshake, which means the + other node has initiated a connection setup that will be + cancelled in favor of this connection.</p> + <p> + Own Id: OTP-15161 Aux Id: ERIERL-191 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.10.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix bug in <c>ei_connect</c> functions that may cause + failure due to insufficient buffer space for + gethostbyname_r.</p> + <p> + Own Id: OTP-15022 Aux Id: ERIERL-163 </p> + </item> + <item> + <p> + Optimize encoding/decoding for pure 7-bit ascii atoms.</p> + <p> + Own Id: OTP-15023 Aux Id: ERIERL-150 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.10.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Removed all old unused files in the documentation. + </p> + <p> + Own Id: OTP-14475 Aux Id: ERL-409, PR-1493 </p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Interface 3.10</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fix bug where gethostname would incorrectly fail with + enametoolong on Linux.</p> + <p> + Own Id: OTP-14310</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Remove generation of atoms in old latin1 external format + in the distribution between erlang nodes, + <c>erl_interface</c>, and <c>jinterface</c>. The new utf8 + format for atoms was introduced in OTP R16. An OTP 20 + node can therefore not connect to nodes older than R16.</p> + <p> + Atoms that can be encoded using latin1 are still encoded + by <c>term_to_binary()</c> using latin1 encoding. Note + that all atoms will by default be encoded using utf8 in a + future Erlang/OTP release. For more information see the + documentation of <seealso + marker="erts:erlang#term_to_binary/2"><c>erlang:term_to_binary/2</c></seealso>.</p> + <p> + Own Id: OTP-14337</p> + </item> + </list> + </section> + +</section> + <section><title>Erl_Interface 3.9.3</title> <section><title>Improvements and New Features</title> @@ -1386,4 +1777,3 @@ </section> </section> </chapter> - diff --git a/lib/erl_interface/doc/src/part_notes.xml b/lib/erl_interface/doc/src/part_notes.xml deleted file mode 100644 index facdf821ee..0000000000 --- a/lib/erl_interface/doc/src/part_notes.xml +++ /dev/null @@ -1,39 +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>2004</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 Release Notes</title> - <prepared></prepared> - <docno></docno> - <date></date> - <rev></rev> - </header> - <description> - <p><em>Erl_Interface</em> is a C interface library for communication - with Erlang.</p> - <p>For information about older versions, see - <url href="part_notes_history_frame.html">Release Notes History</url>.</p> - </description> - <xi:include href="notes.xml"/> -</part> - diff --git a/lib/erl_interface/doc/src/part_notes_history.xml b/lib/erl_interface/doc/src/part_notes_history.xml deleted file mode 100644 index 401fea4dd4..0000000000 --- a/lib/erl_interface/doc/src/part_notes_history.xml +++ /dev/null @@ -1,37 +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>2006</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 Release Notes History</title> - <prepared></prepared> - <docno></docno> - <date></date> - <rev></rev> - </header> - <description> - <p><em>Erl_Interface</em> is a C interface library for communication - with Erlang.</p> - </description> - <xi:include href="notes_history.xml"/> -</part> - diff --git a/lib/erl_interface/doc/src/ref_man.xml b/lib/erl_interface/doc/src/ref_man.xml index 1e20637cb7..a4f947c79f 100644 --- a/lib/erl_interface/doc/src/ref_man.xml +++ b/lib/erl_interface/doc/src/ref_man.xml @@ -29,6 +29,14 @@ <file>ref_man.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> </description> <xi:include href="ei.xml"/> <xi:include href="ei_connect.xml"/> diff --git a/lib/erl_interface/doc/src/ref_man_ei.xml b/lib/erl_interface/doc/src/ref_man_ei.xml index 92ff9ed328..d8d1deaea1 100644 --- a/lib/erl_interface/doc/src/ref_man_ei.xml +++ b/lib/erl_interface/doc/src/ref_man_ei.xml @@ -30,8 +30,14 @@ <file>ref_man_ei.xml</file> </header> <description> - <p>The <c>ei</c> library is a <c>C</c> interface library for - communication with <c>Erlang</c>.</p> + <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 diff --git a/lib/erl_interface/doc/src/ref_man_erl_interface.xml b/lib/erl_interface/doc/src/ref_man_erl_interface.xml index 4b1d0e9981..2b69d0fa74 100644 --- a/lib/erl_interface/doc/src/ref_man_erl_interface.xml +++ b/lib/erl_interface/doc/src/ref_man_erl_interface.xml @@ -30,6 +30,14 @@ <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> diff --git a/lib/erl_interface/doc/src/registry.xml b/lib/erl_interface/doc/src/registry.xml index 6d70fb3475..1c90c5c9dd 100644 --- a/lib/erl_interface/doc/src/registry.xml +++ b/lib/erl_interface/doc/src/registry.xml @@ -44,7 +44,7 @@ <funcs> <func> - <name><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_close(reg)</nametext></name> <fsummary>Close a registry.</fsummary> <type> <v>ei_reg *reg;</v> @@ -59,7 +59,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_delete(reg,key)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_delete(reg,key)</nametext></name> <fsummary>Delete an object from the registry.</fsummary> <type> <v>ei_reg *reg;</v> @@ -85,7 +85,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_dump(fd,reg,mntab,flags)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_dump(fd,reg,mntab,flags)</nametext></name> <fsummary>Back up a registry to Mnesia.</fsummary> <type> <v>int fd;</v> @@ -125,7 +125,7 @@ </func> <func> - <name><ret>double</ret><nametext>ei_reg_getfval(reg,key)</nametext></name> + <name since=""><ret>double</ret><nametext>ei_reg_getfval(reg,key)</nametext></name> <fsummary>Get a floating point object.</fsummary> <type> <v>ei_reg *reg;</v> @@ -151,7 +151,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_getival(reg,key)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_getival(reg,key)</nametext></name> <fsummary>Get an integer object.</fsummary> <type> <v>ei_reg *reg;</v> @@ -177,7 +177,7 @@ </func> <func> - <name><ret>const void *</ret><nametext>ei_reg_getpval(reg,key,size)</nametext></name> + <name since=""><ret>const void *</ret><nametext>ei_reg_getpval(reg,key,size)</nametext></name> <fsummary>Get a binary object.</fsummary> <type> <v>ei_reg *reg;</v> @@ -207,7 +207,7 @@ </func> <func> - <name><ret>const char *</ret><nametext>ei_reg_getsval(reg,key)</nametext></name> + <name since=""><ret>const char *</ret><nametext>ei_reg_getsval(reg,key)</nametext></name> <fsummary>Get a string object.</fsummary> <type> <v>ei_reg *reg;</v> @@ -232,7 +232,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_getval(reg,key,flags,v,...)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_getval(reg,key,flags,v,...)</nametext></name> <fsummary>Get any object.</fsummary> <type> <v>ei_reg *reg;</v> @@ -278,7 +278,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_markdirty(reg,key)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_markdirty(reg,key)</nametext></name> <fsummary>Mark an object as dirty.</fsummary> <type> <v>ei_reg *reg;</v> @@ -305,7 +305,7 @@ </func> <func> - <name><ret>ei_reg *</ret><nametext>ei_reg_open(size)</nametext></name> + <name since=""><ret>ei_reg *</ret><nametext>ei_reg_open(size)</nametext></name> <fsummary>Create and open a registry.</fsummary> <type> <v>int size;</v> @@ -326,7 +326,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_purge(reg)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_purge(reg)</nametext></name> <fsummary>Remove deleted objects.</fsummary> <type> <v>ei_reg *reg;</v> @@ -346,7 +346,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_resize(reg,newsize)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_resize(reg,newsize)</nametext></name> <fsummary>Resize a registry.</fsummary> <type> <v>ei_reg *reg;</v> @@ -363,7 +363,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_restore(fd,reg,mntab)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_restore(fd,reg,mntab)</nametext></name> <fsummary>Restore a registry from Mnesia.</fsummary> <type> <v>int fd;</v> @@ -399,7 +399,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_setfval(reg,key,f)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_setfval(reg,key,f)</nametext></name> <fsummary>Assign a floating point object.</fsummary> <type> <v>ei_reg *reg;</v> @@ -424,7 +424,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_setival(reg,key,i)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_setival(reg,key,i)</nametext></name> <fsummary>Assign an integer object.</fsummary> <type> <v>ei_reg *reg;</v> @@ -448,7 +448,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_setpval(reg,key,p,size)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_setpval(reg,key,p,size)</nametext></name> <fsummary>Assign a binary object.</fsummary> <type> <v>ei_reg *reg;</v> @@ -479,7 +479,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_setsval(reg,key,s)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_setsval(reg,key,s)</nametext></name> <fsummary>Assign a string object.</fsummary> <type> <v>ei_reg *reg;</v> @@ -507,7 +507,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_setval(reg,key,flags,v,...)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_setval(reg,key,flags,v,...)</nametext></name> <fsummary>Assign a value to any object type.</fsummary> <type> <v>ei_reg *reg;</v> @@ -552,7 +552,7 @@ </func> <func> - <name><ret>int</ret><nametext>ei_reg_stat(reg,key,obuf)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_stat(reg,key,obuf)</nametext></name> <fsummary>Get object information.</fsummary> <type> <v>ei_reg *reg;</v> @@ -590,7 +590,7 @@ struct ei_reg_stat { </func> <func> - <name><ret>int</ret><nametext>ei_reg_tabstat(reg,obuf)</nametext></name> + <name since=""><ret>int</ret><nametext>ei_reg_tabstat(reg,obuf)</nametext></name> <fsummary>Get registry information.</fsummary> <type> <v>ei_reg *reg;</v> diff --git a/lib/erl_interface/doc/src/warning.gif b/lib/erl_interface/doc/src/warning.gif Binary files differdeleted file mode 100644 index 96af52360e..0000000000 --- a/lib/erl_interface/doc/src/warning.gif +++ /dev/null |
