From dbeaca78bc6c0d4719a522e447fa59d7a1006ae0 Mon Sep 17 00:00:00 2001
From: Rickard Green <rickard@erlang.org>
Date: Tue, 5 Feb 2019 15:55:23 +0100
Subject: Introduce ei_init()

You previously had to initialize ei via erl_init() which
implied that you were forced to link against the erl_interface
even when not using it (besides initializing ei).
---
 lib/erl_interface/doc/src/ei.xml             | 15 +++++++++++++++
 lib/erl_interface/doc/src/ei_users_guide.xml | 18 +++++++++++++-----
 2 files changed, 28 insertions(+), 5 deletions(-)

(limited to 'lib/erl_interface/doc')

diff --git a/lib/erl_interface/doc/src/ei.xml b/lib/erl_interface/doc/src/ei.xml
index 9502fb1ee7..a7cbf06085 100644
--- a/lib/erl_interface/doc/src/ei.xml
+++ b/lib/erl_interface/doc/src/ei.xml
@@ -732,6 +732,21 @@ ei_encode_tuple_header(buf, &amp;i, 0);</pre>
       </desc>
     </func>
 
+    <func>
+      <name><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><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>
diff --git a/lib/erl_interface/doc/src/ei_users_guide.xml b/lib/erl_interface/doc/src/ei_users_guide.xml
index 0eed50b50b..2dfd99e35a 100644
--- a/lib/erl_interface/doc/src/ei_users_guide.xml
+++ b/lib/erl_interface/doc/src/ei_users_guide.xml
@@ -162,12 +162,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>
-- 
cgit v1.2.3